Re: XML/DocBook for newbies
I just came here to ask about a good guide
to DocBook, having been disappointed by
the site. I tried the Definitive Guide, but it has
Chapter 4 talks about publishing, but only mentions
stylesheets. There's nothing practical here about how
I actually do it.
To get a feel for the process of creating documents using DocBook, I
found it helpful to walk through the example presented in the article
"Creating an Online Help System with JavaHelp and DocBook"
article walks you through getting all the tools, creating a sample
DocBook document, and processing the file to create JavaHelp. It gives
you a feel for the tools and the process of converting a document; I
recommend it even if you're not ultimately interested in JavaHelp. By
now there are newer versions of some of the tools listed in this
article--I think you'd probably be fine with the newest version of the
XSL stylesheets (now 1.69.1), but stick to Saxon 6.5.3.
If you decide to make the plunge, here are some questions and issues
you need to consider:
First, what output formats are you targeting? I convert DocBook to
HTML and PDF, so my answers deal with those outputs. You may need
different tools if you're targeting different formats.
The next decision is whether you want to use XSL or DSSSL
stylesheets. I went with XSL because the DocBook XSL stylesheets are
still being actively maintained and developed, whereas I've been
reading that DSSSL is pretty much a dead end these days (but there's
still a sizable DSSSL user community). Check out the output formats
for the DocBook XSL stylesheets to see if they'll meet your needs.
(The example in the article noted above uses XSL.)
If you choose to go with XSL, you absolutely must read Bob Stayton's
excellent and indispensable "DocBook XSL: The Complete Guide." It covers
everything from choosing and installing tools to customizing the
stylesheets. It's available online at www.sagehill.net/docbookxsl/ index.html,
as an e-book from www.sagehill.net/book-description.html, and in
hardcopy from the usual sources (make sure you're getting the 3rd
Assuming you're not using DSSSL, you need an XSLT processor, and if
you're converting to PDF, an XSL-FO processor. The DocBook XSL Guide
discusses different options for these tools. The most commonly used
open source XSL-FO processor is FOP (xml.apache.org/fop/index.html)
but the current stable release (0.20.5) doesn't implement all of
XSL-FO yet. However a new release with improved functionality
is in the works, with a release planned by the end of the year. (This
is an all-volunteer project, so take that into account before relying
too heavily on this schedule.) There are also several commercial
XSL-FO processors available, ranging greatly in price and
functionality. The DocBook XSL Guide and a few web searches should
provide you with guidance on XSLT and XSL-FO processors.
Finally, you need to choose an authoring tool. You can, of course,
just type text in any editor, but you'll probably want some automatic
help with the tags, such as enforcing DTD compliance. I'm used to
dealing with markup directly so I went with PSGML for emacs. There
are also many WYSIWYG authoring tools, some of which have free
versions. Again, a web search should be helpful here; it looks like
"DocBook authoring tools" turns up many useful links.
"DocBook: The Definitive Guide" is designed to tell you about the tags
and it's extremely useful for that. But chances are you'll end up
using a tool that won't let you create improper markup, so it becomes
less important as you get to know the tags you use most frequently.
I still use it occasionally as a reference.
Hope this helps,
Knowledge Discovery Laboratory
Computer Science Dept., University of Massachusetts
Now Shipping -- WebWorks ePublisher Pro for Word! Easily create online
Help. And online anything else. Redesigned interface with a new
project-based workflow. Try it today! http://www.webworks.com/techwr-l
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.
Search our Technical Writing Archives & Magazine