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_
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).
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.
18 1. Below are links to a small, working implementation for resolving
19 undefined rST references using ikiwiki's mechanism. This is **Proposal 1**
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
27 This is a simple wiki page, with :wiki:`WikiLinks` and other_ links
29 .. _other: wiki:wikilink
31 We can get rid of the role part as well for WikiLinks::
33 .. default-role:: wiki
35 Enables `WikiLinks` but does not impact references such as ``other``
36 This can be made the default for ikiwiki.
38 Benefits of using a `:role:` and a `wiki: page/subpage` URL scheme are
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:
47 .. role:: wiki (title)
49 ### Implementation ###
51 Implementation of Proposal-2 wikilinks are in the branch
52 [rst-wikilinks][rst-wl]
55 This is a simple wiki page, with :wiki:`WikiLinks` and |named| links
57 .. |named| wiki:: Some Page
59 We can get rid of the role part as well for WikiLinks::
61 .. default-role:: wiki
63 Enables `WikiLinks` but does not impact references such as ``named``
64 This can be made the default for ikiwiki.
66 [rst-wl]: http://github.com/engla/ikiwiki/commits/rst-wikilinks
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.
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
80 Some rst-custom [examples are here](http://kaizer.se/wiki/rst_examples/)
82 [rst-custom]: http://github.com/engla/ikiwiki/commits/rst-customize
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
91 1. Formatting rST in `htmlize` (as is done now): Raw html can be escaped by
96 \[[!inline and do stuff]]
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.
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:
106 ..ikiwiki:: inline pages= ...
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.
112 > You've done a lot of work already, but ...
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
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]]
128 > (BTW, the [[plugins/txt]] plugin already does html formatting
129 > in filter, for similar reasons.) --[[Joey]]
131 ### Implementation ###
133 Preserving indents in the preprocessor are in branch [pproc-indent][ppi]
135 (These simple patches come with a warning: _Those are the first lines of
136 Perl I've ever written!_)
138 > This seems like a good idea, since it solves issues for eg, indented
139 > directives in mdwn as well. But, looking at the diff, I see a clear bug:
141 > - return "[[!$command <span class=\"error\">".
142 > + $result = "[[!$command <span class=\"error\">".
144 > That makes it go on and parse an infinitely nested directive chain, instead
145 > of immediatly throwing an error.
147 > Also, it seems that the "indent" matching in the regexps may be too broad,
148 > wouldn't it also match whitespace before a directive that was not at the beginning
149 > of a line, and treat it as an indent? With some bad luck, that could cause mdwn
150 > to put the indented output in a pre block. --[[Joey]]
152 [ppi]: http://github.com/engla/ikiwiki/commits/pproc-indent
156 I guess you (or someone) has been through this before and knows why it
157 simply won't work. But I hoped there was something original in the above;
158 and I know there are wiki installations where rST works. --ulrik
160 **Individual reStructuredText Issues**
162 * We resolve rST links without definition, we don't help resolving defined
163 relative links, so we don't support specifying link name and target
166 * Resolved by |replacement| links with the wiki:: directive.
168 **A first implementation: Resolving unmatched links**
170 I have a working minimal implementation letting the rst renderer resolve
171 undefined native rST links to ikiwiki pages. I have posted it as one patch at:
173 Preview commit: http://github.com/engla/ikiwiki/commit/486fd79e520da1d462f00f40e7a90ab07e9c6fdf
174 Repository: git://github.com/engla/ikiwiki.git
176 Design issues of the patch:
178 The page is rST-parsed once in 'scan' and once in 'htmlize' (the first to generate backlinks). Can the parse output be safely reused?
180 > The page content fed to htmlize may be different than that fed to scan,
181 > as directives can change the content. If you cached the input and output
182 > at scan time, you could reuse the cached data at htmlize time for inputs
183 > that are the same -- but that could be a very big cache! --[[Joey]]
185 >> I would propose using a simple heuristic: If you see \[[ anywhere on the
186 >> page, don't cache it. It would be an effective cache for pure-rst wikis
187 >> (without any ikiwiki directives or wikilinks).
188 >> However, I think that if the cache does not work for a big load, it should
189 >> not work at all; small loads are small so they don't matter. --ulrik