Reference names

reStructuredText distinguishes between simple reference names and phrase references.

Simple reference names

Simple reference names are single words consisting of alphanumeric characters (letters or digits) and isolated (non-adjacent) hyphens, underscores, dots, colons and plus signs. Spaces or other characters are not allowed. Simple reference names are used for quotation labels and some hyperlinks:

Want to learn about MyFavoriteProgrammingLanguage_?

.. _MyFavoriteProgrammingLanguage: http://www.python.org

Want to learn about My_Favorite_Programming-Language_?

.. _My_Favorite_Programming-Language: http://www.python.org

Phrase references

"Phrase references" are reference names that use punctuation or whose names are phrases (two or more words separated by spaces). Phrase references are expressed by including the phrase in back quotes and treating the text as a reference name:

Want to learn about `my favorite programming language`_?

.. _my favorite programming language: http://www.python.org

Reference names 1:

Properties

Reference names are space-neutral and font-independent. If the reference names are resolved internally, the following applies:

Spaces are normalized (one or more spaces and line breaks are interpreted as a single space)
Upper and lower case is normalized (all letters are converted to lower case)

For example, the following hyperlink references are equivalent:

- `A HYPERLINK`_
- `a    hyperlink`_
- `A
  Hyperlink`_

.. _A HYPERLINK: https://beckhoff.de/

By clicking on one of the hyperlink references, the Beckhoff website is called up in the Library Manager.

Reference names 2:

Hyperlinks, footnotes and citations have the same namespace for reference names. The names of quotations (simple reference names) and manually numbered footnotes (decimal numbers) are entered in the same database for the respective library object as other hyperlink names.

This means that within a library object a footnote (defined as .. [1]), which is normally referred to by a footnote reference ([1]_), is also referred to by a simple hyperlink reference (1_). Make sure that there are no conflicts with reference names.