|
| |
Dokumentation mit DocBook
www.oasis-open.org/docbook.
Dokumentation : :
DocBook : Übersicht
19-Sep-2002/09-Jan-07
Übersicht
DocBook bietet ein System, um strukturierte Dokumente mit SGML oder
XML zu schreiben. Im Folgenden werde ich mich auf die XML-Variante von
DocBook beschränken, da die SGML-Variante zunehmend veraltet.
DocBook unterschiedet sich von Systemen wie
 POD
oder LaTeX/
latex2html in einigen Aspekten:
- "Text" in einem DocBook Dokument sollte besser als "Textdaten"
verstanden werden, ein DocBook Dokument ist eher eine
menschenlesbare Datenbank.
- Der Standard "DocBook" schreibt vor, wie gültig Dokumente
aufgebaut sein müssen und wie die Ausgabe aus einem DocBook Dokument
"auszusehen" hat. Ich stelle hier "aussehen" in Anführungszeichen,
da DocBook Dokumente nicht darauf beschränkt sind, auf dem
Bildschirm angeschaut zu werden. Sie können genauso in
Sprachinformationen umgewandelt werden, zum Beispiel für ein
Autonavigationssystem. (Stellen Sie sich vor, wie Sie von Ihrem
Wagen gefragt werden: "Möchten Sie die Version 3 von KDE jetzt
installieren?")
- Wenn Sie in ein Ausgabeformat umgewandelt werden, werden DocBook
Dokumente genauestens überprüft, ob Sie in eine gegebene Struktur
passen. Diese Struktur wird in sogenannten Dokumenttypbeschreibung
(engl.: "document type descriptions") oder kurz DTDs definiert.
- Mit Änderungen in der DTD können beliebige Ansprüche mit einem
DocBook Dokument realisiert werden. Zum Beispiel kann das
Organisationskommitee einer Konferenz die DocBook DTD verändern, so
dass alle Artikel der Konferenz ein gleiches Layout haben und alle
Autoreninformationen enthalten sind.
Die speziellen Besonderheiten von DocBook schaffen DocBook Dokumente,
die so nicht oder nur sehr schwer in POD oder LaTeX zu realisieren sind.
Dank ihrer Struktur sind DocBook Dokumente einfach zu erstellen, zu
bearbeiten oder mit einem Programm abzufragen.
Zum Beispiel laden wir das XML::DOM Modul für Perl um XML
entsprechende Dokumente zu erreichen und Python wird mit dem
xml.dom Modul ausgeliefert, das für dieselben Zwecke entworfen
wurde.
Das Wold Wide Web Consortium (W3C,
www.w3c.org)
hat eine Sprache für XML Übersetzungen definiert, die XSLT genannt wird
(für Beispiele siehe
www.w3.org/TR/xslt
und www.oasis-
open.org/cover/xsl.html). XSLT selbst ist eine Sprache, die mittels
SGML definiert wurde und XML und XSL gleich aussehen lässt: viele spitze
Klammern.
Es gibt viele Tools, die DocBook
Quellen in HTML, TeX, GNU Texinfo und viele andere Formate --
einschließlich Audio -- transformieren. Das ist auch ein Unterschied zu
den Quelltextformaten, die wir vorher besprochen haben, wo nur eine
einzige Anwendung die Transformation vorgenommen hat.
Beliebte Umwandlungswerkzeuge sind:
Die Installation dieser beiden Werkzeuge inklusiver der nötigen
DSSSL- oder
XSL-Stylesheets
ist ein bisschen verzwickt, also empfehle ich den Anfängern, die
Installation mit .deb oder .rpm Paketen zu tätigen.
Da die beiden Werkzeuge Übersetzer für allgemeinere Zwecke sind, sind
beide nicht darauf beschränkt, DocBook Dokumente zu transformieren. Wenn
Sie sie mit den richtigen Stylesheets füttern, werden die beiden auch
andere Transformationen für Sie ausführen.
Die DocBook/XML Syntax ähnelt HTML. Der grundlegende Unterschied
zwischen beiden ist die Strenge, mit der die Syntax eingehalten werden
muss. Viele HTML Browser vergeben sehr stark nicht beendete Element und
sie ignorieren stillschweigend unbekannte Element oder Attribute.
DocBook/XML Übersetzer lehnen nicht-DTD konforme Eingaben mit einer
detaillierten Fehlermeldung ab und weigern sich in diesem Fall
irgendeine Ausgabe zu erzeugen.
DocBook/XML wird in verschiedenen Varianten gesprochen, wobei die
Varianten sich in der Interpretation des schließenden Tags eines
Elements unterscheiden. Der ausdrücklichtste Dialekt schließt immer
<tag> mit </tag>. Eine weitere Variante
erlaubt das schließende Tag zu </> abzukürzen, die nächste
erlaubt, das schließende Tag für leere Elemente ganz wegzulassen. Ich
ziehe es vor, jedes End-Tag auszuschreiben, ein Stil, der bewiesene
Vorteile in tief geschachtelten Strukturen, wie geschachtelten Listen,
hat. Also wird in diesem Artikel nur die Form <tag> ... </tag>
erscheinen.
Spezielle Zeichen werden wie in HTML mit der Kaufmannsund-Semikolon-
Konvention geschrieben. Die am häufigsten benutzten speziellen Zeichen
sind
- Kaufmannsund, "
&"
- Kleiner-Als Zeichen, "
<" und
- Größer-Als Zeichen, "
>".
Kommentare werden mit "< ! - -" und "- - >"
geklammert. (natürlich ohne Leerzeichen dazwischen - Chefred.)
Dokumentstruktur
Wie schon bemerkt, müssen DocBook Dokumente einer Struktur folgen,
die in einer DTD definiert ist. Jedes Dokument beginnt mit der Auswahl
einer bestimmten DTD:
<!DOCTYPE (1)
book (2)
PUBLIC "-//OASIS//DTD DocBook XML V4.1//EN" (3)
"/usr/share/sgml/db41xml/docbookx.dtd" (4)
[ ] (5)
>
wobei ich den Ausdruck (von "<" bis ">") für eine bessere Analyse
aufgeteilt und zum Bezeichnen Zahlen in Klammern hinzugefügt habe:
- Teil (1) teilt dem System mit, dass wir unsere DTD auswählen
möchten.
- Teil (2) definiert das Element
book
als "Root"- Element unseres Dokuments.
- Teil (3), der "Public Identifier" (dtsch. "Öffentlicher
Bezeichner" wählt die DTD aus. Der "Public Identifier" ist der
String in den Anführungszeiten.
- Teil (4), der "System Identifier" (dtsch. "Systembezeichner"),
sagt den Übersetzungswerkzeugen, wo Sie die DTD auf dem lokalen
System finden können. In den eckigen Klammern bei Teil (4) könnten
wir sogenannte "Entity"-Definitionen platzieren, aber ich möchte in
dieser Einführung nicht so sehr ins Detail gehen, also lassen wir
diesen Platz frei.
Nun beginnen wir den Text mit den "Root"-Element, in unserem Fall
book. Welche Elemente in
book passen, ist in der DocBook
DTD definiert. Es sind, z.B. bookinfo oder chapter.
Für eine komplette Liste aller erlaubten Elemente, schauen Sie in den
"Definitive Guide". Die Elemente, die innerhalb von bookinfo
oder chapter erlaubt sind, sind, wie alle anderen Elemente
auch, in der DTD definiert. Der einzige Weg, ein gültiges Dokument zu
erzeugen, ist, alle Regeln die von der DTD vorgeschrieben werden, zu
beachten.
Was auf den ersten Blick wie eine Behinderung aussehen könnte --
Regeln? Wofür Regeln? -- ist der Schlüssel für einen programmtechnischen
Zugriff auf das Dokument. Wenn das Dokument der DTD entspricht, können
alle Nachbearbeiter darauf aufbauen. Gut für die Programmierer der
Übersetzer! Ich muss zugeben, dass die Anzahl der Elemente und ihre
Abhängigkeit untereinander schon schwer aufzunehmen ist. Jedoch sind die
Beziehungen logisch: Ein Kapitel enthält einen oder mehr (einführende)
Absätze und eine oder mehr Stufe 1-Abschnitte. Auf der anderen Seite
enthält kein Abschnitt ein Kapitel, das wäre unsinnig. Eine Ausgabe des
"Definitve Guide" in der Nähe Ihrer Tastatur hilft auch, DocBook zu
lernen. Weiterhin gibt es auch eine kurze Zusammenstellung der oft
benutzten Tags.
Hier kommt ein sehr kurzes, aber komplettes DocBook Dokument:
<§!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1//EN"
"/usr/share/sgml/db41xml/docbookx.dtd" []>
<§book>
<§bookinfo>
<§title>XYZ (Version 0.8.15) Benutzerhandbuch<§/title>
<§/bookinfo>
<§chapter id = "kapitel-einfuehrung">
<§title>Einfuehrung</§title>
<§para>
Dieses Kapitel bietet eine schnelle Einfuehrung zu XYZ.
<§/para>
<§sect1 id = "abschnitt-syntax">
<§title>Syntax</§title>
<§para>
In diesem Abschnitt praesentieren wir einen Ueberblick
ueber die Syntax der Sprache XYZ.
<§/para>
<§/sect1>
<§sect1 id = "abschnitt-basisbibliothek">
<§title>Basisbibliothek</§title>
<§para>
Auch wenn keine zusaetzlichen Bibliotheken in ein
XYZ Programm geladen werden, hat es Zugriff auf einige
Funktionen aus der Basisbibliothek.
<§/para>
<§/sect1>
<§/chapter>
<§chapter id = "kapitel-befehle">
<§title>Befehle<§/title>
<§sect1 id = "abschnitt-interaktive-befehle">
<§title>Interaktive Befehle<§/title>
<§para>
...
<§/para>
<§sect2 id = "section-interaktive-argumentlose-befehle">
<§title>Argumentlose Befehle<§/title>
<§para>
...
<§/para>
<§/sect2>
<§/sect1>
<§sect1 id = "section-nicht-interaktive-befehle">
<§title>Nicht-Interaktive Befehle<§/title>
<§para>
...
<§/para>
<§sect2 id = "section-nicht-interaktive-argumentlose-befehle">
<§title>Argumentlose Befehle</§title>
<§para>
...
<§/para>
<§/sect2>
<§/sect1>
<§/chapter>
<§/book>
Anmerkung: Entfernen sie alle "§"-Zeichen die sie finden damit der
Quelltext funktioniert.
Um dem nach Erfolg strebenden DocBook Autor einen Sinn aus den Massen
von Elementen zu geben, die DocBook definiert, habe ich eine Anzahl von
nützlichen Tags zusammengestellt, die oft benutzt werden.
Basisabschnitt-Tags definieren die äußersten Elemente eines jeden
Dokuments.
- book
<book> Absätze oder Kapitel
</book>
- article
<article>
Absätze oder Stufe 1 Abschnitte
</article>
Abschnittselemente teilen das Dokument in logische Teile wie Kapitel,
Abschnitte, Absätze, usw.
-
chapter, sect1, ..., sect6
<chapter id = "marke">
title
gefolgt von
Absätze oder Abschnitte der Stufe N+1
</chapter>
Definiert einen Abschnitt. Normalerweise tragen Kapitel und
Abschnittselemente das id-Attribut, das erlaubt, auf
diese Elemente zu verweisen, z. B. <xref linkend =
"marke"></xref>.
- para
<para> Absatztext
</para>
Gruppiert mehrere Zeilen von Text zusammen zu einem Absatz. Das
ist das am meisten benutzteste Element in vielen Dokumenten.
- programlisting
<programlisting role = "sprache">
Programmtext
</programlisting>
Formatiert ein längeres Stück Programmtext -- und behält die
Zeilenumbrüche bei. Es wird angenommen, dass das Programm in der
Sprache geschrieben ist, die im Attribute role
angegeben ist. Beachten Sie, dass alle speziellen Zeichen innerhalb
von programlisting
ihre Bedeutung behalten!
Das bedeutet, dass Sie die Kontrollzeichen "<", ">",
und "&" nicht innerhalb dieses Elements benutzen
können. Es gibt verschiedene Lösungen für diese Problem. Entweder
ersetzen Sie alle Kontrollzeichen durch ihre entsprechenden
Umschreibungen ("<", ">", und "&"
in unserem Beispiel) oder Sie umgeben den Programmcode mit einem
CDATA wie zum Beispiel
<programlisting>
<![CDATA[
cout << "value = <" << &p << ">\n";
]]>
</programlisting>
oder, wenn das Programm in der Datei my-program.pl
gespeichert ist, fügen Sie die ganze Datei so ein:
<programlisting>
<inlinemediaobject>
<imageobject>
<imagedata format = "linespecific"
fileref = "my-program.pl"></imagedata>
</imageobject>
</inlinemediaobject>
</programlisting>
Generieren die drei typischen Arten von Listen.
Die items oder definitions werden typischerweise von
einem oder mehreren Absätzen dargestellt, aber sie können auch
Programmtext enthalten. Die terms sind normalerweise einzelne
Wörter, aber keine Absätze.
- Gruppierte Liste
<itemizedlist>
<listitem>
Erstes Element
</listitem>
<listitem>
Zweites Element
</listitem>
...
</itemizedlist>
- Nummerierte Liste
<enumeratedlist>
<listitem>
Erstes Element
</listitem>
<listitem>
Zweites Element
</listitem>
...
</enumeratedlist>
- Beschreibungsliste
<variablelist>
<varlistentry>
<term>Erster Begriff</term>
<listitem>
Erste Definition
</listitem>
</varlistentry>
<varlistentry>
<term>Zweiter Begriff</term>
<listitem>
Zweite Definition
</listitem>
</varlistentry>
...
</variablelist>
emphasis-
<emphasis>hervorzuhebender Text</emphasis>
Hebt einen kurzen Teil des Dokuments hervor;
normalerweise ein einziges Wort.
filename-
<filename>Dateiname oder Verzeichnisname</filename>
Markiert einen Ausdruck als einen Dateinamen.
literal-
<literal>literal something</literal>
<literal role = "classification">etwas Wörtliches</literal>
Markiert ein Wort als einen wörtlichen Ausdruck.
Benutzen Sie dieses Tag nur als letzte Möglichkeit,
wenn es kein anderes Tag gibt.
Um die schlechten Gewissen zu beruhigen:
literal wird oft mit dem role-Attribut dekoriert,
das genauer die Art des wörtlichen Ausdrucks beschreibt.
replaceable-
<replaceable>Platzhalter</replaceable>
Markiert eine Meta-Variable
title-
< title>Titel</ title>
Weist einem Abschnitt oder einem formalen Element,
wie eine Tabelle, einen Namen zu.
Querverweise verweisen auf andere Teile im selben DocBook Dokument
oder auf andere Dokumente im World Wide Web. Ziele der ersteren sind
alle Elemente, die ein id-Attribut tragen, Ziele der
zweiten Art werden mit einer URL ("Universal Resource Locator")
ausgewählt.
link-
<link linkend = "ziel">element</link>
Erzeugt einen (Hyper-) Link zu dem Punkt,
der durch ziel im aktuellen Dokument identifiziert wird.
ulink-
<ulink url = "komplette URL">element</ulink>
Erzeugt einen Hyperlink zu einem
übers WWW erreichbaren Dokument,
das mit einer kompletten URL beschrieben wird.
Eine komplette URL enthält auch das Protokoll,
zum Beispiel http://.
xref-
<xref linkend = "ziel"></xref>
Erzeugt einen (Hyper-) Link zu dem Element,
dass mit ziel im aktuellen Dokument identifiziert ist.
Ein Übersetzer wird Text um das xref Element hinzufügen.
Zum Beispiel könnte ein xref zu einem Abschnitt
mit dem Text "siehe Abschnitt" umgeben werden.
Uff, ich habe Tonnen von Zeug ausgelassen, aber nur, um Ihnen einen
weichen, nicht verängstigenden Einstieg zu bereiten. Einige große Dinge,
die DocBook kann, die ich hier nicht besprochen habe, sind
- Tabellen,
- Grafiken (mit automatischer Auswahl des "passenden" Formats) und
- automatische Erzeugung von Inhalts- und Stichwortverzeichnissen.
Ich habe auch alles ausgelassen, was mit dem Verändern der DTD oder
den Stylesheets zusammenhängt.
- Pros
-
- DocBook ist ein offizieller W3C Standard
- Zugriff auf den Text mit (benutzerdefiniertem) Text
- Texte tragen viele Formatierungen
- Kontras
-
- Langsame Transformation
- Das DocBook Format ist sehr ausführlich. Wenn der Autor
keinen speziellen Editor benutzt, ist sehr viel Tipparbeit
notwendig.
Credits
Dieser Text basiert auf Christoph Spiels Artikel "Schreiben von
Dokumentation, Teil IV: Texinfo" in der Übersetzung von Siegfried
Schnieders, veröffentlicht in der Linux Gazette.
 |
DocBook. von Norman Walsh, Leonard Muellner
Taschenbuch - 656 Seiten - O'Reilly UK
Maße: 18 x 23 cm
Erscheinungsdatum: Oktober 1999
ISBN: 1565925807
UK-Preisempfehlung*: £25.95
Preis: EUR 43,81
Das Buch ist auch online unter
www.docbook.org/tdg/en
verfügbar. |
Topics covered: DocBook basics and SGML/XML, publishing books with
DocBook, stylesheet languages: FOSIs, DSSSL, CSS and XSL, DocBook
element reference, attribute entities, class entities, common entities,
module entities, local attribute entities, mixture entities, module
parameter entities, role attribute parameter entities, character
entities,customising DocBook, converting DocBook to XML.
 |
DocBook XML Publishing (With CD-ROM). von Kara Pritchard,
Joe Brockmeier
US-Preisempfehlung*: $39.99
Preis: EUR 43,36
Taschenbuch - 400 Seiten - Prima Tech
Maße: 18 x 23 cm
Erscheinungsdatum: April 2001
Auflage: Bk&Cd-Rom
ISBN: 0761533311 |
Synopsis:
Document Type Definition (DTD) is the definition of a document type in
SGML. DocBook is a popular DTD. This book is aimed at the writing
community that wish to take advantage of this technology.
Netmarks
Linux Gazette: "Schreiben von Dokumentation, Teil IV:
Texinfo", von Christoph Spiel, Übersetzung von Siegfried Schnieders.
DocBook.org: Offizielle Website,
www.docbook.org.
Norman Walsh - Website vom Vorsitzenden des DocBook
Steering Committee,
nwalsh.com.
Oasis: DocBook Steering Committee,
www.oasis-open.org/committees/docbook.
Anmerkungen
| |
 DocBook: |
|
Name: Besucher.
Online: 25 aktive User.
|
| Login |
Logout
|
|
|
Benachrichtigen bei Änderungen: |
|
|
|
|
Debian GNU/Linux 3.1 »Sarge«,
mit Debian-Anwenderhandbuch.
DVD-ROM +
Bonus-DVD
 EUR
49,90
(versandkostenfrei)
|
Debian GNU/Linux Power Pack.
von
Peter H. Ganten und
Wulf Alex.
946 Seiten, zwei DVDs
EUR 69,95
(versandkostenfrei) |
|
Ubuntu: |
Ubuntu/Kubuntu 5.10,
mit Handbuch.
EUR
29,90
(versandkostenfrei)
|
|
SuSE
Linux: |
SUSE
Linux 10.0 deutsch.
von Novell
EUR
48,95
(versandkostenfrei)
|
SuSE
Linux 9.3 Professional
von Novell.
EUR
82,99
(versandkostenfrei)
|
SuSE
Linux 9.3 Professional Update.
von Novell
EUR 59,95
(versandkostenfrei) |
|
Red
Hat Linux: |
|
Red Hat Linux
Professional Workstation.
EUR 99,95
(versandkostenfrei)
|
Red Hat Linux 9 Personal.
Red Hat Linux 9 Professional.
ab EUR 39,99
(versandkostenfrei) |
|
 |
Thematisch verwandte Subsites:
Apple,
BSD,
Hardware,
Internet,
Microsoft Windows,
Networking,
Open Content,
Open Source & Free Software,
Politik,
Recht,
Safety,
Security,
Shopping,
Software,
The Tark,
Webworking,
Wissen. |
 |
|
|
Kefk Network :
GNU/Linux |
About |
Wiki.
