O'Reilly DocBook Lite

O'Reilly Production Tools Group Documentation

Erik Ray (eray@oreilly.com)

Contents

  1. Introduction
  2. DBLite Package
  3. Authoring Documents
  4. Style Guide
  5. Checking Documents
  6. Viewing Documents
  7. Resources
  8. License Information
  9. Acknowledgements

1. Introduction

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.

2. DBLite Package

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.

Files and Directories

installCommand to install files onto your system.
catalogCatalog file to support public identifiers, if you need them.
dblite.dtdThe DTD for DBLite.
dblite_htmlents.dtdVariant of DTD using HTML character entities instead of standard Unicode entities.
dblite_noents.dtdVariant of DTD without any character entities defined.
dblite_safari.dtdAn older version of the DTD for backwards compatibility with Safari project.
html.entA substitute definition of entities with ISO-8879 names (HTML instead of Unicode).
sdblite.dtdAn SGML version of the dblite DTD.
bin/Tools for processing DBLite documents.
css/dblite.cssA 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.

Tools

db2hA simple DocBook to HTML conversion tool.
db2htmlA more complex DocBook to HTML conversion program for CD-ROM titles.
db2htmlindexUsed with db2html to generate online indexes.
db2htmlindexprocHelper for db2htmlindex.
dbnormspaceNormalizes space so that documents are easier on human eyes.
dbtestTests DBLite installation.
dtdinfoReads a DTD and outputs useful information.
dtdx2sConverts an XML DTD into an SGML DTD.
xtransTransforms an XML file using an XSLT transformation script.
xvalValidates an XML file.
xwfChecks well-formedness of files.

Dependencies

Things you need, not included in the package.

Library SourcePurpose
libxml2gnome.org*C Library for parsing XML documents. Used by db2h, db2html, dbtest, xtrans, xval, xwf.
libxsltgnome.org*C Library for running XSLT transformations. Used by db2h, db2html, xtrans.
XML::LibXMLcpan.org*Perl module for XML parsing. Used by db2h, db2html, dbtest, xtrans, xval, xwf.
XML::LibXSLTcpan.org*Perl module for XSLT transformation. Used by db2h, db2html, xtrans.
XML::DOMHandlercpan.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.

3. Authoring Documents

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.

4. Style guide

For hints at how to tag documents, read the included DocBook Lite Style Guide.

5. Checking Documents

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.

6. Viewing Documents

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.

7. Resources

For more information about DocBook, including tools and documentation, these resources should be of help.

8. License Information

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.

9. Acknowledgements

Thanks to the following people for contributing to the use of DocBook at O'Reilly:

And anyone else I haven't thought of :-) ...