[Doc-SIG] in-line hyperlinks

[Paul Moore]

David Goodger <goodger@python.org> writes:

> 1. `phrase reference <relative_url>`__
>
> 2. `phrase reference`->relative_url
>
> 3. `phrase reference`@relative_url
>
> 4. `phrase reference`__ @relative_url
>
> 5. `phrase reference`_@_relative_url
>
> 6. `phrase reference`__ ->relative_url
>
> 7. `phrase reference`__ __<relative_url>
>
> To me, syntax #1 is even more strongly in front with relative URLs.

I agree. And I think that looking only at absolute URLs gives a false
feeling of what is easily parsed (by human and/or computer). So I
appreciate your reminder that relative URLs need to be covered, too.

> CALL FOR OPINIONS: Please take a look at the implementation notes
> (http://docutils.sf.net/spec/notes.html#inline-external-targets) and
> tell us what you think.  The alternatives are: implement this as a
> general feature; require a global/pragma directive to enable it;
> require a local directive; or don't implement it at all.

My preference is for syntax #1 above. The only other one I find
readable is #2, but doesn't that count as "infix syntax", and hence
score badly, as mentioned in the implementation notes?

I've not got a very strong opinion on implementation - I have a vague
gut feeling that it should be either a general feature or not there at
all - it doesn't "feel like" a directive to me.

One other point. I think I lost track of the issue here. I *think*
that the need for inline targets is self-evident (David just used one,
above) [#]_. But the way David did it leaves both text and URL in the
processed text. Am I right in thinking that the proposal is purely for
a way of writing the *source* so that text and URL appear together,
whereas the *output* contains only the text, as a link to the target?
If so, my views above still stand, but I think it's a pretty minor
issue. (Then again, I don't think I'd ever use the construct in
practice - I spend most of my time when writing plain text, trying to
find a way of moving URLs *out of line*, so reST already has what I
want).

.. [#] Where he said::
       the implementation notes
       (http://docutils.sf.net/spec/notes.html#inline-external-targets)


> Just thought of a better name for this beast: "embedded targets".

How about simply "embedded links"?

Paul.

-- 
This signature intentionally left blank