+ <para>In general, these options act on .tix file after an
+ instrumented binary has generated it, which hpc acting as a
+ conduit between the raw .tix file, and the more detailed reports
+ produced.
+ </para>
+
+ <para>
+ The hpc tool assumes you are in the top-level directory of
+ the location where you built your application, and the .tix
+ file is in the same top-level directory. You can use the
+ flag --srcdir to use hpc for any other directory, and use
+ --srcdir multiple times to analyse programs compiled from
+ difference locations, as is typical for packages.
+ </para>
+
+ <para>
+ We now explain in more details the major modes of hpc.
+ </para>
+
+ <sect3><title>hpc report</title>
+ <para>hpc report gives a textual report of coverage. By default,
+ all modules and packages are considered in generating report,
+ unless include or exclude are used. The report is a summary
+ unless the --per-module flag is used. The --xml-output option
+ allows for tools to use hpc to glean coverage.
+ </para>
+<screen>
+$ hpc help report
+Usage: hpc report [OPTION] .. <TIX_FILE> [<MODULE> [<MODULE> ..]]
+
+Options:
+
+ --per-module show module level detail
+ --decl-list show unused decls
+ --exclude=[PACKAGE:][MODULE] exclude MODULE and/or PACKAGE
+ --include=[PACKAGE:][MODULE] include MODULE and/or PACKAGE
+ --srcdir=DIR path to source directory of .hs files
+ multi-use of srcdir possible
+ --hpcdir=DIR sub-directory that contains .mix files
+ default .hpc [rarely used]
+ --xml-output show output in XML
+</screen>
+ </sect3>
+ <sect3><title>hpc markup</title>
+ <para>hpc markup marks up source files into colored html.
+ </para>
+<screen>
+$ hpc help markup
+Usage: hpc markup [OPTION] .. <TIX_FILE> [<MODULE> [<MODULE> ..]]
+
+Options:
+
+ --exclude=[PACKAGE:][MODULE] exclude MODULE and/or PACKAGE
+ --include=[PACKAGE:][MODULE] include MODULE and/or PACKAGE
+ --srcdir=DIR path to source directory of .hs files
+ multi-use of srcdir possible
+ --hpcdir=DIR sub-directory that contains .mix files
+ default .hpc [rarely used]
+ --fun-entry-count show top-level function entry counts
+ --highlight-covered highlight covered code, rather that code gaps
+ --destdir=DIR path to write output to
+</screen>
+
+ </sect3>
+ <sect3><title>hpc sum</title>
+ <para>hpc sum adds together any number of .tix files into a single
+ .tix file. hpc sum does not change the original .tix file; it generates a new .tix file.
+ </para>
+<screen>
+$ hpc help sum
+Usage: hpc sum [OPTION] .. <TIX_FILE> [<TIX_FILE> [<TIX_FILE> ..]]
+Sum multiple .tix files in a single .tix file
+
+Options:
+
+ --exclude=[PACKAGE:][MODULE] exclude MODULE and/or PACKAGE
+ --include=[PACKAGE:][MODULE] include MODULE and/or PACKAGE
+ --output=FILE output FILE
+ --union use the union of the module namespace (default is intersection)
+</screen>
+ </sect3>
+ <sect3><title>hpc combine</title>
+ <para>hpc combine is the swiss army knife of hpc. It can be
+ used to take the difference between .tix files, to subtract one
+ .tix file from another, or to add two .tix files. hpc combine does not
+ change the original .tix file; it generates a new .tix file.
+ </para>
+<screen>
+$ hpc help combine
+Usage: hpc combine [OPTION] .. <TIX_FILE> <TIX_FILE>
+Combine two .tix files in a single .tix file
+
+Options:
+
+ --exclude=[PACKAGE:][MODULE] exclude MODULE and/or PACKAGE
+ --include=[PACKAGE:][MODULE] include MODULE and/or PACKAGE
+ --output=FILE output FILE
+ --function=FUNCTION combine .tix files with join function, default = ADD
+ FUNCTION = ADD | DIFF | SUB
+ --union use the union of the module namespace (default is intersection)
+</screen>
+ </sect3>
+ <sect3><title>hpc map</title>
+ <para>hpc map inverts or zeros a .tix file. hpc map does not
+ change the original .tix file; it generates a new .tix file.
+ </para>
+<screen>
+$ hpc help map
+Usage: hpc map [OPTION] .. <TIX_FILE>
+Map a function over a single .tix file
+
+Options:
+
+ --exclude=[PACKAGE:][MODULE] exclude MODULE and/or PACKAGE
+ --include=[PACKAGE:][MODULE] include MODULE and/or PACKAGE
+ --output=FILE output FILE
+ --function=FUNCTION apply function to .tix files, default = ID
+ FUNCTION = ID | INV | ZERO
+ --union use the union of the module namespace (default is intersection)
+</screen>
+ </sect3>
+ <sect3><title>hpc overlay and hpc draft</title>
+ <para>
+ Overlays are an experimental feature of HPC, a textual description
+ of coverage. hpc draft is used to generate a draft overlay from a .tix file,
+ and hpc overlay generates a .tix files from an overlay.
+ </para>
+<screen>
+% hpc help overlay
+Usage: hpc overlay [OPTION] .. <OVERLAY_FILE> [<OVERLAY_FILE> [...]]
+
+Options:
+
+ --srcdir=DIR path to source directory of .hs files
+ multi-use of srcdir possible
+ --hpcdir=DIR sub-directory that contains .mix files
+ default .hpc [rarely used]
+ --output=FILE output FILE
+% hpc help draft
+Usage: hpc draft [OPTION] .. <TIX_FILE>
+
+Options:
+
+ --exclude=[PACKAGE:][MODULE] exclude MODULE and/or PACKAGE
+ --include=[PACKAGE:][MODULE] include MODULE and/or PACKAGE
+ --srcdir=DIR path to source directory of .hs files
+ multi-use of srcdir possible
+ --hpcdir=DIR sub-directory that contains .mix files
+ default .hpc [rarely used]
+ --output=FILE output FILE
+</screen>
+ </sect3>
+ </sect2>
+ <sect2><title>Caveats and Shortcomings of Haskell Program Coverage</title>
+ <para>
+ HPC does not attempt to lock the .tix file, so multiple concurrently running
+ binaries in the same directory will exhibit a race condition. There is no way
+ to change the name of the .tix file generated, apart from renaming the binary.
+ HPC does not work with GHCi.
+ </para>
+ </sect2>