Skip to content

Blog

  • in Links
  • 1 min read

Writing Foresight Docs: Part 5

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

foresight-userguide1

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:

foresight-userguide-helpbug

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.

Virtualization Bandwagon Jumping

I decided to jump on the bandwagon and tried out my first appliances today, using the free VMWare player, and a couple of appliances from rpath.org.

Working on Foresight, a number of the images published are for various virtualization technolgies, such as VMWare, Parallels and Xen. Following the VMWare installation instructions in the Wiki, I installed VMWare on Foresight 1.3, downloaded 2 appliances, and was up and running in about 5 minutes.

I am starting to see why these are all the rage right now (at the last TCLUG meeting, a lot of folks put Virtualization on the list for a future speaker to come talk about). From using an image for testing, to installing multiple appliances on a server for specific applications, there are some pretty cool use cases that become possible.

And yes, I know I’m late to the party on this topic, but better late than never. 🙂

Here’s a screenshot of Openfiler, a NAS appliance running in a VMWare player:

vmware-openfiler

And here is a screenshot of Openfiler running, and a WordPress-Multiuser appliance just starting to boot up:

wpmu-openfiler

Click through to see larger versions on Flickr.

  • in Links
  • 1 min read

Writing Foresight Docs: Part 4

Progress on the Userguide has been swift this week. Ken’s comments about having Foresight Linux 2.0 in testing in a “couple of weeks” spurred me to action. In no particular order are the things I’ve learned and accomplished this week:

  • URLs. Again, it’s just a matter of re-wiring my brain from HTML to Docbook’s format. For example: [ulink url="http://www.openoffice.org/product/math.html" type="http">Math here[/ulink] (replace brackets with < or >) links to the Math page on OpenOffice.org. Similar, but different. And god knows I’m no HTML expert to start with.
  • Bullets have been driving me crazy. It was just one little thing, adding the mark=”bullet” to the tag, i.e. [itemizedlist mark="bullet"]
  • 3 of the 5 last pages created were created with zero syntax errors. Yes, pride cometh before the fall. All it means is I’m starting to get the hang of this. And I haven’t started doing any of the advanced formatting yet.
  • All pages have been committed. There’s some editing to be done (more on this below), but the directory structure is complete, all screenshots are uploaded,and the copy is complete in all XML files.
  • I’ve learned more Mercurial commands, such as hg pull and hg update, as I’ve worked on this on my laptop and desktop now. And I experienced a moment of panic after editing a file and not having done a pull. But I figured it out, thankfully.
  • I added a TODO file in the repository, but it probably needs to be updated more often.

Things left to do:

  • The first few pages need major formatting updates, especially on removing the indentation.
  • All pages need to be reviewed and edited for the correct URL tags.
  • Bullet points need to be fixed in almost all the pages.
  • Screenshots need to be resized to 510 pixels wide (so they print correctly, per the GNOME Documentation Handbook guidelines).
  • I still need to research, learn and build a Table of Contents.
  • I need to add some advanced formatting, specifically the arrow labels when showing how to access menus to run applications. (The tag I believe).
  • I still need to research on how to add this to the default Yelp page in GNOME, and how that will work from a packaging perspective.

Paul Scott-Wilson asked a great question in IRC last night, regarding whether Docbook repository or the Wiki will be the master copy of the userguide moving forward. My recommendation would be that Docbook would be the master copy, put together from the text on the wiki. This way it gives users a chance to contribute to the userguide on the wiki, adding new copy, having it proofed, and then moved to Docbook. The Printing section is a great example of this, it’s 80% complete on the wiki, but it needs to be 100% to be included in Docbook. (Jonathan Brickman, where are you? Please finish the Printing page!) Additionally, the Docbook repository has source control, which would make it easier to manage over the long term. Opinions or thoughts? Leave a comment below on the blog, or email me at pcutler at foresightlinux dot org.

Progress will be small to non-existent as I have to travel for my day job. This probably means no blog updates either. More to come soon.