Fix more documentation wibbles
[ghc.git] / docs / users_guide / editing-guide.rst
1 Care and feeding of your GHC User's Guide
2 =========================================
3
4 The GHC User's Guide is the primary reference documentation
5 for the Glasgow Haskell Compiler. Even more than this, it at times serves (for
6 better or for worse) as a de-facto language standard, being the sole
7 non-academic reference for many widely used language extensions.
8
9 Since GHC 8.0, the User's Guide is authored in `ReStructuredText
10 <https://en.wikipedia.org/wiki/ReStructuredText>`__ (or ReST or RST, for short)
11 a rich but light-weight mark-up language aimed at producing documentation. The
12 `Sphinx <http://sphinx-doc.org/>`__ tool is used to produce the final PDF and
13 HTML documentation.
14
15 This document (also written in ReST) serves as a brief introducion to ReST and to
16 document the conventions used in the User's Guide. This document is *not* intended
17 to be a thorough guide to ReST. For this see the resources referenced
18 `below <#references>`__.
19
20 Basics
21 ------
22
23 Unicode characters are allowed in the document.
24
25 The basic syntax works largely as one would expect. For instance,
26
27 .. code-block:: rest
28
29     This is a paragraph containing a few sentences of text. Purple turtles walk
30     through green fields of lofty maize. Lorem ipsum dolor sit amet, consectetur
31     adipiscing elit. Some lists,
32
33     1. This is a list item
34
35        a. Followed by a sub-item
36        b. And another!
37        c. Now with ``a bit of code`` and some *emphasis*.
38
39     2. Back to the first list
40
41     Or perhaps you are more of a bullet list person,
42
43     * Foo
44     * Fizzle
45
46       - Bar
47       - Blah
48
49     Or perhaps a definition list is in order,
50
51     *Chelonii*
52         The taxonomic order consisting of modern turtles
53     *Meiolaniidae*
54         The taxonomic order of an extinct variety of herbivorous turtles.
55
56 Note the blank lines between a list item and its sub-items. Sub-items should be
57 on the same indentation level as the content of their parent items. Also note
58 that no whitespace is necessary or desirable before the bullet or item number
59 (lest the list be indented unnecessarily).
60
61 The above would be rendered as,
62
63     This is a paragraph containing a few sentences of text. Purple turtles walk
64     through green fields of lofty maize. Lorem ipsum dolor sit amet, consectetur
65     adipiscing elit. Some lists,
66
67     1. This is a list item
68
69        a. Followed by a sub-item
70        b. And another!
71        c. Now with ``a bit of code`` and some *emphasis*.
72
73     2. Back to the first list
74
75     Or perhaps you are more of a bullet list person,
76
77     * Foo
78     * Fizzle
79
80       - Bar
81       - Blah
82
83     Or perhaps a definition list is in order,
84
85     *Chelonii*
86         The taxonomic order consisting of modern turtles
87     *Meiolaniidae*
88         The taxonomic order of an extinct variety of herbivorous turtles.
89
90
91 Headings
92 ~~~~~~~~
93
94 While ReST can accommodate a wide range of heading styles, we have standardized
95 on this convention in the User's Guide,
96
97 .. code-block:: rest
98
99     Header level 1
100     ==============
101
102     Header level 2
103     --------------
104
105     Header level 3
106     ~~~~~~~~~~~~~~
107
108     Header level 4
109     ^^^^^^^^^^^^^^
110
111
112 Formatting code
113 ~~~~~~~~~~~~~~~
114
115 Haskell
116 ^^^^^^^
117
118 Code snippets can be included as both inline and block elements. Inline
119 code is denoted with double-backticks whereas block of code are introduced
120 by ending a paragraph with double-colons and indentation,
121
122 .. code-block:: rest
123
124     The ``fib`` function is defined as, ::
125
126         fib :: Integer -> Integer
127         fib 1 = 1
128         fib n = n * fib (n - 1)
129
130 Which would be rendered as,
131
132     The ``fib`` function is defined as, ::
133
134         fib :: Integer -> Integer
135         fib 1 = 1
136         fib n = n * fib (n - 1)
137
138 Other languages
139 ^^^^^^^^^^^^^^^
140
141 Double-colon blocks are syntax-highlighted as Haskell by default. To avoid this
142 use a
143 ``.. code-block`` `directive
144 <http://sphinx-doc.org/markup/code.html#directive-code-block>`__ with explicit
145 language designation,
146
147 .. code-block:: rest
148
149     This is a simple shell script,
150
151     .. code-block:: sh
152
153         #!/bin/bash
154         echo "Hello World!"
155
156
157 Links
158 ~~~~~
159
160 Within the User's Guide
161 ^^^^^^^^^^^^^^^^^^^^^^^
162
163 Frequently we want to give a name to a section so it can be referred to
164 from other points in the document,
165
166 .. code-block:: rest
167
168     .. _options-platform:
169
170     Platform-specific Flags
171     -----------------------
172
173     There are lots of platform-specific flags.
174
175     Some other section
176     -------------------
177
178     GHC supports a variety of :ref:`x86 specific features <options-platform>`.
179
180     See :ref:`options-platform` for details.
181
182
183 To GHC Trac resources
184 ^^^^^^^^^^^^^^^^^^^^^
185
186 There are special macros for conveniently linking to GHC Trac
187 Wiki articles and tickets,
188
189 .. code-block:: rest
190
191     See :ghc-wiki:`Commentary/Latedmd` for details on demand analysis.
192
193     See the :ghc-wiki:`coding style <Commentary/CodingStyle>` for guidelines.
194
195     See the :ghc-ticket:`123` for further discussion.
196
197     See the :ghc-ticket:`this bug <123>` for what happens when this fails.
198
199
200 To external resources
201 ^^^^^^^^^^^^^^^^^^^^^
202
203 External links can be written in either of these ways,
204
205 .. code-block:: rest
206
207     See the `GHC Wiki <http://ghc.haskell.org/wiki>`_ for details.
208
209     See the `GHC Wiki`_ for details.
210
211     .. _GHC Wiki: http://ghc.haskell.org/wiki
212
213
214 To core library Haddock documentation
215 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
216
217 It is often useful to be able to refer to the Haddock documention of the
218 libraries shipped with GHC. The users guide's build system provides
219 commands for referring to documentation for the following core GHC packages,
220
221 * ``base``: ``:base-ref:``
222 * ``cabal``: ``:cabal-ref:``
223 * ``ghc-prim``: ``:ghc-prim-ref:``
224
225 These are defined in :file:`docs/users_guide/ghc_config.py.in`.
226
227 For instance,
228
229 .. code-block:: rest
230
231     See the documentation for :base-ref:`Control.Applicative <Control-Applicative.html>`
232     for details.
233
234 Math
235 ^^^^
236
237 You can insert type-set equations using ``:math:``. For instance,
238
239 .. code-block:: rest
240
241     Fick's law of diffusion, :math:`J = -D \frac{d \varphi}{d x}`, ...
242
243 will render as,
244
245     Fick's law of diffusion, :math:`J = -D \frac{d \varphi}{d x}`, ...
246
247
248 Index entries
249 ~~~~~~~~~~~~~
250
251 Index entries can be included anywhere in the document as a block element.
252 They look like,
253     
254 .. code-block:: rest
255
256     Here is some discussion on the Strict Haskell extension.
257
258     .. index::
259         single: strict haskell
260         single: language extensions; StrictData
261
262 This would produce two entries in the index referring to the "Strict Haskell"
263 section. One would be a simple "strict haskell" heading whereas the other would
264 be a "StrictData" subheading under "language extensions".
265
266 Sadly it is not possible to use inline elements (e.g. monotype inlines) inside
267 index headings.
268
269 Citations
270 ---------
271
272 Citations can be marked-up like this,
273
274 .. code-block:: rest
275
276     See the original paper [Doe2008]_
277
278     .. [Doe2008] John Doe and Leslie Conway.
279                  "This is the title of our paper" (2008)
280
281
282 Admonitions
283 -----------
284
285 `Admonitions`_ are block elements used to draw the readers attention to a point.
286 They should not be over-used for the sake of readability but they can be quite
287 effective in separating and drawing attention to points of importance,
288
289 .. code-block:: rest
290
291     .. important::
292
293         Be friendly and supportive to your fellow contributors.
294
295 Would be rendered as,
296
297     .. important::
298
299         Be friendly and supportive to your fellow contributors.
300
301 There are a number of admonitions types,
302
303 .. hlist::
304     :columns: 3
305
306     * attention
307     * caution
308     * danger
309     * error
310     * hint
311     * important
312     * note
313     * tip
314     * warning
315
316
317 .. _Admonitions: http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions
318
319 Documenting command-line options and GHCi commands
320 --------------------------------------------------
321
322 :file:`conf.py` defines a few Sphinx object types for GHCi commands
323 (``ghci-cmd``), :program:`ghc` command-line options (``ghc-flag``), and runtime
324 :system options (``rts-flag``),
325
326 Command-line options
327 ~~~~~~~~~~~~~~~~~~~~
328
329 The ``ghc-flag`` and ``rts-flag`` roles/directives can be used to document
330 command-line arguments to the :program:`ghc` executable and runtime system,
331 respectively. For instance,
332
333 .. code-block:: rest
334
335     .. rts-flag:: -C ⟨seconds⟩
336
337        :default: 20 milliseconds
338
339        Sets the context switch interval to ⟨s⟩ seconds.
340
341 Will be rendered as,
342
343     .. rts-flag:: -C ⟨seconds⟩
344        :noindex:
345
346        :default: 20 milliseconds
347
348        Sets the context switch interval to ⟨s⟩ seconds.
349
350 and will have an associated index entry generated automatically. Note that, as
351 in Style Conventions below, we use ``⟨⟩`` instead of less-than/greater-than
352 signs. To reference a ``ghc-flag`` or ``rts-flag``, you must match the
353 definition exactly, including the arguments. A quick way to find the exact
354 names and special characters is,
355
356 .. code-block:: sh
357     
358     $ git grep -- "flag:: -o "
359
360 which will generate the appropriate,
361
362 .. code-block:: none
363
364     separate_compilation.rst:.. ghc-flag:: -o ⟨file⟩
365
366 GHCi commands
367 ~~~~~~~~~~~~~
368
369 The ``ghci-cmd`` role and directive can be used to document GHCi directives. For
370 instance, we can describe the GHCi ``:module`` command,
371
372 .. code-block:: rest
373
374     .. ghci-cmd:: :module; [*]⟨file⟩
375
376         Load a module
377
378 which will be rendered as,
379
380     .. ghci-cmd:: :module; [*]⟨file⟩
381         :noindex:
382
383         Load a module
384
385 And later refer to it by just the command name, ``:module``,
386
387 .. code-block:: rest
388
389     The GHCi :ghci-cmd:`:load` and :ghci-cmd:`:module` commands are used
390     to modify the modules in scope.
391
392 Like command-line options, GHCi commands will have associated index entries
393 generated automatically.
394
395 Style Conventions
396 -----------------
397
398 When describing user commands and the like it is common to need to denote
399 user-substitutable tokens. In this document we use the convention, ``⟨subst⟩``
400 (note that these are angle brackets, ``U+27E8`` and ``U+27E9``, not
401 less-than/greater-than signs).
402
403
404 .. _references:
405
406 GHC command-line options reference
407 ----------------------------------
408
409 The tabular nature of GHC flags reference (:file:`flags.rst`) makes it very
410 difficult to maintain as ReST. For this reason it is generated by
411 :file:`utils/mkUserGuidePart`. Any command-line options added to GHC should
412 be added to the appropriate file in :file:`utils/mkUserGuidePart/Options`.
413
414
415 ReST reference materials
416 ------------------------
417
418 * `Sphinx ReST Primer`_: A great place to start.
419 * `Sphinx extensions`_: How Sphinx extends ReST
420 * `ReST reference`_: When you really need the details.
421 * `Directives reference`_
422
423 .. _Sphinx ReST Primer: http://sphinx-doc.org/rest.html
424 .. _ReST reference: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
425 .. _Sphinx extensions: http://sphinx-doc.org/markup/index.html
426 .. _Directives reference: http://docutils.sourceforge.net/docs/ref/rst/directives.html#code