Seiten bearbeiten

Diese Seite ist ein Teil der IsyFact-Standards. Alle Inhalte der Seite, insbesondere Texte und Grafiken, sind urheberrechtlich geschützt. Alle urheberrechtlichen Nutzungs- und Verwertungsrechte liegen beim Bundesverwaltungsamt.

Creative Commons Namensnennung Die Nutzung ist unter den Lizenzbedingungen der Creative Commons Namensnennung 4.0 International gestattet.

Im Folgenden wird beschrieben, wie Seiten bearbeitet werden müssen, damit sie per Antora generiert werden können. Außerdem werden Konventionen zur Bearbeitung beschrieben, die es ermöglichen, die IsyFact Dokumentation in einem einheitlichen Stil zur Verfügung zu stellen.

Außerdem gibt es eine Seitenvorlage, die kopiert werden kann, und exemplarisch alle gängigen Elemente einer Dokumentationsseite enthält.

Außer diesem Handbuch sind Kenntnisse der AsciiDoc-Syntax erforderlich.

Dieses Handbuch erklärt die Grundlagen der AsciiDoc-Syntax nicht weiter. Die folgenden Webseiten bieten ausführliche Tutorials und weiterführende Informationen an:

1. Zeilenumbrüche

Der Quelltext eines Dokuments bricht nach jedem Satz um. Er orientiert sich nicht anhand einer fixen Spaltenbreite. Diese Regel wird "ein Satz pro Zeile" (one sentence per line, s. AsciiDoc Recommended Practices) genannt und orientiert sich an der Art und Weise, wie Quellcode organisiert ist (eine Anweisung pro Zeile).

Die Anwendung der Regel "ein Satz pro Zeile" bringt unter anderem folgende Vorteile mit sich:

Änderungen am Anfang eines Absatzes führen nicht zu Veränderungen an den restlichen Zeilenumbrüchen des Absatzes.
Einzelne Sätze können mit Leichtigkeit verschoben oder ausgetauscht werden.
Absätze können durch das Einfügen oder Löschen von Leerzeilen mit Leichtigkeit verbunden oder auseinander gezogen werden.
Einzelne Sätze können gut auskommentiert oder mit Kommentaren versehen werden.
Eine Analyse der Zeilenlänge lässt schnell auf zu lange Sätze (z.B. Bandwurm- oder Schachtelsätze) oder andere Anomalien wie eine redundante Schreibweise (z.B. alle Sätze eines Absatzes beginnen gleich) schließen.

Die Regel passt außerdem sehr gut zur gleichzeitigen Verwendung eines modernen Versionsverwaltungssystems, das Branching sowie Merging unterstützt und Merges zeilenweise verarbeitet. Neue oder gelöschte Sätze kann das Versionsverwaltungssystem leicht interpretieren und zusammenführen, da sie sich auf jeweils unterschiedliche Zeilen auswirken. Merge-Konflikte passieren häufig auf Ebene eines Satzes. Sie sind daher leicht verständlich, lokal begrenzt und daher in den meisten Fällen gut zu lösen.

2. Überschriften

Überschriften können bei AsciiDoc auf unterschiedliche Weise gesetzt werden. Bei einer IsyFact-Seite ist stets die Variante zu wählen, bei der die Anzahl der vorgesetzten Gleichheitszeichen die Ebene der Überschrift anzeigt. Das folgende Beispiel definiert ein Kapitel und ein Unterkapitel.

Listing 1. Syntax von Überschriften

== Hallo Welt Kapitel
Das ist ein Hallo Welt Text zum Kapitel.

=== Hallo Welt Unterkapitel
Das ist ein Hallo Welt Text zum Unterkapitel.

Die Überschrift auf der höchsten Ebene ist der Seitentitel:

Listing 2. Seitentitel

= Seitentitel
Das ist ein Text zum Seitentitel.

3. Querverweise

Antora bietet die Möglichkeit, innerhalb der Online-Dokumentation beliebige Querverweise zu setzen, auch über die Grenzen von Antora-Modulen und Antora-Komponenten hinweg. Davon sollte jedoch mit Bedacht Gebrauch gemacht werden, denn sehr starke Verlinkungen der Seiten untereinander bewirken auch eine starke Abhängigkeit. Jegliche Umbenennungen oder Löschungen von Sprungzielen, dazu gehören auch Seitendatei-, Modul- und Komponentennamen, machen die Querverweise darauf ungültig. Allerdings weist Antora bei der Generierung der Dokumentation im Log auf nicht auflösbare Querverweise hin.

Generelle Hinweise zur Verwendung von Verweisen siehe Seitenvorlage Verweise.

3.1. Sprungziele (Anchor)

Für eine Überschrift einer IsyFact-Seite fehlen noch die Inline-Anchor, damit durch Klick auf Verweise auf diese Inline-Anchor gesprungen werden kann. Ein Inline-Anchor wird über eckige Klammern gesetzt. Außerdem muss die ID des Anchors den Namenskonventionen folgen.

Listing 3. Überschriften mit Inline Anchors

[[beispiel-kapitel]]
== Beispiel-Kapitel
Das ist ein Beispieltext zum Kapitel.

[[beispiel-unterkapitel]]
=== Beispiel-Unterkapitel
Das ist ein Beispieltext zum Unterkapitel.

Auch Abbildungen, Tabellen und Listings müssen mit einem Anchor versehen werden, damit sie als Sprungziel dienen können.

3.2. Verweise innerhalb einer Seite

In diesem Abschnitt werden Verweise innerhalb einer Seite, d.h. innerhalb einer Asciidoc-Datei, beschrieben.

Ein Querverweis auf eine Überschrift wird über zwei Paare spitzer Klammern gesetzt.

Listing 4. Querverweis auf eine Überschrift

Zum <<ueberschriften,Beispiel-Kapitel>> gelangen Sie über einen Mausklick.
Im Übrigen handelt es sich bei dem Beispiel-Kapitel um das Kapitel <<ueberschriften>>.

Der erste Parameter in dem Klammer-Paar referenziert die ID des Querverweises. Der zweite Parameter kann gesetzt werden, wenn statt des Namens des Kapitels ein eigener Text verwendet werden soll. Der erzeugte Text sieht wie folgt aus:

Zum Beispiel-Kapitel gelangen Sie über einen Mausklick. Im Übrigen handelt es sich bei dem Beispiel-Kapitel um das Kapitel Überschriften.

Verweise können auch auf andere Sprungziele zeigen als Überschriften, wie Abbildungen, Tabellen und Listings, siehe auch Beispiele für Verweise auf Abbildungen, Tabellen und Listings.

3.3. Verweise innerhalb der Antora-Dokumentation

In diesem Abschnitt werden Verweise auf Inline-Anchor beschrieben, die nicht innerhalb derselben Seite in derselben Datei liegen, sondern in anderen Seiten, Antora-Modulen oder Antora-Komponenten. Diese Verweise nutzen die Syntax des Xref-Makros von Antora.

Ein xref-Verweis ist bei Antora immer gleich aufgebaut:

Listing 5. Verweis Antora

xref:version@component:module:file.adoc#sprungziel[Text des Verweises]

Ein Beispiel:

Listing 6. Verweis auf einen Glossareintrag

xref:glossary::terms-definitions.adoc#glossar-isyfact[IsyFact]

Für eine Erläuterung der einzelnen Abschnitte eines xref-Verweises wird auf die Antora-Dokumentation verwiesen: Beschreibung der Struktur des Xref-Makros. Hier werden dagegen die Konventionen für die Dokumentation der IsyFact beschrieben.

Im xref-Verweis kann eine Version angegeben werden. Dies darf jedoch in der IsyFact-Dokumentation nicht verwendet werden. Stattdessen wird keine Version angegeben, wodurch immer die aktuellste Version des Sprungziels in der Antora-Dokumentation referenziert wird. Explizit angegebene Versionen müssten bei Aktualisierungen angepasst werden, was in einer größeren Dokumentation wie derjenigen der IsyFact nicht mehr durchführbar wäre.

Anmerkung: Wenn absichtlich eine bestimmte Version referenziert werden soll und diese sich nie mehr ändert, kann von dieser Konvention abgewichen werden. Allerdings wird der Verweis ungültig, wenn die referenzierte Version irgendwann als veraltete Version aus der Dokumentation herausgenommen wird.

Die Angaben component und module im xref-Verweis sind ebenfalls optional und sollten nur genutzt werden, wenn sie zur Referenzierung nötig sind, d.h. wenn auf eine andere Antora-Komponente oder ein anderes Antora-Modul verwiesen wird, siehe auch Verweise auf andere Seiten.

Beispiele für die Verwendung von xref-Verweisen finden sich hier: Seitenvorlage Verweise.

Ein xref-Verweis könnte auch für Verweise auf derselben Seite in derselben Datei verwendet werden, ist aber aufwendiger und wird daher für diesen Zweck nicht empfohlen. Stattdessen werden Verweise innerhalb einer Seite empfohlen.

3.4. Externe Verweise

Externe Verweise werden gemäß Asciidoc Dokumentation gesetzt.

4. Admonition-Blocks

Mit Admonition Blocks können Inhalte in Dokumenten exponiert dargestellt werden, sodass ihnen besondere Aufmerksamkeit zuteilwird. Standardmäßig werden fünf verschiedene Blöcke angeboten. Die IsyFact-Dokumentation erweitert diese Liste um weitere Blöcke für verbindliche Regeln.

Es gibt zwei Möglichkeiten zur Definition von Admonition Blocks. Die syntaktisch ausführlichere Variante funktioniert sowohl mit den vordefinierten als auch mit den selbst definierten Blöcken.

Listing 7. Definition eines Admonition Blocks (als Block)

[BLOCKTYP]
====
Hier steht der Text.
====

Die syntaktisch schlankere Variante funktioniert nur mit den vordefinierten Blöcken (NOTE, TIP, IMPORTANT, WARNING und CAUTION).

Listing 8. Definition eines Admonition Blocks (inline)

BLOCKTYP: Hier steht der Text.

4.1. Vordefinierte Blöcke

Den folgenden, vordefinierten Blöcken fallen in der IsyFact-Dokumentation einheitliche Bedeutungen zu. Sie helfen dabei, optionale oder ergänzende Inhalte zu markieren, geben Erfahrungswerte weiter und warnen vor typischen Fehlersituationen oder Fallstricken.

Der Block NOTE enthält weiterführende Inhalte, die optionale Ergänzungen des Textes darstellen. Dies können z.B. interessante Randnotizen oder weiterführende Links, Dokumente sowie Artikel sein. Der Inhalt der Verweise ist in jedem Fall für die Nutzung der IsyFact optional.

Die Verwendung ist ähnlich zu einer Fußnote gedacht, wobei Verweise von einem erklärenden Satz begleitet sein sollten.

Der Block TIP enthält optionale Inhalte, die eigene Erfahrungswerte (Good / Best Practices, Tipps & Tricks, …) einbringen. Die Inhalte stellen Empfehlungen, aber keine verpflichtenden Regeln dar. Allgemeine Vorgaben oder Regeln zur Anwendungsentwicklung, Architektur, Sicherheit oder das Styling müssen in jedem Fall über die jeweils dafür gedachten Blöcke formuliert werden!

Der Block IMPORTANT beschreibt allgemeine Vorgaben der IsyFact, die sich nicht einem der selbst definierten Blöcke zuordnen lassen. Die Inhalte stellen verpflichtende Regeln oder Konventionen dar und können bei Nichtbeachtung, je nach Kontext, zu Fehlern, Workarounds oder eingeschränkter Funktionalität führen.

Der Block WARNING beschreibt typische Fallstricke, die sich bei der Nutzung der IsyFact ergeben können. Er warnt davor und bietet Lösungsmöglichkeiten oder hilft, den Fallstrick aktiv zu vermeiden.

Der Block CAUTION beschreibt typische Fehler, die bei der Nutzung der IsyFact passieren können oder in der Vergangenheit häufiger aufgetreten sind. Die Inhalte sollen diesen Fehlern vorbeugen, um Mehraufwände insbesondere durch subtile Unterschiede, "false friends" oder dergleichen zu vermeiden.

In der Abgrenzung zum Block WARNING stellen die Situationen, die in Blöcken des Typs CAUTION beschrieben werden, entweder eine größere Bedrohung für die korrekte oder rechtzeitige Umsetzung von Anforderungen dar, oder sind, gemessen an ihren Auswirkungen, in der Regel schwer oder erst (zu) spät zu erkennen.

4.2. Selbst definierte Blöcke

Die folgenden, selbst definierten Blöcke, bilden Regeln und Vorgaben der IsyFact ab, die verpflichtend einzuhalten sind. Sie bilden die Grundlage für eine zur IsyFact konforme Umsetzung von Anforderungen und definieren so maßgeblich, wie Konformität zur IsyFact erzielt wird.

Anwendungsanforderung: Beispiel für Anwendungsanforderung

Der Block Anwendungsanforderung beschreibt Anforderungen, welche die IsyFact an die Entwicklung von IT-Systemen stellt. Die Anforderungen kommen typischerweise aus den Bereichen:

Struktur des Quellcodes oder der Quellcodeablage,
Format und Inhalt der Auslieferung,
Detailaspekte der Verwendung von Bausteinen.

Sie bilden die Grundlage für eine einheitliche Umsetzung von Anforderungen, die in gleichartig strukturierten IT-Systemen münden.

Beispiel für Architekturregel

Der Block Architekturregel beschreibt Vorgaben und Regeln, welche die IsyFact an die Architektur von mit ihr entwickelten IT-Systemen stellt. Die Vorgaben zielen somit vor allem auf eine korrekte Umsetzung der Referenzarchitektur ab und sind fast ausschließlich technischer Natur. Sie bilden die Grundlage für eine einheitliche softwaretechnische Architektur der IT-Systeme.

Beispiel für Sicherheitshinweis

Der Block Sicherheit beschreibt Regeln, welche die IsyFact an die IT-Sicherheit von mit ihr entwickelten IT-Systemen stellt. Die Regeln stellen vor allem eine, vom festgestellten Schutzbedarf abhängige, sichere Umsetzung der IT-Systeme sicher.

Beispiel für Bedienkonzept

Der Block Bedienkonzept beschreibt Regeln, welche die IsyFact an die Gestaltung der grafischen Oberflächen stellt. Die Regeln kommen typischerweise aus den Bereichen:

Allgemeine Gestaltungsrichtlinien,
Grundlegender Aufbau von Masken,
Vorgaben zur Ein- und Ausgabe von Daten sowie zu Interaktionsmustern,
Barrierefreiheit und Usability.

Die Regeln stellen vor allem sicher, dass grafische Oberflächen ein einheitliches Look&Feel besitzen und gleichartig bedient werden.

5. Tags

Tags (bzw. tagged regions) werden zur Einbindung von Inhalten aus anderen Seiten verwendet. Somit können mit Tags versehene Teile einer Seite in anderen Seiten zusammengezogen oder wiederverwendet werden.

Das zum Teil noch verwendete Vorgehen der Einbettung von Inhalten anhand von Tags (z.B. tag::inhalt[]) ist nicht mehr erlaubt. Seiten besitzen einen engen, thematischen Fokus und sind direkt über die Navigation aufrufbar. Ein Verweis drückt den Zusammenhang zweier Seiten besser aus als das komplette Einfügen einer Seite in eine andere.

Die Syntax von Tags zeigt das folgende Listing. Zu beachten ist, dass der korrekte Tag-Name gesetzt ist und der Inhalt innerhalb des Tags i.d.R. mit Leerzeilen abgesetzt ist. Die Leerzeilen stellen sicher, dass sich der Inhalt beim Einbinden von den Inhalten vor und nach dem Include absetzt.

Listing 9. Syntax von Tags

// tag::tag-name[]

Dieser Inhalt ist mit einem Tag versehen und von Leerzeilen umgeben.

// end::tag-name[]

Eine vollständige Übersicht über die Funktionsweise von Tags bietet die Dokumentation von AsciiDoc zu tagged regions.

In der IsyFact-Dokumentation werden Tags genutzt, um Bestandteile zu bündeln oder zu referenzieren:

Namenskonventionen (Tag-Name: namenskonvention),
Definitionen (Tag-Name: (begriff)-definition),
Whitepaper (Tag-Name: whitepaper),
Templates (Tag-Name: template),
Release-Differenzierung bei Changelogs (Tag-Name: release-X.X.X).

6. Abbildungen

Abbildungen zu einer Seite werden stets im Unterordner images unterhalb des Antora-Moduls abgelegt, in dem sich die Seite befindet (s. Antora-Dokumentation zur Struktur einer Komponente).

Abbildungen sollten mit diagrams.net als <Name Abbildung>.dn.svg erstellt werden.

Diagramme, die mit dem Enterprise Architect erstellt werden, oder Screenshots, dürfen auch weiterhin im PNG-Format eingebunden werden.

Tabelle 1. Namensschema für Namen von Abbildungen aus diagrams.net
Namen für Abbildungen
Schema	`<Name Abbildung gemäß allgemeinem Namensschema für Dokumentation>.dn.svg`
Beispiel	`beispiel.dn.svg`
Hinweis	`dn bedeutet: erstellt mit diagrams.net`

Wenn ein Antora-Modul sehr viele Bilder enthält, kann auch eine Unterstruktur unterhalb von /images angelegt werden, z.B. /images/unterordner.

Eine Abbildung muss folgende Informationen enthalten:

eine Beschreibung,
einen für die Seite eindeutigen Anker,
(optional) eine Angabe über die anzuzeigende Breite.

Die folgenden Beispiele zeigen, wie Abbildungen in Seiten aussehen können.

Listing 10. Beispiele für Abbildungen

[[image-beispiel]]
.Beispiel
image::beispiel.dn.svg[]

[[image-beispiel-unterordner]]
.Beispiel mit Unterordner
image::unterordner/beispiel.dn.svg[]

[[image-beispiel-skaliert]]
.Beispiel mit Skalierung
image::unterordner/beispiel.dn.svg[width="400"]

Eingebundene Abbildungen können wie üblich über einen Querverweis referenziert werden:

<<image-beispiel>>

oder, wenn das eingebundene Bild in einer Seite in einem anderen Modul oder einer anderen Komponente liegt:

xref:component:module:file.adoc#image-beispiel[Text].

Beispiele für Abbildungen finden sich außerdem in Seitenvorlage Abbildungen.

7. Tabellen

In AsciiDoc wird eine Tabelle über folgende Syntax definiert:

Listing 11. Tabelle einfügen

|====
|Zelle 11|Zelle 12|Zelle 13|Zelle 14
|Zelle 21|Zelle 22|Zelle 23|Zelle 24
|Zelle 31|Zelle 32|Zelle 33|Zelle 34
|====

Das Ergebnis ist folgende Tabelle:

Zelle 11

Zelle 12

Zelle 13

Zelle 14

Zelle 21

Zelle 22

Zelle 23

Zelle 24

Zelle 31

Zelle 32

Zelle 33

Zelle 34

In einem IsyFact-Dokument muss eine Tabelle aber auch:

eine Tabellenüberschrift enthalten,
eindeutig identifizierbar und referenzierbar sein und
mit einer Kopfzeile beginnen.

Hierfür soll folgende Syntax verwendet werden:

Listing 12. Tabelle einfügen in IsyFact

[[table-beispiel]]
.Beispiel einer Tabelle
[cols="1s,1,1,1",options="header"]
|====
|Spalte 1|Spalte 2|Spalte 3|Spalte 4

|Zelle 11|Zelle 12|Zelle 13|Zelle 14
|Zelle 21|Zelle 22|Zelle 23|Zelle 24
|Zelle 31|Zelle 32|Zelle 33|Zelle 34
|====

Das Ergebnis sieht dann so aus:

Tabelle 2. Beispiel einer Tabelle
Spalte 1	Spalte 2	Spalte 3	Spalte 4
Zelle 11	Zelle 12	Zelle 13	Zelle 14
Zelle 21	Zelle 22	Zelle 23	Zelle 24
Zelle 31	Zelle 32	Zelle 33	Zelle 34

Die Tabelle kann im AsciiDoc-Text über ihren Anchor referenziert werden:

<<table-beispiel>>

Beispiele für Tabellen finden sich außerdem in Seitenvorlage Tabellen.

8. Listings

Listings müssen folgende Informationen enthalten:

eine Beschreibung,
einen für die Seite eindeutigen Anker,
(sofern möglich) Angaben zum Syntax Highlighting.

Das Beispiel-Listing zeigt ein vollständiges Beispiel.

Listing 13. Beispiel-Listing

[[listing-hallowelt]]
.HalloWelt.java
[source,java]
----
public class HalloWelt {
    public static void main(String[] args) {
        System.out.println("Hallo Welt");
    }
}
----

Die Ausgabe sieht wie folgt aus:

Listing 14. HalloWelt.java

public class HalloWelt {
    public static void main(String[] args) {
        System.out.println("Hallo Welt");
    }
}

Listings nutzen Syntax Highlighting, um ihren Inhalt farblich hervorzuheben. Als Produkt wird hierzu highlight.js genutzt. Ist für den Inhalt des Listings Syntax Highlighting verfügbar, muss es genutzt werden.

Die Übersicht aller unterstützten Inhalte zeigt, für welche Inhalte Syntax Highlighting verfügbar ist.

Verweise auf Listings nutzen, wie üblich, den Anker.

Listing 15. Verweise auf Listings

// Verweis innerhalb einer Seite
<<listing-hallowelt>>

// Verweis zwischen Seiten
xref:version@component:module:file.adoc#listing-hallowelt[Text des Verweises]