Last week, I kicked off the first blog post in my ongoing adventures to learn how to write GNOME documentation, posted as a long rant about my frustrations in the tools and information available. This week in part two, I’ll cover the start of porting the Userguide to Docbook, the tools I’m using, how I’m learning, and my unanswered questions.

After downloading the source for gedit, banshee and seahorse, I started browsing through the XML files to learn the structure and tags. I was using Gedit, but then on Tuesday Og posted about Geany and I decided to give that a try. (And of course it’s in the Foresight repos!) I mentioned it in IRC Thursday night as my new favorite tool for writing Docbook, and Ken recommended I use Mercurial for revision control.

Ken set up a Mercurial repo for the userguide with the other Foresight repos, and answered my questions on using Mercurial as I quickly scanned the Mercurial documentation. Over the next couple of days I tweaked my Mercurial setup, fixing the author link with a tip from Ken, and getting Nano to be my default text editor as set in my .bashrc file.

One of the weird things I learned with Docbook, is that the section tags, and as you can see in the Gedit screenshot, having nothing to with creating sections in the documentation, rather they are the sublevels within a given chapter. I still don’t understand a number of the tags used by default, such as guilabel, which appears to be a bold tag. I fired off an email to the GNOME-docs mailing list this morning, and Leonardo Fontenelle posted links to the Subversion repositories with the handbook and styleguide, which I’m slowly going through today.

For the Userguide itself, we are creating a folder for each chapter, rather than creating one big XML file for Yelp in Mercurial. I’m hopeful a script can be written to tie the XML files together, but I haven’t even started looking at how you take these files and get them to display in Yelp. I’ve only finished chapter one, and chapter 2 is just over halfway done. There’s a lot of copy / paste going on, as I build the docbook structure for the chapter, then copy from the wiki to a text file, and copy chunks from that to the XML file. It’s slow going as I have to review the tags, and I’m just re-using the structure and tags I see used in other GNOME help files. But I learn best by doing, and repetition. At this point I have no idea if it’s working or not, or how many errors each file may have, which I won’t know until they’re displayed in Yelp. My goal is after I finish chapter 3 to ask for help in tackling that piece, in getting the files to display in Yelp, I’m assuming in a FL-1.

I’ve also mentioned this in IRC, but it’s really interesting for me on a personal level to be putting in to practice all the development practices I’ve read about over the years. From creating the source XML file to pushing the files in to a revision control system, it’s an interesting feeling building something from scratch. And this is just the beginning – once I have a few chapters I’ll need to learn how to package them for inclusion in Foresight, and then update the userguide with each release.

The only downside? With the Mercurial repository being public, you’ll be able to see if I’m working on the userguide or slacking off! No pressure there at all….