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 <#references>`__. Basics ------ Unicode characters are allowed in the document. The basic syntax works largely as one would expect. For instance, .. code-block:: rest 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 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. Headings ~~~~~~~~ While ReST can accommodate a wide range of heading styles, we have standardized on this convention in the User's Guide, .. code-block:: rest Header level 1 ============== Header level 2 -------------- Header level 3 ~~~~~~~~~~~~~~ Header level 4 ^^^^^^^^^^^^^^ Formatting code ~~~~~~~~~~~~~~~ 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, .. code-block:: rest 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) Other languages ^^^^^^^^^^^^^^^ Double-colon blocks are syntax-highlighted as Haskell by default. To avoid this use a ``.. code-block`` `directive `__ with explicit language designation, .. code-block:: rest This is a simple shell script, .. code-block:: sh #!/bin/bash echo "Hello World!" Links ~~~~~ 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, .. code-block:: rest .. _options-platform: Platform-specific Flags ----------------------- There are lots of platform-specific flags. Some other section ------------------- GHC supports a variety of :ref:`x86 specific features `. See :ref:`options-platform` for details. To GHC Trac resources ^^^^^^^^^^^^^^^^^^^^^ There are special macros for conveniently linking to GHC Trac Wiki articles and tickets, .. code-block:: rest See :ghc-wiki:`Commentary/Latedmd` for details on demand analysis. See the :ghc-wiki:`coding style ` for guidelines. See the :ghc-ticket:`123` for further discussion. See the :ghc-ticket:`this bug <123>` for what happens when this fails. To external resources ^^^^^^^^^^^^^^^^^^^^^ External links can be written in either of these ways, .. code-block:: rest See the `GHC Wiki `_ for details. See the `GHC Wiki`_ for details. .. _GHC Wiki: http://ghc.haskell.org/wiki 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 :file:`docs/users_guide/ghc_config.py.in`. For instance, .. code-block:: rest See the documentation for :base-ref:`Control.Applicative ` for details. Math ^^^^ You can insert type-set equations using ``:math:``. For instance, .. code-block:: rest Fick's law of diffusion, :math:`J = -D \frac{d \varphi}{d x}`, ... will render as, Fick's law of diffusion, :math:`J = -D \frac{d \varphi}{d x}`, ... Index entries ~~~~~~~~~~~~~ Index entries can be included anywhere in the document as a block element. They look like, .. code-block:: rest 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. Citations --------- Citations can be marked-up like this, .. code-block:: rest See the original paper [Doe2008]_ .. [Doe2008] John Doe and Leslie Conway. "This is the title of our paper" (2008) 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, .. code-block:: rest .. 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, .. hlist:: :columns: 3 * attention * caution * danger * error * hint * important * note * tip * warning .. _Admonitions: http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions Documenting command-line options and GHCi commands -------------------------------------------------- :file:`conf.py` defines a few Sphinx object types for GHCi commands (``ghci-cmd``), :program:`ghc` command-line options (``ghc-flag``), and runtime :system options (``rts-flag``), Command-line options ~~~~~~~~~~~~~~~~~~~~ The ``ghc-flag`` and ``rts-flag`` roles/directives can be used to document command-line arguments to the :program:`ghc` executable and runtime system, respectively. For instance, .. code-block:: rest .. rts-flag:: -C ⟨seconds⟩ :default: 20 milliseconds Sets the context switch interval to ⟨s⟩ seconds. Will be rendered as, .. rts-flag:: -C ⟨seconds⟩ :noindex: :default: 20 milliseconds Sets the context switch interval to ⟨s⟩ seconds. and will have an associated index entry generated automatically. 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, .. code-block:: sh $ git grep -- "flag:: -o " which will generate the appropriate, .. code-block:: none separate_compilation.rst:.. ghc-flag:: -o ⟨file⟩ GHCi commands ~~~~~~~~~~~~~ The ``ghci-cmd`` role and directive can be used to document GHCi directives. For instance, we can describe the GHCi ``:module`` command, .. code-block:: rest .. ghci-cmd:: :module; [*]⟨file⟩ Load a module which will be rendered as, .. ghci-cmd:: :module; [*]⟨file⟩ :noindex: Load a module And later refer to it by just the command name, ``:module``, .. code-block:: rest 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. 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). .. _references: GHC command-line options reference ---------------------------------- The tabular nature of GHC flags reference (:file:`flags.rst`) makes it very difficult to maintain as ReST. For this reason it is generated by :file:`utils/mkUserGuidePart`. Any command-line options added to GHC should be added to the appropriate file in :file:`utils/mkUserGuidePart/Options`. 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`_ .. _Sphinx ReST Primer: http://sphinx-doc.org/rest.html .. _ReST reference: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html .. _Sphinx extensions: http://sphinx-doc.org/markup/index.html .. _Directives reference: http://docutils.sourceforge.net/docs/ref/rst/directives.html#code