update with today's work

[git.ikiwiki.info.git] / doc / todo / do_not_make_links_backwards.mdwn

diff --git a/doc/todo/do_not_make_links_backwards.mdwn b/doc/todo/do_not_make_links_backwards.mdwn
index 7f54c26f7af9c1aa29ab06dd088c823f6b53b213..55db32b4f49e856ffd1cc229aed74a4d236928e2 100644 (file)
--- a/doc/todo/do_not_make_links_backwards.mdwn
+++ b/doc/todo/do_not_make_links_backwards.mdwn
@@ -16,14 +16,21 @@ 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!
  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 (!!)
+ 4. rewrite tests to take into account the two syntaxes (!) would be done when we migrate to the syntax
+ 5. deal with underlays (./) i wrote a script to convert it to markdown
+
+Discussion
+----------

 
 > 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]]
 
 > 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]]

+>
+> > 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".
+> > 
+> > 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]]

 
 

-<!> 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?
+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]]

 
 > I've thought about adding a direction-neutral `\[[!link]]` directive -
 > see [[link plugin perhaps too general?]] for details. The basewiki
 
 > I've thought about adding a direction-neutral `\[[!link]]` directive -
 > see [[link plugin perhaps too general?]] for details. The basewiki


@@ -46,3 +53,36 @@ The following needs to be done:
 >>> 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]]
 >>> 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]]

+
+>>> 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.
+>>> I also agree that we should just switch in one shot, although I am worried this means this could be postponed indefinitely.--[[anarcat]]
+
+>>>> 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]]
+
+----
+
+FWIW, I think this change may well be painful, but is a good idea. I can never remember which way around it should be.
+Rather like USB plugs, I invariably have to try both ways. — [[Jon]]
+
+The bikeshed color should be ...
+--------------------------------
+
+...[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?
+
+I think we can approach this rationnally:
+
+ 1. left to right (text then link) can be considered more natural, and should therefore be supported
+ 2. it is supported in markdown using regular markdown links. in the proposed branch, the underlay wikilinks are converted to use regular markdown links
+ 3. ikiwiki links break other markup plugins, like mediawiki and creole, as those work right to left.
+ 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)
+
+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.
+
+So here's a roadmap to deploy this change:
+
+ 1. the code in the backwards_links branch i am working on is tested and proven, then merged in
+ 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
+ 3. this wiki is converted to the new markup
+ 4. 4.0 is released with the new markup enabled by default and runs ikiwiki-transition on your wiki on upgrade
+
+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]]