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

[David Goodger]

Simon Budig wrote:
> This essentially boils down to "Ok, named links are hard to use, so
> we introduced anonymous links. They are hard to maintain too, but a
> little less."

I'd say that hyperlinks are hard to mark up, period.  You can't have a
markup that is simultaneously readable, unobtrusive, easy,
maintainable, and URLs-close-to-the-reference-text.  You have to
choose some aspect as most important; and you have to give up
something. reStructuredText chose "readable" and "unobtrusive" as the
most important aspects.

> So to use links in reST I have the choice between two evil things:
> 1) make sure that Link targets and Link text are absolutely the same
> 2) count "__"s.
>
> This is exactly why I proposed a third solution  :-)
...
> I'd think this is a good thing...

IMO, the solution is worse than the problem.

But I'm not interested in debating this point *ad nauseum* (and it
is).  I've already written a bunch of replies to yesterday's posts,
but I think it's better to deep-six them.  This is getting old, real
fast.

Our positions can be summed up with:

> Ok, we seem to disagree here fundamentally. I personally think that
> the proposed syntax is readable, you think it isn't. Not sure how to
> solve this...

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

    Ordinary text ...

    A paragraph containing an `inline
    hyperlink`_(http://www.example.org/).

However, I really don't like that syntax; it doesn't make sense.
Let's examine it and see if we can come up with something better.  I
have two objections:

1. The "`ref`_(URL)" syntax forces the last word of the reference text
   to be joined to the URL, making a potentially very long word that
   can't be wrapped (URLs can be very long).  The reference and the
   URL should be separate.

2. The "inline hyperlink" text is *not* a named reference (there's no
   lookup by name), so it shouldn't look like one.

Instead, use the anonymous double-underscore syntax.  Perhaps a
matching double-underscore "anonymous inline target" syntax for the
URL as well?  A space in-between would separate the reference from the
target and allow words to wrap.  For example::

    A paragraph containing an `inline
    hyperlink`__ __`http://www.example.org/`.

Yes, that's much better.  A bit more verbose, but it fits better with
the rest of the syntax.  If you insist on parentheses, then some
compromise may do.  Perhaps::

    A paragraph containing an `inline
    hyperlink`__ __(http://www.example.org/).

However, looking at the URI-recognition code (based on the IETF
standards RFC 2396 and RFC 2732), parentheses are legal URI
characters.  This would introduce ambiguity (a legal URI containing
parentheses wouldn't be recognized properly).  Curly braces and
backquotes are not legal URI characters, but they *are* legal email
characters (see RFC 822).  It's not easy to come up with a completely
unambiguous syntax!  The only useful characters that are neither URI
characters nor email characters are angle brackets, "<>".  So the
syntax becomes::

    A paragraph containing an `inline
    hyperlink`__ __<http://www.example.org/>.

Which actually doesn't look too bad.  There's precedent in using angle
brackets for URIs.  Coming full circle, perhaps we can now drop the
leading "__"::

    A paragraph containing an `inline
    hyperlink`__ <http://www.example.org/>.

Ah, but then it would be difficult to write about HTML/XML/SGML tags
("img" in "the <img> tag" would be parsed as a relative URL).  We
*could* recognize inline URLs only immediately after anonymous
references, but that would require keeping track of state.  So the
leading "__" *is* required.

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.

-- 
David Goodger  <goodger@users.sourceforge.net>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/