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

[David Goodger]

Ken Manheimer wrote:
> One point i'd make about "discouraging for aesthetic reasons" - you
> could consider that people's choosing to use it or not _conveys_
> their aesthetic judgement.

It's not *their* aesthetic judgement I'm worried about, it's *mine*.
I've got to look at the big picture.  In designing this markup, I'm
saying to the world, "This is my best effort; this is what I think
strikes the best balance between readability, practicality,
functionality, etc."  Of course I'm extremely grateful for input from
everyone participating, but -- like Guido with Python -- the buck
stops here.

My "spider sense" is still tingling on this issue.

> The concern i see is having the extraneous syntax if peopl choose
> not to use it, getting in the way of people finding and learning the
> things they do want to use.

Thus my idea of hiding it as an explicitly activated extension.  That
doesn't help the poor sap who has to *read* the plaintext though.

> I've lost track of the summary post, and i apologize if good reasons
> for dismissing this alternative have already been covered:
> 
>   here_(http://www.python.org) or `sometimes
>   here`_(http://www.zope.org),

I took Wednesday's "Summary of reference/target syntaxes" Doc-SIG
post, added references and excerpts from discussions to date, and
added it to "A Record of reStructuredText Syntax Alternatives".  The
main objection with ``"`reference`_(target)"`` was the unprecedented
"infix" syntax (significant syntax *in the middle* of the construct).
I won't repeat it all here; please take a look:
http://docutils.sf.net/spec/rst/alternatives.html#inline-external-targets
Simon's original syntax (``"reference_(target)"``) is alternative 1,
the split compromise (``"reference__ __<target>"``) is alternative 2,
and the embedded syntax (``"`reference <target>`__"``) is alternative
3.  I currently consider #3 to be the least objectionable.

> I think it is pretty natural for people to put URLs in parens this
> way, in regular text.

Agreed, if you're saying "See the Python homepage
(http://www.python.org)".  But if the URL is meant to be hidden (an
active link), or if it's a two-line monstrosity, it makes the
plaintext painfully hard to read.

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