Resolve native reStructuredText links to ikiwiki pages

1 files changed, 124 insertions, 0 deletions

diff --git a/doc/todo/Resolve_native_reStructuredText_links_to_ikiwiki_pages.mdwn b/doc/todo/Resolve_native_reStructuredText_links_to_ikiwiki_pages.mdwn
new file mode 100644
index 000000000..c90261dc3
--- /dev/null
+++ b/doc/todo/Resolve_native_reStructuredText_links_to_ikiwiki_pages.mdwn
@@ -0,0 +1,124 @@
+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:
+
+Right now it changes rendering so that undefined pages (previous errors) are resolved to either ikiwiki pages or link to "#". It could be changed (trivially) so that undefined pages give the same error as before. Since it only resolves links that would previously error out, impact on current installations should be minimal.
+
+I don't know why backlinks don't show up with the patch as it is; they are registered, but not rendered on the linked-to page.
+
+Desing issues in general:
+
+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.
+
+Many other issues with rST are of course unresolved, but some might be solved by implementing custom rST directives (which is a supported extension mechanism).
+
+Patch follows:
+
+----
+<pre>
+	From 486fd79e520da1d462f00f40e7a90ab07e9c6fdf Mon Sep 17 00:00:00 2001
+	From: Ulrik Sverdrup <ulrik.sverdrup@gmail.com>
+	Date: Thu, 17 Sep 2009 15:18:50 +0200
+	Subject: [PATCH] rst: Resolve native reStructuredText links to ikiwiki pages
+
+	Links in rST use syntax `Like This`_ or OneWordLink_, and are
+	generally used for relative or absolue links, with an auxiliary
+	definition:
+
+	.. _`Like This`: http://ikiwiki.info
+	.. _OneWordLink: relative
+
+	We can hook into docutils to resolve unresolved links so that rST
+	links without definition can be resolved to wiki pages. This enables
+	WikiLink_ to link to [[WikiLink]] (if no .. _WikiLink is specified).
+
+	Comparing to Ikiwiki's wikilinks
+
+	[[blogging|blog]] specifies a link to the page blog, with the name
+	blogging. In rST we should use blogging_
+
+	.. _blogging: blog
+
+	*However*, note that this patch does not hook into this. What we
+	resolve in this patch is finding the appropriate "_blogging" if it is
+	not found, not resolving the address 'blog'.
+	---
+	 plugins/rst |   46 +++++++++++++++++++++++++++++++++++++++++-----
+	 1 files changed, 41 insertions(+), 5 deletions(-)
+
+	diff --git a/plugins/rst b/plugins/rst
+	index a2d07eb..a74baa8 100755
+	--- a/plugins/rst
+	+++ b/plugins/rst
+	@@ -6,22 +6,58 @@
+	 # based a little bit on rst.pm by Sergio Talens-Oliag, but only a little bit. :)
+	 #
+	 # Copyright © martin f. krafft <madduck@madduck.net>
+	+# Copyright © Ulrik Sverdrup <ulrik.sverdrup@gmail.com>, 2009
+	+#
+	 # Released under the terms of the GNU GPL version 2
+	 #
+	+
+	 __name__ = 'rst'
+	 __description__ = 'xml-rpc-based ikiwiki plugin to process RST files'
+	-__version__ = '0.3'
+	+__version__ = '0.3+'
+	 __author__ = 'martin f. krafft <madduck@madduck.net>'
+	 __copyright__ = 'Copyright © ' + __author__
+	 __licence__ = 'GPLv2'
+	 
+	 from docutils.core import publish_parts;
+	+from docutils.writers import html4css1
+	 from proxy import IkiWikiProcedureProxy
+	 
+	-def rst2html(proxy, *kwargs):
+	-    # FIXME arguments should be treated as a hash, the order could change
+	-    # at any time and break this.
+	-    parts = publish_parts(kwargs[3], writer_name='html',
+	+class IkiwikiWriter(html4css1.Writer):
+	+    def resolve_node(self, node):
+	+        refname = node.get('refname', None)
+	+        if not refname:
+	+            return False
+	+
+	+        bestlink = self.proxy.rpc('bestlink', self.page, refname)
+	+
+	+        node.resolved = 1
+	+        node['class'] = 'wiki'
+	+        del node['refname']
+	+
+	+        if not bestlink:
+	+            rel_url = "#"
+	+        else:
+	+            rel_url = self.proxy.rpc('urlto', bestlink, self.page)
+	+            self.proxy.rpc('add_link', self.page, bestlink)
+	+        node['refuri'] = rel_url
+	+        self.proxy.rpc('debug', "Emitting link %s => %s" % (refname, rel_url))
+	+        return True
+	+
+	+    resolve_node.priority = 1
+	+
+	+    def __init__(self, proxy, page):
+	+        html4css1.Writer.__init__(self)
+	+        self.proxy = proxy
+	+        self.page = page
+	+        self.unknown_reference_resolvers = (self.resolve_node, )
+	+
+	+def rst2html(proxy, *args):
+	+    # args is a list paired by key, value, so we turn it into a dict
+	+    kwargs = dict((k, v) for k, v in zip(*[iter(args)]*2))
+	+    page = kwargs['page']
+	+
+	+    parts = publish_parts(kwargs['content'],
+	+                          writer=IkiwikiWriter(proxy, page),
+	                           settings_overrides = { 'halt_level': 6
+	                                                , 'file_insertion_enabled': 0
+	                                                , 'raw_enabled': 1
+	-- 
+	1.6.4
+
+</pre>
+----