Footnotes/Sidenotes

Warning

Be careful about copying usage as seen in docs. Make sure it conforms to this documentation. Rationale for this below.[1]

ICG Usage

  • First, determine whether an endnote or a sidenote is needed.
  • For endnotes, use autonumbering exclusively (not symbols, not manual numbering), even if there is only one.
  • Endnote sections should always be the absolute last visible content on the page.
  • For sidenotes, there is no numbering, nor is there a limit to the number you can create, but realistically this should be done sparingly.

The footnotes inherited from the old TeX system are difficult to map, since the one thing that is not done in ICG-style Sphinx is footnotes. This means all footnote matter from those docs has had to be re-allocated to either endnotes or sidenotes.

Endnotes vs. Sidenotes

Technically, what were “footnotes” in the old TeX system are now “endnotes,” since they always appear at the bottom (end) of a doc. In the meantime, some footnotes in the old manuals are better transformed into sidenotes. Briefly, here is a rubric to help determine what is needed with regard to these items.

  • if the matter involves a “technicality” that is not necessary to understanding the main point, use an endnote.
  • if the matter is lengthy and interruptive of the flow of the main document, use an endnote.
  • if the matter is brief and should ideally be positioned near the paragraph from which it is pulled, use a sidenote.
  • if the matter is parenthetical to the main point being made, do not do not move it to a note; leave it in place (and make it a parenthetical statement). This criteria may be considered to be in tension with the second one above. As a rule of thumb, if the matter is two or more paragraphs or more than six output lines at full screen width, use an endnote.

With regard to sidenotes, a good illustration of proper use is the message seen in the example docs “If you would like to load the example files for this project…” message that appears at the top of the document. Waiting to show this message until the end of the document (i.e., as an endnote) runs the risk of rendering it moot by the time it is encountered. Another necessary usage of sidenotes would be a message of this type: “Keywords marked with an asterisk ( * ) require the Dynamic Option”. There is no one-to-many mechanism for notes like this (that is, there will be one “note”, but the marker will occur multiple times), so the best you can do is put the “Note” as a sidenote near the place where the keywords appear.

Footnote Format

The footnote created on this doc is made as follows. The mark is made like this:

.. warning::

   *Be careful* about copying usage as seen in docs.  Make sure it conforms
   to the information below. Rationale for this below.\ [#]_

Note

A mark that appears at the end of a sentence — as is common — will require a backslash and space (\ ) immediately after the period:
... sentence end.\ [#]_
not
... sentence end.[#]_
The footnote mark must be preceded in markup by a space; use of the backslash “removes” that space when rendering occurs.

The mark “definition” is just [#]_. Using # stipulates autonumbering (the system will determine the numeral to use for the mark), which is preferred. Content changes too much in ICG docs to give manual numbering any consideration.

Similarly, if the impulse to use a character as a symbol-type footnote mark is present ( * or † or ‡ ), there is a good chance that what you need to begin with is really a sidenote, not an endnote (or maybe even nothing at all — see the guidelines above for choosing endnote vs. sidenote).

The footnote section, which should always be the very last content on a page, is formed like this:

.. rubric:: _
   :class: footnotessection

.. [#] The "standards" defined here did not take shape until after the |pfc|
   6.0 doc set was nearly complete (this should give you a chronological
   context).  Prior to this, a number of approaches for footnotes were
   inconsistently applied to the doc sets for |pfc| 5.0 & 6.0 , |flac3d|
   6.0, |udec| 7.0, and the draft of |3dec| 6.0 docs.  So it is possible,
   even likely, that if you are copying the usage as seen in a doc from
   one of those sets that has not been updated since it was first created,
   you are copying *incorrect* usage.

The .. rubric:: is required; any character(s) may be used for the rubric title, as they will be “hidden” on render anyway. As a convention underscore (_) is often seen here. The :class:: footnotessection option is required to make the section overline (and to hide the rubric title).

Sidenote Format

Sidenotes are not constructed using the note mechanism in Docutils. They are really just admonition-type blocks with a :class: option that will offset them to the right side of the main content column. The sidenote on this page was constructed like this:

.. note::
   :class: aside

   A mark that appears at the end of a sentence — as is common — will
   require a backslash and space (``\`` ) immediately after the period: |br|
   ``... sentence end.\ [#]_`` |br| not |br| ``... sentence end.[#]_`` |br|
   The footnote mark *must* be preceded in markup by a space; use of the
   backslash "removes" that space when rendering occurs.

Vertically align a sidenote by placing it in markup ahead of the block to which it should align (e.g., the sidenote above appears in markup above the paragraph starting with The mark "definition" is just...).

_

[1]The “standards” defined here did not take shape until after the PFC 6.0 doc set was nearly complete (this should give you a chronological context). Prior to this, a number of approaches for footnotes were inconsistently applied to the doc sets for PFC 5.0 & 6.0 , FLAC3D 6.0, UDEC 7.0, and the draft of 3DEC 6.0 docs. So it is possible, even likely, that if you are copying the usage as seen in a doc from one of those sets that has not been updated since it was first created, you are copying incorrect usage.