From e19d4f2ddc642d15a6e5e1b24afc1f1890e034a0 Mon Sep 17 00:00:00 2001 From: rrt 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 0000000..5462c11 --- /dev/null +++ b/docs/docbook-cheat-sheet.sgml @@ -0,0 +1,144 @@ + + +
+ + + +Using DocBook to write GHC documentation +The GHC Team +
glasgow-haskell-{users,bugs}@dcs.gla.ac.uk
+January 2000 + + + + +Getting the DocBook tools + + +See the building guide. + + + + + +Document layout + + +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. + + + +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. + + + + +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>. + + + + +KeyCapKeyCombo + + +Some more tags you may miss. Used for combinations such as ControlD. + + + + +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. + + + + + + + + +
-- 1.7.10.4