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

[Luc Saffre]

Thank you, David.

I agree that a syntax change is something to avoid if possible, and you 
mentioned two alternatives:

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

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

Idea 2 : what about  `Python expression`!_ or something similar? The 
python expression would not be allowed to contain backticks, but imho 
that's not a big problem. Problem could rather be that a text like "She 
shouted "_No!_" and ran away." must not be processed this way. The rule 
would be that something which ends with "!_" and does not start with "_" 
is to be considered a Python expression to evaluate.

   Return to `url("index", "Main page")`!_.

or::

   See file `fileref("src/lino/__init__.py")`!_ for details.


I hope for some feedback about these ideas.

Luc Saffre


On 20/11/2003 4:55, David Goodger wrote:

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