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

[David Goodger]

Luc Saffre wrote:
 > But I would like to come back to my original idea of "commands".
 > After all these discussions I still believe that this would be an
 > elegant extension slot for reStructuredText.

I am unconvinced of the necessity (see below).

 > It would also make custom URI schemes unnecessary.

My suggestion of custom URI schemes was to avoid or minimize any new
syntax.  A small tweak to an existing construct is easier to accept
than a whole new construct.

 > Consider also that commands would enhance readability for specific
 > contexts::
 >
 >   Don't execute [=fileref /setup.py]_ because it does not work yet.
 >
 > is much more readable than::
 >
 >   Don't execute `setup.py <:fileref:/setup.py>`_ because it does
 >   not work yet.

I would write it either using substitutions and a directive::

     Don't execute |setup.py| because it does not work yet.

     .. |setup.py| fileref:: /setup.py

Or using interpreted text roles::

     Don't execute :fileref:`setup.py` because it does not work yet.

Directives and roles are Docutils' extension mechanisms.  Before
adding another mechanism, I'd like to see an example that clearly
isn't covered by the existing two.

 > I did not yet find time to study the parser's code in order to check
 > how expensive my idea would be.

The expense of implementing an idea in code is not so important.  The
cost to the markup itself is the important thing.  The idea and its
syntax must be necessary, non-redundant, and elegant.  I don't think
we're at that point yet.

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