No, your eyes aren’t fooling you, the Getting Started with Foresight Linux User Guide is complete, and ported to Docbook. (Click through to see a larger picture at flickr.com):

I was traveling for most of the week for my day job, but I did a little writing after last weeks post, then a flurry of activity Friday and Saturday. Last week, I was mostly content complete, with tons of formatting left to complete in almost every document, including:

• Linking all URLs
• Fixing all bullet points
• Adding arrows to directions for clicking in the menu
• Fixing the indentation errors
• Resizing all screenshots to 510 pixels wide

The above items were almost all completed Friday, but I still hadn’t started the biggest challenge, which was writing a Table of Contents. Looking through the source code of various other Yelp / Docbook files, I had seen a number of pages calling other Docbook pages, such as the GNOME Documentation Project Handbook, for inclusion using this tag:

[include href="filename.xml" xmlns="http://www.w3.org/2001/XInclude"/]

In the end, I ended up using the ENTITY tag, as found in the GNOME Documentation Style Guide, which consists of listing all the files in alphabetical order at the top, and then calling each one in the order you want within the [book] tag:

[!ENTITY APPLICATIONS SYSTEM "applications.xml"]

&APPLICATIONS;

I borrowed heavily from the GNOME Documentation Style Guide’s structure and code, in writing the default page (foresight-user-guide.xml) and create a Preface chapter. This chapter is new as of yesterday, and includes an “About” section, “What’s in this Guide” with links to each Chapter and it’s summary, and a “Who Should Read this Guide” which breaks out by chapter for new or experienced Linux users the chapters they might find the most relevant.

This required me to rewrite the first 75 lines of each of the 9 Docbook files that currently make up the userguide, and change them from using sect1 tags, to using chapter tags. This actually makes it much more simpler for future contributors to add to the book, as they write their chapter and don’t have to worry about filling out all the revision history in each file, it’s updated in the foresight-user-guide.xml file instead of each individual one. I got in the zone and knocked all the files out last night, and submitted them to the Mercurial repo.

There is one bug I have yet to solve:

In two different sections of the Userguide, the “Help” section is called, both in the Preface chapter, and it references the IRC help sub-topic instead. A bug-hunting we will go.

I am sure that I haven’t done everything in the right order or by the book – for example, I’ve found references that GNOME developers use make to write documentation files, I can guess to why, but I’m not sure, nor can I figure out how they’re set up. I’m also not sure on the translation process, other than editing the files by hand but I’ve never created a program either that has had to use a po file.

I’m also darned if I can find where Yelp, when you start the GNOME Help from System > Help, is calling the files on the right side under “Welcome to the GNOME Help Browser”. That’s where I want to put the userguide, but when you open /usr/share/yelp/toc.xml it only appears to be calling the links under “Desktop” on the left.

This has been a great experience so far, and isn’t even close to over. After I track down the bug and find a place for the userguide to live in the default documentation, it’s time to take Foresight documentation to the next level. The content written so far is not set in stone. In some cases, it only skims the top of what should be included in a given chapter, there are huge holes of information not even presented in the current guide, such as a better installation overview or printing, and more screenshots could be sprinkled throughout. Other sub-chapters could be written on specialized topics, such as installing on a Macbook or running OpenBox.

A process still needs to be developed to cull documentation on the wiki to live offline in the userguide. Documentation should be a living, breathing thing that grows with the operating system, not something that grows stale. (Quick sidenote – the fact that GNOME still ships with the GNOME 2.14 Desktop Accessibility Guide and the GNOME 2.14 Desktop System Administration Guide in the default help page ticks me off to no end. Now that I have some limited experience with Docbook, it’s time to give back). Taking user contribution submissions to the wiki and putting them in the userguide should be a high priority. Hopefully, the work done on the userguide so far can serve as a base for future contributors to continue to add content to, and people will find it useful as they use Foresight Linux.