Skip to content
Snippets Groups Projects

Compare revisions

Changes are shown as if the source revision was being merged into the target revision. Learn more about comparing revisions.

Source

Select target project
No results found

Target

Select target project
  • rae/haddock
  • sjakobi/haddock
  • RyanGlScott/haddock
  • mynguyenbmc/haddock
  • kcsongor/haddock
  • wz1000/haddock
  • dten/haddock
  • bgamari/haddock
  • abrar/haddock
  • obsidiansystems/haddock
  • inaki/haddock
  • hsyl20/haddock
  • JoshMeredith/haddock
  • matheus23/haddock
  • Gertjan423/haddock
  • ulysses4ever/haddock
  • facundominguez/haddock
  • SuedeHead/haddock
  • Haskell-mouse/haddock
  • fgaz/haddock
  • arybczak/haddock
  • coot/haddock
  • hithroc/haddock
  • ani/haddock
  • supersven/haddock
  • alt-romes/haddock
  • sspencer/haddock
  • Joald/haddock
  • raehik/haddock
  • lexi.lambda/haddock
  • torsten.schmits/haddock
  • Bodigrim/haddock
  • doyougnu/haddock
  • barci2/haddock
  • Jade/haddock
  • wavewave/haddock
  • soulomoon/haddock
  • tvh/haddock
  • trac-sjoerd_visscher/haddock
  • Kleidukos/haddock
  • mmzk1526/haddock
  • stephenjudkins/haddock
  • KommuSoft1/haddock
43 results
Show changes
Expand all Hide whitespace changes
Inline Side-by-side
Showing
with 3392 additions and 2055 deletions
doc/aclocal.m4 deleted 100644 → 0
View file @ 1ea1385d
# FP_GEN_DOCBOOK_XML
# ------------------
# Generates a DocBook XML V4.2 document in conftest.xml.
AC_DEFUN([FP_GEN_DOCBOOK_XML],
[rm -f conftest.xml
cat > conftest.xml << EOF
<?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">
<book id="test">
<title>A DocBook Test Document</title>
<chapter id="id-one">
<title>A Chapter Title</title>
<para>This is a paragraph, referencing <xref linkend="id-two"/>.</para>
</chapter>
<chapter id="id-two">
<title>Another Chapter Title</title>
<para>This is another paragraph, referencing <xref linkend="id-one"/>.</para>
</chapter>
</book>
EOF
]) # FP_GEN_DOCBOOK_XML
# FP_PROG_XSLTPROC
# ----------------
# Sets the output variable XsltprocCmd to the full path of the XSLT processor
# xsltproc. XsltprocCmd is empty if xsltproc could not be found.
AC_DEFUN([FP_PROG_XSLTPROC],
[AC_PATH_PROG([XsltprocCmd], [xsltproc])
if test -z "$XsltprocCmd"; then
AC_MSG_WARN([cannot find xsltproc in your PATH, you will not be able to build the documentation])
fi
])# FP_PROG_XSLTPROC
# FP_DIR_DOCBOOK_XSL(XSL-DIRS)
# ----------------------------
# Check which of the directories XSL-DIRS contains DocBook XSL stylesheets. The
# output variable DIR_DOCBOOK_XSL will contain the first usable directory or
# will be empty if none could be found.
AC_DEFUN([FP_DIR_DOCBOOK_XSL],
[AC_REQUIRE([FP_PROG_XSLTPROC])dnl
if test -n "$XsltprocCmd"; then
AC_CACHE_CHECK([for DocBook XSL stylesheet directory], fp_cv_dir_docbook_xsl,
[FP_GEN_DOCBOOK_XML
fp_cv_dir_docbook_xsl=no
for fp_var in $1; do
if $XsltprocCmd ${fp_var}/html/docbook.xsl conftest.xml > /dev/null 2>&1; then
fp_cv_dir_docbook_xsl=$fp_var
break
fi
done
rm -rf conftest*])
fi
if test x"$fp_cv_dir_docbook_xsl" = xno; then
AC_MSG_WARN([cannot find DocBook XSL stylesheets, you will not be able to build the documentation])
DIR_DOCBOOK_XSL=
else
DIR_DOCBOOK_XSL=$fp_cv_dir_docbook_xsl
fi
AC_SUBST([DIR_DOCBOOK_XSL])
])# FP_DIR_DOCBOOK_XSL
# FP_PROG_XMLLINT
# ----------------
# Sets the output variable XmllintCmd to the full path of the XSLT processor
# xmllint. XmllintCmd is empty if xmllint could not be found.
AC_DEFUN([FP_PROG_XMLLINT],
[AC_PATH_PROG([XmllintCmd], [xmllint])
if test -z "$XmllintCmd"; then
AC_MSG_WARN([cannot find xmllint in your PATH, you will not be able to validate your documentation])
fi
])# FP_PROG_XMLLINT
# FP_CHECK_DOCBOOK_DTD
# --------------------
AC_DEFUN([FP_CHECK_DOCBOOK_DTD],
[AC_REQUIRE([FP_PROG_XMLLINT])dnl
if test -n "$XmllintCmd"; then
AC_MSG_CHECKING([for DocBook DTD])
FP_GEN_DOCBOOK_XML
if $XmllintCmd --valid --noout conftest.xml > /dev/null 2>&1; then
AC_MSG_RESULT([ok])
else
AC_MSG_RESULT([failed])
AC_MSG_WARN([cannot find a DTD for DocBook XML V4.2, you will not be able to validate your documentation])
AC_MSG_WARN([check your XML_CATALOG_FILES environment variable and/or /etc/xml/catalog])
fi
rm -rf conftest*
fi
])# FP_CHECK_DOCBOOK_DTD
# FP_GEN_FO
# ------------------
# Generates a formatting objects document in conftest.fo.
AC_DEFUN([FP_GEN_FO],
[rm -f conftest.fo
cat > conftest.fo << EOF
<?xml version="1.0"?>
<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
<fo:layout-master-set>
<fo:simple-page-master master-name="blank">
<fo:region-body/>
</fo:simple-page-master>
</fo:layout-master-set>
<fo:page-sequence master-reference="blank">
<fo:flow flow-name="xsl-region-body">
<fo:block>
Test!
</fo:block>
</fo:flow>
</fo:page-sequence>
</fo:root>
EOF
]) # FP_GEN_FO
# FP_PROG_FOP
# -----------
# Set the output variable 'FopCmd' to the first working 'fop' in the current
# 'PATH'. Note that /usr/bin/fop is broken in SuSE 9.1 (unpatched), so try
# /usr/share/fop/fop.sh in that case (or no 'fop'), too.
AC_DEFUN([FP_PROG_FOP],
[AC_PATH_PROGS([FopCmd1], [fop])
if test -n "$FopCmd1"; then
AC_CACHE_CHECK([for $FopCmd1 usability], [fp_cv_fop_usability],
[FP_GEN_FO
if "$FopCmd1" -fo conftest.fo -ps conftest.ps > /dev/null 2>&1; then
fp_cv_fop_usability=yes
else
fp_cv_fop_usability=no
fi
rm -rf conftest*])
if test x"$fp_cv_fop_usability" = xyes; then
FopCmd=$FopCmd1
fi
fi
if test -z "$FopCmd"; then
AC_PATH_PROGS([FopCmd2], [fop.sh], , [/usr/share/fop])
FopCmd=$FopCmd2
fi
AC_SUBST([FopCmd])
])# FP_PROG_FOP
# FP_PROG_FO_PROCESSOR
# --------------------
# Try to find an FO processor. PassiveTeX output is sometimes a bit strange, so
# try FOP first. Sets the output variables FopCmd, XmltexCmd, DvipsCmd, and
# PdfxmltexCmd.
AC_DEFUN([FP_PROG_FO_PROCESSOR],
[AC_REQUIRE([FP_PROG_FOP])
AC_PATH_PROG([XmltexCmd], [xmltex])
AC_PATH_PROG([DvipsCmd], [dvips])
if test -z "$FopCmd"; then
if test -z "$XmltexCmd"; then
AC_MSG_WARN([cannot find an FO => DVI converter, you will not be able to build DVI or PostScript documentation])
else
if test -z "$DvipsCmd"; then
AC_MSG_WARN([cannot find a DVI => PS converter, you will not be able to build PostScript documentation])
fi
fi
AC_PATH_PROG([PdfxmltexCmd], [pdfxmltex])
if test -z "$PdfxmltexCmd"; then
AC_MSG_WARN([cannot find an FO => PDF converter, you will not be able to build PDF documentation])
fi
elif test -z "$XmltexCmd"; then
AC_MSG_WARN([cannot find an FO => DVI converter, you will not be able to build DVI documentation])
fi
])# FP_PROG_FO_PROCESSOR
doc/cheatsheet/LICENSE 0 → 100644
View file @ c9bc29c6
Attribution-ShareAlike 4.0 International
=======================================================================
Creative Commons Corporation ("Creative Commons") is not a law firm and
does not provide legal services or legal advice. Distribution of
Creative Commons public licenses does not create a lawyer-client or
other relationship. Creative Commons makes its licenses and related
information available on an "as-is" basis. Creative Commons gives no
warranties regarding its licenses, any material licensed under their
terms and conditions, or any related information. Creative Commons
disclaims all liability for damages resulting from their use to the
fullest extent possible.
Using Creative Commons Public Licenses
Creative Commons public licenses provide a standard set of terms and
conditions that creators and other rights holders may use to share
original works of authorship and other material subject to copyright
and certain other rights specified in the public license below. The
following considerations are for informational purposes only, are not
exhaustive, and do not form part of our licenses.
Considerations for licensors: Our public licenses are
intended for use by those authorized to give the public
permission to use material in ways otherwise restricted by
copyright and certain other rights. Our licenses are
irrevocable. Licensors should read and understand the terms
and conditions of the license they choose before applying it.
Licensors should also secure all rights necessary before
applying our licenses so that the public can reuse the
material as expected. Licensors should clearly mark any
material not subject to the license. This includes other CC-
licensed material, or material used under an exception or
limitation to copyright. More considerations for licensors:
wiki.creativecommons.org/Considerations_for_licensors
Considerations for the public: By using one of our public
licenses, a licensor grants the public permission to use the
licensed material under specified terms and conditions. If
the licensor's permission is not necessary for any reason--for
example, because of any applicable exception or limitation to
copyright--then that use is not regulated by the license. Our
licenses grant only permissions under copyright and certain
other rights that a licensor has authority to grant. Use of
the licensed material may still be restricted for other
reasons, including because others have copyright or other
rights in the material. A licensor may make special requests,
such as asking that all changes be marked or described.
Although not required by our licenses, you are encouraged to
respect those requests where reasonable. More_considerations
for the public:
wiki.creativecommons.org/Considerations_for_licensees
=======================================================================
Creative Commons Attribution-ShareAlike 4.0 International Public
License
By exercising the Licensed Rights (defined below), You accept and agree
to be bound by the terms and conditions of this Creative Commons
Attribution-ShareAlike 4.0 International Public License ("Public
License"). To the extent this Public License may be interpreted as a
contract, You are granted the Licensed Rights in consideration of Your
acceptance of these terms and conditions, and the Licensor grants You
such rights in consideration of benefits the Licensor receives from
making the Licensed Material available under these terms and
conditions.
Section 1 -- Definitions.
a. Adapted Material means material subject to Copyright and Similar
Rights that is derived from or based upon the Licensed Material
and in which the Licensed Material is translated, altered,
arranged, transformed, or otherwise modified in a manner requiring
permission under the Copyright and Similar Rights held by the
Licensor. For purposes of this Public License, where the Licensed
Material is a musical work, performance, or sound recording,
Adapted Material is always produced where the Licensed Material is
synched in timed relation with a moving image.
b. Adapter's License means the license You apply to Your Copyright
and Similar Rights in Your contributions to Adapted Material in
accordance with the terms and conditions of this Public License.
c. BY-SA Compatible License means a license listed at
creativecommons.org/compatiblelicenses, approved by Creative
Commons as essentially the equivalent of this Public License.
d. Copyright and Similar Rights means copyright and/or similar rights
closely related to copyright including, without limitation,
performance, broadcast, sound recording, and Sui Generis Database
Rights, without regard to how the rights are labeled or
categorized. For purposes of this Public License, the rights
specified in Section 2(b)(1)-(2) are not Copyright and Similar
Rights.
e. Effective Technological Measures means those measures that, in the
absence of proper authority, may not be circumvented under laws
fulfilling obligations under Article 11 of the WIPO Copyright
Treaty adopted on December 20, 1996, and/or similar international
agreements.
f. Exceptions and Limitations means fair use, fair dealing, and/or
any other exception or limitation to Copyright and Similar Rights
that applies to Your use of the Licensed Material.
g. License Elements means the license attributes listed in the name
of a Creative Commons Public License. The License Elements of this
Public License are Attribution and ShareAlike.
h. Licensed Material means the artistic or literary work, database,
or other material to which the Licensor applied this Public
License.
i. Licensed Rights means the rights granted to You subject to the
terms and conditions of this Public License, which are limited to
all Copyright and Similar Rights that apply to Your use of the
Licensed Material and that the Licensor has authority to license.
j. Licensor means the individual(s) or entity(ies) granting rights
under this Public License.
k. Share means to provide material to the public by any means or
process that requires permission under the Licensed Rights, such
as reproduction, public display, public performance, distribution,
dissemination, communication, or importation, and to make material
available to the public including in ways that members of the
public may access the material from a place and at a time
individually chosen by them.
l. Sui Generis Database Rights means rights other than copyright
resulting from Directive 96/9/EC of the European Parliament and of
the Council of 11 March 1996 on the legal protection of databases,
as amended and/or succeeded, as well as other essentially
equivalent rights anywhere in the world.
m. You means the individual or entity exercising the Licensed Rights
under this Public License. Your has a corresponding meaning.
Section 2 -- Scope.
a. License grant.
1. Subject to the terms and conditions of this Public License,
the Licensor hereby grants You a worldwide, royalty-free,
non-sublicensable, non-exclusive, irrevocable license to
exercise the Licensed Rights in the Licensed Material to:
a. reproduce and Share the Licensed Material, in whole or
in part; and
b. produce, reproduce, and Share Adapted Material.
2. Exceptions and Limitations. For the avoidance of doubt, where
Exceptions and Limitations apply to Your use, this Public
License does not apply, and You do not need to comply with
its terms and conditions.
3. Term. The term of this Public License is specified in Section
6(a).
4. Media and formats; technical modifications allowed. The
Licensor authorizes You to exercise the Licensed Rights in
all media and formats whether now known or hereafter created,
and to make technical modifications necessary to do so. The
Licensor waives and/or agrees not to assert any right or
authority to forbid You from making technical modifications
necessary to exercise the Licensed Rights, including
technical modifications necessary to circumvent Effective
Technological Measures. For purposes of this Public License,
simply making modifications authorized by this Section 2(a)
(4) never produces Adapted Material.
5. Downstream recipients.
a. Offer from the Licensor -- Licensed Material. Every
recipient of the Licensed Material automatically
receives an offer from the Licensor to exercise the
Licensed Rights under the terms and conditions of this
Public License.
b. Additional offer from the Licensor -- Adapted Material.
Every recipient of Adapted Material from You
automatically receives an offer from the Licensor to
exercise the Licensed Rights in the Adapted Material
under the conditions of the Adapter's License You apply.
c. No downstream restrictions. You may not offer or impose
any additional or different terms or conditions on, or
apply any Effective Technological Measures to, the
Licensed Material if doing so restricts exercise of the
Licensed Rights by any recipient of the Licensed
Material.
6. No endorsement. Nothing in this Public License constitutes or
may be construed as permission to assert or imply that You
are, or that Your use of the Licensed Material is, connected
with, or sponsored, endorsed, or granted official status by,
the Licensor or others designated to receive attribution as
provided in Section 3(a)(1)(A)(i).
b. Other rights.
1. Moral rights, such as the right of integrity, are not
licensed under this Public License, nor are publicity,
privacy, and/or other similar personality rights; however, to
the extent possible, the Licensor waives and/or agrees not to
assert any such rights held by the Licensor to the limited
extent necessary to allow You to exercise the Licensed
Rights, but not otherwise.
2. Patent and trademark rights are not licensed under this
Public License.
3. To the extent possible, the Licensor waives any right to
collect royalties from You for the exercise of the Licensed
Rights, whether directly or through a collecting society
under any voluntary or waivable statutory or compulsory
licensing scheme. In all other cases the Licensor expressly
reserves any right to collect such royalties.
Section 3 -- License Conditions.
Your exercise of the Licensed Rights is expressly made subject to the
following conditions.
a. Attribution.
1. If You Share the Licensed Material (including in modified
form), You must:
a. retain the following if it is supplied by the Licensor
with the Licensed Material:
i. identification of the creator(s) of the Licensed
Material and any others designated to receive
attribution, in any reasonable manner requested by
the Licensor (including by pseudonym if
designated);
ii. a copyright notice;
iii. a notice that refers to this Public License;
iv. a notice that refers to the disclaimer of
warranties;
v. a URI or hyperlink to the Licensed Material to the
extent reasonably practicable;
b. indicate if You modified the Licensed Material and
retain an indication of any previous modifications; and
c. indicate the Licensed Material is licensed under this
Public License, and include the text of, or the URI or
hyperlink to, this Public License.
2. You may satisfy the conditions in Section 3(a)(1) in any
reasonable manner based on the medium, means, and context in
which You Share the Licensed Material. For example, it may be
reasonable to satisfy the conditions by providing a URI or
hyperlink to a resource that includes the required
information.
3. If requested by the Licensor, You must remove any of the
information required by Section 3(a)(1)(A) to the extent
reasonably practicable.
b. ShareAlike.
In addition to the conditions in Section 3(a), if You Share
Adapted Material You produce, the following conditions also apply.
1. The Adapter's License You apply must be a Creative Commons
license with the same License Elements, this version or
later, or a BY-SA Compatible License.
2. You must include the text of, or the URI or hyperlink to, the
Adapter's License You apply. You may satisfy this condition
in any reasonable manner based on the medium, means, and
context in which You Share Adapted Material.
3. You may not offer or impose any additional or different terms
or conditions on, or apply any Effective Technological
Measures to, Adapted Material that restrict exercise of the
rights granted under the Adapter's License You apply.
Section 4 -- Sui Generis Database Rights.
Where the Licensed Rights include Sui Generis Database Rights that
apply to Your use of the Licensed Material:
a. for the avoidance of doubt, Section 2(a)(1) grants You the right
to extract, reuse, reproduce, and Share all or a substantial
portion of the contents of the database;
b. if You include all or a substantial portion of the database
contents in a database in which You have Sui Generis Database
Rights, then the database in which You have Sui Generis Database
Rights (but not its individual contents) is Adapted Material,
including for purposes of Section 3(b); and
c. You must comply with the conditions in Section 3(a) if You Share
all or a substantial portion of the contents of the database.
For the avoidance of doubt, this Section 4 supplements and does not
replace Your obligations under this Public License where the Licensed
Rights include other Copyright and Similar Rights.
Section 5 -- Disclaimer of Warranties and Limitation of Liability.
a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE
EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS
AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF
ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS,
IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION,
WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS,
ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT
KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT
ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU.
b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE
TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION,
NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT,
INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES,
COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR
USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN
ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR
DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR
IN PART, THIS LIMITATION MAY NOT APPLY TO YOU.
c. The disclaimer of warranties and limitation of liability provided
above shall be interpreted in a manner that, to the extent
possible, most closely approximates an absolute disclaimer and
waiver of all liability.
Section 6 -- Term and Termination.
a. This Public License applies for the term of the Copyright and
Similar Rights licensed here. However, if You fail to comply with
this Public License, then Your rights under this Public License
terminate automatically.
b. Where Your right to use the Licensed Material has terminated under
Section 6(a), it reinstates:
1. automatically as of the date the violation is cured, provided
it is cured within 30 days of Your discovery of the
violation; or
2. upon express reinstatement by the Licensor.
For the avoidance of doubt, this Section 6(b) does not affect any
right the Licensor may have to seek remedies for Your violations
of this Public License.
c. For the avoidance of doubt, the Licensor may also offer the
Licensed Material under separate terms or conditions or stop
distributing the Licensed Material at any time; however, doing so
will not terminate this Public License.
d. Sections 1, 5, 6, 7, and 8 survive termination of this Public
License.
Section 7 -- Other Terms and Conditions.
a. The Licensor shall not be bound by any additional or different
terms or conditions communicated by You unless expressly agreed.
b. Any arrangements, understandings, or agreements regarding the
Licensed Material not stated herein are separate from and
independent of the terms and conditions of this Public License.
Section 8 -- Interpretation.
a. For the avoidance of doubt, this Public License does not, and
shall not be interpreted to, reduce, limit, restrict, or impose
conditions on any use of the Licensed Material that could lawfully
be made without permission under this Public License.
b. To the extent possible, if any provision of this Public License is
deemed unenforceable, it shall be automatically reformed to the
minimum extent necessary to make it enforceable. If the provision
cannot be reformed, it shall be severed from this Public License
without affecting the enforceability of the remaining terms and
conditions.
c. No term or condition of this Public License will be waived and no
failure to comply consented to unless expressly agreed to by the
Licensor.
d. Nothing in this Public License constitutes or may be interpreted
as a limitation upon, or waiver of, any privileges and immunities
that apply to the Licensor or You, including from the legal
processes of any jurisdiction or authority.
=======================================================================
Creative Commons is not a party to its public
licenses. Notwithstanding, Creative Commons may elect to apply one of
its public licenses to material it publishes and in those instances
will be considered the “Licensor.” The text of the Creative Commons
public licenses is dedicated to the public domain under the CC0 Public
Domain Dedication. Except for the limited purpose of indicating that
material is shared under a Creative Commons public license or as
otherwise permitted by the Creative Commons policies published at
creativecommons.org/policies, Creative Commons does not authorize the
use of the trademark "Creative Commons" or any other trademark or logo
of Creative Commons without its prior written consent including,
without limitation, in connection with any unauthorized modifications
to any of its public licenses or any other arrangements,
understandings, or agreements concerning use of licensed material. For
the avoidance of doubt, this paragraph does not form part of the
public licenses.
Creative Commons may be contacted at creativecommons.org.
doc/cheatsheet/README.md 0 → 100644
View file @ c9bc29c6
![License: CC BY-SA 4.0](https://img.shields.io/badge/License-CC%20BY--SA%204.0-lightgrey.svg)
# Haddock Markup Quick Reference
This page is a single-page quick reference for the markup used in GHC's [Haddock](https://www.haskell.org/haddock/) documentation format. It doesn't list all the details of the format, just the basic markup, so for the vagaries and edge-cases of the syntax, it would be helpful to consult the [Haddock user guide](http://haskell-haddock.readthedocs.io/en/latest/index.html).
## License
This document is licensed under the CC BY-SA 4.0 license.
doc/cheatsheet/haddocks.md 0 → 100644
View file @ c9bc29c6
# Code Sections
```
-- * Section
-- ** Sub-section
-- *** Sub-sub-section
-- et cetera
```
# Named Documentation Chunks
```
-- $name
[...]
-- $name
-- Here is the documentation text
-- which is embedded elsewhere
```
# Code Blocks
```
With internal markup:
-- @
-- fact n = product [1..n]
-- @
With literal text:
-- > fact n = product [1..n]
```
# REPL Examples
```
-- >>> fact 5
-- 120
```
# Properties
```
-- prop> a + b = b + a
```
# Hyperlinked Identifiers
```
-- The value 'x' of type 'T'
-- The out-of-scope 'MyModule.x'
-- The "MyModule" module
```
# Textual Markup
```
-- Emphasis: /forward slashes/.
-- Bolding: __underscores__.
-- Monospaced text: @ampersands@.
```
# Links and Images
```
-- A raw link <http://example.com>
-- [a link](http://example.com)
-- ![description](imagepath.png)
```
# Lists
```
itemized with "*" or "-"
-- * first item
-- * second item
numbered with "(n)" or "n."
-- 1. first item
-- 2. second item
definitions with "[thing]"
-- [one] first item
-- [two] second item
```
# Mathematics/LaTeX
```
-- \[
-- f(n) = \Sum_{i=1}^{n} i
-- \]
-- when \(n > 0\)
```
# Headings in Documentation
```
-- = Heading
-- == Sub-heading
-- === Sub-sub-heading
```
# Metadata
```
-- @since 1.2.3
```
# Module Attributes
```
{-# OPTIONS_HADDOCK hide #-}
Omit this module from the docs
{-# OPTIONS_HADDOCK prune #-}
Omit definitions without docs
{-# OPTIONS_HADDOCK not-home #-}
Do not treat this module as the
"home" of identifiers it exports
{-# OPTIONS_HADDOCK show-extensions #-}
Show all enabled LANGUAGE extensions
{-# OPTIONS_HADDOCK print-explicit-runtime-reps #-}
Show all `RuntimeRep` type variables
```
# Grid tables
```
+------------------------+------------+----------+----------+
| Header row, column 1 | Header 2 | Header 3 | Header 4 |
| (header rows optional) | | | |
+========================+============+==========+==========+
| body row 1, column 1 | column 2 | column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2 | Cells may span columns. |
+------------------------+------------+---------------------+
| body row 3 | Cells may | \[ |
+------------------------+ span rows. | f(n) = \sum_{i=1} |
| body row 4 | | \] |
+------------------------+------------+---------------------+
```
doc/cheatsheet/haddocks.pdf 0 → 100644
View file @ c9bc29c6
File added
doc/cheatsheet/haddocks.svg 0 → 100644
View file @ c9bc29c6
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!-- Created with Inkscape (http://www.inkscape.org/) -->
<svg
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:cc="http://creativecommons.org/ns#"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns="http://www.w3.org/2000/svg"
xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
width="8.5in"
height="11in"
viewBox="0 0 170 220"
version="1.1"
id="svg8"
inkscape:version="0.92.1 r"
sodipodi:docname="haddocks.svg"
inkscape:export-filename="/home/gdritter/projects/haddock-cheatsheet/haddocks.png"
inkscape:export-xdpi="100"
inkscape:export-ydpi="100">
<defs
id="defs2" />
<sodipodi:namedview
id="base"
pagecolor="#ffffff"
bordercolor="#666666"
borderopacity="1.0"
inkscape:pageopacity="0.99607843"
inkscape:pageshadow="2"
inkscape:zoom="1.1689792"
inkscape:cx="338.82394"
inkscape:cy="776.62735"
inkscape:document-units="in"
inkscape:current-layer="layer1"
showgrid="false"
inkscape:snap-smooth-nodes="true"
inkscape:snap-intersection-paths="true"
units="in"
scale-x="20"
inkscape:window-width="1918"
inkscape:window-height="1036"
inkscape:window-x="0"
inkscape:window-y="42"
inkscape:window-maximized="0"
showguides="true"
inkscape:guide-bbox="true">
<inkscape:grid
type="xygrid"
id="grid4485" />
</sodipodi:namedview>
<metadata
id="metadata5">
<rdf:RDF>
<cc:Work
rdf:about="">
<dc:format>image/svg+xml</dc:format>
<dc:type
rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
<dc:title />
</cc:Work>
</rdf:RDF>
</metadata>
<g
inkscape:label="Layer 1"
inkscape:groupmode="layer"
id="layer1"
transform="translate(0,-17.599983)">
<text
xml:space="preserve"
style="font-style:normal;font-weight:normal;font-size:23.44835281px;line-height:0px;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.24425368px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
x="9.2960958"
y="44.426563"
id="text4489"><tspan
sodipodi:role="line"
x="9.2960958"
y="44.426563"
style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:4.61581755px;line-height:0px;font-family:'Fira Sans';-inkscape-font-specification:'Fira Sans Bold';stroke-width:0.24425368px"
id="tspan4497">Code Sections</tspan><tspan
sodipodi:role="line"
x="9.2960958"
y="49.229057"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
id="tspan4507"> -- * Section</tspan><tspan
sodipodi:role="line"
x="9.2960958"
y="54.461079"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
id="tspan4511"> -- ** Sub-section</tspan><tspan
sodipodi:role="line"
x="9.2960958"
y="59.6931"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
id="tspan4513"> -- *** Sub-sub-section</tspan><tspan
sodipodi:role="line"
x="9.2960958"
y="64.925117"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
id="tspan4515"> -- et cetera</tspan></text>
<text
id="text4569"
y="70.848915"
x="9.3546734"
style="font-style:normal;font-weight:normal;font-size:23.44835281px;line-height:0px;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.24425368px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
xml:space="preserve"><tspan
style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:4.61581755px;font-family:'Fira Sans';-inkscape-font-specification:'Fira Sans Bold';stroke-width:0.24425368px"
y="70.848915"
x="9.3546734"
sodipodi:role="line"
id="tspan4753">Named Documentation Chunks</tspan><tspan
id="tspan4567"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:2.82077742px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
y="75.651405"
x="9.3546734"
sodipodi:role="line"> -- $name</tspan><tspan
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:2.82077742px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
y="80.955017"
x="9.3546734"
sodipodi:role="line"
id="tspan4580"><tspan
style="font-size:2.82077742px;fill:#808080;stroke-width:0.24425368px"
id="tspan4586">[...]</tspan></tspan><tspan
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:2.82077742px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
y="86.258629"
x="9.3546734"
sodipodi:role="line"
id="tspan4578"> -- $name</tspan><tspan
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:2.82077742px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
y="91.562233"
x="9.3546734"
sodipodi:role="line"
id="tspan4582"> -- Here is the documentation text</tspan><tspan
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:2.82077742px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
y="96.865845"
x="9.3546734"
sodipodi:role="line"
id="tspan4584"> -- which is embedded elsewhere</tspan></text>
<text
id="text4661"
y="102.25972"
x="9.3546734"
style="font-style:normal;font-weight:normal;font-size:23.44835281px;line-height:0px;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.24425368px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
xml:space="preserve"><tspan
id="tspan4647"
style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:4.61581755px;line-height:0px;font-family:'Fira Sans';-inkscape-font-specification:'Fira Sans Bold';stroke-width:0.24425368px"
y="102.25972"
x="9.3546734"
sodipodi:role="line">Code Blocks</tspan><tspan
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';fill:#808080;stroke-width:0.24425368px"
y="107.06221"
x="9.3546734"
sodipodi:role="line"
id="tspan4649">With internal markup:</tspan><tspan
id="tspan4651"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
y="112.29424"
x="9.3546734"
sodipodi:role="line"> -- @</tspan><tspan
id="tspan4653"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
y="117.52625"
x="9.3546734"
sodipodi:role="line"> -- fact n = product [1..n]</tspan><tspan
id="tspan4655"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
y="122.75829"
x="9.3546734"
sodipodi:role="line"> -- @</tspan><tspan
id="tspan4657"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';fill:#808080;stroke-width:0.24425368px"
y="127.9903"
x="9.3546734"
sodipodi:role="line">With literal text:</tspan><tspan
id="tspan4659"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
y="133.22232"
x="9.3546734"
sodipodi:role="line"> -- &gt; fact n = product [1..n]</tspan></text>
<text
xml:space="preserve"
style="font-style:normal;font-weight:normal;font-size:23.44835281px;line-height:0px;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.24425368px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
x="9.3546734"
y="140.30173"
id="text4602"><tspan
sodipodi:role="line"
x="9.3546734"
y="140.30173"
style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:4.61581755px;line-height:0px;font-family:'Fira Sans';-inkscape-font-specification:'Fira Sans Bold';stroke-width:0.24425368px"
id="tspan4588">REPL Examples</tspan><tspan
sodipodi:role="line"
x="9.3546734"
y="145.10422"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
id="tspan4629"> -- &gt;&gt;&gt; fact 5</tspan><tspan
sodipodi:role="line"
x="9.3546734"
y="150.33624"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
id="tspan4674"> -- 120</tspan></text>
<text
id="text4692"
y="156.90796"
x="9.3546734"
style="font-style:normal;font-weight:normal;font-size:23.44835281px;line-height:0px;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.24425368px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
xml:space="preserve"><tspan
id="tspan4680"
style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:4.61581755px;line-height:0px;font-family:'Fira Sans';-inkscape-font-specification:'Fira Sans Bold';stroke-width:0.24425368px"
y="156.90796"
x="9.3546734"
sodipodi:role="line">Properties</tspan><tspan
id="tspan4690"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
y="161.71045"
x="9.3546734"
sodipodi:role="line"> -- prop&gt; a + b = b + a</tspan></text>
<text
xml:space="preserve"
style="font-style:normal;font-weight:normal;font-size:23.3177433px;line-height:0px;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.24289316px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
x="9.5486708"
y="169.6808"
id="text4731"><tspan
sodipodi:role="line"
x="9.5486708"
y="169.6808"
style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:4.59010696px;line-height:0px;font-family:'Fira Sans';-inkscape-font-specification:'Fira Sans Bold';stroke-width:0.24289316px"
id="tspan4727">Hyperlinked Identifiers</tspan><tspan
sodipodi:role="line"
x="9.5486708"
y="174.45654"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.06007123px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24289316px"
id="tspan4729"> -- The value 'x' of type 'T'</tspan><tspan
sodipodi:role="line"
x="9.5486708"
y="179.65942"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.06007123px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24289316px"
id="tspan4733"> -- The out-of-scope 'MyModule.x'</tspan><tspan
sodipodi:role="line"
x="9.5486708"
y="184.8623"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.06007123px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24289316px"
id="tspan4747"> -- The &quot;MyModule&quot; module</tspan></text>
<text
id="text4741"
y="192.34953"
x="9.3546734"
style="font-style:normal;font-weight:normal;font-size:23.44835281px;line-height:0px;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.24425368px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
xml:space="preserve"><tspan
id="tspan4735"
style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:4.61581755px;line-height:0px;font-family:'Fira Sans';-inkscape-font-specification:'Fira Sans Bold';stroke-width:0.24425368px"
y="192.34953"
x="9.3546734"
sodipodi:role="line">Textual Markup</tspan><tspan
id="tspan4737"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
y="197.15202"
x="9.3546734"
sodipodi:role="line"> -- Emphasis: /forward slashes/.</tspan><tspan
id="tspan4739"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
y="202.38405"
x="9.3546734"
sodipodi:role="line"> -- Bolding: __underscores__.</tspan><tspan
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
y="207.61607"
x="9.3546734"
sodipodi:role="line"
id="tspan4745"> -- Monospaced text: @at signs@.</tspan></text>
<text
xml:space="preserve"
style="font-style:normal;font-weight:normal;font-size:23.44835281px;line-height:0px;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.24425368px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
x="9.3546734"
y="215.33546"
id="text4771"><tspan
sodipodi:role="line"
x="9.3546734"
y="215.33546"
style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:4.61581755px;line-height:0px;font-family:'Fira Sans';-inkscape-font-specification:'Fira Sans Bold';stroke-width:0.24425368px"
id="tspan4763">Links and Images</tspan><tspan
id="tspan4769"
sodipodi:role="line"
x="9.3546734"
y="220.13795"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"> -- A raw link &lt;http://example.com&gt;</tspan><tspan
sodipodi:role="line"
x="9.3546734"
y="225.36998"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
id="tspan4780"> -- [a link](http://example.com)</tspan><tspan
sodipodi:role="line"
x="9.3546734"
y="230.60201"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
id="tspan4778"> -- ![description](imagepath.png)</tspan></text>
<text
id="text4806"
y="44.426563"
x="89.102867"
style="font-style:normal;font-weight:normal;font-size:23.44835281px;line-height:0px;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.24425368px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
xml:space="preserve"><tspan
id="tspan4796"
style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:4.61581755px;line-height:0px;font-family:'Fira Sans';-inkscape-font-specification:'Fira Sans Bold';stroke-width:0.24425368px"
y="44.426563"
x="89.102867"
sodipodi:role="line">Lists</tspan><tspan
style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:4.61581755px;line-height:0px;font-family:'Fira Sans';-inkscape-font-specification:'Fira Sans Bold';stroke-width:0.24425368px"
y="49.229057"
x="89.102867"
sodipodi:role="line"
id="tspan4812" /><tspan
id="tspan4798"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';fill:#808080;stroke-width:0.24425368px"
y="49.229057"
x="89.102867"
sodipodi:role="line">itemized with &quot;*&quot; or &quot;-&quot;</tspan><tspan
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
y="54.461079"
x="89.102867"
sodipodi:role="line"
id="tspan4814"> -- * first item</tspan><tspan
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
y="59.6931"
x="89.102867"
sodipodi:role="line"
id="tspan4810"> -- * second item</tspan><tspan
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';fill:#808080;stroke-width:0.24425368px"
y="64.925117"
x="89.102867"
sodipodi:role="line"
id="tspan4816">numbered with &quot;(n)&quot; or &quot;n.&quot;</tspan><tspan
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
y="70.157143"
x="89.102867"
sodipodi:role="line"
id="tspan4818"> -- 1. first item</tspan><tspan
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
y="75.38916"
x="89.102867"
sodipodi:role="line"
id="tspan4822"> -- 2. second item</tspan><tspan
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';fill:#808080;stroke-width:0.24425368px"
y="80.621185"
x="89.102867"
sodipodi:role="line"
id="tspan4826">definitions with &quot;[thing]&quot;</tspan><tspan
id="tspan4804"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
y="85.853203"
x="89.102867"
sodipodi:role="line"> -- [one] first item</tspan><tspan
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
y="91.085228"
x="89.102867"
sodipodi:role="line"
id="tspan4834"> -- [two] second item</tspan></text>
<text
id="text4936"
y="98.872009"
x="89.102867"
style="font-style:normal;font-weight:normal;font-size:23.44835281px;line-height:0px;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.24425368px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
xml:space="preserve"><tspan
id="tspan4920"
style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:4.61581755px;line-height:0px;font-family:'Fira Sans';-inkscape-font-specification:'Fira Sans Bold';stroke-width:0.24425368px"
y="98.872009"
x="89.102867"
sodipodi:role="line">Mathematics/LaTeX</tspan><tspan
style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:4.61581755px;line-height:0px;font-family:'Fira Sans';-inkscape-font-specification:'Fira Sans Bold';stroke-width:0.24425368px"
y="103.6745"
x="89.102867"
sodipodi:role="line"
id="tspan4922" /><tspan
id="tspan4924"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
y="103.6745"
x="89.102867"
sodipodi:role="line" /><tspan
id="tspan4926"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
y="103.6745"
x="89.102867"
sodipodi:role="line"> -- \[</tspan><tspan
id="tspan4928"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
y="108.90652"
x="89.102867"
sodipodi:role="line"> -- f(n) = \Sum_{i=1}^{n} i</tspan><tspan
id="tspan4930"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
y="114.13854"
x="89.102867"
sodipodi:role="line"> -- \]</tspan><tspan
id="tspan4934"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
y="119.37056"
x="89.102867"
sodipodi:role="line"> -- when \(n &gt; 0\)</tspan></text>
<text
xml:space="preserve"
style="font-style:normal;font-weight:normal;font-size:23.44835281px;line-height:0px;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.24425368px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
x="89.102867"
y="126.79274"
id="text4984"><tspan
sodipodi:role="line"
x="89.102867"
y="126.79274"
style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:4.61581755px;line-height:0px;font-family:'Fira Sans';-inkscape-font-specification:'Fira Sans Bold';stroke-width:0.24425368px"
id="tspan4970">Headings in Documentation</tspan><tspan
id="tspan4972"
sodipodi:role="line"
x="89.102867"
y="131.59523"
style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:4.61581755px;line-height:0px;font-family:'Fira Sans';-inkscape-font-specification:'Fira Sans Bold';stroke-width:0.24425368px" /><tspan
sodipodi:role="line"
x="89.102867"
y="131.59523"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
id="tspan4974" /><tspan
sodipodi:role="line"
x="89.102867"
y="131.59523"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
id="tspan4982"> -- = Heading</tspan><tspan
sodipodi:role="line"
x="89.102867"
y="136.82726"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
id="tspan4995"> -- == Sub-heading</tspan><tspan
sodipodi:role="line"
x="89.102867"
y="142.05928"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
id="tspan4997"> -- === sub-sub-heading</tspan></text>
<text
id="text5011"
y="149.362"
x="89.102867"
style="font-style:normal;font-weight:normal;font-size:23.44835281px;line-height:0px;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.24425368px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
xml:space="preserve"><tspan
id="tspan4999"
style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:4.61581755px;line-height:0px;font-family:'Fira Sans';-inkscape-font-specification:'Fira Sans Bold';stroke-width:0.24425368px"
y="149.362"
x="89.102867"
sodipodi:role="line">Metadata</tspan><tspan
style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:4.61581755px;line-height:0px;font-family:'Fira Sans';-inkscape-font-specification:'Fira Sans Bold';stroke-width:0.24425368px"
y="154.16449"
x="89.102867"
sodipodi:role="line"
id="tspan5001" /><tspan
id="tspan5009"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
y="154.16449"
x="89.102867"
sodipodi:role="line" /><tspan
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
y="154.16449"
x="89.102867"
sodipodi:role="line"
id="tspan5018"> -- @since 1.2.3</tspan></text>
<flowRoot
xml:space="preserve"
id="flowRoot5020"
style="font-style:normal;font-weight:normal;font-size:96px;line-height:25px;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
transform="matrix(0.92316354,0,0,0.92316354,5.4302439,15.266139)"><flowRegion
id="flowRegion5022"><rect
id="rect5024"
width="238.32765"
height="162.11119"
x="435.52261"
y="59.137138" /></flowRegion><flowPara
id="flowPara5026" /></flowRoot> <text
xml:space="preserve"
style="font-style:normal;font-weight:normal;font-size:23.44835281px;line-height:0px;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.24425368px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
x="89.102867"
y="161.86107"
id="text5038"><tspan
sodipodi:role="line"
x="89.102867"
y="161.86107"
style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:4.61581755px;line-height:0px;font-family:'Fira Sans';-inkscape-font-specification:'Fira Sans Bold';stroke-width:0.24425368px"
id="tspan5028">Module Attributes</tspan><tspan
id="tspan5030"
sodipodi:role="line"
x="89.102867"
y="166.66356"
style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:4.61581755px;line-height:0px;font-family:'Fira Sans';-inkscape-font-specification:'Fira Sans Bold';stroke-width:0.24425368px" /><tspan
id="tspan5036"
sodipodi:role="line"
x="89.102867"
y="166.66356"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px" /><tspan
sodipodi:role="line"
x="89.102867"
y="166.66356"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
id="tspan5044">{-# OPTIONS_HADDOCK hide #-}</tspan><tspan
sodipodi:role="line"
x="89.102867"
y="171.89558"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
id="tspan5048"><tspan
style="fill:#808080;stroke-width:0.24425368px"
id="tspan5080"> Omit this module from the docs</tspan></tspan><tspan
sodipodi:role="line"
x="89.102867"
y="177.12761"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
id="tspan5050">{-# OPTIONS_HADDOCK prune #-}</tspan><tspan
sodipodi:role="line"
x="89.102867"
y="182.35962"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
id="tspan5054"><tspan
style="fill:#808080;stroke-width:0.24425368px"
id="tspan5082"> Omit definitions without docs</tspan></tspan><tspan
sodipodi:role="line"
x="89.102867"
y="187.59164"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
id="tspan5056">{-# OPTIONS_HADDOCK ignore-exports #-}</tspan><tspan
sodipodi:role="line"
x="89.102867"
y="192.82367"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
id="tspan5060"><tspan
style="fill:#808080;stroke-width:0.24425368px"
id="tspan5084"> Treat this module as though all</tspan></tspan><tspan
sodipodi:role="line"
x="89.102867"
y="198.05569"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';fill:#808080;stroke-width:0.24425368px"
id="tspan5064"> top-level items are exported</tspan><tspan
sodipodi:role="line"
x="89.102867"
y="203.2877"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
id="tspan5066">{-# OPTIONS_HADDOCK not-home #-}</tspan><tspan
sodipodi:role="line"
x="89.102867"
y="208.51973"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';fill:#808080;stroke-width:0.24425368px"
id="tspan5068"> Do not treat this module as the</tspan><tspan
sodipodi:role="line"
x="89.102867"
y="213.75175"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';fill:#808080;stroke-width:0.24425368px"
id="tspan5078"> &quot;home&quot; of identifiers it exports</tspan><tspan
sodipodi:role="line"
x="89.102867"
y="218.98378"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
id="tspan5070">{-# OPTIONS_HADDOCK show-extensions #-}</tspan><tspan
sodipodi:role="line"
x="89.102867"
y="224.21579"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:3.07721162px;line-height:0px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';stroke-width:0.24425368px"
id="tspan5072"><tspan
style="fill:#808080;stroke-width:0.24425368px"
id="tspan5086"> Show all enabled LANGUAGE extensions</tspan></tspan></text>
<text
xml:space="preserve"
style="font-style:normal;font-weight:normal;font-size:20px;line-height:5.20833302px;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.20833333px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
x="5.544848"
y="32.398926"
id="text5294"><tspan
sodipodi:role="line"
id="tspan5292"
x="5.544848"
y="32.398926"
style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:13.33333302px;font-family:'Fira Sans';-inkscape-font-specification:'Fira Sans Bold';stroke-width:0.20833333px">Haddock Markup</tspan></text>
<path
style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.78740158;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;stroke-miterlimit:4;stroke-dasharray:none"
d="M 6.2499999,37.599983 H 162.5"
id="path5504"
inkscape:connector-curvature="0" />
<text
xml:space="preserve"
style="font-style:normal;font-weight:normal;font-size:20px;line-height:5.20833302px;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.20833333px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
x="121.27747"
y="21.599566"
id="text5529"><tspan
sodipodi:role="line"
id="tspan5527"
x="121.27747"
y="29.399044"
style="stroke-width:0.20833333px" /></text>
<text
xml:space="preserve"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:2.22222233px;font-family:'Fira Sans';-inkscape-font-specification:'Fira Sans, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:end;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:end;fill:#666666;fill-opacity:1;stroke:none;stroke-width:0.26458332px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
x="163.25969"
y="21.504742"
id="text4489-0"><tspan
sodipodi:role="line"
x="163.25969"
y="21.504742"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:1.94444454px;font-family:'Fira Sans';-inkscape-font-specification:'Fira Sans, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:end;writing-mode:lr-tb;text-anchor:end;fill:#666666;stroke-width:0.26458332px"
id="tspan5579">Haddock Markup Cheat-sheet, Version 1.1</tspan><tspan
sodipodi:role="line"
x="163.25969"
y="24.28252"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:1.94444454px;font-family:'Fira Sans';-inkscape-font-specification:'Fira Sans, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:end;writing-mode:lr-tb;text-anchor:end;fill:#666666;stroke-width:0.26458332px"
id="tspan5571">Getty Ritter (<tspan
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:1.94444454px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';fill:#666666"
id="tspan5597">@aisamanra</tspan>)</tspan><tspan
sodipodi:role="line"
x="163.25969"
y="27.060297"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:1.94444454px;font-family:'Fira Mono';-inkscape-font-specification:'Fira Mono';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:end;writing-mode:lr-tb;text-anchor:end;fill:#666666;stroke-width:0.26458332px"
id="tspan5565">github.com/aisamanra/haddock-cheatsheet</tspan><tspan
sodipodi:role="line"
x="163.25969"
y="29.838076"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:1.94444454px;font-family:'Fira Sans';-inkscape-font-specification:'Fira Sans, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:end;writing-mode:lr-tb;text-anchor:end;fill:#666666;stroke-width:0.26458332px"
id="tspan5601" /><tspan
sodipodi:role="line"
x="163.25969"
y="32.615852"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:1.94444454px;font-family:'Fira Sans';-inkscape-font-specification:'Fira Sans, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:end;writing-mode:lr-tb;text-anchor:end;fill:#666666;stroke-width:0.26458332px"
id="tspan5605">This work is licensed under a Creative Commons</tspan><tspan
sodipodi:role="line"
x="163.25969"
y="35.393631"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:1.94444454px;font-family:'Fira Sans';-inkscape-font-specification:'Fira Sans, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:end;writing-mode:lr-tb;text-anchor:end;fill:#666666;stroke-width:0.26458332px"
id="tspan5593">Attribution-ShareAlike 4.0 International License</tspan></text>
</g>
</svg>
doc/common-errors.rst 0 → 100644
View file @ c9bc29c6
Common Errors
=============
``parse error on input ‘-- | xxx’``
-----------------------------------
This is probably caused by the ``-- | xxx`` comment not following a declaration. I.e. use ``-- xxx`` instead. See :ref:`top-level-declaration`.
``parse error on input ‘-- $ xxx’``
-----------------------------------
You've probably commented out code like::
f x
$ xxx
``-- $`` is a special syntax for named chunks, see :ref:`named-chunks`. You can fix this by escaping the ``$``::
-- \$ xxx
doc/conf.py 0 → 100644
View file @ c9bc29c6
# -*- coding: utf-8 -*-
import sys
import os
import shlex
extensions = []
source_suffix = '.rst'
master_doc = 'index'
# General information about the project.
project = u'Haddock'
copyright = u'2016, Simon Marlow'
author = u'Simon Marlow'
version = '1.0'
release = '1.0'
language = 'en'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = ['.build']
todo_include_todos = False
# Syntax highlighting
highlight_language = 'haskell'
pygments_style = 'tango'
# -- Options for HTML output ----------------------------------------------
htmlhelp_basename = 'Haddockdoc'
# -- Options for LaTeX output ---------------------------------------------
latex_elements = { }
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'Haddock.tex', u'Haddock Documentation',
u'Simon Marlow', 'manual'),
]
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'haddock', u'Haddock Documentation',
[author], 1)
]
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'Haddock', u'Haddock Documentation',
author, 'Haddock', 'One line description of project.',
'Miscellaneous'),
]
doc/config.mk.in deleted 100644 → 0
View file @ 1ea1385d
#-----------------------------------------------------------------------------
# DocBook XML stuff
XSLTPROC = @XsltprocCmd@
XMLLINT = @XmllintCmd@
FOP = @FopCmd@
XMLTEX = @XmltexCmd@
PDFXMLTEX = @PdfxmltexCmd@
DVIPS = @DvipsCmd@
DIR_DOCBOOK_XSL = @DIR_DOCBOOK_XSL@
XSLTPROC_LABEL_OPTS = --stringparam toc.section.depth 3 \
--stringparam section.autolabel 1 \
--stringparam section.label.includes.component.label 1
doc/configure.ac deleted 100644 → 0
View file @ 1ea1385d
AC_INIT([Haddock docs], [1.0], [simonmar@microsoft.com], [])
AC_CONFIG_SRCDIR([Makefile])
dnl ** check for DocBook toolchain
FP_CHECK_DOCBOOK_DTD
FP_DIR_DOCBOOK_XSL([/usr/share/xml/docbook/stylesheet/nwalsh/current /usr/share/xml/docbook/stylesheet/nwalsh /usr/share/sgml/docbook/docbook-xsl-stylesheets* /usr/share/sgml/docbook/xsl-stylesheets* /opt/kde?/share/apps/ksgmltools2/docbook/xsl /usr/share/docbook-xsl /usr/share/sgml/docbkxsl /usr/local/share/xsl/docbook /sw/share/xml/xsl/docbook-xsl])
FP_PROG_FO_PROCESSOR
AC_CONFIG_FILES([config.mk])
AC_OUTPUT
doc/docbook-xml.mk deleted 100644 → 0
View file @ 1ea1385d
#-----------------------------------------------------------------------------
# DocBook XML
.PHONY: html html-no-chunks chm HxS fo dvi ps pdf
ifneq "$(XML_DOC)" ""
all :: html
# multi-file XML document: main document name is specified in $(XML_DOC),
# sub-documents (.xml files) listed in $(XML_SRCS).
ifeq "$(XML_SRCS)" ""
XML_SRCS = $(wildcard *.xml)
endif
XML_HTML = $(addsuffix /index.html,$(basename $(XML_DOC)))
XML_HTML_NO_CHUNKS = $(addsuffix .html,$(XML_DOC))
XML_CHM = $(addsuffix .chm,$(XML_DOC))
XML_HxS = $(addsuffix .HxS,$(XML_DOC))
XML_FO = $(addsuffix .fo,$(XML_DOC))
XML_DVI = $(addsuffix .dvi,$(XML_DOC))
XML_PS = $(addsuffix .ps,$(XML_DOC))
XML_PDF = $(addsuffix .pdf,$(XML_DOC))
$(XML_HTML) $(XML_NO_CHUNKS_HTML) $(XML_FO) $(XML_DVI) $(XML_PS) $(XML_PDF) :: $(XML_SRCS)
html :: $(XML_HTML)
html-no-chunks :: $(XML_HTML_NO_CHUNKS)
chm :: $(XML_CHM)
HxS :: $(XML_HxS)
fo :: $(XML_FO)
dvi :: $(XML_DVI)
ps :: $(XML_PS)
pdf :: $(XML_PDF)
CLEAN_FILES += $(XML_HTML_NO_CHUNKS) $(XML_FO) $(XML_DVI) $(XML_PS) $(XML_PDF)
FPTOOLS_CSS = fptools.css
clean ::
$(RM) -rf $(XML_DOC).out $(basename $(XML_DOC)) $(basename $(XML_DOC))-htmlhelp
validate ::
$(XMLLINT) --valid --noout $(XMLLINT_OPTS) $(XML_DOC).xml
endif
#-----------------------------------------------------------------------------
# DocBook XML suffix rules
#
%.html : %.xml
$(XSLTPROC) --output $@ \
--stringparam html.stylesheet $(FPTOOLS_CSS) \
$(XSLTPROC_LABEL_OPTS) $(XSLTPROC_OPTS) \
$(DIR_DOCBOOK_XSL)/html/docbook.xsl $<
%/index.html : %.xml
$(RM) -rf $(dir $@)
$(XSLTPROC) --stringparam base.dir $(dir $@) \
--stringparam use.id.as.filename 1 \
--stringparam html.stylesheet $(FPTOOLS_CSS) \
$(XSLTPROC_LABEL_OPTS) $(XSLTPROC_OPTS) \
$(DIR_DOCBOOK_XSL)/html/chunk.xsl $<
cp $(FPTOOLS_CSS) $(dir $@)
# Note: Numeric labeling seems to be uncommon for HTML Help
%-htmlhelp/index.html : %.xml
$(RM) -rf $(dir $@)
$(XSLTPROC) --stringparam base.dir $(dir $@) \
--stringparam manifest.in.base.dir 1 \
--stringparam htmlhelp.chm "..\\"$(basename $<).chm \
$(XSLTPROC_OPTS) \
$(DIR_DOCBOOK_XSL)/htmlhelp/htmlhelp.xsl $<
%-htmlhelp2/collection.HxC : %.xml
$(RM) -rf $(dir $@)
$(XSLTPROC) --stringparam base.dir $(dir $@) \
--stringparam use.id.as.filename 1 \
--stringparam manifest.in.base.dir 1 \
$(XSLTPROC_OPTS) \
$(DIR_DOCBOOK_XSL)/htmlhelp2/htmlhelp2.xsl $<
# TODO: Detect hhc & Hxcomp via autoconf
#
# Two obstacles here:
#
# * The reason for the strange "if" below is that hhc returns 0 on error and 1
# on success, the opposite of what shells and make expect.
#
# * There seems to be some trouble with DocBook indices, but the *.chm looks OK,
# anyway, therefore we pacify make by "|| true". Ugly...
#
%.chm : %-htmlhelp/index.html
( cd $(dir $<) && if hhc htmlhelp.hhp ; then false ; else true ; fi ) || true
%.HxS : %-htmlhelp2/collection.HxC
( cd $(dir $<) && if Hxcomp -p collection.HxC -o ../$@ ; then false ; else true ; fi )
%.fo : %.xml
$(XSLTPROC) --output $@ \
--stringparam draft.mode no \
$(XSLTPROC_LABEL_OPTS) $(XSLTPROC_OPTS) \
$(DIR_DOCBOOK_XSL)/fo/docbook.xsl $<
ifeq "$(FOP)" ""
ifneq "$(PDFXMLTEX)" ""
%.pdf : %.fo
$(PDFXMLTEX) $<
if grep "LaTeX Warning: Label(s) may have changed.Rerun to get cross-references right." $(basename $@).log > /dev/null ; then \
$(PDFXMLTEX) $< ; \
$(PDFXMLTEX) $< ; \
fi
endif
else
%.ps : %.fo
$(FOP) $(FOP_OPTS) -fo $< -ps $@
%.pdf : %.fo
$(FOP) $(FOP_OPTS) -fo $< -pdf $@
endif
ifneq "$(XMLTEX)" ""
%.dvi : %.fo
$(XMLTEX) $<
if grep "LaTeX Warning: Label(s) may have changed.Rerun to get cross-references right." $(basename $@).log > /dev/null ; then \
$(XMLTEX) $< ; \
$(XMLTEX) $< ; \
fi
endif
doc/fptools.css deleted 100644 → 0
View file @ 1ea1385d
div {
font-family: sans-serif;
color: black;
background: white
}
h1, h2, h3, h4, h5, h6, p.title { color: #005A9C }
h1 { font: 170% sans-serif }
h2 { font: 140% sans-serif }
h3 { font: 120% sans-serif }
h4 { font: bold 100% sans-serif }
h5 { font: italic 100% sans-serif }
h6 { font: small-caps 100% sans-serif }
pre {
font-family: monospace;
border-width: 1px;
border-style: solid;
padding: 0.3em
}
pre.screen { color: #006400 }
pre.programlisting { color: maroon }
div.example {
background-color: #fffcf5;
margin: 1ex 0em;
border: solid #412e25 1px;
padding: 0ex 0.4em
}
a:link { color: #0000C8 }
a:hover { background: #FFFFA8 }
a:active { color: #D00000 }
a:visited { color: #680098 }
doc/ghc.mk 0 → 100644
View file @ c9bc29c6
# -----------------------------------------------------------------------------
#
# (c) 2009 The University of Glasgow
#
# This file is part of the GHC build system.
#
# To understand how the build system works and how to modify it, see
# http://ghc.haskell.org/trac/ghc/wiki/Building/Architecture
# http://ghc.haskell.org/trac/ghc/wiki/Building/Modifying
#
# -----------------------------------------------------------------------------
ifeq "$(BUILD_SPHINX_HTML)" "YES"
html : html_utils/haddock/doc
$(eval $(call clean-target,utils/haddock/doc,sphinx,utils/haddock/doc/haddock utils/haddock/doc/.build-html utils/haddock/doc/.build-pdf))
$(eval $(call all-target,utils/haddock/doc,html_utils/haddock/doc))
INSTALL_HTML_DOC_DIRS += utils/haddock/doc/haddock
endif
html_utils/haddock/doc :
$(MAKE) -C utils/haddock/doc html SPHINX_BUILD=$(SPHINXBUILD)
cp -R utils/haddock/doc/.build-html utils/haddock/doc/haddock
doc/haddock.xml deleted 100644 → 0
View file @ 1ea1385d
This diff is collapsed.
doc/index.rst 0 → 100644
View file @ c9bc29c6
Welcome to Haddock's documentation!
===================================
This is Haddock, a tool for automatically generating documentation from
annotated Haskell source code.
Contents:
.. toctree::
:maxdepth: 2
intro
invoking
markup
common-errors
multi-components
Indices and tables
==================
* :ref:`genindex`
* :ref:`search`
doc/intro.rst 0 → 100644
View file @ c9bc29c6
Introduction
============
This is Haddock, a tool for automatically generating documentation from
annotated Haskell source code. Haddock was designed with several goals
in mind:
- 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.
- 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.
- 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
`IDoc <https://web.archive.org/web/20180621053227/http://www.cse.unsw.edu.au/~chak/haskell/idoc/>`__. In fact,
Haddock can understand IDoc-annotated source code.
- 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.
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.
- 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.
- 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.
Obtaining Haddock
-----------------
Haddock is distributed with GHC distributions, and will automatically be provided if you use
`ghcup <https://www.haskell.org/ghcup>`__, for instance.
Up-to-date sources can also be obtained from our public GitHub
repository. The Haddock sources are at
``https://github.com/haskell/haddock``.
License
-------
The following license covers this documentation, and the Haddock source
code, except where otherwise indicated.
Copyright (c) 2002-2010, Simon Marlow
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. 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.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"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
OWNER OR CONTRIBUTORS 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.
Contributors
------------
A list of contributors to the project can be seen at
``https://github.com/haskell/haddock/graphs/contributors``.
Acknowledgements
----------------
Several documentation systems provided the inspiration for Haddock, most
notably:
- `IDoc <https://web.archive.org/web/20180621053227/http://www.cse.unsw.edu.au/~chak/haskell/idoc/>`__
- `HDoc <https://mail.haskell.org/pipermail/haskelldoc/2001-April/000067.html>`__
- `Doxygen <https://www.doxygen.nl/index.html>`__
and probably several others I've forgotten.
Thanks to the the members of haskelldoc@haskell.org,
haddock@projects.haskell.org and everyone who contributed to the many
libraries that Haddock makes use of.
doc/invoking.rst 0 → 100644
View file @ c9bc29c6
Invoking Haddock
================
Haddock is invoked from the command line, like so:
.. code-block:: none
haddock [option ...] file ...
Where each ``file`` is a filename containing a Haskell source module (.hs)
or a Literate Haskell source module (.lhs) or just a module name.
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.
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.
The modules should *not* be mutually recursive, as Haddock don't like
swimming in circles.
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.
You must also specify an option for the output format. Currently only
the :option:`--html` option for HTML, the :option:`--hoogle` option for
outputting Hoogle data, and the :option:`--latex` option are functional.
The packaging tool
`Cabal <http://www.haskell.org/ghc/docs/latest/html/Cabal/index.html>`__
has Haddock support, and is often used instead of invoking Haddock
directly.
The following options are available:
.. option:: -B <dir>
Tell GHC that its lib directory is dir. Can be used to override
the default path.
.. option:: -o <dir>
--odir=<dir>
Generate files into dir instead of the current directory.
.. option:: -l <dir>
--lib=<dir>
Use Haddock auxiliary files (themes, javascript, etc...) in dir.
.. option:: -i <file>
--read-interface=<file>
-i <docpath>,<file>
--read-interface=<docpath>,<file>
-i <docpath>,<srcpath>,<file>
--read-interface=<docpath>,<srcpath>,<file>
-i <docpath>,<srcpath>,<visibility>,<file>
Read the interface file in file, which must have been produced by
running Haddock with the :option:`--dump-interface` option. The interface
describes a set of modules whose HTML documentation is located in
docpath (which may be a relative pathname). The docpath is optional,
and defaults to “.”. The srcpath is optional but has no default
value.
This option allows Haddock to produce separate sets of documentation
with hyperlinks between them. The docpath 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
docpath means that a documentation subtree can still be moved around
without breaking links.
Similarly to docpath, srcpath is used generate cross-package
hyperlinks but within sources rendered with :option:`--hyperlinked-source`
option.
If visibility is set to `hidden`, modules from that interface file will
not be listed in haddock generated content file.
Multiple :option:`--read-interface` options may be given.
.. option:: -D <file>
--dump-interface=<file>
Produce an interface file [1]_ in the file file. 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 for more details. The interface file is
in a binary format; don't try to read it.
.. option:: --show-interface=<file>
Dumps a binary interface file to stdout in a human readable fashion.
Uses json as output format.
.. [1]
Haddock interface files are not the same as Haskell interface files,
I just couldn't think of a better name.
.. option:: --html, -h
Generate documentation in HTML format. Several files will be
generated into the current directory (or the specified directory if
the :option:`-o` option is given), including the following:
``module.html``; ``mini_module.html``
An HTML page for each module, and a "mini" page for each used
when viewing their synopsis.
``index.html``
The top level page of the documentation: lists the modules
available, using indentation to represent the hierarchy if the
modules are hierarchical.
``doc-index.html``; ``doc-index-X.html``
The alphabetic index, possibly split into multiple pages if big
enough.
``some.css``; ``etc...``
Files needed for the themes used. Specify your themes using the
:option:`--theme` option.
``haddock-util.js``
Some JavaScript utilities used to implement some of the dynamic
features like collapsible sections.
.. option:: --mathjax
Specify a custom URL for a mathjax-compatible JS script. By default,
this is set to `MathJax
<https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML>`_.
.. option:: --latex
Generate documentation in LaTeX format. Several files will be
generated into the current directory (or the specified directory if
the :option:`-o` option is given), including the following:
``package.tex``
The top-level LaTeX source file; to format the documentation
into PDF you might run something like this: ::
$ pdflatex package.tex
``haddock.sty``
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.
``module.tex``
The LaTeX documentation for each module.
.. option:: --latex-style=<style>
This option lets you override the default style used by the LaTeX
generated by the :option:`--latex` option. Normally Haddock puts a
standard ``haddock.sty`` in the output directory, and includes the
command ``\usepackage{haddock}`` in the LaTeX source. If this option
is given, then ``haddock.sty`` is not generated, and the command is
instead ``\usepackage{style}``.
.. option:: --hoogle
Generate an index file for the
`Hoogle <http://hackage.haskell.org/package/hoogle>`_ search engine.
One text file will be generated into the current directory (or the
specified directory if the :option:`-o` is given). Note that
the :option:`--package-name` is required.
Since the output is intended to be parsed by Hoogle, some conventions
need to be upheld:
* Every entity should span exactly one line. ::
newtype ReaderT r (m :: * -> *) a :: * -> (* -> *) -> * -> *
The one exception to this rule is classes. The body of a class
is split up with one class member per line, an opening brace on
the line of the header, and a closing brace on a new line after
the class. ::
class Foo a where {
foo :: a -> a -> Baz a;
type family Baz a;
type Baz a = [(a, a)];
}
* Entites that are exported only indirectly (for instance data
constructors visible via a ``ReaderT(..)`` export) have their names
wrapped in square brackets. ::
[ReaderT] :: (r -> m a) -> ReaderT r m a
[runReaderT] :: ReaderT r m a -> r -> m a
.. option:: --hyperlinked-source
Generate hyperlinked source code (as HTML web page). All rendered
files will be put into ``src/`` subfolder of output directory.
Usually, this should be used in combination with :option:`--html` 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:`--source-module`, :option:`--source-entity` and
related options. Note that these flags are ignored once
:option:`--hyperlinked-source` is set.
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:: --source-css=<style>
Use custom CSS file for sources rendered by the
:option:`--hyperlinked-source` option. If no custom style file is
provided, Haddock will use default one.
.. option:: -S, --docbook
Reserved for future use (output documentation in DocBook XML
format).
.. option:: --base-url=<url>
Base url for static assets (eg. css, javascript, json files etc.).
When present, static assets are not copied. This option is useful
when creating documentation for multiple packages, it allows to have
a single copy of static assets served from the given url.
.. option:: --source-base=<url>
--source-module=<url>
--source-entity=<url>
--source-entity-line=<url>
Include links to the source files in the generated documentation.
Use the :option:`--source-base` option to add a source code link in the
header bar of the contents and index pages. Use the
:option:`--source-module` to add a source code link in the header bar of
each module page. Use the :option:`--source-entity` option to add a source
code link next to the documentation for every value and type in each
module. :option:`--source-entity-line` 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.
In each case URL 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 URL:
- The string ``%M`` or ``%{MODULE}`` is replaced by the module
name. Note that for the per-entity URLs this is the name of the
*exporting* module.
- The string ``%N`` or ``%{NAME}`` is replaced by the name of the
exported value or type. This is only valid for the
:option:`--source-entity` option.
- The string ``%K`` or ``%{KIND}`` is replaced by a flag indicating
whether the exported name is a value ``v`` or a type
``t``. This is only valid for the :option:`--source-entity` option.
- The string ``%L`` or ``%{LINE}`` 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.
- The string ``%%`` is replaced by ``%``.
If you have html versions of your sources online with anchors for
each type and function name, you would say
``haddock --source-base=url/ --source-module=url/%M.html --source-entity=url/%M.html#%N``
For the ``%{MODULE}`` substitution you may want to replace the
``.`` character in the module names with some other character
(some web servers are known to get confused by multiple ``.``
characters in a file name). To replace it with a character c use
``%{MODULE/./c}``.
One example of a tool that can generate syntax-highlighted HTML from
your source code, complete with anchors suitable for use from
haddock, is
`hscolour <http://www.cs.york.ac.uk/fp/darcs/hscolour>`__.
.. option:: -s <url>
--source=<url>
Deprecated aliases for :option:`--source-module`
.. option:: --comments-base=<url>
--comments-module=<url>
--comments-entity=<url>
documentation. This feature would typically be used in conjunction
with a Wiki system.
Use the :option:`--comments-base` option to add a user comments link in
the header bar of the contents and index pages. Use the
:option:`--comments-module` to add a user comments link in the header bar
of each module page. Use the :option:`--comments-entity` option to add a
comments link next to the documentation for every value and type in
each module.
In each case URL 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` and
:option:`--source-entity` options above.
For example, if you want to link the contents page to a wiki page,
and every module to subpages, you would say
``haddock --comments-base=url --comments-module=url/%M``
If your Wiki system doesn't like the ``.`` character in Haskell
module names, you can replace it with a different character. For
example to replace the ``.`` characters with ``_`` use
``haddock --comments-base=url --comments-module=url/%{MODULE/./_}``.
Similarly, you can replace the ``/`` in a file name (may be useful for
entity comments, but probably not).
.. option:: --theme=<path>
Specify a theme to be used for HTML (:option:`--html`) 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 ("Linuwial") is used.
The path parameter can be one of:
- A *directory*: The base name of the directory becomes the name of
the theme. The directory must contain exactly one ``some.css``
file. Other files, usually image files, will be copied, along
with the ``some.css`` file, into the generated output directory.
- A *CSS file*: The base name of the file becomes the name of the
theme.
- The *name* of a built-in theme ("Linuwial", "Ocean", or "Classic").
.. option:: --built-in-themes
Includes the built-in themes ("Linuwial", "Ocean", and "Classic"). Can be
combined with :option:`--theme`. Note that order matters: The first
specified theme will be the default.
.. option:: --use-unicode
Enable use of Unicode characters in HTML output.
.. option:: -c <file>
--css=<file>
Deprecated aliases for :option:`--theme`
.. option:: -p <file>
--prologue=<file>
Specify a file containing documentation which is placed on the main
contents page under the heading “Description”. The file is parsed as
a normal Haddock doc comment (but the comment markers are not
required).
.. option:: -t <title>
--title=<title>
Use title as the page heading for each page in the
documentation.This will normally be the name of the library being
documented.
The title should be a plain string (no markup please!).
.. option:: --package-name=<name>
Specify the name of the package being documented.
.. option:: --package-version=<version>
Specify the version of the package being documented.
.. option:: -q <mode>
--qual=<mode>
Specify how identifiers are qualified.
mode should be one of
- ``none`` (default): don't qualify any identifiers
- ``full``: always qualify identifiers completely
- ``local``: only qualify identifiers that are not part of the module
- ``relative``: like local, but strip name of the module from
qualifications of identifiers in submodules
Example: If you generate documentation for module A, then the
identifiers A.x, A.B.y and C.z are qualified as follows.
- none: x, y, z
- full: A.x, A.B.y, C.z
- local: x, A.B.y, C.z
- relative: x, B.y, C.z
.. option:: --since-qual=<mode>
Specify how ``@since`` annotations are qualified.
mode should be one of
- ``always`` (default): always qualify ``@since`` annotations with
a package name and version
- ``only-external``: only qualify ``@since`` annotations with a
package name and version when they do not come from the current
package
.. option:: -?
--help
Display help and exit.
.. option:: -V
--version
Output version information and exit.
.. option:: --ghc-version
Output the version of GHC which Haddock expects to find at :option:-B
and exit.
.. option:: --print-ghc-path
Output the path to the GHC (which Haddock computes based on :option:-B)
and exit.
.. option:: --print-ghc-libdir
Output the path to the GHC ``lib`` directory (which Haddock computes
based on :option:-B) and exit.
.. option:: -v
--verbose
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 ``Prelude``).
.. option:: --use-contents=<url>
--use-index=<url>
When generating HTML, do not generate an index. Instead, redirect
the Contents and/or Index link on each page to URL. This option is
intended for use in conjunction with :option:`--gen-contents` and/or
:option:`--gen-index` for generating a separate contents and/or index
covering multiple libraries.
.. option:: --gen-contents
--gen-index
Generate an HTML contents and/or index containing entries pulled
from all the specified interfaces (interfaces are specified using
:option:`-i` or :option:`--read-interface`). This is used to generate a single
contents and/or index for multiple sets of Haddock documentation.
.. option:: --hide <module>
Causes Haddock to behave as if module module has the ``hide``
attribute. (:ref:`module-attrs`).
.. option:: --show <module>
Causes Haddock to behave as if module module does not have the ``hide``
attribute. (:ref:`module-attrs`).
.. option:: --show-all
Causes Haddock to behave as if no modules have the ``hide`` attribute.
(:ref:`module-attrs`).
.. option:: --show-extensions <module>
Causes Haddock to behave as if module module has the
``show-extensions`` attribute. (:ref:`module-attrs`).
.. option:: --optghc=<option>
Pass option to GHC. Note that there is a double dash there, unlike
for GHC.
.. option:: -w
--no-warnings
Turn off all warnings.
.. option:: --interface-version
Prints out the version of the binary Haddock interface files that
this version of Haddock generates.
.. option:: --compatible-interface-versions
Prints out space-separated versions of binary Haddock interface
files that this version of Haddock is compatible with.
.. option:: --bypass-interface-version-check
**DANGEROUS** Causes Haddock to ignore the interface versions of
binary Haddock interface files. This can make Haddock crash during
deserialization of interface files.
.. option:: --no-tmp-comp-dir
Do not use a temporary directory for reading and writing compilation
output files (``.o``, ``.hi``, and stub files). Instead, use the
present directory or another directory that you have explicitly told
GHC to use via the :option:`--optghc` flag.
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.
.. option:: --print-missing-docs
Print extra information about any undocumented entities.
.. option:: --trace-args
Make Haddock print the arguments it receives to standard output. This is
useful for examining arguments when invoking through ``cabal haddock``, as
``cabal`` uses temporary `response files
<https://gcc.gnu.org/wiki/Response_Files>`_ to pass arguments to Haddock.
Using literate or pre-processed source
--------------------------------------
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 ``-cpp``
option to GHC using :option:`--optghc`.
Avoiding recompilation
----------------------
With the advent of "hi-haddock", Haddock now produces documentation from ``.hi``
(Haskell interface) files and ``.hie`` (``.hi`` extended) files [#]_, rather
than typechecked module results. This means that as long as the necessary
``.hi`` and ``.hie`` files are available (i.e. produced by your build process),
recompilation can be avoided during documentation generation.
.. [#] Note that ``.hie`` files are only necessary to build documentation which
includes hyperlinked source files `like this one
<https://hackage.haskell.org/package/base-4.18.0.0/docs/src/GHC.Base.html>`_,
while ``.hi`` files are required for all Haddock documentation flavors.
The first step is to ensure that your build process is producing ``.hi`` files
that contain Haddock docstrings. This requires that you somehow provide the
``-fwrite-interface`` and ``-haddock`` flags to GHC. If you intend to generate
documentation that includes hyperlinked source files, you should also provide
the ``-fwrite-ide-info`` flag to GHC. You may specify the directory in which GHC
should write the ``.hi`` and ``.hie`` files by providing the
``-hidir=/path/to/hidir`` and ``-hiedir=/path/to/hiedir`` flags to GHC. If you
are building your application with ``cabal build``, the default location is in
``dist-newstyle/build/<arch>-<os>/ghc-<ghc-version>/<component>-0.1.0/build``.
The next step is to ensure that the flags which Haddock passes to GHC will not
trigger recompilation. Unfortunately, this is not very easy to do if you are
invoking Haddock through ``cabal haddock``. Upon ``cabal haddock``, Cabal passes
a ``--optghc="-optP-D__HADDOCK_VERSION__=NNNN"`` (where ``NNNN`` is the Haddock
version number) flag to Haddock, which forwards the ``-optP=...`` flag to GHC
and triggers a recompilation (unless the existing build results were also
created by a ``cabal haddock``). Additionally, Cabal passes a
``--optghc="-stubdir=<temp directory>"`` flag to Haddock, which forwards the
``-stubdir=<temp directory>`` flag to GHC and triggers a recompilation since
``-stubdir`` adds a global include directory. Moreover, since the ``stubdir``
that Cabal passes is a temporary directory, a recompilation is triggered even
for immediately successive invocations. To avoid recompilations due to these
flags, one must manually extract the arguments passed to Haddock by Cabal and
remove the ``--optghc="-optP-D__HADDOCK_VERSION__=NNNN"`` and
``--optghc="-stubdir=<temp directory>"`` flags. This can be achieved using the
:option:`--trace-args` flag by invoking ``cabal haddock`` with
``--haddock-option="--trace-args"`` and copying the traced arguments to a script
which makes an equivalent call to Haddock without the aformentioned flags.
In addition to the above, Cabal passes a temporary directory as ``-hidir`` to
Haddock by default. Obviously, this also triggers a recompilation for every
invocation of ``cabal haddock``, since it will never find the necessary
interface files in that temporary directory. To remedy this, pass a
``--optghc="-hidir=/path/to/hidir"`` flag to Haddock, where ``/path/to/hidir``
is the path to the directory in which your build process is writing ``.hi``
files.
Following the steps above will allow you to take full advantage of "hi-haddock"
and generate Haddock documentation from existing build results without requiring
any further compilation.
doc/markup.rst 0 → 100644
View file @ c9bc29c6
Documentation and Markup
========================
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.
.. _top-level-declaration:
Documenting a Top-Level Declaration
-----------------------------------
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: ::
square :: Int -> Int
square x = x * x
Then we can document it like this: ::
-- |The 'square' function squares an integer.
square :: Int -> Int
square x = x * x
The ``-- |`` syntax begins a documentation annotation, which applies
to the *following* declaration in the source file. Note that the
annotation is just a comment in Haskell — it will be ignored by the
Haskell compiler.
The declaration following a documentation annotation should be one of
the following:
- A type signature for a top-level function,
- A definition for a top-level function with no type signature,
- A ``data`` declaration,
- A ``pattern`` declaration,
- A ``newtype`` declaration,
- A ``type`` declaration
- A ``class`` declaration,
- An ``instance`` declaration,
- A ``data family`` or ``type family`` declaration, or
- A ``data instance`` or ``type instance`` declaration.
If the annotation is followed by a different kind of declaration, it
will probably be ignored by Haddock.
Some people like to write their documentation *after* the declaration;
this is possible in Haddock too: ::
square :: Int -> Int
-- ^The 'square' function squares an integer.
square x = x * x
Since Haddock uses the GHC API internally, it can infer types for
top-level functions without type signatures. However, you're
encouraged to add explicit type signatures for all top-level
functions, to make your source code more readable for your users, and
at times to avoid GHC inferring overly general type signatures that
are less helpful to your users.
Documentation annotations may span several lines; the annotation
continues until the first non-comment line in the source file. For
example: ::
-- |The 'square' function squares an integer.
-- It takes one argument, of type 'Int'.
square :: Int -> Int
square x = x * x
You can also use Haskell's nested-comment style for documentation
annotations, which is sometimes more convenient when using multi-line
comments: ::
{-|
The 'square' function squares an integer.
It takes one argument, of type 'Int'.
-}
square :: Int -> Int
square x = x * x
Documenting Parts of a Declaration
----------------------------------
In addition to documenting the whole declaration, in some cases we can
also document individual parts of the declaration.
Class Methods
~~~~~~~~~~~~~
Class methods are documented in the same way as top level type
signatures, by using either the ``-- |`` or ``-- ^`` annotations: ::
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
Associated type and data families can also be annotated in this way.
Constructors and Record Fields
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Constructors are documented like so: ::
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
or like this: ::
data T a b
= C1 -- ^ This is the documentation for the 'C1' constructor
a -- ^ This is the documentation for the argument of type 'a'
b -- ^ This is the documentation for the argument of type 'b'
There is one edge case that is handled differently: only one ``-- ^``
annotation occurring after the constructor and all its arguments is
applied to the constructor, not its last argument: ::
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
Record fields are documented using one of these styles: ::
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
}
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.
In cases where more than one constructor exports a field with the same
name, the documentation attached to the first occurrence of the field
will be used, even if a comment is not present. ::
data T a = A { someField :: a -- ^ Doc for someField of A
}
| B { someField :: a -- ^ Doc for someField of B
}
In the above example, all occurrences of ``someField`` in the
documentation are going to be documented with
``Doc for someField of A``. 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 ``someField``
is actually the same (partial) function.
Deriving clauses
~~~~~~~~~~~~~~~~
Most instances are top-level, so can be documented as in
:ref:`top-level-declaration`. The exception to this is instance that are
come from a ``deriving`` clause on a datatype declaration. These can
be documented like this: ::
data D a = L a | M
deriving ( Eq -- ^ @since 4.5
, Ord -- ^ default 'Ord' instance
)
This also scales to the various GHC extensions for deriving: ::
newtype T a = T a
deriving Show -- ^ derivation of 'Show'
deriving stock ( Eq -- ^ stock derivation of 'Eq'
, Foldable -- ^ stock derivation of 'Foldable'
)
deriving newtype Ord -- ^ newtype derivation of 'Ord'
deriving anyclass Read -- ^ unsafe derivation of 'Read'
deriving ( Eq1 -- ^ deriving 'Eq1' via 'Identity'
, Ord1 -- ^ deriving 'Ord1' via 'Identity'
) via Identity
Function Arguments
~~~~~~~~~~~~~~~~~~
Individual arguments to a function may be documented like this: ::
f :: Int -- ^ The 'Int' argument
-> Float -- ^ The 'Float' argument
-> IO () -- ^ The return value
Pattern synonyms, GADT-style data constructors, and class methods also
support this style of documentation.
.. _module-description:
The Module Description
----------------------
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. ::
{-|
Module : W
Description : Short description
Copyright : (c) Some Person, 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
...
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 the ``--`` syntax, the consecutive lines have
to start at two spaces at the very least. For example, above we saw a
multiline ``Copyright`` field: ::
{-|
...
Copyright : (c) Some Person, 2013
Someone Else, 2014
...
-}
That could equivalently be written as: ::
-- | ...
-- Copyright:
-- (c) Some Person, 2013
-- Someone Else, 2014
-- ...
or as: ::
-- | ...
-- Copyright: (c) Some Person, 2013
-- Someone Else, 2014
-- ...
but not as: ::
-- | ...
-- Copyright: (c) Some Person, 2013
-- Someone Else, 2014
-- ...
since the ``Someone`` needs to be indented more than the
``Copyright``.
Whether new lines and other formatting in multiline fields is
preserved depends on the field type. For example, new lines in the
``Copyright`` field are preserved, but new lines in the
``Description`` field are not; leading whitespace is not preserved in
either [#backend]_. Please note that we do not enforce the format for
any of the fields and the established formats are just a convention.
.. [#backend] Technically, whitespace and newlines in the
``Description`` field are preserved verbatim by the HTML backend,
but because most browsers collapse whitespace in HTML, they don't
render as such. But other backends may render this whitespace.
Fields of the Module Description
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ``Module`` field specifies the current module name. Since the module
name can be inferred automatically from the source file, it doesn't
affect the output of any of the backends. But you might want to
include it for any other tools that might be parsing these comments
without the help of GHC.
The ``Description`` 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.
The ``Copyright``, ``License``, ``Maintainer`` and ``Stability`` fields should
be obvious. An alternative spelling for the ``License`` field is accepted
as ``Licence`` but the output will always prefer ``License``.
The ``Portability`` 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 ``show-extensions`` module
flag for the latter (see :ref:`module-attrs`).
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 ``Description`` in the documentation for the module. All the
usual Haddock :ref:`markup` is valid in this comment.
Controlling the Documentation Structure
---------------------------------------
Haddock produces interface documentation that lists only the entities
actually exported by the module. If there is no export list then all
entities defined by the module are exported.
The documentation for a module will
include *all* entities exported by that module, even if they were
re-exported from 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.
To Haddock the export list has even more significance than just
specifying the entities to be included in the documentation. It also
specifies the *order* 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 *module* 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.
In the next section we give examples illustrating most of the
structural markup features. After the examples we go into more detail
explaining the related markup, namely :ref:`section-headings`,
:ref:`named-chunks`, and :ref:`re-exporting-entire-module`.
.. _structure-examples:
Documentation Structure Examples
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
We now give several examples that produce similar results and
illustrate most of the structural markup features. The first two
examples use an export list, but the third example does not.
The first example, using an export list with :ref:`section-headings`
and inline section descriptions: ::
module Image
( -- * Image importers
--
-- | There is a "smart" importer, 'readImage', that determines
-- the image format from the file extension, and several
-- "dumb" format-specific importers that decode the file as
-- the specified type.
readImage
, readPngImage
, readGifImage
, ...
-- * Image exporters
-- ...
) where
import Image.Types ( Image )
-- | Read an image, guessing the format from the file name.
readImage :: FilePath -> IO Image
readImage = ...
-- | Read a GIF.
readGifImage :: FilePath -> IO Image
readGifImage = ...
-- | Read a PNG.
readPngImage :: FilePath -> IO Image
readPngImage = ...
...
Note that the order of the entities ``readPngImage`` and
``readGifImage`` in the export list is different from the order of the
actual declarations farther down; the order in the export list is the
order used in the generated docs. Also, the imported ``Image`` type
itself is not re-exported, so it will not be included in the rendered
docs (see :ref:`hyperlinking-re-exported`).
The second example, using an export list with a section description
defined elsewhere (the ``$imageImporters``; see :ref:`named-chunks`):
::
module Image
( -- * Image importers
--
-- $imageImporters
readImage
, readPngImage
, readGifImage
, ...
-- * Image exporters
-- ...
) where
import Image.Types ( Image )
-- $imageImporters
--
-- There is a "smart" importer, 'readImage', that determines the
-- image format from the file extension, and several "dumb"
-- format-specific importers that decode the file as the specified
-- type.
-- | Read an image, guessing the format from the file name.
readImage :: FilePath -> IO Image
readImage = ...
-- | Read a GIF.
readGifImage :: FilePath -> IO Image
readGifImage = ...
-- | Read a PNG.
readPngImage :: FilePath -> IO Image
readPngImage = ...
...
This produces the same rendered docs as the first example, but the
source code itself is arguably more readable, since the documentation
for the group of importer functions is closer to their definitions.
The third example, without an export list: ::
module Image where
import Image.Types ( Image )
-- * Image importers
--
-- $imageImporters
--
-- There is a "smart" importer, 'readImage', that determines the
-- image format from the file extension, and several "dumb"
-- format-specific importers that decode the file as the specified
-- type.
-- | Read an image, guessing the format from the file name.
readImage :: FilePath -> IO Image
readImage = ...
-- | Read a GIF.
readGifImage :: FilePath -> IO Image
readGifImage = ...
-- | Read a PNG.
readPngImage :: FilePath -> IO Image
readPngImage = ...
...
-- * Image exporters
-- ...
Note that the section headers (e.g. ``-- * Image importers``) now
appear in the module body itself, and that the section documentation
is still given using :ref:`named-chunks`. Unlike in the first example
when using an export list, the named chunk syntax ``$imageImporters``
*must* be used for the section documentation; attempting to use the
``-- | ...`` syntax to document the image importers here will wrongly
associate the documentation chunk with the next definition!
.. _section-headings:
Section Headings
~~~~~~~~~~~~~~~~
You can insert headings and sub-headings in the documentation by
including annotations at the appropriate point in the export list, or
in the module body directly when not using an export list.
For example: ::
module Foo (
-- * Classes
C(..),
-- * Types
-- ** A data type
T,
-- ** A record
R,
-- * Some functions
f, g
) where
Headings are introduced with the syntax ``-- *``, ``-- **`` and so
on, where the number of ``*``\ s indicates the level of the heading
(section, sub-section, sub-sub-section, etc.).
If you use section headings, then Haddock will generate a table of
contents at the top of the module documentation for you.
By default, when generating HTML documentation Haddock will create an
anchor to each section of the form ``#g:n``, where ``n`` is an integer
that might change as you add new section headings. If you want to
create stable links, you can add an explicit anchor (see
:ref:`anchors`) after the section heading: ::
module Foo (
-- * Classes #classes#
C(..)
) where
This will create an HTML anchor ``#g:classes`` to the section.
The alternative style of placing the commas at the beginning of each
line is also supported, e.g.: ::
module Foo (
-- * Classes
C(..)
-- * Types
-- ** A data type
, T
-- ** A record
, R
-- * Some functions
, f
, g
) where
When not using an export list, you may insert section headers in the
module body. Such section headers associate with all entities
declared up until the next section header. For example: ::
module Foo where
-- * Classes
class C a where ...
-- * Types
-- ** A data type
data T = ...
-- ** A record
data R = ...
-- * Some functions
f :: ...
f = ...
g :: ...
g = ...
.. _re-exporting-entire-module:
Re-Exporting an Entire Module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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: ::
module A (
module B,
module C
) where
What will the Haddock-generated documentation for this module look like?
Well, it depends on how the modules ``B`` and ``C`` are imported. If
they are imported wholly and without any ``hiding`` qualifiers, then the
documentation will just contain a cross-reference to the documentation
for ``B`` and ``C``.
However, if the modules are not *completely* re-exported, for example:
::
module A (
module B,
module C
) where
import B hiding (f)
import C (a, b)
then Haddock behaves as if the set of entities re-exported from ``B``
and ``C`` had been listed explicitly in the export list.
The exception to this rule is when the re-exported module is declared
with the ``hide`` attribute (see :ref:`module-attrs`), in which
case the module is
never cross-referenced; the contents are always expanded in place in the
re-exporting module.
.. _named-chunks:
(Named) Chunks of Documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
It is often desirable to include a chunk of documentation which is not
attached to any particular Haskell declaration, for example, when
giving summary documentation for a group of related definitions (see
:ref:`structure-examples`). In addition to including such documentation
chunks at the top of the file, as part of the
:ref:`module-description`, you can also associate them with
:ref:`section-headings`.
There are several ways to associate documentation chunks with section
headings, depending on whether you are using an export list or not:
- The documentation can be included in the export list directly, by
preceding it with a ``-- |``. For example: ::
module Foo (
-- * A section heading
-- | Some documentation not attached to a particular Haskell entity
...
) where
In this case the chunk is not "named".
- 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
``-- $``, which we call a *named chunk*: ::
module Foo (
-- * A section heading
-- $doc
...
) where
-- $doc
-- Here is a large chunk of documentation which may be referred to by
-- the name $doc.
The documentation chunk is given a name of your choice (here
``doc``), which is the sequence of alphanumeric characters directly
after the ``-- $``, and it may be referred to by the same name in
the export list. Note that named chunks must come *after* any
imports in the module body.
- If you aren't using an export list, then your only choice is to use
a named chunk with the ``-- $`` syntax. For example: ::
module Foo where
-- * A section heading
--
-- $doc
-- Here is a large chunk of documentation which may be referred to by
-- the name $doc.
Just like with entity declarations when not using an export list,
named chunks of documentation are associated with the preceding
section header here, or with the implicit top-level documentation
section if there is no preceding section header.
**Warning**: the form used in the first bullet above, where the
chunk is not named, *does not work* when you aren't using an
export list. For example: ::
module Foo where
-- * A section heading
--
-- | Some documentation not attached to a particular Haskell entity
-- | The fooifier.
foo :: ...
will result in ``Some documentation not ...`` being attached to the
*next* entity declaration, here ``foo``, in addition to any other
documentation that next entity already has!
.. _hyperlinking-re-exported:
Hyperlinking and Re-Exported Entities
-------------------------------------
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?
Let's look at an example. Suppose we have three modules ``A``, ``B`` and
``C`` defined as follows: ::
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
Module ``A`` exports a datatype ``T``. Module ``B`` imports ``A`` and
exports a function ``f`` whose type refers to ``T``. Also, both ``T``
and ``f`` are re-exported from module C.
Haddock takes the view that each entity has a *home* 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.
How is the home module for an entity determined? Haddock uses the
following rules:
- If modules A and B both export the entity, and module A imports
(directly or indirectly) module B, then B is preferred.
- A module with the ``hide`` attribute is never chosen as the home.
- A module with the ``not-home`` attribute is only chosen if there are
no other modules to choose.
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.
In the example above, module ``A`` is chosen as the home for ``T``
because it does not import any other module that exports ``T``. The link
from ``f``'s type in module ``B`` will therefore point to ``A.T``.
However, ``C`` also exports ``T`` and ``f``, and the link from ``f``'s
type in ``C`` will therefore point locally to ``C.T``.
.. _module-attrs:
Module Attributes
-----------------
Certain attributes may be specified for each module which affect the
way that Haddock generates documentation for that module. Attributes are
specified in a comma-separated list in an
``{-# OPTIONS_HADDOCK ... #-}`` pragma at the top of the module, either
before or after the module description. For example: ::
{-# OPTIONS_HADDOCK hide, prune #-}
-- |Module description
module A where
...
The options and module description can be in either order.
The following attributes are currently understood by Haddock:
``hide``
Omit this module from the generated documentation, but nevertheless
propagate definitions and documentation from within this module to
modules that re-export those definitions.
``prune``
Omit definitions that have no documentation annotations from the
generated documentation.
``not-home``
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 :ref:`hyperlinking-re-exported`
for more details.
``show-extensions``
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.
``print-explicit-runtime-reps``
Print type variables that have kind ``RuntimeRep``. By default, these
are defaulted to ``LiftedRep`` so that end users don't have to see the
underlying levity polymorphism. This flag is analogous to GHC's
``-fprint-explicit-runtime-reps`` flag.
.. _markup:
Markup
------
Haddock understands certain textual cues inside documentation
annotations that tell it how to render the documentation. The cues (or
“markup”) have been designed to be simple and mnemonic in ASCII so
the programmer doesn't have to deal with heavyweight annotations when
editing documentation comments.
Paragraphs
~~~~~~~~~~
One or more blank lines separates two paragraphs in a documentation
comment.
Special Characters
~~~~~~~~~~~~~~~~~~
The following characters have special meanings in documentation comments:
``\``, ``/``, ``'``, `````, ``"``, ``@``, ``<``, ``$``, ``#``. To insert a
literal occurrence of one of these special characters, precede it with a
backslash (``\``).
Additionally, the character ``>`` has a special meaning at the beginning
of a line, and the following characters have special meanings at the
beginning of a paragraph: ``*``, ``-``. These characters can also be
escaped using ``\``.
Furthermore, the character sequence ``>>>`` has a special meaning at the
beginning of a line. To escape it, just prefix the characters in the
sequence with a backslash.
Character References
~~~~~~~~~~~~~~~~~~~~
Although Haskell source files may contain any character from the Unicode
character set, the encoding of these characters as bytes varies between
systems. Consequently, 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 ``&#``\ D\ ``;`` and ``&#x``\ H\ ``;`` where D
and H are decimal and hexadecimal numbers denoting a code position in
Unicode (or ISO 10646). For example, the references ``&#x3BB;``,
``&#x3bb;`` and ``&#955;`` all represent the lower-case letter lambda.
Code Blocks
~~~~~~~~~~~
Displayed blocks of code are indicated by surrounding a paragraph with
``@...@`` or by preceding each line of a paragraph with ``>`` (we often
call these “bird tracks”). For example: ::
-- | This documentation includes two blocks of code:
--
-- @
-- f x = x + x
-- @
--
-- > g x = x * 42
There is an important difference between the two forms of code block: in
the bird-track form, the text to the right of the ‘\ ``>``\ ’ is
interpreted literally, whereas the ``@...@`` form interprets markup as
normal inside the code block. In particular, ``/`` is markup for italics,
and so e.g. ``@x / y / z@`` renders as ``x`` followed by italic
``y`` with no slashes, followed by ``z``.
Examples
~~~~~~~~
Haddock has markup support for examples of interaction with a
*read-eval-print loop (REPL)*. An example is introduced with ``>>>``
followed by an expression followed by zero or more result lines: ::
-- | Two examples are given below:
--
-- >>> fib 10
-- 55
--
-- >>> putStrLn "foo\nbar"
-- foo
-- bar
Result lines that only contain the string ``<BLANKLINE>`` are rendered
as blank lines in the generated documentation.
Properties
~~~~~~~~~~
Haddock provides markup for properties: ::
-- | Addition is commutative:
--
-- prop> a + b = b + a
This allows third-party applications to extract and verify them.
Hyperlinked Identifiers
~~~~~~~~~~~~~~~~~~~~~~~
Referring to a Haskell identifier, whether it be a type, class,
constructor, or function, is done by surrounding it with a combination
of single quotes and backticks. For example: ::
-- | This module defines the type 'T'.
```T``` is also ok. ``'T``` and ```T'`` are accepted but less common.
If there is an entity ``T`` in scope in the current module, then the
documentation will hyperlink the reference in the text to the definition
of ``T`` (if the output format supports hyperlinking, of course; in a
printed format it might instead insert a page reference to the
definition).
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: ::
-- | The identifier 'M.T' is not in scope
If ``M.T`` is not otherwise in scope, then Haddock will simply emit a
link pointing to the entity ``T`` exported from module ``M`` (without
checking to see whether either ``M`` or ``M.T`` exist).
Since values and types live in different namespaces in Haskell, it is possible
for a reference such as ``'X'`` to be ambiguous. In such a case, Haddock
defaults to pointing to the type. The ambiguity can be overcome by explicitly
specifying a namespace, by way of a ``v`` (for value) or ``t`` (for type)
immediately before the link: ::
-- | An implicit reference to 'X', the type constructor
-- An explicit reference to v'X', the data constructor
-- An explicit reference to t'X', the type constructor
data X = X
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: ::
-- | I don't have to escape my apostrophes; great, isn't it?
Nothing special is needed to hyperlink identifiers which contain
apostrophes themselves: to hyperlink ``foo'`` one would simply type
``'foo''``. Hyperlinking operators works in exactly the same way. ::
-- | A prefix operator @'(++)'@ and an infix identifier @'`elem`'@.
Emphasis, Bold and Monospaced Styled Text
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Text can be emphasized, made bold (strong) or monospaced (typewriter font)
by surrounding it with slashes, double-underscores or at-symbols: ::
-- | This is /emphasized text/, __bold text__ and @monospaced text@.
Note that those styled texts must be kept on the same line: ::
-- | Styles /do not work
-- | when continuing on the next line/
Other markup is valid inside emphasized, bold and monospaced text.
Frequent special cases:
* To have a forward slash inside of emphasis, just escape it: ``/fo\/o/``.
* There's no need to escape a single underscore if you need it
bold: ``__This_text_with_underscores_is_bold__``.
* ``@'f' a b@`` will hyperlink the identifier ``f`` inside the code
fragment.
* ``@__FILE__@`` will render ``FILE`` in bold with no underscores,
which may not be what you had in mind.
Linking to Modules
~~~~~~~~~~~~~~~~~~
Linking to a module is done by surrounding the module name with double
quotes: ::
-- | This is a reference to the "Foo" module.
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.
It is also possible to specify alternate text for the generated link
using syntax analogous to that used for URLs: ::
-- | This is a reference to [the main module]("Module.Main").
Itemized and Enumerated Lists
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A bulleted item is represented by preceding a paragraph with either
“``*``” or “``-``”. A sequence of bulleted paragraphs is rendered as an
itemized list in the generated documentation, e.g.: ::
-- | This is a bulleted list:
--
-- * first item
--
-- * second item
An enumerated list is similar, except each paragraph must be preceded by
either “``(n)``” or “``n.``” where n is any integer. e.g. ::
-- | This is an enumerated list:
--
-- (1) first item
--
-- 2. second item
Lists of the same type don't have to be separated by a newline: ::
-- | This is an enumerated list:
--
-- (1) first item
-- 2. second item
--
-- This is a bulleted list:
--
-- * first item
-- * second item
You can have more than one line of content in a list element: ::
-- |
-- * first item
-- and more content for the first item
-- * second item
-- and more content for the second item
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 paragraphs: ::
{-|
* 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.
-}
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. ::
{-|
* foo
* bar
-}
Definition Lists
~~~~~~~~~~~~~~~~
Definition lists are written as follows: ::
-- | This is a definition list:
--
-- [@foo@]: The description of @foo@.
--
-- [@bar@]: The description of @bar@.
To produce output something like this:
``foo``
The description of ``foo``.
``bar``
The description of ``bar``.
Each paragraph should be preceded by the “definition term” enclosed in
square brackets and followed by a colon. Other markup operators may be
used freely within the definition term. You can escape ``]`` with a
backslash as usual.
Same rules about nesting and no newline separation as for bulleted and
numbered lists apply.
URLs
~~~~
A URL can be included in a documentation comment by surrounding it in
angle brackets, for example: ::
<http://example.com>
If the output format supports it, the URL will be turned into a
hyperlink when rendered.
If Haddock sees something that looks like a URL (such as something
starting with ``http://`` or ``ssh://``) where the URL markup is valid,
it will automatically make it a hyperlink.
Links
~~~~~
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: ::
[some link](http://example.com)
The link text is used as a description for the URL if the output
format supports it.
Images
~~~~~~
Haddock supports Markdown syntax for inline images. This resembles the
syntax for links, but starts with an exclamation mark. An example looks
like this: ::
![image description](pathtoimage.png)
If the output format supports it, the image will be rendered inside the
documentation. The image description is used as replacement text and/or
an image title.
Mathematics / LaTeX
~~~~~~~~~~~~~~~~~~~
Haddock supports LaTeX syntax for rendering mathematical notation. The
delimiters are ``\[...\]`` for displayed mathematics and ``\(...\)``
for in-line mathematics. An example looks like this: ::
\[
f(a) = \frac{1}{2\pi i}\oint_\gamma \frac{f(z)}{z-a}\,\mathrm{d}z
\]
If the output format supports it, the mathematics will be rendered
inside the documentation. For example, the HTML backend will display
the mathematics via `MathJax <https://www.mathjax.org>`__.
Grid Tables
~~~~~~~~~~~
Inspired by reSTs grid tables, Haddock supports a complete table representation
via grid-like "ASCII art". Grid tables are described with a visual grid made
up of the characters "-", "=", "|", and "+". The hyphen ("-") is used for
horizontal lines (row separators). The equals sign ("=") may be used to
separate optional header rows from the table body. The vertical bar ("|") is
used for vertical lines (column separators). The plus sign ("+") is used for
intersections of horizontal and vertical lines. ::
-- | This is a grid table:
--
-- +------------------------+------------+----------+----------+
-- | Header row, column 1 | Header 2 | Header 3 | Header 4 |
-- | (header rows optional) | | | |
-- +========================+============+==========+==========+
-- | body row 1, column 1 | column 2 | column 3 | column 4 |
-- +------------------------+------------+----------+----------+
-- | body row 2 | Cells may span columns. |
-- +------------------------+------------+---------------------+
-- | body row 3 | Cells may | \[ |
-- +------------------------+ span rows. | f(n) = \sum_{i=1} |
-- | body row 4 | | \] |
-- +------------------------+------------+---------------------+
.. _anchors:
Anchors
~~~~~~~
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 *anchors* to be included in a documentation comment.
The syntax is ``#label#``, where label is the name of the anchor. An
anchor is invisible in the generated documentation.
To link to an anchor from elsewhere, use the syntax ``"module#label"``
where module is the module name containing the anchor, and label 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 ``"module\#label"``. It is considered deprecated
and will be removed in the future.
Headings
~~~~~~~~
Headings inside of comment documentation are possible by preceding them
with a number of ``=``\ s. From 1 to 6 are accepted. Extra ``=``\ 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. ::
-- |
-- = Heading level 1 with some /emphasis/
-- Something underneath the heading.
--
-- == /Subheading/
-- More content.
--
-- === Subsubheading
-- Even more content.
Note that while headings have to start on a new paragraph, we allow
paragraph-level content to follow these immediately. ::
-- |
-- = Heading level 1 with some __bold__
-- Something underneath the heading.
--
-- == /Subheading/
-- More content.
--
-- === Subsubheading
-- >>> examples are only allowed at the start of paragraphs
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 ``=``\ s. ::
-- |
-- === __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.
Metadata
~~~~~~~~
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.
Since
^^^^^
``@since`` annotation can be used to convey information about when the
function was introduced or when it has changed in a way significant to
the user. ``@since`` 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. ``@since`` 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. ::
-- |
-- Some comment
--
-- @since 1.2.3
Additionally, as of GHC 9.10 ``@since`` in docstrings following export list items: ::
module Mod
( wombat -- ^ @since 2.0
) where ...
This has the function of superceding the ``@since`` annotation given at the
definition site of ``wombat`` and can be used to record changes in the
module exports, particularly when a declaration is re-exported from another
module.
doc/multi-components.rst 0 → 100644
View file @ c9bc29c6
Haddocks of multiple components
===============================
Haddock supports building documentation of multiple components. First, one
needs to build haddocks of all components which can be done with:
.. code-block:: none
cabal haddock --haddock-html \
--haddock-quickjump \
--haddock-option="--use-index=../doc-index.html" \
--haddock-option="--use-contents=../index.html" \
--haddock-option="--base-url=.." \
all
The new ``--base-url`` option will allow to access the static files from the
main directory (in this example its the relative ``./..`` directory). It will
also prevent ``haddock`` from copying its static files to each of the
documentation folders, we're only need a single copy of them where the
``--base-url`` option points to.
The second step requires to copy all the haddocks to a common directory, let's
say ``./docs``, this will depend on your project and it might look like:
.. code-block:: none
cp -r dist-newstyle/build/x86_64-linux/ghc-9.0.1/package-a-0.1.0.0/doc/html/package-a/ docs
cp -r dist-newstyle/build/x86_64-linux/ghc-9.0.1/package-b-0.1.0.0/doc/html/package-b/ docs
Note that you can also include documentation of other packages in this way,
e.g. ``base``, but you need to know where it is hidden on your hard-drive.
To build html and js (``quickjump``) indexes one can now invoke ``haddock`` with:
.. code-block:: none
haddock \
-o docs \
--quickjump --gen-index --gen-contents \
--read-interface=package-a,docs/package-a/package-a.haddock \
--read-interface=package-b,docs/package-b/package-b.haddock
Note: the ``PATH`` in ``--read-interface=PATH,...`` must be a relative url of
a package it points to (relative to the ``docs`` directory).
There's an example project which shows how to do that posted `here
<https://github.com/coot/haddock-example>`_, which haddocks are served on
`github-pages <https://coot.github.io/haddock-example>`_.
driver/Main.hs 0 → 100644
View file @ c9bc29c6
module Main where
import Documentation.Haddock (haddock)
import GHC.ResponseFile (getArgsWithResponseFiles)
main :: IO ()
main = getArgsWithResponseFiles >>= haddock