(From http://structuredtext.sourceforge.net/spec/alternatives.txt) Earlier today (late last night) I posted several ideas for changes to footnote syntax: - Change footnote syntax from ``.. [1]`` to ``_[1]``? ... - Differentiate (with new DTD elements) author-date "citations" (``[GVR2002]``) from numbered footnotes? ... - Render footnote references as superscripts without "[]"? ... These ideas are all related, and suggest changes in the reStructuredText syntax as well as the docutils tree model. The footnote has been used for both true footnotes (asides expanding on points or defining terms) and for citations (references to external works). Rather than dealing with one amalgam construct, we could separate the current footnote concept into strict footnotes and citations. Citations could be interpreted and treated differently from footnotes. Footnotes would be limited to numerical labels: manual ("1") and auto-numbered (anonymous "#", named "#label"). 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". Printed texts often put footnotes at the bottom of the page where the reference occurs (thus "foot note"). Some HTML designs would leave footnotes to be rendered the same positions where they're defined. Other online and printed designs will gather footnotes into a section near the end of the document, converting them to "endnotes" (perhaps using a directive in our case); but this "special processing" is not an intrinsic property of the footnote itself, but a decision made by the document author or processing system. Citations are almost invariably collected in a section at the end of a document or section. Citations "disappear" from where they are defined and are magically reinserted at some well-defined point. There's more of a connection to the "special" connotation of the ".. " syntax. The point at which the list of citations is inserted could be defined manually by a directive (e.g., ".. citations::"), and/or have default behavior (e.g., a section automatically inserted at the end of the document) that might be influenced by options to the Writer. Syntax proposals: + Footnotes: - Current syntax:: .. [1] Footnote 1 .. [#] Auto-numbered footnote. .. [#label] Auto-labeled footnote. - The syntax proposed in the original 2002-02-28 Doc-SIG post: remove the ".. ", prefix a "_":: _[1] Footnote 1 _[#] Auto-numbered footnote. _[#label] Auto-labeled footnote. The leading underscore syntax (earlier dropped because ``.. _[1]:`` was too verbose) is a useful reminder that footnotes are hyperlink targets. - Minimal syntax: remove the ".. [" and "]", prefix a "_", and suffix a ".":: _1. Footnote 1. _#. Auto-numbered footnote. _#label. Auto-labeled footnote. ``_1.``, ``_#.``, and ``_#label.`` are markers, like list markers. Footnotes could be rendered something like this in HTML | 1. This is a footnote. The brackets could be dropped | from the label, and a vertical bar could set them | off from the rest of the document in the HTML. Two-way hyperlinks on the footnote marker ("1." above) would also help to differentiate footnotes from enumerated lists. If converted to endnotes (by a directive/transform), a horizontal half-line might be used instead. Page-oriented output formats would typically use the horizontal line for true footnotes. + Footnote references:: - Current syntax:: [1]_, [#]_, [#label]_ - Minimal syntax to match the minimal footnote syntax above:: 1_, #_, #label_ As a consequence, pure-numeric hyperlink references would not be possible; they'd be interpreted as footnote references. + Citation references: no change is proposed from the current footnote reference syntax:: [GVR2001]_ + Citations: - Current syntax (footnote syntax):: .. _[GVR2001] Python Documentation; van Rossum, Drake, et al.; http://www.python.org/doc/ - Possible new syntax:: _[GVR2001] Python Documentation; van Rossum, Drake, et al.; http://www.python.org/doc/ _[DJG2002] Docutils: Python Documentation Utilities project; Goodger et al.; http://docutils.sourceforge.net/ Without the ".. " marker, subsequent lines would either have to align as in one of the above, or we'd have to allow loose alignment (I'd rather not):: _[GVR2001] Python Documentation; van Rossum, Drake, et al.; http://www.python.org/doc/ I propose adopting the "minimal" syntax for footnotes and footnote references, and adding citations and citation references to reStructuredText's repertoire. The current footnote syntax for citations is better than the alternatives given. -- 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
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.)
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.)
Tony J Ibbs (Tibs) wrote:
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!).
That suggests a good idea: how about, in addition to auto-numbered footnotes, we add "auto-symbol" footnotes? They'd have a syntax like:: Here's an auto-symbol reference [*]_. .. _[*] Here's the footnote itself (modulo any syntax changes yet to come). I like symbols for footnotes too. The Chicago Manual of Style lists the following symbols for "Note Reference Marks" (section 12.51 in the 14th edition): asterisk/star ("*"), dagger, double dagger, section mark, parallels ("||"), number sign ("#"). For more symbols, it suggests using doubles and triples of these symbols, ("**" etc.) in the same sequence, but I'm sure we could come up with some more interesting glyphs. More "gilding on the lily" perhaps, but I like it! -- 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
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
David Goodger wrote:
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" [*]_ [*]_.
Hmm. Or how text-centred one is - much of my own sense of humour is based around word-play as such, which means that text-on-the-page works well (and also means that the Goons, Firesign Theater, etc. are also appreciated), and also means that other people often don't see why I think something funny. Of course, it may also be that everyone's taste is different - many of the authors cited as "you'll love this if you love Pratchett" leave me cold, and I can imagine the phenomenum working the other way around as well.
.. [*] 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.
Hmm. I think that this example is itself enough to warn people to be very careful about using autogenerated footnotes (of whatever sort - the "*" could equally well be "#") in an other-than-trivial manner - two anonymous footnotes in a row are confusing! On the other hand, I also think it's relatively unlikely - I'd be much more likely to attach tags to things if they are that complex. On the other other hand, if we're going to allow generated footnote indices, I don't see a way to limit it, so we'll have to cope.
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!
And the man says he doesn't like prose humour. Ho hum. Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ A single element tuple needs a trailing comma, and an empty tuple needs brackets to distinguish it from a coffee stain. - Duncan Booth, in his intro to Python for the ACCU Spring 2002 conference My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)
participants (2)
-
David Goodger -
Tony J Ibbs (Tibs)