The GHC documentation is written using DocBook 3.1, so the DTD line should be:
<!DOCTYPE Article PUBLIC "-//OASIS//DTD DocBook V3.1//EN"> |
This guide is not meant to teach you how to write DocBook; read the DocBook book for that. It is more of a reference than a tutorial, so see the DocBook home page for other links.
However, by popular demand, here are some useful points:
Remember to use <Para>
inside
<ListItem>
s.
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.
Comments in SGML look like this: <!--This is a
comment-->
.
<Command>
Used for commands typed into interactive sessions (e.g. cp foo bar and the names of programs such as gmake.
<Constant>
Used for system constants such as U_MAXINT
and Makefile variables like SRC_FILES
(because they are usually constant for a given run of make, and hence have a constant feel to them).
<Email>
For email addresses. This is a tag that's easy to overlook if you don't know it's there.
<Filename>
Used for paths, filenames, file extensions.
<Function>
Used for functions and constructors.
<IndexTerm>
The normal way to mark up an index term is <IndexTerm><Primary>term</Primary></IndexTerm>.
<KeyCap>
, <KeyCombo>
Some more tags you may miss. Used for combinations such as Control-D.
<Literal>
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.
<Option>
Used for compiler options and similar.
<ProgramListing>
For displayed program listings (including shell scripts).
<Screen>
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.
<VarName>
Used for variables, but not type variables.