Arbeiten mit Elementen
Zurück Kapitel 4. Editieren von Dokumenten Weiter

Arbeiten mit Elementen

Das DocBook-Dokument wird über DocBook-Elemente aufgebaut. Dabei werden drei Arten von Elementen unterschieden:

  1. Strukturierende Elemente

    Strukturierende Elemente geben den Aufbau bzw. die Gliederung und die Dokumentart des Dokuments wieder. Darunter fallen z.B. book, chapter, glossary, index usw.

  2. Block-Elemente

    Block-Elemente zeichnen den Inhalt aus und erzwingen i.d.R. einen Zeilenumbruch vor und nach dem Element. Darunter fallen bspw. para, itemizedlist, figure usw.

  3. Inline-Elemente

    Inline-Elemente "fliessen mit dem Text" und erzwingen keinen Zeilenumbruch. Ein xref oder link gehört beispielsweise dazu.

Beim Editieren muß der Redakteur den Text in adäquate DocBook-Elemente "verpacken" - dazu stehen eine fast unüberschaubare Menge an unterschiedlichen Elementen zur Verfügung. Eine Auflistung sämtlicher Elemente ist auf der DocBook-Webseite untergebracht.

Von den über 400 gelisteten Elementen werden jedoch meist nur eine sehr viel geringere Anzahl für die eigenen Dokumentationen benötigt. In Anhang A, DocBook-Elemente wird die Verwendung und Bedeutung der wichtigsten Elemente erläutert.

Markup escapen

Anmerkung

Soll DocBook- oder XML-Markup lediglich ausgegeben statt ausgewertet werden, so müssen Teile davon "escaped" werden. Beispielsweise die Zeichen, die ein DocBook-/XML-Element einleiten (<) und beenden (>), müssen als Entity notiert (< sowie >) werden, damit sie beim Generieren der Ausgabeformate auch "buchstäblich" ausgegeben werden.

Bei längeren Textpassagen, die eventuell XML-Markup enthalten, kann die gesamte Textpassage als CDATA markiert und escaped werden: 

<section>
   <title>Beispiel CDATA</title>
   <para>Die DocBook-Elemente dieses Abschnitts werden ausgegeben statt interpretiert.</para>
</section>

CDATA-Quellcode.  

<![CDATA[ 
 zu escapender Quellcode  
]]>

IDs

Mit einer id kann ein eindeutiger Identifizierer innerhalb eines Dokument für ein Element vergeben werden. Über Links wie link oder xref können diese identifizierbaren Elemente angesprungen werden. Im Folgenden ein Quelltext-Beispiel:

Beispiel 4.1. Verlinkung von Elementen

<section id="anker">
   <title>Beispieltitel</title>
   <para>Nullam consequat. Phasellus iaculis, urna non sodales pulvinar, tellus ligula
    pellentesque mi, eu tempor nisl nisi non lectus. </para>
    <para> Nam accumsan tincidunt elit. Suspendisse rutrum luctus nisi. Siehe auch <link linkend="anker">Linkziel</link>.</para>
</section>

Kommentare

Kommentare im Sinne von XML-Kommentaren erscheinen nicht in den Ausgabeformaten.

Anmerkung

Kommentare im DocBook-Quelltext sind für die Zusammenarbeit mit anderen Redakteuren sowie für eigene Notizen im Dokument sinnvoll und zur Kommentierung wird ausdrücklich aufgerufen. Auf Quelltext-Ebene wird ein Kommentar in XML-Syntax (<!-- Kommentar /--> eingegeben.

Validieren

zpub kann ausschließlich valide DocBook-XML-Dokumente gemäß der DTD verarbeiten. Sollte der verwendete Editor nicht sicherstellen, dass nur valide Dokumente produziert werden, muß dies der Redakteur übernehmen. Hierfür stehen unterschiedliche Hilfsmittel bereit. Unter einem GNU/Linux-Betriebssystem beispielsweise via: 

xmllint --noout  --postvalid Dateiname.xml

Anmerkung

Bevor zpub versucht, die unterschiedlichen Ausgabeformate eines Dokuments zu generieren, wird intern xmllint zum Überprüfen der Syntax der xml-Datei genutzt. Die Ausgaben hierbei - insbesondere die Fehermeldungen - informieren über eventuell gefundene Probleme mit der Docbook-XML-Datei des Dokuments. Für jede Revision eines Dokuments kann die Logdatei, die auch die xmllint-Ausgaben enthält unter der folgenden URL abgerufen werden:

https:// $Instanz .zpub.de/ $Dokument /archive/ $Revision / $Style /zpub-render.log

Zurück Nach oben Weiter
Arbeiten mit Serna Free Zum Anfang Wiederverwendbarer Inhalt