[project @ 2000-01-17 14:06:36 by rrt]

Added how-to for GHC's use of DocBook. Just describes a few conventions for
particular tags at the moment.

diff --git a/docs/docbook-cheat-sheet.sgml b/docs/docbook-cheat-sheet.sgml
new file mode 100644 (file)
index 0000000..5462c11
--- /dev/null
+++ b/docs/docbook-cheat-sheet.sgml
@@ -0,0 +1,144 @@
+<!DOCTYPE Article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
+
+<Article>
+
+<ArtHeader>
+
+<Title>Using DocBook to write GHC documentation</Title>
+<Author><OtherName>The GHC Team</OtherName></Author>
+<Address><Email>glasgow-haskell-&lcub;users,bugs&rcub;@dcs.gla.ac.uk</Email></Address>
+<PubDate>January 2000</PubDate>
+
+</ArtHeader>
+
+
+<Sect1><Title>Getting the DocBook tools</Title>
+
+<Para>
+See the building guide.
+</Para>
+
+</Sect1>
+
+
+<Sect1><Title>Document layout</Title>
+
+<Para>
+The GHC documentation is written using DocBook 3.1, so the DTD line should be:
+</Para>
+
+<Screen>
+&lt;!DOCTYPE Article PUBLIC "-//OASIS//DTD DocBook V3.1//EN"&gt;
+</Screen>
+
+<Para>
+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.
+</Para>
+
+<Para>
+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.
+</Para>
+
+<VariableList>
+
+<VarListEntry><Term><SGMLTag class="StartTag">Command</SGMLTag></Term>
+<ListItem>
+<Para>
+Used for commands typed into interactive sessions (e.g. <Command>cp foo bar</Command> and the names of programs such as <Command>gmake</Command>.
+</Para>
+</ListItem>
+</VarListEntry>
+
+<VarListEntry><Term><SGMLTag class="StartTag">Constant</SGMLTag></Term>
+<ListItem>
+<Para>
+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).
+</Para>
+</ListItem>
+</VarListEntry>
+
+<VarListEntry><Term><SGMLTag class="StartTag">Email</SGMLTag></Term>
+<ListItem>
+<Para>
+For email addresses. This is a tag that's easy to overlook if you don't know it's there.
+</Para>
+</ListItem>
+</VarListEntry>
+
+<VarListEntry><Term><SGMLTag class="StartTag">Filename</SGMLTag></Term>
+<ListItem>
+<Para>
+Used for paths, filenames, file extensions.
+</Para>
+</ListItem>
+</VarListEntry>
+
+<VarListEntry><Term><SGMLTag class="StartTag">Function</SGMLTag></Term>
+<ListItem>
+<Para>
+Used for functions and constructors.
+</Para>
+</ListItem>
+</VarListEntry>
+
+<VarListEntry><Term><SGMLTag class="StartTag">IndexTerm</SGMLTag></Term>
+<ListItem>
+<Para>
+The normal way to mark up an index term is <Literal>&lt;IndexTerm&gt;&lt;Primary&gt;term&lt/Primary&gt;&lt;/IndexTerm&gt;</Literal>.
+</Para>
+</ListItem>
+</VarListEntry>
+
+<VarListEntry><Term><SGMLTag class="StartTag">KeyCap</SGMLTag></Term><Term><SGMLTag class="StartTag">KeyCombo</SGMLTag></Term>
+<ListItem>
+<Para>
+Some more tags you may miss. Used for combinations such as <KeyCombo><KeyCap>Control</KeyCap><KeyCap>D</KeyCap></KeyCombo>.
+</Para>
+</ListItem>
+</VarListEntry>
+
+<VarListEntry><Term><SGMLTag class="StartTag">Literal</SGMLTag></Term>
+<ListItem>
+<Para>
+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.
+</Para>
+</ListItem>
+</VarListEntry>
+
+<VarListEntry><Term><SGMLTag class="StartTag">Option</SGMLTag></Term>
+<ListItem>
+<Para>
+Used for compiler options and similar.
+</Para>
+</ListItem>
+</VarListEntry>
+
+<VarListEntry><Term><SGMLTag class="StartTag">ProgramListing</SGMLTag></Term>
+<ListItem>
+<Para>
+For displayed program listings (including shell scripts).
+</Para>
+</ListItem>
+</VarListEntry>
+
+<VarListEntry><Term><SGMLTag class="StartTag">Screen</SGMLTag></Term>
+<ListItem>
+<Para>
+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.
+</Para>
+</ListItem>
+</VarListEntry>
+
+<VarListEntry><Term><SGMLTag class="StartTag">VarName</SGMLTag></Term>
+<ListItem>
+<Para>
+Used for variables, but not type variables.
+</Para>
+</ListItem>
+</VarListEntry>
+
+</VariableList>
+
+</Sect1>
+
+</Article>