I ran into a couple of roadblocks in trying to use entities with Mallard recently, and thought I would share how I worked around them in case anyone else needed to do the same thing. Although my examples deal with Mallard, what I note here will also work for entities in DocBook 5 documents, or any other RelaxNG-based XML documents.

Entities?

Before I start, though, if anyone is wondering what I’m talking about when I say, “entities,” they are a handy variable-like feature of XML and a couple of other markup languages. For example, they allow you to type something like &exaile; into your document, and then have it magically parsed as:

<guiseq><gui>Applications</gui><gui>Multimedia</gui><gui>Exaile</gui><guiseq>

Using Entities in Mallard / RelaxNG documents

To set up and use entities in your XML-based document, you basically need three things. You need a file that contains the entities you want to use*, you need to declare where those entities are tracked, and you need to actually use the entities in your document.

The Entities File

Previously, step one was very easy. You would just create a file that contained values like this:

<?xml version="1.0" encoding="UTF-8"?>
<!-- MENUS -->
<!ENTITY abiword '<guiseq><gui>Applications</gui><gui>Office</gui>
<gui>AbiWord</gui></guiseq>'>
<!ENTITY about-me '<guiseq><gui>Applications</gui><gui>System</gui>
<gui>Users and Groups</gui></guiseq>'>

<?xml version="1.0" encoding="UTF-8"?>
<!-- MENUS -->
<!ENTITY abiword '<guiseq xmlns="http://projectmallard.org/1.0/"><gui>Applications</gui>
<gui>Office</gui><gui>AbiWord</gui></guiseq>'>
<!ENTITY about-me '<guiseq xmlns="http://projectmallard.org/1.0/"><gui>Applications</gui>
<gui>System</gui><gui>Users and Groups</gui></guiseq>'>

Out of the Woods

Once you make it past step one, the rest is a walk in the park.

Step two is to declare your entities in the start of your documentation files. I modified a DocBook 5 example to come up with this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE page [
<!ENTITY % entities-xubuntu SYSTEM "libs/xubuntu.ent">
%entities-xubuntu;
]>
<page xmlns="http://projectmallard.org/1.0/"
      type="topic" style="task"
      id="music">

Wrapping Things Up

Step three, using your entities in your documents, is no different than what you would have done with DocBook 4 or any other XML-based syntax. For example, typing &abiword; will be parsed as:

<guiseq><gui>Applications</gui><gui>Office</gui><gui>AbiWord</gui></guiseq>

and will cause “Application > Office > Abiword,” to magically appear in your rendered documentation.

If you have any questions, corrections, or suggestions (as I’m sure you’re all keen to be chatting about XML entities), feel free to leave me a note in the comments.

* I’m using external entities, which requires a separate file, but you can also use named or charater entities.
** Apparently the namespace of the parent node is no longer inherited by the entities, so you need to declare the namespace in the entity itself.

Dear Yahoo!

Welcome to Ubuntu! As a regular contributor to the Ubuntu project, I think it’s great that you are partnering with Canonical.  Because of the agreement you signed, Canonical will be able to hire more people to work on Free software.  Also, your contributions will help Ubuntu continue offering their OS at no cost to users.  These are great things.

As things get going, though, there is one big thing (or a set of big things centered around one request) that you need to do to make the Ubuntu-Yahoo! user experience better.  In short, you need to index the crap out of Ubuntu- and Linux-related sites.  For example, if I do a Yahoo! search for launchpad bug 387765, I need the first link that comes up to be a link to the actual bug page for Launchpad bug #387765.  As it stands now, a Yahoo! search for that phrase brings up two results, neither of which are relevant.  The first of the two results is a link to the Debian Bugs page on Launchpad.  As a contributor, this is not what I need.

For comparison, the same search on Google brings up 273 results, with the first result being a direct link to the bug report on Launchpad (which is now closed, thanks to the efforts of Fabien Tassin and the other Chromium packagers and hackers)).  Google’s results not only link me directly to the bug that I am inquiring about, but also link me to a large number of pages that may be relevant to that bug report.

The example that I provide above concerns search results that are beneficial for contributors and developers, but what about regular users?  When I search Yahoo! for “Dual boot Windows 7 and Ubuntu,” the first page in the search results is for the Ubuntu 8.04 “Dual Booting,” official documentation page.  This page is out of date, especially given our migration to Grub2 in the 9.10 release.

These are just two examples, and my searches are likely not representative of the multitudes of search requests made daily on your site for Ubuntu-related tasks.  Moreover, I won’t pretend to understand how incredibly complex indexing the web can be.  I’m just writing to note that there is room for improvement, and I would like to see improvement so that our users can use your service to get relevant search results.

After all, improving Linux-related searches would be a win-win for us and for you.  Ubuntu developers and users would get their work done, and problems solved, more quickly and effectively, and you would get more regular users performing their searches on Yahoo!  This sounds pretty good to me.  Here’s to hoping it can happen.

Per Daniel Holbach’s recent blog post about the Global Bug Jam, I thought I’d add my two cents (or give you a penny for my thoughts, and donate the additional penny to charity) about what the Ubuntu-Chicago Local Community Team is planning for the Global Bug Jam.

There are still quite a few details for us to iron out, but we have the basics in place, and are gearing up for the event.  What have we done so far?  First, we’ve been able to secure a great location, the headquarters of Centro – an online media services company in downtown Chicago – for the event.  Centro uses a lot of FLOSS tools in their development, and they’ve been a consistent supporter of FLOSS events in the Chicagoland area for a number of years, so we’re really grateful to them for allowing us to use their space.  (As a side note, one of their developers who helped to secure the location for the event is also the creator of “Open Sprints,” an GPL’ed indoor bike-racing application that has garnered a lot of enthusiasm amongst the bike messenger crowd in the U.S.)

Ok, so we have a location.  We also have people who are going to attend.  Those people have (for the most part) been prepped on what we’ll be doing.  We held an introductory session as part of a Chicago GNU/Linux User Group meeting a few weeks ago, where we were able to set people up with Launchpad accounts, PGP keys, SSH keys, and the 5-a-day application.  For those who weren’t able to attend the meeting, I’m sure we’ll be able to set them up online in advance of the event, or when they arrive for the bug jam.

Also, I mentioned it briefly above (“We also have people who are going to attend…”), but we are expanding the ranks of our loco team for this event.  Ubuntu-Chicago had been relatively quiet for a while, but we’re doing what we can to involve people outside of regular X/K/Ubuntu users and developers in the bug jam.  One of the better things to see in this process is how members of the Chicago GNU/Linux User Group are joining in, and how we’re also getting involvement of people who develop for FLOSS projects, but who aren’t typically involved in local Ubuntu events.  (They don’t even have to use Ubuntu . . .).  For example, I have heard of one Miro developer plans to attend portions of the bug jam, we hope to get some folks from Banshee and GNOME . . . and I’ve even heard that the entire Tilda development team (ok . . . so it’s just one person) may be involved, too.

Personally, I’m going to do my best to advocate testing and bug triage of Xfce 4.6 during the event.  I’m also excited that there will be a Lou Malnati’s Pizzeria DIRECTLY ACROSS FROM OUR BUG JAM LOCATION.  OH HAI, UBUNTU-CHICAGO CAN HAS TEH BEST PIZZA.

So, yeah, if you’re a X/K/Ubuntu user or FLOSS-coder who lives in / around Chicago . . . even if you’re not an expert . . . Check out our wiki page (with the new NavBanner that I ganked from the Massachusetts team), join our mailing list, and make plans to see us the weekend of February 20th. 

I volunteered at Free Geek Chicago again on Sunday, and spent much of my day trying to get Xubuntu Feisty Fawn to install on some rather unique hardware. It didn’t go so well.

The machine in question was a PII with 256mb of RAM, and two SCSI hard drives – one 8gb and one 4gb in size. I tried to set up an LVM installation, but the installer hung after it had completed 85% of the software installation. So I also tried manual partitioning, setting up the root partition on the 4gb drive, and boot, home, and swap partitions on the 8gb drive. It hung at 85%, too. Even trying to do a command-line installation hung at 85%.

With frustration mounting, we just switched over to a new computer. I knew there had to be a way to view what was causing the install to hang, so I asked the folks in #ubuntu-iso what I could do to see these error messages. I talked the issue over with Stephane Graber, and he suggested that I check out some of the install messages in /var/log by pressing ctrl-alt-f2 and getting to run level 2 once the installation had hung.

I’m going to do that the next time I’m at Free Geek Chicago. If anything, I’d like to at least get a good bug report out of this. I haven’t done too much testing of SCSI drives, and also haven’t done to much LVM testing, so I think I might try and add that to my testing repertoire on this release cycle. I’m even going to trade in my standard PII testing box (which runs just fine, thank you) for this SCSI beast (assuming it has no hardware issues).

Ubuntu Illinois / Chicago member Freddy Martinez had given me some brief pointers on filing bugs during one of our more recent Ubuntu-Chicago loco meetings, but my involvement with the ISO testing has really started to give me a taste for what bug reporting and triaging involves. Now that Xubuntu ISO testing is at a decent state, and we have enough testers to keep things moving, it seems like bug-related work will make for a natural progression from what I’m currently doing.

The “Helping With Bugs” wiki page looks like a good-enough place to get started.

I’m starting to better understand the role of ISO testing, and how it differs from bug reporting. ISO testing looks at successes and failures from a big picture – is this release stable enough to get out the door? ISO testing seeks out the show-stopper bugs that would prevent a milestone build from being released. Bug reporting works in a similar way, but on a smaller scale – does this package work as intended?

That’s how I kind of see it, anyway. They are different, but they compliment each other.

Oh, and apparently QA is a whole other ballgame, but I don’t know much about how it differs yet.