Substitution

Substitutionen ermöglichen es, beliebig komplexe Inline-Strukturen in den Text einzubinden und gleichzeitig die Details aus dem Textfluss herauszuhalten.

Sie bestehen aus zwei Teilen: Subsitutionsreferenz und Subsitutionsdefinition. Das Verarbeitungssystem ersetzt die Substitutionsreferenzen durch den Inhalt der entsprechenden Substitutionsdefinitionen.

Substitutionsreferenz

Beschreibung

Die Substitutionsreferenz besteht aus einem von vertikalen Balken eingeklammerten Referenztext.

Eine Substitutionsreferenz kann gleichzeitig eine Hyperlink-Referenz durch Anhängen eines „_“ (benannt) oder „__“ (anonym) sein.

Start- und Endzeichen

Startzeichen = „|“, Endzeichen = „|“ (optional gefolgt von „_“ oder „__“)

(Siehe auch: Inline-Markup)

Eigenschaften

  • Substitutionsreferenzen werden inline durch den Inhalt der Substitutionsdefinition ersetzt.
  • Ein Referenztext darf nicht mit einem Leerzeichen beginnen oder enden

Substitutionsdefinition

Beschreibung

Die Substitutionsdefinition besteht aus einem expliziten Markup-Start („.. “) gefolgt von dem in vertikalen Balken umschlossenen Referenztext, einem Leerzeichen und dem Definitionsblock.

Der Definitionsblock enthält eine eingebettete inline-kompatible Direktive, wie z. B. „image“ oder „replace“.

(Siehe auch: Explizite Markup-Blöcke)

Prinzip

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

Eigenschaften

  • Der Inhalt der Substitutionsdefinition ersetzt inline die Substitutionsreferenz.
  • Ein Referenztext darf nicht mit einem Leerzeichen beginnen oder enden.

Anwendungsfälle

Nachfolgend werden einige Anwendungsfälle für den Substitutionsmechanismus beschrieben:

Ersatztext

Der Substitutionsmechanismus kann für die einfache Textsubstitution verwendet werden. Dies kann sinnvoll sein, wenn der Ersetzungstext mehrmals im Kommentar wiederholt wird, insbesondere wenn er später geändert werden muss.

Direktiventyp: replace

Beispiele

(Im Beispielprojekt: 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:

Beachten Sie den abschließenden Unterstrich bei der ersten Verwendung der Substitutionsreferenz. Dies zeigt einen Verweis auf das entsprechende Hyperlink-Ziel an. Inline-Markup werden in der Substitutionsdefinition nicht verarbeitet.

(*
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:

Bilder

(Im Beispielprojekt: B_DocuElements\Substitution\FB_Libdoc_Substitution_Images)

Der Substitutionsmechanismus kann auch verwendet werden, um Bilder in den Kommentartext einzubinden.

Direktiventyp: image

(Siehe auch: Bilder)

Beispiele

Substitution in Absätzen

Der Kommentartext |Beckhoff|_ wird durch das Logo ergänzt. Der Unterstrich, der der Substitutionsreferenz folgt, zeigt einen Verweis auf ein Hyperlink-Ziel an. Durch einen Klick auf das Bild wird die Beckhoff Homepage im Bibliotheksverwalter geöffnet.

(*
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 Listen oder Tabellen

(*
* |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: