[Doc-SIG] Reworking Footnotes

[Moore, Paul]

From: Tony J Ibbs (Tibs) [mailto:tony@lsl.co.uk]
> I think I don't, in practice, mind the targets too much
> (the use of a dot after the number helps a lot here),
> but I do have a problem with the body text, in that I
> don't naturally separate out the footnotes as different
> than the rest of the text - instead I keep wondering why
> there are numbers interspered in the text. The use of
> brackets around the numbers ([ and ]) made me somehow
> parse the footnote references as "odd" - i.e., not part
> of the body text - and thus both easier to skip, and also
> (paradoxically) easier to pick out so that I could follow
> them.

I agree with this entirely. 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.

On the target change, it doesn't matter much to me.

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

Exactly.

> That leaves David's problem of wanting to distinguish
> footnotes and citations - and the only thing I can propose
> there is that footnotes are numeric or # and citations are
> not (which, as a human being, I can probably cope with!).

I can (sort-of) see the value in distinguishing footnotes and citations. As
a Pratchett fan (:-)) I'd probably use footnotes, but not so much citations.
So I don't have much of a view on citations. But I suspect that using some
form of DWIM [1]_ which distinguishes footnotes and citations based on the
style of the reference (footnote is numeric or #, others are citation) would
work fine in practice.

  _1. [2]_ Do What I Mean - is that a common term in Python
      circles? I picked it up from Perl...
  _2. Just trying out the new form. Hmm, feels OK...


Paul.