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

Luc Saffre luc.saffre at gmx.net
Wed Nov 19 18:21:17 EST 2003


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::


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


- 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:

More information about the Doc-SIG mailing list