doc/plugins/rst/discussion.mdwn

   1 The main problem with more sophisticated RST support is that ikiwiki turns
   2 preprocessor directives into raw HTML and reST hates inline HTML.
   3 inline relies on Markdown's handling of raw HTML, specifically
   4 that it doesn't wrap paragraph-level `<div>`s in `<p>` tags -- see
   5 [[todo/htmlvalidation]]. Other plugins might expect their output to be
   6 interpreted in certain ways too -- [[Joey]] mentions toggleable and fortune.
   7
   8 Is [prest][1] the perl version of the reST processor referred to in the text?
   9 It seems to be reasonably well-maintained to me, and differences between it and
  10 "standard" reST are pretty minor. A fairly exhaustive list, taken from the
  11 prest docs, follows:
  12
  13 [1]: http://search.cpan.org/~nodine/Text-Restructured-0.003024/
  14
  15 An exhaustive list of differences between prest and "standard" reST follows:
  16
  17 * fewer alternatives for bullet lists (only "+", "*" and "-")
  18 * escaped colons are not allowed in field names
  19 * RCS keyword processing is only activated on "recognized bibliographic
  20     field names"
  21 * multiple consecutive blockquotes seperated by attributions may not be allowed
  22     (not sure; text could be interpreted either way)
  23 * a warning about auto-symbol footnotes is missing (maybe it's not relevant?)
  24 * colons are allowed within hyperlink reference names
  25 * inline markup can be nested
  26 * some directives are missing (epigraph, highlights, pull quote, date) and
  27     some have been added (MathML, code execution (disabled by default), enscript)
  28 * container directive now uses "class" instead of "classes"
  29 * csv directive doesn't require csv.py
  30 * references directive doesn't allow options
  31
  32 There may be a few others; my eyes glazed over. --Ethan
  33
  34 rst support for ikiwiki seems to be on hold. rst is much more elegant
  35 than markdown in my opinion, so I tried it out in ikiwiki. I found out
  36 in other places that some directives work just fine, like [[meta]] and
  37 [[tag]], others work fine if you wrap them in `.. raw::`, like [[inline]].
  38
  39 But to make a wiki we need [[WikiLinks]]; they can't be escape-inserted or
  40 such since they are inline elements in the text.. But images work fine in
  41 rst's syntax.. what about using rst syntax for wikilinks as well?
  42 Is it possible to inject something into the parser to turn unmached links
  43 ``WikiLink`_` into ikiwiki links? --ulrik
  44
  45 ------
  46
  47 Resolving WikiLinks in rst
  48 ==========================
  49
  50 I wanted to look into if we can hook into rst and influence how links are resolved.
  51 It turns out it is possible, and I have a working WIP for the rst plugin that does this.
  52
  53 My work in progress for `/usr/lib/ikiwiki/plugins/rst` is here:
  54 [[todo/Resolve native reStructuredText links to ikiwiki pages]]
  55
  56 It basically matches normal rst links just like ikiwiki would match a wikilink
  57 if it existed.
  58 I can't read perl so I haven't found out so much. The plugin successfully registers backlinks using
  59 `proxy.rpc('add_link', on_page, bestlink)` (since the destination page will be rebuilt to update),
  60 but the backlinks don't show up.
  61
  62 I converted one of my pages to rst:
  63
  64 Before: http://kaizer.se/wiki/kupfer-mdwn
  65 After: http://kaizer.se/wiki/kupfer-rst
  66
  67 I need help on a couple of points
  68
  69 * How to fix the backlinks with `add_link`?
  70 * How to generate NonExistingLinks using the plugin API?
  71 * Can we include this in ikiwiki's rst if it is not too hairy?
  72
  73 --ulrik