doc/todo/do_not_make_links_backwards.mdwn

   1 [[!template  id=gitbranch branch=anarcat/backwards_links author="[[anarcat]]"]]
   2
   3 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]]`.
   4
   5 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.
   6
   7 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]]
   8
   9 Dev notes
  10 ---------
  11
  12 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]]).
  13
  14 The following needs to be done:
  15
  16  1. the `link_regexp` variable needs to be turned backwards (or frontwards, if you like :P) (./) added an option for this, working!
  17  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]]`
  18  3. a (solid!) parser needs to be written for [[ikiwiki-transition]] to change the actual links (if necessary) (./) done!
  19  4. rewrite tests to take into account the two syntaxes (!) I would need help here, always have trouble with unit tests...
  20  5. deal with underlays (!!)
  21
  22 > It's not at all obvious to me that `rtl` should mean "link before description"
  23 > and not the other way round. Perhaps `wikilink_text_first` => `1` for the historical
  24 > IkiWiki syntax or `0` for the Creole/Mediawiki syntax? --[[smcv]]
  25
  26 <!> 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?
  27
  28 > I've thought about adding a direction-neutral `\[[!link]]` directive -
  29 > see [[link plugin perhaps too general?]] for details. The basewiki
  30 > could use `\[[!link to=b desc=a]]` whenever it needs `\[[a|b]]`-style
  31 > links, maybe? --[[smcv]]