--- /dev/null
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<article id="docbook-cheat-sheet">
+
+ <articleinfo>
+ <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>
+ </articleinfo>
+
+ <sect1 id="sec-getting-docbook">
+ <title>Getting the DocBook tools</title>
+ <para>See the installation guide.</para>
+ </sect1>
+
+ <sect1 id="doc-layout">
+ <title>Document layout</title>
+
+ <para>The GHC documentation is written using DocBook XML V4.2, so
+ the first few lines should look like this:</para>
+
+<programlisting>
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+</programlisting>
+
+ <para>The encoding can of course be chosen according to taste.</para>
+
+ <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>However, by popular demand, here are some useful points:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Remember to use <sgmltag class="starttag">para</sgmltag>
+ inside <sgmltag class="starttag">listitem</sgmltag>s.</para>
+ </listitem>
+ </itemizedlist>
+
+ <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>Comments</term>
+ <listitem>
+ <para>Comments in SGML look like this: <sgmltag
+ class="sgmlcomment">This is a comment</sgmltag>.</para>
+ </listitem>
+ </varlistentry>
+
+ <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>
+
+ <sect1 id="docbook-tables">
+ <title>Tables</title>
+
+ <para>Tables are quite complicated to write in SGML (as in HTML,
+ there are lots of fiddly tags), so here's an example you can
+ cannibalise. In the spirit of the LaTeX short introduction I don't
+ repeat all the markup verbatim; you have to look at the source for
+ that.</para>
+
+ <informaltable>
+ <tgroup cols="3">
+ <colspec colname="one" align="left" colsep="0"/>
+ <colspec colname="two" align="center" colsep="0"/>
+ <colspec colname="three" align="right" colsep="0"/>
+ <tbody>
+
+ <row>
+ <entry>Here's</entry>
+ <entry>a sample</entry>
+ <entry>table</entry>
+ </row>
+
+ <row>
+ <entry>With differently</entry>
+ <entry>aligned</entry>
+ <entry>cells</entry>
+ </row>
+
+ <row>
+ <entry namest="one" nameend="three" morerows="1">
+ <para> There's not much else to it. Entries can span
+ both extra rows and extra columns; just be careful when
+ using block markup (such as <sgmltag
+ class="starttag">para</sgmltag>s) within an <sgmltag
+ class="starttag">entry</sgmltag> that there is no space
+ between the open and close <sgmltag
+ class="starttag">entry</sgmltag> tags and the adjacent
+ text, as otherwise you will suffer from <ulink
+ url="http://www.docbook.org/tdg/html/entry.html">Pernicious
+ Mixed Content</ulink> (the parser will think you're
+ using inline markup).</para>
+ </entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect1>
+</article>
projects / ghc-hetmet.git / blobdiff