| Firebird Documentation Index → Firebird Docwriting-Anleitung → DocBook XML – Eine Einleitung |
|
|
|
Das Format der Wahl für die Dokumentation innerhalb des Firebird manual Modul ist DocBook XML. Sollten Sie bisher nicht vertraut mit XML und/oder DocBook sein, folgen noch kurze Einleitungen in XML und DocBook. Beachten Sie, dass diese Einleitungen nur einen vereinfachtes Bild zeigen können. Aber das ist auch der Vorteil: Sie müssen kein DocBook-Experte sein um Firebird-Dokumente zu schreiben. Sie benötigen lediglich Basiswissen - welches Sie in innerhalb einer halben Stunde von den u.a. Absätzen erlernen können - und ein wenig Erfahrung bei der Zuweisung von DocBook XML-Tags zu Ihren Texten (diese werden Sie aber schnell während des Schreibens erlernen).
Überspringen Sie die allgemeinen XML-Grundlagen, wenn Sie bereits alles über XML-Element, -Tags, -Attribute, -Rendering und -Multichannel-Publishing wissen.
Überspringen Sie beide Grundlagen, wenn Sie auch schon Erfahrungen als DocBook-Author haben.
Obwohl wir strikt empfehlen, dass Sie zumindest versuchen sollten, Ihre Dokumente im DocBook-Format abzugeben, akzeptieren wir natürlich auch, dass einige Leute nicht die Zeit haben sich einzuarbeiten (oder ihre existieren Dokus ins DocBook-Format zu konvertieren). Wenn dies auf Sie zutrifft, sprechen Sie dies bitte in der firebird-docs list an. Wir werden sicherlich keine nützliche Dokumentation ablehnen, weil sie im falschen Format vorliegt.
XML steht für Extensible Markup Language, was vereinfacht ausgedrückt soviel bedeutet wie, Standardtext mit Markup-Tags versehen. Ein typisches XML-Text-Fragment könnte so aussehen:
<paragraph> <loud>'No!'</loud> she screamed. <scary>But the bloody hand <italics>kept on creeping</italics> towards her.</scary> <picture file="bloody_hand.png"/> </paragraph>
Im obigen Beispiel werden die Wörter und Sätze in spitze Klammern eingeschlossen. Dies sind die Markup-Tags.
<italics> ist ein Start-Tag
, </italics> ist ein
End-Tag, und <picture
file="bloody_hand.png"/> ist ein alleinstehender Tag, offiziel
empty-element tag genannt. XML-Tags werden immer wie folgt formatiert:
Tabelle 1. Format of XML tags
| Tag-Typ | Beginnt mit | Endet mit |
|---|---|---|
| Start tag | < |
> |
| End tag | </ |
> |
| Empty-element tag | < |
/> |
Immer noch unserem Beispiel folgend, sind
paragraph, loud,
scary, italics and
picture Tag-Namen. Im
Tag <picture.../> ist file="bloody_hand.png" ein
Attribut, mit file als Attributnamen
und bloody_hand.png als Attributwert.
Attributwerte stehen immer in Anführungszeichen; einfache und doppelte sind beide erlaubt.
XML erlaubt Ihnen beliebige Tags zu definieren, solange Sie diese korrekt erstellen. Somit sind <thistag>,
<thattag>, und <this_is_not_a_tag/> wohlgeformte (well-formed) XML-Tags.
(XML welches dem Standard folgt, nennt man
wohlgeformte (engl. well-formed); Der Begriff
valid wird nur in spezifisch definierten Implementationen verwendet – DocBook XML zum Beispiel).
Natürlich sollen die Tags selbst nicht im finalen Dokument erscheinen (das Dokument wird ja von den Lesern angeschaut). Vielmehr kümmern sie sich um die Ausgabe, die durch die Tags beeinflusst wird. XML, wenn es zum Schreiben von Dokumentationen Verwendung findet, ist ein typisches Quellformat, vorgesehen für die Verarbeitung durch Software, welche hübsch formatierte Ausgaben generiert. Die Ausgabe wird häufig als Rendering bezeichnet.
Einige Tags sind unmissverständliche Make-Up-Anweisungen:
<italics>kept on creeping</italics>
was natürlich bedeutet, dass die Wörter kept on creeping kursiv dargestellt werden sollen. Andererseits ist
<loud>'No!'</loud>
weniger offensichtlich zu verstehen. Soll das Wort No!
in Fettdruck erscheinen? Oder unterstrichen? Oder wieder kursiv? Vielleicht soll dieser
Text von einem Sprachprogramm laut vorgelesen werden, und das Tag
<loud> weist es an die Stimme zu heben. Diese Dinge sind alle möglich, und noch mehr:
Häufig wird ein einzelnes XML Quelldokument in verschiedene Ausgabeformate gewandelt
– sagen wir, ein PDF-Dokument, eine HTML-Webseite und eine Audio-Datei. Dies wird Multichannel-Publishing (engl. multichannel publishing) genannt.
Hiermit könnte <loud> im PDF als Fettdruck angezeigt werden; in der HTML-Seite wird es zu einem fetten, roten Text; und das Audioprogramm erhöht
die Lautstärke um 50%.
Schauen wir uns die anderen Tags an. <picture.../> ist offensichtlich die Anweisung das Bild
bloody_hand.png einzufügen, und <scary>,
gut... das ist wieder weniger klar, genauso wie <loud>.
Vielleicht soll der Satz zwischen <scary>
zitternt mit Blutstropfen dargestellt werden. Vielleicht wird angsteinflößende Musik gespielt.
Dies hängt alles von den Leuten ab, die die Tags definieren und der Software die diese Interpretiert, also das Rendering.
Abschließend haben wir noch das Tag <paragraph>,
welches ein Strukturtag ist. Es erzählt uns etwas über den Platz, den die Zeilen innerhalb der internen Dokumenthierarchie
einnehmen.
Im endgültigen Dokument können Absätze mit Leerzeilen getrennt dargestellt werden.
Aber nochmal, dies hängt von der Rendering-Software ab, und denkbar sind auch Benutzerkonfigurations-Einstellungen.
Andere Strukturtags sind z.B. <chapter>, <section> und <subdocument>.
Da das Zeichen „<“ eine spezielle Bedeutung als Start eines Tags besitzt, können Sie dies nicht direkt als
literalen Wert (wörtlich) verwenden. Wenn Ihre Leser eine spitze Klammer sehen sollen, müssen Sie folgendes eintippen:
<
Dies ist ein kaufmännisches Und, gefolgt von den Buchstaben
l und t (kleiner
als), gefolgt von einem Semikolon. Sie können außerdem > (größer gleich) als schließende spitze Klammer
„>“ verwenden, müssen dies aber nicht.
XML hat viele dieser Codes; Sie heißen
entities. Einige repräsentieren Zeichen, wie
< und ä (ä, kleines a mit Umlaut) und andere dienen ganz andeen Zwecken.
Aber alle beginnen mit einem kaufmännischen Und und enden mit einem Semikolon.
Aber einen Moment... wenn alle Entitäten mit einem kaufmännischen Und starten, wie packen Sie dann ein literales kaufmännisches Und in Ihren Text? Tja, dafür gibt es ebenfalls eine Entität:
&
Somit wird diese Zeile XML:
Kernigan & Ritchie chose '<' as the less-than operator for C.
schlussendlich im Dokument zu:
Kernigan & Ritchie chose '<' as the less-than
operator for C.
Und hier noch die gute Nachricht: wenn Sie einen guten XML-Editor verwenden, dann können Sie wahrscheinlich einfach
„<“ und
„&“ eintippen wo Sie diese auch immer als Literale verwenden möchten.
Der Editor wird sicherstellen, dass sie als
< und & im XML gespeichert werden.
An späterer Stelle werden wir einige XML/DocBook-Editoren auflisten.
Es gibt ein weiteres wichtiges XML-Konzept über das Sie bescheid wissen sollten: Das Element. Ein Element ist die Kombination aus Start-Tag, einem passenden End-Tag und das ganze dazwischen. Dieses „ganze dazwischen“ wird als Element-Inhalt (engl. content) bezeichnet, und es kann wiederum andere Elemente enthalten. Elemente werden nach ihren Tags benannt. Somit können wir über Absatzelemente, Kursivelemente, etc. sprechen.
Elemente sind ein grundlegenderes Konzept als Tags. Tags sind bloß die Dinger, die Elemente identifizieren. Somit wäre es besser zu sagen, dass Tags nach ihren Elementen benannt werden. Aber da Tags leichter zu erkennen sind als ein ganzes Element, werde ich diese zuerst erläutern.
Das ist ein Element:
<loud>'No!'</loud>
Das ist auch ein Element:
<paragraph>This is an element containing <bold>another</bold> element!</paragraph>
Ein Leerelement-Tag (engl. empty-element tag) stellt das Element selbst dar. Solche Elemente haben natürlich keinen Inhalt, da sie kein Tag-Paar besitzen:
<picture file="bloody_hand.png"/>
Verwechseln Sie Inhalt nicht mit Attributen. Inhalt liegt zwischen den Tags, Attribute innerhalb der Tags. Das Leerelement des letzten Beispiels besaß ein Attribut, aber keinen Inhalt.
Ich überstrapaziere das Konzept der Elemente etwas, da die meisten Dokumentationen dazu tendieren von „Kapitelelementen“, „Titelelementen“, etc. zu sprechen. Richtiger wären aber „Kapitel-Tags“ und „Title-Tags“. Die Begriffe werden oft synonym verwendet, aber an manchen Stellen ist es wichtig die Unterschiede zu kennen.
So – das war alles was Sie über XML wissen müssen. Sie sollten nun eine grundlegende Idee haben was XML ist, wie es aussieht, was und wofür Tags sowie Elemente sind. Wie ich schon sagte: Das Gesamtbild ist deutlich vereinfacht, aber für unsere Zwecke ausreichend.
Es sollte außerdem klar sein, dass reines Schreiben von selbsterstelltem XML relativ sinnlos ist, solange Sie keine Software besitzen, die Ihre Tags verstehen. Wie sonst können Sie Ihre XML-Quellen in ein hübsch formatiertes Dokument umwandeln?
Glücklicherweise müssen wir uns hierüber keine Sorgen machen. Es stehen uns bereits einige formalisierte XML-Typen zu Verfügung, wovon jedes einen Satz Tags und, genauso wichtig, einen Satz Regeln beinhaltet. Letztere sagen uns wie die Tags zu verwenden sind. DocBook XML ist einer dieser XML-Typen.
DocBook wurde entworfen, um das Schreiben strukturierter Dokumente unter Verwendung von SGML oder XML zu verbessern (machen Sie sich keine Gedanken über SGML - wir nutzen den XML-Stamm). Dies betrifft insbesondere das Schreiben technischer Dokumente und Artikel, vor allem für Computer-relevante Themen. DocBook ist durch seine Document Type Definition bzw. DTD definiert: Ein Satz von Definitionen und Regeln, die genau beschreiben, wie ein gültiges DocBook-Dokument strukturiert ist. DocBook wurde schnell zum de facto-Standard für Computer-technische Dokumente und wird durch eine wachsende Anzahl von Werkzeugen und Anwendungen unterstützt.
Wichtige Eigenschaften von DocBook - im Gegensatz zum „allgmeinen“ XML – sind:
Die DocBook DTD definiert eine begrenzte Anzahl Tags und gibt genaue Regeln aus, wie diese zu verwenden sind: Welche Attribute sind möglich für Tag A, ob Element B in Element C verschachtelt werden kann, u.s.w.. Wenn Sie undefinierte Tags benutzen oder den Regeln nicht folgen, ist Ihr Dokument auch kein DocBook mehr (und DocBook-unterstützende Anwendungen versagen möglicherweise Ihren Dienst).
DocBook-Tags vermitteln immer die Struktur und Semantiken
(Bedeutungen), niemals Aussehen. In DocBook werden Sie Struktur-Tags finden wie
<book>, <part>, <chapter>, <section>, <para>, <table>; and semantic tags like <filename>, <warning,> <emphasis>, <postcode>; but nothing like <font>, <bold>, <center>, <indent>, <backgroundcolor> – nichts was mit dem Layout oder Aussehen zu tun hat.
Deshalb muss irgendwo eine Entscheidung getroffen werden, wie die DocBook-Tags in ihr endgültiges Aussehen übersetzt werden sollen. Diese Entscheidung (oder besser: die Rendering-Regeln) können statisch in die Tools einprogrammiert werden, aber dies würde die Dinge sehr unflexibel gestalten. Darum sind die Regeln meistens in den Stylesheets definiert. Ein Stylesheet ist ein Dokument, welches dem Tool Zeug wie dieses erzählt:
„Zeige Kapitelüberschriften als 24 Punkte großer, schwarzer Schrift an; beginne jedes Kapitel auf einer neuen Seite; benutze kursiv für Betonungen; zeige Warnungen in fett und 12 Punkten an; benutze Großschreibung für Abkürzungen; etc., etc.“
Dieser Ansatz ermöglicht es dem Benutzer die Stylesheets nach seinen Bedürfnissen zu verändern. Es würde deutlich aufwändiger sein - wenn nicht unmöglich - die Tools selbst anzupassen.
Stylesheets die benutzt werden, um DocBook XML in andere Formate zu wandeln, werden transformation stylesheets genannt. Sie werden in einer anderen Art XML geschrieben, XSLT (eXtensible Stylesheet Language for Transformations) genannt.
DocBook hat eine Menge Vorteile für alle, die technische Dokumentationen erstellen. Dies sind die wichtigsten:
Ein DocBook XML-Dokument besteht aus reinem, unverfälschtem Inhalt. Sie werden sich niemals Gedanken über das Aussehen machen müssen, während Sie schreiben. Sie können sich ganz auf die Struktur und Information konzentrieren. Diese Praxis mag Ihnen etwas altertümlich vorkommen, wenn Sie Text sonst in z.B. Word verfassen, aber ich verspreche Ihnen: Sie werden es lieben lernen.
Da sich DocBook nur um die Struktur und Bedeutung kümmert, wird es überraschend einfach sein, Ihren kleinen Abriss in ein DocBook-Skelett zu konvertieren.
Viele Leute erstellen Dokumente für das manual Modul. Wenn sie alle verschiedene Formate, oder gar ein einheitliches Format wie Word oder HTML verwendeten, würden Ihre Ergebnisse sehr unterschiedlich aussehen, da jeder sein eigenes Aussehen präferiert. Natürlich könnten wir einen Satz Regeln hierfür erstellen, aber dann müsste jeder Schreiber sich dieser Regeln annehmen und diese auch noch selbst implementieren. Es ist also besser die Regelsätze an einem zentralen Ort zu halten: Die Stylesheets, und somit den Dokumenterstellern Zeit für ihre Dokumentation zu lassen. Sie müssen sich nicht um das Aussehen kümmern. Die Stylesheets werden sicherstellen, dass alle unsere Dokumentationen gleich Aussehen.
Wenn wir das Aussehen unserer Dokumente nicht mögen, können wir dieses einfach ändern, wenn die Regeln hierfür in Stylesheets vorliegen. Nichts muss in den DocBook-Quellen selbst geändert werden; alles was wir zu tun haben, nachdem die Stylesheets angepasst wurden, ist die Dokumente neu zu rendern. Neu erstellte Dokus werden automatisch das neue Aussehen erhalten. Versuchen Sie das mal zu erreichen, wenn Sie Anweisungen für Aussehen und Styling in den Dokumenten verstreut sind!
Ein weiterer Vorteil ist das DocBook ein offener Standard ist, nicht an kommierzielle Belange oder ein bestimmtes System gekoppelt. Wenn Sie das Firebird manual Modul herunterladen, können Sie die HTML- und PDF-Dokumente aus den DocBook-Quellen unter Linux und Windows erstellen - und wir können mehr Betriebssysteme unterstützen, wenn notwendig.
Ein DocBook-Dokument ist reiner text, welcher ideal für die Nutzung im CVS ist. Ja, ein CVS-Baum kann natürlich auch Binärdateien enthalten, aber viele nützliche Eigenschaften, die CVS bietet (z.B. die Anzeige der Unterschiede zwischen zwei Versionen einer Datei) funktionieren nur mit Text.
Zugegebenermaßen, keiner der beschriebenen Vorteile gilt einzig und allein für DocBook. Aber DocBook hat sie alle. Und es wird weitreichend unterstützt. Das macht es zur perfekten Wahl für unsere Firebird-Dokumentationen.
Hier sind ein paar Links, sollten Sie sich weiter über DocBook informieren wollen:
http://opensource.bureau-cornavin.com/crash-course/
Writing Documentation Using DocBook – A Crash Course von David Rugge, Mark Galassi und Eric Bischoff. Ein sehr schönes Tutorial, auch wenn viele der vorgestellten Werkzeuge nich von uns verwendet werden.
DocBook – The Definitive Guide, von Norman Walsh und Leonard Muellner. Erwarten Sie nicht, ein anfängerfreundliches Tutorial zu finden - tatsächlis ist der erste Teil einschüchternt, wenn sie ein Anfänger sind. Der Grund weshalb ich dieses hier aufführe ist, dass es eine tolle Online-Referenz ist, welche ich oft beim Schreiben verwende.
http://www.tldp.org/HOWTO/DocBook-Demystification-HOWTO/
Das DocBook Demystification Howto ist interessant, wenn Sie etwas mehr über XML und DocBook erfahren wollen als wir Ihnen bisher erzählt haben. Es enthält außerdem einiges an Material über SGML und - nochmal - Werkzeuge, die wir nicht für das Firebird-Dokumentations-Unterprojekt verwenden.
http://sourceforge.net/projects/docbook
Das DocBook Open-Source-Projekt bei SourceForge.
Wenn Sie weitere gute Online-Resourcen kennen, lassen Sie uns dies bitte wissen. Schreiben Sie eine Nachricht an die firebird-docs list.
|
| Firebird Documentation Index → Firebird Docwriting-Anleitung → DocBook XML – Eine Einleitung |