Writing Documentation Using DocBook A Crash Course David Rugge [email protected] Mark Galassi [email protected] Éric Bischoff [email protected] Writing Documentation Using DocBook: A Crash Course by David Rugge, Mark Galassi, and Éric Bischoff Copyright © 1997-2006 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.1. About this Booklet ............................................................................................................... 1 1.2. Why DocBook?.................................................................................................................... 2 1.3. Your World View.................................................................................................................. 3 1.4. Markup based on content ..................................................................................................... 4 2. Getting started ................................................................................................................................ 5 2.1. Presentation of the Tools...................................................................................................... 5 2.2. The Old Way: the DocBook-tools........................................................................................ 5 2.3. The New Way: XSLTProc and FOP..................................................................................... 7 2.4. My First DocBook File ........................................................................................................ 8 2.5. Introducing the Style Sheets ................................................................................................ 9 3. Basic notions..................................................................................................................................11 3.1. Anatomy of a DocBook Tag ..............................................................................................11 3.2. The Structure of a DocBook File .......................................................................................11 4. The Document Type Declaration.................................................................................................14 4.1. Using Entities for Shared Text ...........................................................................................14 4.2. Using Entities to Include Other files ..................................................................................15 4.3. Identifying files with formal public IDs.............................................................................15 4.4. Using Marked Sections to Handle Conditional Content....................................................17 5. Meta Information..........................................................................................................................19 6. Lists ................................................................................................................................................21 6.1. The simplelist.....................................................................................................................21 6.2. The itemizedlist..................................................................................................................22 6.3. The orderedlist ...................................................................................................................22 6.4. The variablelist...................................................................................................................23 6.5. The segmentedlist...............................................................................................................24 6.6. qandaset..............................................................................................................................25 6.7. Procedures..........................................................................................................................25 7. Tables .............................................................................................................................................27 8. Graphics.........................................................................................................................................29 9. Links...............................................................................................................................................32 10. Describing the Application’s Interface .....................................................................................33 10.1. Examples..........................................................................................................................33 10.2. GUI Interface Elements....................................................................................................34 10.3. Command Line Elements.................................................................................................36 10.4. Describing an API............................................................................................................38 11. Miscellaneous Useful Tags..........................................................................................................40 11.1. Labelling Tags..................................................................................................................40 11.2. Formatting Tags................................................................................................................40 11.3. Warnings, Tips, and Notes ...............................................................................................40 12. Where to Go Next .......................................................................................................................41 12.1. DocBook Resources.........................................................................................................41 A. Licence ..........................................................................................................................................42 A.1. Free Documentation Licence ............................................................................................42 iii B. Emacs PSGML mode tips............................................................................................................50 Glossary .............................................................................................................................................52 iv List of Tables 7-1. Mouse Mileage............................................................................................................................28 v Chapter 1. Introduction 1.1. About this Booklet This booklet was meant as a tutorial that can give you an introduction on how to use all the power and effectiveness of DocBook. It aims at getting you introduced to this matter in the shortest delay, hence then name of "Crash-course to DocBook". Even if you have never used either DocBook or other markup languages (like LinuxDoc) before, you should be able to become proficient in it just by reading through this guide and using the online (http://www.oasis-open.org/docbook/documentation/reference/html/docbook.html) or the paper (http://www.oreilly.com/catalog/docbook/index.html) version of [DocBook - The Definitive Guide] published by O’Reilly & Associates. Note: Please note that this crash course is designed to be used along with, not instead of, the DocBook Reference. There are a number of cases where it is much easier to refer to the reference rather than trying to rehash what it already covers. Use this guide to understand what DocBook is about and to have a general overview on how to use those tags. This tutorial will teach you enough DocBook to write basic documentation. You will learn: • What DocBook is about • How to get the DocBook-Tools up and running • The format of a DocBook tag • How to structure your documents properly • How to use lists and tables to organize data • How to describe GUI elements and Unix Commands • How to include graphics in your documentation • How to link to URL’s and create cross-references In appendix, one can find a short description of the Emacs psgml mode. This material comes from the 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 Many parts of this document were borrowed from the "DocBook 3.0 Reference" by Eve Maler of ArborText, Inc. and Terry Allen of Fujitsu Software Corporation. The parts of this document that 1 Chapter 1. Introduction were borrowed from the Reference are Copyright © 1992, 1993, 1994, 1995, 1996, 1997 by HaL Computer Systems, Inc., O’Reilly & Associates, Inc., Fujitsu Software Corporation, and ArborText, Inc. 1.2. Why DocBook? The DocBook format was designed by OASIS consortium specifically for technical documentation. It provides a rich set of tags to describe the content of