[Doc-SIG] Reworking Footnotes

[Tony J Ibbs (Tibs)]

First off, I'm glad you want to keep the "citation" form as::

     For more information refer to [GVR2001]_.

     .. _[GVR2001] Python Documentation; van Rossum, Drake, et al.;
        http://www.python.org/doc/

since I like that.


David Goodger wrote:
> Footnotes would be limited to numerical labels:
> manual ("1") and auto-numbered (anonymous "#", named "#label").

I have no problem with regarding footnotes as distinct from citations,
and limiting them to numeric (although I've always like using little
symbols when doing "real" text processing!).

I can also see the usefulness in allowing them to be distinguished for
presentation purposes.

> The footnote is the only explicit markup construct (starts with ".. ")
> that directly translates to a visible body element.  I've always been
> a little bit uncomfortable with the ".. " marker for footnotes because
> of this; ".. " has a connotation of "special", but footnotes aren't
> especially "special".

Hmm - we obviously differed in what we thought ".." meant, but so it
goes.

However, I think easier with examples, so let's create one::

    Fans of Terry Pratchett are perhaps more likely to use
    footnotes [1]_ in their own writings than other people
    [2]_. Of course, in *general*, one only sees footnotes
    in academic or technical writing - it's use in fiction
    and letter writing is not normally considered good
    style [4]_, particularly in emails (not a medium that
    lends itself to footnotes).

    .. [1] That is, little bits of referenced text at the
       bottom of the page.
    .. [2] Because Terry himself does, of course [3]_
    .. [3] Although he has the distinction of being
       *funny* when he does it, and his fans don't always
       achieve that aim.
    .. [4] Presumably because it detracts from linear
       reading of the text - this is, of course, the point.

and look at it with the second syntax proposal:

    Fans of Terry Pratchett are perhaps more likely to use
    footnotes [1]_ in their own writings than other people
    [2]_. Of course, in *general*, one only sees footnotes
    in academic or technical writing - it's use in fiction
    and letter writing is not normally considered good
    style [4]_, particularly in emails (not a medium that
    lends itself to footnotes).

    _[1] That is, little bits of referenced text at the
         bottom of the page.
    _[2] Because Terry himself does, of course [3]_
    _[3] Although he has the distinction of being
         *funny* when he does it, and his fans don't always
         achieve that aim.
    _[4] Presumably because it detracts from linear
         reading of the text - this is, of course, the point.

(I note here that if I have gotten the indentation of the footnotes
themselves correct, this is clearly not as nice. And if the indentation
should be to the left margin instead, I like that even less).

and the third (new) proposal:

    Fans of Terry Pratchett are perhaps more likely to use
    footnotes 1_ in their own writings than other people
    2_. Of course, in *general*, one only sees footnotes
    in academic or technical writing - it's use in fiction
    and letter writing is not normally considered good
    style 4_, particularly in emails (not a medium that
    lends itself to footnotes).

    _1. That is, little bits of referenced text at the
        bottom of the page.
    _2. Because Terry himself does, of course 3_
    _3. Although he has the distinction of being
        *funny* when he does it, and his fans don't always
        achieve that aim.
    _4. Presumably because it detracts from linear
        reading of the text - this is, of course, the point.

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.

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.

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

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
.. "equal" really means "in some sense the same, but maybe not
.. the sense you were hoping for", or, more succinctly, "is
.. confused with". (Gordon McMillan, Python list, Apr 1998)
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)