Appendix B. Building DocBook XML Books
Prev   Next

Appendix B. Building DocBook XML Books

This appendix contains supplementary information for building books using DocBook XML as an alternative to FrameMaker source files. Other parts of this book contain useful information for the overall book building process. When using DocBook XML directly, the information in this appendix supersedes the directions that apply to FrameMaker based books. The following sections introduce DocBook XML and the steps to create online books.

What is DocBook XML?

XML (http://www.w3c.org/XML/ ) is an increasingly popular format for structured content. There is really no limit to what the structured the content contains and current uses range from books to laboratory data sets. XML was created as a simplification of SGML of which HTML is one example. The key features of XML include:

  • Unambiguous structure can be verified easily

  • Separation of content from presentation

  • Platform independence by using Unicode

  • Numerous additional tools for creating and processing XML

  • Data interchange using industry standard formats

SGI publications use a particular structure of XML known as DocBook (http://www.docbook.org ). DocBook is a popular, industry standard markup language for technical documentation. A short example of a DocBook XML document below shows the starting point of an article.

Example B-1. Sample DocBook XML Document

<?xml version="1.0" ?>
<!DOCTYPE article SYSTEM "dtd/docbook/docbookx.dtd">
<article>
<title>Widget Update</title>

<para>
Introductory text.  Refer to <xref linkend="details"/>
for additional information on the new widget format.
</para>

<section id="details">
<title>Widget Details</title>

<note>
<para>This is preliminary information.</para>     
</note>
<para>
...
</para>
</section>
</article>

This simple example demonstrates the features of XML. Using an XML parser, it is possible to verify the document is structurally correct. This document could be sent to anybody using DocBook, regardless of computer platform, who could process or update the document. The example shows how the information is tagged to describe what it is without regard to its appearance. This allows existing and future tools to transform the content into formats such as HTML, PDF, and man pages with no changes to the document. Additionally with minor changes, the formatting style of any document can be changed quickly and uniformly.

Note: The book building tools only support creating an HTML formatted copy of the book. Other publicly available tools, not included in the SGI Book Building Tools, can be used for creating print formatted deliverables.

Building DocBook XML into HTML

Before following Procedure B-1, ensure that the book building tools have been installed as covered in Chapter 2, “Preparing Your Workstation”

Procedure B-1. Building a DocBook XML Book

  1. In a new directory, create the DocBook XML instance using a text editor or other XML editing application. For the purposes of the book building tools, the doctype declaration that begins the file must contain the SYSTEM path shown in the example below. The PUBLIC DocBook XML identifier can optionally be used.

    <!DOCTYPE article SYSTEM "dtd/docbook/docbookx.dtd">

    Any figures used in the book must be referenced using the fileref attribute and refer to files in the online subdirectory as shown in this example:

    <imagedata fileref="online/publish.gif"/>

    If online help as covered in Chapter 7, “Creating Online Help ” is required for this book, the condition attribute is used to hold the helpid information. This use of the condition attribute can be used with any container tag that contains a title tag. In the example below, the second instance of helpid should be replaced with the helpid string.

    condition="sgi_helpid:helpid"

  2. Set up the Makefile that drives the publishing process using these command and instructions.

    % cp /usr/share/Insight/templates/make/Makefile_sgidocbk Makefile
% chmod 644 Makefile

    Using the instructions in the Makefile and the values below, edit the following variables in the file:

    • TITLE

    • FULL_TITLE

    • DOCTYPE - set to DOCBOOK_XML

    • BOOK_FILES - set to the name of the file created in step #1.

  3. Publish the book by running make book. If the XML parser reports any error, use the error description and line number to correct the problem. After the make command completes, the For review: line provides a URL to view to HTML files in the build/sgi_html subdirectory.

Prev Table of Contents Next
Appendix A. Using the SGI Book Building Templates to Author Documents  Glossary