2009-09-18 16:46:41 +02:00
|
|
|
_NB! this page has been refactored, hopefully it is clearer now_
|
|
|
|
_I propose putting discussion posts somewhere in the vincity of
|
|
|
|
the secttion Individual reStructuredText Issues_
|
2009-09-17 17:29:23 +02:00
|
|
|
|
2009-09-21 23:50:42 +02:00
|
|
|
## Design ##
|
|
|
|
|
2009-09-18 16:46:41 +02:00
|
|
|
**Goal**
|
2009-09-17 17:29:23 +02:00
|
|
|
|
2009-09-18 16:46:41 +02:00
|
|
|
To be able to use rst as a first-class markup language in ikiwiki. I think
|
|
|
|
most believe this is almost impossible (ikiwiki is built around markdown).
|
2009-09-17 17:29:23 +02:00
|
|
|
|
2009-09-21 23:50:42 +02:00
|
|
|
## Wikilinks ##
|
2009-09-17 17:29:23 +02:00
|
|
|
|
2009-09-18 16:46:41 +02:00
|
|
|
**WikiLinks**, first and foremost, are needed for a wiki. rST already allows
|
|
|
|
specifying absolue and relative URL links, and relative links can be used to
|
|
|
|
tie together wiki of rst documents.
|
2009-09-17 17:29:23 +02:00
|
|
|
|
2009-09-18 16:46:41 +02:00
|
|
|
1. Below are links to a small, working implementation for resolving
|
|
|
|
undefined rST references using ikiwiki's mechanism. This is **Proposal 1**
|
|
|
|
for rst WikiLinks.
|
2009-09-17 18:42:40 +02:00
|
|
|
|
2009-09-18 16:46:41 +02:00
|
|
|
2. Looking over at rST-using systems such as trac and MoinMoin; I think it
|
|
|
|
would be wiser to implement wikilinks by the `:role:` mechanism, together
|
|
|
|
with allowing a custom URL scheme to point to wiki links. This is
|
|
|
|
**Proposal 2**.
|
|
|
|
|
|
|
|
This is a simple wiki page, with :wiki:`WikiLinks` and other_ links
|
2009-09-18 20:07:18 +02:00
|
|
|
|
2009-09-18 16:46:41 +02:00
|
|
|
.. _other: wiki:wikilink
|
|
|
|
|
2009-09-18 20:07:18 +02:00
|
|
|
We can get rid of the role part as well for WikiLinks::
|
|
|
|
|
|
|
|
.. default-role:: wiki
|
|
|
|
|
|
|
|
Enables `WikiLinks` but does not impact references such as ``other``
|
|
|
|
This can be made the default for ikiwiki.
|
|
|
|
|
2009-09-18 16:46:41 +02:00
|
|
|
Benefits of using a `:role:` and a `wiki: page/subpage` URL scheme are
|
|
|
|
following:
|
|
|
|
|
|
|
|
1. rST documents taken out of the context (the wiki) will not fail as bad as
|
|
|
|
if they have lots of Proposal-1 links: They look just the same as valid
|
|
|
|
references, and you have to edit them all.
|
|
|
|
In contrast, should the `:wiki:` role disappear, one line is enough
|
|
|
|
to redefined it and silence all the warnings for the document:
|
|
|
|
|
|
|
|
.. role:: wiki (title)
|
|
|
|
|
2009-09-21 23:50:42 +02:00
|
|
|
### Implementation ###
|
|
|
|
|
|
|
|
Implementation of Proposal-2 wikilinks are in the branch
|
|
|
|
[rst-wikilinks][rst-wl]
|
|
|
|
|
|
|
|
|
|
|
|
This is a simple wiki page, with :wiki:`WikiLinks` and |named| links
|
|
|
|
|
|
|
|
.. |named| wiki:: Some Page
|
|
|
|
|
|
|
|
We can get rid of the role part as well for WikiLinks::
|
|
|
|
|
|
|
|
.. default-role:: wiki
|
|
|
|
|
|
|
|
Enables `WikiLinks` but does not impact references such as ``named``
|
|
|
|
This can be made the default for ikiwiki.
|
|
|
|
|
|
|
|
[rst-wl]: http://github.com/engla/ikiwiki/commits/rst-wikilinks
|
|
|
|
|
2009-09-22 23:17:11 +02:00
|
|
|
**rst-wikilinks** patch series includes changes at the end to use ikiwiki's
|
|
|
|
'htmllink' for the links (which is the only sane thing to do to work in all configurations).
|
|
|
|
This means a :wiki:`Link` should render just exactly like [[Link]] whether
|
|
|
|
the target exists or not.
|
|
|
|
|
2009-09-21 23:50:42 +02:00
|
|
|
On top of **rst-wikilinks** is [rst-customize][rst-custom] which adds two
|
|
|
|
power user features: Global (python) file to read in custom directives
|
|
|
|
(unsafe), and a wikifile as "header" file for all parsed .rst files (safe,
|
|
|
|
but disruptive since all .rst depend on it). Well, the customizations have
|
|
|
|
to be picked and chosen from this, but at least the global python file can
|
|
|
|
be very convenient.
|
|
|
|
|
|
|
|
Some rst-custom [examples are here](http://kaizer.se/wiki/rst_examples/)
|
|
|
|
|
|
|
|
[rst-custom]: http://github.com/engla/ikiwiki/commits/rst-customize
|
|
|
|
|
|
|
|
## Directives ##
|
2009-09-18 16:46:41 +02:00
|
|
|
|
|
|
|
Now **Directives**: As it is now, ikiwiki goes though (roughly):
|
|
|
|
filter, preprocess, htmlize, format as major stages of content
|
|
|
|
transformation. rST has major problems to work with any HTML that enters the
|
|
|
|
picture before it.
|
|
|
|
|
|
|
|
1. Formatting rST in `htmlize` (as is done now): Raw html can be escaped by
|
|
|
|
raw blocks:
|
|
|
|
|
|
|
|
.. raw:: html
|
|
|
|
|
|
|
|
\[[!inline and do stuff]]
|
|
|
|
|
|
|
|
(This can be simplified to alias the above as `.. ikiwiki::`)
|
|
|
|
This escape method works, if ikwiki can be persuaded to maintain the
|
|
|
|
indent when inserting html, so that it stays inside the raw block.
|
|
|
|
|
|
|
|
2. Formatting rST in `filter` (idea)
|
|
|
|
1. rST does not have to see any HTML (raw not needed)
|
|
|
|
2. rST directives can alias ikiwiki syntax:
|
|
|
|
|
|
|
|
..ikiwiki:: inline pages= ...
|
2009-09-18 16:08:16 +02:00
|
|
|
|
2009-09-18 16:46:41 +02:00
|
|
|
3. Using rST directives as ikiwiki directives can be complicated;
|
|
|
|
but rST directives allow a direct line (after :: on first line),
|
|
|
|
an option list, and a content block.
|
2009-09-17 17:29:23 +02:00
|
|
|
|
2009-09-30 19:57:36 +02:00
|
|
|
> You've done a lot of work already, but ...
|
|
|
|
>
|
|
|
|
> The filter approach seems much simpler than the other approaches
|
|
|
|
> for users to understand, since they can just use identical ikiwiki
|
|
|
|
> markup on rst pages as they would use anywhere else. This is very desirable
|
|
|
|
> if the wiki allows rst in addition to mdwn, since then users don't have
|
|
|
|
> to learn two completly different ways of doing wikilinks and directives.
|
|
|
|
> I also wonder if even those familiar with rst would find entirely natural
|
|
|
|
> the ways you've found to shoehorn in wikilinks, named wikilinks, and ikiwiki
|
|
|
|
> directives?
|
|
|
|
>
|
|
|
|
> Htmlize in filter avoids these problems. It also leaves open the possibility
|
|
|
|
> that ikiwiki could become smarter about the rendering chain later, and learn
|
|
|
|
> to use a better order for rst (ie, htmlize first). If that later happened,
|
|
|
|
> the htmlize in filter hack could go away. --[[Joey]]
|
|
|
|
|
|
|
|
> (BTW, the [[plugins/txt]] plugin already does html formatting
|
|
|
|
> in filter, for similar reasons.) --[[Joey]]
|
|
|
|
|
2009-09-21 23:50:42 +02:00
|
|
|
### Implementation ###
|
|
|
|
|
|
|
|
Preserving indents in the preprocessor are in branch [pproc-indent][ppi]
|
2009-09-18 16:46:41 +02:00
|
|
|
|
2009-09-22 01:39:03 +02:00
|
|
|
(These simple patches come with a warning: _Those are the first lines of
|
|
|
|
Perl I've ever written!_)
|
|
|
|
|
2009-09-30 19:57:36 +02:00
|
|
|
> This seems like a good idea, since it solves issues for eg, indented
|
|
|
|
> directives in mdwn as well. But, looking at the diff, I see a clear bug:
|
|
|
|
>
|
|
|
|
> - return "[[!$command <span class=\"error\">".
|
|
|
|
> + $result = "[[!$command <span class=\"error\">".
|
|
|
|
>
|
|
|
|
> That makes it go on and parse an infinitely nested directive chain, instead
|
|
|
|
> of immediatly throwing an error.
|
|
|
|
>
|
|
|
|
> Also, it seems that the "indent" matching in the regexps may be too broad,
|
|
|
|
> wouldn't it also match whitespace before a directive that was not at the beginning
|
|
|
|
> of a line, and treat it as an indent? With some bad luck, that could cause mdwn
|
|
|
|
> to put the indented output in a pre block. --[[Joey]]
|
|
|
|
|
2009-09-21 23:50:42 +02:00
|
|
|
[ppi]: http://github.com/engla/ikiwiki/commits/pproc-indent
|
|
|
|
|
|
|
|
## Discussion ##
|
2009-09-18 16:46:41 +02:00
|
|
|
|
|
|
|
I guess you (or someone) has been through this before and knows why it
|
|
|
|
simply won't work. But I hoped there was something original in the above;
|
|
|
|
and I know there are wiki installations where rST works. --ulrik
|
|
|
|
|
|
|
|
**Individual reStructuredText Issues**
|
|
|
|
|
|
|
|
* We resolve rST links without definition, we don't help resolving defined
|
|
|
|
relative links, so we don't support specifying link name and target
|
|
|
|
separately.
|
2009-09-21 23:50:42 +02:00
|
|
|
|
|
|
|
* Resolved by |replacement| links with the wiki:: directive.
|
2009-09-17 21:38:40 +02:00
|
|
|
|
2009-09-18 16:46:41 +02:00
|
|
|
**A first implementation: Resolving unmatched links**
|
|
|
|
|
|
|
|
I have a working minimal implementation letting the rst renderer resolve
|
|
|
|
undefined native rST links to ikiwiki pages. I have posted it as one patch at:
|
|
|
|
|
|
|
|
Preview commit: http://github.com/engla/ikiwiki/commit/486fd79e520da1d462f00f40e7a90ab07e9c6fdf
|
|
|
|
Repository: git://github.com/engla/ikiwiki.git
|
|
|
|
|
|
|
|
Design issues of the patch:
|
|
|
|
|
|
|
|
The page is rST-parsed once in 'scan' and once in 'htmlize' (the first to generate backlinks). Can the parse output be safely reused?
|
|
|
|
|
|
|
|
> The page content fed to htmlize may be different than that fed to scan,
|
|
|
|
> as directives can change the content. If you cached the input and output
|
|
|
|
> at scan time, you could reuse the cached data at htmlize time for inputs
|
|
|
|
> that are the same -- but that could be a very big cache! --[[Joey]]
|
2009-09-17 21:38:40 +02:00
|
|
|
|
2009-09-18 16:46:41 +02:00
|
|
|
>> I would propose using a simple heuristic: If you see \[[ anywhere on the
|
|
|
|
>> page, don't cache it. It would be an effective cache for pure-rst wikis
|
|
|
|
>> (without any ikiwiki directives or wikilinks).
|
|
|
|
>> However, I think that if the cache does not work for a big load, it should
|
|
|
|
>> not work at all; small loads are small so they don't matter. --ulrik
|
2009-09-17 17:29:23 +02:00
|
|
|
|