Gnome Documentation

Rich had an
interesting blog about a Gnome book
. One of the things I found
interesting about it was that his proposal shares a number of
similarities with the
Developing with Gnome
guide I wrote for gnome-love (and which I
need to get back to and add more info, update, etc.). I thought it
might be fun to compare and contrast. I’d like feedback on whether I
should incorporate more of the things that Rich suggests. Of course,
I’d also love to have volunteers to assist. 🙂

Rich’s first introductory chapter covers basic info about the Gnome
project, guides for users, bug reporting and similar things. I really
don’t cover this kind of information at all. I do have a section in
my guide on
building gnome from CVS
, but what I have is probably much
different in scope since it tries to also provide general methods for
overcoming build obstacles (I think I’ve only once ever had a build
from CVS run to completion without any intervention).

Rich then suggests spending the second chapter on choosing a job, todo
lists that exist, and the gnome-love project. I have a section on
joining the Gnome community
, but it is much smaller in scope. I
basically point to a web page that lists the many projects he covers
individually and then mention a little more detail about the bugsquad
or quality assurance team (simply because that is the one I am the
most familiar with). I don’t cover TODO lists at all; I had thought
of something slightly similar but it definitely isn’t included yet.

Rich suggests spending the third chapter on gnome communication,
finding the right person to contact, and other resources. I believe I
cover most of this stuff in my
joining the Gnome community
and
important websites
sections. I definitely don’t have IRC or
finding the right contact for a given project covered, though.

Rich suggests a variety of things for the fourth chapter. First he
starts with development tools. I cover cvs and a number of other
important tools (e.g. pkg-config) in my
general tools
section. I do not cover autoconf, automake,
libtool, and popt (command line parsing)
on purpose
, although I do
explain what they are and what they are used for
and provide
links to outside tutorials
. (Update: popt isn’t covered in those
two sections; instead it’s in the overview of Gnome and related libraries–see
below) I have a section on
common filenames and filetypes
which explain some common support
files but I’m not sure if that’s what Rich had in mind. I don’t cover
anything on saving state, and I don’t have anything specific on
usability, i18n, l10n, or a11y.

Rich’s fifth suggested chapter provides an API reference, an overview
of various libraries, language bindings, and glade. I don’t have an
API reference, but I do have an
overview of Gnome and related libraries
, and I cover gtkmm,
gtk2-perl, and pygtk bindings pretty thoroughly (all examples in the
tutorial are provided for each of those bindings). I give
glade
and
libglade
prominent coverage.

Finally, Rich suggests some extra things at the end. I cover
pkg-config and provide links for autoconfig, automake, and libtool,
but I don’t cover any of the other topics.

My tutorial also contains some things Rich doesn’t suggest. Namely a

debugging chapter
that covers gdb, strace, and valgrind, and also
the chapter I have on building Gnome from CVS that I mentioned
earlier.

So, those who have read this: Which of Rich’s topics would fit well
with my tutorial? Which topics have neither of us thought of that
need to be covered?

Rich: Perhaps we could collaborate? I don’t consider my guide
complete, and you clearly had a number of ideas that didn’t even occur
to me. Even if we have goals that are different enough to warrant
separate projects, it may make sense to share some work in the areas
we have in common.

Enlightenment

I feared this information had been lost last week, but I just found
the file where I placed it. That’s very fortunate, because this
information came from one of those truly illuminating moments. Last
week, while I was in the #gnome-hackers IRC channel, I saw one of
those conversations that leaves you pondering the sagacity of the
builders of Gnome. Meditate upon this and you will learn wisdom.

    <ed__> you should put linux on your ibook rml
 <tberman> thats like buying a 400 dollar paperweight and using it as
           a rock
 <Tybstar> Rupert: quote <tberman> thats like buying a 400 dollar
           paperweight and using it as a rock
  <Rupert> done
 <campout> "and using it as a rock" ?
 <campout> what is that supposed to mean?
     <rml> campout: haha
 <tberman> campout: buying a powerbook and using linux on it
<mtgordon> I have a piece of wood I like to use as a rock.
<mtgordon> It's not as heavy as a real rock would be.
 <campout> but "using it as a rock" ?
 <campout> that makes no sense
 <tberman> sure it does
 <tberman> how do you use rocks?
    <ed__> TO BUILD WITCHES
 <tberman> EXACTLY
<mtgordon> And if an ibook... weighs the same... as a duck...
    <ed__> BURN TBERMAN
    <ed__> BURN TBERMAN

…I love the fact that developing on Gnome is kept fun. 🙂

Ooops

Seeing luis blog
about the
patch-status
and patch-report
cgis that he wrote, I realize that I forgot to mention to anyone that
I added a “Maintainers” section on the front of bugzilla a few days ago. Two of
the links that I put in this section were these cgi scripts which aid
finding unreviewed patches. The other is a link to some basic
procedure info about things like updating versions or components in
bugzilla.