Next / Previous / Contents / TCC Help System / NM Tech homepage

Abstract

Describes a system for writing general documentation for presentation in both Web and PDF form.

This publication is available in Web form and also as a PDF document. Please forward any comments to tcc-doc@nmt.edu.

Table of Contents

1. Advantages of DocBook
2. Setting up your directory for DocBook
3. Creating and translating your document
3.1. What is DocBook and how does it relate to XML?
3.2. The DocBook workflow cycle
4. Overall section structure
4.1. The titleabbrev element: Short title
5. Ordinary prose paragraphs: simpara and para
6. Inline markup
7. Links: connecting your document to itself and elsewhere
7.1. The link and xref tags: Linking within your document
7.2. The ulink tag: Linking to a Web page
8. Special paragraph shapes
8.1. Bullet lists: itemizedlist
8.2. Numbered lists: The orderedlist element
8.3. Procedures
8.4. Question-and-answer sets
8.5. Definition lists: variablelist
8.6. Notes, warnings, cautions, etc.
8.7. Block quotations
9. Verbatim displays
9.1. Callouts in verbatim displays
9.2. Poetry
10. Including graphic images
10.1. Formal and informal figures
10.2. Tuning graphics for different roles
10.3. Scaling a figure
10.4. Inline graphics
10.5. How to get screen shots (Windows, MacOS, and Linux)
11. Tables
11.1. Ruled lines in tables
11.2. Controlling table dimensions
11.3. Controlling alignment in tables
11.4. Horizontal (column) spanning in tables
11.5. Vertical (row) spanning in tables
12. Including TeX and LaTeX math
12.1. Preparing a formula with LaTeX
12.2. Preparing a formula with TeX
12.3. Processing your math files for inclusion
12.4. Automating math display production with your Makefile
12.5. Simple inline math
12.6. Inline math using LaTeX or TeX
13. User-defined entities
14. Breaking your document into multiple files
15. Special characters
15.1. Universally available entities
15.2. International character entities
15.3. The Greek alphabet
15.4. Special symbols
16. FOP: An older, free toolchain
16.1. FOP limitations
16.2. Bad page breaks
16.3. Using tables inside <listitem>
16.4. Graphics file support
17. Converting DocBook-SGML 4.1 documents
18. Converting DocBook 3.0 documents

1. Advantages of DocBook

The DocBook system has these advantages over other methods of creating documentation:

  • The same document can be translated mechanically to both Web-based and printable formats.
  • You as an author can concentrate on the content of your document, without worrying about how it will appear.

The Tech Computer Center supplies a locally-customized installation of the DocBook translation software for output to PDF or Web form. You can use our installation, or install and customize DocBook yourself (see the DocBook Modular Style Sheets web site).

However, this mechanical translation to various formats can be improved and tuned independently of the writing process. These improvements do not at all affect the DocBook files you write.

Note

This document assumes you are using DocBook-XML revision 4.3. If your document was done under the SGML versions, see Section 18, “Converting DocBook 3.0 documents” and Section 17, “Converting DocBook-SGML 4.1 documents” below.