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 (!) would be done when we migrate to the syntax
  20  5. deal with underlays (./) i wrote a script to convert it to markdown
  21
  22 Discussion
  23 ----------
  24
  25 > It's not at all obvious to me that `rtl` should mean "link before description"
  26 > and not the other way round. Perhaps `wikilink_text_first` => `1` for the historical
  27 > IkiWiki syntax or `0` for the Creole/Mediawiki syntax? --[[smcv]]
  28 >
  29 > > A friend made the argument that it is more natural for a human to read the `text` then `link`, as the link is less important. Since we (occidental languages) read left to right, I felt this was appropriate. I also blindly assumed that it would "feel" also appropriate for right to left languages (arabic, hebrew, etc) to have those links backwards, and those languages are generally named "right to left".
  30 > >
  31 > > Originally, I named that parameter `backwards_links`, but then it wouldn't make sense in the long term, and isn't exactly neutral: it assume the current way is backwards! Your suggestion is interesting however, but I don't think the rtl/ltr nomenclature is problematic, with proper documentation of course... --[[anarcat]]
  32
  33 > > > I still don't think `rtl`/`ltr` is the right terminology here. I think
  34 > > > the "API" should say what you mean: the distinction being made is
  35 > > > "text first" vs. "link first", so, say that.
  36 > > >
  37 > > > As far as I understand it, RTL languages like Arabic typically write
  38 > > > text files "in logical order" (i.e. reading/writing order - first
  39 > > > letter is first in the bytestream) and only apply RTL rendering on
  40 > > > display. IkiWiki is UTF-8-only, and Unicode specifies that all
  41 > > > Unicode text should be in logical order. The opposite of logical
  42 > > > order is is "display order", which is how you would have to mangle
  43 > > > the file for it to appear correctly on a naive terminal that expects
  44 > > > LTR; that can only work correctly for hard-wrapped text, I think.
  45 > > >
  46 > > > IkiWiki will parse files
  47 > > > in logical order too; so if a link's text and destination are both
  48 > > > written in Arabic, in text-before-link order in the source code, an
  49 > > > Arabic reader starting from the right would still see the text
  50 > > > before the link. Similarly, in your proposed link-before-text
  51 > > > order, an Arabic reader would still see the link before the text
  52 > > > (which in their case means further to the right). So I don't think
  53 > > > it would make sense to suggest that
  54 > > > one order was more appropriate for RTL languages than the other: if
  55 > > > it's "more correct" (for whatever opinion of "correct") in English, then
  56 > > > it's "more correct" in Arabic too.
  57 > > >
  58 > > > (If the destination is written in Latin then it gets
  59 > > > more complicated, because the destination will be rendered LTR within an
  60 > > > otherwise RTL document. I think the order still works though.) --[[smcv]]
  61
  62 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? --[[anarcat]]
  63
  64 > I've thought about adding a direction-neutral `\[[!link]]` directive -
  65 > see [[link plugin perhaps too general?]] for details. The basewiki
  66 > could use `\[[!link to=b desc=a]]` whenever it needs `\[[a|b]]`-style
  67 > links, maybe? --[[smcv]]
  68
  69 >> It could, but it would be a pain to remember to do that.
  70 >>
  71 >> I feel that this should probably be a flag day transition because
  72 >> otherwise there will be a lot of variation between how different
  73 >> ikiwikis handle links, which is even worse than the current variation
  74 >> between ikiwiki and other wikis!
  75 >>
  76 >> There are quite likely ikiwiki page generators that build wikilinks
  77 >> too. One that's part of ikiwiki itself is `change.tmpl`. There may be
  78 >> others... --[[Joey]]
  79
  80 >>> Agreed that it would be cleaner to just change everything, even though the transition might be painful.
  81
  82 >>> Another interim option might be to change the basewiki links to be just \[[link to whatever]] without having a description.
  83 >>> 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.
  84 >>> --[[KathrynAndersen]]
  85
  86 >>>> I dislike placing such requirements on the underlay, which is after
  87 >>>> all, just a subset of pages in this wiki, which many of the people
  88 >>>> editing may not even realize are part of the underlay. --[[Joey]]
  89
  90 >>> Another option for internal links is to just use the regular markdown links instead of `\[[text|link]]` markup, that way it works regardless. Then the documentation for the link plugin just has to state both syntaxes in a safe manner.
  91 >>> I also agree that we should just switch in one shot, although I am worried this means this could be postponed indefinitely.--[[anarcat]]
  92
  93 >>>> I have done just that in my branch: now the underlay only uses wikilinks in the wikilink page, elsewhere regular markdown links are used. I haven't converted the whole of the doc/ directory however, that would be left to the migration. I have written a ikiwik-transition tool to migrate from wikilink to markdown while i was there. --[[anarcat]]
  94
  95 >>>>> No, that is *not* an option. Relative markdown links **break** when
  96 >>>>> page A, containing a link, is inlined into page B. --[[Joey]]
  97
  98 ----
  99
 100 FWIW, I think this change may well be painful, but is a good idea. I can never remember which way around it should be.
 101 Rather like USB plugs, I invariably have to try both ways. — [[Jon]]
 102
 103 The bikeshed color should be ...
 104 --------------------------------
 105
 106 ...[blue](http://blue.bikeshed.org/) of course. :) Just to make things clear here, the "bikeshedding" potential is absolutely huge here. right to left? left to right? who's right? how could we even decide this?
 107
 108 I think we can approach this rationnally:
 109
 110  1. left to right (text then link) can be considered more natural, and should therefore be supported
 111  2. it is supported in markdown using regular markdown links. in the proposed branch, the underlay wikilinks are converted to use regular markdown links
 112     > Joey explicitly rejected this for a valid reason (it breaks inlining). See above. --[[smcv]]
 113  3. ikiwiki links break other markup plugins, like mediawiki and creole, as those work right to left.
 114  4. those are recognized "standards" used by other popular sites, like Wikipedia, or any wiki supporting the Creole markup, which is [most wikis](http://www.wikicreole.org/wiki/Engines)
 115
 116 Therefore, to respect interoperability and [POLA](https://en.wikipedia.org/wiki/Principle_of_least_astonishment), ikiwiki should respect that convention and reverse the way links are parsed by the link plugin, or move that functionality into creole/mediawiki modules, and out of the main core, which I do not think can be an option.
 117
 118 So here's a roadmap to deploy this change:
 119
 120  1. the code in the backwards_links branch i am working on is tested and proven, then merged in
 121  2. a release of the 3.x branch is published with the possibility for wikis to convert to the new markup, with the notion that the older markup is deprecated
 122  3. this wiki is converted to the new markup
 123  4. 4.0 is released with the new markup enabled by default and runs ikiwiki-transition on your wiki on upgrade
 124
 125 Note that ikiwiki-transition can be ran multiple and will convert your markup to and from rtl/ltr, without issues, so this is pretty sturdy. I think the configuration variable can be kept throughout 4.x, with the notion that it will be completely removed eventually. --[[anarcat]]