This page is an archive, possibly an out-of-date one. You’ll find newer weblog postings at So… and more about norm on his homepage.

DocBook.org redesigned

Volume 9, Issue 74; 28 Jul 2006; last modified 08 Oct 2010

Yesterday, I rolled out a redesign of the DocBook.org website.

DocBook.org, like nwalsh.com and a number of other sites I put together, was originally created with the Website customization layer of DocBook.

Back in 1999 or 2000, when I did most of the design for the Website document type, it seemed a pretty reasonable solution. Back then, CSS support was limited at best and browsers weren't as compatible as they are today, especially in the area of scripting support. In order to get a menu system, I resorted to HTML tables constructed staticly in each pageAnd because tables aren't the most accessible sort of markup, I could also generate a completely different set of pages with more accessible markup (though I wasn't actually using that feature on docbook.org).

In order to make maintaining the navigation system practical in Website, it is described by a separate “layout” file, but the entire layout is constructed in each page. So if the layout changes, every page has to be rebuilt. (In point of fact, that's not true, but any page that is related to the layout change does, and I never figured out a good way to determine which subset of pages was actually effected by the layout change.)

For the DocBook.org site, this was particularly tedious because each new release of any DocBook resource added a page to the site and that required rebuilding the whole site. Also, the actual page for each release was a pretty thin skin over a simple directory listing.

So, inspired by the Yahoo! UI Library, I went looking for something better. What I ended up with was a simple set of navigation tabs that require nothing more than CSS.

To ease the tedium of making a new release, I decided to turn all the release pages into actual directory listings, dressed up with a little header markup and some additional descriptions.

I'm still using a separate file to establish the menus, so that they can be changed without editing every page. In fact, the resulting menus are inserted into each page with a server-side include so I can actually change the menus without editing any pages. The markup for the pages, by the way, is no longer Website, they're straight DocBook V5.0 articles.

I think the design is an improvement. What do you think?

Speaking of website design, this site got a bit of a facelift a few weeks ago. I think it's improved as well. And I have every intention of improving the design of nwalsh.com real soon now. I haven't decided if I want to simply give the site a face lift or if I want to convert the whole thing to use my blog software. Stay tuned.

Comments

There's an processing instruction with the name "xml" in the middle of the DocBook.org pages. It's a good thing you use "text/html" or else Firefox would have given DocBook.org readers an "XML Parsing Error: xml declaration not at start of external entity".

—Posted by Sjoerd Visscher on 28 Jul 2006 @ 02:25 UTC #

Very nice! Really readable.

—Posted by Misty on 28 Jul 2006 @ 02:58 UTC #

Very nice. Theres a couple of broken links though: on the "Documentation" page, the links in the body to TDG and TDG5 are both incorrect and generate 404s - the correct links are in the menu above. However, both the pages linked to themselves contain broken links to the online version of TDG.

—Posted by Brian Ewins on 28 Jul 2006 @ 03:20 UTC #

Just seconding Brian, I was troubled this morning when most of the links to elements from my bookmarked DocBook reference (which I find invaluable), http://www.docbook.org/tdg/en/html/docbook.html, (for example: http://www.docbook.org/tdg/en/html/chapter.html) were broken, giving 404s.

On a positive note, the main page looks much nicer.

—Posted by Keith Fahlgren on 28 Jul 2006 @ 03:42 UTC #

Oh, ack!, Sjoerd. I forgot that Apache was going to stick something in front of my header. I've fixed that now, and also tinkered to make the files well formed. I don't see how to make them valid unless someone knows how to make Apache use lowercase element names.

Brian & Keith, I fixed the redirects. Those links should all work again.

Sorry about that.

—Posted by Norman Walsh on 28 Jul 2006 @ 04:03 UTC #

My goodness, what have you done to that poor duck's feet?

—Posted by Chris Chiasson on 30 Jul 2006 @ 12:44 UTC #

Perhaps you should just use HTML? HTML allows uppercase element names...

—Posted by Anne van Kesteren on 31 Jul 2006 @ 12:01 UTC #

Good suggestion, Anne! Unfortunately, that only helped a little bit. The Apache server seems to generate invalid HTML too. *Shrug*

—Posted by Norman Walsh on 31 Jul 2006 @ 02:15 UTC #

Hmm. The first two links I mentioned are still broken. (ie in the body of http://www.docbook.org/docs/ , the links to http://www.docbook.org/docs/tdg and http://www.docbook.org/docs/tdg5). I see they're both relative, I think they're missing leading slashes.

—Posted by Brian Ewins on 31 Jul 2006 @ 09:39 UTC #

Thank you, Brian. Sorry I missed those. Fixed now.

—Posted by Norman Walsh on 01 Aug 2006 @ 10:42 UTC #

The link http://www.docbook.org/tdg5/tdg5-0.0.17.zip in http://www.docbook.org/tdg5/ is broken.

Thanks. Federico

—Posted by Federico on 22 Aug 2006 @ 07:29 UTC #

Thanks, Federico; links fixed.

—Posted by Norman Walsh on 22 Aug 2006 @ 03:24 UTC #