From e19d4f2ddc642d15a6e5e1b24afc1f1890e034a0 Mon Sep 17 00:00:00 2001 From: rrt <unknown> Date: Mon, 17 Jan 2000 14:06:36 +0000 Subject: [PATCH] [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. --- docs/docbook-cheat-sheet.sgml | 144 ++++++++++++++++++++++++++++++++++ 1 file changed, 144 insertions(+) create mode 100644 docs/docbook-cheat-sheet.sgml diff --git a/docs/docbook-cheat-sheet.sgml b/docs/docbook-cheat-sheet.sgml new file mode 100644 index 000000000000..5462c115987e --- /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-{users,bugs}@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> +<!DOCTYPE Article PUBLIC "-//OASIS//DTD DocBook V3.1//EN"> +</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><IndexTerm><Primary>term</Primary></IndexTerm></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> -- GitLab