install command doesn't install dist/doc/users-guide/

This is part of the wider issue that Cabal does not handle general docs, just haddock docs. This is mostly because documentation is almost completely non-standardised. We know what to do with haddock. For other kinds of documentation it always seems to need custom scripts.

The Cabal manual is a case in point, it needs docbook. How do we identify that doc/Cabal.xml is a docbook file? Perhaps we should rename it to doc/Cabal.docbook. If we can identify that it is docbook how do we process it portably? Are there any standard processing tools? Currently we have to use a raw XSLT processor and guess the location of the xslt stylesheet.

Similar issues come up for latex, man pages, raw html, plain text files etc. We need to be able to identify them and apply standard build rules. This all works nicely for source files because we use standard conventions. We'll have to do something similar with documentation.

There are two tasks: building the documentation and installing it. As for building, it is surely good to support widely known formats, but I think the developer should always have the option to do something else (say via a hook). It is not possible to anticipate all the possible types of documentation that the developers are going to come up with. Suppose for instance if someone writes an alternative to haddock and uses it to process its own documentation.

As to installing the documentation, it seems to be rather easy: just copy the contents of /dist/doc to $docdir. This can be done independently of how the documentation was built. Or am I missing something?

Replying to guest:

There are two tasks: building the documentation and installing it. As for building, it is surely good to support widely known formats, but I think the developer should always have the option to do something else (say via a hook). It is not possible to anticipate all the possible types of documentation that the developers are going to come up with. Suppose for instance if someone writes an alternative to haddock and uses it to process its own documentation.

True. That is possible at the moment. One would have to override the haddock and install hooks.

As to installing the documentation, it seems to be rather easy: just copy the contents of /dist/doc to $docdir. This can be done independently of how the documentation was built. Or am I missing something?

I'm a bit nervous of just installing all the files that happen to be under that directory. I much prefer solutions where we know exactly which files we should be installing. What happens when you get stale files in there due to renaming etc? We end up installing said stale files.

In a decent build system I think we should know how to build and re-build every file. In that case we always know what files to install and how to make sure they're up-to-date.

The implication of course is that we should use Cabal's Setup.hs script to build and install the user guide. Though we still have the problem of portably discovering the xslt stylesheet to use.

I'd suggest adding package properties like extra-doc-files and extra-doc-dirs and treating them similar to data-files. This way I'd be able to say that the README file along with a compilable Example.hs as well as the users-guide directory belong to the documentation.

See also #330.