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

[David Goodger]

Luc Saffre wrote:
> Thank you, David.

You're welcome.

 > - Substitutions : are not a candidate for my problem because there
 > is no possibility to specify parameters.

Perhaps not.  Not directly anyhow.  Did you look at the proposal at
<http://docutils.sf.net/spec/notes.html#adaptable-file-extensions>?

 > - Some variation on the existing "`reference`_" or "`reference
 > <URL>`_" syntax... : This seems promising!
 >
 > Idea 1 : provide a possibility to declare a function that decides
 > what to do with URLs. The parser would call this function each time
 > that it found an URL. The default function would do the same as what
 > is done now. A framework-defined function would call the default
 > function if the URL is a normal one, but if it starts with a keyword
 > (for example "lref:" instead of the normal "http:") then it would
 > apply its own processing (and return a list of nodes, I guess). Then
 > I could write::
 >
 >   Return to `Main page <lref:index>`_.
 >
 > or::
 >
 >   See file `__init__.py <fileref:src/lino/__init.py>`_ for details.

Interesting idea: custom URI schemes that trigger internal behavior.
We'd have to be careful not to duplicate any existing schemes (see
docutils/urischemes.py); perhaps a custom scheme syntax that cannot
conflict with public schemes (i.e., an invalid URI syntax)?  The
syntax for URI schemes (from RFC 2396) is::

     scheme        = alpha *( alpha | digit | "+" | "-" | "." )

Perhaps a role-like syntax would suffice?  I don't think this is valid
URI syntax::

     Return to `Main page <:lref:index>`_.

 > Idea 2 : what about  `Python expression`!_ or something similar?

There is a proposal for an "exec" directive at
<http://docutils.sf.net/spec/notes.html#misc-exec>, followed by
"system" and "eval".  All of these are potentially dangerous, which is
one reason they haven't been implemented up to now.  The notes file
has some ideas for reducing the danger.  But do we want to leave the
door open to potentially malicious *documents*?  Alternatively, it
ought to be easy to use one of the many templating systems with
reStructuredText files, chained together with Docutils.

In general, for text that isn't directly part of the document I'd much
rather use substitutions rather than adding inline syntax, to keep the
non-textual details outside of the text.  Python expressions can be
quite readable, but still, only to a programmer.  Not to a
non-technical writer.

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