[Doc-SIG] New concept of "commands"?

[Luc Saffre]

Hello,

there is a general problem with docutils: if you have a collection of
hyperlinked pages (for example a website), then the only possibility
to refer to other pages of your site is to hard-code the extension 
(usually `.html`) in the reStructuredText source. But if you hard-coded 
html links and then render your site in pdf (for example) then the 
intra-site links would also be broken since the other pages would have 
another extension than `.html`.

Solution could be to introduce a new docutils command, let's call it
"lref" (for "local reference"), whose syntax would be something like::

   [lref index Main Page]

and which would get expanded by the writer (or translator?) to::

   <a href="index.html">Main page</a>

when in static html mode, but to something else when in pdf mode. (I 
suppose that it is possible to link from one pdf file to another?)

The syntax `[cmd param1...paramN]` would be a new concept for
reStructuredText:  if a `[` is followed immediately by a recognized
command, then the parser collects the "parameters" (the remaining
text until the closing ']'), then it executes a function associated
with this command. The function should probably return a list of
parsed nodes (not to be parsed again).  If a `[` is not followed by any 
known command, then there is no special action.

Another example would be a `filref` command, to be used by authors
who often talk about individual files of a CVS tree::

     [fileref src/lino/__init__.py]

This could (now for both html or pdf) expand automatically to the 
following extra-site link::

   <a 
href="http://cvs.sourceforge.net/viewcvs.py/lino/lino/src/lino/__init__.py?rev=1.4&view=auto">src/lino/__init__.py</a>

In general, "commands" would be something similar to directives, but 
without requiring to be in a separate paragraph.


Questions:

- Am I missing something? Can my problem be solved without requiring a 
new syntax concept?

- Who can give me hints about how to implement this?


Luc Saffre
Author of Lino:
http://lino.sourceforge.net/