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

[Luc Saffre]

David,

yes, custom URI schemes that trigger internal behavior would enable me 
to write a solution for the "fileref" problem.

And I agree with you that an 'exec' (or 'python') directive should not 
be integrated into standard reStructuredText for security reasons.  This 
is no problem for me or WebMan, since WebMan can declare its own 
directive (as done in 
http://cvs.sourceforge.net/viewcvs.py/lino/lino/src/lino/webman/xdocutils.py?view=markup)

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.  It would also make custom URI 
schemes unnecessary.

Your problem was that the `[cmd param1...paramN]` syntax seems fragile. 
Okay, we could require an underscore after the "]" and say that commands 
are a special case of citation references: if the label starts with "=", 
then its not a citation reference but a command.

Consider also that this "feature" can be disabled in standard rst as 
long as there is no declared command.  It is just an extension slot for 
tools as WebMan. Maybe there are authors who wrote reStructured texts 
containing citations whose labels start with "=".

It's true that WebMan would create its own dialect of "extended rst", 
making webman files unreadable by standard docutils tools. But this is 
WebMan's problem, not your's.

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 did not yet find time to study the parser's code in order to check how 
expensive my idea would be. But in any case I hope for your blessing 
before diving into this project.

Luc


On 21/11/2003 8:01, David Goodger wrote:

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