[Doc-SIG] Reworking Footnotes

[David Goodger]

Thanks, Tony, for the excellent examples [*]_. Concrete examples
really help.

.. [*] I recently read Pratchett & Gaiman's *Good Omens*, which was
   moderately entertaining [*]_, so I know what you're talking about.

.. [*] (Just trying out the proposed symbol form here.)

   I cannot fully appreciate humorous fiction though; I much prefer
   real-time audio or video comedy. Perhaps it's due to how I read
   prose; there's a lack of what Steve Martin calls "Thai Ming" [*]_
   [*]_.

.. [*] Timing.

   Get it? :-D

.. [*] I'll add a note to the spec about the care that must be taken
   with the order of footnotes and references when footnote references
   are added inside footnotes. It's confusing; they can easily get out
   of sync.

I will implement the new "citation" and "citation_reference" elements
as discussed. I think they encapsulate a useful distinction from
footnotes.

[Tony]
> Thus, for the moment (and as always susceptable to argument), I'd say -1
> on the new form of footnote reference (i.e., I much prefer the existing
> ``[1]_`` over the proposed ``1_``), and ambivalent over the proposed
> target change.

[Paul]
> I think the current footnote syntax ``[1]_`` is *exactly* the right
> balance of distinctness vs unobtrusiveness. I very definitely don't
> think this should change.

I agree. The reference syntax will stay as is, and I'll let the target
syntax percolate through my ganglia for a while.

[Paul]
> _1. [2]_ Do What I Mean - is that a common term in Python
>     circles? I picked it up from Perl...

It exists in all computing circles, all the way down to the mythical ideal
CPU with a single instruction: "DWIM". Programs written for this CPU vary
only in length, if that. (A future version of this CPU will have a second
instruction: "NWIS" [Not What I Say]. Alas, it remains beyond current
technology.)

[Tony, on the "[1]" form and actual usage in email]
> Clearly [2]_ this is a form people are used to, and thus we should
> consider it strongly (in the same way that the usage of ``*..*`` to mean
> emphasis was taken partly from email practise).
> 
> Equally clearly, there is something "magical" for people in the use of a
> similar form (i.e., ``[1]``) for both footnote reference and footnote
> target - it seems natural to keep them similar.

Good points.

> I think that this established plaintext usage leads me to strongly
> believe we should retain square brackets at both ends of a footnote. The
> markup of the reference end (a single trailing underscore) seems about
> as minimal as we can get away with. The markup of the target end depends
> on how one envisages the thing - if ".." means "I am a target" (as I
> tend to see it), then that's good, but one can also argue that the
> "_[1]" syntax has a neat symmetry with the footnote reference itself, if
> one wishes (in which case ".." presumably means "hidden/special" as
> David seems to think, which is why one needs a ".." *and* a leading
> underline for hyperlink targets [3]_.

Also good points, and a good summary of the thinking process that has
resulted in the current syntax. It's the art of balancing -- nay, of
juggling! It certainly helps that there are multiple brains to cushion
the impact whenever a juggling pin is missed [*]_.

.. [*] I do love these grotesque mixed metaphors!

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