X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/ca0ce08605a2d4ac74a64405080082c513e681d2..e67a9382f67e745af3be7d367fe7a0d36c1777e6:/doc/plugins/rst/discussion.mdwn?ds=sidebyside diff --git a/doc/plugins/rst/discussion.mdwn b/doc/plugins/rst/discussion.mdwn index 68e8f514f..38fbed6d6 100644 --- 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 `
`s in `

` 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