rts: Rename the nondescript initProfiling2 to refreshProfilingCCSs
[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 resources
184 ^^^^^^^^^^^^^^^^
185
186 There are special macros for conveniently linking to GHC
187 Wiki articles and tickets,
188
189 .. code-block:: rest
190
191     See :ghc-wiki:`commentary/compiler/demand` for details on demand analysis.
192
193     See the :ghc-wiki:`coding style <commentary/coding-style>` 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 <https://gitlab.haskell.org/ghc/ghc/wikis>`_ for details.
208
209     See the `GHC Wiki`_ for details.
210
211     .. _GHC Wiki: https://gitlab.haskell.org/ghc/ghc/wikis
212
213
214 To core library Haddock documentation
215 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
216
217 It is often useful to be able to refer to the Haddock documentation 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        :since: 8.2
338        :default: 20 milliseconds
339
340        Sets the context switch interval to ⟨s⟩ seconds.
341
342 Will be rendered as,
343
344     .. rts-flag:: -C ⟨seconds⟩
345        :noindex:
346
347        :since: 8.2
348        :default: 20 milliseconds
349
350        Sets the context switch interval to ⟨s⟩ seconds.
351
352 and will have an associated index entry generated automatically.
353
354 The ``ghc-flag`` directive requires a few extra parameters to be passed.
355 This extra information is used to generate the :ref:`flag-reference` and the
356 man page. A ``ghc-flag`` directive looks like this,
357
358 .. code-block:: rest
359
360     .. ghc-flag:: -fasm
361         :shortdesc: Use the native code generator
362         :type: dynamic
363         :reverse: -fllvm
364         :category: codegen
365
366         Regular description...
367
368 When rendered, the extra parameters will be hidden, and the data stored for
369 later use. For more details, see the Sphinx extension ``flags.py``.
370
371 Note that, as in Style Conventions below, we use ``⟨⟩`` instead of
372 less-than/greater-than signs. To reference a ``ghc-flag`` or ``rts-flag``, you
373 must match the definition exactly, including the arguments. A quick way to find
374 the exact names and special characters is,
375
376 .. code-block:: sh
377
378     $ git grep -- "flag:: -o "
379
380 which will generate the appropriate,
381
382 .. code-block:: none
383
384     separate_compilation.rst:.. ghc-flag:: -o ⟨file⟩
385
386 GHCi commands
387 ~~~~~~~~~~~~~
388
389 The ``ghci-cmd`` role and directive can be used to document GHCi directives. For
390 instance, we can describe the GHCi ``:module`` command,
391
392 .. code-block:: rest
393
394     .. ghci-cmd:: :module; [*]⟨file⟩
395
396         Load a module
397
398 which will be rendered as,
399
400     .. ghci-cmd:: :module; [*]⟨file⟩
401         :noindex:
402
403         Load a module
404
405 And later refer to it by just the command name, ``:module``,
406
407 .. code-block:: rest
408
409     The GHCi :ghci-cmd:`:load` and :ghci-cmd:`:module` commands are used
410     to modify the modules in scope.
411
412 Like command-line options, GHCi commands will have associated index entries
413 generated automatically.
414
415 Style Conventions
416 -----------------
417
418 When describing user commands and the like it is common to need to denote
419 user-substitutable tokens. In this document we use the convention, ``⟨subst⟩``
420 (note that these are angle brackets, ``U+27E8`` and ``U+27E9``, not
421 less-than/greater-than signs).
422
423
424 ReST reference materials
425 ------------------------
426
427 * `Sphinx ReST Primer`_: A great place to start.
428 * `Sphinx extensions`_: How Sphinx extends ReST
429 * `ReST reference`_: When you really need the details.
430 * `Directives reference`_
431
432 .. _Sphinx ReST Primer: http://sphinx-doc.org/rest.html
433 .. _ReST reference: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
434 .. _Sphinx extensions: http://sphinx-doc.org/markup/index.html
435 .. _Directives reference: http://docutils.sourceforge.net/docs/ref/rst/directives.html#code