Get Going With DocBook Notes for Hackers Mark Galassi Cygnus Solutions Get Going With DocBook: Notes for Hackers by Mark Galassi Copyright © 1998 by Mark Galassi This document can be freely redistributed according to the terms of the GNU General Public License. Revision History Revision 0.01997-10-11Revised by: [email protected] Initial revision; mostly just an outline Revision 0.11997-11-01Revised by: [email protected] Firmed up the outline, based on the evolution of Cygnus’s DocBook effort Revision 0.21997-11-09Revised by: [email protected] Have enough meat in there that I have announced it. Revision 0.31997-12-31Revised by: [email protected] Separated the tutorial (this document) from the style guide for my project at Cygnus. This tutorial can now be distributed on its own. Revision 0.41998-02-14Revised by: [email protected] Added some blurbs on descriptions and made the first web release of this document. Revision 0.51998-06-12Revised by: [email protected] Added Sara Mitchell’s brief essay on SGML marked sections as its own chapter. Revision 0.61998-10-19Revised by: [email protected] Mentioned that this document is GPLed, did a bit of cleanup, and added mention of my FrameMaker+SGML EDD. Table of Contents 1. What is this?......................................................................................................... -999 1.1. A tutorial for hacker–writers ...................................................................... -999 1.2. An example of how to use DocBook structure........................................... -999 1.3. Not an example for all situations ................................................................ -999 2. Get going............................................................................................................... -999 2.1. Hello, world ................................................................................................ -999 2.2. A slightly more complex example.............................................................. -999 2.3. From here on............................................................................................... -999 3. A tour of some DocBook features....................................................................... -999 3.1. Global markups........................................................................................... -999 3.1.1. Books ............................................................................................... -999 3.1.2. Articles............................................................................................. -999 3.2. Examples and screen snapshots.................................................................. -999 3.2.1. Examples involving plain text ......................................................... -999 3.2.2. Describing GUIs .............................................................................. -999 3.2.3. Code samples................................................................................... -999 3.3. Describing an API ...................................................................................... -999 3.4. Tables.......................................................................................................... -999 3.5. Reference things ......................................................................................... -999 4. Concepts ............................................................................................................... -999 4.1. Your world view.......................................................................................... -999 4.2. Markup based on content............................................................................ -999 4.3. Explanation of SGML–related terms.......................................................... -999 4.3.1. SGML — a framework for defining markup languages.................. -999 4.3.2. What about the appearnace on output media? ................................. -999 5. How you should structure your documents....................................................... -999 5.1. Structure of a book ..................................................................................... -999 5.2. Structure of a chapter.................................................................................. -999 5.3. Structure of sections ................................................................................... -999 6. DocBook Resources ............................................................................................. -999 3 7. SGML entities ...................................................................................................... -999 7.1. BASIC STRUCTURE OF AN SGML DOCUMENT................................ -999 7.2. USING ENTITIES TO CONNECT OTHER FILES.................................. -999 7.3. IDENTIFYING FILES WITH FORMAL PUBLIC IDS ........................... -999 7.4. USING ENTITIES FOR SHARED TEXT ................................................ -999 7.5. USING MARKED SECTIONS TO HANDLE CONDITIONAL CONTENT -999 8. Emacs PSGML mode tips ................................................................................... -999 A. Obtaining and installing DocBook tools ........................................................... -999 A.1. UNIX ......................................................................................................... -999 A.2. Win32......................................................................................................... -999 A.3. FrameMaker+SGML ................................................................................. -999 Glossary .................................................................................................................... -999 4 List of Tables 3-1. Convergence of dynamical equations and constraints for various choices of constrained edges............................................................................................... -999 List of Examples 2-1. Bare bones DocBook document — the source................................................... -999 2-2. Fleshier DocBook document — the source........................................................ -999 3-1. Documenting a typical ftp session ..................................................................... -999 3-2. Program listings in DocBook ............................................................................. -999 3-3. A simple C program ........................................................................................... -999 3-4. Describing a function in a C library API............................................................ -999 3-5. A simple informal table (no title)....................................................................... -999 3-6. A more complex table ........................................................................................ -999 5 Chapter 1. What is this? 1.1. A tutorial for hacker–writers This booklet has two main goals: The first is present a tutorial on writing documentation that will be used in a particular project at Cygnus. The second is for me to clarify my thoughts on how I think the books we ship with should be structured. A third goal, which is not as pressing, is that this booklet should become a tutorial for all people at Cygnus (and elsewhere; the GNOME project, for example is using DocBook) who will be writing notes for future incorporation into Cygnus documentation. If you just want the tutorial with no further background information, please jump right to Chapter 2. 1.2. An example of how to use DocBook structure This booklet is a valid demonstration of how to use DocBook elements for writing Cygnus documentation. As the Cygnus tag team refines the Cygnus style and typical tag usage, this document will be updated to reflect that style and usage. Whenever I mention Cygnus, please note that the Cygnus stylesheets and all the tools we use are being made available to the world at large, so projects outside of Cygnus can also use these stylesheets, our tools, and this tutorial. If you are a hacker working on a project and you need to write an essay, or if you would like to document your portion of the project, you can use this booklet as an example of 6 Chapter 1. What is this? how to structure your document and what DocBook elements you should use to mark up your text. 1.3. Not an example for all situations This booklet is a tutorial written in quasi–slapstick style — I use the words I and you liberally. You should not treat it as an example of how to write a reference manual, or as an example of how to write a more stuffy tutorial. 7 Chapter 2. Get going Here is a brutal sequence of steps that will get you started writing DocBook documents. If you actually want to understand what is going on, you might want to read Chapter 4 first and then come back to this chapter. This chapter will not tell you how to get the tools installed — it is assumed that your system administrator has done that for you. If she or he has not done so, there is an appendix that gives instructions to get DocBook editing and processing tools. There are sections for Section A.1 (with free tools), Section A.2 (with free tools) and Section A.3. 2.1. Hello, world Here’s a simple DocBook document to get going. I will show you how to write this document using explicit element tags, but if you are using an authoring tool that provides a high level interface, just choose the same tags using that interface. Example 2-1. Bare bones DocBook document — the source <!doctype book PUBLIC