Erik Ray (eray@oreilly.com)
This document describes the O'Reilly customization of DocBook-XML for marking up manuscripts. We call this customization DocBook Lite because it's a subset of DocBook tailored and augmented to fit our particular style of books. The DTD is an extension of DocBook-XML version 4.1 by Norm Walsh, available at the OASIS Group's website.
For any questions that this document doesn't cover, please contact the Tools Group at tools@oreilly.com. Any feedback or contributions are enthusiastically accepted.
The DBLite package is available from our FTP server at ftp://ftp.ora.com/pub/dblite/dblite.tar.gz. The tables below describe the details of the package.
install Command to install files onto your system. catalog Catalog file to support public identifiers, if you need them. dblite.dtd The DTD for DBLite. dblite_htmlents.dtd Variant of DTD using HTML character entities instead of standard Unicode entities. dblite_noents.dtd Variant of DTD without any character entities defined. dblite_safari.dtd An older version of the DTD for backwards compatibility with Safari project. html.ent A substitute definition of entities with ISO-8879 names (HTML instead of Unicode). sdblite.dtd An SGML version of the dblite DTD. bin/ Tools for processing DBLite documents. css/dblite.css A CSS stylesheet suitable for XML editors like XMetaL. doc/ Documentation for DBLite. docbook41/ DocBook-XML 4.1 distribution on which DBLite is based. test/lx/ A sample book in DBLite XML. xsl/ XSLT stylesheets for use by some tools.
db2h A simple DocBook to HTML conversion tool. db2html A more complex DocBook to HTML conversion program for CD-ROM titles. db2htmlindex Used with db2html to generate online indexes. db2htmlindexproc Helper for db2htmlindex. dbnormspace Normalizes space so that documents are easier on human eyes. dbtest Tests DBLite installation. dtdinfo Reads a DTD and outputs useful information. dtdx2s Converts an XML DTD into an SGML DTD. xtrans Transforms an XML file using an XSLT transformation script. xval Validates an XML file. xwf Checks well-formedness of files.
Things you need, not included in the package.
Library Source Purpose libxml2 gnome.org* C Library for parsing XML documents. Used by db2h, db2html, dbtest, xtrans, xval, xwf. libxslt gnome.org* C Library for running XSLT transformations. Used by db2h, db2html, xtrans. XML::LibXML cpan.org* Perl module for XML parsing. Used by db2h, db2html, dbtest, xtrans, xval, xwf. XML::LibXSLT cpan.org* Perl module for XSLT transformation. Used by db2h, db2html, xtrans. XML::DOMHandler cpan.org* Perl module used by db2html. *Note: if you are running MacOS X, you should obtain these libraries through the Fink (http://fink.sf.net/) packaging system.
There are lot of ways to edit XML. You can use a basic editor such as vi or emacs. Both have versions and/or modes that give special support to XML markup. For emacs, there is a package called psgml that adds an XML/SGML major mode which integrates an XML parser for in-situ parsing. These tools, however, do not give you any kind of special formatted view other than possibly hilighting tags in color.
For a nicer, formatted view of text, and a GUI interface, you can opt for one of the many graphical XML editors available. Several authors have said good things about XMetaL, a Windows-only editor, for example. I have enjoyed working with Morphon XML Editor, an editor written in Java that supports MacOS, Windows, and Linux. Most XML editors that provide formatted viewing use Cascading Stylesheets (CSS) to render styles. This package includes a sample CSS stylesheet that you can use.
For hints at how to tag documents, read the included DocBook Lite Style Guide.
It's a good idea periodically to check your XML files to make sure they are well-formed (i.e. no syntax errors in the markup). Use the tool xwf included in this package to locate errors and fix them. For arguments, it takes individual XML files in the book like so:
xwf ch01.xml ch02.xml ...
For more thorough error checking, use the xval tool to run a validation test. This compares the document against the DTD which has grammar rules for XML elements. Apply it only to the book.xml file (top level XML file for the book):
xval book.xml
Note that for xval to work correctly, you need to set up a file called book.xml which contains a Doctype declaration. To learn how to do that, see the DocBook Lite Style Guide included in this package.
Besides the formatted viewing capability in graphical XML editors, I've provided another way you can format books for viewing. The tool db2h transforms the DocBook-XML into HTML for viewing in a web browser. Each chapter will be converted into a separate HTML file. You can run it on the whole book (using book.xml as the argument) or on individual XML files.
For more information about DocBook, including tools and documentation, these resources should be of help.
Norman Walsh and Leonard Muellner, DocBook, The Definitive Guide, O'Reilly and Associates.
The OASIS Group DocBook Project page.
The O'Reilly Tools Group (tools@oreilly.com).
The Tools Intranet Page (if you are inside the O'Reilly firewall).
Permission is granted to use and distribute the DBLite DTD and materials, but not to modify it any way. All content in this package is copyright © 1995-2002 O'Reilly & Associates.
Thanks to the following people for contributing to the use of DocBook at O'Reilly:
And anyone else I haven't thought of :-) ...