[Doc-SIG] New concept of "commands"?
Luc Saffre
luc.saffre at gmx.net
Wed Nov 19 18:21:17 EST 2003
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/
More information about the Doc-SIG
mailing list