Tag Archives: docbook

XML editing with Emacs.

I’ve been using GNU Emacs ever since I started working with the Fedora documentation team years ago. I wouldn’t call myself a power user by any means, but it handles my modest needs very well. Other people may have different preferences, which is fine. (Holy wars to /dev/null please.)

In the intervening years some really nice tools have evolved for dealing with different kinds of XML documents. I used to use the old psgml-mode to do editing of XML documents, but nowadays things are even more elegant and functional with nxml-mode. In truth, I was probably late to switch, simply because I didn’t have time to fix that which wasn’t broken.

However, ultimately psgml fell out of favor and the switch was necessary. But I discovered an array of helpful configurations that made XML editing even easier than before. I use these tools for editing DocBook XML, but they’re equally powerful for other schemas as well. For instance, you could use nxml-mode to hand-edit libvirt domain files with good confidence on their validity.

You can probably find directions like these (or even better) in a lot of places around the web. What I found difficult about the process was discovering the why as opposed to the what to do. How does all this stuff work, anyhow? None of the pages I read did a great job at explaining that. Admittedly, some of them were parts of much larger works, but I just wanted to get something done, not read an entire book. In writing the above page, I thought to myself, How can I improve this situation for the next person?

The key to solving that problem was this fantastic post by Mel Chua (and her lightning talk at FUDCon Tempe) where she talked about baking croissants. Short summary: it’s not enough to write a recipe and expect people to follow it, if your goal is to get people baking who aren’t bakers by trade. You have to take the time to fill in all the gaps.

So the result is this page I added to the Fedora wiki: How to use Emacs for XML editing.

Thanks, Mel, for the great advice. If anyone finds something wrong with that page, why bother commenting here? Just edit the wiki page if you’re a Fedora contributor (in other words, someone with an account and completed CLA). I’ll get notified when you do and everyone can benefit from your changes.

UPDATE: I revised the page slightly to give some needed background information up front and make it even more Mel-icious. Also I slightly edited this post to eliminate some awkwardness from where I rearranged text.

Documenting the goodness.

The Fedora Documentation team uses a fantastic tool called Publican for their documentation work. Publican allows people to turn DocBook XML source, a popular and fairly ubiquitous format, into beautiful renderings in HTML, PDF, ASCII, and even RPM. Publican was developed by Jeff Fearn, who works at Red Hat’s office down under in beautiful Brisbane, QLD Australia, and of course a cast of many people who contributed bugs and enhancement requests.

The Fedora Docs team uses DocBook XML for a number of important release documents like the Installation Guide and the Release Notes. By using source in a git repository, they can collaborate quickly on new and existing documents, and Publican helps them quickly produce translatable POT files that our awesome Fedora translation teams turn into localized documents. (That’s the meaning of L10n by the way — “localization.”) The work the Documentation team produces can be turned into dozens of local languages this way.

When Publican originally debuted, it was fairly robust but it did take a while to build things. Recently, though, it’s taken an enormous leap in efficiency, and rendering documents is incredibly fast, which makes the lives of writers, editors, and translators better by a huge margin. When your workflow speeds up by a factor of ten, thanks to the hard work of developers, it does tend to put a smile on your face!

Wait — did I mention the hard work of developers? Well, let me not forget the next step in this toolchain of wonder and majesty: Transifex. The genii over at Indifex haven’t been sitting on their laurels either, and we’re now using a newer branch of their product on our translation site. That allows our translators to work incredibly quickly and efficiently on documentation and software, localizing all of them so that we can bring Fedora’s free software to people all over the world in their own languages.

In fact, the Indifex guys work so fast that they’ve already turned out version 0.8.0 even though we’ve just migrated to 0.7.4 for our translation site. (I hear the transition up to 0.8.0 isn’t difficult, and it’s likely we’ll be doing this in the near future.) I should also note that a bunch of people spent cycles on getting our translation infrastructure updated, including Dimitris Glezos, Mike McGrath, Noriko Mizumoto, Jens Petersen, Diego Búrigo Zacarão, Ricky Zhou, and others. You guys just kick hindquarters all over the place.

The great thing about moving to Transifex 0.7.4 is that it now supports Publican’s method of divvying up POT and PO files for translators. Rather than have just one big file for the original format, and for each language, Publican divides them up. This makes collaborative work easier, and it also increases translators’ morale because their individual and iterative progress is more visible.

As a result the Docs and Translation teams are ready to kick out the jams for the Fedora 13 release. Translators can quickly and easily test their translation; documentation folks can test builds quickly and collaborate faster on content changes; and we can publish the results immediately to package updates which we can push out regularly leading up to the final release of Fedora 13. It’s going to be amazing!

Notes on a weekend.

It was a nice weekend even though it was blisteringly hot. Saturday my wife took my daughter out for haircuts and some shopping, so I stayed at home with Trouble (we should probably just get around to changing my son’s name legally) and we played a bit. I also checked to see how his reading is coming along, and at age 4.5 he’s doing about as well as we could possibly hope. He trips a bit on words like “casually” but generally he can read even things he’s never seen before at a decent speed.

I also tuned my wife’s old autoharp — which has been sitting in various closets since we moved in together close to 20 years ago — so my daughter could use it. In actuality it probably badly needs new strings, but those generally cost upward of $60 and I have yet to see if Evie will keep up with it. They’re kind of limited, but very easy to play, and there’s a huge number of songs that are within reach with just a handful of chords. She seemed pretty psyched about it, but she’s much more into reading, writing, and making crafts.

I worked a little on a revamp of the Fedora release notes to try and get them building with publican. However, I ran into some pretty thorny problems because publican doesn’t seem to do things with XML in an XML-ish way. Instead, it relies on a lot of awk and sed commands to query or change the XML during the validation, translation, and build processes.

I remember several years ago when I was one of the people working on the Fedora documentation tool chain, that I had initially tried doing a lot of work this same way. The downfall in that methodology is it makes assumptions about the way the input document is physically formatted, which is a huge fail when it comes to XML (as I later learned, slowly and painfully). It also makes life very hard for people who want to use your tools on their pre-existing documents. Instead, there are a large variety of ways to do these same things programmatically using XSLT. Your input document is “understood” as a set of data nodes, and can be queried, manipulated, and output in ways that are sensible.

In any case, I was pretty disappointed, and although I was initially very enthusiastic about getting our Fedora docs working using this toolchain, I’m a little less so now. I’ll probably see if I can’t pull out some specific problems and file them as bugs. That means I should probably publish a git repository of the document on which I’m working, as a sort of test for the toolchain. Hopefully I’ll get some time for that this week.

Saturday night I stayed up a bit and watched Le scaphandre et le papillon (The Diving Bell and the Butterfly), which was simply superb. The lead, Mathieu Amalric, was great, but the actor who most surprised me was Max von Sydow as his father — phenomenal performance.

On Sunday morning Evie and I went out for some more bike riding practice. There were a couple of near-spills, but nothing too traumatic, other than the usual whining because she couldn’t immediately do it perfectly. I think it’s just a matter of a few more practices and she’ll be confident enough to start turning. By lunchtime, it was practically too hot to be out, but nevertheless I was running alongside her down the street as she went. We finished up covered with sweat, and went in to get cleaned up and have lunch.

Last night, Eleya and I watched another great film — El Orfanato (The Orphanage). It’s a Spanish language film that purports to be a horror movie, but only in the same sense as The Sixth Sense. Notably, it was produced by Guillermo del Toro, who seems to be racking up quite the résumé of tragedic horror fantasies featuring children. Well worth seeing.