aboutsummaryrefslogtreecommitdiff
path: root/doc/haddock.xml
blob: e805a437fd07a9fea1b081963b764fd5a85f8b85 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
    <!ENTITY nbsp   '&#160;'>
    <!ENTITY frac12 '&#189;'>
    <!ENTITY mdash  '&#8212;'>
    <!ENTITY lsquo  '&#8217;'>
    <!ENTITY rsquo  '&#8218;'>
    <!ENTITY ldquo  '&#8220;'>
    <!ENTITY rdquo  '&#8221;'>
] >

<book id="haddock">
  <bookinfo>
    <date>2015-06-02</date>
    <title>Haddock User Guide</title>
    <author>
      <firstname>Simon</firstname>
      <surname>Marlow</surname>
    </author>
    <address><email>marlowsd@gmail.com</email></address>
    <author>
      <firstname>David</firstname>
      <surname>Waern</surname>
    </author>
    <address><email>david.waern@gmail.com</email></address>
    <author>
      <firstname>Mateusz</firstname>
      <surname>Kowalczyk</surname>
    </author>
    <address><email>fuuzetsu@fuuzetsu.co.uk</email></address>
    <copyright>
      <year>2010</year>
      <holder>Simon Marlow, David Waern</holder>
    </copyright>
    <copyright>
      <year>2013-2015</year>
      <holder>Mateusz Kowalczyk</holder>
    </copyright>
    <abstract>
      <para>This document describes Haddock version 2.16.2, a Haskell
      documentation tool.</para>
    </abstract>
  </bookinfo>

  <!-- Table of contents -->
  <toc></toc>

  <chapter id="introduction">
    <title>Introduction</title>

    <para>This is Haddock, a tool for automatically generating
    documentation from annotated Haskell source code.  Haddock was
    designed with several goals in mind:</para>

    <itemizedlist>
      <listitem>
        <para>When documenting APIs, it is desirable to keep the
        documentation close to the actual interface or implementation
        of the API, preferably in the same file, to reduce the risk
        that the two become out of sync.  Haddock therefore lets you
        write the documentation for an entity (function, type, or
        class) next to the definition of the entity in the source
        code.</para>
      </listitem>
      <listitem>
        <para>There is a tremendous amount of useful API documentation
        that can be extracted from just the bare source code,
        including types of exported functions, definitions of data
        types and classes, and so on.  Haddock can therefore generate
        documentation from a set of straight Haskell 98 modules, and
        the documentation will contain precisely the interface that is
        available to a programmer using those modules.</para>
      </listitem>
      <listitem>
        <para>Documentation annotations in the source code should be
        easy on the eye when editing the source code itself, so as not
        to obscure the code and to make reading and writing
        documentation annotations easy.  The easier it is to write
        documentation, the more likely the programmer is to do it.
        Haddock therefore uses lightweight markup in its annotations,
        taking several ideas from <ulink
        url="http://www.cse.unsw.edu.au/~chak/haskell/idoc/">IDoc</ulink>.
        In fact, Haddock can understand IDoc-annotated source
        code.</para>
      </listitem>
      <listitem>
        <para>The documentation should not expose any of the structure
        of the implementation, or to put it another way, the
        implementer of the API should be free to structure the
        implementation however he or she wishes, without exposing any
        of that structure to the consumer.  In practical terms, this
        means that while an API may internally consist of several
        Haskell modules, we often only want to expose a single module
        to the user of the interface, where this single module just
        re-exports the relevant parts of the implementation
        modules.</para>

        <para>Haddock therefore understands the Haskell module system
        and can generate documentation which hides not only
        non-exported entities from the interface, but also the
        internal module structure of the interface.  A documentation
        annotation can still be placed next to the implementation, and
        it will be propagated to the external module in the generated
        documentation.</para>
      </listitem>
      <listitem>
        <para>Being able to move around the documentation by following
        hyperlinks is essential.  Documentation generated by Haddock
        is therefore littered with hyperlinks: every type and class
        name is a link to the corresponding definition, and
        user-written documentation annotations can contain identifiers
        which are linked automatically when the documentation is
        generated.</para>
      </listitem>
      <listitem>
        <para>We might want documentation in multiple formats - online
        and printed, for example.  Haddock comes with HTML, LaTeX,
  and Hoogle backends, and it is structured in such a way that adding new
        backends is straightforward.</para>
      </listitem>
    </itemizedlist>

    <section id="obtaining">
      <title>Obtaining Haddock</title>

      <para>Distributions (source &amp; binary) of Haddock can be obtained
      from its <ulink url="http://www.haskell.org/haddock/">web
      site</ulink>.</para>

      <para>Up-to-date sources can also be obtained from our public
      darcs repository.  The Haddock sources are at
      <literal>http://code.haskell.org/haddock</literal>.  See
      <ulink url="http://www.darcs.net/">darcs.net</ulink> for more
      information on the darcs version control utility.</para>
    </section>

    <section id="license">
      <title>License</title>

      <para>The following license covers this documentation, and the
      Haddock source code, except where otherwise indicated.</para>

      <blockquote>
        <para>Copyright 2002-2010, Simon Marlow.  All rights reserved.</para>

        <para>Redistribution and use in source and binary forms, with
        or without modification, are permitted provided that the
        following conditions are met:</para>

        <itemizedlist>
          <listitem>
            <para>Redistributions of source code must retain the above
            copyright notice, this list of conditions and the
            following disclaimer.</para>
          </listitem>
          <listitem>
            <para>Redistributions in binary form must reproduce the
            above copyright notice, this list of conditions and the
            following disclaimer in the documentation and/or other
            materials provided with the distribution.</para>
          </listitem>
        </itemizedlist>

        <para>THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS "AS
        IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
        LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
        FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
        SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY DIRECT,
        INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
        SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
        OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
        LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
        (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
        THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
        OF SUCH DAMAGE.</para>
      </blockquote>
    </section>

    <section>
      <title>Contributors</title>
      <para>Haddock was originally written by Simon Marlow. Since it is an open source
      project, many people have contributed to its development over the years.
      Below is a list of contributors in alphabetical order that we hope is
      somewhat complete. If you think you are missing from this list, please contact
      us.
      </para>
      <itemizedlist>
        <listitem><simpara>Ashley Yakeley</simpara></listitem>
        <listitem><simpara>Benjamin Franksen</simpara></listitem>
        <listitem><simpara>Brett Letner</simpara></listitem>
        <listitem><simpara>Clemens Fruhwirth</simpara></listitem>
        <listitem><simpara>Conal Elliott</simpara></listitem>
        <listitem><simpara>David Waern</simpara></listitem>
        <listitem><simpara>Duncan Coutts</simpara></listitem>
        <listitem><simpara>George Pollard</simpara></listitem>
        <listitem><simpara>George Russel</simpara></listitem>
        <listitem><simpara>Hal Daume</simpara></listitem>
        <listitem><simpara>Ian Lynagh</simpara></listitem>
        <listitem><simpara>Isaac Dupree</simpara></listitem>
        <listitem><simpara>Joachim Breitner</simpara></listitem>
        <listitem><simpara>Krasimir Angelov</simpara></listitem>
        <listitem><simpara>Lennart Augustsson</simpara></listitem>
        <listitem><simpara>Luke Plant</simpara></listitem>
        <listitem><simpara>Malcolm Wallace</simpara></listitem>
        <listitem><simpara>Manuel Chakravarty</simpara></listitem>
        <listitem><simpara>Mark Lentczner</simpara></listitem>
        <listitem><simpara>Mark Shields</simpara></listitem>
        <listitem><simpara>Mateusz Kowalczyk</simpara></listitem>
        <listitem><simpara>Mike Thomas</simpara></listitem>
        <listitem><simpara>Neil Mitchell</simpara></listitem>
        <listitem><simpara>Oliver Brown</simpara></listitem>
        <listitem><simpara>Roman Cheplyaka</simpara></listitem>
        <listitem><simpara>Ross Paterson</simpara></listitem>
        <listitem><simpara>Sigbjorn Finne</simpara></listitem>
        <listitem><simpara>Simon Hengel</simpara></listitem>
        <listitem><simpara>Simon Marlow</simpara></listitem>
        <listitem><simpara>Simon Peyton-Jones</simpara></listitem>
        <listitem><simpara>Stefan O'Rear</simpara></listitem>
        <listitem><simpara>Sven Panne</simpara></listitem>
        <listitem><simpara>Thomas Schilling</simpara></listitem>
        <listitem><simpara>Wolfgang Jeltsch</simpara></listitem>
        <listitem><simpara>Yitzchak Gale</simpara></listitem>
      </itemizedlist>
    </section>
    <section>
      <title>Acknowledgements</title>

      <para>Several documentation systems provided the inspiration for
      Haddock, most notably:</para>

      <itemizedlist>
        <listitem>
          <para><ulink
          url="http://www.cse.unsw.edu.au/~chak/haskell/idoc/">
          IDoc</ulink></para>
        </listitem>
        <listitem>
          <para><ulink
          url="http://www.fmi.uni-passau.de/~groessli/hdoc/">HDoc</ulink></para>
        </listitem>
        <listitem>
          <para><ulink url="http://www.stack.nl/~dimitri/doxygen/">
          Doxygen</ulink></para>
        </listitem>
      </itemizedlist>

      <para>and probably several others I've forgotten.</para>

      <para>Thanks to the the members
      of <email>haskelldoc@haskell.org</email>,
      <email>haddock@projects.haskell.org</email> and everyone who
      contributed to the many libraries that Haddock makes use
      of.</para>
    </section>

  </chapter>

  <chapter id="invoking">
    <title>Invoking Haddock</title>
    <para>Haddock is invoked from the command line, like so:</para>

    <cmdsynopsis>
      <command>haddock</command>
      <arg rep="repeat"><replaceable>option</replaceable></arg>
      <arg rep="repeat" choice="plain"><replaceable>file</replaceable></arg>
    </cmdsynopsis>

    <para>Where each <replaceable>file</replaceable> is a filename
    containing a Haskell source module (.hs) or a Literate Haskell source
    module (.lhs) or just a module name.</para>

    <para>All the modules specified on the command line will be
    processed together.  When one module refers to an entity in
    another module being processed, the documentation will link
    directly to that entity.</para>

    <para>Entities that cannot be found, for example because they are
    in a module that isn't being processed as part of the current
    batch, simply won't be hyperlinked in the generated
    documentation.  Haddock will emit warnings listing all the
    identifiers it couldn't resolve.</para>

    <para>The modules should <emphasis>not</emphasis> be mutually
    recursive, as Haddock don't like swimming in circles.</para>

    <para>Note that while older version would fail on invalid markup, this is considered a bug in the
    new versions. If you ever get failed parsing message, please report it.</para>

    <para>You must also specify an option for the output format.
    Currently only the <option>-h</option> option for HTML and the
    <option>--hoogle</option> option for outputting Hoogle data are
    functional.</para>

    <para>The packaging
    tool <ulink url="http://www.haskell.org/ghc/docs/latest/html/Cabal/index.html">Cabal</ulink>
    has Haddock support, and is often used instead of invoking Haddock
    directly.</para>

    <para>The following options are available:</para>

    <variablelist>

      <varlistentry>
        <term>
          <indexterm><primary><option>-B</option></primary></indexterm>
          <option>-B</option> <replaceable>dir</replaceable>
        </term>
        <listitem>
          <para>Tell GHC that that its lib directory is
    <replaceable>dir</replaceable>. Can be used to override the default path.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <indexterm><primary><option>-o</option></primary></indexterm>
          <option>-o</option> <replaceable>dir</replaceable>
        </term>
        <term>
          <indexterm><primary><option>--odir</option></primary></indexterm>
          <option>--odir</option>=<replaceable>dir</replaceable>
        </term>
        <listitem>
          <para>Generate files into <replaceable>dir</replaceable>
          instead of the current directory.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <indexterm><primary><option>-l</option></primary></indexterm>
          <option>-l</option> <replaceable>dir</replaceable>
        </term>
        <term>
          <indexterm><primary><option>--lib</option></primary></indexterm>
          <option>--lib</option>=<replaceable>dir</replaceable>
        </term>
        <listitem>
          <para>Use Haddock auxiliary files (themes, javascript, etc...) in <replaceable>dir</replaceable>.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <indexterm><primary><option>-i</option></primary></indexterm>
          <option>-i</option> <replaceable>file</replaceable>
        </term>
        <term>
          <indexterm><primary><option>-i</option></primary></indexterm>
          <option>-i</option> <replaceable>docpath</replaceable>,<replaceable>file</replaceable>
        </term>
        <term>
          <indexterm><primary><option>-i</option></primary></indexterm>
          <option>-i</option> <replaceable>docpath</replaceable>,<replaceable>srcpath</replaceable>,<replaceable>file</replaceable>
        </term>
        <term>
          <indexterm><primary><option>--read-interface</option></primary></indexterm>
          <option>--read-interface</option>=<replaceable>file</replaceable>
        </term>
        <term>
          <indexterm><primary><option>--read-interface</option></primary></indexterm>
          <option>--read-interface</option>=<replaceable>docpath</replaceable>,<replaceable>file</replaceable>
        </term>
        <term>
          <indexterm><primary><option>--read-interface</option></primary></indexterm>
          <option>--read-interface</option>=<replaceable>docpath</replaceable>,<replaceable>srcpath</replaceable>,<replaceable>file</replaceable>
        </term>
        <listitem>
          <para>Read the interface file in
          <replaceable>file</replaceable>, which must have been
          produced by running Haddock with the
          <option>--dump-interface</option> option.  The interface
          describes a set of modules whose HTML documentation is
          located in <replaceable>docpath</replaceable> (which may be a
          relative pathname).  The <replaceable>docpath</replaceable> is
          optional, and defaults to <quote>.</quote>. The
          <replaceable>srcpath</replaceable> is optional but has no default
          value.</para>

          <para>This option allows Haddock to produce separate sets of
          documentation with hyperlinks between them.  The
          <replaceable>docpath</replaceable> is used to direct hyperlinks
          to point to the right files; so make sure you don't move the
          HTML files later or these links will break.  Using a
          relative <replaceable>docpath</replaceable> means that a
          documentation subtree can still be moved around without
          breaking links.</para>

          <para>Similarly to <replaceable>docpath</replaceable>, <replaceable>srcpath</replaceable> is used generate cross-package hyperlinks but
          within sources rendered with <option>--hyperlinked-source</option>
          option.</para>

          <para>Multiple <option>--read-interface</option> options may
          be given.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <indexterm><primary><option>-D</option></primary></indexterm>
          <option>-D</option> <replaceable>file</replaceable>
        </term>
        <term>
          <indexterm><primary><option>--dump-interface</option></primary></indexterm>
          <option>--dump-interface</option>=<replaceable>file</replaceable>
        </term>
        <listitem>
          <para>Produce an <firstterm>interface
          file</firstterm><footnote><para>Haddock interface files are
          not the same as Haskell interface files, I just couldn't
          think of a better name.</para> </footnote>
          in the file <replaceable>file</replaceable>.  An interface
          file contains information Haddock needs to produce more
          documentation that refers to the modules currently being
          processed - see the <option>--read-interface</option> option
          for more details.  The interface file is in a binary format;
          don't try to read it.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <indexterm><primary><option>-h</option></primary></indexterm>
          <option>-h</option>
        </term>
        <term>
          <indexterm><primary><option>--html</option></primary></indexterm>
          <option>--html</option>
        </term>
        <listitem>
          <para>Generate documentation in HTML format.  Several files
          will be generated into the current directory (or the
          specified directory if the <option>-o</option> option is
          given), including the following:</para>
          <variablelist>
            <varlistentry>
              <term><filename><replaceable>module</replaceable>.html</filename></term>
              <term><filename>mini_<replaceable>module</replaceable>.html</filename></term>
              <listitem>
                <para>An HTML page for each
                <replaceable>module</replaceable>, and a "mini" page for
                each used when viewing in frames.</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term><filename>index.html</filename></term>
              <listitem>
                <para>The top level page of the documentation: lists
                the modules available, using indentation to represent
                the hierarchy if the modules are hierarchical.</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term><filename>doc-index.html</filename></term>
              <term><filename>doc-index-<replaceable>X</replaceable>.html</filename></term>
              <listitem>
                <para>The alphabetic index, possibly split into multiple
                pages if big enough.</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term><filename>frames.html</filename></term>
              <listitem>
                <para>The top level document when viewing in frames.</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term><filename><replaceable>some</replaceable>.css</filename></term>
              <term><filename><replaceable>etc...</replaceable></filename></term>
              <listitem>
                <para>Files needed for the themes used. Specify your themes
                using the <option>--theme</option> option.</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term><filename>haddock-util.js</filename></term>
              <listitem>
                <para>Some JavaScript utilities used to implement some of the
                dynamic features like collapsible sections, and switching to
                frames view.</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <indexterm><primary><option>--latex</option></primary></indexterm>
          <option>--latex</option>
        </term>
        <listitem>
          <para>Generate documentation in LaTeX format.  Several files
          will be generated into the current directory (or the
            specified directory if the <option>-o</option> option is
            given), including the following:</para>

          <variablelist>
            <varlistentry>
              <term><filename><replaceable>package</replaceable>.tex</filename></term>
              <listitem>
                <para>The top-level LaTeX source file; to format the
                documentation into PDF you might run something like
                  this:</para>
<screen>
$ pdflatex <replaceable>package</replaceable>.tex</screen>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term><filename>haddock.sty</filename></term>
              <listitem>
                <para>The default style.  The file contains
                definitions for various macros used in the LaTeX
                sources generated by Haddock; to change the way the
                formatted output looks, you might want to override
                these by specifying your own style with
                the <option>--latex-style</option> option.</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term><filename><replaceable>module</replaceable>.tex</filename></term>
              <listitem>
                <para>The LaTeX documentation for
                each <replaceable>module</replaceable>.</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <indexterm><primary><option>--latex-style</option></primary></indexterm>
          <option>--latex-style=<replaceable>style</replaceable></option>
        </term>
        <listitem>
          <para>This option lets you override the default style used
            by the LaTeX generated by the <option>--latex</option> option.
            Normally Haddock puts a
            standard <filename>haddock.sty</filename> in the output
            directory, and includes the
            command <literal>\usepackage{haddock}</literal> in the
            LaTeX source.  If this option is given,
            then <filename>haddock.sty</filename> is not generated,
            and the command is
            instead <literal>\usepackage{<replaceable>style</replaceable>}</literal>.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <indexterm><primary><option>--hyperlinked-source</option></primary></indexterm>
          <option>--hyperlinked-source</option>
        </term>
        <listitem>
          <para>Generate hyperlinked source code (as HTML web page). All
          rendered files will be put into
          <filename class='directory'>src/</filename> subfolder of output
          directory.</para>
          <para>Usually, this should be used in combination with
          <option>--html</option> option - generated documentation will then
          contain references to appropriate code fragments. Previously, this
          behaviour could be achieved by generating sources using external
          tool and specifying <option>--source-base</option>,
          <option>--source-module</option>, <option>--source-entity</option>
          and related options. Note that these flags are ignored once
          <option>--hyperlinked-source</option> is set.</para>
          <para>In order to make cross-package source hyperlinking possible,
          appropriate source paths have to be set up when providing
          interface files using <option>--read-interface</option>
          option.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <indexterm><primary><option>--source-css</option></primary></indexterm>
          <option>--source-css=<replaceable>style</replaceable></option>
        </term>
        <listitem>
          <para>Use custom CSS file for sources rendered by the
          <option>--hyperlinked-source</option> option. If no custom style
          file is provided, Haddock will use default one.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <indexterm><primary><option>-S</option></primary></indexterm>
          <option>-S</option>
        </term>
        <term>
          <indexterm><primary><option>--docbook</option></primary></indexterm>
          <option>--docbook</option>
        </term>
        <listitem>
          <para>Reserved for future use (output documentation in DocBook XML
          format).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <indexterm><primary><option>--source-base</option></primary></indexterm>
          <option>--source-base</option>=<replaceable>URL</replaceable>
        </term>
        <term>
          <indexterm><primary><option>--source-module</option></primary></indexterm>
          <option>--source-module</option>=<replaceable>URL</replaceable>
        </term>
        <term>
          <indexterm><primary><option>--source-entity</option></primary></indexterm>
          <option>--source-entity</option>=<replaceable>URL</replaceable>
        </term>
        <term>
          <indexterm><primary><option>--source-entity-line</option></primary></indexterm>
          <option>--source-entity-line</option>=<replaceable>URL</replaceable>
        </term>
        <listitem>
          <para>Include links to the source files in the generated
          documentation. Use the <option>--source-base</option> option to add a
          source code link in the header bar of the contents and index pages.
          Use the <option>--source-module</option> to add a source code link in
          the header bar of each module page. Use the
          <option>--source-entity</option> option to add a source code link
          next to the documentation for every value and type in each module.
          <option>--source-entity-line</option> is a flag that gets used for
          entities that need to link to an exact source location rather than a
          name, eg. since they were defined inside a Template Haskell splice.
          </para>

          <para>In each case <replaceable>URL</replaceable> is the base URL
          where the source files can be found.  For the per-module and
          per-entity URLs, the following substitutions are made within the
          string <replaceable>URL</replaceable>:</para>

          <itemizedlist>
            <listitem>
              <para>The string <literal>%M</literal> or <literal>%{MODULE}</literal>
              is replaced by the module name. Note that for the per-entity URLs
              this is the name of the <emphasis>exporting</emphasis> module.</para>
            </listitem>
            <listitem>
              <para>The string <literal>%F</literal> or <literal>%{FILE}</literal>
              is replaced by the original source file name. Note that for the
              per-entity URLs this is the name of the <emphasis>defining</emphasis>
              module.</para>
            </listitem>
            <listitem>
              <para>The string <literal>%N</literal> or <literal>%{NAME}</literal>
              is replaced by the name of the exported value or type. This is
              only valid for the <option>--source-entity</option> option.</para>
            </listitem>
            <listitem>
              <para>The string <literal>%K</literal> or <literal>%{KIND}</literal>
              is replaced by a flag indicating whether the exported name is a value
              '<literal>v</literal>' or a type '<literal>t</literal>'. This is
              only valid for the <option>--source-entity</option> option.</para>
            </listitem>
            <listitem>
              <para>The string <literal>%L</literal> or <literal>%{LINE}</literal>
              is replaced by the number of the line where the exported value or
              type is defined. This is only valid for the
              <option>--source-entity</option> option.</para>
            </listitem>
            <listitem>
              <para>The string <literal>%%</literal> is replaced by
              <literal>%</literal>.</para>
      </listitem>

          </itemizedlist>

          <para>For example, if your sources are online under some directory,
          you would say
          <literal>haddock --source-base=<replaceable>url</replaceable>/
          --source-module=<replaceable>url</replaceable>/%F</literal></para>

          <para>If you have html versions of your sources online with anchors
          for each type and function name, you would say
          <literal>haddock --source-base=<replaceable>url</replaceable>/
          --source-module=<replaceable>url</replaceable>/%M.html
          --source-entity=<replaceable>url</replaceable>/%M.html#%N</literal></para>

          <para>For the <literal>%{MODULE}</literal> substitution you may want to
          replace the '<literal>.</literal>' character in the module names with
          some other character (some web servers are known to get confused by
          multiple '<literal>.</literal>' characters in a file name). To
          replace it with a character <replaceable>c</replaceable> use
          <literal>%{MODULE/./<replaceable>c</replaceable>}</literal>.</para>

          <para>Similarly, for the <literal>%{FILE}</literal> substitution
          you may want to replace the '<literal>/</literal>' character in
          the file names with some other character (especially for links
          to colourised entity source code with a shared css file).  To replace
          it with a character <replaceable>c</replaceable> use
          <literal>%{FILE///<replaceable>c</replaceable>}</literal>/</para>

          <para>One example of a tool that can generate syntax-highlighted
          HTML from your source code, complete with anchors suitable for use
          from haddock, is
          <ulink url="http://www.cs.york.ac.uk/fp/darcs/hscolour">hscolour</ulink>.</para>

        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <indexterm><primary><option>-s</option></primary></indexterm>
          <option>-s</option> <replaceable>URL</replaceable>
        </term>
        <term>
          <indexterm><primary><option>--source</option></primary></indexterm>
          <option>--source</option>=<replaceable>URL</replaceable>
        </term>
        <listitem>
          <para>Deprecated aliases for <option>--source-module</option></para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <indexterm><primary><option>--comments-base</option></primary></indexterm>
          <option>--comments-base</option>=<replaceable>URL</replaceable>
        </term>
        <term>
          <indexterm><primary><option>--comments-module</option></primary></indexterm>
          <option>--comments-module</option>=<replaceable>URL</replaceable>
        </term>
        <term>
          <indexterm><primary><option>--comments-entity</option></primary></indexterm>
          <option>--comments-entity</option>=<replaceable>URL</replaceable>
        </term>
        <listitem>
          <para>Include links to pages where readers may comment on the
          documentation. This feature would typically be used in conjunction
          with a Wiki system.</para>

          <para>Use the <option>--comments-base</option> option to add a
          user comments link in the header bar of the contents and index pages.
          Use the <option>--comments-module</option> to add a user comments
          link in the header bar of each module page. Use the
          <option>--comments-entity</option> option to add a comments link
          next to the documentation for every value and type in each module.
          </para>

          <para>In each case <replaceable>URL</replaceable> is the base URL
          where the corresponding comments page can be found.  For the
          per-module and per-entity URLs the same substitutions are made as
          with the <option>--source-module</option> and
          <option>--source-entity</option> options above.</para>

          <para>For example, if you want to link the contents page to a wiki
          page, and every module to subpages, you would say
          <literal>haddock --comments-base=<replaceable>url</replaceable>
          --comments-module=<replaceable>url</replaceable>/%M</literal></para>

          <para>If your Wiki system doesn't like the '<literal>.</literal>' character
          in Haskell module names, you can replace it with a different character. For
          example to replace the '<literal>.</literal>' characters with
          '<literal>_</literal>' use <literal>haddock
          --comments-base=<replaceable>url</replaceable>
          --comments-module=<replaceable>url</replaceable>/%{MODULE/./_}</literal>
          Similarly, you can replace the '<literal>/</literal>' in a file name (may
          be useful for entity comments, but probably not.) </para>

        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <indexterm><primary><option>--theme</option></primary></indexterm>
          <option>--theme</option>=<replaceable>path</replaceable>
        </term>
        <listitem>
          <para>Specify a theme to be used for HTML (<option>--html</option>)
          documentation. If given multiple times then the pages will use the
          first theme given by default, and have alternate style sheets for
          the others. The reader can switch between themes with browsers that
          support alternate style sheets, or with the "Style" menu that gets
          added when the page is loaded. If
          no themes are specified, then just the default built-in theme
          ("Ocean") is used.
          </para>

          <para>The <replaceable>path</replaceable> parameter can be one of:
          </para>

          <itemizedlist>
            <listitem>
              <para>A <emphasis>directory</emphasis>: The base name of
              the directory becomes the name of the theme. The directory
              must contain exactly one
              <filename><replaceable>some</replaceable>.css</filename> file.
              Other files, usually image files, will be copied, along with
              the <filename><replaceable>some</replaceable>.css</filename>
              file, into the generated output directory.</para>
            </listitem>
            <listitem>
              <para>A <emphasis>CSS file</emphasis>: The base name of
              the file becomes the name of the theme.</para>
            </listitem>
            <listitem>
              <para>The <emphasis>name</emphasis> of a built-in theme
              ("Ocean" or "Classic").</para>
            </listitem>
          </itemizedlist>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <indexterm><primary><option>--built-in-themes</option></primary></indexterm>
          <option>--built-in-themes</option>
        </term>
        <listitem>
          <para>Includes the built-in themes ("Ocean" and "Classic").
          Can be combined with <option>--theme</option>. Note that order
          matters: The first specified theme will be the default.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <indexterm><primary><option>-c</option></primary></indexterm>
          <option>-c</option> <replaceable>file</replaceable>
        </term>
        <term>
          <indexterm><primary><option>--css</option></primary></indexterm>
          <option>--css</option>=<replaceable>file</replaceable>
        </term>
        <listitem>
          <para>Deprecated aliases for <option>--theme</option></para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <indexterm><primary><option>-p</option></primary></indexterm>
          <option>-p</option> <replaceable>file</replaceable>
        </term>
        <term>
          <indexterm><primary><option>--prologue</option></primary></indexterm>
          <option>--prologue</option>=<replaceable>file</replaceable>
        </term>
        <listitem>
          <para>Specify a file containing documentation which is
          placed on the main contents page under the heading
          &ldquo;Description&rdquo;.  The file is parsed as a normal
          Haddock doc comment (but the comment markers are not
          required).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <indexterm><primary><option>-t</option></primary></indexterm>
          <option>-t</option> <replaceable>title</replaceable>
        </term>
        <term>
          <indexterm><primary><option>--title</option></primary></indexterm>
          <option>--title</option>=<replaceable>title</replaceable>
        </term>
        <listitem>
          <para>Use <replaceable>title</replaceable> as the page
          heading for each page in the documentation.This will
          normally be the name of the library being documented.</para>

          <para>The title should be a plain string (no markup
          please!).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <indexterm><primary><option>-q</option></primary></indexterm>
          <option>-q</option> <replaceable>mode</replaceable>
        </term>
        <term>
          <indexterm><primary><option>--qual</option></primary></indexterm>
          <option>--qual</option>=<replaceable>mode</replaceable>
        </term>
        <listitem>
            <para>
                Specify how identifiers are qualified.
            </para>
            <para>
                <replaceable>mode</replaceable> should be one of
                <itemizedlist>
                    <listitem>
                        <para>none (default): don't qualify any identifiers</para>
                    </listitem>
                    <listitem>
                        <para>full: always qualify identifiers completely</para>
                    </listitem>
                    <listitem>
                        <para>local: only qualify identifiers that are not part
                            of the module</para>
                    </listitem>
                    <listitem>
                        <para>relative: like local, but strip name of the module
                            from qualifications of identifiers in submodules</para>
                    </listitem>
                </itemizedlist>
            </para>
            <para>
                Example: If you generate documentation for module A, then the
                identifiers A.x, A.B.y and C.z are qualified as follows.
            </para>
            <para>
                <itemizedlist>
                    <listitem>
                        <simpara>none: x, y, z</simpara>
                    </listitem>
                    <listitem>
                        <simpara>full: A.x, A.B.y, C.z</simpara>
                    </listitem>
                    <listitem>
                        <simpara>local: x, A.B.y, C.z</simpara>
                    </listitem>
                    <listitem>
                        <simpara>relative: x, B.y, C.z</simpara>
                    </listitem>
                </itemizedlist>
                </para>
            </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <indexterm><primary><option>-?</option></primary></indexterm>
          <option>-?</option>
        </term>
        <term>
          <indexterm><primary><option>--help</option></primary></indexterm>
          <option>--help</option>
        </term>
        <listitem>
          <para>Display help and exit.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <indexterm><primary><option>-V</option></primary></indexterm>
          <option>-V</option>
        </term>
        <term>
          <indexterm><primary><option>--version</option></primary></indexterm>
          <option>--version</option>
        </term>
        <listitem>
          <para>Output version information and exit.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <indexterm><primary><option>-v</option></primary></indexterm>
          <option>-v</option>
        </term>
        <term>
          <indexterm><primary><option>--verbose</option></primary></indexterm>
          <option>--verbose</option>
        </term>
        <listitem>
          <para>Increase verbosity.  Currently this will cause Haddock
          to emit some extra warnings, in particular about modules
          which were imported but it had no information about (this is
          often quite normal; for example when there is no information
          about the <literal>Prelude</literal>).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <indexterm><primary><option>--use-contents</option></primary></indexterm>
          <option>--use-contents=<replaceable>URL</replaceable></option>
        </term>
        <term>
          <indexterm><primary><option>--use-index</option></primary></indexterm>
          <option>--use-index=<replaceable>URL</replaceable></option>
        </term>
        <listitem>
          <para>When generating HTML, do not generate an index.
          Instead, redirect the Contents and/or Index link on each page to
          <replaceable>URL</replaceable>.  This option is intended for
          use in conjunction with <option>--gen-contents</option> and/or
          <option>--gen-index</option> for
          generating a separate contents and/or index covering multiple
          libraries.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <indexterm><primary><option>--gen-contents</option></primary></indexterm>
          <option>--gen-contents</option>
        </term>
        <term>
          <indexterm><primary><option>--gen-index</option></primary></indexterm>
          <option>--gen-index</option>
        </term>
        <listitem>
          <para>Generate an HTML contents and/or index containing entries pulled
          from all the specified interfaces (interfaces are specified using
          <option>-i</option> or <option>--read-interface</option>).
          This is used to generate a single contents and/or index for multiple
          sets of Haddock documentation.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <indexterm><primary><option>--ignore-all-exports</option></primary>
          </indexterm>
          <option>--ignore-all-exports</option>
        </term>
        <listitem>
          <para>Causes Haddock to behave as if every module has the
            <literal>ignore-exports</literal> attribute (<xref
              linkend="module-attributes" />).  This might be useful for
            generating implementation documentation rather than interface
            documentation, for example.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <indexterm><primary><option>--hide</option></primary>
          </indexterm>
          <option>--hide</option>&nbsp;<replaceable>module</replaceable>
        </term>
        <listitem>
          <para>Causes Haddock to behave as if module
            <replaceable>module</replaceable> has the <literal>hide</literal>
            attribute. (<xref linkend="module-attributes" />).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <indexterm><primary><option>--show-extensions</option></primary>
          </indexterm>
          <option>--show-extensions</option>&nbsp;<replaceable>module</replaceable>
        </term>
        <listitem>
          <para>Causes Haddock to behave as if module
            <replaceable>module</replaceable> has the <literal>show-extensions</literal>
            attribute. (<xref linkend="module-attributes" />).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <indexterm><primary><option>--optghc</option></primary></indexterm>
          <option>--optghc</option>=<replaceable>option</replaceable>
        </term>
        <listitem>
          <para>Pass <replaceable>option</replaceable> to GHC. Note that there is a double dash there, unlike for GHC.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <indexterm><primary><option>-w</option></primary></indexterm>
          <option>-w</option>
        </term>
        <term>
          <indexterm><primary><option>--no-warnings</option></primary></indexterm>
          <option>--no-warnings</option>
        </term>
        <listitem>
          <para>Turn off all warnings.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <indexterm><primary><option>--compatible-interface-versions</option></primary></indexterm>
          <option>--compatible-interface-versions</option>
        </term>
        <listitem>
          <para>
            Prints out space-separated versions of binary Haddock interface files that this version is compatible
            with.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <indexterm><primary><option>--no-tmp-comp-dir</option></primary></indexterm>
          <option>--no-tmp-comp-dir</option>
        </term>
        <listitem>
          <para>
          Do not use a temporary directory for reading and writing compilation output files
          (<literal>.o</literal>, <literal>.hi</literal>, and stub files). Instead, use the
          present directory or another directory that you have explicitly told GHC to use
          via the <literal>--optghc</literal> flag.
          </para>
          <para>
          This flag can be used to avoid recompilation if compilation files already exist.
          Compilation files are produced when Haddock has to process modules that make use of
          Template Haskell, in which case Haddock compiles the modules using the GHC API.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <indexterm><primary><option>--print-missing-docs</option></primary></indexterm>
          <option>--print-missing-docs</option>
        </term>
        <listitem>
          <para>
          Print extra information about any undocumented entities.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>

    <section id="cpp">
      <title>Using literate or pre-processed source</title>

      <para>Since Haddock uses GHC internally, both plain and
            literate Haskell sources are accepted without the need for the user
            to do anything. To use the C pre-processor, however,
            the user must pass the the <option>-cpp</option> option to GHC
            using <option>--optghc</option>.
      </para>
    </section>

  </chapter>

  <chapter id="markup">
    <title>Documentation and Markup</title>

    <para>Haddock understands special documentation annotations in the
    Haskell source file and propagates these into the generated
    documentation.  The annotations are purely optional: if there are
    no annotations, Haddock will just generate documentation that
    contains the type signatures, data type declarations, and class
    declarations exported by each of the modules being
    processed.</para>

    <section>
      <title>Documenting a top-level declaration</title>

      <para>The simplest example of a documentation annotation is for
      documenting any top-level declaration (function type signature,
      type declaration, or class declaration).  For example, if the
      source file contains the following type signature:</para>

<programlisting>
square :: Int -> Int
square x = x * x
</programlisting>

    <para>Then we can document it like this:</para>

<programlisting>
-- |The 'square' function squares an integer.
square :: Int -> Int
square x = x * x
</programlisting>


      <para>The <quote><literal>-- |</literal></quote> syntax begins a
      documentation annotation, which applies to the
      <emphasis>following</emphasis> declaration in the source file.
      Note that the annotation is just a comment in Haskell &mdash; it
      will be ignored by the Haskell compiler.</para>

      <para>The declaration following a documentation annotation
      should be one of the following:</para>
      <itemizedlist>
        <listitem>
          <para>A type signature for a top-level function,</para>
        </listitem>
        <listitem>
          <para>A <literal>data</literal> declaration,</para>
        </listitem>
        <listitem>
          <para>A <literal>newtype</literal> declaration,</para>
        </listitem>
        <listitem>
          <para>A <literal>type</literal> declaration</para>
        </listitem>
        <listitem>
          <para>A <literal>class</literal> declaration,</para>
        </listitem>
        <listitem>
          <para>A <literal>data family</literal> or
            <literal>type family</literal> declaration, or</para>
        </listitem>
        <listitem>
          <para>A <literal>data instance</literal> or
            <literal>type instance</literal> declaration.</para>
        </listitem>
      </itemizedlist>

      <para>If the annotation is followed by a different kind of
      declaration, it will probably be ignored by Haddock.</para>

      <para>Some people like to write their documentation
      <emphasis>after</emphasis> the declaration; this is possible in
      Haddock too:</para>

<programlisting>
square :: Int -> Int
-- ^The 'square' function squares an integer.
square x = x * x
</programlisting>

      <para>Note that Haddock doesn't contain a Haskell type system
      &mdash; if you don't write the type signature for a function,
      then Haddock can't tell what its type is and it won't be
      included in the documentation.</para>

      <para>Documentation annotations may span several lines; the
      annotation continues until the first non-comment line in the
      source file.  For example:</para>

<programlisting>
-- |The 'square' function squares an integer.
-- It takes one argument, of type 'Int'.
square :: Int -> Int
square x = x * x
</programlisting>

      <para>You can also use Haskell's nested-comment style for
      documentation annotations, which is sometimes more convenient
      when using multi-line comments:</para>

<programlisting>
{-|
  The 'square' function squares an integer.
  It takes one argument, of type 'Int'.
-}
square :: Int -> Int
square x = x * x
</programlisting>

    </section>
    <section>
      <title>Documenting parts of a declaration</title>

      <para>In addition to documenting the whole declaration, in some
      cases we can also document individual parts of the
      declaration.</para>

      <section>
        <title>Class methods</title>

        <para>Class methods are documented in the same way as top
        level type signatures, by using either the
        <quote><literal>--&nbsp;|</literal></quote> or
        <quote><literal>--&nbsp;^</literal></quote>
        annotations:</para>

<programlisting>
class C a where
   -- | This is the documentation for the 'f' method
   f :: a -> Int
   -- | This is the documentation for the 'g' method
   g :: Int -> a
</programlisting>
      </section>

      <section>
        <title>Constructors and record fields</title>

        <para>Constructors are documented like so:</para>

<programlisting>
data T a b
  -- | This is the documentation for the 'C1' constructor
  = C1 a b
  -- | This is the documentation for the 'C2' constructor
  | C2 a b
</programlisting>

        <para>or like this:</para>

<programlisting>
data T a b
  = C1 a b  -- ^ This is the documentation for the 'C1' constructor
  | C2 a b  -- ^ This is the documentation for the 'C2' constructor
</programlisting>

        <para>Record fields are documented using one of these
        styles:</para>

<programlisting>
data R a b =
  C { -- | This is the documentation for the 'a' field
      a :: a,
      -- | This is the documentation for the 'b' field
      b :: b
    }

data R a b =
  C { a :: a  -- ^ This is the documentation for the 'a' field
    , b :: b  -- ^ This is the documentation for the 'b' field
    }
</programlisting>

        <para>Alternative layout styles are generally accepted by
        Haddock - for example doc comments can appear before or after
        the comma in separated lists such as the list of record fields
        above.</para>

        <para>In case that more than one constructor exports a field
        with the same name, the documentation attached to the first
        occurence of the field will be used, even if a comment is not
        present.
        </para>

<programlisting>
data T a = A { someField :: a -- ^ Doc for someField of A
             }
         | B { someField :: a -- ^ Doc for someField of B
             }
</programlisting>

        <para>In the above example, all occurences of
        <literal>someField</literal> in the documentation are going to
        be documented with <literal>Doc for someField of A</literal>.
        Note that Haddock versions 2.14.0 and before would join up
        documentation of each field and render the result. The reason
        for this seemingly weird behaviour is the fact that
        <literal>someField</literal> is actually the same (partial)
        function.</para>

      </section>

      <section>
        <title>Function arguments</title>

        <para>Individual arguments to a function may be documented
        like this:</para>

<programlisting>
f  :: Int      -- ^ The 'Int' argument
   -> Float    -- ^ The 'Float' argument
   -> IO ()    -- ^ The return value
</programlisting>
      </section>
    </section>

    <section>
      <title>The module description</title>

      <para>A module itself may be documented with multiple fields
      that can then be displayed by the backend. In particular, the
      HTML backend displays all the fields it currently knows
      about. We first show the most complete module documentation
      example and then talk about the fields.</para>

<programlisting>
{-|
Module      : W
Description : Short description
Copyright   : (c) Some Guy, 2013
                  Someone Else, 2014
License     : GPL-3
Maintainer  : sample@email.com
Stability   : experimental
Portability : POSIX

Here is a longer description of this module, containing some
commentary with @some markup@.
-}
module W where
...
</programlisting>

      <para>The <quote>Module</quote> field should be clear. It
      currently doesn't affect the output of any of the backends but
      you might want to include it for human information or for any
      other tools that might be parsing these comments without the
      help of GHC.</para>

      <para>The <quote>Description</quote> field accepts some short text
      which outlines the general purpose of the module. If you're
      generating HTML, it will show up next to the module link in
      the module index.</para>

      <para>The <quote>Copyright</quote>, <quote>License</quote>,
      <quote>Maintainer</quote> and <quote>Stability</quote> fields
      should be obvious. An alternative spelling for the
      <quote>License</quote> field is accepted as
      <quote>Licence</quote> but the output will always prefer
      <quote>License</quote>.</para>

      <para>The <quote>Portability</quote> field has seen varied use
      by different library authors. Some people put down things like
      operating system constraints there while others put down which GHC
      extensions are used in the module. Note that you might want to
      consider using the <quote>show-extensions</quote> module flag for the
      latter.</para>

      <para>Finally, a module may contain a documentation comment
      before the module header, in which case this comment is
      interpreted by Haddock as an overall description of the module
      itself, and placed in a section entitled
      <quote>Description</quote> in the documentation for the module.
      All usual Haddock markup is valid in this comment.</para>

      <para>All fields are optional but they must be in order if they
      do appear. Multi-line fields are accepted but the consecutive
      lines have to start indented more than their label. If your
      label is indented one space as is often the case with
      <quote>--</quote> syntax, the consecutive lines have to start at
      two spaces at the very least. Please note that we do not enforce
      the format for any of the fields and the established formats are
      just a convention.</para>

    </section>

    <section>
      <title>Controlling the documentation structure</title>

      <para>Haddock produces interface documentation that lists only
      the entities actually exported by the module.  The documentation
      for a module will include <emphasis>all</emphasis> entities
      exported by that module, even if they were re-exported by
      another module.  The only exception is when Haddock can't see
      the declaration for the re-exported entity, perhaps because it
      isn't part of the batch of modules currently being
      processed.</para>

      <para>However, to Haddock the export list has even more
      significance than just specifying the entities to be included in
      the documentation.  It also specifies the
      <emphasis>order</emphasis> that entities will be listed in the
      generated documentation.  This leaves the programmer free to
      implement functions in any order he/she pleases, and indeed in
      any <emphasis>module</emphasis> he/she pleases, but still
      specify the order that the functions should be documented in the
      export list.  Indeed, many programmers already do this: the
      export list is often used as a kind of ad-hoc interface
      documentation, with headings, groups of functions, type
      signatures and declarations in comments.</para>

      <para>You can insert headings and sub-headings in the
      documentation by including annotations at the appropriate point
      in the export list.  For example:</para>

<programlisting>
module Foo (
  -- * Classes
  C(..),
  -- * Types
  -- ** A data type
  T,
  -- ** A record
  R,
  -- * Some functions
  f, g
  ) where
</programlisting>

      <para>Headings are introduced with the syntax
      <quote><literal>--&nbsp;*</literal></quote>,
      <quote><literal>--&nbsp;**</literal></quote> and so on, where
      the number of <literal>*</literal>s indicates the level of the
      heading (section, sub-section, sub-sub-section, etc.).</para>

      <para>If you use section headings, then Haddock will generate a
      table of contents at the top of the module documentation for
      you.</para>

      <para>The alternative style of placing the commas at the
      beginning of each line is also supported. eg.:</para>

<programlisting>
module Foo (
  -- * Classes
  , C(..)
  -- * Types
  -- ** A data type
  , T
  -- ** A record
  , R
  -- * Some functions
  , f
  , g
  ) where
</programlisting>

      <section>
        <title>Re-exporting an entire module</title>

        <para>Haskell allows you to re-export the entire contents of a
        module (or at least, everything currently in scope that was
        imported from a given module) by listing it in the export
        list:</para>

<programlisting>
module A (
  module B,
  module C
 ) where
</programlisting>

        <para>What will the Haddock-generated documentation for this
        module look like?  Well, it depends on how the modules
        <literal>B</literal> and <literal>C</literal> are imported.
        If they are imported wholly and without any
        <literal>hiding</literal> qualifiers, then the documentation
        will just contain a cross-reference to the documentation for
        <literal>B</literal> and <literal>C</literal>.  However, if
        the modules are not <emphasis>completely</emphasis>
        re-exported, for example:</para>

<programlisting>
module A (
  module B,
  module C
 ) where

import B hiding (f)
import C (a, b)
</programlisting>

        <para>then Haddock behaves as if the set of entities
        re-exported from <literal>B</literal> and <literal>C</literal>
        had been listed explicitly in the export
        list<footnote><para>NOTE: this is not fully implemented at the
        time of writing (version 0.2).  At the moment, Haddock always
        inserts a cross-reference.</para>
          </footnote>.</para>

        <para>The exception to this rule is when the re-exported
        module is declared with the <literal>hide</literal> attribute
        (<xref linkend="module-attributes"/>), in which case the module
        is never cross-referenced; the contents are always expanded in
        place in the re-exporting module.</para>
      </section>

      <section>
        <title>Omitting the export list</title>

        <para>If there is no export list in the module, how does
        Haddock generate documentation?  Well, when the export list is
        omitted, e.g.:</para>

<programlisting>module Foo where</programlisting>

        <para>this is equivalent to an export list which mentions
        every entity defined at the top level in this module, and
        Haddock treats it in the same way.  Furthermore, the generated
        documentation will retain the order in which entities are
        defined in the module.  In this special case the module body
        may also include section headings (normally they would be
        ignored by Haddock).</para>

<programlisting>
module Foo where

-- * This heading will now appear before foo.

-- | Documentation for 'foo'.
foo :: Integer
foo = 5
</programlisting>

      </section>
    </section>

    <section>
      <title>Named chunks of documentation</title>

      <para>Occasionally it is desirable to include a chunk of
      documentation which is not attached to any particular Haskell
      declaration.  There are two ways to do this:</para>

      <itemizedlist>
        <listitem>
          <para>The documentation can be included in the export list
          directly, e.g.:</para>

<programlisting>
module Foo (
   -- * A section heading

   -- | Some documentation not attached to a particular Haskell entity
   ...
 ) where
</programlisting>
        </listitem>

        <listitem>
          <para>If the documentation is large and placing it inline in
          the export list might bloat the export list and obscure the
          structure, then it can be given a name and placed out of
          line in the body of the module.  This is achieved with a
          special form of documentation annotation
          <quote><literal>--&nbsp;$</literal></quote>:</para>

<programlisting>
module Foo (
   -- * A section heading

   -- $doc
   ...
 ) where

-- $doc
-- Here is a large chunk of documentation which may be referred to by
-- the name $doc.
</programlisting>

          <para>The documentation chunk is given a name, which is the
          sequence of alphanumeric characters directly after the
          <quote><literal>--&nbsp;$</literal></quote>, and it may be
          referred to by the same name in the export list.</para>
        </listitem>
      </itemizedlist>
    </section>

    <section id="hyperlinking">
      <title>Hyperlinking and re-exported entities</title>

      <para>When Haddock renders a type in the generated
      documentation, it hyperlinks all the type constructors and class
      names in that type to their respective definitions.  But for a
      given type constructor or class there may be several modules
      re-exporting it, and therefore several modules whose
      documentation contains the definition of that type or class
      (possibly including the current module!) so which one do we link
      to?</para>

      <para>Let's look at an example.  Suppose we have three modules
      <literal>A</literal>, <literal>B</literal> and
      <literal>C</literal> defined as follows:</para>

<programlisting>
module A (T) where
data T a = C a

module B (f) where
import A
f :: T Int -> Int
f (C i) = i

module C (T, f) where
import A
import B
</programlisting>

      <para>Module <literal>A</literal> exports a datatype
      <literal>T</literal>.  Module <literal>B</literal> imports
      <literal>A</literal> and exports a function <literal>f</literal>
      whose type refers to <literal>T</literal>.  Also, both
        <literal>T</literal> and <literal>f</literal> are re-exported from
        module C.</para>

      <para>Haddock takes the view that each entity has a
        <emphasis>home</emphasis> module; that is, the module that the library
        designer would most like to direct the user to, to find the
        documentation for that entity.  So, Haddock makes all links to an entity
        point to the home module.  The one exception is when the entity is also
      exported by the current module: Haddock makes a local link if it
        can.</para>

      <para>How is the home module for an entity determined?
        Haddock uses the following rules:</para>

      <itemizedlist>
        <listitem>
          <para>If modules A and B both export the entity, and module A imports
            (directly or indirectly) module B, then B is preferred.</para>
        </listitem>
        <listitem>
          <para>A module with the <literal>hide</literal> attribute is never
            chosen as the home.</para>
        </listitem>
        <listitem>
          <para>A module with the <literal>not-home</literal> attribute is only
            chosen if there are no other modules to choose.</para>
        </listitem>
      </itemizedlist>

      <para>If multiple modules fit the criteria, then one is chosen at
        random.  If no modules fit the criteria (because the candidates are all
      hidden), then Haddock will issue a warning for each reference to an
        entity without a home.</para>

      <para>In the example above, module <literal>A</literal> is chosen as the
        home for <literal>T</literal> because it does not import any other
        module that exports <literal>T</literal>.  The link from
        <literal>f</literal>'s
        type in module <literal>B</literal> will therefore point to
        <literal>A.T</literal>.  However, <literal>C</literal> also exports
        <literal>T</literal> and <literal>f</literal>, and the link from
        <literal>f</literal>'s type in <literal>C</literal> will therefore
        point locally to <literal>C.T</literal>.</para>
    </section>

    <section id="module-attributes">
      <title>Module Attributes</title>

      <para>Certain attributes may be specified for each module which
      affects the way that Haddock generates documentation for that
      module.  Attributes are specified in a comma-separated list in an
      <literal>{-# OPTIONS_HADDOCK ... #-}</literal> pragma at the
      top of the module, either before or after the module
      description.  For example:</para>

<programlisting>
{-# OPTIONS_HADDOCK hide, prune, ignore-exports #-}

-- |Module description
module A where
...
</programlisting>

      <para>The options and module description can be in either order.</para>

      <para>The following attributes are currently understood by
      Haddock:</para>

      <variablelist>
        <varlistentry>
          <term>
            <indexterm><primary><literal>hide</literal></primary></indexterm>
            <literal>hide</literal>
          </term>
          <listitem>
            <para>Omit this module from the generated documentation,
            but nevertheless propagate definitions and documentation
            from within this module to modules that re-export those
            definitions.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <indexterm><primary><literal>hide</literal></primary></indexterm>
            <literal>prune</literal>
          </term>
          <listitem>
            <para>Omit definitions that have no documentation
            annotations from the generated documentation.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <indexterm><primary><literal>ignore-exports</literal></primary></indexterm>
            <literal>ignore-exports</literal>
          </term>
          <listitem>
            <para>Ignore the export list.  Generate documentation as
            if the module had no export list - i.e. all the top-level
            declarations are exported, and section headings may be
            given in the body of the module.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <indexterm><primary><literal>not-home</literal></primary></indexterm>
      <literal>not-home</literal>
          </term>
          <listitem>
            <para>Indicates that the current module should not be considered to
              be the home module for each entity it exports,
              unless that entity is not exported from any other module.  See
              <xref linkend="hyperlinking" /> for more details.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <indexterm><primary><literal>show-extensions</literal></primary></indexterm>
      <literal>show-extensions</literal>
          </term>
          <listitem>
            <para>Indicates that we should render the extensions used in this module in the
            resulting documentation. This will only render if the output format supports it.
            If Language is set, it will be shown as well and all the extensions implied by it won't.
            All enabled extensions will be rendered, including those implied by their more powerful versions.</para>
          </listitem>
        </varlistentry>

      </variablelist>

    </section>

    <section>
      <title>Markup</title>

      <para>Haddock understands certain textual cues inside
      documentation annotations that tell it how to render the
      documentation.  The cues (or <quote>markup</quote>) have been
      designed to be simple and mnemonic in ASCII so that the
      programmer doesn't have to deal with heavyweight annotations
      when editing documentation comments.</para>

      <section>
        <title>Paragraphs</title>

        <para>One or more blank lines separates two paragraphs in a
        documentation comment.</para>
      </section>

      <section>
        <title>Special characters</title>

        <para>The following characters have special meanings in
        documentation comments: <literal>\</literal>, <literal>/</literal>,
        <literal>'</literal>, <literal>`</literal>,
        <literal>"</literal>, <literal>@</literal>,
        <literal>&lt;</literal>.  To insert a literal occurrence of
        one of these special characters, precede it with a backslash
        (<literal>\</literal>).</para>

        <para>Additionally, the character <literal>&gt;</literal> has
        a special meaning at the beginning of a line, and the
        following characters have special meanings at the beginning of
        a paragraph:
        <literal>*</literal>, <literal>-</literal>.  These characters
        can also be escaped using <literal>\</literal>.</para>

        <para>Furthermore, the character sequence <literal>&gt;&gt;&gt;</literal>
        has a special meaning at the beginning of a line. To
        escape it, just prefix the characters in the sequence with a
        backslash.</para>
      </section>

      <section>
        <title>Character references</title>

        <para>Although Haskell source files may contain any character
        from the Unicode character set, the encoding of these characters
        as bytes varies between systems, so that only source files
        restricted to the ASCII character set are portable.  Other
        characters may be specified in character and string literals
        using Haskell character escapes.  To represent such characters
        in documentation comments, Haddock supports SGML-style numeric
        character references of the forms
        <literal>&amp;#</literal><replaceable>D</replaceable><literal>;</literal>
        and
        <literal>&amp;#x</literal><replaceable>H</replaceable><literal>;</literal>
        where <replaceable>D</replaceable> and <replaceable>H</replaceable>
        are decimal and hexadecimal numbers denoting a code position
        in Unicode (or ISO 10646).  For example, the references
        <literal>&amp;#x3BB;</literal>, <literal>&amp;#x3bb;</literal>
        and <literal>&amp;#955;</literal> all represent the lower-case
        letter lambda.</para>
      </section>

      <section>
        <title>Code Blocks</title>

        <para>Displayed blocks of code are indicated by surrounding a
        paragraph with <literal>@...@</literal> or by preceding each
        line of a paragraph with <literal>&gt;</literal> (we often
        call these &ldquo;bird tracks&rdquo;).  For
        example:</para>

<programlisting>
-- | This documentation includes two blocks of code:
--
-- @
--     f x = x + x
-- @
--
-- &gt;  g x = x * 42
</programlisting>

        <para>There is an important difference between the two forms
        of code block: in the bird-track form, the text to the right
        of the &lsquo;<literal>></literal>&rsquo; is interpreted
        literally, whereas the <literal>@...@</literal> form
        interprets markup as normal inside the code block.</para>
      </section>

      <section>
        <title>Examples</title>

        <para> Haddock has markup support for examples of interaction with a
  <emphasis>read-eval-print loop (REPL)</emphasis>.  An
        example is introduced with
        <literal>&gt;&gt;&gt;</literal> followed by an expression followed
        by zero or more result lines:</para>

<programlisting>
-- | Two examples are given below:
--
-- &gt;&gt;&gt; fib 10
-- 55
--
-- &gt;&gt;&gt; putStrLn "foo\nbar"
-- foo
-- bar
</programlisting>
        <para>Result lines that only contain the string
        <literal>&lt;BLANKLINE&gt;</literal> are rendered as blank lines in the
        generated documentation.</para>
      </section>

      <section>
        <title>Properties</title>
        <para>
          Haddock provides markup for properties:
<programlisting>
-- | Addition is commutative:
--
-- prop> a + b = b + a
</programlisting>
          This allows third-party applications to extract and verify them.
        </para>
      </section>

      <section>
        <title>Hyperlinked Identifiers</title>

        <para>Referring to a Haskell identifier, whether it be a type,
        class, constructor, or function, is done by surrounding it
        with single quotes:</para>

<programlisting>
-- | This module defines the type 'T'.
</programlisting>

        <para>If there is an entity <literal>T</literal> in scope in
        the current module, then the documentation will hyperlink the
        reference in the text to the definition of
        <literal>T</literal> (if the output format supports
        hyperlinking, of course; in a printed format it might instead
        insert a page reference to the definition).</para>

        <para>It is also possible to refer to entities that are not in
        scope in the current module, by giving the full qualified name
        of the entity:</para>

<programlisting>
-- | The identifier 'M.T' is not in scope
</programlisting>

        <para>If <literal>M.T</literal> is not otherwise in scope,
        then Haddock will simply emit a link pointing to the entity
        <literal>T</literal> exported from module <literal>M</literal>
        (without checking to see whether either <literal>M</literal>
        or <literal>M.T</literal> exist).</para>

        <para>To make life easier for documentation writers, a quoted
        identifier is only interpreted as such if the quotes surround
        a lexically valid Haskell identifier.  This means, for
        example, that it normally isn't necessary to escape the single
        quote when used as an apostrophe:</para>

<programlisting>
-- | I don't have to escape my apostrophes; great, isn't it?
</programlisting>

        <para>Nothing special is needed to hyperlink identifiers which
        contain apostrophes themselves: to hyperlink
        <literal>foo'</literal> one would simply type
        <literal>'foo''</literal>. To hyperlink identifiers written in
        infix form, simply put them in quotes as always:
        <literal>'`elem`'</literal>.</para>

        <para>For compatibility with other systems, the following
        alternative form of markup is accepted<footnote><para>
        We chose not to use this as the primary markup for
        identifiers because strictly speaking the <literal>`</literal>
        character should not be used as a left quote, it is a grave accent.</para>
          </footnote>: <literal>`T'</literal>.</para>
      </section>

      <section>
        <title>Emphasis, Bold and Monospaced text</title>

        <para>Emphasis may be added by surrounding text with
        <literal>/.../</literal>. Other markup is valid inside emphasis. To have a forward
        slash inside of emphasis, just escape it: <literal>/fo\/o/</literal></para>

        <para>Bold (strong) text is indicated by surrounding it with <literal>__...__</literal>.
        Other markup is valid inside bold. For example, <literal>__/foo/__</literal> will make the emphasised
        text <literal>foo</literal> bold. You don't have to escape a single underscore if you need it bold:
        <literal>__This_text_with_underscores_is_bold__</literal>.
        </para>

        <para>Monospaced (or typewriter) text is indicated by
        surrounding it with <literal>@...@</literal>.  Other markup is
        valid inside a monospaced span: for example
        <literal>@'f'&nbsp;a&nbsp;b@</literal> will hyperlink the
        identifier <literal>f</literal> inside the code fragment.</para>
      </section>

      <section>
        <title>Linking to modules</title>

        <para>Linking to a module is done by surrounding the module
        name with double quotes:</para>

<programlisting>
-- | This is a reference to the "Foo" module.
</programlisting>

        <para>A basic check is done on the syntax of the header name to ensure that it is valid
        before turning it into a link but unlike with identifiers, whether the module is in scope isn't checked
        and will always be turned into a link.
        </para>

      </section>

      <section>
        <title>Itemized and Enumerated lists</title>

        <para>A bulleted item is represented by preceding a paragraph
        with either <quote><literal>*</literal></quote> or
        <quote><literal>-</literal></quote>.  A sequence of bulleted
        paragraphs is rendered as an itemized list in the generated
        documentation, eg.:</para>

<programlisting>
-- | This is a bulleted list:
--
--     * first item
--
--     * second item
</programlisting>

        <para>An enumerated list is similar, except each paragraph
        must be preceded by either
        <quote><literal>(<replaceable>n</replaceable>)</literal></quote>
        or
        <quote><literal><replaceable>n</replaceable>.</literal></quote>
        where <replaceable>n</replaceable> is any integer.  e.g.</para>

<programlisting>
-- | This is an enumerated list:
--
--     (1) first item
--
--     2. second item
</programlisting>

      <para>Lists of the same type don't have to be separated by a newline:</para>
<programlisting>
-- | This is an enumerated list:
--
--     (1) first item
--     2. second item
--
-- This is a bulleted list:
--
--     * first item
--     * second item
</programlisting>

      <para>You can have more than one line of content in a list element:
      </para>
<programlisting>
-- |
-- * first item
-- and more content for the first item
-- * second item
-- and more content for the second item
</programlisting>

     <para>You can even nest whole paragraphs inside of list elements. The rules
     are 4 spaces for each indentation level. You're required to use a newline before
     such nested paragraph:
     </para>
<programlisting>
{-|
* Beginning of list
This belongs to the list above!

    > nested
    > bird
    > tracks

    * Next list
    More of the indented list.

        * Deeper

            @
            even code blocks work
            @

            * Deeper

                    1. Even deeper!
                    2. No newline separation even in indented lists.
-}
</programlisting>
    <para>The indentation of the first list item is honoured. That is,
    in the following example the items are on the same level. Before
    Haddock 2.16.1, the second item would have been nested under the
    first item which was unexpected.
    </para>
<programlisting>
{-|
    * foo

    * bar
-}
</programlisting>
      </section>

      <section>
        <title>Definition lists</title>

        <para>Definition lists are written as follows:</para>

<programlisting>
-- | This is a definition list:
--
--   [@foo@]: The description of @foo@.
--
--   [@bar@]: The description of @bar@.
</programlisting>

        <para>To produce output something like this:</para>

        <variablelist>
          <varlistentry>
            <term><literal>foo</literal></term>
            <listitem>
              <para>The description of <literal>foo</literal>.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><literal>bar</literal></term>
            <listitem>
              <para>The description of <literal>bar</literal>.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <para>Each paragraph should be preceded by the
        &ldquo;definition term&rdquo; enclosed in square brackets and followed by a colon.
        Other markup operators may be used freely within the
        definition term. You can escape <literal>]</literal> with a backslash as usual.</para>

      <para>Same rules about nesting and no newline separation as for bulleted and numbered lists apply.
      </para>

      </section>

      <section>
        <title>URLs</title>

        <para>
          A URL can be included in a documentation comment by surrounding it in
          angle brackets, for example:
        </para>

<programlisting>
&lt;http://example.com&gt;
</programlisting>

        <para>
          If the output format supports it, the URL will be turned into a
          hyperlink when rendered.
        </para>

        <para>If Haddock sees something that looks like a URL (such as something starting with
        <literal>http://</literal> or <literal>ssh://</literal>) where the URL markup is valid,
        it will automatically make it a hyperlink.</para>
      </section>

      <section>
        <title>Links</title>

        <para>
          Haddock supports Markdown syntax for inline links.  A link consists
          of a link text and a URL.  The link text is enclosed in square
          brackets and followed by the URL enclosed in regular parentheses, for
          example:
        </para>

<programlisting>
[some link](http://example.com)
</programlisting>
        <para>
          The link text is used as a descriptive text for the URL, if the
          output format supports it.
        </para>
      </section>

      <section>
        <title>Images</title>
        <para>
            Haddock supports Markdown syntax for inline images.  This resembles
            the syntax for links, but starts with an exclamation mark.  An
            example looks like this:
        </para>

<programlisting>
![image description](pathtoimage.png)
</programlisting>
        <para>
          If the output format supports it, the image will be rendered inside
          the documentation.  The image description is used as relpacement text
          and/or image title.
        </para>
      </section>

      <section>
        <title>Anchors</title>

        <para>Sometimes it is useful to be able to link to a point in
        the documentation which doesn't correspond to a particular
        entity.  For that purpose, we allow <emphasis>anchors</emphasis> to be
        included in a documentation comment.  The syntax is
        <literal>#<replaceable>label</replaceable>#</literal>, where
        <replaceable>label</replaceable> is the name of the anchor.
        An anchor is invisible in the generated documentation.</para>

        <para>To link to an anchor from elsewhere, use the syntax
        <literal>"<replaceable>module</replaceable>#<replaceable>label</replaceable>"</literal>
        where <replaceable>module</replaceable> is the module name
        containing the anchor, and <replaceable>label</replaceable> is
        the anchor label. The module does not have to be local, it can
        be imported via an interface. Please note that in Haddock
        versions 2.13.x and earlier, the syntax was
        <literal>"<replaceable>module</replaceable>\#<replaceable>label</replaceable>"</literal>.
        It is considered deprecated and will be removed in the future.</para>
      </section>

      <section>
        <title>Headings</title>
        <para>Headings inside of comment documentation are possible be preceding them with
        a number of <literal>=</literal>s. From 1 to 6 are accepted. Extra <literal>=</literal>s will
        be treated as belonging to the text of the heading. Note that it's up to the output format to decide
        how to render the different levels.
        </para>

<programlisting>
-- |
-- = Heading level 1 with some /emphasis/
-- Something underneath the heading.
--
-- == /Subheading/
-- More content.
--
-- === Subsubheading
-- Even more content.
</programlisting>

        <para>Note that while headings have to start on a new paragraph, we allow paragraph-level content to
        follow these immediately.
        </para>

<programlisting>
-- |
-- = Heading level 1 with some __bold__
-- Something underneath the heading.
--
-- == /Subheading/
-- More content.
--
-- === Subsubheading
-- >>> examples are only allowed at the start of paragraphs
</programlisting>

        <para>As of 2.15.1, there's experimental (read: subject to
        change or get removed) support for collapsible headers: simply
        wrap your existing header title in underscores, as per bold
        syntax. The collapsible section will stretch until the end of
        the comment or until a header of equal or smaller number of
        <literal>=</literal>s.</para>

<programlisting>
-- |
-- === __Examples:__
-- >>> Some very long list of examples
--
-- ==== This still falls under the collapse
-- Some specialised examples
--
-- === This is does not go into the collapsable section.
-- More content.
</programlisting>

      </section>

      <section>
        <title>Metadata</title>
        <para>Since Haddock 2.16.0, some support for embedding
        metadata in the comments has started to appear. The use of
        such data aims to standardise various community conventions in
        how such information is conveyed and to provide uniform
        rendering.
        </para>

        <section>
          <title>Since</title>
          <para><literal>@since</literal> annotation can be used to
          convey information about when the function was introduced or
          when it has changed in the way significant to the user.
          <literal>@since</literal> is a paragraph-level element.
          While multiple such annotations are not an error, only the
          one to appear in the comment last will be used.
          <literal>@since</literal> has to be followed with a version
          number, no further description is currently allowed. The
          meaning of this feature is subject to change in the future
          per user feedback.
          </para>

<programlisting>
-- |
-- Some comment
--
-- @since 1.2.3
</programlisting>

        </section>

      </section>

    </section>
  </chapter>
  <index/>
</book>