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

[Ken Manheimer]

On Fri, 12 Jul 2002, David Goodger wrote:

> Ken Manheimer wrote:

> > I really think the readability in this case is a judgement call, and
> > the author should have the opportunity to choose the style they
> > think is most appropriate for the situation.

> Noted.  But on the other hand, we can't cater to everyone's taste; the
> result would be an uncoordinated mess.  I'm torn on this issue.  The
> proposed syntax offers convenience, but I don't know if the
> convenience is worth the cost in ugliness.  Perhaps if the syntax is
> *allowed* but its use strongly *discouraged*, for aesthetic reasons?
> Or would that just be hypocritical?  Dilemma.

I'm also torn about this - we may have reached the same level of 
ambivalence, coming from opposite sides.-)  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.  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.

Earlier in the cited message:

> Using the embedded variation of inline external targets (#4 in the
> "summary" post), it would look like this::
>       
>     You can find more info about life `here
>     <http://www.example.com/first>`__ and `here
>     <http://www.example.com/second>`__

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 think it is pretty natural for people to put URLs in parens this way, in
regular text.  The act of deciding between making it appear in the HTML as
a reference link or just some text followed by an explicit link in parens
is practically just adding the '_' underscore.  (At least for the single
word case - there's the backticks for the multiple word case, but the
spirit is the same.)  I think it is exceptionallly intuitively obvious,
and actually like how it looks (which i can't say about #4 syntax above).

Like i said, i'm also torn about this.  The here_(link) syntax seems so
unobjectionable to me that it make it easy for me to lean to the dark side
(possibly extraneous syntax), but i lost track of the objections, so may
well be missing something crucial...

-- 
Ken
klm@zope.com