Help improve Glib/GTK+ documentation

Update: Before start working in a module, check that It’s not already deprecated (like CList or CTree): these modules will be removed in GTK+3 so the doc migration is not needed

One of the tasks to improve the GTK+/Glib docs maintenance is to convert the documentation from templates (*.sgml) files into source-comments. This is a easy tasks that everybody can do.

All the process is documented here: [1]

Here a step-by-step example to help new contributors ;)

  1. Download GTK+ and gtk-doc source code:

    cd ~/git
    git clone git://
    git clone git://

  2. Execute gtk-doc script to convert the documentation

    cd gtk+/docs/reference/gtk
    ~/git/gtk-doc/tools/ –module=gtk

    This creates a “src” directory containing “*.c” files with all the comments.

  3. Copy and paste them to the right place.

    The section docs are best placed in the *.c file. Put them below the copyright header and the main includes (if there is no *.c file use the appropriate *.h file).
    All other comment blocks should be put directly above the definition of the symbol.

    For example, for GtkAccelGroup, we’d move the comments from gtk+/docs/reference/gtk/src/gtkaccelgroup.c to gtk+/gtkaccelgroup.c and gtk+/gtkaccelgroup.h

  4. Remove the template file:

    git rm docs/reference/gtk/tmpl/gtkaccelgroup.sgml

  5. Check that the documentation is correctly generated with:

    ./autogen –enable-gtk-doc

    then go with a browser to docs/reference/gtk/html

  6. Send a patch to bugzilla and make it block 599599 for GTK+ or 589775 for Glib documentation.
  7. Update the wiki page [1] to avoid duplicate work

When adding the source code comment, its a good opportunity to review it a bit. Have a look on spelling and style. Is it really giving a helpful explanation what the function does, etc. Also improve cross references. The gtk-doc syntax of the comments is described in the gtk-doc manual [2].

You can take a look to the gtkwidget.h [3] and gtkwidget.c [4] code as an example.





Modernize your autotools build system

Update: I converted this post in a new GnomeGoal, see here

Update 2: Added some more tips

Autotools is the most common system to build programs in GTK+/GNOME projects.

Remove deprecated macros for our file and use the new syntax will do our build system more legible and portable

The Autotools comes with a program to make the work for us, simply run


in you source tree and you have a new updated (Checks the result for possibles errors)

Some more tips:

  • Respect the standard layout
  • Try to avoid the use of AM_MAINTAINER_MODEAM_MAINTAINER_MODE (called like that) disables dependency-checking for autotools-generated stuff. AM_MAINTAINER_MODE([enabled]) retains the default behavior, but lets users pass a configure option to disable the dependency checking. So, if you really need this macro, use AM_MAINTAINER_MODE([enabled]). See the automake manual for a extended explanation
  • Use all the parameters of AC_INIT() (for the fifth parameter you need autoconf >= 2.64):
  • Use updated versions of the programs (all of these versions (and newer) are present in Debian stable):
    • automake >= 1.11.1 (AM_INIT_AUTOMAKE([1.11.1])) (or 1.10.3, Automake < 1.10.3 and 1.11 are known to be suffering from critical security issues)
    • autoconf >= 2.64 (AC_PREREQ(2.64))
    • libtool >= 2.2.6 (LT_PREREQ([2.2.6]))
    • intltool >= 0.40.0 (IT_PROG_INTLTOOL([0.40.0]))
  • Take a look to all AM_INIT_AUTOMAKE() posible parameters. For example, to use 1.11.1 automake version and generate bzip2 distribution tarballs in addition to the gzip’ed:
AM_INIT_AUTOMAKE([1.11.1 dist-bzip2])
  • Use LT_INIT() syntax for libtool (needs libtool >= 2.2.0). More info about LT_INIT(). For example, change this:

For this:

LT_INIT([dlopen win32-dll disable-static])
  • Don’t use GNOME_COMMON_INIT, as it does not work with autoreconf. Simply add this to your (You have to define the macros dir in your, in this case: AC_CONFIG_MACRO_DIR([m4]))
  • Use gnome-common macros for compile warnings macros instead custom ones. Also use GNOME_MAINTAINER_MODE_DEFINES to get warnings when using deprecated symbols:

Other tips

Feel free to suggest more tips in the comments!

Some documentation:

Flattr this

Help cleaning GNOME Bugzilla

Do you want to help cleaning GNOME Bugzilla?

Are you afraid because you are a newbie? Or you don’t know where to start?

In a recent Bugsquad meeting [1], a new initiative was propossed: the BugsquadGoals [2] .

This is the objective: Setting small concrete goals to clean some kind of bugs from the database.

For example: Search for bugs about a crash without the correct value in severity field (critical). Also, set the keyword STACKTRACE if the bug has a decent Stacktrace with line numbers and symbols.

You have more info and the bugzilla queries in the BugsquadGoals page [2]. Also, any suggestion for other queries are always welcomed.

If you have any problem or you want to request some Bugzilla permissions, we are in #bugs irc channel on

See you there!



2009: My GNOME year

2009 was a great year: I started to contribute to GNOME this year for the first time.

I’ve worked in Gnome 3 cleanup tasks, bugsquad, GnomeGoals and finally I’ve done some GTK+ patches.

After reading Andre Annual GNOME Bugzilla statistics for 2009, I’ve recollected some of my statistics since my first bug report in 2009-04-26 (255 days ago): [1]

  • 201 Bugs reported (4th position)
  • 300 patches (2th position)

Although some of the patches are quite trivial, I think that they are good numbers for a newbie like me ;)

But the best thing was meet great people in the GNOME community; Thank you to all the people that help me this year, was great work with you ;)

Looking forward to 2010!


Adapt your module to GNOME3 / GTK+3

Hello all!

I’ve been working in GNOME3 “cleaning” tasks for some time and I’d like to share this mini-guide to make your library/application GNOME3 / GTK+3-compilant. The process is quite easy:


Don’t use deprecated libraries:

GTK+ 3:

When you finish, use GNOME_MAINTAINER_MODE_DEFINES macro ( included in gnome-common ) in your files, so you will be notified when you use a new deprecated symbol.

Also, take a look to the awesome Frederic Peters graphs to track the status of your module:

This work by Javier Jardón is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported.