[[!template  id=gitbranch branch=anarcat/backwards_links author="[[anarcat]]"]]

I understand this may be a bit provocative, but I strongly feel that ikiwiki linking rules are backwards. I come from the world of wikis like MoinMoin and [[plugins/contrib/mediawiki]], where you use `\[[link|description]]`. The defacto wiki markup "[[plugins/creole]]" also uses that convention, as does raw HTML (href comes first!). Ikiwiki doesn't: here we need to use `\[[description|link]]`.

Everytime i come back to ikiwiki, i need to bend my mind backwards to create *proper* links. I understand that `\[[description|link]]` is more inline with Markdown's `[description](link)` approach, but in my mind it is too much of a problem for third part plugins to be a proper justification. For example, the [[plugins/creole]] plugin works pretty much as expected *expect* for links, because it can't override ikiwiki's internal link parser. For me that's a huge inconsistency that should be fixed.

If there is an agreement within the community that we can change that, I am ready to work on a migration script or even a configuration variable... -- [[anarcat]]

Dev notes
---------

I started looking into this, after encouraging words from Joey ("very long term roadmap", AKA "if someone does it"). It turns out it is less deeply rooted than i thought in the core of ikiwiki; everything being a plugin and all, this is also a plugin ([[plugins/link]]).

The following needs to be done:

 1. the `link_regexp` variable needs to be turned backwards (or frontwards, if you like :P) (./) added an option for this, working!
 2. a config setting need to be added to the `link` plugin so that we can choose if we want backwards links or not (./) `links_direction`, how does that sound? I have changed that from `backwards_links` to be more neutral. 'rtl' means `\[[link|text]]` and 'ltr' means `\[[text|link]]`
 3. a (solid!) parser needs to be written for [[ikiwiki-transition]] to change the actual links (if necessary) (./) done!
 4. rewrite tests to take into account the two syntaxes (!) I would need help here, always have trouble with unit tests...
 5. deal with underlays (!!)

> It's not at all obvious to me that `rtl` should mean "link before description"
> and not the other way round. Perhaps `wikilink_text_first` => `1` for the historical
> IkiWiki syntax or `0` for the Creole/Mediawiki syntax? --[[smcv]]

<!> There's a caveat: we can't have a per-wiki backwards_links option, because of the underlay, common to all wikis, which needs to be converted. So the option doesn't make much sense. Not sure how to deal with this... Maybe this needs to be at the package level?

> I've thought about adding a direction-neutral `\[[!link]]` directive -
> see [[link plugin perhaps too general?]] for details. The basewiki
> could use `\[[!link to=b desc=a]]` whenever it needs `\[[a|b]]`-style
> links, maybe? --[[smcv]]

>> It could, but it would be a pain to remember to do that.
>> 
>> I feel that this should probably be a flag day transition because
>> otherwise there will be a lot of variation between how different
>> ikiwikis handle links, which is even worse than the current variation
>> between ikiwiki and other wikis!
>>
>> There are quite likely ikiwiki page generators that build wikilinks
>> too. One that's part of ikiwiki itself is `change.tmpl`. There may be
>> others... --[[Joey]]

>>> Agreed that it would be cleaner to just change everything, even though the transition might be painful.

>>> Another interim option might be to change the basewiki links to be just \[[link to whatever]] without having a description.
>>> That style of link would work whether the link style was "backwards" or "forwards".  Unfortunately it could make some links less readable; after all, there is a reason why one wants to be able to change the link text!  But I don't know what proportion of the links are like that.  It's a thought, anyway.
>>> --[[KathrynAndersen]]