make cabal install command support haddock options

[duncan]

Currently the cabal install command supports just --enable-documentation which turns on library docs. The cabal haddock option has various other things like enabling docs for executables, specifying css files, linking to source code etc. Some or perhaps all of these would be useful when installing packages.

This is not fundamentally difficult. The task is just to work out which options are useful (or perhaps all) and how to present the user interface (command line options and config file). Bonus points for a UI that is usable and orthogonal.

See #206 for some of the previous discussion on this topic. See also #516 about maintaining a central haddock module index.

For reference the current haddock command options are:

Flags for haddock:
 -h --help                 Show this help text
 -v --verbose[=n]          Control verbosity (n is 0--3, default verbosity
                           level is 1)
    --builddir=DIR         The directory where Cabal puts generated build files
                           (default dist)
    --hoogle               Generate a hoogle database
    --html-location=URL    Location of HTML documentation for pre-requisite
                           packages
    --executables          Run haddock for Executables targets
    --internal             Run haddock for internal modules and include all
                           symbols
    --css=PATH             Use PATH as the haddock stylesheet
    --hyperlink-source     Hyperlink the documentation to the source code
                           (using HsColour)
    --hscolour-css=PATH    Use PATH as the HsColour stylesheet
    --with-haddock=PATH    give the path to haddock
    --haddock-options=OPTS give extra options to haddock
    --haddock-option=OPT   give an extra option to haddock (no need to quote
                           options containing spaces)

[guest]

I've attached a patch which exposes the following options in cabal install:

--enable-documentation-hoogle (corresponds to --hoogle)
--enable-documentation-source-links (corresponds to --hyperlink-source)
--enable-documentation-executables (corresponds to --executables)
--enable-documentation-internal (corresponds to --internal)
--documentation-css=PATH (corresponds to --css=PATH)
--documentation-hscolour-css=PATH (corresponds to --hscolour-css-PATH)

None of the flags have any effect unless --enable-documentation is set. All of the flags can be set in ~/.cabal/config.

Reiner Pope

[guest]

New patch attached. Same options available, but superior treatment of Hoogle. The hoogle command is now

--enable-hoogle

and can be enabled independently of --enable-documentation. If --enable-documentation and --enable-hoogle are both set, haddock is run twice (once for html documentation; once for hoogle database generation). This has to be done because of #560.

[David]

Yes. Please, please, please incorporate this improvement into the distribution. Even if later on after #560 is fixed there's an even better way to do it, for now, some sort of way of installing source code is needed.

Really, the "documentation: True" option in the config file is barely useful without source code, because most packages do not contain sufficient haddock documentation to be useful without occasionally peeking at the source. Yet one of the great things about haskell is that it's very easy to understand other people's source.

So please either apply this patch, or make --hyperlink-source (#534) the default. Please don't wait for the perfect solution to come along before enabling some sort of way of installing source code with cabal install. The functionality is too critical to defer.

[ross]

To use cabal install for building documentation for packages on hackage would require --html-location, --hyperlink-source and --hoogle.

It would also be handy if variable substitution were applied to --haddock-options (etc): since cabal install may build multiple packages, those packages may require varying configure arguments.