[Doc-SIG] Reworking Explicit Markup

[Tony J Ibbs (Tibs)]

David doing his good work as normal, so not much to say (erm, when did
that stop me?)

The interesting bit of this email is at `the end`_ - in summary, I'm +1
for David's proposed syntax, number 5 (sorry, they've been replaying
Hitchhikers' Guide to the Galaxy on the radio recently over her, and I
wouldn't want to keep anyone in needless suspense).

David noted that he used "#" in anonymous footnotes because of the
connotation of "number" - hah, I'm on the wrong continent again, I
hadn't quite gotten that (pronouncing it "hash" probably doesn't help).
OK, for a sizable constituency it will have that direct connotation, I
can understand that.

I'm less sanguine than he about the ease of remembering what can't go at
the beginning of a comment, although I suppose "magic" allows::

   .. Remember: http://www.python.org/ is a really neat site.

to be a comment because of the trailing text? But not a great worry -
comments are secondary, and we already had this discussion.

Trivial note: there's an alternative 6 which follows on immediately (as
does alternative 5) from a comment in alternative 1:

> 1. Original syntax::
>    Disadvantages:
>    - Anonymous target markup is awkward: ".. __:".

so the "obvious" thing to do is drop the "__", giving ".. :".
Unfortunately, this has no great advantage, whilst losing the "_" link
connotation, and it *looks* odd (I suspect Alan's users would prefer
something without a space embedded in the middle!).

.. _the end:

> 5. David Goodger's proposed syntax: Perhaps going back to one of
>    Alan's earlier suggestions might be the best solution. How about
>    simply adding "__ " as a synonym for ".. __: "? These would become
>    equivalent::
>
>        .. __: http://somewhere
>
>        __ http://somewhere
>
>    Would that be sufficient, with no other syntax changes?

So one might type::

    Useful languages for this purpose include Tcl__,
    Python_, Perl__ and Sather__ - but irrespective
    of practicality, Python_ will always be my first
    love.

    __ http://www.sometcl.resource/
    .. _python: http://www.python.org/
    __ http://www.perl.org/
    __ http://www.sather.org/

Yes, I could see that working "visually". Decent error messages when one
types "__" instead of "_" (and vice versa) will help, but I trust us (!)
to do that. Could one could also do::

    Useful languages for this purpose include Tcl__,
    Python__, Perl__ and Sather__ - but irrespective
    of practicality, Python_ will always be my first
    love.

    __ http://www.sometcl.resource/
    .. _python:
    __ http://www.python.org/
    __ http://www.perl.org/
    __ http://www.sather.org/

as an alternative?

Anyway, consider me a +1 on this idea, at least for the moment.

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
"Bounce with the bunny. Strut with the duck.
 Spin with the chickens now - CLUCK CLUCK CLUCK!"
BARNYARD DANCE! by Sandra Boynton
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)