/!\ Warning:
This is obsoleted by Initiatives/GnomeGoals/NewDocumentationInfrastructure
Projects should now move to yelp-tools

Migrating your documentation to gnome-doc-utils

/!\ See http://developer.gnome.org/gnome-doc-make/ for the official documentation


  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_INCLUDES = legal.xml
    DOC_FIGURES = figures/main_window.png      \
    • 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"?>
        <subject category="GNOME|Tutorials"/>
        <relation seriesid="b57e7e48-be78-11d6-85a3-d094906a987c"/>
        <rights type="GNU FDL" license.version="1.1" holder="Shaun McCance"/>

    (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


      An <abstract role="description"> in your <articleinfo>


      Both <author> and <corpauthor> in your <articleinfo>


      Any of <author>, <corpauthor>, <editor>, <othercredit>, or <publisher> with the attribute role="maintainer"


      The <title> element of the <article> or <articleinfo>


      The <date> element in the last <revision> in your <revhistory>


      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])


      • 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 of migration is on the page GnomeDocUtilsMigration.


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)


Projects/GnomeDocUtils/MigrationHowTo (last edited 2014-01-18 18:28:17 by BaptisteMilleMathias)