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

[David Goodger]

Luc Saffre wrote:
 > 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`.

This issue has come up before.  A summary of the last idea is at
<http://docutils.sf.net/spec/notes.html#adaptable-file-extensions>.

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

I'd rather not add syntax unless absolutely necessary.  If the earlier
idea isn't sufficient, perhaps some variation on the existing
"`reference`_" or "`reference <URL>`_" syntax?

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

It seems fragile to me.  [Brackets] are very commonly used in ordinary
text, and even more so in technical text.

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

There's another old idea related to this:
<http://docutils.sf.net/spec/notes.html#targets-in-other-documents>.

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

That concept is what "substitutions" are now.  The directive
parameters are outside of the text, which I consider a major advantage
to readability.

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

First, study the spec
(http://docutils.sf.net/spec/rst/reStructuredText.html) and the parser
code (overview starts in docutils/parsers/rst/__init__.py's module
docstring).  Next, ask some specific questions.  Let's firm up the
proposal first though.

-- 
David Goodger    http://starship.python.net/~goodger
For hire: http://starship.python.net/~goodger/cv
Docutils: http://docutils.sourceforge.net/
(includes reStructuredText: http://docutils.sf.net/rst.html)