Skip to main content

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.

A code sample. In the code, there are callout icons labelled 1 and 2. Below the code, there are matching 1 and 2 callout icons, each with a text description of the corresponding line of code.

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.

    Element context menu shows a search field and a list of elements that are valid at the current position.

  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.