(no commit message)

[www/ikiwiki.git] / doc / plugins / rst / discussion.mdwn

diff --git a/doc/plugins/rst/discussion.mdwn b/doc/plugins/rst/discussion.mdwn
index 68e8f514f6c92774101afe0e5c24bcd839ed0cf5..38fbed6d69bbb5f5826932aebf857cfaff28f834 100644 (file)
--- a/doc/plugins/rst/discussion.mdwn
+++ b/doc/plugins/rst/discussion.mdwn
@@ -1,14 +1,17 @@
+The main problem with more sophisticated RST support is that ikiwiki turns 
+preprocessor directives into raw HTML and reST hates inline HTML.
+inline relies on Markdown's handling of raw HTML, specifically
+that it doesn't wrap paragraph-level `<div>`s in `<p>` tags -- see 
+[[todo/htmlvalidation]]. Other plugins might expect their output to be 
+interpreted in certain ways too -- [[Joey]] mentions toggleable and fortune.
+
 Is [prest][1] the perl version of the reST processor referred to in the text?
 It seems to be reasonably well-maintained to me, and differences between it and
-"standard" reST are pretty minor (a fairly exhaustive list, taken from the 
-prest docs, is at the end of this page).
+"standard" reST are pretty minor. A fairly exhaustive list, taken from the 
+prest docs, follows:
 
 [1]: http://search.cpan.org/~nodine/Text-Restructured-0.003024/
 
-In addition, reST appears to allow raw HTML pass-through with the `raw` 
-directive, though I think a better solution would be expanding the format plugin
-interface. --Ethan
-
 An exhaustive list of differences between prest and "standard" reST follows:
 
 * fewer alternatives for bullet lists (only "+", "*" and "-")
@@ -26,4 +29,45 @@ An exhaustive list of differences between prest and "standard" reST follows:
 * csv directive doesn't require csv.py
 * references directive doesn't allow options
 
-There may be a few others; my eyes glazed over. --Ethan
\ No newline at end of file
+There may be a few others; my eyes glazed over. --Ethan
+
+rst support for ikiwiki seems to be on hold. rst is much more elegant
+than markdown in my opinion, so I tried it out in ikiwiki. I found out
+in other places that some directives work just fine, like [[meta]] and
+[[tag]], others work fine if you wrap them in `.. raw::`, like [[inline]].
+
+But to make a wiki we need [[WikiLinks]]; they can't be escape-inserted or
+such since they are inline elements in the text.. But images work fine in
+rst's syntax.. what about using rst syntax for wikilinks as well?
+Is it possible to inject something into the parser to turn unmached links
+``WikiLink`_` into ikiwiki links? --ulrik
+
+------
+
+Resolving WikiLinks in rst
+==========================
+
+I wanted to look into if we can hook into rst and influence how links are resolved.
+It turns out it is possible, and I have a working WIP for the rst plugin that does this.
+
+My work in progress for `/usr/lib/ikiwiki/plugins/rst` is here: 
+[[todo/Resolve native reStructuredText links to ikiwiki pages]]
+
+It basically matches normal rst links just like ikiwiki would match a wikilink
+if it existed.
+I can't read perl so I haven't found out so much. The plugin successfully registers backlinks using
+`proxy.rpc('add_link', on_page, bestlink)` (since the destination page will be rebuilt to update),
+but the backlinks don't show up.
+
+I converted one of my pages to rst:
+
+Before: http://kaizer.se/wiki/kupfer-mdwn  
+After: http://kaizer.se/wiki/kupfer-rst  
+
+I need help on a couple of points
+
+* How to fix the backlinks with `add_link`?
+* How to generate NonExistingLinks using the plugin API?
+* Can we include this in ikiwiki's rst if it is not too hairy?
+
+--ulrik