<?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="en">
  <articleinfo>
    <title>GNOME Documentation Build Utilities</title>

    <abstract role="description">
      <para>The GNOME Documentation Build Utilities were created to make it
      easier for application developers to include and create documentation in
      their releases.</para>
    </abstract>

    <copyright>
      <year>2004</year>

      <holder>Shaun McCance</holder>
    </copyright>

    <publisher>
      <publishername>GNOME Documentation Project</publishername>
    </publisher>

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

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

        <surname>McCance</surname>

        <affiliation>
          <orgname>GNOME Documentation Project</orgname>
        </affiliation>

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

      <author>
        <firstname>Brent</firstname>

        <surname>Smith</surname>

        <affiliation>
          <orgname>GNOME Documentation Project</orgname>
        </affiliation>

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

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

        <date>2004-07-08</date>
      </revision>

      <revision>
        <revnumber>0.2</revnumber>

        <date>2006-02-04</date>
      </revision>
    </revhistory>
  </articleinfo>

  <section id="intro">
    <title>Introduction</title>

    <para>The GNOME Documentation Build Utilities were created to make it
    easier for application developers to include and create documentation in
    their releases.</para>

    <para>There are several advantages to using gnome-doc-utils in your
    application:</para>

    <para>
      <orderedlist>
        <listitem>
          <para>Translation is made much easier through the use of
          <application>xml2po</application>, which generates standard
          <filename>.po</filename> files from docbook/xml.</para>
        </listitem>

        <listitem>
          <para>OMF file creation is automated from a template file for all
          translated languages.</para>
        </listitem>

        <listitem>
          <para>Installation of documentation is automated.</para>
        </listitem>
      </orderedlist>
    </para>

    <para>GNOME Documentation Build Utilities are named
    <application>gnome-doc-utils</application> on the GNOME CVS server, so we
    will refer to them in this manner throughout the rest of this
    document.</para>
  </section>

  <section id="migrating">
    <title>Migrating to GNOME Documentation Build Utilities</title>

    <para>Many applications use an older method of including documentation. It
    is our intention that these applications switch over to gnome-doc-utils to
    provide a uniform method for building and installing documentation. The
    following instructions should help you to set up new documentation or port
    existing documentation to gnome-doc-utils.</para>

    <section>
      <title>Requirements</title>

      <para>Make sure you're using recent
      <application>gnome-common</application> (from 2005-07-19 or later) if
      you're using <filename>gnome-autogen.sh</filename>, or call
      <application>gnome-doc-prepare</application> in your
      <filename>autogen.sh</filename> by hand.</para>
    </section>

    <section>
      <title>Setting up <filename>help/Makefile.am</filename></title>

      <para>The standard location for documentation is in a subdir named
      <filename>help/</filename> in your directory structure. This name is not
      mandatory, although it is recommended. There should also be a
      <filename>help/C/</filename> subdirectory which contains the help
      document as <literal>document-name.xml</literal>.</para>

      <para>In the <filename>help</filename> directory, create a file named
      <filename>Makefile.am</filename>. Define the following variables inside
      the file:</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>Here is a brief description of what
      each variable does:</para>

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

            <listitem>
              <para>The name of the help document to build. This is the
              filename without the <literal>.xml</literal> extension. You
              should have help/C/$DOC_MODULE.xml</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>DOC_ENTITIES</term>

            <listitem>
              <para>List any files included in the help document using system
              entities.</para>

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

          <varlistentry>
            <term>DOC_INCLUDES</term>

            <listitem>
              <para>List any files that are included with the <ulink
              url="???">Xinclude</ulink> specification.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>DOC_FIGURES</term>

            <listitem>
              <para>List all the figures that are referenced in the help
              document.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>DOC_LINGUAS</term>

            <listitem>
              <para>List all the language codes for the languages in which the
              document is currently translated.</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </para>
    </section>

    <section>
      <title>Setting Up <filename>help/document-name.omf.in</filename></title>

      <para>GNOME Documentation Build Utilities require a template OMF file be
      installed at <filename>help/document-name.omf.in</filename>. This file
      contains a stripped down version of a Scrollkeeper OMF file. If you are
      porting documentation, you can modify your existing OMF file (and rename
      it) to meet these requirements.</para>

      <para><emphasis>PLEASE</emphasis> remember to change the documentation
      license if you are not using the GFDL. The GNOME documentation project
      does not endorse or recommend the use of this license without
      understanding the full implications of doing so.</para>

      <example id="example-omf-template">
        <title>Example of a OMF file template</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>If you are porting documentation to gnome-doc-utils, use the
          the same <code>seriesid</code> attribute on the
          <code>relation</code> element as defined in your old OMF file. This
          will ensure that when the new documentation gets installed, it will
          get replace the older version of the document.</para>
        </warning>
      </para>

      <para>GNOME Documentation Build Utilities will create a
      <filename>document-name-C.omf</filename> and an additional
      <filename>document-name-&lt;locale&gt;.omf</filename> for each language
      code defined in the DOC_LINGUAS variable in
      <filename>Makefile.am</filename>. Depending on certain elements present
      in the help document, gnome-doc-utils will generate additional elements
      in the OMF file. For more information on this, please see the next
      section, <xref linkend="settingup-document-name.xml" />.</para>

      <para>Where the documentation shows up in
      <application>Yelp</application> depends on the category that you defined
      in the <code>subject</code> element. You can see a list of valid
      scrollkeeper categories at <ulink
      url="http://scrollkeeper.sourceforge.net/documentation/categories.html">http://scrollkeeper.sourceforge.net/documentation/categories.html</ulink>.</para>

      <para>You can also get more information about what each element does by
      referring to the <ulink
      url="http://scrollkeeper.sourceforge.net/documentation/writing_scrollkeeper_omf_files/ar01s04.html#skomf-category">scrollkeeper
      docs</ulink>.</para>
    </section>

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

      <para>Create or move your help document to the location
      <filename>help/C/document-name.xml</filename> (replacing
      <literal>document-name</literal> with the actual document's name of
      course).</para>

      <para>Then you will need to add the following elements/attributes to the
      help document so that gnome-doc-utils will be able to populate the
      autogenerated OMF files with the correct information. For more
      information about where these elements should appear in the document,
      you can refer to the excellent site <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;This application
            is...&lt;/abstract&gt;</term>

            <listitem>
              <para>Include this element in the
              <code>&lt;articleinfo&gt;</code> section of your help document.
              Gnome-doc-utils will use this information to create a
              <code>&lt;description&gt;</code> element in the generated OMF
              file.</para>
            </listitem>
          </varlistentry>

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

            <listitem>
              <para>Include this element (as well as firstname and surname
              elements as children) in the <code>&lt;authorgroup&gt;</code>
              section under the <code>&lt;articleinfo&gt;</code> element.
              Gnome-doc-utils will use this information to create the
              <code>&lt;creator&gt;</code> element in the generated OMF
              file.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>&lt;author&gt;, &lt;corpauthor&gt;, &lt;editor&gt;,
            &lt;othercredit&gt;, or &lt;publisher&gt; with the attribute
            role="maintainer"</term>

            <listitem>
              <para>Include the attribute <code>role="maintainer"</code> on
              one of these elements so that gnome-docs-utils creates a
              <code>&lt;maintainer&gt;</code> element in the generated OMF
              file.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>&lt;title&gt; element of the &lt;article&gt; or
            &lt;articleinfo&gt;</term>

            <listitem>
              <para>Gnome-doc-utils uses the contents of this element to
              create the <code>&lt;title&gt;</code> element in the generated
              OMF file.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>&lt;date&gt; element in the last &lt;revision&gt; in your
            &lt;revhistory&gt;</term>

            <listitem>
              <para>Gnome-doc-utils uses the contents of this element to
              create the <code>&lt;date&gt;</code> element in the generated
              OMF file.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>&lt;revnumber&gt; element in the last &lt;revision&gt; in
            your &lt;revhistory&gt;</term>

            <listitem>
              <para>Gnome-doc-utils uses the contents of this element to
              create the <code>&lt;version&gt;</code> element in the generated
              OMF file.</para>
            </listitem>
          </varlistentry>
        </variablelist></para>

      <example id="example-omf-docbook">
        <title>Example of DocBook file with required elements</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>The example in <xref linkend="example-omf-autogen" /> produces the
      following omf file, when using the
      <filename>document-name.omf.in</filename> file listed in <xref
      linkend="example-omf-template" />.</para>

      <example id="example-omf-autogen">
        <title>OMF file autogenerated by gnome-doc-utils</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>Removing Leftover Files</title>

      <para>If you are porting old documentation to gnome-doc-utils, then it
      is recommended that you remove old
      <filename>help/C/Makefile.am</filename> files, as well as any language
      specific OMF files, such as <filename>help/C/document-name-C.omf or
      <filename>help/&lt;locale&gt;/Makefile.am</filename>.</filename></para>
    </section>

    <section>
      <title>Adding New Files</title>

      <para>If you don't already have one, create a <filename>m4</filename>
      directory in the toplevel directory, and create a
      <filename>m4/.cvsignore</filename> file. Add both of these files to
      CVS.</para>

      <para>Add a <filename>help/ChangeLog</filename>, analagous to
      <filename>po/ChangeLog</filename>, which is used to track translations
      and modifications to the help document. Also add this file to
      CVS.</para>

      <para>Since gnome-doc-utils autogenerates <filename>.omf</filename>
      files for each locale for which the help document is translated, you
      will probably want to create and add a
      <filename>help/.cvsignore</filename> and add this file to CVS.</para>
    </section>

    <section>
      <title>Modifying <filename>configure.ac</filename></title>

      <para>The following commands should be set in the
      <filename>configure.ac</filename> file.<orderedlist>
          <listitem>
            <para>Add <filename>help/Makefile</filename> to
            <function>AC_CONFIG_FILES</function> (or
            <function>AC_OUTPUT</function> if you still use the old
            method)</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>Modifying the Toplevel <filename>Makefile.am</filename></title>

      <para>The following modifications should be made to the toplevel
      <filename>Makefile.am</filename> file.</para>

      <orderedlist>
        <listitem>
          <para>Add gnome-doc-utils.make to
          <varname>EXTRA_DIST</varname>.</para>
        </listitem>

        <listitem>
          <para>Add gnome-doc-utils.make to
          <varname>DISTCLEANFILES</varname>.</para>
        </listitem>

        <listitem>
          <para>Add <code>--disable-scrollkeeper</code> to
          <varname>DISTCHECK_CONFIGURE_FLAGS</varname>.</para>
        </listitem>

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

          <note>
            <para>You must remember to add <filename>m4</filename> to
            <varname>EXTRA_DIST</varname> insite the top-level
            <filename>Makefile.am</filename>, otherwise the directory won't be
            added to the package and configure will fail (to catch this, you
            must do <command>make distcheck</command> after <command>make
            check</command>).</para>
          </note>
        </listitem>
      </orderedlist>
    </section>

    <section>
      <title>Modifying the <filename>.cvsignore</filename> files</title>

      <para>Certain files are generated during the build process that you want
      CVS to ignore when creating diffs and doing other functions. To make CVS
      ignore these files:</para>

      <orderedlist>
        <listitem>
          <para>Add <filename>gnome-doc-utils.make</filename> to the top-level
          <filename>.cvsignore</filename></para>
        </listitem>

        <listitem>
          <para>Add <filename>*.omf</filename> to the
          <filename>help/.cvsignore</filename> file</para>
        </listitem>
      </orderedlist>
    </section>

    <section>
      <title>Testing</title>

      <para>To test and see if everything works:</para>

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

    <section>
      <title>Additional Steps</title>

      <para>There are just a few more steps to follow to finish migrating to
      <application>gnome-doc-utils</application>:</para>

      <orderedlist>
        <listitem>
          <para>Add a <application>gnome-doc-utils</application> dependency
          for your module in the <application>jhbuild</application>
          moduleset.</para>
        </listitem>

        <listitem>
          <para>Migrate existing translations as described on <ulink
          url="http://live.gnome.org/GnomeDocUtilsTranslationMigration">GnomeDocUtilsTranslationMigration</ulink>
          (or just ask translators to do that for their own languages, since
          this may be harder to do)</para>
        </listitem>

        <listitem>
          <para>Change status of your module on <ulink
          url="http://live.gnome.org/GnomeDocUtilsMigration">GnomeDocUtilsMigration</ulink>
          (if applicable).</para>
        </listitem>
      </orderedlist>
    </section>

    <section>
      <title>Let Us Know About it!</title>

      <para>We would definitely like to know if you port your documentation to gnome-doc-utils, so 
      please send an email to the following mailing lists if you have converted (or started) using
      <application>gnome-doc-utils</application> to manage your documentation.</para>

      <para>Let <ulink
      url="mailto:gnome-doc-list@gnome.org">gnome-i18n@gnome.org</ulink> and <ulink
      url="mailto:gnome-doc-list@gnome.org">gnome-doc-list@gnome.org</ulink> know
      about it!</para>
    </section>
  </section>

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