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. Relevant online files
3. Setting up your directory for DocBook
4. Creating and translating your document
4.1. What is DocBook and how does it relate to XML?
4.2. The DocBook workflow cycle
5. Overall section structure
5.1. The titleabbrev element: Short title
6. Ordinary prose paragraphs: simpara and para
7. Inline markup
8. Links: connecting your document to itself and elsewhere
8.1. The link and xref tags: Linking within your document
8.2. The ulink tag: Linking to a Web page
9. Special paragraph shapes
9.1. Bullet lists: itemizedlist
9.2. Numbered lists: The orderedlist element
9.3. Procedures
9.4. Question-and-answer sets
9.5. Definition lists: variablelist
9.6. Notes, warnings, cautions, etc.
9.7. Block quotations
10. Verbatim displays
10.1. Callouts in verbatim displays
10.2. Poetry
11. Including graphic images
11.1. Formal and informal figures
11.2. Tuning graphics for different roles
11.3. Scaling a figure
11.4. Inline graphics
11.5. How to get screen shots (Windows, MacOS, and Linux)
12. Tables
12.1. Ruled lines in tables
12.2. Controlling table dimensions
12.3. Controlling alignment in tables
12.4. Horizontal (column) spanning in tables
12.5. Vertical (row) spanning in tables
13. Including TeX and LaTeX math
13.1. Preparing a formula with LaTeX
13.2. Preparing a formula with TeX
13.3. Processing your math files for inclusion
13.4. Automating math display production with your Makefile
13.5. Simple inline math
13.6. Inline math using LaTeX or TeX
14. User-defined entities
15. Breaking your document into multiple files
16. Decluttering the project directory
17. Literate programming with DocBook
17.1. Controlling spurious blanks and blank lines
18. Special characters
18.1. Universally available entities
18.2. International character entities
18.3. The Greek alphabet
18.4. Special symbols
19. Model files for make
19.1. make-basic: A basic Makefile
19.2. make-lit: A Makefile for literate programming
19.3. make-large: A Makefile for large projects
20. FOP: An older, free toolchain
20.1. FOP limitations
20.2. Bad page breaks
20.3. Using tables inside <listitem>
20.4. Graphics file support
21. Converting DocBook-SGML 4.1 documents
22. 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.

The 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 22, “Converting DocBook 3.0 documents” and Section 21, “Converting DocBook-SGML 4.1 documents” below.