Created some documentation for the build utilities; based the documents

2006-02-05  Brent Smith  <gnome@nextreality.net>
        * doc/gnome-doc-make/C/gnome-doc-make.xml:
        Created some documentation for the build utilities; based the
        documents off the GnomeDocUtilsMigrationHowTo page on the wiki

2 files changed, 572 insertions, 12 deletions

diff --git a/ChangeLog b/ChangeLog
index 4b3b723..842809e 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2006-02-05  Brent Smith  <gnome@nextreality.net>
+
+	* doc/gnome-doc-make/C/gnome-doc-make.xml:
+	Created some documentation for the build utilities; based the
+	documents off the GnomeDocUtilsMigrationHowTo page on the wiki
+
 2006-01-31  Shaun McCance  <shaunm@gnome.org>
 
 	* xslt/docbook/html/db2html-block.xsl:
diff --git a/doc/gnome-doc-make/C/gnome-doc-make.xml b/doc/gnome-doc-make/C/gnome-doc-make.xml
index bafb75f..0095301 100644
--- a/doc/gnome-doc-make/C/gnome-doc-make.xml
+++ b/doc/gnome-doc-make/C/gnome-doc-make.xml
@@ -1,43 +1,597 @@
-<?xml version='1.0' encoding='utf-8'?><!-- -*- indent-tabs-mode: nil -*- -->
+<?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" [
-]>
-
+"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"/>
+
+    <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" />
+
     <authorgroup>
-      <author>
+      <author role="maintainer">
         <firstname>Shaun</firstname>
+
         <surname>McCance</surname>
-	<affiliation>
+
+        <affiliation>
           <orgname>GNOME Documentation Project</orgname>
-	</affiliation>
-	<email>shaunm@gnome.org</email>
+        </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">
+  <section>
     <title>Introduction</title>
 
-    <para>Foo</para>
+    <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>
 
-  <include href="make-ref.xml" xmlns="http://www.w3.org/2001/XInclude"/>
+  <section>
+    <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>