The Gist

Jakub writes:

Let me offer the following paralell. I loved how the Mozilla folks avoided the Frankestein and solved the issue of specific needs with their extension system in Firefox. Firefox only ships with essential functionality, that pretty much everyone will find useful. And if there is a need for a specific functionality for a specific user base, somebody sits down and writes an extension for it. Such extensions are developed separately from the main app.

He goes on to mention the prospect of “extenion” themes like gnome-icon-theme-artists and gnome-icon-theme-hackers. The parallel, however, falls apart in that I can load up all the plugins I want in Firefox. Let’s postulate these extension themes:

• gnome-icon-theme-artists – Differentiate between different image types
• gnome-icon-theme-hackers – Differentiate between different source and object file formats
• gnome-icon-theme-audiophiles – Differentiate between different audio types
• gnome-icon-theme-network – Differentiate between different types of network servers

It’s a well established fact that I am not an artist. I once made a pretty decent scale drawing of a pixel. That’s about the best I can do. But I am a programmer, and an audiophile, and one of those weird people who uses Gnome on a wacky heterogeneous network. So I want to load up three of those.

But it isn’t a plugin system. It’s a set of independent extension themes. So we’ll have to have funky conglomerate extension themes, like gnome-icon-theme-audiophile-hacker-network. With just the four I listed, we get 2^4 = 16 extension themes. Yikes.

So Calum brings up two interesting points about DocBook output for the web: First, without any sidebars or maximum widths set, the line width is too wide for most normal-sighted users. Second, the lack of a navigation sidebar makes it difficult to keep track of where you are and jump quickly to other places in the document.

And Calum is absolutely right. The good news is that these two problems can be solved in one fell swoop. Long ago, I created a customization for Norm’s stylesheets to add a navigation sidebar and make the output fit the Gnome web site. We’ve used it primarily for the release notes. The implementation is kind of slow and fragile, but it does work.

Regular readers of gnome-doc-devel-list will know that Peter Williams has been trying to add these sorts of things, so that we can have kick-ass standalone HTML builds without hassle. He’s also developed a gnome-doc-process script, which makes it easy to process DocBook from the command line. We’ll get all that into CVS in the next release cycle.

The goal with adding such extensions is to do them without doing something stupid, like overriding the body-creating template, like I did in the customizations mentioned above. Fortunately, I have control over my stylesheets, and I can add hooks wherever we need them to make this happen.

Here’s our seven-step program for success:

1. Make all output prettier.
2. Provide the necessary goodness to make HTML suitable for our web site, and hopefully easily tailored to other web sites.
3. Get a simple script to do the transforms.
4. Use this as the base infastructure for library.gnome.org.
5. Get people to write documentation.
6. Put all of our documentation online.
7. Brag on our blogs about how we have the bestest documentation ever.

The bragging part is important. Fortunately, it’s easy, and we’re all really good at it. I mean, we are awesome braggers. Nobody brags as well as we do. We rule.

Why doesn’t Fedora Core 4 ship with FLAC support enabled in XMMS? I get the whole MP3 thing; I’m cool with that. All my ripped CDs are in Ogg Vorbis, because that’s the sort of left-wing tree-hugging pinko Free Software zealot I am. But FLAC, the Free Lossless Audio Codec, it’s pretty free.

FLAC is the only example I can think of where the shiny new free format completely decimated the entrenched non-free format. It clubbed SHN to within inches of its life and left it lying in a ditch. And it’s stood strong against Apple’s best efforts to strangle lossless audio with Digital Restrictions Management using ALE.

FLAC is a winner. Let’s treat it as such.

Planet readers should now skip on to Christian’s excellent post on GPL and DRM. This paragraph isn’t for you. Hi Silke. I love you.

If you watch mailing lists and IRC carefully, and you keep your eye out for the word “DocBook”, you’ll see a trend emerge. People like to complain that the HTML you get from DocBook looks ugly. But it doesn’t have to be that way.

These days, you have basically two options for converting DocBook to HTML: Either you use Norm’s pan-galactice all-singing-all-dancing XSLT, or you use mine. Mine don’t provide as many options, and they still lack support for some of the more complex book-oriented stuff, but they’re mighty fast.

People said DocBook was slow, so I set out to prove them wrong. Now they say it’s ugly. So, hey, a challenge. Understand that any amount of prettification necessarily involves dictating style. Try writing HTML without any CSS or other fancy styling stuff. It looks ugly. So the goal here is to continue to make the generated XHTML generic, but to make the default CSS styling nicer. And there’s my long-standing goal of making Yelp do less customization to gnome-doc-utils than it currently does.

So, mockups:
BeanStalk Manual
Working with Beans
Purchasing Beans (includes an admonition)
Bean Storage and Care (includes a program listing)

These are rough sketches, and there are a few problems still. The XHTML behind them is clean, and easy to create from DocBook source. Everything is in the CSS. More to come later.

I was just in a car accident today on my way to lunch. There were four people in my car (including me), and one in the other car. Nobody is hurt, and the damage to the cars looks relatively small. My car shouldn’t need anything more than some bumper work and an alignment (which it was due for anyway).

Rather than try to explain what happened, I present Exhibit A: a nice diagram by my good friend Ryan, who was in the front passenger seat of my car when the accident occurred.

I don’t think I ever announced this publicly, so I’m doing it now: A few weeks back, I appointed Don Scorgie and Brent Smith as full co-maintainers for Yelp. And here’s what happens when you add more hackers to the mix:

• Chris Lahey’s patch to add Beagle-based search landed on HEAD. If you have Beagle, Yelp will give you love.
• Don put some extra love into Chris’s original printing implementation, then committed it. So Yelp prints now.
• Brent Smith has done a lot of work on the man page stuff. So, you know, if you’re into that sort of thing, maybe you should buy him a CD or something.
• Don did some work on info pages. So, you know, if you’re into that sort of thing, maybe you should buy him a CD or something.
• Brent and Don have both done performance enhancements, including an awesome patch from Don for the DocBook transformations. (/me smacks himself.)

That’s right. Yelp 2.14 will search and print. And I had almost nothing to do with any of this. Free Software, I salute you!

If you haven’t read Project Mallard yet, read it now. Go ahead, I’ll wait.

Matthew Thomas pointed me to DITA, an all-singing topic-oriented format from IBM. There’s a lot of complexity there, but it’s worth looking at. Some resources:

• Norman Walsh on DITA for DocBook
• Wikepedia addresses DITA
• IBM developerWorks: Introduction to DITA
• And a PDF: DITA Language Specification

Also interesting is that Microsoft is heading in a similar direction for Longhorn. What’s really interesting is that their content model looks an awful lot like DocBook. Some quick reads:

• On MSDN: Introducing Windows “Longhorn” Help
• On HyperWrite: Help.Longhorn – What is it?

A lot of people are having pretty much the same idea. I suspect the success of sites like Wikipedia have had a profound impact on how we all think about such things.

What I need now is to assemble a team of people to sit down and flesh things out. I need people who are out there writing the tools, and who have a strong idea of what sorts of things are going to trip us up in the implementation phase. I need people who are out there writing the content, and who have a strong idea of what sort of content structure is actually needed. And I need people who have ties to the Greater XML Community, and who can smack me down when I reinvent too many wheels.

I was asked for the script I used to count element usage in our DocBook files, as posted here yesterday. I’ve got to be honest. I wrote it in Mathematica. Why? Well, I thought through the problem in my head, and I thought to myself “Golly, the Split function would be handy here.”

But hey, it’s not all that hard with sh, given the right tools. So I wrote up the script again in something everybody could use. It’s a simple sh script, using the XMLStarlet utility. Don’t have XMLStarlet on your machine yet? Go get it. Get it now. XMLStarlet is a godsend for any *nix geeks doing XML stuff. Learn it, use it, love it.

Here’s the script in plain ol’ sh:

#!/bin/sh

rm -rf ALL && touch ALL;
rm -rf COUNT && touch COUNT;

for dir in /usr/share/gnome/help/*; do
    name=`echo $dir | sed -e 's/.*\///'`;
    doc=$dir"/C/"$name".xml";

    xmllint --xinclude $doc \
	| xml sel -t -m "//*" -v "name(.)" -n - \
	| grep -v '^$' >> ALL;
done;

for el in `sort -u ALL`; do
    echo -n "$el " >> COUNT;
    grep -c $el ALL >> COUNT;
done;

sort -k2 -rn COUNT >> COUNT.tmp && mv COUNT.tmp COUNT

Following Federico’s suggestion, I whipped up a script to see how often we use which DocBook elements in our help files. The top four are para (10499), entry (3415), listitem (3114), title (1948). None of these came as a surprise to me. Here’s some interesting data points:

The rundown of how often the basic sectioning elements are used: sect2 (1201), sect1 (502), sect3 (205), section (8), sect4 (2). We have very few documents using the section element. In general, I favor using section, but the numbered ones do provide more information with this script (not that it would be hard to write another depth-checking script). Since sect2 is used more than twice as often as sect1, it seems two-level section is common. Deeper levels seem rather uncommon, although three-level isn’t rare.

Articles (70) and books (4), right about what I expected.

On basic inline markup: guilabel (1858), application (1527), keycap (1032), guimenuitem (792), guibutton (744), filename (702), guimenu (647), menuchoice (605), literal (281), keycombo (214), phrase (206), replaceable (170), command (140), guisubmenu (134), userinput (109), and stuff that didn’t manage to hit 100. Those in the know will know that guilabel (1858) is used as a catch-all for most things on the screen. Its high usage amuses me, because it means DocBook’s various gui* elements can’t manage to catch everything. I think it should give up. Note that menuchoice (605) is used far more often than keycombo (134). I was actually surprised that userinput (109) was used as often as it was. I’ll have to take a look at where it’s being used.

On lists: listitem (3114), varlistentry (1135), itemizedlist (309), variablelist (276), orderedlist (267), simplelist (3). I didn’t expect a high turnout from simplelist (3). Since listitem (3114) is used in most lists (just as li is used in both ol and ul in HTML), its number wasn’t surprising. There’s not a huge difference in numbers between the three common list types.

The titleabbrev element was used only once. I’ll bet I’m the one that used it, too.

We used indexterm 242 times, a primary term 241 times (huh?), a secondary term 128 times, and a tertiary term only 17 times.

We used the general-purpose synopsis element 123 times. As expected, we didn’t use any of the special-purpose *synopsis elements at all.

Admonition breakdown: note (96), tip (26), caution (6), warning (5), important (1). I still don’t have a clear idea on the difference between caution and warning. I was surprised that important was used only once.

There were 232 imageobject elements, but only 204 textobject elements. That means we have images without accessible text.

Some block elements: figure (188), screenshot (187), informaltable (172), mediaobject (164), screen (68), table (64), literallayout (27), programlisting (13), highlights (13).

Finally, we used just 146 out of DocBook’s 411 elements.

For is it not written in the Book of Gnome:

In the darkest hour of the Documentation Project, there shall come a False Hope of salvation. And the last Fearless Leader of the old ways shall embrace the False Hope, and the eyes of the people shall be blinded to the truth. They shall trust in the False Hope and lay down their pens, and the Project shall lay in ruins.

Though the Serpent speaks in the tongues of men, he is not man, nor shall he deliver man from the darkness. He is a lie, preying on man’s weaknesses and desires. He who believes in the Serpent shall be forever scarred, and shall do good deeds no more.

And the last Fearless Leader, being marked by the lies of the Serpent, shall nevermore lead men in the great Project they knew. Only the benevolence of times past shall resurrect their charge.

Then the trumpets shall sound as Our Once and Future King returns. And he shall return to the people the benevolence and love of times forgotten. And his reign shall last a thousand thousand days.

So was it prophesied, so shall it be.