Writing Documentation Using DocBook A Crash Course David Rugge [email protected] Mark Galassi [email protected] Eric Bischoff [email protected] Writing Documentation Using DocBook: A Crash Course by David Rugge, Mark Galassi, and Eric Bischoff Copyright © 1997-2002 by David Rugge, Mark Galassi, Eric Bischoff This document is a first tutorial on how to write documentation in DocBook using the Docbook-Tools distribution. 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.....................................................................................................................................9 1.1. About this Booklet ...............................................................................................................9 1.2. Why DocBook?..................................................................................................................10 1.3. Your World View................................................................................................................11 1.4. Markup based on content ...................................................................................................12 2. Getting started ..............................................................................................................................15 2.1. Presentation of the DocBook-Tools ...................................................................................15 2.2. Installing the DocBook-Tools ............................................................................................15 2.3. My First DocBook File ......................................................................................................17 2.4. Introducing the Style Sheets ..............................................................................................18 2.5. Other conversion utilities ...................................................................................................19 3. Basic notions..................................................................................................................................21 3.1. Anatomy of a DocBook Tag ..............................................................................................21 3.2. The Structure of a DocBook File .......................................................................................21 4. The Document Type Declaration.................................................................................................25 4.1. Using Entities for Shared Text ...........................................................................................25 4.2. Using Entities to Include Other files ..................................................................................26 4.3. Identifying files with formal public IDs.............................................................................27 4.4. Using Marked Sections to Handle Conditional Content....................................................28 5. Meta Information..........................................................................................................................31 6. Lists ................................................................................................................................................33 6.1. The simplelist.....................................................................................................................33 6.2. The itemizedlist..................................................................................................................34 6.3. The orderedlist ...................................................................................................................34 6.4. The variablelist...................................................................................................................35 6.5. The segmentedlist...............................................................................................................36 6.6. qandaset..............................................................................................................................37 6.7. Procedures..........................................................................................................................38 7. Tables .............................................................................................................................................41 8. Graphics.........................................................................................................................................45 9. Links...............................................................................................................................................47 10. Describing the Application’s Interface .....................................................................................49 10.1. Examples..........................................................................................................................49 10.2. GUI Interface Elements....................................................................................................50 10.3. Command Line Elements.................................................................................................53 10.4. Describing an API............................................................................................................55 11. Miscellaneous Useful Tags..........................................................................................................57 11.1. Labelling Tags..................................................................................................................57 11.2. Formatting Tags................................................................................................................57 5 11.3. Warnings, Tips, and Notes ...............................................................................................57 12. Where to Go Next .......................................................................................................................59 12.1. DocBook and SGML Resources ......................................................................................59 A. Licence ..........................................................................................................................................61 A.1. Free Documentation Licence ............................................................................................61 B. Emacs PSGML mode tips............................................................................................................71 Glossary .............................................................................................................................................73 6 List of Tables 7-1. Mouse Mileage............................................................................................................................42 List of Examples 2-1. A minimal DocBook file .............................................................................................................17 2-2. The minimal DocBook file, with some attributes........................................................................18 3-1. Chapters and sections ..................................................................................................................22 4-1. Entities used to share text............................................................................................................25 4-2. Entities used to include other files...............................................................................................26 5-1. DocBook metainformation..........................................................................................................31 6-1. A simplelist..................................................................................................................................33 6-2. An itemizedlist ............................................................................................................................34 6-3. An orderedlist..............................................................................................................................35 6-4. A variablelist ...............................................................................................................................35 6-5. A segmentedlist ...........................................................................................................................36 6-6. A qandaset ...................................................................................................................................37 6-7. A procedure list ...........................................................................................................................38 7-1. A table .........................................................................................................................................41 8-1. An inline media object ................................................................................................................45 8-2. A screenshot ................................................................................................................................45