Skip to content

Linux

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.

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

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.

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.

Lovin' Feedburner

About 6 months ago, I burned my blog’s RSS feed to Feedburner. I was using WP-Shortstat as a WordPress plugin, and the RSS feed subscribers didn’t look realistic (and they weren’t!) as it was over reporting on the number of subscribers. I’ve been happy with Feedburner since, and it provided a very simple view to my feed’s statistics, and there was a plugin to view the statistics right in my WordPress dashboard.

When I was syndicated on Planet Foresight, I created a Linux feed on Feedburner so those users weren’t subject to my entertainment and copyright rants, and later I burned a feed of the Foresight Linux Newsletter as well.

Since then, I continue to learn more about Feedburner and its features, in no particular order:

  • Feedburner takes over Steve Smith’s WordPress plugin for Feedburner stats, renames it Feedsmith.
  • Rick @ Feedburner recaps why partial feeds are a bad thing. I couldn’t agree more – I’m too lazy to follow links out of my feedreader just because a site wants hits. I’ll usually end up unsubscribing after a while unless the site has really, really good content, like TV Squad.
  • It might be fun to create a Headline Animator – if I could do a non-cheesy looking one, might be a good way to market the Foresight newsletter
  • I can’t believe I didn’t know about FeedFlares until today – what a great concept. Add little tags to the end of your posts, such as “add to del.icio.us”, “email author” etc. See the whole list here. I’ve already updated my feed. And the have an open FeedFlare API to create your own.

I also use Feedburner as tool combined with the Foresight Wiki based on Confluence. Confluence gives you the ability to build a feed right from the dashboard, but it’s really only useful for tracking a whole space, and not independent pages.

The first feed I built was the Foresight Linux Newsletter. Using Confluence, I created a RSS 2 feed based on any news post in the Newsletter space. Confluence gave me me a feed that looks like this:

<br /> http://issues.foresightlinux.org/confluence/createrssfeed.action?types=blogpost&statuses=created<br /> &spaces=newsletter&labelString=&rssType=rss2&maxResults=10&timeSpan=180<br /> &publicFeed=true&title=Foresight+Linux+Newsletter+RSS+Feed

Not necessarily human readable, or easy for a subscribe to type in to their feedreader, though possible using cut and paste.

I took that feed, and burned it in Feedburner, and got this:

http://feeds.feedburner.com/foresightnewsletter

Much better, and now I have statistics tracking for our subscribers (Which we need more of!)

The second feed I created in Confluence, was for the Package Request page on the Wiki. On this page, users can request software packages to be added to the Foresight repository, so they can install them via Conary, instead of building and compiling the software by hand.

Confluence doesn’t give you an option, at least that I could find, to build a feed for a specific page. First, I gave the the wiki page a specific label, “package-requests”. I then went to the Feed Builder, and chose to build a feed in the Developer space, with a label “package-requests” and to show all new edits and comments on the page. Confluence gave me the feed:

http://issues.foresightlinux.org/confluence/createrssfeed.action?types=page&types=comment<br /> &statuses=created&statuses=modified&spaces=kitchen&labelString=package-requests<br /> &rssType=rss2&maxResults=10&timeSpan=5&publicFeed=true&title=Foresight+Linux+Package+Requests+RSS+Feed<br />

I burned that in Feedburner and came up with:

http://feeds.feedburner.com/fl-packagerequests

So if you want to add that to your feedreader, you will see all requests and comments for new packages, as well as edits to the page when someone marks a package as added to the repository.

I’m really starting to dig the power of Feedburner.

Mark Shuttleworth: In defense of independent governance

Mark Shuttleworth, founder of Canonical and Ubuntu Linux, has a stirring blog post up titled In defense of independent governance.

I cannot due a summary justice, but Mr. Shuttleworth’s extremely well written words on culture, democracy and free speech have moved me, and I encourage you to read it.

I’ll leave you with this from Mark Shuttleworth:

At times like these, we are our own worst enemy. We hear what we want to hear. It is painful to hear that one might be wrong, that oneÂ’s hero might have flaws, that oneÂ’s leaders might not be all that we wished them to be. The awful truth of the media is that it pays to tell people what they want to hear, much more than it pays to tell people what they need to hear, and so society can whip itself into a frenzy of mistaken greed or fear or anger, and make poor decisions.

It takes great courage to speak out, when these basic principles are at risk. In a free society, there is nevertheless pressure to conform, to stay with the herd. In a society that is not free, one speaks out at some considerable personal cost to life and liberty. I salute those who do.

Elisa

With the recent announcement of Ubuntu forming a Media Center team focusing on Elisa as it’s media center platform, I took another look at Elisa as a potential solution for my home theater PC. (Sidenote: I’m way too lazy and need a gook kick in the butt. I’ve had my HTPC built and ready to go for a year, and have barely tried to fix the last few issues I have with it. Shame on me. Though since I got my dual-tuner HD-DVR from DirecTV, when combined with my Sonos and Xbox 360, I haven’t really needed all the features of a HTPC that I originally planned on).

Elisa was already available in the Foresight repository, but it was version 0.0.1. Asking nicely in IRC, Ken Vandine updated the version to Elisa’s current release, 0.1.6. Ken was unable to run it because of an ATI or Xorg issue in 1-devel with 3D effects, but it started right up for me.

I’ll do a more formal review later, I’ve only played with it for maybe 30-60 minutes tops over the last day and a half, but for a very, very early release, Elisa looks promising. After some user error on where you edit different file locations in the ~/elisa/elisa.conf file, I was able to browse my music and photos.

To be clear, it’s a program to manage your media – it does not have DVR functionality built-in. And for me, that may just be perfect. It will manage your movies & videos, play DVDs, photos, and music. It has built-in support already for Streamzap remotes. (I don’t know what that is yet, but I’m going to find out).

One obvious bug, is when I start Elisa from a terminal or Alt-F2, there is no window border. Changing Elisa to fullscreen with the “F” key and back to a windowed version, brings up a window. This tip is useful, because if you don’t, and you lose focus of Elisa, none of the shortcut keys work if the window border isn’t there.

I’m going to play with it more this weekend, and will post more thoughts on Elisa early next week. For now, here are some screenshots of Elisa in action, with bigger versions available on my Flickr account.

elisa

elisa2

elisa-photos

Bluetooth (Headset / ALSA) update

A follow-up to last night’s post about Bluetooth adapters on Linux to use a headset with my desktop:

_

Breaking News: Foresight Developers can read minds!_

Serendipity struck, that within an hour of posting, Ken Vandine pinged me in IRC on #foresight to let me know that earlier in the day, he had already updated the Bluetooth ALSA packages on Foresight to make this project work.

So not only will Foresight developers package up software if you ask nicely in IRC, I have now learned that Foresight Developers have the ability to read minds, and package software they know their users will want later in the day.

Can your distribution’s developers read minds? Get Foresight today!

(Now I’m off to pickup a bluetooth adapter later today!)

Dear Lazyweb: Bluetooth Adapters on Linux

Dear Lazyweb: I’m looking for a USB Bluetooth adapter that is Linux friendly.

I have two headsets with boom mics I’ve used on my desktop – one is a cheap off-brand, and one is a very nice Plantronics. I have been working on a podcast off and on for the last couple of months using Jokosher, more as a test to learn Jokosher so I can add audio to screencasts and help show users how to use Foresight.

Unfortunately, the sound quality on the boom mics is lacking – the cheap off brand sounds tinny, and the Plantronics makes it sound like the mic is 10 feet away from my voice, and doesn’t really move on the headset so I can position it better.

However, I just received a Jawbone bluetooth headset for my cellphone. The Jawbone’s claim to fame is that they made it for DARPA, and it blocks all ambient noise so you only hear the user’s voice. My hope is that it might work well for voice recording on Linux. But I’m not sure how compatible the different USB Bluetooth adapters are for pairing a device like a headset, and I don’t even know if Jokosher or other applications will see the headset as a microphone for voice recording.

If anyone has any thoughts, please leave a comment here, or drop me a line at pcutler _at_ foresightlinux dot org.

Thanks!