Maintain central haddock module index.

[duncan]

The ghc api documentation includes a central index of  all the modules in the core libraries. Some people would like the same for all the modules provided by all the packages they have installed.

See #206 for some of the previous discussion on this topic.

The questions to resolve are where the index should be kept by default and how it should be configured (eg switched off).

For example for a per-user install an index could live in $HOME/.cabal/share/doc/index.html but the equivalent is not appropriate for other prefixes like /usr/local.

For global packages shipped by a distro the problem is much worse. We do not really want to have to have distro packages re-generating an html index every time they add and remove a package. Perhaps we should be looking at alternative solutions like using  devhelp which can give easy access to installed documentation without maintaining a central index/catalog.

Similar issues apply to a hoogle index.

[Saizan]

patch for Cabal

[Saizan]

patch for cabal-install

[duncan]

Applied (finally).

There is one new config file setting / command line flag:

doc-index-file: $datadir/doc/index.html

This is also the default value if none is specified. We should check this is ok on Windows.

However it is not just this setting that determines if the index is updated. The index is updated when:

• --enable-documentation flag given (or equiv config file setting)
• --doc-index-file=... flag given (or equiv config file setting)
• doing a per-user install (but not into a specific local package db)
• some packages with docs were installed

We currently do not know about whether exes actually get docs or not. The install plan records DocsOk? if we tried and it did not fail. We always try irrespective of whether it's just an exe and the --executables flag is not given (not that it can be yet).

Another issue is that we dump rather a few files into the target directory. We dump these files into ~/.cabal/share/doc/:

index.html
doc-index.html

frames.html
index-frames.html

haddock.css
haddock-util.js

haskell_icon.gif
minus.gif
plus.gif

This is not just the index file.

In fact we completely ignore the file name given and only use the directory part. It's quite misleading to say:

doc-index-file: $datadir/doc/index.html

when we only use the dir part. Do we need all the files? The frames is absolutely useless imho (why does haddock always generate it, can't we make it a --html-frames option that's not on by default?). Also the index of names is almost useless and the javascript search on that page is completely useless because it's so slow.

So I think we need to fix this, we might need to specify a 'doc-index-dir' and/or not copy over all the usless files. Perhaps we can ask that haddock be enhanced so that the support files can go in a subdir so we do not pollute the top level doc dir.

[duncan]

Oops, was wrong about it ignoring the filename, it renames to the target name before copying all the files haddock generated into the target directory, but the point about getting all the other files still stands.

See also these haddock tickets:

•  http://trac.haskell.org/haddock/ticket/114 (frames)
•  http://trac.haskell.org/haddock/ticket/115 (support files)

[duncan]

Sun Jun  7 18:05:12 BST 2009  Andrea Vezzosi <sanzhiyan@gmail.com>
  * #516, maintains a per-user index of haddock docs
  Ignore-this: 1114f6b944043781c4bf99620573b1cc
  If the haddock-index flag is set it keeps an index 
  of the haddock documentation of the packages in 
  the global and user databases

Included in cabal-install 0.8