review

[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 55db32b4f49e856ffd1cc229aed74a4d236928e2..50720fed04d06cd69a260323d373cea2852526b6 100644 (file)
--- a/doc/todo/do_not_make_links_backwards.mdwn
+++ b/doc/todo/do_not_make_links_backwards.mdwn
@@ -30,6 +30,35 @@ Discussion
 > > 
 > > 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]]
 
 > > 
 > > 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]]
 

+> > > I still don't think `rtl`/`ltr` is the right terminology here. I think
+> > > the "API" should say what you mean: the distinction being made is
+> > > "text first" vs. "link first", so, say that.
+> > >
+> > > As far as I understand it, RTL languages like Arabic typically write
+> > > text files "in logical order" (i.e. reading/writing order - first
+> > > letter is first in the bytestream) and only apply RTL rendering on
+> > > display. IkiWiki is UTF-8-only, and Unicode specifies that all
+> > > Unicode text should be in logical order. The opposite of logical
+> > > order is is "display order", which is how you would have to mangle
+> > > the file for it to appear correctly on a naive terminal that expects
+> > > LTR; that can only work correctly for hard-wrapped text, I think.
+> > >
+> > > IkiWiki will parse files
+> > > in logical order too; so if a link's text and destination are both
+> > > written in Arabic, in text-before-link order in the source code, an
+> > > Arabic reader starting from the right would still see the text
+> > > before the link. Similarly, in your proposed link-before-text
+> > > order, an Arabic reader would still see the link before the text
+> > > (which in their case means further to the right). So I don't think
+> > > it would make sense to suggest that
+> > > one order was more appropriate for RTL languages than the other: if
+> > > it's "more correct" (for whatever opinion of "correct") in English, then
+> > > it's "more correct" in Arabic too.
+> > >
+> > > (If the destination is written in Latin then it gets
+> > > more complicated, because the destination will be rendered LTR within an
+> > > otherwise RTL document. I think the order still works though.) --[[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? --[[anarcat]]
 
 > I've thought about adding a direction-neutral `\[[!link]]` directive -
 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 -


@@ -54,11 +83,18 @@ There's a caveat: we can't have a per-wiki backwards_links option, because of th
 >>> 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]]
 
 >>> 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]]
 

+>>>> I dislike placing such requirements on the underlay, which is after
+>>>> all, just a subset of pages in this wiki, which many of the people
+>>>> editing may not even realize are part of the underlay. --[[Joey]]
+

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

+>>>>> No, that is *not* an option. Relative markdown links **break** when
+>>>>> page A, containing a link, is inlined into page B. --[[Joey]]
+

 ----
 
 FWIW, I think this change may well be painful, but is a good idea. I can never remember which way around it should be.
 ----
 
 FWIW, I think this change may well be painful, but is a good idea. I can never remember which way around it should be.


@@ -73,6 +109,7 @@ 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
 
  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

+    > Joey explicitly rejected this for a valid reason (it breaks inlining). See above. --[[smcv]]

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