[Doc-SIG] New concept of "commands"?
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::
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?
Author of Lino:
More information about the Doc-SIG