doc/todo/Short_wikilinks.mdwn

   1 Markdown supports nice short links to external sites within body text by
   2 references defined elsewhere in the source:
   3
   4         foo [bar][ref]
   5
   6         [ref]: http://example.invalid/
   7
   8 It would be nice to be able to do this or something like this for wikilinks
   9 as well, so that you can have long page names without the links cluttering
  10 the body text. I think the best way to do this would be to move wikilink
  11 resolving after HTML generation: parse the HTML with a proper HTML parser,
  12 and replace relative links with links to the proper files (plus something
  13 extra for missing pages).
  14
  15 > That's difficult to do and have resonable speed as well. Ikiwiki needs to
  16 > know all about all the links between pages before it can know what pages
  17 > it needs to build to it can update backlink lists, update links to point
  18 > to new/moved pages etc. Currently it accomplishes this by a first pass
  19 > that scans new and changed files, and quickly finds all the wikilinks
  20 > using a simple regexp. If it had to render the whole page before it was
  21 > able to scan for hrefs using a html parser, this would make it at least
  22 > twice as slow, or would require it to cache all the rendered pages in
  23 > memory to avoid re-rendering. I don't want ikiwiki to be slow or use
  24 > excessive amounts of memory. YMMV. --[[Joey]]
  25
  26 >> Or you could disk cache the incomplete page containing only the body text,
  27 >> which should often not need re-rendering, as most alterations consist of
  28 >> changing the link targets exactly, and we can know pages that exist before
  29 >> rendering a single page. Then after backlinks have been resolved, it would
  30 >> suffice to feed this body text from the cache file to the template. However, e.g.
  31 >> the inline plugin would demand extra rendering after the depended-upon pages
  32 >> have been rendered, but these pages should usually not be that frequent, or
  33 >> contain that many other pages in full. (And for 'archive' pages we don't need
  34 >> to remember that much information from the semi-inlined pages.) It would help
  35 >> if you could get data structures instead of HTML text from the HTMLizer, and
  36 >> then simply cache these data structures in some quickly-loadeble form (that
  37 >> I suppose perl itself has support for). Regexp hacks are so ugly compared
  38 >> to actually parsing a properly-defined syntax...
  39
  40 A related possibility would be to move a lot of "preprocessing" after HTML
  41 generation as well (thus avoiding some conflicts with the htmlifier), by
  42 using special tags for the preprocessor stuff. (The old preprocessor could
  43 simply replace links and directives with appropriate tags, that the
  44 htmlifier is supposed to let through as-is. Possibly the htmlifier plugin
  45 could configure the format.)
  46
  47 > Or using postprocessing, though there are problems with that too and it
  48 > doesn't solve the link scanning issue.
  49
  50 Other alternatives would be
  51
  52   * to understand the source format, but this seems too much work with all the supported formats; or
  53
  54   * something like the shortcut plugin for external links, with additional
  55     support for specifying the link text, but the syntax would be much more
  56     cumbersome then.
  57
  58 > I agree that a plugin would probably be more cumbersome, but it is very
  59 > doable. It might look something like this:
  60
  61         \[[link bar]]
  62
  63         \[[link bar=VeryLongPageName]]
  64
  65 >> This is, however, still missing specifying the link text, and adding that option would seem to me to complicate the plugin syntax a lot, unless support is added for the |-syntax for specifying a particular parameter to every plugin.
  66
  67 >>> Well, the link text in my example above is "bar". It's true that if
  68 >>> you want to use the same link text for multiple distinct links, or
  69 >>> different link texts for the same link, this is missing a useful layer of
  70 >>> indirection; it's optimised for the (probably) more common case. It
  71 >>> could be done as a degenerate form of the syntax I propose below, BTW.
  72 >>> --[[Joey]]
  73
  74 >> ... Returning to this, the syntax infact wouldn't be so bad with the |-syntax, given a short name for the plugin:
  75
  76        [[whatever|ref 1]]
  77        \[[ref 1=page_with_long_name]]
  78
  79 >>> A way to do this that doesn't need hacking at the preprocessor syntax
  80 >>> follows: --[[Joey]]
  81
  82         \[[link bar=1]]
  83         \[[dest 1=page_with_long_name]]
  84
  85 >>>> But this doesn't work so well for links that aren't valid keys. Such
  86 >>>> as stuff with spaces in it. I'd like to be able to write any kind of
  87 >>>> links conveniently, not just something that looks like a wikilink.
  88
  89 >>>>> You're right, and to fix that it could be turned around: --[[Joey]]
  90
  91         \[[link 1=bar]]
  92         \[[dest 1=page_with_long_name]]
  93
  94 >> It also shouldn't be difficult to support non-wiki links in this same
  95 >> way, so that you could still link everywhere in an uniform manner, as
  96 >> the (still preferred by me) HTML processing approach would provide.
  97 >> Perhaps a plugin call wouldn't even be necessary for the links
  98 >> themselves: what about aliases for the normal link mechanism? Although
  99 >> the 'ref' call may infact be cleaner, and adding that |-syntax for
 100 >> plugins could offer other possibilities for other plugins.
 101
 102 >>> I agree, it should be easy to make it support non-wiki links too.
 103 >>> We seem to have converged at something we can both live with that's
 104 >>> reasonable to implement.. --[[Joey]]