Software- und Codedokumentation

2 min read

Codeblöcke in Ihren Inhalten

Zu den häufigsten Anforderungen bei der Dokumentation von Software zählt das Schreiben von Codeblöcken. Das wichtigste Element hierfür ist programlisting.

So fügen Sie ein programlisting-Element hinzu:

  1. Positionieren Sie den Cursor am Anfang der Zeile, in die der Codeblock eingefügt werden soll.

  2. Drücken Sie Alt + Enter ⏎ (Windows) oder Command ⌘ + Enter ⏎ (Mac), um den Kontextmenü „Elemente“ anzuzeigen.

  3. Suchen Sie das programlisting-Element und wählen Sie es aus.

    Sobald Sie ein programlisting-Element hinzufügen, erscheint ein Codefragment-Feld im Topic.

  4. Fügen Sie Ihren Code in das Codefragment-Feld ein.

Das programlisting-Element wird manchmal als „verbatim“ bezeichnet, da der in das Element eingefügte Code exakt so dargestellt wird, wie er im Editor erscheint. Beispielsweise werden Leerzeichen und Zeilenumbrüche beibehalten, um den Code korrekt darzustellen. Einige andere Elemente funktionieren genauso, wie z. B. screen oder literallayout.

Beispiel 49. Ein programlisting-Beispiel

Hier wurde eine Javascript-Funktion innerhalb eines programlisting-Elements hinzugefügt. So sieht der Code in der Ausgabe aus.

function myFunction() { ①
    var x = "", i;
    for (i=0; i<5; i++) {
        x = x + "The number is " + i + "<br>";
    }
    document.getElementById("demo").innerHTML = x; ②
}
①

Dies ist eine Javascript-Funktion

②

Hiermit wird ein Wert für ein Element mithilfe des DOM-Modells festgelegt.

In dem gezeigten Beispiel wird ein Codeblock innerhalb des programlisting-Elements hinzugefügt. Die Javascript-Funktion enthält (1) in der ersten Zeile und (2) in der letzten Zeile. Hierbei handelt es sich um Callouts, mit denen Sie Anmerkungen erstellen können.

Anmerkungen zu Codeblöcken erstellen

Mithilfe des Elements calloutlist und von co-Elementen können Sie Anmerkungen erstellen. In der veröffentlichten Ausgabe fungieren die Callouts als anklickbare „Hotspots“, mit denen sich Teile des Codes hervorheben lassen. Klickt man auf einen „Hotspot“, gelangt man zum Callout-Erklärtext für diesen „Hotspot“.

Beispielsweise besitzt das Codebeispiel in der nachstehenden Abbildung zwei Callout-„Hotspots“, die mit 1 und 2 bezeichnet sind. Unterhalb des Codebeispiels befinden sich Ziffern, die den Hotspots entsprechen, und neben jeder Ziffer steht eine Anmerkung, die über den Zweck des entsprechenden Codeabschnitts aufklärt.

So erstellen Sie Anmerkungen mit calloutlist:

  1. Wählen Sie eine Position im Codeblock, an die ein Callout-„Hotspot“ gesetzt werden soll.

  2. Drücken Sie Alt + Enter ⏎ (Windows) oder Command ⌘ + Enter ⏎ (Mac), um den Kontextmenü „Elemente“ anzuzeigen.

  3. Wählen Sie das co-Element aus und geben Sie ihm im Abschnitt Elementattribute einen xml:id-Wert. Jedes co-Element muss einen xml:id-Wert besitzen, der in diesem spezifischen Topic eindeutig ist. Zum Beispiel können Sie dem ersten co-Element die xml:id id_1, dem zweiten co-Element die xml:id id_2 und so weiter geben.

  4. Fügen Sie hinter dem programlisting-Element, das Ihren Codeblock enthält, ein calloutlist-Element hinzu.

    Tipp

    Meist empfiehlt es sich, die programlisting- und calloutlist-Elemente in ein example-Element einzufügen, so dass sie sich alle in einem gemeinsamen „Container“ (dem example-Element) befinden.

  5. Weisen Sie außerdem jedem callout in der calloutlist eine xml:id zu, die sich von denen in den co-Elementen unterscheidet, z. B. „callout_1“, „callout_2“ usw. Auch diese IDs müssen eindeutig sein.

  6. Verknüpfen Sie die co-Elemente mit den callout-Elementen:

    1. Fügen Sie für jedes co-Element ein linkends-Attribut hinzu. Stellen Sie den Wert des linkends-Attributs auf den xml:id-Wert von callout ein, mit dem Sie es verknüpfen möchten.

    2. Fügen Sie für jedes callout-Element das Attribut arearefs hinzu. Geben Sie als Wert des arearefs-Attributs den xml:id-Wert des co-Elements ein, mit dem es verknüpft werden soll.