Substitution

Substitutions allow you to include any number of complex inline structures in the text and at the same time keep the details out of the text flow.

They consist of two parts: substitution reference and substitution definition. The processing system replaces the substitution references with the contents of the corresponding substitution definitions.

Substitution reference

Description

The substitution reference consists of a reference text enclosed by vertical bars.

A substitution reference can also be a hyperlink reference by appending a "_" (named) or "__" (anonymous).

Start and end characters

Start character = "|", end character = "|" (optionally followed by "_" or "__")

(See also: Inline markup)

Properties

  • Substitution references are replaced inline with the contents of the substitution definition.
  • A reference text must not start or end with a space

Substitution definition

Description

The substitution definition consists of an explicit markup start (".. ") followed by the reference text enclosed in vertical bars, a space and the definition block.

The definition block contains an embedded inline-compatible directive, such as "image" or "replace".

(See also: Explicit markup blocks)

Principle

+-----+----------------------------------------------+
|".. "|"|"reference text"|" directive type"::" data  |
+-----+directive block                               |
      |                                              |
      +----------------------------------------------+

Properties

  • The contents of the substitution definition replace the substitution reference inline.
  • A reference text must not start or end with a space.

Applications

Some use cases for the substitution mechanism are described below:

Replacement text

The substitution mechanism can be used for simple text substitution. This can be useful if the replacement text is repeated several times in the comment, especially if it has to be changed later.

Directive type: replace

Samples

(In sample project: B_DocuElements\Substitution\FB_Libdoc_Substitution_ReplacementText)

(*
|RST|_ is an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax.
Among others it is useful for library documentation. If the |RST| option is activated,
comments written in |RST| will be shown in the Documentation tab of the library manager in an attractive format.
|RST| is a little annoying to type over and over and spelling out the
bicapitalized word |RST| every time isn't really necessary for |RST| source readability.

.. |RST| replace:: reStructuredText
.. _RST: https://infosys.beckhoff.de/
*)

Substitution 1:

Note the final underscore when you first use the substitution reference. This indicates a reference to the corresponding hyperlink target. Inline markup is not processed in the substitution definition.

(*
This is a simple |substitution reference|. It will be replaced by
the processing system.

This is a |substitution and hyperlink reference|_. In
addition to being replaced, the replacement text or element will
refer to the "substitution and hyperlink reference" target.

.. |substitution reference| replace:: example of substitution 
.. |substitution and hyperlink reference| replace:: combination of substitution and hyperlink reference
.. _substitution and hyperlink reference: https://beckhoff.de/
*)

Substitution 2:

Images

(In sample project: B_DocuElements\Substitution\FB_Libdoc_Substitution_Images)

The substitution mechanism can also be used to include images in the comment text.

Directive type: image

(See also: Images)

Samples

Substitution in paragraphs

The comment text |Beckhoff|__ is supplemented by the logo. The underscore following the substitution reference indicates a reference to a hyperlink target. Click on the image to open the Beckhoff website in the Library Manager.

(*
Images are a common use for substitution references: |Beckhoff|_.

.. |Beckhoff| image:: C:\Tc3LibDocImages\SampleLib1\logo.gif
 :height: 16
 :width: 64
.. _Beckhoff: http://www.beckhoff.de/
*)

Substitution 3:

(*
The |safety| symbol indicates a hazardous situation which,
if not avoided, could result in minor or moderate injury.

.. |safety| image:: C:\Tc3LibDocImageslogo\SampleLib1\safetysymbol.png
*)

Substitution 4:

Substitution in lists or tables

(*
* |Run mode| Run mode
* |Stop mode| Stop mode
* |Config mode| Config mode

============= ======
Symbol        Status
============= ======
|Run mode|    Run mode
|Stop mode|   Stop mode
|Config mode| Config mode
============= ======

.. |Run mode| image:: C:\Tc3LibDocImages\SampleLib1\tc3rtrunmode.png
.. |Stop mode| image:: C:\Tc3LibDocImages\SampleLib1\tc3rtstopmode.png
.. |Config mode| image:: C:\Tc3LibDocImages\SampleLib1\tc3rtconfigmode.png
*)

Substitution 5: