[Doc-SIG] References in the same line as the target text

[Simon Budig]

David Goodger (goodger@users.sourceforge.net) wrote:
> You seem to feel inline URLs are important.  Here's a chance to prove
> your position.  I'll leave it up to you to implement them, on an
> experimental basis.  There is a proposed mechanism for experimental
> syntax called "pragma directives":
> 
>     It may also be possible for directives to be used as pragmas, to
>     modify the behavior of the parser, such as to experiment with
>     alternate syntax.  There is no parser support for this
>     functionality at present; if a reasonable need for pragma
>     directives is found, they may be supported.
> 
>     (http://docutils.sf.net/spec/rst/reStructuredText.html#directives)
> 
> I will help with the infrastructure (any changes that need to be made
> to the parser to accept pragma directives), but I won't implement the
> parsing itself.  Here's an example of how such a directive might
> work::
> 
>     .. enable-inline-urls::
 
[...]

>     A paragraph containing an `inline
>     hyperlink`__ __<http://www.example.org/>.
 
> Once the pragma directive is implemented, we'll see how it fares in
> the real world.  I may accept it into standard reStructuredText, leave
> it in as a pragma directive, or reject it outright.
>
> Your mission, Mr. Budig, if you choose to accept it, is to create an
> "enable-inline-urls" pragma directive that implements some variation
> of the above syntax (recommended: "__<URI>").  Except for necessary
> infrastructure support for pragmas, there should be no changes to the
> parser itself.  I will work with you to add support for pragmas.

I'd like to raise two points.

First I am not sure if the use of pragmas to change the behaviour is a
good way to do this. There might be a need for lots of different local
extensions to the syntax. You'd end up implementing lots of pragmas...

It might be better to have either a pragma that looks like::

   .. reST-options::
        :inline-urls: true
        :math-markup: true
        :whatever-id: "blah"

or something like this. So you could have a more generic framework for
extensions to the parser. reST could provide a mechanism to derive for
example class names from the first field and try to import and plug them
into the parser.

This would also make it easier to avoid having to type this pragma by
creating customized document processors where you would do something
like

parser.add_plugin (InlineUrlPlugin (1))


The second point is closely connected to this. When looking at Inline
markup the parsing work is done by a class "Inliner". This is dominated
by a huge regular expression that matches to a lot of different
constructs. In my eyes it would be better to break this apart in
different regular expressions and test them in a sequence (it might be
necessary to remember which match starts first). An extension could
add a regular expression to that list instead of having to replace a
complicated regular expression with an even more complicated regex.

Of course this would mean that there *would* be changes to the parser
itself, but it might result in a more flexible parsing framework.

Do you think this is worth it?

Bye,
        Simon

-- 
      Simon.Budig@unix-ag.org       http://www.home.unix-ag.org/simon/