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 > You've done a lot of work already, but ...
 113 >
 114 > The filter approach seems much simpler than the other approaches
 115 > for users to understand, since they can just use identical ikiwiki
 116 > markup on rst pages as they would use anywhere else. This is very desirable
 117 > if the wiki allows rst in addition to mdwn, since then users don't have
 118 > to learn two completly different ways of doing wikilinks and directives.
 119 > I also wonder if even those familiar with rst would find entirely natural
 120 > the ways you've found to shoehorn in wikilinks, named wikilinks, and ikiwiki
 121 > directives?
 122 >
 123 > Htmlize in filter avoids these problems. It also leaves open the possibility
 124 > that ikiwiki could become smarter about the rendering chain later, and learn
 125 > to use a better order for rst (ie, htmlize first). If that later happened,
 126 > the htmlize in filter hack could go away. --[[Joey]]
 127
 128 > (BTW, the [[plugins/txt]] plugin already does html formatting
 129 > in filter, for similar reasons.) --[[Joey]]
 130
 131 >> Thank you for the comments! Forget the work, it's not so much.
 132 >> I'd rank the :wiki: link addition pretty high, and the other changes way
 133 >> behind that:
 134 >>
 135 >> The :wiki:`Wiki Link` syntax is *very* appropriate as rst syntax
 136 >> since it fits well with other uses of roles (notice that :RFC:`822`
 137 >> inserts a link to RFC822 etc, and that the default role is a *title* role
 138 >> (title of some work); thus very appropriate for medium-specific links like
 139 >> wiki links. So I'd rank :wiki: links a worthwhile addition regardless of
 140 >> outcome here, since it's a very rst-like alternative for those who wish to
 141 >> use more rst-like syntax (and documents degrades better outside the wiki as
 142 >> noted).
 143 >>
 144 >> The named link syntax (just like the :wiki: role) are inspired from trac
 145 >> and a good fit, but only if the wiki is committed to using only rst,
 146 >> which I don't think is the case.
 147 >>
 148 >> The rst-customize changes are very useful for custom directive
 149 >> installations (like the sourcecode directive, or shortcut roles I show
 150 >> in the examples page), but there might be a way for the user to inject
 151 >> docutils addons that I'm missing (one very ugly way would be to stick
 152 >> them in sitecustomize.py which affects all Python programs).
 153 >>
 154 >> With the presented changes, I already have a working RestructuredText
 155 >> wiki, but I'm admitting that using .. raw:: html around all directives is
 156 >> very ugly (I use few directives: inline, toggle, meta, tag, map)
 157 >>
 158 >> On filter/htmlize: Well **rst** is clearly antisocial: It can't see HTML,
 159 >> and ikiwiki directives are wrappend in paragraph tags. (For wikilinks
 160 >> this is probably no problem). So the suggestion about `.. ikiwiki:` is
 161 >> partly because it looks good in rst syntax, but also since it would emit
 162 >> a div to wrap around the element instead of a paragraph.
 163 >>
 164 >> I don't know if you mean that rst could be reordered to do htmlize before
 165 >> other phases? rst must be before any preprocess hook to avoid seeing any
 166 >> HTML.
 167 >>
 168 >> With the presented changes, I already have a working RestructuredText
 169 >> wiki, but I'm admitting that using .. raw:: html around all directives is
 170 >> very ugly (I use few directives: inline, toggle, meta, tag, map)
 171 >>
 172 >> If I'm thinking right, processing to HTML already in filter means any
 173 >> processing in scan can be reused directly (or skipped if it's legal to
 174 >> emit 'add_link' in filter.)
 175 >>
 176 >> -- [[ulrik]]
 177
 178
 179 ### Implementation ###
 180
 181 Preserving indents in the preprocessor are in branch [pproc-indent][ppi]
 182
 183 (These simple patches come with a warning: _Those are the first lines of
 184 Perl I've ever written!_)
 185
 186 > This seems like a good idea, since it solves issues for eg, indented
 187 > directives in mdwn as well. But, looking at the diff, I see a clear bug:
 188 >
 189 >       -                               return "[[!$command <span class=\"error\">".
 190 >       +                               $result = "[[!$command <span class=\"error\">".
 191 >
 192 > That makes it go on and parse an infinitely nested directive chain, instead
 193 > of immediatly throwing an error.
 194 >
 195 > Also, it seems that the "indent" matching in the regexps may be too broad,
 196 > wouldn't it also match whitespace before a directive that was not at the beginning
 197 > of a line, and treat it as an indent? With some bad luck, that could cause mdwn
 198 > to put the indented output in a pre block. --[[Joey]]
 199 >
 200 >> You are probably right about the bug. I'm not quite sure what the nested
 201 >> directives examples looks like, but I must have overlooked how the
 202 >> recursion counter works; I thought simply changing if to elif the next
 203 >> few lines would solve that. I'm sorry for that!
 204 >>
 205 >> We don't have to change the `$handle` function at all, if it is possible
 206 >> to do the indent substitution all in one line instead of passing it to
 207 >> handle, I don't know if it is possible to turn:
 208 >>
 209 >>              $content =~ s{$regex}{$handle->($1, $2, $3, $4, $5)}eg;
 210 >>
 211 >> into
 212 >>
 213 >>              $content =~ s{$regex}{s/^/$1/gm{$handle->($2, $3, $4, $5)}}eg;
 214 >>
 215 >> Well, no idea how that would be expressed, but I mean, replace the indent
 216 >> directly in $handle's return value.
 217 >>
 218 >> The indent-catching regex is wrong in the way you mention, it has been
 219 >> nagigng my mind a bit as well; I think matching start of line + spaces
 220 >> and tabs is the only thing we want.
 221 >> -- [[ulrik]]
 222
 223 [ppi]: http://github.com/engla/ikiwiki/commits/pproc-indent
 224
 225 ## Discussion ##
 226
 227 I guess you (or someone) has been through this before and knows why it
 228 simply won't work. But I hoped there was something original in the above;
 229 and I know there are wiki installations where rST works. --ulrik
 230
 231 **Individual reStructuredText Issues**
 232
 233 * We resolve rST links without definition, we don't help resolving defined
 234   relative links, so we don't support specifying link name and target
 235   separately.
 236
 237   * Resolved by |replacement| links with the wiki:: directive.
 238
 239 **A first implementation: Resolving unmatched links**
 240
 241 I have a working minimal implementation letting the rst renderer resolve
 242 undefined native rST links to ikiwiki pages. I have posted it as one patch at:
 243
 244 Preview commit: http://github.com/engla/ikiwiki/commit/486fd79e520da1d462f00f40e7a90ab07e9c6fdf
 245 Repository: git://github.com/engla/ikiwiki.git
 246
 247 Design issues of the patch:
 248
 249 The page is rST-parsed once in 'scan' and once in 'htmlize' (the first to generate backlinks). Can the parse output be safely reused?
 250
 251 > The page content fed to htmlize may be different than that fed to scan,
 252 > as directives can change the content. If you cached the input and output
 253 > at scan time, you could reuse the cached data at htmlize time for inputs
 254 > that are the same -- but that could be a very big cache! --[[Joey]]
 255
 256 >> I would propose using a simple heuristic: If you see \[[ anywhere on the
 257 >> page, don't cache it. It would be an effective cache for pure-rst wikis
 258 >> (without any ikiwiki directives or wikilinks).
 259 >> However, I think that if the cache does not work for a big load, it should
 260 >> not work at all; small loads are small so they don't matter. --ulrik
 261