aboutsummaryrefslogtreecommitdiff
path: root/doc/invoking.rst
diff options
context:
space:
mode:
Diffstat (limited to 'doc/invoking.rst')
-rw-r--r--doc/invoking.rst458
1 files changed, 458 insertions, 0 deletions
diff --git a/doc/invoking.rst b/doc/invoking.rst
new file mode 100644
index 00000000..c69c9031
--- /dev/null
+++ b/doc/invoking.rst
@@ -0,0 +1,458 @@
+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:`-h` option for HTML and the :option:`--hoogle` option for outputting
+Hoogle data 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:
+
+.. program:: haddock
+
+.. option:: -B <dir>
+
+ Tell GHC that 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>
+
+ 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.
+
+ 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.
+
+.. [1]
+ Haddock interface files are not the same as Haskell interface files,
+ I just couldn't think of a better name.
+
+.. option:: -h
+ --html
+
+ 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 in frames.
+
+ ``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.
+
+ ``frames.html``
+ The top level document when viewing in frames.
+
+ ``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, and switching to frames
+ view.
+
+.. 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:: --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:: --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 ``%F`` or ``%{FILE}`` is replaced by the original
+ source file name. Note that for the per-entity URLs this is the
+ name of the *defining* 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 ``%``.
+
+ For example, if your sources are online under some directory, you
+ would say ``haddock --source-base=url/ --source-module=url/%F``
+
+ 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}``.
+
+ Similarly, for the ``%{FILE}`` substitution you may want to replace
+ the ``/`` character in the file names with some other character
+ (especially for links to colourised entity source code with a shared
+ css file). To replace it with a character c use ``%{FILE///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 ("Ocean") 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 ("Ocean" or "Classic").
+
+.. option:: --built-in-themes
+
+ Includes the built-in themes ("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:: -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:: -?
+ --help
+
+ Display help and exit.
+
+.. option:: -V
+ --version
+
+ Output version information 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:: --ignore-all-exports
+
+ Causes Haddock to behave as if every module has the
+ ``ignore-exports`` attribute (:ref:`module-attrs`). This might be useful for
+ generating implementation documentation rather than interface
+ documentation, for example.
+
+.. option:: --hide <module>
+
+ Causes Haddock to behave as if module module has 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:: --compatible-interface-versions
+
+ Prints out space-separated versions of binary Haddock interface
+ files that this version is compatible with.
+
+.. 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.
+
+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 the :option:`-cpp`
+option to GHC using :option:`--optghc`.
+