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

[David Goodger]

[Simon]
>>> Also for my personal homepage as mentioned at the beginning of the
>>> Mail I am pretty picky, since graphical stuff has a pretty high
>>> priority in my life...

[David]
>> But there are no graphics in plaintext.  You're asking for too much.
>> Either the plaintext is at least equally as important as the HTML (in
>> which case they ought to look as similar as possible, precluding
>> inline URLs that aren't displayed in the HTML), or the HTML is more
>> important (in which case you're the only one who will ever read the
>> plaintext).  I suspect the latter.

[Aahz]
> Enh.  I disagree with this line of reasoning.  Where I'm coming from is
> wanting to use reST to save writing time for structured documents;
> nobody but me will use the plaintext.  I do agree that graphics are
> beside the point for reST, but that's because of the emphasis on
> *structure*.  To the extent that graphics are part of a structured
> design, I think reST should support them (and already does, I think).

I think there's some misunderstanding here (perhaps on my part).  Yes,
reStructuredText already supports graphics, using an explicit directive
mechanism.  All I'm saying is that there are no graphics *embedded* in the
plaintext file itself, *when you're editing it*.  In other words, you don't
see the images within the text in Emacs; no cut & paste from GIMP.
reStructuredText is *not* about graphic layout.  I understood Simon to be
saying that he wants the reader convenience/usability of HTML in
reStructuredText with regards to external references (URLs), and images are
simply one form of external reference.

It comes down to this: the top goal of reStructuredText is to be as readable
in plaintext (source) form as in processed form.  An important market for
this is (will be) Python docstrings.  You and Simon seem not so interested
in the plaintext readability issue; it's the processed output which is most
important.  If reStructuredText works for that, great, but we're not going
to make significant alterations for the output-centric market if those
changes adversely affect the "plaintext as readable as processed" market.  I
believe that the "reference_(url)" proposed syntax would adversely affect
the plaintext readability of reStructuredText.

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