18. Care and feeding of your GHC User’s Guide — Glasgow Haskell Compiler 8.4.0.20180224 User's Guide

# Glasgow Haskell Compiler User's Guide

### Navigation

- index
- previous |
- GHC 8.4.0.20180224 User's Guide »

# 18. 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.

## 18.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.

### 18.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
    ^^^^^^^^^^^^^^

### 18.1.2. Formatting code

#### 18.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)

#### 18.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!"

### 18.1.3. Links

#### 18.1.3.1. Within the User’s Guide

Frequently we want to give a name to a section so it can be referred to from other points in the document,

    .. _options-platform:

    Platform-specific Flags
    -----------------------

    There are lots of platform-specific flags.

    Some other section
    -------------------

    GHC supports a variety of :ref:`x86 specific features <options-platform>`.

    See :ref:`options-platform` for details.

#### 18.1.3.2. To GHC Trac resources

There are special macros for conveniently linking to GHC Trac Wiki articles and tickets,

    See :ghc-wiki:`Commentary/Latedmd` for details on demand analysis.

    See the :ghc-wiki:`coding style <Commentary/CodingStyle>` for guidelines.

    See the :ghc-ticket:`123` for further discussion.

    See the :ghc-ticket:`this bug <123>` for what happens when this fails.

#### 18.1.3.3. To external resources

External links can be written in either of these ways,

    See the `GHC Wiki <http://ghc.haskell.org/wiki>`_ for details.

    See the `GHC Wiki`_ for details.

    .. _GHC Wiki: http://ghc.haskell.org/wiki

#### 18.1.3.4. To core library Haddock documentation

It is often useful to be able to refer to the Haddock documention of the libraries shipped with GHC. The users guide’s build system provides commands for referring to documentation for the following core GHC packages,

- `base`: `:base-ref:`
- `cabal`: `:cabal-ref:`
- `ghc-prim`: `:ghc-prim-ref:`

These are defined in `docs/users_guide/ghc_config.py.in`.

For instance,

    See the documentation for :base-ref:`Control.Applicative <Control-Applicative.html>`
    for details.

#### 18.1.3.5. Math

You can insert type-set equations using `:math:`. For instance,

    Fick's law of diffusion, :math:`J = -D \frac{d \varphi}{d x}`, ...

will render as,

> Fick’s law of diffusion, \(J = -D \frac{d \varphi}{d x}\), ...

### 18.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.

## 18.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)

## 18.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

## 18.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`),

### 18.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⟩

       :default: 20 milliseconds

       Sets the context switch interval to ⟨s⟩ seconds.

Will be rendered as,

> `-C``⟨seconds⟩`

>   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⟩

### 18.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.

## 18.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).

## 18.6. ReST reference materials

- Sphinx ReST Primer: A great place to start.
- Sphinx extensions: How Sphinx extends ReST
- ReST reference: When you really need the details.
- Directives reference

### Navigation

- index
- previous |
- GHC 8.4.0.20180224 User's Guide »