19. Care and feeding of your GHC User’s Guide

The GHC User’s Guide is the primary reference documentation for the Glasgow Haskell Compiler. Even more than this, it at times serves (for better or for worse) as a de-facto language standard, being the sole non-academic reference for many widely used language extensions.

Since GHC 8.0, the User’s Guide is authored in ReStructuredText (or ReST or RST, for short) a rich but light-weight mark-up language aimed at producing documentation. The Sphinx tool is used to produce the final PDF and HTML documentation.

This document (also written in ReST) serves as a brief introducion to ReST and to document the conventions used in the User’s Guide. This document is not intended to be a thorough guide to ReST. For this see the resources referenced below.

19.1. Basics

Unicode characters are allowed in the document.

The basic syntax works largely as one would expect. For instance,

This is a paragraph containing a few sentences of text. Purple turtles walk
through green fields of lofty maize. Lorem ipsum dolor sit amet, consectetur
adipiscing elit. Some lists,

1. This is a list item

   a. Followed by a sub-item
   b. And another!
   c. Now with ``a bit of code`` and some *emphasis*.

2. Back to the first list

Or perhaps you are more of a bullet list person,

* Foo
* Fizzle

  - Bar
  - Blah

Or perhaps a definition list is in order,

*Chelonii*
    The taxonomic order consisting of modern turtles
*Meiolaniidae*
    The taxonomic order of an extinct variety of herbivorous turtles.

Note the blank lines between a list item and its sub-items. Sub-items should be on the same indentation level as the content of their parent items. Also note that no whitespace is necessary or desirable before the bullet or item number (lest the list be indented unnecessarily).

The above would be rendered as,

This is a paragraph containing a few sentences of text. Purple turtles walk through green fields of lofty maize. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Some lists,

  1. This is a list item
    1. Followed by a sub-item
    2. And another!
    3. Now with a bit of code and some emphasis.
  2. Back to the first list

Or perhaps you are more of a bullet list person,

  • Foo
  • Fizzle
    • Bar
    • Blah

Or perhaps a definition list is in order,

Chelonii
The taxonomic order consisting of modern turtles
Meiolaniidae
The taxonomic order of an extinct variety of herbivorous turtles.

19.1.1. Headings

While ReST can accommodate a wide range of heading styles, we have standardized on this convention in the User’s Guide,

Header level 1
==============

Header level 2
--------------

Header level 3
~~~~~~~~~~~~~~

Header level 4
^^^^^^^^^^^^^^

19.1.2. Formatting code

19.1.2.1. Haskell

Code snippets can be included as both inline and block elements. Inline code is denoted with double-backticks whereas block of code are introduced by ending a paragraph with double-colons and indentation,

The ``fib`` function is defined as, ::

    fib :: Integer -> Integer
    fib 1 = 1
    fib n = n * fib (n - 1)

Which would be rendered as,

The fib function is defined as,

fib :: Integer -> Integer
fib 1 = 1
fib n = n * fib (n - 1)

19.1.2.2. Other languages

Double-colon blocks are syntax-highlighted as Haskell by default. To avoid this use a .. code-block directive with explicit language designation,

This is a simple shell script,

.. code-block:: sh

    #!/bin/bash
    echo "Hello World!"

19.1.4. Index entries

Index entries can be included anywhere in the document as a block element. They look like,

Here is some discussion on the Strict Haskell extension.

.. index::
    single: strict haskell
    single: language extensions; StrictData

This would produce two entries in the index referring to the “Strict Haskell” section. One would be a simple “strict haskell” heading whereas the other would be a “StrictData” subheading under “language extensions”.

Sadly it is not possible to use inline elements (e.g. monotype inlines) inside index headings.

19.2. Citations

Citations can be marked-up like this,

See the original paper [Doe2008]_

.. [Doe2008] John Doe and Leslie Conway.
             "This is the title of our paper" (2008)

19.3. Admonitions

Admonitions are block elements used to draw the readers attention to a point. They should not be over-used for the sake of readability but they can be quite effective in separating and drawing attention to points of importance,

.. important::

    Be friendly and supportive to your fellow contributors.

Would be rendered as,

Important

Be friendly and supportive to your fellow contributors.

There are a number of admonitions types,

  • attention
  • caution
  • danger
  • error
  • hint
  • important
  • note
  • tip
  • warning

19.4. Documenting command-line options and GHCi commands

conf.py defines a few Sphinx object types for GHCi commands (ghci-cmd), ghc command-line options (ghc-flag), and runtime :system options (rts-flag),

19.4.1. Command-line options

The ghc-flag and rts-flag roles/directives can be used to document command-line arguments to the ghc executable and runtime system, respectively. For instance,

.. rts-flag:: -C ⟨seconds⟩

   :since: 8.2
   :default: 20 milliseconds

   Sets the context switch interval to ⟨s⟩ seconds.

Will be rendered as,

-C ⟨seconds⟩
Since:8.2
Default:20 milliseconds

Sets the context switch interval to ⟨s⟩ seconds.

and will have an associated index entry generated automatically.

The ghc-flag directive requires a few extra parameters to be passed. This extra information is used to generate the Flag reference and the man page. A ghc-flag directive looks like this,

.. ghc-flag:: -fasm
    :shortdesc: Use the native code generator
    :type: dynamic
    :reverse: -fllvm
    :category: codegen

    Regular description...

When rendered, the extra parameters will be hidden, and the data stored for later use. For more details, see the Sphinx extension flags.py.

Note that, as in Style Conventions below, we use ⟨⟩ instead of less-than/greater-than signs. To reference a ghc-flag or rts-flag, you must match the definition exactly, including the arguments. A quick way to find the exact names and special characters is,

$ git grep -- "flag:: -o "

which will generate the appropriate,

separate_compilation.rst:.. ghc-flag:: -o ⟨file⟩

19.4.2. GHCi commands

The ghci-cmd role and directive can be used to document GHCi directives. For instance, we can describe the GHCi :module command,

.. ghci-cmd:: :module; [*]⟨file⟩

    Load a module

which will be rendered as,

:module [*]⟨file⟩

Load a module

And later refer to it by just the command name, :module,

The GHCi :ghci-cmd:`:load` and :ghci-cmd:`:module` commands are used
to modify the modules in scope.

Like command-line options, GHCi commands will have associated index entries generated automatically.

19.5. Style Conventions

When describing user commands and the like it is common to need to denote user-substitutable tokens. In this document we use the convention, ⟨subst⟩ (note that these are angle brackets, U+27E8 and U+27E9, not less-than/greater-than signs).

19.6. ReST reference materials