Skip to content

Blog

Writing Foresight Docs: Part 3

My original intent in this continuing series on Writing Documentation for Foresight was to post weekly, but I just had to share the latest news.

With Paul Scott-Wilson’s help in IRC last night, the Userguide’s first two chapters are now working in Yelp. Pscott shared a diff file fixing some syntax issues, and pointed out I could just run yelp installation.xml to display the Docbook file in Yelp, or if it crashed, the terminal spit back all the errors and the lines to go fix them on. (I really do need to use the command line more.)

After spending a couple hours on all the errors that the terminal was yelling at me about, we now have Yelp displaying the Userguide (with images!):

userguide-yelp1

There are still a number of typo’s I’m finding, especially as it relates to bullets and indentation, but the menu’s and links are working, the content is displayed, and best of all, no errors when starting from the command line. Check it out yourself from the Mercurial repository, it’s up to date.

Next up: Learn how to tie the docbook files together (Pscott pointed me at this link: http://www.sagehill.net/docbookxsl/ModularDoc.html) and package them up in Foresight. These first two chapters took me longer than expected to port to Docbook and re-write, so it’s probably a good idea to see if this even works.

Nadrinplace.com

My son Alex has a blog.

And like his father, his alias (Nadrin) was randomly generated by a game.

My wife registered the domain and added it to my hosting account, and I installed WordPress for him this weekend, and he picked out the theme.

Good to know geekery runs in the family!

Here he is at his desk, his monitor is just out of sight on the left.

DSC01677

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.