[Doc-SIG] auto-numbered footnotes

[David Goodger]

Garth T Kidd <garth@deadlybloodyserious.com> wrote on 2001-08-09 9:58 PM:
> * Let's say we want to use non-URI link targets as automatically
>   numbered footnotes, which I think is pretty nifty. Explicitly
>   named footnotes are still perfect_ for citing references, but
>   authors are freed from the tyranny of having to avoid footnote
>   number collisions.
> 
>   .. perfect: Perfection is great! And, since this link target
>      doesn't have anything resembling a URI in it, it's an auto
>      numbered footnote, right?

Wrong! Too ambiguous.

For auto-numbered footnotes, how about something like::

    Auto-numbered footnote ref: []_.

    .. _[] Here's the footnote. Of course, the order is all-important
       here. However, it's impossible to refer to this footnote a
       second time.

Or we could define a new syntax variant::

    Auto-numbered footnote ref: [#name]_.

    .. _[#name] Here's the footnote. The order is no longer
       important. And, we can refer to this footnote as
       ``name_``.

The second idea seems to work well.

> * Therefore, we need a way for applications to specify a resolver
>   function to the parser.

I *don't* think so.

[on indirect links]
> That would
> let me refer to a section called ``Extremely Long Heading``
> as ``ELH_`` as follows::
> 
>     See ELH_ for more details.
> 
>     .. _ELH: `Extremely Long Heading`_

I've thought these over, and I don't see them happening. If you need another
way to refer to a part of the current document, just put in another target::

    .. _ELH:

    Extremely Long Heading
    ======================
    ...

If it's to an external link, just duplicate the target::

    .. _link name number 1: http://somehost.somecompany.com
    .. _link1: http://somehost.somecompany.com

> + I'm still going on about indirect links, even though I suspect
> that they're already in the spec. I lack the time right now to
> wade through and check. Bueller?

Suspicions incorrect.

Don't be like Ferris; do your homework!

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