Hyperlinks
Hyperlinks refer to another location within or outside the comment. They usually consist of two parts: hyperlink reference (source) and hyperlink target. If the body of the text contains a source link, there must also be a target link somewhere else in the comment (exception: detached hyperlinks).
reStructuredText distinguishes explicit, implicit and inline hyperlink targets.
It is also possible to set a link to the documentation of another library object that is also included in that library (see Link to another object).
Explicit hyperlink targets
Explicit hyperlink targets refer to a section within the function block documentation or to an external page and can be linked together. They can be named or anonymized. Unlike the named hyperlinks, the reference name is not used with anonymous hyperlinks to match the reference with their target (see Anonymous hyperlinks).
- Internal hyperlinks (link to a position within the comment or within the function block documentation)
- External hyperlinks (link to a website or email program)
- Indirect hyperlinks (linking of explicit hyperlink targets)
Inline hyperlink targets
Inline hyperlink targets refer to the current text of a comment or function block documentation.
Implicit hyperlink targets
Implicit hyperlink targets are generated by section headings, footnotes and citations. Unlike explicit hyperlink targets, section headings, footnotes and citations automatically generate a hyperlink target to themselves; they do not contain a link block in their definition. The reference name corresponds to the section heading or the footnote or quotation label. Otherwise, implicit hyperlinks behave identically to explicit hyperlinks.
Ambiguity in implicit and explicit hyperlinks within a library object
- Explicit and implicit hyperlink targets with the same reference name: The hyperlinks do not work.
Error message: Duplicate target name, cannot be used as a unique reference: "1" ("Beckhoff").
Sample:
This in an explicit internal hyperlink reference: 1_
For more information see [1]_
--------
.. _1:
This is an explicit internal hyperlink target.
.. [1] Footnote
or
See Beckhoff_.
This is an explicit hyperlink to Beckhoff_.
--------
.. _Beckhoff: http:\\www.beckhoff.de
Beckhoff
========
- Duplicate implicit hyperlink targets: The hyperlinks do not work.
Error message: Duplicate target name, cannot be used as a unique reference: "chapter a".
Sample:
Chapter 1
=========
Chapter a
*********
Chapter 2
=========
Chapter a
*********
--------
See `Chapter a`_
- Duplicate explicit hyperlink targets: The hyperlinks do not work. Exception: Duplicated external hyperlink targets (identical reference names and referenced URIs) are conflict-free and are not removed.
Error message: Duplicate target name, cannot be used as a unique reference: "1".
Sample:
This in an explicit internal hyperlink reference: 1_
This in another explicit internal hyperlink reference: 1_
--------
.. _1:
This is an explicit internal hyperlink target.
.. _1:
This is another explicit internal hyperlink target.
See also: Reference names