******************************
Explicit Directive Quick Notes
******************************


Comments
********

Arbitrary indented text may follow the explicit markup start and will be processed as
a comment element, and not included in the output.

.. code:: rst

    ..
       _This: is a comment.

    ..
       [and] this.

    ..
       this:: too.

    ..
       |even| this:: .

    .. [this] however, is a citation.

See comments_ for more information.


QuickNote: Explicit Directive
*****************************

.. code:: rst

    .. directive_name::    <-- two colons
        :config_option:    <-- config options when available

        text block the directive applies to


QuickNote: Explicit Internal Hyperlink Targets
**********************************************

.. code:: rst

    .. _link_identifer:     <-- one colon

    hyperlink target heading or text


QuickNote: Explicit External Hyperlink Targets
**********************************************

.. code:: rst

    .. _link_identifer:   URL (can be relative, but then you have to know the path, which isn't ideal for maintainability)


Footnotes
*********

.. code:: rst

    Lorem ipsum\ [3]_ dolor sit amet, consectetur adipiscing elit\ [#]_, sed do eiusmod
    tempor incididunt [#unique_name]_ ut labore et dolore magna aliqua.  Ut enim\ [*]_ ad
    minim veniam, quis nostrud...

    .. rubric:: Footnotes   <-- optional

    .. [citation_label]
        Footnote text

    .. [3]             <-- manually-numbered footnote
    .. [#]             <-- auto-numbered footnote (starts at 1)
    .. [#unique_name]  <-- auto-numbered label
    .. [*]             <-- auto-symbol footnote

Note that the reference *must* be preceded by a space.  If the hyperlinked footnote
symbol should be against the word before it, then escape the preceeding space like
this:  ``footnoted topic\ [1]_``.

Auto-numbered label footnotes are used when a footnote reference needs to be used
more than once.

Auto-numbered and auto-symbol footnotes rely upon the sequence in which the footnotes
actually appear.  To avoid maintenance difficulty (e.g. when paragraphs are moved
around in a document), use manually-numbered footnotes or auto-numbered labels.

Footnote text must be consistently indented and left-aligned.  The first body element
within a footnote may begin on the same line as the footnote label. However, if the
first element fits on one line and the indentation of the remaining elements differ,
the first element must begin on the line after the footnote label.  Otherwise, the
difference in indentation will not be detected.

Footnotes may occur anywhere in the document, not only at the end.  Where and how
they appear in the processed output depends on the processing system.


Citations
*********

Citations are different from footnotes in that the first character after the first
'[' is something other than a number or ``#`` or ``*``.

.. code:: rst

    Lorem ipsum [CIT2002]_ dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
    incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud...

    .. [CIT2002] Book or article reference, URL or whatever.
        More text indented when additional text is needed.


Substitutions
*************

reStructuredText supports "substitutions" (ref), which are pieces of text and/or
markup referred to in the text by \|name\|.  They are defined like footnotes with
explicit markup blocks, like this:

.. code:: rst

    .. |unique_name| replace:: replacement *text*

or this:

.. code:: rst

    .. |caution| image:: warning.png
             :alt: Warning!

or this:

.. code:: rst

    .. |aacute| unicode:: U+000E1 .. LATIN SMALL LETTER A WITH ACUTE ACCENT MARK
        :trim:     <-- optional, causes whitespace on either side to be closed.
                       This       :  Lorem ipsum [aacute] dolor sit amet
                       Rather than:  Lorem ipsum\ [aacute]\ dolor sit amet

See `reStructuredText reference for substitutions <rest_substitutions_>`_ for details.

If you want to use some substitutions for all documents, put them into ``rst_prolog`` or
``rst_epilog`` (a Sphinx variable in the doc project's ``conf.py`` file) or put them
into a separate file and include it into all documents you want to use them in, using
the ``.. include::`` directive.  (Be sure to give the include file a file name
extension differing from that of other source files, to avoid Sphinx finding it as a
standalone document.)

Sphinx defines some `default substitutions <sphinx_substitutions_>`_.



.. include:: external_links.txt