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
Design
Goal
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).
Wikilinks
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.
-
Below are links to a small, working implementation for resolving
undefined rST references using ikiwiki's mechanism. This is Proposal 1
for rst WikiLinks.
-
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
.. _other: wiki:wikilink
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.
Benefits of using a :role: and a wiki: page/subpage URL scheme are
following:
-
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)
Implementation
Implementation of Proposal-2 wikilinks are in the branch
rst-wikilinks
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-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.
On top of rst-wikilinks is rst-customize 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
Directives
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.
-
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.
-
Formatting rST in filter (idea)
-
rST does not have to see any HTML (raw not needed)
-
rST directives can alias ikiwiki syntax:
..ikiwiki:: inline pages= ...
-
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.
Implementation
Preserving indents in the preprocessor are in branch pproc-indent
(These simple patches come with a warning: Those are the first lines of
Perl I've ever written!)
Discussion
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
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]]
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
