Writing Documentation Using DocBook
   Next

Writing Documentation Using DocBook

Using DocBook at CERN

Michel Goossens

CERN

work in progress

Copyright © 1997-2000, 2001-2002 David Rugge, Mark Galassi, Eric Bischoff, Michel Goossens

This document can be freely redistributed according to the terms of the GNU General Public License.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".

Revision History
Revision 0.02001-07-21[email protected]
Initial version, started from DocBook-Intro.xml written by Mark Galassi (Cygnus) and crash-course of David Rugge, Mark Galassi, Eric Bischoff
Revision 0.32002-03-05[email protected]
Start clean up source
Revision 0.42002-03-21[email protected]
First public release with many additions for CERN
Revision 0.52002-07-24[email protected]
Change to use version 4.2 of DocBook DTD throughout

Abstract

This document is a tutorial on how to write documentation in DocBook, and generate HTML and PDF from the XML sources. The description of the DTD elements is general in nature, whereas some tools and the location of system files relate to the CERN XML set-up.

This material is based in part on "A crash-course in DocBook", which was itself created from a fusion of three documents:

  • the "Introduction to DocBook" by Mark Galassi

  • the "KDE crash-course to DocBook" by David Rugge

  • parts of Eric Bischoff's tutorial about DocBook

I have freely adapted the above material to CERN, and have complemented it in many places. On the other hand, for reasons of maintainability, I have completely eliminated all references to SGML and DSSSL, since at CERN I only want to maintain the XSLT stylesheets to render DocBook source material.

Table of Contents

1. XML and DocBook
1.1. DocBook
1.2. A few words about XSLT
1.3. Presentation of the DocBook XML Tools installed at CERN
1.4. My First DocBook File
1.5. Translation to HTML
1.6. What about those Style Sheets?
1.7. Translation to PDF
1.8. Anatomy of a DocBook Tag
1.9. The Structure of a DocBook File
1.10. The Document Type Declaration
2. Meta Information
3. Lists
3.1. The simplelist
3.2. The itemizedlist
3.3. The orderedlist
3.4. The variablelist
3.5. The segmentedlist
3.6. qandaset
3.7. Procedures
4. Tables
4.1. A simple table
4.2. An informal table
4.3. A more complex table with some math
5. Graphics
6. Links
7. Describing the Application's Interface
7.1. Examples
7.2. GUI Interface Elements
7.3. Command Line Elements
7.4. Elements for classes and methods
7.5. Describing an API
8. Bibliograpy elements
8.1. Handling
9. Miscellaneous
9.1. Labelling Tags
9.2. Formatting Tags
9.3. Warnings, Tips, and Notes
10. If you want to know more
A. Emacs PSGML mode tips
B. A complete example of a DocBook article
Glossary
C. Overview of all DocBook elements
Index

List of Figures

1.1. PDF rendering of a small DocBook test file
8.1. Citations and bibliography (PDF output)
8.2. Citations and bibliography (Displayed by the Mozilla browser)
A.1. Emacs and its psgml mode with the DocBook DTD
B.1. DocBook example with MathML translated into PDF
B.2. DocBook example with MathML translated into HTML and viewed with Mozilla (one file)
B.3. DocBook example with MathML translated into HTML and viewed with Mozilla (chunked file)

List of Tables

4.1. Number of Visitors
4.2. Physical and mathematical constants

List of Examples

1.1. My first simple DocBook file
1.2. Running docbook2html (single output file)
1.3. HTML version generated from a DocBook file as displayed by lynx
1.4. Running docbook2html with the chunk option
1.5. A small DocBook file showing the use of attributes
1.6. Generating PDF with docbook2pdf
1.7. Chapters and sections
1.8. Entities used to share text
1.9. HTML version generated from a DocBook file as displayed by Lynx
1.10. Including external files using entities
2.1. DocBook metainformation
3.1. A simplelist
3.2. An itemizedlist
3.3. An orderedlist
3.4. A variablelist
3.5. A segmentedlist
3.6. A qandaset
3.7. A procedure list
4.1. A regular simple table
4.2. A simple informal table (no title)
4.3. A more complex table
5.1. An inline media object
5.2. A screenshot
6.1. Five kinds of links
7.1. An example
7.2. A BASIC Example
7.3. Displaying markup in a CDATA section
7.4. CDATA sections and markup
7.5. guimenu and shortcut
7.6. A command and its output
7.7. A commandsynopsis
7.8. Class synopsys
7.9. Describing a function in a C library API
8.1. Example of A bibliography and citations
   Next
   Chapter 1. XML and DocBook