[Hackage] #517: make cabal install command support haddock options
#517: make cabal install command support haddock options ---------------------------------+------------------------------------------ Reporter: duncan | Owner: Type: enhancement | Status: new Priority: normal | Milestone: Component: cabal-install tool | Version: Severity: normal | Keywords: Difficulty: normal | Ghcversion: Platform: | ---------------------------------+------------------------------------------ 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) }}} -- Ticket URL: http://hackage.haskell.org/trac/hackage/ticket/517 Hackage http://haskell.org/cabal/ Hackage: Cabal and related projects
#517: make cabal install command support haddock options ---------------------------------+------------------------------------------ Reporter: duncan | Owner: Type: enhancement | Status: new Priority: normal | Milestone: Component: cabal-install tool | Version: Severity: normal | Resolution: Keywords: | Difficulty: normal Ghcversion: | Platform: ---------------------------------+------------------------------------------ Changes (by guest): * cc: reiner.pope@gmail.com (added) Comment: 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 -- Ticket URL: http://hackage.haskell.org/trac/hackage/ticket/517#comment:1 Hackage http://haskell.org/cabal/ Hackage: Cabal and related projects
#517: make cabal install command support haddock options ---------------------------------+------------------------------------------ Reporter: duncan | Owner: Type: enhancement | Status: new Priority: normal | Milestone: Component: cabal-install tool | Version: Severity: normal | Resolution: Keywords: | Difficulty: normal Ghcversion: | Platform: ---------------------------------+------------------------------------------ Comment (by 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. -- Ticket URL: http://hackage.haskell.org/trac/hackage/ticket/517#comment:2 Hackage http://haskell.org/cabal/ Hackage: Cabal and related projects
#517: make cabal install command support haddock options ---------------------------------+------------------------------------------ Reporter: duncan | Owner: Type: enhancement | Status: new Priority: normal | Milestone: Component: cabal-install tool | Version: Severity: normal | Resolution: Keywords: | Difficulty: normal Ghcversion: | Platform: ---------------------------------+------------------------------------------ Comment (by 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. -- Ticket URL: http://hackage.haskell.org/trac/hackage/ticket/517#comment:3 Hackage http://haskell.org/cabal/ Hackage: Cabal and related projects
#517: make cabal install command support haddock options ---------------------------------+------------------------------------------ Reporter: duncan | Owner: Type: enhancement | Status: new Priority: normal | Milestone: Component: cabal-install tool | Version: Severity: normal | Keywords: Difficulty: normal | Ghcversion: Platform: | ---------------------------------+------------------------------------------ Comment(by 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. -- Ticket URL: http://hackage.haskell.org/trac/hackage/ticket/517#comment:4 Hackage http://haskell.org/cabal/ Hackage: Cabal and related projects
#517: make cabal install command support haddock options ---------------------------------+------------------------------------------ Reporter: duncan | Owner: Type: enhancement | Status: new Priority: normal | Milestone: Component: cabal-install tool | Version: Severity: normal | Keywords: Difficulty: normal | Ghcversion: Platform: | ---------------------------------+------------------------------------------ Changes (by danfish): * cc: daniel.is.fischer@… (added) Comment:
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.
At least, for now, make it settable in the config file. It's not so pressing for me anymore since I had the idea to change defaultHaddockFlags in Distribution.Simple.Setup, but I don't want that kind of drastic measure to become an eternal workaround. -- Ticket URL: http://hackage.haskell.org/trac/hackage/ticket/517#comment:5 Hackage http://haskell.org/cabal/ Hackage: Cabal and related projects
At least, for now, make it settable in the config file. It's not so
#517: make cabal install command support haddock options ---------------------------------+------------------------------------------ Reporter: duncan | Owner: Type: enhancement | Status: new Priority: normal | Milestone: Component: cabal-install tool | Version: Severity: normal | Keywords: Difficulty: normal | Ghcversion: Platform: | ---------------------------------+------------------------------------------ Comment(by David): Replying to [comment:5 danfish]: pressing for me anymore since I had the idea to change defaultHaddockFlags in Distribution.Simple.Setup, but I don't want that kind of drastic measure to become an eternal workaround. Can you post more detail on your workaround? Thanks. -- Ticket URL: http://hackage.haskell.org/trac/hackage/ticket/517#comment:6 Hackage http://haskell.org/cabal/ Hackage: Cabal and related projects
#517: make cabal install command support haddock options ---------------------------------+------------------------------------------ Reporter: duncan | Owner: Type: enhancement | Status: new Priority: normal | Milestone: Component: cabal-install tool | Version: Severity: normal | Keywords: Difficulty: normal | Ghcversion: Platform: | ---------------------------------+------------------------------------------ Comment(by danfish): Replying to [comment:6 David]:
Can you post more detail on your workaround?
Before building Cabal (or GHC), just open Distribution.Simple.Setup.hs in a text editor, go down to defaultHscolourFlags, change hscolourCSS from !NoFlag to Flag "~/.cabal/hscolour.css". Go down a little further, in defaultHaddockFlags, change haddockHscolour to Flag True, haddockHscolourCss to Flag "~/.cabal...", haddockInternal/Executables to Flag True if you want that. If you do it when you build GHC, that's all, build and don't worry again (until you get some package on which hscolour chokes). If your GHC is already built, bump the version number in Cabal.cabal, run cabal install in that directory and then cabal install --reinstall cabal-install to get your changes into cabal. It's evil, but I wanted source-links bad enough to not care :) -- Ticket URL: http://hackage.haskell.org/trac/hackage/ticket/517#comment:7 Hackage http://haskell.org/cabal/ Hackage: Cabal and related projects
#517: make cabal install command support haddock options ---------------------------------+------------------------------------------ Reporter: duncan | Owner: Type: enhancement | Status: new Priority: normal | Milestone: Component: cabal-install tool | Version: Severity: normal | Keywords: Difficulty: normal | Ghcversion: Platform: | ---------------------------------+------------------------------------------ Comment(by David): Replying to [comment:7 danfish]:
Before building Cabal (or GHC), just open Distribution.Simple.Setup.hs in a text editor...
Can you upload this to hackage? I'm sure if we had a Cabal-src package that people could enable with ghc- pkg instead of the default Cabal, many people would want to install it. Lots of packages have inadequate or occasionally ambiguous documentation, so I think the lack of easily browsable source code is a real impediment to adoption of Haskell compared to interpreted languages. -- Ticket URL: http://hackage.haskell.org/trac/hackage/ticket/517#comment:8 Hackage http://haskell.org/cabal/ Hackage: Cabal and related projects
#517: make cabal install command support haddock options ---------------------------------+------------------------------------------ Reporter: duncan | Owner: Type: enhancement | Status: new Priority: normal | Milestone: Component: cabal-install tool | Version: Severity: normal | Keywords: Difficulty: normal | Ghcversion: Platform: | ---------------------------------+------------------------------------------ Changes (by danfish): * cc: daniel.is.fischer@… (removed) Comment: Replying to [comment:8 David]:
Can you upload this to hackage?
I'm sure if we had a Cabal-src package that people could enable with ghc-pkg instead of the default Cabal, many people would want to install it.
I don't think that's a particularly good idea. Using the Cabal library is rather baked-in for at least GHC, and AFAIK, it doesn't like the version it came with to be hidden, let alone uninstalled. Having a package which would basically be a copy of Cabal, but with a different name, would create namespace-pollution by having the same module names and likely confuse GHC as to which package to pick them from. Using different module names, how would one convince the tools to use that library? I think we should try to make these options settable in the config file. That would require understanding how cabal-install works, when and how it invokes 'cabal haddock' etc. I've taken a few short looks at the source before, but so far, I haven't been able to unravel it (not that I tried too hard yet), the scarcity of documentation and absence of a source-guide don't help getting into it. -- Ticket URL: http://hackage.haskell.org/trac/hackage/ticket/517#comment:9 Hackage http://haskell.org/cabal/ Hackage: Cabal and related projects
participants (1)
-
Hackage