From: rrt Date: Mon, 17 Jan 2000 14:06:36 +0000 (+0000) Subject: [project @ 2000-01-17 14:06:36 by rrt] X-Git-Tag: Approximately_9120_patches~5274 X-Git-Url: http://git.megacz.com/?a=commitdiff_plain;h=e19d4f2ddc642d15a6e5e1b24afc1f1890e034a0;p=ghc-hetmet.git [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 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. + + + + + + + + +