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

[David Goodger]

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

[David]
>> 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
>>        }

[fantasai] 
> You would only have to do that in very rare cases: a relative url
> with an @ sign. Absolute urls must specify a scheme followed by a
> colon. Colons aren't allowed in mail addresses, so the email parsing
> regex wouldn't pick them up even if you left out the spaces.

Exceptions like that make the rules very hard to remember.  Curly
braces, with or without spaces, are out.

>> 2. Curly braces are very similar to parentheses, which cannot be
>>    used because they're too common in text.
> 
> Can you give me an example? I don't remember the last time I saw
> curly braces in non-mathmematical text.

I'm saying that "(parenthesized text)" is very common in ordinary
text, and "{curly braces}" look just like them.  A weak argument, to
be sure.  In any case, curly braces will not be accepted.

> > 3. There's overwhelming precedent for angle brackets with URLs.
> ..
> > Angle brackets are familiar, standard URI delimiters.  Much better
> > than curly braces.
> 
> Certainly, I agree, but as you said, they are already taken for SGML
> notation. And this workaround:
> 
>    `inline hyperlink`__ __<uri>
> 
> Looks horrendous. If your goal is unobtrusive, that syntax fails
> miserably. Seven consecutive punctuation characters--really, it's
> not necessary.

My goal for this syntax is not "unobtrusive", it's "unambiguous" and
"unsurprising".  This is one of the "Less common constructs, for
which there is no natural or obvious markup," and therefore it "should
be distinctive" (quotes from the "unobtrusive" goal).

Please remember, I'm not convinced this syntax is a good idea.  In
fact, I still think it's probably a bad idea.  I'm only allowing an
experimental extension via a pragma directive, to see how it fares in
the wild, and to try to keep an open mind.  I'm reserving the right to
rip it out if it proves unsuccessful.  This may sound all
high-and-mighty, but I've got the unenviable responsibility of being
in the position of making the final decisions.  I have to try to keep
the syntax as consistent and elegant as possible.  Although you and
Simon might think it's a brilliant idea, I've got to look at the big
picture.  That means saying "no" sometimes; tough.

> Alternatives:
> 
> a. This sentence contains an `inline hyperlink` {uri} which will
>    direct you to some other resource.

It's never going to happen.  Please drop it.

> b. This sentence contains an `inline hyperlink` __<uri> which will
>    direct you to some other resource.

You've dropped the trailing underscores from the reference, turning it
into interpreted text.  No good.  Same in all of these alternatives;
I'll pretend they're all spelled "`inline hyperlink`__".

> c. This sentence contains an `inline hyperlink` <"uri"> which will
>    direct you to some other resource.

Why do we need quotation marks?  To distinguish from HTML/SGML/XML
tags?  At least the underscores have precedent.  And see (b).

> d. This sentence contains an `inline hyperlink` >uri> which will
>    direct you to some other resource.

Not in my lifetime.

> e. This sentence contains an `inline hyperlink` ^<uri> which will
>    direct you to some other resource.

Yuck.

> f. This sentence contains an `inline hyperlink` [>uri] which will
>    direct you to some other resource.

Double-yuck.

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