Simple Web Sites Using DocBook XML and CSS

The Web was originally intended to make content easily accessible. Today, Web developers focus on style and marketing, but the need to put together content-driven Web sites quickly and easily remains as valid as when Tim Berners-Lee first conceived of HTML. I have taken the approach of using primarily DocBook XML and CSS, as well as some other readily available Linux tools, that allows me to bring up simple content-focused Web sites—a poor man's content management system.

I am an embedded software developer. HTML, XML, CSS and the Web in general are peripheral to what I do. I am not as intimate with the details and idiosyncrasies of HTML as I am of processors, NICs and UARTs. Yet today, the Web is part of everything. Proof that an embedded processor is up and running under Linux often consists of being able to browse Web pages on it. I look for clients, and clients seek me out over the Web. Although expertise in JavaScript, cross-browser HTML, CSS, PHP, Ruby on Rails and so forth is not essential, a basic knowledge of HTML and the ability to use some tools to create simple but useful Web sites quickly and easily is increasingly a core skill to software development, as well as many other jobs. DocBook XML provides a means of creating documentation focused on content, with the ability to use it easily in many forms, including Web pages.

This approach has a number of elements, and they are not heavily interdependent. Even if you do not like my overall approach, you can take bits and pieces from it and incorporate them into your own approach. I am a software-tools kind of guy. There are probably numerous IDEs for Web development that will do everything for you once you know them, and there are likely a number of Eclipse plugins. Powerful, dedicated tools typically have a steep learning curve that pays off only if you do a lot of that type of work.

This article is not about DocBook XML. It is about how to build Web sites using CSS to render DocBook XML documents simply. I am not a Web developer, and I opt to learn tools that have broad uses. The tools I use for building Web content are vim for editing, m4 or Perl for macro processing and HTML tidy for verification—the same tools I use to develop software and write documentation. During the past few years, I have added basic XML, particularly DocBook XML, to my list of fundamentals.

I keep a simple DocBook XML article template readily available and pull it up in vim whenever I feel inspired to write something technical that is larger than an e-mail. By using a DocBook XML template, I can focus mostly on content and produce results that are clear and meaningful, with minimal emphasis on presentation.

More recently, I have discovered that with a little help from CSS, DocBook XML documents can be viewed directly on any Web site by CSS-capable browsers, without transforming to HTML, making it easy to add to my Web site. For more complex documents, OpenOffice.org supports DocBook XML as an output format, and there are increasingly more tools to produce and manipulate DocBook XML. DocBook XML can be read directly by OpenOffice.org or transformed easily into all commonly used document formats, such as HTML, PDF, Word and so on. One objective of XML (one that would be difficult to identify in the competing XML word-processor formats) is divorcing content from presentation. This is a principle I heartily endorse.

I make a distinction between the parts of a Web site used for navigation and the content of the Web site. I deliberately choose to separate content physically from navigation. With rare exceptions, all content pages are devoid of navigation and function as standalone documents. Today, I do them in DocBook XML. Previously, I used HTML; however, I always tried to maintain a separation between content and navigation. My first step is to build an HTML presentation/navigation framework. I create the main HTML index page for the site, and I use HTML FRAMES to divide the display into three regions: a header, a menu and a body. FRAMES are somewhat frowned upon within Web development, as they can be used to capture other people's Web content and create the impression that it is your own. They also can impede navigation, and they may be less friendly to people with disabilities. However, I am not aware of another equally easy-to-use Web construct that can be made to separate content from navigation and presentation. There are other means to achieve similar effects, but all of those that I am aware of incorporate navigation and presentation elements into the content. My objective is to be able to develop the content of the Web site in DocBook XML, modified only to include a stylesheet and to isolate presentation and navigation elsewhere.

There is one other heretical side effect to this approach—nothing about it requires a Web server. You can build and test all of this in the browser of your choice without installing a Web server, and when finished, you can drop it all on a CD-ROM where it can be viewed on any system with a Web browser.

The core of my index page is:

<frameset class="frame" cols="140,*" bordercolor="#000000"
frameborder="0" framespacing="0">
 <frame class="frame" src="margin.html" name="Margin" scrolling="no"
marginwidth="0" marginheight="0"
 <frameset class="frame" rows="100,*" bordercolor="#000000"
frameborder="0" framespacing="0">
  <frame class="frame" src="header.html" name="Header" scrolling="no"
marginwidth="0" marginheight="0" />
  <frame class="frame" src="home/index.xml" name="Body" scrolling="auto"
marginwidth="0" marginheight="0" frameborder="0" />
 </frameset>
</frameset>

This divides the browser display into three regions. A menu area on the left, a header at the top and a body for content in most of the remainder. My header page tends to be fairly trivial, basically:

<body class="header" id="body-header">
 <div class="header">
  <h1 class="header">My Title</h1>
 </div>
</body>