[Doc-SIG] Reworking Footnotes

[Tony J Ibbs (Tibs)]

More on footnote forms.

Whilst only one datum [1]_, I note that I've now finished reading my
email fix for the day, and in both the Python and HPV (human powered
vehicle) lists, people writing email tend to compose footnotes as::

   Here is some text, with a footnote [1] - note that
   these are always numerical (although Michael Hudson
   is about the only person I've ever seen to use "0"
   as the footnote number!)

   [1] and here is the footnote itself.

Given I believe there to be little overlap between these two (sets of)
email lists (!), and given I've also seen this form elsewhere (the Terry
Pratchett newsgroup *does* spring to mind!), it must surely be a
significant datum.

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.

reST is already pushing it a *little* bit by requiring the footnote
indicators to bear extra markup beyond the square brackets - but we can
justify that with some fast talking (mainly because otherwise,
particularly in Python-describing text, we lose easy use of square
brackets for other purposes).

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

Has anyone come across any other pre-existing plaintext representation
for footnotes?

.. [1] That is, the fact of it all being email is
   singular - clearly the *instances* of usage are
   not.

.. [2] Is that like saying "obviously", which normally
   means "not at all obviously, but I can't be bothered
   to explain or justify"?

.. [3] The use of *two* leading underscores for anounymous
   hyperlinks is then an oddity to be learnt separately,
   but that was discussed another time, and I can cope
   with the occasional oddity.

Tibs
--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Give a pedant an inch and they'll take 25.4mm
(once they've established you're talking a post-1959 inch, of course)
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)