Migrating to GNOME Documentation Build Utilities
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.
- 2.1. Requirements
- 2.2. Setting up help/Makefile.am
- 2.3. Setting Up help/document-name.omf.in
- 2.4. Setting up help/C/document-name.xml
- 2.5. Removing Leftover Files
- 2.6. Adding New Files
- 2.7. Modifying configure.ac
- 2.8. Modifying the Toplevel Makefile.am
- 2.9. Modifying the .cvsignore files
- 2.10. Testing
- 2.11. Additional Steps
- 2.12. Let Us Know About it!
Make sure you're using recent gnome-common (from 2005-07-19 or later) if you're using gnome-autogen.sh, or call gnome-doc-prepare in your autogen.sh by hand.
2.2. Setting up help/Makefile.am
The standard location for documentation is in a subdir named help/ in your directory structure. This name is not mandatory, although it is recommended. There should also be a help/C/ subdirectory which contains the help document as document-name.xml.
In the help directory, create a file named Makefile.am. Define the following variables inside the file:
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
The name of the help document to build. This is the filename without the .xml extension. You should have help/C/$DOC_MODULE.xml
List any files included in the help document using system entities.
Example: <!ENTITY SYSTEM "chapter1.xml">
List any files that are included with the Xinclude specification.
List all the figures that are referenced in the help document.
List all the language codes for the languages in which the document is currently translated.
2.3. Setting Up help/document-name.omf.in
GNOME Documentation Build Utilities require a template OMF file be installed at help/document-name.omf.in. 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.
PLEASE 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.
<?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>
If you are porting documentation to gnome-doc-utils, use the the same seriesid attribute on the relation 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.
GNOME Documentation Build Utilities will create a document-name-C.omf and an additional document-name-<locale>.omf for each language code defined in the DOC_LINGUAS variable in Makefile.am. 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, Section 2 ― Migrating to GNOME Documentation Build Utilities.
Where the documentation shows up in Yelp depends on the category that you defined in the subject element. You can see a list of valid scrollkeeper categories at http://scrollkeeper.sourceforge.net/documentation/categories.html.
You can also get more information about what each element does by referring to the scrollkeeper docs.
Create or move your help document to the location help/C/document-name.xml (replacing document-name with the actual document's name of course).
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 http://www.docbook.org/tdg/en/html/.
- <abstract role="description">This application is...</abstract>
Include this element in the <articleinfo> section of your help document. Gnome-doc-utils will use this information to create a <description> element in the generated OMF file.
Include this element (as well as firstname and surname elements as children) in the <authorgroup> section under the <articleinfo> element. Gnome-doc-utils will use this information to create the <creator> element in the generated OMF file.
- <author>, <corpauthor>, <editor>, <othercredit>, or <publisher> with the attribute role="maintainer"
Include the attribute role="maintainer" on one of these elements so that gnome-docs-utils creates a <maintainer> element in the generated OMF file.
- <title> element of the <article> or <articleinfo>
Gnome-doc-utils uses the contents of this element to create the <title> element in the generated OMF file.
- <date> element in the last <revision> in your <revhistory>
Gnome-doc-utils uses the contents of this element to create the <date> element in the generated OMF file.
- <revnumber> element in the last <revision> in your <revhistory>
Gnome-doc-utils uses the contents of this element to create the <version> element in the generated OMF file.
<?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>
<?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. Removing Leftover Files
If you are porting old documentation to gnome-doc-utils, then it is recommended that you remove old help/C/Makefile.am files, as well as any language specific OMF files, such as help/C/document-name-C.omf or help/<locale>/Makefile.am.
2.6. Adding New Files
If you don't already have one, create a m4 directory in the toplevel directory, and create a m4/.cvsignore file. Add both of these files to CVS.
Add a help/ChangeLog, analagous to po/ChangeLog, which is used to track translations and modifications to the help document. Also add this file to CVS.
Since gnome-doc-utils autogenerates .omf files for each locale for which the help document is translated, you will probably want to create and add a help/.cvsignore and add this file to CVS.
2.7. Modifying configure.ac
The following commands should be set in the configure.ac file.
- Add help/Makefile to AC_CONFIG_FILES (or AC_OUTPUT if you still use the old method)
2.8. Modifying the Toplevel Makefile.am
The following modifications should be made to the toplevel Makefile.am file.
Add gnome-doc-utils.make to EXTRA_DIST.
Add gnome-doc-utils.make to DISTCLEANFILES.
Add --disable-scrollkeeper to DISTCHECK_CONFIGURE_FLAGS.
Add m4 to EXTRA_DIST in the top-level Makefile.am
You must remember to add m4 to EXTRA_DIST insite the top-level Makefile.am, otherwise the directory won't be added to the package and configure will fail (to catch this, you must do make distcheck after make check).
2.9. Modifying the .cvsignore files
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:
- Add gnome-doc-utils.make to the top-level .cvsignore
- Add *.omf to the help/.cvsignore file
To test and see if everything works:
$ make && make check
2.11. Additional Steps
There are just a few more steps to follow to finish migrating to gnome-doc-utils:
- Add a gnome-doc-utils dependency for your module in the jhbuild moduleset.
- Migrate existing translations as described on GnomeDocUtilsTranslationMigration (or just ask translators to do that for their own languages, since this may be harder to do)
- Change status of your module on GnomeDocUtilsMigration (if applicable).
2.12. Let Us Know About it!
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 gnome-doc-utils to manage your documentation.
- Copyright © 2004 Shaun McCance
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License (GFDL), Version 1.1 or any later version published by the Free Software Foundation with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. You can find a copy of the GFDL at this link or in the file COPYING-DOCS distributed with this manual.
This manual is part of a collection of GNOME manuals distributed under the GFDL. If you want to distribute this manual separately from the collection, you can do so by adding a copy of the license to the manual, as described in section 6 of the license.
Many of the names used by companies to distinguish their products and services are claimed as trademarks. Where those names appear in any GNOME documentation, and the members of the GNOME Documentation Project are made aware of those trademarks, then the names are in capital letters or initial capital letters.
DOCUMENT AND MODIFIED VERSIONS OF THE DOCUMENT ARE PROVIDED UNDER THE TERMS OF THE GNU FREE DOCUMENTATION LICENSE WITH THE FURTHER UNDERSTANDING THAT:
- DOCUMENT IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, WARRANTIES THAT THE DOCUMENT OR MODIFIED VERSION OF THE DOCUMENT IS FREE OF DEFECTS MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE OR NON-INFRINGING. THE ENTIRE RISK AS TO THE QUALITY, ACCURACY, AND PERFORMANCE OF THE DOCUMENT OR MODIFIED VERSION OF THE DOCUMENT IS WITH YOU. SHOULD ANY DOCUMENT OR MODIFIED VERSION PROVE DEFECTIVE IN ANY RESPECT, YOU (NOT THE INITIAL WRITER, AUTHOR OR ANY CONTRIBUTOR) ASSUME THE COST OF ANY NECESSARY SERVICING, REPAIR OR CORRECTION. THIS DISCLAIMER OF WARRANTY CONSTITUTES AN ESSENTIAL PART OF THIS LICENSE. NO USE OF ANY DOCUMENT OR MODIFIED VERSION OF THE DOCUMENT IS AUTHORIZED HEREUNDER EXCEPT UNDER THIS DISCLAIMER; AND
- UNDER NO CIRCUMSTANCES AND UNDER NO LEGAL THEORY, WHETHER IN TORT (INCLUDING NEGLIGENCE), CONTRACT, OR OTHERWISE, SHALL THE AUTHOR, INITIAL WRITER, ANY CONTRIBUTOR, OR ANY DISTRIBUTOR OF THE DOCUMENT OR MODIFIED VERSION OF THE DOCUMENT, OR ANY SUPPLIER OF ANY OF SUCH PARTIES, BE LIABLE TO ANY PERSON FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF GOODWILL, WORK STOPPAGE, COMPUTER FAILURE OR MALFUNCTION, OR ANY AND ALL OTHER DAMAGES OR LOSSES ARISING OUT OF OR RELATING TO USE OF THE DOCUMENT AND MODIFIED VERSIONS OF THE DOCUMENT, EVEN IF SUCH PARTY SHALL HAVE BEEN INFORMED OF THE POSSIBILITY OF SUCH DAMAGES.