docs/docbook-cheat-sheet.sgml

   1 <!DOCTYPE Article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
   2
   3 <Article>
   4
   5 <ArtHeader>
   6
   7 <Title>Using DocBook to write GHC documentation</Title>
   8 <Author><OtherName>The GHC Team</OtherName></Author>
   9 <Address><Email>glasgow-haskell-&lcub;users,bugs&rcub;@dcs.gla.ac.uk</Email></Address>
  10 <PubDate>January 2000</PubDate>
  11
  12 </ArtHeader>
  13
  14
  15 <Sect1><Title>Getting the DocBook tools</Title>
  16
  17 <Para>
  18 See the building guide.
  19 </Para>
  20
  21 </Sect1>
  22
  23
  24 <Sect1><Title>Document layout</Title>
  25
  26 <Para>
  27 The GHC documentation is written using DocBook 3.1, so the DTD line should be:
  28 </Para>
  29
  30 <Screen>
  31 &lt;!DOCTYPE Article PUBLIC "-//OASIS//DTD DocBook V3.1//EN"&gt;
  32 </Screen>
  33
  34 <Para>
  35 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.
  36 </Para>
  37
  38 <Para>
  39 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.
  40 </Para>
  41
  42 <VariableList>
  43
  44 <VarListEntry><Term><SGMLTag class="StartTag">Command</SGMLTag></Term>
  45 <ListItem>
  46 <Para>
  47 Used for commands typed into interactive sessions (e.g. <Command>cp foo bar</Command> and the names of programs such as <Command>gmake</Command>.
  48 </Para>
  49 </ListItem>
  50 </VarListEntry>
  51
  52 <VarListEntry><Term><SGMLTag class="StartTag">Constant</SGMLTag></Term>
  53 <ListItem>
  54 <Para>
  55 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).
  56 </Para>
  57 </ListItem>
  58 </VarListEntry>
  59
  60 <VarListEntry><Term><SGMLTag class="StartTag">Email</SGMLTag></Term>
  61 <ListItem>
  62 <Para>
  63 For email addresses. This is a tag that's easy to overlook if you don't know it's there.
  64 </Para>
  65 </ListItem>
  66 </VarListEntry>
  67
  68 <VarListEntry><Term><SGMLTag class="StartTag">Filename</SGMLTag></Term>
  69 <ListItem>
  70 <Para>
  71 Used for paths, filenames, file extensions.
  72 </Para>
  73 </ListItem>
  74 </VarListEntry>
  75
  76 <VarListEntry><Term><SGMLTag class="StartTag">Function</SGMLTag></Term>
  77 <ListItem>
  78 <Para>
  79 Used for functions and constructors.
  80 </Para>
  81 </ListItem>
  82 </VarListEntry>
  83
  84 <VarListEntry><Term><SGMLTag class="StartTag">IndexTerm</SGMLTag></Term>
  85 <ListItem>
  86 <Para>
  87 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>.
  88 </Para>
  89 </ListItem>
  90 </VarListEntry>
  91
  92 <VarListEntry><Term><SGMLTag class="StartTag">KeyCap</SGMLTag></Term><Term><SGMLTag class="StartTag">KeyCombo</SGMLTag></Term>
  93 <ListItem>
  94 <Para>
  95 Some more tags you may miss. Used for combinations such as <KeyCombo><KeyCap>Control</KeyCap><KeyCap>D</KeyCap></KeyCombo>.
  96 </Para>
  97 </ListItem>
  98 </VarListEntry>
  99
 100 <VarListEntry><Term><SGMLTag class="StartTag">Literal</SGMLTag></Term>
 101 <ListItem>
 102 <Para>
 103 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.
 104 </Para>
 105 </ListItem>
 106 </VarListEntry>
 107
 108 <VarListEntry><Term><SGMLTag class="StartTag">Option</SGMLTag></Term>
 109 <ListItem>
 110 <Para>
 111 Used for compiler options and similar.
 112 </Para>
 113 </ListItem>
 114 </VarListEntry>
 115
 116 <VarListEntry><Term><SGMLTag class="StartTag">ProgramListing</SGMLTag></Term>
 117 <ListItem>
 118 <Para>
 119 For displayed program listings (including shell scripts).
 120 </Para>
 121 </ListItem>
 122 </VarListEntry>
 123
 124 <VarListEntry><Term><SGMLTag class="StartTag">Screen</SGMLTag></Term>
 125 <ListItem>
 126 <Para>
 127 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.
 128 </Para>
 129 </ListItem>
 130 </VarListEntry>
 131
 132 <VarListEntry><Term><SGMLTag class="StartTag">VarName</SGMLTag></Term>
 133 <ListItem>
 134 <Para>
 135 Used for variables, but not type variables.
 136 </Para>
 137 </ListItem>
 138 </VarListEntry>
 139
 140 </VariableList>
 141
 142 </Sect1>
 143
 144 </Article>