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:
- Make all output prettier.
- Provide the necessary goodness to make HTML suitable for our web site, and hopefully easily tailored to other web sites.
- Get a simple script to do the transforms.
- Use this as the base infastructure for library.gnome.org.
- Get people to write documentation.
- Put all of our documentation online.
- 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.
