[Doc-SIG] Colons and footnotes (was RE: reST Wiki mode, was [Doc-SIG] Suggestions for reST "modes")

[David Goodger]

[Garth]
> ... remind me: I think we should make footnote identifiers
> (excepting the square brackets) implicit hyperlink targets in their
> own right.

On rereading, this does seem like a good idea. Then ``.. _[1]
footnote`` becomes the equivalent of::

    .. _1:

    [1] footnote

(The above lacks the <footnote> semantics, of course.)

The "namespace" for footnotes and hyperlinks is already one and the
same, but footnotes keep their brackets now; this change would simply
drop the brackets. The footnote reference, ``[1]_``, and hyperlink,
``1_``, would both refer to the same thing, but their representation
may be different. I don't think there will be many conflicts, since
footnotes are often numbered and must be short.

[Tony, on using colons with footnotes]
> *My* reason for suggesting using them was, however, entirely
> orthogonal, and was simply that it is one less thing to remember, if
> *all* hyperlink targets start with ``.. _`` and end with ``:``.

I don't want to insert ':' after the footnote label.
Footnotes are visible after processing, therefore I'd like the input
and output to correspond as much as possible. Hyperlink targets are
not (typically) visible after processing, so their syntax doesn't
matter.

The notion of ':' as "mapping" is important here. Remember that and
you won't (a) mistakenly put the ':' on a footnote, (b) forget to put
':' on a hyperlink target, or (c) mistakenly put note text on a
hyperlink target. ``.. _external: URI`` means, "when you see
``external_``, link to URI". ``.. _internal:`` (followed by a blank
line) means, "when you see ``internal_``, link to *here*". Maybe we
should change the ':' to '=', in order to emphasize the nature of the
mapping going on::

    .. _target=URI

Perhaps, to make footnotes even more distinct from hyperlink targets,
we can drop the leading '_' too. Then a footnote would look like this::

    .. [1] footnote

We'd lose a little bit of consistency (the reference, ``[1]_``,
would have to keep its trailing underscore), but the visual
correspondence (before and after processing) would be better, and the
hyperlink target would no longer be explicit.

> Now,this is convenience for the author, so not necessarily our
> preeminent goal, but two of us at least keep typing the things and
> then having to remenber to remove them (so, two out of a
> scientifically selected sample of, erm, how many...).

Just because you can't remember colons are *not* necessary doesn't
mean they *are*! ;-)

[Tony]
> So the issue is:
> 
>     Do we want different sorts of hyperlink to occupy
>     different namespaces, or the same namespace.

Good summary of the issues.

The footnote references and hyperlinks were already sharing a
namespace in the parser, but the footnote refs kept their brackets,
making hyperlink references messy. I'm leaning toward merging them
completely.

Let me sleep on it, think about it over the weekend.

-- 
David Goodger    dgoodger@bigfoot.com    Open-source projects:
 - Python Docstring Processing System: http://docstring.sourceforge.net
 - reStructuredText: http://structuredtext.sourceforge.net
 - The Go Tools Project: http://gotools.sourceforge.net