Skip to content

2007

Writing Docs: Part 2

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.

geany-gedit

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….

Philip K. Dick

I mentioned a few weeks ago a link from Total Dick-Head, a blog dedicated to all things Philip K. Dick. Today’s post covers the new Library of America release of four of Dick’s most original novels that is released today in one hardcover edition. The novels are:

  • The Man in the High Castle
  • The Three Stigmata of Palmer Eldritch
  • Do Androids Dream of Electric Sheep?
  • Ubik

The Library of America’s mission is to _“preserve the nation’s cultural heritage by publishing America’s best and most significant writing in authoritative editions is as strong as ever.”

_

Their goal is to publish books to last the test time:

  • The paper is acid-free and meets the requirements for permanence set by the American National Standards Institute; it will not turn yellow or brittle. The books are bound with the grain of the paper to ensure that they open easily and lie flat without crinkling or buckling.
  • The binding boards are flexible yet strong and make the book light, easy to carry, trim in appearance, and a pleasure to hold.
  • The page layout has been designed for clarity as well as elegance. The typeface, Galliard, is exceptionally readable and easy on the eyes.
  • The binding cloth is durable woven rayon, dyed in the thread for richness of color. Handsome endsheets match the binding cloth and add to the visual unity of the series. The books are Smyth-sewn for permanence and flexibility, and each includes a ribbon marker.

Apparently the street date for the book is today. I actually picked this up almost 3 weeks ago in Milwaukee at a local book store. The book is gorgeous – it came shrink wrapped, and the paper quality and presentation is top notch. I own a lot of Dick’s short fiction, and look forward to reading some of his early novels.

Release Day! Foresight 1.3

It’s release day for Foresight Linux 1.3. Nothing gets your adrenaline flowing like release day as you try and get all your tasks done to help out. Not only did we release the latest and greatest version of Foresight Linux, including GNOME 2.18.2 also released today, Issue #3 of the Newsletter is out. Here are some links to keep you busy:

  • Foresight Linux 1.3 release notes
  • Go download Foresight! We have installable CD & DVD images, and lots of Live Media, including VMware images, Parallels / QEMU images, and a LiveCD will be out in the next day or two. Why aren’t you using Foresight Linux yet?
  • Issue #3 of the Newsletter. Including a first look at the next generation version of Foresight Linux, 2.0.
  • The Release Day HOWTO. All the different tasks that go into release day. (Feel free to add whatever we’ve missed!)

Use it, love it, and help us make Foresight even better. Stop by #foresight on FreeNode in IRC – we won’t bite, I promise.

Site5 Issues

I’ve been hosted on Site5 for just shy of two years, and up until last week, the service has been great. Unfortunately, I’ve had 4 outages in the last week alone, and folks over at Webhostingtalkforums are saying similar things about Site5. I’ve only done a cursory glance at other webhosts, as I would have no idea where I would go. I see a lot of technical folks and blogs hosted at Mediatemple, but their reviews aren’t much better. After the two outages in the last 24 hours, I left a heated post in the Site5 forums this morning:

I’m very disappointed with the recent downtime on Peony. I have a Multisite plan currently, and on Tues, May 22nd, Peony first appeared to go down. I let it go and it seemed to be up within an hour of me noticing it was down. The sites were unresponsive, and then they were back up, with the exception of MySQL, so a couple of my sites were displaying database couldn’t connect errors, such as my blog or forums on different domains.

The next day, May 23rd, it happened again, and I opened a trouble ticket. I was told due to several users monopolizing server resources my sites were down, and this was being addressed.

Yesterday, Sunday the 27th, my sites were down again, and I opened another trouble ticket. I was told that due to bots spamming SSH logins the server was down again and it was fixed. I wake up this morning, and my sites are still down, even though the trouble ticket said it was fixed.

I’ve been a happy Site5 customer just shy of 2 years – these are the kinds of things that have driven me to new webhosts over the years.

What disturbs and disappoints me the most is the lack of communication from the Site5 staff. If a server goes down 4 times in a week, I expect a level of personal communication showing the staff is on top of it and fixing it. In addition, in the Current Services Disruptions forum, not once is Peony listed as having a disruption. I would expect that bots flooding SSH logins would be listed as a disruption, as that is approaching a DDoS style attack.

At the minimum, it made me feel better, and a few hours later a Sysadmin posted to mention they’ve added 2GB of RAM to the server and some kernel modifications and “are going to be monitoring the server very closely now to ensure it remains stable.”

Let’s hope so. And sorry about the downtime.

Elisa Updates

Moosy, an OpenSUSE blog, has a short post up today on Elisa, mentioning that the 0.3 release will be a complete rewrite, and now includes Tango icons.

I look forward to the upcoming release. As I’ve mentioned before, Foresight has the latest Elisa release already in it’s repos, so hopefully we can get an updated version when it’s released. I was this close (holds fingers apart) to trying to reinstall MythTV this morning on my HTPC, but I couldn’t find a surge protector as I’m out of outlets at my home theater. (That should tell me something, shouldn’t it?)

Moosy links to the following Youtube showing off the new icons:

GNOME Documentation – Irony 101

Now that I have a few newsletters under my belt for Foresight Linux and completed the Getting Started user guide on the wiki, my next two big projects for Foresight are porting the Getting Started guide from the wiki to Docbook for inclusion in Yelp on a default Foresight installation, and getting some screencasts recorded and posted to the Foresight wiki.

With newsletter #3 out the door, and an hour or two on my hands, I decided to jump in and start learning some basics of Yelp, Docbook and contributing to GNOME documentation. I started off keeping track of some interesting links I was coming across in Tomboy, and as my frustrations grew, it became a live journal of my research in to contributing to GNOME documentation. What follows is the unedited thoughts that ran through my brain for just over an hour as I looked for content on where to start on this journey.

The good thing I’ve learned in this process is what needs to be updated to make it easier for folks who want to help out GNOME and it’s documentation. Docs are one of the easiest areas for a new volunteer to get involved with, and now that I’ve complained publicly about my experiences, I’ve added it to my to-do list to try and make this better. (But it’s down on my to-do list after Foresight documentation in Yelp and screencasts. And maybe the new Foresight website, we’ll see).

Without further adieu, here are my notes:

**

GNOME Documentation**

Documenting my learnings on contributing to YELP

15:45 – Start looking on the GNOME wiki and Google

http://live.gnome.org/DocumentationProject

(last update in October 2006)

http://live.gnome.org/ProjectMallard (next generation GNOME docs tool in development)

15:55 join IRC (#docs on GIMPnet)

Continue to use the Wiki and Google:

http://live.gnome.org/DeveloperGuides (could be a gold mine, lots of links)

http://live.gnome.org/IdealDeveloperDocumentation (A wishlist of perfect documentation, last updated last August)

http://developer.gnome.org/projects/gdp/handbook/gdp-handbook/index.html (last update 2003, this had to be the bible for doc developers once upon a time)

http://www.ibiblio.org/oswg/oswg-nightly/oswg/en_US.ISO_8859-1/articles/DocBook-Intro/docbook-intro/ (Linked from the GDP handbook above, it’s from 1999!)

16:05: Edit the GNOME wiki with a broken link to the non-existent style guide:

http://live.gnome.org/DeveloperGuides

16:10 Ask for help in IRC (no response, but I’m patient)

16:15 Find new links that look helpful:

http://live.gnome.org/DocumentationProject/Contributing

http://live.gnome.org/DocumentationProject/Contributing/SubmittingPatches

16:18 Complain in #foresight about the irony in that getting started with the GNOME documentation team isn’t really documented

16:24 Realize the link above on SubmittingPatches is also horribly outdated as GNOME has moved to subversion

Make mental note that I should be probably updating the GNOME documentation personally with these learnings. Add to to-do list in Tomboy

16:29 Thilo agrees with me in IRC, and reinforces an opinion I have too:

thilopfennig: pcutler_: yeah

thilopfennig: thats true

even simple links are broken

and nobody cares really

That last sentence bothers me, as I had the same thought. Perception is reality.

16:31 Pull up the GNOME SVN wiki page and prepare to checkout some help files to browse through as a base:

http://live.gnome.org/SubversionFAQ

16:36 first 2 projects svn co doesn’t work, try with epiphany, but it pulls the whole source, and not the help files. keep reading through LGO. Quite frustrated.

16:43 Pull down Gedit files. Realize that I was pulling the help files correctly with SVN, but still can’t find english versions. Mistakenly ask for help in IRC, when I did do it right.

16:46 Remind self it’s a holiday weekend in US on a Sunday afternoon, of course no one is going to respond.

16:48 Open Gedit, and start browsing through source files. In the Help directory, the “C” subdirectory has “gedit.xml” – I found the file! Why is it in the C directory if it’s American English? Who thinks of these things? All the other files I pulled down were correct as well.

16:55 Finish scrolling through gedit.xml after opening the files in Yelp for comparison. Docbook looks fairly sane, if just overly, well, there’s a lot to it, but it’s fairly logical. Overwhelmed by the sheer amount of work porting the userguide from the wiki to Docbook will be, but it’s doable.

16:56 Walk away. Remind self to blog this.