Writing the Flumotion Manual

I’m blogging about this a little late because I waited for some (internal) Flumotion Incorporated releases before mentioning it.

Between July and September 2008 I did about a man-month of work for Openismus on Flumotion‘s user manual (HTML, or PDF, or DocBook in the GNOME help browser), the first major piece of user documentation I’ve done. I usually write developer documentation. Flumotion is an audio/video streaming system. From the introduction:

Flumotion can broadcast your content live or on-demand in a range of popular audio and video formats. It supports a wide range of input hardware thanks to its use of Linux, GStreamer and other open source software. You can get started quickly with Flumotion’s simple user interface then just place a link to the streamed content on your website.

Flumotion allows processing to be spread across multiple machines, so your platform can scale to handle more viewers of more streams in more formats. Its open source architecture makes it more efficient and more flexible than competing systems, making better use of your hardware.

I worked from a table-of-contents that I agreed with Thomas Vander Stichele over a couple of days in person. There was a previous version but it was very developer-focused, immediately talking about the internal architecture of the software. Lots of that existing content was reused, updated, and expanded as sysadmin information, but the first few chapters are new, actually making the manual user-focused.

We wanted  an immediate introduction to Flumotion while providing a path to its full functionality and clearly offering the necessary information for later deployment, configuration, and security. I think we succeeded. We also added a reference section that’s generated from the Flumotion components themselves. These and other sections are heavily interlinked so it’s easy to get more information regardless of where you jump into the manual, because it’s natural for different people to focus on their area of concern.

I needed to ask lots of questions and do follow-up interrogation to get the raw information before writing content. Along the way I found myself acting as a tester, filing several Flumotion bugs that were then fixed, so Flumotion now works better as well as being better documented. The Flumotion/Fluendo developers were incredibly helpful and never lost patience with me, making the work a real pleasure.

Note that neither the HTML or PDF at flumotion.net have yet had any Flumotion-specific style or layout applied to them.

DocBook to PDF with fop

I’ve been writing DocBook documentation for a long time, starting with the gtkmm manual, so I’m generally familiar with the tools. (Though I had to learn lots of new markup and correct terminology for documenting an application instead of an API). Applications can just install their DocBook XML directly and leave the rendering to the GNOME Help browser (yelp), but you often need the document in HTML or PDF format to show on a website.

The DocBook XSL stylesheets for XHTML are still the correct way to generate HTML and work well. In the past I used docbook2pdf  (a simple way to use jade) to generate PDF , as you can see in the gtkmm-documentation Makefile.am. But it quickly became obvious that docbook2pdf wasn’t good enough. For instance, it did not include our index in the PDF and didn’t offer any way to customize the PDF output.

So I tried fop again and actually got it working, at least on Fedora Linux 9. fop uses Java so it had not really been packaged on Linux distributions before Java was open-sourced. I was pleasantly surprised at how much progress has been made since my last attempts. In the past it was frustrating to hear that we should be using fop because that was the only system being maintained, but never finding anyone who had managed to get it working.

Using fop means generating a .fo (XML) file from your DocBook XML, by processing it with the official fop XSL stylesheet from the DocBook people. fop then processes this .fo file to create a .pdf file. You can influence the end result by setting some XSL parameters when generating the .fo file.

Even on Fedora 9 there were various bugs to work around, such as:

• fop can’t read PNG files.
• fop massively scales up some jpeg images in pdfs
• We had to use imagemagick to scale down the pictures for the PDF because we couldn’t find any way to make fop do this automatically. I think that’s a bug though I haven’t filed it yet.

As the flumotion-doc Makefile.am shows, we also chose a useful set of DocBook XSL Stylesheet parameters, which are surprisingly well documented. These avoid some problems (maybe bugs, though its debatable) and add some attractive admonition icons.

That Makefile.am is the result of much work so I hope it’s useful to other people trying the same thing. Note that it has a little extra complication because we bring in some XML examples inline, just like we bring C++ examples in to the gtkmm book.

fop broken again on Fedora 10 and Ubuntu Intrepid

Unfortunately I can’t confirm yet that these bugs are really fixed in Fedora 10 because Fedora 10 has some even more serious bugs that prevent me from getting that far:

• fop fails with SEVERE: Couldn’t find hyphenation pattern en
• fop fails when using indexterm in a varlistentry

And Ubuntu Intrepid (the first Ubuntu to package fop) has the same problem: fop crashes with SEVERE: Couldn’t find hyphenation pattern en. Plus the workaround  for the FOP PNG problem (and the scaling)  doesn’t work due to an apparently totally-broken Imagemagick  on Ubuntu.

This is rather disappointing. I was looking forward to using fop for the gtkmm book, for both HTML and PDF, hoping that the syntax highlighting stuff would work on our inline example code. Note to self: This might be useful help for that.