doc/todo/Resolve_native_reStructuredText_links_to_ikiwiki_pages.mdwn

   1 _NB! this page has been refactored, hopefully it is clearer now_
   2 _I propose putting discussion posts somewhere in the vincity of
   3 the secttion Individual reStructuredText Issues_
   4
   5 ## Design ##
   6
   7 **Goal**
   8
   9 To be able to use rst as a first-class markup language in ikiwiki. I think
  10 most believe this is almost impossible (ikiwiki is built around markdown).
  11
  12 ## Wikilinks ##
  13
  14 **WikiLinks**, first and foremost, are needed for a wiki. rST already allows
  15 specifying absolue and relative URL links, and relative links can be used to
  16 tie together wiki of rst documents.
  17
  18 1. Below are links to a small, working implementation for resolving
  19    undefined rST references using ikiwiki's mechanism. This is **Proposal 1**
  20    for rst WikiLinks.
  21
  22 2. Looking over at rST-using systems such as trac and MoinMoin; I think it
  23    would be wiser to implement wikilinks by the `:role:` mechanism, together
  24    with allowing a custom URL scheme to point to wiki links. This is
  25    **Proposal 2**.
  26
  27         This is a simple wiki page, with :wiki:`WikiLinks` and other_ links
  28
  29         .. _other: wiki:wikilink
  30
  31         We can get rid of the role part as well for WikiLinks::
  32
  33             .. default-role:: wiki
  34
  35         Enables `WikiLinks` but does not impact references such as ``other``
  36         This can be made the default for ikiwiki.
  37
  38 Benefits of using a `:role:` and a `wiki: page/subpage` URL scheme are
  39 following:
  40
  41 1. rST documents taken out of the context (the wiki) will not fail as bad as
  42    if they have lots of Proposal-1 links: They look just the same as valid
  43    references, and you have to edit them all.
  44    In contrast, should the `:wiki:` role disappear, one line is enough
  45    to redefined it and silence all the warnings for the document:
  46
  47         .. role:: wiki (title)
  48
  49 ### Implementation ###
  50
  51 Implementation of Proposal-2 wikilinks are in the branch
  52 [rst-wikilinks][rst-wl]
  53
  54
  55         This is a simple wiki page, with :wiki:`WikiLinks` and |named| links
  56
  57         .. |named| wiki:: Some Page
  58
  59         We can get rid of the role part as well for WikiLinks::
  60
  61             .. default-role:: wiki
  62
  63         Enables `WikiLinks` but does not impact references such as ``named``
  64         This can be made the default for ikiwiki.
  65
  66 [rst-wl]: http://github.com/engla/ikiwiki/commits/rst-wikilinks
  67
  68 **rst-wikilinks** patch series includes changes at the end to use ikiwiki's
  69 'htmllink' for the links (which is the only sane thing to do to work in all configurations).
  70 This means a :wiki:`Link` should render just exactly like [[Link]] whether
  71 the target exists or not.
  72
  73 On top of **rst-wikilinks** is [rst-customize][rst-custom] which adds two
  74 power user features: Global (python) file to read in custom directives
  75 (unsafe), and a wikifile as "header" file for all parsed .rst files (safe,
  76 but disruptive since all .rst depend on it). Well, the customizations have
  77 to be picked and chosen from this, but at least the global python file can
  78 be very convenient.
  79
  80 Some rst-custom [examples are here](http://kaizer.se/wiki/rst_examples/)
  81
  82 [rst-custom]: http://github.com/engla/ikiwiki/commits/rst-customize
  83
  84 ## Directives ##
  85
  86 Now **Directives**: As it is now, ikiwiki goes though (roughly):
  87 filter, preprocess, htmlize, format as major stages of content
  88 transformation. rST has major problems to work with any HTML that enters the
  89 picture before it.
  90
  91 1. Formatting rST in `htmlize` (as is done now): Raw html can be escaped by
  92    raw blocks:
  93
  94         .. raw:: html
  95
  96                 \[[!inline and do stuff]]
  97
  98    (This can be simplified to alias the above as `.. ikiwiki::`)
  99    This escape method works, if ikwiki can be persuaded to maintain the
 100    indent when inserting html, so that it stays inside the raw block.
 101
 102 2. Formatting rST in `filter` (idea)
 103    1. rST does not have to see any HTML (raw not needed)
 104    2. rST directives can alias ikiwiki syntax:
 105
 106         ..ikiwiki:: inline pages= ...
 107
 108    3. Using rST directives as ikiwiki directives can be complicated;
 109       but rST directives allow a direct line (after :: on first line),
 110       an option list, and a content block.
 111
 112 ### Implementation ###
 113
 114 Preserving indents in the preprocessor are in branch [pproc-indent][ppi]
 115
 116 (These simple patches come with a warning: _Those are the first lines of
 117 Perl I've ever written!_)
 118
 119 [ppi]: http://github.com/engla/ikiwiki/commits/pproc-indent
 120
 121 ## Discussion ##
 122
 123 I guess you (or someone) has been through this before and knows why it
 124 simply won't work. But I hoped there was something original in the above;
 125 and I know there are wiki installations where rST works. --ulrik
 126
 127 **Individual reStructuredText Issues**
 128
 129 * We resolve rST links without definition, we don't help resolving defined
 130   relative links, so we don't support specifying link name and target
 131   separately.
 132
 133   * Resolved by |replacement| links with the wiki:: directive.
 134
 135 **A first implementation: Resolving unmatched links**
 136
 137 I have a working minimal implementation letting the rst renderer resolve
 138 undefined native rST links to ikiwiki pages. I have posted it as one patch at:
 139
 140 Preview commit: http://github.com/engla/ikiwiki/commit/486fd79e520da1d462f00f40e7a90ab07e9c6fdf
 141 Repository: git://github.com/engla/ikiwiki.git
 142
 143 Design issues of the patch:
 144
 145 The page is rST-parsed once in 'scan' and once in 'htmlize' (the first to generate backlinks). Can the parse output be safely reused?
 146
 147 > The page content fed to htmlize may be different than that fed to scan,
 148 > as directives can change the content. If you cached the input and output
 149 > at scan time, you could reuse the cached data at htmlize time for inputs
 150 > that are the same -- but that could be a very big cache! --[[Joey]]
 151
 152 >> I would propose using a simple heuristic: If you see \[[ anywhere on the
 153 >> page, don't cache it. It would be an effective cache for pure-rst wikis
 154 >> (without any ikiwiki directives or wikilinks).
 155 >> However, I think that if the cache does not work for a big load, it should
 156 >> not work at all; small loads are small so they don't matter. --ulrik
 157