1 <!DOCTYPE Article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
7 <Title>Using DocBook to write GHC documentation</Title>
8 <Author><OtherName>The GHC Team</OtherName></Author>
9 <Address><Email>glasgow-haskell-{users,bugs}@dcs.gla.ac.uk</Email></Address>
10 <PubDate>January 2000</PubDate>
15 <Sect1><Title>Getting the DocBook tools</Title>
18 See the building guide.
24 <Sect1><Title>Document layout</Title>
27 The GHC documentation is written using DocBook 3.1, so the DTD line should be:
31 <!DOCTYPE Article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
35 This guide is <Emphasis>not</Emphasis> meant to teach you how to write DocBook; read the <ULink URL="http://www.docbook.org/">DocBook book</ULink> for that. It is more of a reference than a tutorial, so see the <ULink URL="http://www.oasis-open.org/docbook/">DocBook home page</ULink> for other links.
39 The rest of this section outlines the use of several tags which may not be obvious (DocBook is rather scholastic in style: it has tags for many things from C function prototypes to keyboard bindings; at the same time it has many omissions and oddities). The current scheme has many infelicities, partly because it was dreamt up in a hurry while the author was learning DocBook and converting the documentation thereto, and partly because DocBook is rather C-centric.
44 <VarListEntry><Term><SGMLTag class="StartTag">Command</SGMLTag></Term>
47 Used for commands typed into interactive sessions (e.g. <Command>cp foo bar</Command> and the names of programs such as <Command>gmake</Command>.
52 <VarListEntry><Term><SGMLTag class="StartTag">Constant</SGMLTag></Term>
55 Used for system constants such as <Constant>U_MAXINT</Constant> and <Filename>Makefile</Filename> variables like <Constant>SRC_FILES</Constant> (because they are usually constant for a given run of <Command>make</Command>, and hence have a constant feel to them).
60 <VarListEntry><Term><SGMLTag class="StartTag">Email</SGMLTag></Term>
63 For email addresses. This is a tag that's easy to overlook if you don't know it's there.
68 <VarListEntry><Term><SGMLTag class="StartTag">Filename</SGMLTag></Term>
71 Used for paths, filenames, file extensions.
76 <VarListEntry><Term><SGMLTag class="StartTag">Function</SGMLTag></Term>
79 Used for functions and constructors.
84 <VarListEntry><Term><SGMLTag class="StartTag">IndexTerm</SGMLTag></Term>
87 The normal way to mark up an index term is <Literal><IndexTerm><Primary>term</Primary></IndexTerm></Literal>.
92 <VarListEntry><Term><SGMLTag class="StartTag">KeyCap</SGMLTag></Term><Term><SGMLTag class="StartTag">KeyCombo</SGMLTag></Term>
95 Some more tags you may miss. Used for combinations such as <KeyCombo><KeyCap>Control</KeyCap><KeyCap>D</KeyCap></KeyCombo>.
100 <VarListEntry><Term><SGMLTag class="StartTag">Literal</SGMLTag></Term>
103 Used for everything that should appear in typewriter font that has no other obvious tag: types, monads, small snippets of program text that are formatted inline, and the like.
108 <VarListEntry><Term><SGMLTag class="StartTag">Option</SGMLTag></Term>
111 Used for compiler options and similar.
116 <VarListEntry><Term><SGMLTag class="StartTag">ProgramListing</SGMLTag></Term>
119 For displayed program listings (including shell scripts).
124 <VarListEntry><Term><SGMLTag class="StartTag">Screen</SGMLTag></Term>
127 For displayed screen dumps, such as portions of shell interaction. It's easy to tell the difference between these and shell scripts: the latter lack a shell prompt.
132 <VarListEntry><Term><SGMLTag class="StartTag">VarName</SGMLTag></Term>
135 Used for variables, but not type variables.