The Crash Course to DocBook

Writing Documentation Using DocBook

A Crash Course

David Rugge

Mark Galassi

Éric Bischoff

This document is a first tutorial on how to write documentation in DocBook.

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".

Table of Contents
1. Introduction
1.1. About this Booklet
1.2. Why DocBook?
1.3. Your World View
1.4. Markup based on content
2. Getting started
2.1. Presentation of the Tools
2.2. The Old Way: the DocBook-tools
2.3. The New Way: XSLTProc and FOP
2.4. My First DocBook File
2.5. Introducing the Style Sheets
3. Basic notions
3.1. Anatomy of a DocBook Tag
3.2. The Structure of a DocBook File
4. The Document Type Declaration
4.1. Using Entities for Shared Text
4.2. Using Entities to Include Other files
4.3. Identifying files with formal public IDs
4.4. Using Marked Sections to Handle Conditional Content
5. Meta Information
6. Lists
6.1. The simplelist
6.2. The itemizedlist
6.3. The orderedlist
6.4. The variablelist
6.5. The segmentedlist
6.6. qandaset
6.7. Procedures
7. Tables
8. Graphics
9. Links
10. Describing the Application's Interface
10.1. Examples
10.2. GUI Interface Elements
10.3. Command Line Elements
10.4. Describing an API
11. Miscellaneous Useful Tags
11.1. Labelling Tags
11.2. Formatting Tags
11.3. Warnings, Tips, and Notes
12. Where to Go Next
12.1. DocBook Resources
A. Licence
A.1. Free Documentation Licence
B. Emacs PSGML mode tips
List of Tables
7-1. Mouse Mileage
List of Examples
2-1. A minimal DocBook file
2-2. The minimal DocBook file, with some attributes
3-1. Chapters and sections
4-1. Entities used to share text
4-2. Entities used to include other files
5-1. DocBook metainformation
6-1. A simplelist
6-2. An itemizedlist
6-3. An orderedlist
6-4. A variablelist
6-5. A segmentedlist
6-6. A qandaset
6-7. A procedure list
7-1. A table
8-1. An inline media object
8-2. A screenshot
9-1. Many kinds of links
10-1. An example
10-2. A programlisting
10-3. CDATA usage
10-4. Some markup
10-5. guimenu and shortcut
10-6. A command and its output
10-7. A commandsynopsis
10-8. Describing a function in a C library API