Anwenderhandbuch mit DocBook erstellen
Warum DocBook für das iDempiere Anwenderhandbuch verwendet wird
DocBook eignet sich besonders zur Erstellung von Büchern, Artikeln und Dokumentationen im technischen Umfeld (Hardware oder Software).
Eingesetzte Version
Zur Zeit wird 5.0 eingesetzt. Die Diskussion läuft jedoch noch. Im Gespräch ist auch eine ältere Version einzusetzen, da dort mehr Entwicklungswerkzeuge (z.B.: Serna) zur Verfügung stehen. Sobal eine eindeutige Entscheidung getroffen wurde wird diese hier veröffentlicht.
Vorbereitung und Hinweis zum Einsatz von DocBook
DocBook wird als DEB Paket unter Linux installiert
Innerhalb der DocBook Datei wird auf die "XSL Stylesheets" verwiesen
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V5.0//EN" "http://docbook.org/xml/5.0/dtd/docbook.dtd">
Diese werden immer aktuell aus dem Internet, ohne Änderungen, verwendet.
Somit wird sichergestellt, dass die erstellte Dokumentation weltweit ein einheitliches Aussehen erhält.
Der Artikel (oder das Buch) wird in einen Texteditor erstellt.
In der Konsole wird der Artikel oder das Buch in HTML Dateien übersetzt. Hierzu wird z.B. folgender Befehl verwendet:
xsltproc /usr/share/xml/docbook/stylesheet/docbook-xsl-ns/html/chunk.xsl Startseite.xml
Der genaue Befehl hängt natürlich von Ihrer Installation und Ihrem Arbeitsverzeichnis ab. Dies ist nur ein Beispiel.
Um Include-Direktiven zu benutzen, nimmt man folgenden Befehl (mit der Option "--xinclude"):
xsltproc --xinclude /usr/share/xml/docbook/stylesheet/docbook-xsl-ns/html/chunk.xsl iDempiere-Buch.xml
Eingesetzte Editoren und Hilfsmittel um einen DocBook Artikel zu erstellen
Es kann grundsätzlich jeder Texteditor eingesetzt werden. DocBook Funktionen werden z.B. von Emacs unterstützt.
XML Copy Editor
Thomas Thießen setzt den "XML Copy Editor" ein.
Kleiner Tipp:
- Datei
- Neu
- DocBook 5.0 book (*xml) oder DocBook 5.0 article (*xml) auswählen
Anschließend steht der Befehlssatz von DocBook 5.0 zur Verfügung
Kapitelstruktur
Die Kapitelstruktur sollte von allen Autoren einheitlich verwendet werden.
Hier folgen die ersten "Grundgedanken"
Konkrete Anwendung
<book xml:lang="de" xml:id="userguid-anwenderhandbuch"> // <book> Das gesamte Buch (ink. ID)
<title>iDempiere Anwenderhandbuch</title> // <title> Titel des Buches
<article xml:id="userguide-allgemeines-zu-idempiere-article"> // <article> Artikel (Grobes Kapitel)
<title>Allgemeines zu iDempiere</title> // <title> Titel des Kapitels
</article>
<article> // <article> Artikel (Grobes Kapitel)
<sect1 xml:id="userguide-startseite"> // <sect1> ein wesentliches Unterkapitel (Eigene Seite, Indexeintrag wird erzeugt, große Überschrift)
<title>Startseite - Willkommensseite</title>
<sect2 xml:id="userguide-einleitung"> // <sect2> Ein kleiners Unterkapitel (Keine eigene Seite, kein Indexeintrag, mittelgroße Überschrift)
<title>Einleitung</title>
</sect2>
<sect2 xml:id="userguide-bereiche-der-startseite">
<title>Bereiche der Startseite</title>
<sect3 xml:id="userguide-menueleiste-idempiere-logo"> // <sect3> Ein Absatz (Keine eigene Seite, kein Indexeintrag, mittelgroße Überschrift)
<title>Menüleiste: iDemperie Logo</title>
</sect3>
<sect3 xml:id="userguide-menueleiste-hinzufuegen-loeschen-knopf">
<title>Menüleiste: hinzufügen / löschen Knopf</title>
</sect3>
</sect2>
</sect1>
</article>
</book>
Gedankensammlung zur Kapitelstruktur
<book xml:lang="de" xml:id="userguid-idempiere"> // book ist der "Name des Buches"
<chapter xml:id="userguide-installation"> // chapter ist das grobe "oberste Kapitel" z.B. "Vorwort", "Installation", "Anwenderhandbuch", "Anhänge", usw.... (chapter kann jedoch KEINE article enthalten)
</chapter>
<chapter xml:id="userguide-anwenderhanduch">
<section xml:id="userguide-allgemeine-einführung"> // section ist ein wesentliches Kapitel, innerhalb des "obersten Kapitels"
</section>
</chapter>
<chapter xml:id="userguide-inhaltsverzeichnis">
</chapter>
</book>
- Ein <book> kann <chapter> oder <article> enthalten
- Ein <chapter> kann KEINE <article>
- Ein <chapter> kann <section> enthalten
- Eine <section> kann weitere <section> enthalten.
- <sect1> bildet immer eine große Überschrift als "Kapitel"
- <sect1> wird immer auf einer neuen Seite begonnen
- <sect1> erhält immer einen Indexeintrag
Speicherort für Bilder
- Zur Zeit werden die Bilder auf dem lokalen Laufwerk gespeichert. Hierfür muss ein öffentlicher Org geschaffen werden.
- Dateinamen und Verzeichnisbenennungen müssen festgelegt werden
Eingesetzte Befehle
Gliederung
<book xml:lang="de" xml:id="userguid-anwenderhandbuch"> <article xml:id="userguide-grundlagen"> <sect1 xml:id="userguide-startseite"> <sect2 xml:id="userguide-einleitung"> <sect3 xml:id="userguide-menueleiste-idempiere-logo"> <title>Einleitung</title> <para>Eigentlicher Textbereich</para> <imageobject><imagedata fileref="bilder/Startseite.png"/></imageobject>
Listen
<orderedlist> <listitem>Menüleiste</listitem> </orderedlist> <itemizedlist mark='opencircle'> <listitem override='bullet'>Informationen über Ihre aktuell installierte iDempier Installation</listitem> </itemizedlist>
Infos zu Lizenz und Autor
<info>
<legalnotice>
<para>Der Inhalt ist verfügbar unter der Lizenz GNU-Lizenz für freie Dokumentation 1.3 oder höher.</para>
</legalnotice>
<author>
<personname>
<firstname>Thomas</firstname>
<surname>Thießen</surname>
</personname>
</author>
<author>
<publisher>
<publishername>Thomas Thießen </publishername>
<address>Hülser Str. 113</address>
<address>DE-47803 Krefeld</address>
<address>email TTHatARCORdotDE</address>
</publisher>
<edition>01.11.2014 iDempiere Version 2.0 </edition>
</info>
<appendix>
<title>Lizenzbedingungen</title>
<para>Lizenzbedingungen für dieses Buch</para>
</appendix>
Widmung
<dedication>
<title>Widmung am Anfang des Buches</title>
<para>Eigentliche Widmung</para>
</dedication>
