<?xml version="1.0" encoding="utf-8"?>
<!-- -*- indent-tabs-mode: nil -*- -->
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<article id="index" lang="de">
  <articleinfo>
    <title>GNOME Werkzeuge zur Erstellung von Dokumentation</title>

    <abstract role="description">
      <para>Die GNOME Werkzeuge zur Erstellung von Dokumentation wurden entworfen, um Anwendungsentwicklern zu ermöglichen, Dokumentationen in ihren Veröffentlichungen mitzuliefern und erstellen zu lassen.</para>
    </abstract>

    <copyright>
      <year>2004</year>

      <holder>Shaun McCance</holder>
    </copyright><copyright><year>2009</year><holder>Mario Blättermann (mariobl@gnome.org)</holder></copyright>

    <publisher>
      <publishername>GNOME-Dokumentationsprojekt</publishername>
    </publisher>

    <include xmlns="http://www.w3.org/2001/XInclude" href="legal.xml"/>

    <authorgroup>
      <author role="maintainer">
        <firstname>Shaun</firstname>

        <surname>McCance</surname>

        <affiliation>
          <orgname>GNOME-Dokumentationsprojekt</orgname>
        </affiliation>

        <email>shaunm@gnome.org</email>
      </author>

      <author>
        <firstname>Brent</firstname>

        <surname>Smith</surname>

        <affiliation>
          <orgname>GNOME-Dokumentationsprojekt</orgname>
        </affiliation>

        <email>gnome@nextreality.net</email>
      </author>
    </authorgroup>

    <revhistory>
      <revision>
        <revnumber>0.1</revnumber>

        <date>8. Juli 2007</date>
      </revision>

      <revision>
        <revnumber>0.2</revnumber>

        <date>4. Februar 2006</date>
      </revision>
    </revhistory>
  </articleinfo>

  <section id="intro">
    <title>Einführung</title>

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

    <para>Die Verwendung der gnome-doc-utils in Ihrer Anwendung hat verschiedene Vorteile:</para>

    <para>
      <orderedlist>
        <listitem>
          <para>Übersetzungen werden durch die Nutzung von <application>xml2po</application> erheblich vereinfacht, welches standardisierte <filename>.po</filename>-Dateien aus DocBook/XML erzeugt.</para>
        </listitem>

        <listitem>
          <para>Die Erstellung der OMF-Datei geschieht automatisch aus einer Vorlagendatei für alle Übersetzungen.</para>
        </listitem>

        <listitem>
          <para>Die Installation der Dokumentation geschieht automatisch.</para>
        </listitem>
      </orderedlist>
    </para>

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

  <section id="migrating">
    <title>Migration auf die GNOME Werkzeuge zur Erstellung von Dokumentation</title>

    <para>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.</para>

    <section>
      <title>Erfordernisse</title>

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

    <section>
      <title>Erstellen der Datei <filename>help/Makefile.am</filename></title>

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

      <para>Erstellen Sie im Ordner <filename>help</filename> eine Datei namens <filename>Makefile.am</filename>. Definieren Sie in dieser Datei die folgenden Variablen:</para>

      <para><programlisting>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</programlisting>Hier eine kurze Beschreibung der Funktion der einzelnen Variablen:</para>

      <para>
        <variablelist>
          <varlistentry>
            <term>DOC_MODULE</term>

            <listitem>
              <para>Der Name des zu erstellenden Hilfedokuments. Dies ist der Dateiname ohne die Erweiterung <literal>.xml</literal>. Sie sollten also einen Dateinamen der Form help/C/$DOC_MODULE.xml haben.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>DOC_ENTITIES</term>

            <listitem>
              <para>Listet jegliche im Hilfedokument einbezogene Dateien auf, wobei die System-Entities verwendet werden.</para>

              <para>Beispiel: <code>&lt;!ENTITY SYSTEM "chapter1.xml"&gt;</code></para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>DOC_INCLUDES</term>

            <listitem>
              <para>Listet jegliche in der <ulink url="???">Xinclude</ulink>-Spezifikation einbezogene Dateien auf.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>DOC_FIGURES</term>

            <listitem>
              <para>Liste aller im Hilfedokument referenzierten Abbildungen.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>DOC_LINGUAS</term>

            <listitem>
              <para>Listet alle Sprachcodes für die Sprachen auf, in welchen das Dokument derzeit verfügbar ist.</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </para>
    </section>

    <section>
      <title>Erstellen der Datei <filename>help/document-name.omf.in</filename></title>

      <para>Die GNOME Werkzeuge zur Erstellung von Dokumentation benötigen eine Vorlage für eine OMF-Datei, die als <filename>help/document-name.omf.in</filename> 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.</para>

      <para><emphasis>Bitte denken Sie daran</emphasis>, 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.</para>

      <example id="example-omf-template">
        <title>Beispiel einer Vorlage für eine OMF-Datei</title>

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

      <para>
        <warning>
          <para>Falls Sie Dokumentation auf die gnome-doc-utils portieren, verwenden Sie das gleiche <code>seriesid</code>-Attribut im Element <code>relation</code>, 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.</para>
        </warning>
      </para>

      <para>GNOME-Werkzeuge zur Erstellung von Dokumentation erstellen eine Datei <filename>document-name-C.omf</filename> und eine zusätzliche Datei <filename>document-name-&lt;locale&gt;.omf</filename> für jeden Sprachcode, der in der Variable DOC_LINGUAS in <filename>Makefile.am</filename> 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, <xref linkend="settingup-document-name.xml"/>.</para>

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

      <para>Weitere Informationen über die Funktion der einzelnen Elemente finden Sie in der <ulink url="http://scrollkeeper.sourceforge.net/documentation/writing_scrollkeeper_omf_files/ar01s04.html#skomf-category">Dokumentation zu Scrollkeeper</ulink>.</para>
    </section>

    <section>
      <title>Einrichten von <filename id="settingup-document-name.xml">help/C/document-name.xml</filename></title>

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

      <para>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 <ulink url="http://www.docbook.org/tdg/en/html/">http://www.docbook.org/tdg/en/html/</ulink>.<variablelist>
          <varlistentry>
            <term>&lt;abstract role="description"&gt;Diese Anwendung ist …&lt;/abstract&gt;</term>

            <listitem>
              <para>Fügen Sie dieses Element zum Abschnitt <code>&lt;articleinfo&gt;</code> Ihres Hilfedokuments hinzu. Gnome-doc-utils verwendet diese Information zum Erstellen des Elements <code>&lt;description&gt;</code> in der generierten OMF-Datei.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>&lt;author&gt;...&lt;/author&gt;</term>

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

          <varlistentry>
            <term>&lt;author&gt;, &lt;corpauthor&gt;, &lt;editor&gt;, &lt;othercredit&gt;, oder &lt;publisher&gt; mit dem Attribut role="maintainer"</term>

            <listitem>
              <para>Fügen Sie das Attribut <code>role="maintainer"</code> zu einem dieser Elemente hinzu, so dass die gnome-doc-utils ein <code>&lt;maintainer&gt;</code>-Element in der generierten OMF-Datei erstellen können.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>&lt;title&gt;-Element von &lt;article&gt; oder &lt;articleinfo&gt;</term>

            <listitem>
              <para>Die gnome-doc-utils verwenden den Inhalt dieses Elements, um das <code>&lt;title&gt;</code>-Element in der zu erstellenden OMF-Datei zu erzeugen.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>&lt;date&gt;-Element in der letzten &lt;revision&gt; in Ihrer &lt;revhistory&gt;</term>

            <listitem>
              <para>Die gnome-doc-utils verwenden den Inhalt dieses Elements, um das <code>&lt;date&gt;</code>-Element in der zu erstellenden OMF-Datei zu erzeugen.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>&lt;revnumber&gt;-Element in der letzten &lt;revision&gt; in Ihrer &lt;revhistory&gt;</term>

            <listitem>
              <para>Die gnome-doc-utils verwenden den Inhalt dieses Elements, um das <code>&lt;version&gt;</code>-Element in der zu erstellenden OMF-Datei zu erzeugen.</para>
            </listitem>
          </varlistentry>
        </variablelist></para>

      <example id="example-omf-docbook">
        <title>Beispiel einer DocBook-Datei mit den benötigten Elementen</title>

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

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

    &amp;legal;

    &lt;authorgroup&gt;
      &lt;author role="maintainer"&gt;
        &lt;firstname&gt;Brent&lt;/firstname&gt;
        &lt;surname&gt;Smith&lt;/surname&gt;
        &lt;affiliation&gt;&lt;orgname&gt;GNOME Documentation Project&lt;/orgname&gt;&lt;/affiliation&gt;
      &lt;/author&gt;
    &lt;/authorgroup&gt;

    &lt;revhistory&gt;
      &lt;revision&gt;
        &lt;revnumber&gt;&amp;appname; Manual &amp;manrevision;&lt;/revnumber&gt;
        &lt;date&gt;2006-02-04&lt;/date&gt;
      &lt;/revision&gt;
    &lt;/revhistory&gt;

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

      <para>Das Beispiel in <xref linkend="example-omf-autogen"/> erzeugt die folgende OMF-Datei, wenn die Datei <filename>document-name.omf.in</filename> in <xref linkend="example-omf-template"/> verwendet wird.</para>

      <example id="example-omf-autogen">
        <title>Automatisch von den gnome-doc-utils erzeugte OMF-Datei</title>

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

    <section>
      <title>Entfernen nicht mehr benötigter Dateien</title>

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

    <section>
      <title>Hinzufügen neuer Dateien</title>

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

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

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

    <section>
      <title>Anpassung der Datei <filename>configure.ac</filename></title>

      <para>Die folgenden Befehle sollten zur Datei <filename>configure.ac</filename> hinzugefügt werden.<orderedlist>
          <listitem>
            <para>Fügen Sie <filename>help/Makefile</filename> zu <function>AC_CONFIG_FILES</function> hinzu (oder <function>AC_OUTPUT</function>, falls Sie die alte Methode benutzen)</para>
          </listitem>

          <listitem>
            <para><function>AC_CONFIG_MACRO_DIR</function>(<parameter>[m4]</parameter>)</para>
          </listitem>

          <listitem>
            <para>
              <function>GNOME_DOC_INIT</function>
            </para>
          </listitem>
        </orderedlist></para>
    </section>

    <section>
      <title>Anpassen der Datei <filename>Makefile.am</filename> in der obersten Ebene</title>

      <para>Die Datei <filename>Makefile.am</filename> in der obersten Ebene sollte wie folgt geändert werden.</para>

      <orderedlist>
        <listitem>
          <para>Fügen Sie gnome-doc-utils.make zu <varname>EXTRA_DIST</varname> hinzu.</para>
        </listitem>

        <listitem>
          <para>Fügen Sie gnome-doc-utils.make zu <varname>DISTCLEANFILES</varname> hinzu.</para>
        </listitem>

        <listitem>
          <para>Fügen Sie <code>--disable-scrollkeeper</code> zu <varname>DISTCHECK_CONFIGURE_FLAGS</varname> hinzu.</para>
        </listitem>

        <listitem>
          <para>Add <filename>m4</filename> to <varname>EXTRA_DIST</varname> 
            in the top-level Makefile.am</para>

          <note>
            <para>Vergessen Sie nicht, <filename>m4</filename> zu <varname>EXTRA_DIST</varname> zur Datei <filename>Makefile.am</filename> der obersten Ebene hinzuzufügen, anderenfalls wird der Ordner nicht zum Paket hinzugefügt und <command>configure</command> wird scheitern. Um dies zu gewährleisten, müssen Sie <command>make distcheck</command> nach <command>make check</command> ausführen.</para>
          </note>
        </listitem>
      </orderedlist>
    </section>

    <section>
      <title>Bearbeiten der <filename>.cvsignore</filename>-Dateien</title>

      <para>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:</para>

      <orderedlist>
        <listitem>
          <para>Fügen Sie <filename>gnome-doc-utils.make</filename> zur Datei <filename>.cvsignore</filename> der obersten Ebene hinzu.</para>
        </listitem>

        <listitem>
          <para>Fügen Sie <filename>*.omf</filename> zur Datei <filename>help/.cvsignore</filename> hinzu.</para>
        </listitem>
      </orderedlist>
    </section>

    <section>
      <title>Testen</title>

      <para>So können Sie testen, ob alles funktioniert:</para>

      <screen><prompt>$</prompt> <command>make &amp;&amp; make check</command></screen>
    </section>

    <section>
      <title>Weitere Schritte</title>

      <para>Nur noch wenige Schritte, und die Migration auf die <application>gnome-doc-utils</application> ist abgeschlossen:</para>

      <orderedlist>
        <listitem>
          <para>Fügen Sie eine Abhängigkeit zu den <application>gnome-doc-utils</application> für Ihr Modul im Modulsatz von <application>jhbuild</application> hinzu.</para>
        </listitem>

        <listitem>
          <para>Migrieren Sie vorhandene Übersetzungen wie in <ulink url="http://live.gnome.org/GnomeDocUtilsTranslationMigration">GnomeDocUtilsTranslationMigration</ulink> beschrieben. Oder bitten Sie die Übersetzer, dies für ihre Sprachen zu tun, denn das ist eine recht schwierige Aufgabe.</para>
        </listitem>

        <listitem>
          <para>Ändern Sie den Status Ihres Moduls auf <ulink url="http://live.gnome.org/GnomeDocUtilsMigration">GnomeDocUtilsMigration</ulink> (falls möglich).</para>
        </listitem>
      </orderedlist>
    </section>

    <section>
      <title>Berichten Sie darüber!</title>

      <para>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 <application>gnome-doc-utils</application> umgestellt oder mit der Umstellung begonnen haben.</para>

      <para>Informieren Sie <ulink url="mailto:gnome-doc-list@gnome.org">gnome-i18n@gnome.org</ulink> und <ulink url="mailto:gnome-doc-list@gnome.org">gnome-doc-list@gnome.org</ulink> darüber.</para>
    </section>
  </section>

  <include xmlns="http://www.w3.org/2001/XInclude" href="make-ref.xml"/>
</article>
