Migrating your documentation to gnome-doc-utils

Advantages

1. You get a build system that works for you
2. You get translated docs which are easier to maintain

3. You get translation status pages for you docs: http://l10n.gnome.org/

4. Everybody starts loving you

...

Porting your documentation to g-d-u

1. 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. If you have documentation in eg. "help" (if you have multiple documents each in "help/blah", "help/foo", just substitute "help" with that), enter the "help" subdirectory, and create Makefile.am with the following content (removing any other):

   include $(top_srcdir)/gnome-doc-utils.make
   dist-hook: doc-dist-hook
   DOC_MODULE = document-name
   DOC_ENTITIES =
   DOC_INCLUDES = legal.xml
   DOC_FIGURES = figures/main_window.png      \
                 figures/open_document.png
   DOC_LINGUAS =

   • DOC_MODULE is the base name of your document, you should have "help/C/$DOC_MODULE.xml"; DOC_ENTITIES is for files included using entities (<!ENTITY>), and DOC_INCLUDES for files included using xinclude (this is preferred). Finally, DOC_LINGUAS is a variable containing a list of language codes for document translations

3. Make use of your existing help/C/document-name-C.omf to create a stripped down version inside help/document-name.omf.in:

   <?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>

   (this example is from gnome-hello; be sure to keep your values of seriesid, category, type, and rights). Check scrollkeeper docs for details.

4. Move your start document to help/C/$DOC_MODULE.xml, and add stuff for populating .omf files:

   • .omf field	gdu docbook equivalent
     description	An <abstract role="description"> in your <articleinfo>
     creator	Both <author> and <corpauthor> in your <articleinfo>
     maintainer	Any of <author>, <corpauthor>, <editor>, <othercredit>, or <publisher> with the attribute role="maintainer"
     title	The <title> element of the <article> or <articleinfo>
     date	The <date> element in the last <revision> in your <revhistory>
     version	The <revnumber> element in the last <revision> in your <revhistory>

5. Remove leftovers such as help/C/Makefile.am and help/C/*.omf

6. Set your build system up:

   • If you don't have one yet, create a m4 directory in your toplevel source directory; and create a .cvsignore file in it containing at least gnome-doc-utils.m4. Add this directory and its .cvsignore to cvs.

   • Add the following to configure.ac (resp. configure.in):

     • AC_CONFIG_MACRO_DIR([m4])

     • GNOME_DOC_INIT

     • help/Makefile to AC_CONFIG_FILES (or AC_OUTPUT if you still use the old method)

   • Add gnome-doc-utils.make to EXTRA_DIST and DISTCLEANFILES, and --disable-scrollkeeper to DISTCHECK_CONFIGURE_FLAGS in the top-level Makefile.am

   • Add m4 to EXTRA_DIST in the top-level Makefile.am See below Note 2

   • Add gnome-doc-utils.make to the top-level .cvsignore

   • Add *.omf to the help directory's .cvsignore

7. Add help/ChangeLog analogous to po/ChangeLog so that translation changes can be tracked separately and be found easily

8. Test if it works: make all && make check

9. Add a gnome-doc-utils dependency for your module in the jhbuild moduleset

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

11. Let gnome-i18n@gnome.org and gnome-doc-list@gnome.org know about it!

12. Change status of your module on GnomeDocUtilsMigration (if applicable)

Status

Status of migration is on the page GnomeDocUtilsMigration.

Discussion

Problems, solutions, tips, tricks, whatever.

VincentNoel : I've tried applying these steps to gnome-utils, but failed miserably. gnome-utils is set up in a weird way (for historical reasons I guess) : several applications are installed in subdirectories of the toplevel. There is a help/ directory in each of these directories, while translations are all gathered in po/ in the toplevel. My auto* powers are very weak, so I have no idea what I'm doing while following the steps outlined here, which explains why the compilation fails (I think it complains that gnome-doc-utils.make.in cannot be found, or something like that). Some parts of this page are also not very clear if you don't know anything about doc files ("DOC_ENTITIES is for files included using entities (<!ENTITY>)" ? "be sure to keep your values of seriesid, category, type, and rights" ? What am I supposed to do exactly ?) Any hint ?

Note 2:

EmmanueleBassi: 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).

• TommiVainikainen: For me actually very opposite is happening. If EXTRA_DIST contains m4, then make distcheck fails, but if it does not contain, make distcheck works. This is with Automake 1.9 and GNOME Nettool from HEAD which I tried to migrate.

• chpe: It is definitely unnecessary to add m4 to EXTRA_DIST since those m4 files in there that are used are automatically dist'ed. (Verified with automake 1.9)

CategoryDocumentationProject