Titles

ICG titles always use “#” for underlining, which always extends at least as far as the text it underlines. Subsections of the document may either be underlined, or, more likely, will use a .. rubric:: directive. This is discussed in the next topic.

.. _icgsphinx-titles:

Titles
######

ICG titles always use "#" for underlining, which always extends *at least*
as far as the text it underlines. Subsections of the document may either be
underlined, or, more likely, will use a ``.. rubric::`` directive. This is
discussed in the :ref:`next topic <icgsphinx-sections>`.

ICG Usage

Breakdown

Underlining

Always use “#” for titles.

Link Anchor

Always create a unique link anchor for the document and place it immediately above the title (placement elsewhere will cause it not to work) — except command and FISH reference documents, which don’t need them.

Other Matter

Anything can go above a document title, but in practice ICG only uses the document top for:

definition of custom roles,

inclusion of material (as is seen above), and

comments, particularly for defining a document-wide prefix (see Anchors).

Notes

Titles and subsections that use underlining may use any of the following characters: ! ” # $ % & ‘ ( ) * + , - . / : ; < = > ? @ [ ] ^ _ ˋ { | } ~. In practice, ICG docs always use “#” for titles, and generally use “+”, “=”, and “-” for second, third, and fourth level headings, respectively. (See Docutils: Sections for complete info.)
The one place where anchors above the document title do not appear is in command or FISH documents. These have a customized “built-in” mechanism (the :cmd: and :func: roles) for hyperlinking that renders doc-topping anchors unnecessary.