Opened 7 years ago

Last modified 15 months ago

#1572 new task

Make it easy to find documentation for GHC and installed packages

Reported by: simonpj Owned by:
Priority: lowest Milestone: 7.6.2
Component: Compiler Version: 6.6.1
Keywords: Cc: claus.reinke@…, alpmestan@…
Operating System: Unknown/Multiple Architecture: Unknown/Multiple
Type of failure: None/Unknown Difficulty: Unknown
Test Case: Blocked By:
Blocking: Related Tickets:

Description

ghc-pkg builds a package database that helps GHC find all installed packages. But it'd be a great improment if the same step also helped the user find the Haddock documentation for all installed packages.

Corresponding to GHC's package database would be an HTML page that is a single point of entry for the user to find documentation about installed packages. Preferably together with a consolidated index. (And maybe ghc --help should give the local URL of this documentation root.)

Change History (17)

comment:1 Changed 7 years ago by claus

  • Cc claus.reinke@… added

there are also other tools who'd like easy access to that information, on behalf of the user;-) for instance, one of my haskell mode plugins for vim uses haddock's index to figure out which haskell identifiers have documentation, and where to find it:

haskell_doc.vim

one would like at least a central html table of contents plus a central index for the user, plus a more accessible format of the index for ide-like tools. currently, the toc and index contain all packages built together with ghc, but the information in the index isn't easily accessible for tools. preferably, added packages should integrate their toc and index with the central ones (or include the central ones into their own central toc and index, if they are a user-build).

also, i have found that ghc-pkg reports where the docs *might* be, even if they aren't installed! perhaps there should be a separate documentation package associated with each binary package?

this is also related to #1226 (finding ghc user_guide installed location).

comment:2 Changed 6 years ago by igloo

  • Milestone set to 6.10 branch

comment:3 Changed 6 years ago by igloo

  • Summary changed from Make it easy to find documentation for installed packages to Make it easy to find documentation for GHC and installed packages

We should also try to integrate this with the system-specific central documentation system, when such a thing exists.

comment:4 Changed 6 years ago by simonmar

  • Architecture changed from Unknown to Unknown/Multiple

comment:5 Changed 6 years ago by simonmar

  • Operating System changed from Unknown to Unknown/Multiple

comment:6 Changed 5 years ago by igloo

  • Milestone changed from 6.10 branch to 6.12 branch

comment:7 Changed 4 years ago by igloo

  • Milestone changed from 6.12 branch to 6.12.3

comment:8 Changed 4 years ago by igloo

  • Milestone changed from 6.12.3 to 6.14.1
  • Priority changed from normal to low

comment:9 Changed 3 years ago by igloo

  • Milestone changed from 7.0.1 to 7.0.2

comment:10 Changed 3 years ago by igloo

  • Milestone changed from 7.0.2 to 7.2.1

comment:11 Changed 3 years ago by alpmestan

  • Cc alpmestan@… added
  • Type of failure set to None/Unknown

This is partly handled by cabal (when the appropriate option is enabled, either in the config file or using command line arguments). For instance, my ~/.cabal/share/doc/index.html file does the job, for the user at least, even if it's modules-centered, not package-centered.

Are you people still interested in what Simon suggested ? Would that mean moving some stuffs from cabal to GHC, and extending them for what Claus described ?

comment:12 Changed 3 years ago by simonmar

It's basically hooking up our documentation to whatever the system's convention for documentation is. e.g. on Windows we already have a start menu entry for GHC's documentation, but we should also have one for Cabal-generated documentation. On Linux I'm not sure - GHC's documentation often comes in a separate package and just gets dumped somewhere like /usr/share/doc/ghc, there doesn't seem to be a central place to get at application documentation, at least on Ubuntu.

comment:13 Changed 3 years ago by igloo

For Debian, and presumably ubuntu, there's the doc-base package. But GHC shouldn't worry about that: the packagers will.

comment:14 Changed 3 years ago by igloo

  • Milestone changed from 7.2.1 to 7.4.1

comment:15 Changed 2 years ago by igloo

  • Milestone changed from 7.4.1 to 7.6.1
  • Priority changed from low to lowest

comment:16 Changed 20 months ago by igloo

  • Milestone changed from 7.6.1 to 7.6.2

comment:17 Changed 15 months ago by morabbin

Bump. I agree with Ian re packages doco, but where are we with GHC docs?

Note: See TracTickets for help on using tickets.