reviewed, not merged

[git.ikiwiki.info.git] / doc / todo / Resolve_native_reStructuredText_links_to_ikiwiki_pages.mdwn

diff --git a/doc/todo/Resolve_native_reStructuredText_links_to_ikiwiki_pages.mdwn b/doc/todo/Resolve_native_reStructuredText_links_to_ikiwiki_pages.mdwn
index 4468ce1e997526d0b9e3eb33df0c55bf77f3779d..6e0f32fd57177b1f5ed10a5b339a903213910b35 100644 (file)
--- a/doc/todo/Resolve_native_reStructuredText_links_to_ikiwiki_pages.mdwn
+++ b/doc/todo/Resolve_native_reStructuredText_links_to_ikiwiki_pages.mdwn
@@ -77,6 +77,28 @@ 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.
 
 to be picked and chosen from this, but at least the global python file can
 be very convenient.
 

+> Did you consider just including the global rst header text into an item
+> in the setup file? --[[Joey]] 
+>
+>> Then `rst_header` would not be much different from the python script
+>> `rst_customize`. rst_header is as safe as other files (though disruptive
+>> as noted), so it should/could be a editable file in the Wiki. A Python
+>> script of course can not be. There is nothing you can do in the
+>> rst_header (that you sensibly would do, I think) that couldn't be done in
+>> the Python script. `rst_header` has very limited use, but it is another
+>> possibility, mainly for the user-editable aspect. --[[ulrik]]
+>>
+>> (I foresaw only two things to be added to the rst_header: the default
+>> role could be configured there (as with rst_wikirole), and if you have a
+>> meta-role like :shortcut:, shortcuts could be defined there.)
+>
+> I have some discussion on the [docutils mailing list][dml], the developers
+> of docutils seems to favor "Proposal 1", while I defend my ideas. They
+> want all users of ReST to use only the basic featureset to remain
+> compatible, of course. -- [[ulrik]]
+
+[dml]: http://thread.gmane.org/gmane.text.docutils.user/5376
+

 Some rst-custom [examples are here](http://kaizer.se/wiki/rst_examples/)
 
 [rst-custom]: http://github.com/engla/ikiwiki/commits/rst-customize
 Some rst-custom [examples are here](http://kaizer.se/wiki/rst_examples/)
 
 [rst-custom]: http://github.com/engla/ikiwiki/commits/rst-customize


@@ -141,9 +163,23 @@ picture before it.
 >> use more rst-like syntax (and documents degrades better outside the wiki as
 >> noted).
 >>
 >> use more rst-like syntax (and documents degrades better outside the wiki as
 >> noted).
 >>

->> The named link syntax (just like the :wiki: role) are inspired from trac
->> and a good fit, but only if the wiki is committed to using only rst,
->> which I don't think is the case.
+>>> Unsure about the degredation argument. It will work some of
+>>> the time, but ikiwiki's [[ikiwiki/subpage/linkingrules]]
+>>> are sufficiently different from normal html relative link
+>>> rules that it often won't work. --[[Joey]]
+>>>
+>>>> With degradation I mean that if you take a file out of the wiki; the
+>>>> links degrade to stylized text. If using default role, they degrade to
+>>>> :title: which renders italicized text (which I find is exactly
+>>>> appropriate). There is no way for them to degrade into links, except of
+>>>> course if you reimplement the :wiki: role. You can also respecify
+>>>> either the default role (the `wikilink` syntax) or the :wiki: role (the
+>>>> :wiki:`wikilink` syntax) to any other markup, for example None.
+>>>> --[[ulrik]]
+>> 
+>> The named link syntax (just like the :wiki: role) are inspired from
+>> [trac][tracrst] and a good fit, but only if the wiki is committed to
+>> using only rst, which I don't think is the case.

 >>
 >> The rst-customize changes are very useful for custom directive
 >> installations (like the sourcecode directive, or shortcut roles I show
 >>
 >> The rst-customize changes are very useful for custom directive
 >> installations (like the sourcecode directive, or shortcut roles I show


@@ -165,9 +201,11 @@ picture before it.
 >> other phases? rst must be before any preprocess hook to avoid seeing any
 >> HTML.
 >>
 >> other phases? rst must be before any preprocess hook to avoid seeing any
 >> HTML.
 >>

->> With the presented changes, I already have a working RestructuredText
->> wiki, but I'm admitting that using .. raw:: html around all directives is
->> very ugly (I use few directives: inline, toggle, meta, tag, map)
+>>> One of my long term goals is to refactor all the code in ikiwiki
+>>> that manually runs the various stages of the render pipeline,
+>>> into one centralized place. Once that's done, that place can get
+>>> smart about what order to run the stages, and use a different
+>>> order for rst. --[[Joey]]

 >>
 >> If I'm thinking right, processing to HTML already in filter means any
 >> processing in scan can be reused directly (or skipped if it's legal to
 >>
 >> If I'm thinking right, processing to HTML already in filter means any
 >> processing in scan can be reused directly (or skipped if it's legal to


@@ -175,6 +213,14 @@ picture before it.
 >>
 >> -- [[ulrik]] 
 
 >>
 >> -- [[ulrik]] 
 

+>>> Seems it could be, yes. --[[Joey]]
+>>>
+>>>> It is not clear how we can work around reST wrapping directives with
+>>>> paragraph tags. Also, some escaping of xml characters & <> might
+>>>> happen, but I can't imagine right now what breakage can come from that.
+>>>> -- [[ulrik]]
+
+[tracrst]: http://trac.edgewall.org/wiki/WikiRestructuredText

 
 ### Implementation ###
 
 
 ### Implementation ###
 


@@ -215,10 +261,27 @@ Perl I've ever written!_)
 >> Well, no idea how that would be expressed, but I mean, replace the indent
 >> directly in $handle's return value.
 >>
 >> Well, no idea how that would be expressed, but I mean, replace the indent
 >> directly in $handle's return value.
 >>

+>>> Yes, in effect just `indent($1, handle->($2,$,4))` --[[Joey]] 
+>>

 >> The indent-catching regex is wrong in the way you mention, it has been
 >> nagigng my mind a bit as well; I think matching start of line + spaces
 >> and tabs is the only thing we want.
 >> -- [[ulrik]]
 >> The indent-catching regex is wrong in the way you mention, it has been
 >> nagigng my mind a bit as well; I think matching start of line + spaces
 >> and tabs is the only thing we want.
 >> -- [[ulrik]]

+>> 
+>>> Well, seems you want to match the indent at the start of the line containing
+>>> the directive, even if the directive does not start the line. That would
+>>> be quite hard to make a regexp do, though. --[[Joey]]
+>>
+>> I wasted a long time getting the simpler `indent($1, handle->($2,$,4))` to
+>> work (remember, I don't know perl at all). Somehow `$1` does not arrive, I
+>> made a simple testcase that worked, and I conclude something inside $handle
+>> results in the value of $1 not arriving as it should!
+>>
+>> Anyway, instead a very simple incremental patch is in [pproc-indent][ppi]
+>> where the indentation regex is `(^[ \t]+|)` instead, which seems to work
+>> very well (and the regex is multiline now as well). I'm happy to rebase the
+>> changes if you want or you can just squash the four patches 1+3 => 1+1
+>> -- [[ulrik]]

 
 [ppi]: http://github.com/engla/ikiwiki/commits/pproc-indent
 
 
 [ppi]: http://github.com/engla/ikiwiki/commits/pproc-indent
 


@@ -259,3 +322,12 @@ The page is rST-parsed once in 'scan' and once in 'htmlize' (the first to genera
 >> 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
 
 >> 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
 

+-----
+
+Another possiblity is using empty url for wikilinks (gitit uses this approach), for example:
+
+    `SomePage <>`_
+
+Since it uses *empty* url, I would like to call it *proposal 0* :-)  --[weakish]
+
+[weakish]: http://weakish.pigro.net