# GNOME Werkzeuge zur Erstellung von Dokumentation

## Einführung

Die GNOME Werkzeuge zur Erstellung von Dokumentation wurden entworfen, um Anwendungsentwicklern zu ermöglichen, Dokumentationen in ihren Veröffentlichungen mitzuliefern und erstellen zu lassen.

Die Verwendung der gnome-doc-utils in Ihrer Anwendung hat verschiedene Vorteile:

1. Übersetzungen werden durch die Nutzung von xml2po erheblich vereinfacht, welches standardisierte `.po`-Dateien aus DocBook/XML erzeugt.

2. Die Erstellung der OMF-Datei geschieht automatisch aus einer Vorlagendatei für alle Übersetzungen.

3. Die Installation der Dokumentation geschieht automatisch.

Die GNOME Werkzeuge zur Erstellung von Dokumentation werden auf dem CVS-Server von GNOME gnome-doc-utils genannt, daher beziehen wir uns im Folgenden auf diesen Namen.

## Migration auf die GNOME Werkzeuge zur Erstellung von Dokumentation

Viele Anwendungen benutzen zur Erstellung der Dokumentation eine ältere Methode. Es ist unser Ziel, dass diese Anwendungen auf die gnome-doc-utils umschwenken, um eine einheitliche Methode zur Erstellung und Installation von Dokumentationen bereitzustellen. Die folgenden Anweisungen sollen Ihnen dabei helfen, neue Dokumentationen zu erstellen oder vorhandene Dokumentationen auf die gnome-doc-utils zu portieren.

### Erfordernisse

Stellen Sie sicher, dass Sie eine aktuelle Version von gnome-common verwenden (vom 19. Juli 2005 oder neuer), wenn Sie `gnome-autogen.sh` benutzen. Anderenfalls fügen Sie gnome-doc-prepare zur Datei `autogen.sh` manuell hinzu.

### Erstellen der Datei `help/Makefile.am`

Der Standardort für Dokumentation ist ein Unterordner namens `help/` in Ihrer Ordnerstruktur. Dieser Name ist nicht zwingend vorgeschrieben, aber empfehlenswert. Auẞerdem sollte ein Unterordner namens `help/C/` vorhanden sein, welcher ein Hilfedokument wie beispielsweise `document-name.xml` enthält.

Erstellen Sie im Ordner `help` eine Datei namens `Makefile.am`. Definieren Sie in dieser Datei die folgenden Variablen:

    include $(top_srcdir)/gnome-doc-utils.make
    dist-hook: doc-dist-hook

    DOC_MODULE = document-name
    DOC_ENTITIES = legal.xml
    DOC_INCLUDES = filename.c
    DOC_FIGURES = figures/main_window.png      \
                  figures/open_document.png

    DOC_LINGUAS = es sr uk

Hier eine kurze Beschreibung der Funktion der einzelnen Variablen:

DOC_MODULE

- Der Name des zu erstellenden Hilfedokuments. Dies ist der Dateiname ohne die Erweiterung `.xml`. Sie sollten also einen Dateinamen der Form help/C/$DOC_MODULE.xml haben.

DOC_ENTITIES

- Listet jegliche im Hilfedokument einbezogene Dateien auf, wobei die System-Entities verwendet werden.

  Beispiel: `<!ENTITY SYSTEM "chapter1.xml">`

DOC_INCLUDES

- Listet jegliche in der Xinclude-Spezifikation einbezogene Dateien auf.

DOC_FIGURES

- Liste aller im Hilfedokument referenzierten Abbildungen.

DOC_LINGUAS

- Listet alle Sprachcodes für die Sprachen auf, in welchen das Dokument derzeit verfügbar ist.

### Erstellen der Datei `help/document-name.omf.in`

Die GNOME Werkzeuge zur Erstellung von Dokumentation benötigen eine Vorlage für eine OMF-Datei, die als `help/document-name.omf.in` verfügbar sein muss. Diese Datei enthält eine Basisversion einer von Scrollkeeper lesbaren Version einer OMF-Datei. Falls Sie Ihre Dokumentation portieren wollen, können Sie zu diesem Zweck Ihre vorhandene OMF-Datei anpassen und umbenennen.

Bitte denken Sie daran, die Lizenz der Dokumenation zu ersetzen, falls Sie nicht die GFDL verwenden wollen. Das GNOME-Dokumentationsprojekt rät von der Nutzung dieser Lizenz ab, wenn Sie sich über die Folgen der Implementation dieser Lizenz nicht absolut im Klaren sind.

#### Beispiel einer Vorlage für eine OMF-Datei

    <?xml version="1.0" standalone="no"?>
    <omf>
      <resource>
        <subject category="GNOME|Tutorials"/>
        <type>manual</type>
        <relation seriesid="b57e7e48-be78-11d6-85a3-d094906a987c"/>
        <rights type="GNU FDL" license.version="1.1" holder="Shaun McCance"/>
      </resource>
    </omf>

Falls Sie Dokumentation auf die gnome-doc-utils portieren, verwenden Sie das gleiche `seriesid`-Attribut im Element `relation`, wie Sie es in Ihrer alten OMF-Datei verwendet haben. Das stellt bei der Installation der neuen Dokumentation sicher, dass die alte Version des Dokuments dadurch ersetzt wird.

GNOME-Werkzeuge zur Erstellung von Dokumentation erstellen eine Datei `document-name-C.omf` und eine zusätzliche Datei `document-name-<locale>.omf` für jeden Sprachcode, der in der Variable DOC_LINGUAS in `Makefile.am` definiert ist. Abhängig von den verschiedenen im Dokument enthaltenen Elementen erzeugen die gnome-doc-utils zusätzliche Elemente in der OMF-Datei. Weitere Informationen darüber finden Sie im nächsten Abschnitt, settingup-document-name.xml.

Wo die Dokumentation später in Yelp erscheint, hängt von der im Element `subject` definierten Kategorie ab. Eine Liste der verfügbaren Scrollkeeper-Kategorien finden Sie in http://scrollkeeper.sourceforge.net/documentation/categories.html.

Weitere Informationen über die Funktion der einzelnen Elemente finden Sie in der Dokumentation zu Scrollkeeper.

### Einrichten von `help/C/document-name.xml`

Erstellen Sie Ihr Hilfedokument in `help/C/document-name.xml` oder verschieben Sie es dorthin. Vergessen Sie dabei nicht, `document-name` durch den Namen Ihres aktuellen Dokuments zu ersetzen.

Weiterhin müssen Sie die folgenden Elemente/Attribute zum Hilfedokument hinzufügen, so dass die gnome-doc-utils in der Lage sind, die automatisch erzeugten OMF-Dateien mit korrekten Informationen zu veröffentlichen. Weitere Informationen darüber, wo diese Elemente im Dokument erscheinen sollen, finden sie auf der hervorragenden Seite http://www.docbook.org/tdg/en/html/.

<abstract role="description">Diese Anwendung ist …</abstract>

- Fügen Sie dieses Element zum Abschnitt `<articleinfo>` Ihres Hilfedokuments hinzu. Gnome-doc-utils verwendet diese Information zum Erstellen des Elements `<description>` in der generierten OMF-Datei.

<author>...</author>

- Fügen Sie dieses Element (und zusätzlich Vor- und Zuname) zum Abschnitt `<authorgroup>` unter dem Element `<articleinfo>` hinzu. Gnome-doc-utils verwendet diese Information zum Erstellen des Elements `<creator>` in der generierten OMF-Datei.

<author>, <corpauthor>, <editor>, <othercredit>, oder <publisher> mit dem Attribut role="maintainer"

- Fügen Sie das Attribut `role="maintainer"` zu einem dieser Elemente hinzu, so dass die gnome-doc-utils ein `<maintainer>`-Element in der generierten OMF-Datei erstellen können.

<title>-Element von <article> oder <articleinfo>

- Die gnome-doc-utils verwenden den Inhalt dieses Elements, um das `<title>`-Element in der zu erstellenden OMF-Datei zu erzeugen.

<date>-Element in der letzten <revision> in Ihrer <revhistory>

- Die gnome-doc-utils verwenden den Inhalt dieses Elements, um das `<date>`-Element in der zu erstellenden OMF-Datei zu erzeugen.

<revnumber>-Element in der letzten <revision> in Ihrer <revhistory>

- Die gnome-doc-utils verwenden den Inhalt dieses Elements, um das `<version>`-Element in der zu erstellenden OMF-Datei zu erzeugen.

#### Beispiel einer DocBook-Datei mit den benötigten Elementen

    <?xml version="1.0" encoding="utf-8"?>
    <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
      <!ENTITY legal SYSTEM "legal.xml">
      <!ENTITY appversion "1.0">
      <!ENTITY manrevision "1.0">
      <!ENTITY date "February 2006">
      <!ENTITY app "<application>My application</application>">
      <!ENTITY appname "My GNOME App">
    ]>

    <article id="index" lang="en">
      <articleinfo>
        <title>&appname; Manual</title>
        <abstract role="description">
          <para>&appname; is a program that ...</para>
        </abstract>
        <copyright>
          <year>2006</year>
          <holder>Brent Smith</holder>
        </copyright>
        <publisher>
          <publishername> GNOME Documentation Project </publishername>
        </publisher>

        &legal;

        <authorgroup>
          <author role="maintainer">
            <firstname>Brent</firstname>
            <surname>Smith</surname>
            <affiliation><orgname>GNOME Documentation Project</orgname></affiliation>
          </author>
        </authorgroup>

        <revhistory>
          <revision>
            <revnumber>&appname; Manual &manrevision;</revnumber>
            <date>2006-02-04</date>
          </revision>
        </revhistory>

        <releaseinfo>This manual describes version &appversion; of &appname;</releaseinfo>
      </articleinfo>
      <section>
        <title>Introduction</title>
        <para>Foo</para>
      </section>
    </article>

Das Beispiel in example-omf-autogen erzeugt die folgende OMF-Datei, wenn die Datei `document-name.omf.in` in example-omf-template verwendet wird.

#### Automatisch von den gnome-doc-utils erzeugte OMF-Datei

    <?xml version="1.0" encoding="utf-8"?>
    <omf>
      <resource>
        <creator>(Brent Smith)</creator>
        <maintainer>(Brent Smith)</maintainer>
        <title>My GNOME App Manual</title>
        <date>2006-02-04</date>
        <version identifier="My GNOME App Manual 1.0" date="2006-02-04"/>
        <subject category="GNOME|Tutorials"/>
        <description>
          My GNOME App is a program that ...
        </description>
        <type>manual</type>
        <format mime="" dtd="-//OASIS//DTD DocBook XML V4.1.2//EN"/>
        <identifier url="file:///opt/gnome2/share/gnome/help/test/C/test.xml"/>
        <language code="C"/>
        <relation seriesid="b57e7e48-be78-11d6-85a3-d094906a987c"/>
        <rights type="GNU FDL" license.version="1.1" holder="Shaun McCance"/>
      </resource>
    </omf>

### Entfernen nicht mehr benötigter Dateien

Falls Sie alte Dokumentationen auf die gnome-doc-utils portieren wollen, ist es empfehlenswert, alte `help/C/Makefile.am`-Dateien zu löschen. Ebenfalls sollten sprachspezifische OMF-Dateien gelöscht werden, wie beispielsweise `help/C/document-name-C.omf` oder `help/<locale>/Makefile.am`.

### Hinzufügen neuer Dateien

Falls Sie nicht schon darüber verfügen, erstellen Sie einen Ordner namens `m4` im Ordner der obersten Ebene und erstellen Sie darin eine Datei `m4/.cvsignore`. Fügen Sie beide Dateien zum CVS hinzu.

Fügen Sie die Datei `help/ChangeLog` hinzu, analog zur Datei `po/ChangeLog`, welche dann zur Verfolgung von Änderungen und Übersetzungen in Ihrem Dokument benutzt wird. Fügen Sie diese Datei auch zum CVS hinzu.

Da die gnome-doc-utils automatisch `.omf`-Dateien für jede Sprache erzeugen, in die das Hilfedokument übersetzt werden soll, sollte auch eine Datei `help/.cvsignore` zum CVS hinzugefügt werden.

### Anpassung der Datei `configure.ac`

Die folgenden Befehle sollten zur Datei `configure.ac` hinzugefügt werden.

1. Fügen Sie `help/Makefile` zu `AC_CONFIG_FILES` hinzu (oder `AC_OUTPUT`, falls Sie die alte Methode benutzen)

2. `AC_CONFIG_MACRO_DIR`(`[m4]`)

3. `GNOME_DOC_INIT`

### Anpassen der Datei `Makefile.am` in der obersten Ebene

Die Datei `Makefile.am` in der obersten Ebene sollte wie folgt geändert werden.

1. Fügen Sie gnome-doc-utils.make zu `EXTRA_DIST` hinzu.

2. Fügen Sie gnome-doc-utils.make zu `DISTCLEANFILES` hinzu.

3. Fügen Sie `--disable-scrollkeeper` zu `DISTCHECK_CONFIGURE_FLAGS` hinzu.

4. Add `m4` to `EXTRA_DIST` in the top-level Makefile.am

   Vergessen Sie nicht, `m4` zu `EXTRA_DIST` zur Datei `Makefile.am` der obersten Ebene hinzuzufügen, anderenfalls wird der Ordner nicht zum Paket hinzugefügt und `configure` wird scheitern. Um dies zu gewährleisten, müssen Sie `make distcheck` nach `make check` ausführen.

### Bearbeiten der `.cvsignore`-Dateien

Einige der während des Erstellungsprozesses erzeugten Dateien sollten von der Versionsverwaltung ignoriert werden, beispielsweise dann, wenn Diff-Dateien erstellt werden. So weisen Sie CVS an, diese Dateien zu ignorieren:

1. Fügen Sie `gnome-doc-utils.make` zur Datei `.cvsignore` der obersten Ebene hinzu.

2. Fügen Sie `*.omf` zur Datei `help/.cvsignore` hinzu.

### Testen

So können Sie testen, ob alles funktioniert:

    $ make && make check

### Weitere Schritte

Nur noch wenige Schritte, und die Migration auf die gnome-doc-utils ist abgeschlossen:

1. Fügen Sie eine Abhängigkeit zu den gnome-doc-utils für Ihr Modul im Modulsatz von jhbuild hinzu.

2. Migrieren Sie vorhandene Übersetzungen wie in GnomeDocUtilsTranslationMigration beschrieben. Oder bitten Sie die Übersetzer, dies für ihre Sprachen zu tun, denn das ist eine recht schwierige Aufgabe.

3. Ändern Sie den Status Ihres Moduls auf GnomeDocUtilsMigration (falls möglich).

### Berichten Sie darüber!

Wir möchten gern darüber informiert werden, wenn Sie Ihre Dokumentation auf die gnome-doc-utils portiert haben. Bitte senden Sie eine E-Mail an eine der folgenden Mailinglisten, sobald Sie Ihre Dokumentation auf die Nutzung der gnome-doc-utils umgestellt oder mit der Umstellung begonnen haben.

Informieren Sie gnome-i18n@gnome.org und gnome-doc-list@gnome.org darüber.