Doc-SIG

Download

doc-sig@python.org

November 2003

2 participants
1 discussions

New concept of "commands"?
by Luc Saffre Dec. 3, 2003

Dec. 3, 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.…">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/

2 7