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.

2.1. 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.

2.2. 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.

2.3. 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 1Beispiel 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, Abschnitt 2 ― Migration auf die GNOME Werkzeuge zur Erstellung von Dokumentation.

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.

2.4. 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 2Beispiel 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 Beispiel 3 erzeugt die folgende OMF-Datei, wenn die Datei document-name.omf.in in Beispiel 1 verwendet wird.

Beispiel 3Automatisch 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>

2.5. 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.

2.6. 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.

2.7. 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

2.8. 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.

2.9. 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.

2.10. Testen

So können Sie testen, ob alles funktioniert:

$ make && make check

2.11. 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).

2.12. 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.