Die GuideXML-Syntax ist zugleich leichtgewichtig als auch ausdrucksstark, so dass sie schnell erlernbar ist, gleichzeitg aber alle notwendigen Eigenschaften bereitstellt, die wir für das Erstellen von Internet-Dokumenten brauchen. Die Anzahl der Tags ist auf ein Minimum beschränkt -- nur die, die wir brauchen. Dadurch wird es einfacher, Dokumente in andere Formate, wie z.B. DocBook, XML/SGML oder HTML umzuwandeln.

Das Ziel ist, das Erstellen und Umwandeln von GuideXML-Dokumenten zu erleichtern.

Wenn Sie planen, Dokumentation zu Gentoo beizutragen, oder GuideXML testen wollen, lesen Sie bitte den Tipps und Tricks-Guide, welcher Tipps und Tricks zur Erstellung von Dokumentation beinhaltet.

Vielleicht möchten Sie auch den XML-Code dieses Dokuments sehen, während Sie die Tipps und Tricks lesen.

Lassen Sie uns anfangen die GuideXML Syntax zu erlernen. Wir beginnen mit den einleitenden Tags, die in einem GuideXML-Dokument verwendet werden:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<!-- $Header$ -->

<guide link="/doc/de/guide.xml" lang="de">
<title>Gentoo Dokumentationsleitfaden</title>

<author title="Autor">
  <mail link="Ihrname@gentoo.org">Ihr Name</mail>
</author>

<abstract>
Dieser Leitfaden erklärt Ihnen, wie Sie Dokumente mit Hilfe der neuen
leichtgewichtigen Gentoo GuideXML Syntax erstellen können. Diese Syntax stellt
das offizielle Format für Gentoo-Dokumente dar - auch dieses Dokument wurde mit
Hilfe von Gentoo GuideXML erstellt.
</abstract>

<!-- The content of this document is licensed under the CC-BY-SA license
-->
<!-- See http://creativecommons.org/licenses/by-sa/3.0 -->
<license version="3.0"/>

<version>1</version>
<date>2011-11-29</date>

In der ersten Zeile sehen wir den notwendigen Tag, der festlegt, dass das Dokument in XML beschrieben ist, sowie sein DTD. Die <!-- $Header$ --> Zeile wird automatisch vom CVS modifiziert und erleichtert das Verfolgen von Versionsänderungen. Darauf folgt ein <guide> Tag. Das ganze Dokument ist umschlossen von einem <guide> </guide> Paar.
Das link Attribut ist optional und sollte bevorzugt den absoluten Pfad relativ zum Root der Dokumente, auch wenn der Dateiname alleine funktionieren mag, enthalten. Dieses Attribut wird nur genutzt, um einen Link zu einer druckerfreundlichen Version des Dokuments zu erzeugen und um zu prüfen, ob eine Übersetzung aktuell ist. Unsere XSL Back-Engine übergibt den eigentlichen Pfad unserem XSL-Stylesheet. Das link-Attribut wird nur als Ausweichlösung benutzt, falls das XML auf einen anderen Weg abgearbeitet wird.
Das lang Attribut sollte zur Spezifizierung des Sprachcodes verwendet werden. Es sorgt für die richtige Formatierung von Datum und Übersetzungen wie "Notiz", "Inhalt" usw. Die Standardeinstellung ist Englisch.

Schließlich gibt es noch den Tag <title>, mit dem der Titel für das Dokument festgelegt wird.

Als nächstes kommen wir zu den <author> Tags, welche Informationen über die unterschiedlichen Autoren eines Dokumentes enthalten. Jeder <author> Tag besitzt ein optionales Element title. Dieses wird benutzt, um die Beziehungen der Autoren zum Dokument (Autor, Co-Autor, Bearbeiter, Übersetzer usw.) zu beschreiben. Im vorliegenden Beispiel sind die Namen der Autoren in einem weiteren Tag eingeschlossen -- dem Tag <mail>. Mit diesem kann eine Email-Adresse mit der betreffenden Person verbunden werden. Der Tag <mail> ist optional und kann weggelassen werden. Weiterhin wird mindestens ein <author> Element pro Dokument benötigt.

Es folgen die Tags <abstract>, <version> und <date>, die benutzt werden, um die Überschrift, die gegenwärtige Versionsnummer und das gegenwärtige Versionsdatum (im Format JJJJ-MM-TT, z.B. 2004-12-25) des Dokuments festzulegen. Ungültige oder nicht dem JJJJ-MM-TT Format folgende Angaben werden ohne Änderung übernommen.

Damit sind alle Tags genannt, die zu Beginn des Dokuments stehen sollten. Ebenso wie die Tags <title> und <mail> sollten diese nur direkt im Tag <guide> und nicht irgendwo anders stehen. Weiterhin wird empfohlen (aber nicht gefordert), dass diese Tags vor dem eigentlichen Inhalt im Dokument stehen.

Und schließlich haben wir das <license version="3.0"/> Tag, mit dem wir das Dokument unter der Creative Commons - Attribution / Share Alike Lizenz veröffentlichen, wie es die Dokumentations-Richtlinie erfordert. In früheren Versionen wurde das Tag <license /> genutzt, welches für Version 2.5 der Lizenz stand. Diese Variante wird noch immer akzeptiert und darf benutzt werden.

Sobald Sie die einleitenden Tags spezifiziert haben, können Sie damit beginnen, Strukturelemente des Dokuments hinzuzufügen. Guide-Dokumente sind unterteilt in Kapitel (chapter) und jedes Kapitel kann einen oder mehrere Abschnitte (section) enthalten. Jedes Kapitel und jeder Abschnitt hat eine Überschrift. Hier ist ein Beispielkapitel mit einem Abschnitt, der einen Absatz enthält. Wenn Sie dieses XML an das XML im vorherigen Auszug anhängen und ein </guide> am Ende hinzufügen, haben Sie ein (minimales) Guide-Dokument:

<chapter>
<title>Das ist mein Kapitel</title>
<section>
<title>Hier ist Abschnitt Eins in meinem Kapitel</title>
<body>

<p>
Dies ist der eigentliche Textinhalt meines Abschnitts.
</p>

</body>
</section>
</chapter>

Wie Sie sehen, habe ich dem Kapitel durch das Hinzufügen eines Kindelements <title> in das Element <chapter> eine Überschrift gegeben. Anschließend habe ich einen Abschnitt durch das Hinzufügen des Elements <section> erzeugt. Wenn Sie sich das Element <section> anschauen, werden Sie zwei Kindelemente erkennen -- ein <title> und ein <body> Element. Da Ihnen das Element <title> bereits bekannt ist, sei hier das Element <body> erläutert; dieses enthält den eigenlichen Inhalt des derzeitigen Abschnitts. Wir betrachten nun kurz die Tags, die innerhalb von <body> erlaubt sind.

Jetzt ist es an der Zeit zu lernen, wie man den eigentlichen Inhalt auszeichnet. Hier ist der XML-Code zu einem Beispiel-<body>-Element:

<p>
Das ist ein Absatz.  <path>/etc/passwd</path> ist eine Datei.
<uri>http://forums.gentoo.org</uri> ist meine Lieblings-Webseite.
Geben Sie <c>ls</c> ein - wenn sie wollen. Ich sollte jetzt
<e>wirklich</e> schlafen gehen.</p>

<pre caption="Code Sample">
Das ist Textausgabe oder Quelltext.
# <i>das sind Benutzereingaben</i>

Um HTML/XML lesbarer zu machen, sollten Sie verschiedene Hervorhebungen
verwenden:
<foo><i>bla</i></foo>

<comment>So wird ein Kommentar in einen Quelltextabschnitt
eingefügt</comment>
</pre>

<note>
Das ist eine Anmerkung.
</note>

<warn>
Das ist eine Warnung.
</warn>

<impo>
Das ist wichtig.
</impo>

Und so wird dieses <body> Element dargestellt:

Das ist ein Absatz. /etc/passwd ist eine Datei. http://forums.gentoo.org ist meine Lieblings-Webseite. Geben Sie ls ein - wenn Sie wollen. Ich sollte jetzt wirklich schlafen gehen.

Das ist Textausgabe oder Quelltext.
# das sind Benutzereingaben

Um HTML/XML lesbacher zu machen, sollten Sie verschiedene Hervorhebungen
verwenden:
<foo>bar</foo>

So wird ein Kommentar in einen Quelltextabschnitt eingefügt

Im vorherigen Abschnitt wurde eine Menge neuer Tags eingeführt -- jetzt werden sie erläutert. Die Tags <p> (Absatz), <pre> (Quelltextabschnitt), <note> (Anmerkung), <warn> (Warnung) und <impo> (Wichtig), können alle ein oder mehrere Zeilen Text enthalten. Neben den <table>-Elementen (auf das wir später eingehen), sollten das die einzigen Tags, die innerhalb des Elements <body> stehen, sein. Weiterhin sollten diese Tags nie verschachtelt werden -- mit anderen Worten, Sie sollten das Element <note> nicht innerhalb des Elements <p> verwenden! Wie Sie vielleicht bemerken, gibt das Element <pre> Leerzeichen und Zeilenumbrüche exakt wieder - dadurch empfiehlt es sich für Quelltextschnipsel. Sie müssen das <pre> Tag mit einem caption Attribut benennen:

<pre caption="Ausgabe von uptime">
# <i>uptime</i>
16:50:47 up 164 days,  2:06,  5 users,  load average: 0.23, 0.20, 0.25
</pre>

In Österreich werden Stromleitungen über Land verlegt. Kommt ein Österreicher am Ort des Geschehens vorbei, kichert, geht weiter. Kommt der zweite vorbei, lacht, geht weiter. Der dritte kommt, bleibt stehen und lacht schallend - er kriegt sich gleich gar nicht mehr ein. Da fragt ihn einer der Arbeiter, was denn daran so komisch sei. "Naja", sagt er prustend, "ihr hängt den Zaun so hoch, daß alle Kühe unten durchlaufen..."

Epigrafen werden manchmal am Anfang eines Kapitels verwendet und sollen erläutern, was folgt. Sie sind kurz gesagt einfach ein Absatz, der mit einem bei-Attribut abschließt, welches die Signatur enthält.

<p by="ein witziger Deutscher">
In Österreich werden Stromleitungen über Land verlegt. Kommt...
</p>

Die <path>, <c>, <b>, <e>, <sub> und <sup> Elemente können innerhalb jedes <body>-Kindelements verwendet werden, ausgenommen ist <pre>.

Das <path> Element wird verwendet, um Text hervorzuheben, der auf eine Datei auf der Festplatte verweist -- genauso wie für einen absoluten oder relativen Pfad oder einfach einen Dateinamen. Dieses Element wird normalerweise mit einer Maschinentextschrift dargestellt, um es vom Rest des Textes abzugrenzen.

Das Element <c> wird verwendet, um Befehle oder Benutzereingaben zu markieren. Sie können sich <c> als eine Möglichkeit vorstellen, dem Leser mitzuteilen, dass er etwas eingeben kann, was zu irgendeiner Aktion führt. Zum Beispiel sind alle XML-Tags in diesem Dokument von <c> umschlossen, um zu zeigen, dass der Benutzer etwas anderes als einen Pfad eingeben kann. Indem Sie das Element <c> verwenden, erleichtern Sie es Ihren Lesern, Befehle die sie eingeben müssen schneller zu erkennen. Des Weiteren ist es auf Grund dessen, dass <c> Elemente sich vom regulären Text abheben, nicht zwingend notwendig, Benutzereingaben mit doppelten Anführungszeichen zu umgeben. Verwenden Sie zum Beispiel das Element "<c>" nicht wie in diesem Satz. Vermeiden Sie die Benutzung von nicht-notwendigen doppelten Anführungszeichen, um das Dokument leserlicher und ansprechender zu gestalten.

Wie Sie sich vielleicht schon gedacht haben wird <b> verwendet um Textstellen fettgedruckt darzustellen.

<e> wird benutzt, um Wörter oder Wortgruppen zu betonen; zum Beispiel: Ich sollte wirklich öfter Semikola verwenden. Wie Sie sehen können, hebt sich dieser Text zur Betonung von der normalen Absatzschrift ab. Dadurch wird das von ihnen Gesagte schlagkräftiger!

Die <sub> und <sup>-Elemente werden zum _Tiefstellen und ^Hochstellen verwendet.

Um die Lesbarkeit von Code-Beispielen zu erhöhen, stehen innerhalb eines <pre>-Blocks folgende Tags zur Verfügung:

<i>

Hebt Benutzereingaben hervor

<comment>

Kommentar, der meistens den/die darauffolgende(n) Befehl(e) betrifft

<keyword>

Zeigt ein Schlüsselwort der Programmiersprache an

<ident>

Wird für Bezeichner verwendet

<const>

Wird für Konstanten verwendet

<stmt>

Wird für eine Anweisung verwendet

<var>

Wird für eine Variable verwendet

Beispiel für einen farbcodierten <pre>-Block:

# Copyright 1999-2009 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Header: $

DESCRIPTION="Exuberant ctags generates tags files for
quick source navigation"
HOMEPAGE="http://ctags.sourceforge.net"
SRC_URI="mirror://sourceforge/ctags/${P}.tar.
gz"

LICENSE="GPL-2"
SLOT="0"
KEYWORDS="~mips ~sparc ~x86"
IUSE=""

src_compile() {
    econf --with-posix-regex
    emake || die "emake
failed"
}

src_install() {
    make DESTDIR="${D}" install ||
die "install failed"

    dodoc FAQ NEWS README
    dohtml EXTENDING.html ctags.html
}

Wir hatten uns den Tag <mail> schon vorhin angesehen, er wird benutzt, um einen Text mit einer speziellen Email-Adresse zu verbinden. Er hat die Form <mail link="foo@bar.com">Herr Foo Bar</mail>. Wenn Sie die Email-Adresse darstellen möchten können Sie <mail>foo@bar.com</mail> verwenden, dies wird als foo@bar.com dargestellt.

Kürzere Formen machen es einfacher Namen und Email-Adressen von Gentoo-Entwicklern zu benutzen. Sowohl <mail>neysx</mail> als auch <mail link="neysx"/> würde als neysx erscheinen. Wenn Sie die Email eines Gentoo Entwicklers mit einem anderen Inhalt als dem vollen Namen verwenden möchten, benutzen Sie die zweite Form mit etwas Inhalt. Zum Beispiel, benutzen Sie den Vornamen eines Entwicklers: <mail link="neysx">Xavier</mail> erscheint als Xavier.
Dies ist besonders nützlich, wenn Sie einen Entwickler benennen wollen, dessen Namen "komische" Zeichen enthält, die Sie nicht tippen können.

Der Tag <uri> wird verwendet, um auf Dateien oder Seiten im Internet zu verweisen. Es gibt zwei Varianten: Bei der ersten wird die URI direkt im Text angezeigt, so wie dieser Link zu http://forums.gentoo.org. Um diesen Link zu erzeugen, habe ich <uri>http://forums.gentoo.org/</uri> eingegeben. Die Alternative wird verwendet, wenn Sie eine URI mit einem abweichenden Text verknüpfen wollen -- z.B. den Gentoo Foren. Um diesen Link zu erzeugen, wurde <uri link="http://forums.gentoo.org/">den Gentoo Foren</uri> eingegeben. Sie brauchen nicht http://www.gentoo.org/ vor Links auf andere Teile der Gentoo Webseite zu setzen. Beispielsweise setzen Sie für einen Link auf den Dokumentationsindex einfach <uri link="/doc/de/index.xml">Dokumentationsindex</uri>. Sie können index.xml sogar auslassen, wenn Sie auf einen Verzeichnisindex wie den <uri link="/doc/de/">Dokumentationsindex</uri> verweisen. Der abschließene Slash spart eine zusätzliche HTTP-Anfrage.

Sie sollten kein <uri> Tag mit einem link Attribut, das mit mailto: beginnt, verwenden.

Bitte vermeiden Sie das Hier klicken Syndrom, wie vom W3C empfohlen.

Und so können Sie Grafiken in ein Dokument einfügen: <figure link="meinbild.png" short="mein Bild" caption="für immer mein Lieblingsbild"/ >. Das Attribut link verweist auf die gewünschte Grafikdatei, das Attribut short legt eine Kurzbeschreibung fest (wird derzeit für das Attribute alt im HTML-Tag <img> verwendet) und mit caption wird schließlich eine Bildunterschrift festgelegt -- alles in allem nicht allzu schwer :) Außerdem wird noch der Tag <img src="bla.gif"/> aus HTML unterstützt, um Grafiken ohne Unterschrift, Ränder u.a. einzufügen.

GuideXML stellt eine vereinfachte Tabellensyntax, vergleichbar mit der von HTML, bereit. Um eine Tabelle zu erzeugen, benutzen Sie den Tag <table>. Eine Reihe wird mit <tr> begonnen. Allerdings unterstützt GuideXML keinen Tag <td> wie in HTML, um die eigentlichen Tabelleninhalte einzufügen; verwenden Sie stattdessen <th> für den Tabellenkopf und <ti> wenn Sie normale Informationen einfügen wollen. Sie können <th> überall dort verwenden, wo Sie auch <ti> verwenden können -- es gibt also keinen Zwang <th> Elemente nur in der ersten Reihe zu verwenden.

Außerdem unterstützen sowohl Tabellenkopf (<th>) als auch Tabelleninhalte (<ti>) die colspan und rowspan-Attribute um ihren Inhalt über mehrere Spalten, Zeilen oder beides gehen zu lassen.

Zusätzlich können die Tabelleninhalte ( <ti> & <th>) rechts-, linksbündig oder mit dem Attribut align zentriert sein.

Um eine sortierte oder unsortierte Liste zu erzeugen, verwenden Sie einfach die gleichwertigen Tags im XHTML-Stil: <ol>, <ul> und <li>. Listen können nur innerhalb eines <body> oder <li> Tags erstellt werden. Dies bedeutet also, dass Listen auch innerhalb von Listen möglich sind. Vergessen Sie nicht, dass sie XML verwenden und alle Tags schließen müssen, auch die Listen-Tags, welches in HTML nicht nötig ist.

Definitionslisten (<dl>) werden auch unterstützt. Bitte beachten Sie, dass weder das Definitions-Term-Tag (<dt>) noch das Definitions-Daten-Tag (<dd>) andere Blocklevel-Tags, wie zum Beispiel Paragraphen oder Warnungen, erlaubt. Eine Definitionsliste beinhaltet:

<dl>

Ein Definitions-Listen-Tag welches ein

<dt>

paar Definitions-Term-Tags und

<dd>

Definitions-Daten-Tags enthält.

Die folgende Liste wurde von w3.org kopiert. Sie zeigt, dass eine Definitionsliste geordnete und ungeordnete Listen enthalten kann. Eine weitere Definitionsliste enthält sie jedoch nicht.

Die Zutaten:

• 100g Mehl
• 10g Zucker
• 1 Tasse Wasser
• 2 Eier
• Salz, Pfeffer

Zubereitung:

1. Vermischen Sie die trockenen Zutaten miteinander
2. Geben Sie die flüssigen Zutaten dazu
3. Mixen Sie 10 Minuten lang
4. Backen Sie den Teig bei 300°C eine Stunde lang

Notizen

Das Rezept wird durch Beimischen von Rousinen eventuell besser

In GuideXML ist es wirklich einfach, Verweise zu anderen Teilen des Dokuments mit Hilfe von Hyperlinks zu erstellen. Sie können einen Verweis zu Kapitel 1 durch das Eingeben von <uri link="#doc_chap1">Kapitel 1</uri> erzeugen. Um auf Abschnitt 2 in Kapitel 1 zu verweisen, geben Sie <uri link="#doc_chap1_sect2">Abschnitt 2 in Kapitel 1</uri> ein. Um auf Grafik 3 in Kapitel 1 zu verweisen, geben Sie <uri link="#doc_chap1_fig3">Grafik 1.3</uri> ein; oder für einen Verweis auf Quelltextbeispiel 2.2 einfach <uri link="#doc_chap2_pre2">Quelltextbeispiel 2.2</uri>.

Allerdings ändern sich viele Anleitungen öfters und solches "Zählen" kann dann zu fehlerhaften Links führen. Um dem abzuhelfen, kann ein Name für ein <chapter>, <section> oder <tr> mit Hilfe des id Attributes hinzugefügt werden. Nun muss man nur noch auf dieses Attribut verweisen:

<chapter id="foo">
<title>Das ist foo!</title>
 ...
<p>
Weitere Informationen finden Sie im <uri link="#foo">foo
Kapitel</uri>
</p>

Ein Disclaimer Attribut kann auf Guides und Handbücher angewandt werden, um einen vordefinierten Disclaimer am Anfang des Dokuments anzuzeigen. Die verfügbaren Disclaimer sind:

• articles wird für neuaufgelegte Artikel verwendet.
• draft wird verwendet, um anzuzeigen, dass ein Dokument noch in Bearbeitung ist und nicht als offiziell angesehen werden sollte.
• oldbook wird bei alten Handbüchern verwendet, um klarzustellen, dass diese nicht länger instand gehalten werden.
• obsolete wird verwendet, um ein Dokument als veraltet/überholt zu markieren.

Wenn Sie ein Dokument als obsolet markieren, sollten Sie in Betracht ziehen einen Link zu einer neueren Version hinzuzufügen. Das redirect Attribut tut dies automatisch. Der Benutzer wird möglicherweise automatisch zur neuen Seite weitergeleitet, aber Sie sollten sich nicht auf dieses Verhalten verlassen.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<!-- $Header$ -->

<guide disclaimer="obsolete" redirect="/doc/en/handbook/handbook-x86.xml">
<title>Gentoo x86 Installation Guide</title>

<author title="Author">
...

FAQ-Dokumente müssen mit einer Liste von Fragen mit Links zu deren Antworten beginnen. Das Erstellen einer solchen Liste ist sowohl zeitintensiv als auch fehleranfällig. Die Liste kann automatisch erstellt werden, wenn Sie ein faqindex Element als erstes Kapitel Ihres Dokumentes verwenden. Dieses Element hat dieselbe Struktur wie ein chapter, um einen Einführungstext zu ermöglichen. Die Struktur des Dokuments sollte in Kapitel (mindestens ein Kapitel) aufgeteilt sein, welche Abschnitte enthalten. Jeder Abschnitt besteht aus einer Frage, die in seinem title Element, und der Antwort, die in seinem body Element definiert ist. Der FAQ-Index erscheint als ein Abschnitt pro Kapitel und ein Link pro Frage.

Ein schneller Blick auf eine FAQ und ihren Quelltext sollte das oben stehende offensichtlich machen.

Für umfangreichere Dokumentationen, wie bei den Installationsanweisungen, wird ein erweitertes Format gebraucht. Wir erstellten eine GuideXML-kompatible Erweiterung, die es uns erlaubt, modulare und mehrseitige Dokumentationen zu schreiben.

Die erste Änderung ist, dass ein "Master" Dokument gebraucht wird. Dies enthält keinen Inhalt, aber Links zu den einzelnen Dokumentationsmodulen. Die Syntax unterscheidet sich nur wenig von GuideXML:

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE book SYSTEM "/dtd/book.dtd">
<!-- $Header$ -->

<book link="example.xml">
<title>Example Book Usage</title>

<author...>
  ...
</author>

<abstract>
  ...
</abstract>

<!-- The content of this document is licensed under the CC-BY-SA license
-->
<!-- See http://creativecommons.org/licenses/by-sa/3.0 -->
<license version="3.0"/>

<version>...</version>
<date>...</date>

So weit gibt es keine wirklichen Unterschiede (sieht man einmal vom Gebrauch des <book> anstelle des <guide> Tags ab). Anstelle des individuellen <chapter>, erstellen Sie zunächst ein <part> (Teil), welcher äquivalent zum bestimmten Teil im Buch ist:

<part>
<title>Teil Eins</title>
<abstract>
  ...
</abstract>

(Mehere Kapitel erstellen)
</part>

Jeder Teil (part) wird von einem <title> und <abstract> begleitet, die eine kleine Einführung in diesen geben.

In jedem Teil (part) definieren Sie die individuellen <chapter> (Kapitel). Jedes Kapitel muss ein eigenes Dokument sein. Deswegen existiert ein spezielles Tag (<include>), das die Einbindung des separaten Dokuments erlaubt.

<chapter>
<title>Kapitel Eins</title>
<abstract>
  Dies ist eine kurze Erklärung von Kapitel Eins.
</abstract>

  <include href="Pfad/zu/Kapitel-Eins.xml"/>

</chapter>

Der Inhalt eines individuellen Kapitels wird wie folgt strukturiert:

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE sections SYSTEM "/dtd/book.dtd">
<!-- $Header$ -->

<!--  The content of this document is licensed under the CC-BY-SA license
-->
<!--  See http://creativecommons.org/licenses/by-sa/3.0 -->

<sections>

<version>...</version>
<date>...</date>

(Erstellen Sie die einzelnen <section> und
<subsection>)

</sections>

Innerhalb jedes Kapitels können Sie <section> (äquivalent zu <chapter> im Guide) und <subsection> (äquivalent zu <section> im Guide) erstellen.

Jedes einzelne Kapitel soll sein eigenes Datums- und Versionselement besitzen. Das aktuelle Datum aller Kapitel und des Masterdokuments wird angezeigt, wenn ein Benutzer durch alle Teile des Buchs blättert.

Ab und zu werden die selben Werte immer wieder in mehreren Teilen des Handbuchs wiederholt. Globale Such- und Ersetzungsoperationen tendieren dazu, einige Änderungen zu vergessen oder führen ungewollte ein. Außerdem kann es nützlich sein, unterschiedliche Werte zur Benutzung in geteilten Kapiteln zu definieren, davon abhängig, welches Handbuch das Kapitel enthält.

Globale Werte können in einem Handbuch-Hauptdokument definiert und in allen eingebundenen Kapiteln benutzt werden.

Um globale Werte zu definieren, fügen Sie ein <values> Element zum Handbuch-Hauptdokument hinzu. Jeder Wert wird dann in einem <key> Element, dessen id Attribut den Wert identifiziert, d.h. es ist der Name der Variablen, angegeben.

Das folgende Beispiel definiert drei Werte in einem Handbuch-Hauptdokument:

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE book SYSTEM "/dtd/book.dtd">
<!-- $Header$ -->

<book>
<title>Example Book Usage</title>

<values>
  <key id="arch">x86</key>
  <key id="min-cd-name">install-x86-minimal-2007.0-r1.iso</key>
  <key id="min-cd-size">57</key>
</values>

<author...>
...
</author>

...

Die definierten Werte können dann im gesamten Handbuch mit dem Inline-Element <keyval id="key_id"/> verwendet werden. Geben Sie den Namen des Schlüssels in seinem id Attribut an, z.B. würde <keyval id="min-cd-name"/> in unserem Beispiel durch "install-x86-minimal-2007.0-r1.iso" ersetzt werden.

<p>
The Minimal Installation CD is called <c><keyval id="min-cd-name"/></c>
and takes up only <keyval id="min-cd-size"/> MB of diskspace. You can use this
Installation CD to install Gentoo, but <e>only</e> with a working Internet
connection.
</p>

Um das Leben unserer Übersetzer zu vereinfachen, benutzen Sie nur die eigentlichen Werte, d.h. Inhalt, der nicht übersetzt werden muss. Zum Beispiel haben wir den Wert -min-cd-size als 57 definiert, und nicht als 57 MB.

Kapitel, die von einigen Handbüchern, wie unserem Installationshandbuch, geteilt werden, haben oft nur kleine Unterschiede, davon abhängig, welches Handbuch sie einbindet. Anstatt Inhalt hinzuzufügen, der für einige Handbücher irreleveant ist, können die Autoren eine Bedingung zu den folgenden Elemten hinzufügen: <section>, <subsection>, <body>, <note>, <impo>, <warn>, <pre>, <p>, <table>, <tr>, <ul>, <ol> und <li>.

Die Bedingung muss ein XPATH Ausdruck sein, der ausgewertet wird, wenn das XML umgeformt wird. Wenn es zu true ausgwertet wird, wird das Element verarbeitet, falls nicht, wird es ignoriert. Die Bedingung ist im Attribut test angegeben.

Das folgende Beispiel benutzt den Wert arch, welcher in jedem Handbuch-Hauptdokument definiert ist, um einigen Inhalt abhängig zu machen:

<body test="contains('AMD64 x86',func:keyval('arch'))">

<p>
Dieser Absatz trifft auf die Architekturen x86 und AMD64 zu.
</p>

<p test="func:keyval('arch')='x86'">
Dieser Absatz trifft nur auf die Architektur x86 zu.
</p>

<p test="func:keyval('arch')='AMD64'">
Dieser Absatz trifft nur auf die Architektur AMD64 zu.
</p>

<p test="func:keyval('arch')='PPC'">
Dieser Absatz wird niemals gesehen werden!
Der komplette Körper wird aufgrund der ersten Bedingung ausgelassen.
</p>

</body>

<body test="contains('AMD64 PPC64',func:keyval('arch'))">

<p>
Dieser Absatz trifft auf die Architekturen AMD64, PPC64
und PPC zu, da die Zeichenkette 'AMD64 PPC64' 'PPC' enthält.
</p>

<note test="func:keyval('arch')='AMD64' or func:keyval('arch')='PPC64'">
Diese Notiz trifft auf die Architekturen AMD64 und PPC64 zu.
</note>

</body>

Da jede Gentoo Dokumentation eine große Anstregung ist und viele Leute die Dokumentation ändern, ist ein Coding Style notwendig. Ein Coding Style beinhaltet zwei Teile. Der erste (Interner Coding Style) erläutert wie die XML-Tags platziert werden sollen, der zweite beschreibt den Inhalt: wie man die Leser nicht verwirrt.

Beide Teile werden jetzt erläutert.

Neue Zeilen müssen direkt nach jedem GuideXML-Tag platziert werden (öffnende und schließende), ausgenommen für <version>, <date>, <title>, <th>, <ti>, <li>, <i>, <e>, <uri>, <path>, <b>, <c>, <comment>, <mail>.

Leere Zeilen müssen direkt nach jedem <body> (nur öffnende Tags) und vor jedem <chapter>, <p>, <table>, <author> (Gruppe), <pre>, <ul>, <ol>, <warn>, <note> and <impo> (nur öffnende Tags) platziert werden.

Ein Zeilenumbruch muss nach 80 Zeichen angewandt werden, außer im <pre> Tag. Nur wenn es keine andere Wahl gibt kann von dieser Regel abgewichen werden (zum Beispiel wenn eine URL über das Maximum an Zeichen hinausgeht). Der Editor muss dann beim nächsten Leerzeichen umbrechen. Sie sollten versuchen den gerenderten Inhalt des <pre> Elements auf 80 Zeichen zu begrenzen, um Konsolenbenutzern zu helfen.

Einrücken soll nicht benutzt werden, außer in XML Konstruktionen bei denen die Elterntags <tr> (von <table>), <ul>, <ol>, <dl> und <author> sind. Wenn Einrücken benutzt wird, müssen zwei Leerzeichen für jede Einrückung benutzt werden. Das heißt, keine Tabs und nicht mehr Leerzeichen. Tabs sind in GuideXML-Dokumenten sowieso nicht erlaubt.

Wenn ein Zeilenumbruch in ein <ti>, <th>, <li> oder <dd> Konstrukt fällt, muss eine Einrückung für den Inhalt verwendet werden.

Ein Beispiel für Einrückung ist:

<table>
<tr>
  <th>Foo</th>
  <th>Bar</th>
</tr>
<tr>
  <ti>Das ist ein Beispiel für Einrückung</ti>
  <ti>
    Wennn Text nicht in eine 80 Zeichen lange Zeile passt, müssen
    Sie Einrückung benutzen, wenn das Parent Tag es erlaubt
  </ti>
</tr>
</table>

<ul>
  <li>Erste Option</li>
  <li>Zweite Option</li>
</ul>

Attribute sollen keine Leerzeichen zwischen den Attributen, dem "=" und dem Wert haben. Ein Beispiel:

Falsch :     <pre caption = "Attribute">
Richtig:     <pre caption="Attribute">

Innerhalb von Tabellen (<table>) und Auflistungen (<ul>, <ol> und <dl>) sollten Punkte (".") nur benutzt werden, wenn mehrere Sätze benutzt werden. In diesem Fall sollte jeder Satz mit einem Punkt (oder anderem Satzzeichen) enden.

Jeder Satz, auch innerhalb von Tabellen und Listings, sollte mit einem Großbuchstaben beginnen.

<ul>
  <li>Kein Punkt</li>
  <li>Mit Punkt. Mehrere Sätze, Sie erinnern sich?</li>
</ul>

Codelistings sollten immer eine Beschreibung haben.

Benutzen Sie soweit möglich <uri> mit dem link Attribut. In anderen Worten, Gentoo Foren wird http://forums.gentoo.org vorgezogen.

Wenn Sie etwas innerhalb eines <pre> Konstruktes kommentieren möchten, benutzen Sie <comment> und den Kommentarmarker der jeweiligen Sprache (# für Bash Skripte und andere Dinge, // für C Code, etc.). Platzieren Sie den Kommentar vor vor dem Inhalt des Kommentars.

(Ersetzen Sie "john" mit Ihrem Benutzer Namen)
# id john

GuideXML wurde speziell dafür entwickelt, es Entwicklern zu ermöglichen, mehr Zeit mit dem Schreiben der Dokumentation und weniger mit dem Erlernen der eigentlichen XML-Syntax zu verbringen. Wir hoffen, dass dies den Entwicklern erlaubt, qualitativ hochwertige Gentoo-Dokumentation zu schreiben. Werfen Sie auch einen Blick auf die Tipps und Tricks rund um das Schreiben von Dokumentation (englisch). Wenn Sie uns helfen möchten (oder irgendeine Fragen zu GuideXML haben), dann senden Sie eine Nachricht an die gentoo-doc Mailingliste (in Englisch!). Wir wünschen viel Spaß!