Endnotes/Sidenotes

Endnotes

ICG docs produce endnotes, not footnotes. Normally[1] endnotes, if they appear, should be at the very end of the document. There should be nothing following an endnote.

Endnote

[1]

This is not a normal document. Be careful about copying footnote/endnote markup, as this is an area where the usage in existing documents varies widely.

Endnotes
++++++++

ICG docs produce endnotes, not footnotes. Normally\ [#]_ endnotes, if they
appear, should be at the very end of the document. There should be nothing
following an endnote.

.. rubric:: Endnote
   :class: endnotesection

.. [#] This is not a normal document. Be careful about copying
footnote/endnote markup, as this is an area where the usage in existing
documents varies widely.

ICG Usage

Set the Endnote Mark

Place the markup \ [#]_ at the point where the endnote mark is needed. The use of # causes the numbering of notes to happen automatically.

Create the Endnote Section Heading

This markup is fixed and must appear exactly as shown, or it will not render correctly — which includes NO heading and a horizontal rule to mark the start of the endnote fsection. The class option and its content are critical here.

.. rubric:: Endnote
   :class: endnotesection

Create the Notes

Each note begins with .. [#], a space, followed by its content. The order of notes as they appear in the section must match the order of marks in the body of the doc (the note at the first .. [#] must be for the first mark in the doc, and so on). Note a multiline note does not need to have vertically aligned

Sidenotes/Admonitions

I’m a Sidenote

Sidenotes are used for content that supports the adjacent text. They should be brief, and observe, in the markup they are placed above the content to which they should be adjacent.

Sidenotes are built with the .. admonition:: directive, with the option :class: aside added to them. They will float to the right of any adjacent paragraph text. Without the :class:, an .. admonition:: directive will appear, by default, below whatever content preceded it. Examples of both are shown here.

I’m an Admonition

Admonitions are used for content that is regarded as important enough to interrupt the flow of the document to make a point.

See the next section for some guidance on when to use each of these constructs.

Sidenotes/Admonitions
+++++++++++++++++++++

.. admonition:: **I'm a Sidenote**
   :class: aside

   Sidenotes are used for content that supports the adjacent text. They
   should be brief, and observe, in the markup they are placed *above* the
   content to which they should be adjacent.

Sidenotes are built with the ``.. admonition::`` directive, with the option
``:class: aside`` added to them.  They will float to the right of any
adjacent paragraph text. Without the ``:class:``, an ``.. admonition::``
directive will appear, by default, below whatever content preceded it.
Examples of both are shown here.

.. admonition:: *I'm an Admonition*

   Admonitions are used for content that is regarded as important enough to
   *interrupt* the flow of the document to make a point.

   See the next section for some guidance on when to use each of these
   constructs.

In markup, a sidenote should be placed above the paragraph to which it should be adjacent. Generally, sidenotes should only appear next to paragraph elements. Poor/bad rendering will occur if they are placed next to block-level items (e.g., a figure or table).

The title content of an .. admonition:: directive will take formatting, which is useful for bringing emphasis or context to the content. However, there is no standard for title formatting at this time, so this is up to the author.

Endnotes vs. Sidenotes. vs. Admonitions

1. Use an endnote:

   • if the matter involves a “technicality” that is not necessary to understanding the main point, or

   • if the matter is lengthy and interruptive of the flow of the main document.

2. Use a sidenote:

   • if the matter is brief and should ideally be positioned near the paragraph from which it is pulled, or

   • if the matter is assistive but not intrinsic to the adjacent paragraph.

3. Use an admonition:

   • if the matter is Important! or Warning! or Remember!

4. DO NOT DO ANYTHING:

   • if the matter is brief and parenthetical to the main point being made. In this case, leave it in place (and make it a parenthetical statement).