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

[David Goodger]

[David Goodger]
>> 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).

[fantasai]
> Why would accepting curly braces in an email address preclude using
> them to delimit a URI?

Because the parsing would be ambiguous.  Even if we could work around
the corner cases, the code/regexp would be nightmarish.

> I think this:
>     `inline hyperlink` { uri_with@weird,symbols }
> looks much better than this:
>     `inline hyperlink`__ __<uri_with@weird,symbols>

I disagree, for several reasons:

1. Using whitespace like that is a kluge.  Line-wrap the text and you
   could end up with::

       `inline hyperlink`_ {
       uri_with@weird,symbols
       }

   Not pretty.

2. Curly braces are very similar to parentheses, which cannot be used
   because they're too common in text.

3. There's overwhelming precedent for angle brackets with URLs.  From
   RFC 2396 (URI syntax):

       The angle-bracket "<" and ">" and double-quote (") characters
       are excluded [from URIs] because they are often used as the
       delimiters around URI in text documents and protocol fields.

       Using <> angle brackets around each URI is especially
       recommended as a delimiting style for URI that contain
       whitespace.

   From RFC 822 (email headers):

       Angle brackets ("<" and ">") are generally used to indicate the
       presence of a one machine-usable reference (e.g., delimiting
       mailboxes), possibly including source-routing to the machine.

   Also, see my signature block.

Angle brackets are familiar, standard URI delimiters.  Much better
than curly braces.

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