Ticket #283 (new defect)

Opened 6 months ago

Last modified 3 months ago

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

Reported by: Misha Aizatulin <avatar@hot.ee> Assigned to:
Priority: normal Milestone:
Component: Cabal library Version: HEAD
Severity: normal Keywords:
Cc: Difficulty: very hard (<1 week)
GHC Version: 6.8.2 Platform:

Description

When doing install on cabal itself, only the contents of dist/doc/html are copied to their install location. The users guide doesn't get installed.

Change History

05/26/08 17:57:47 changed by guest

  • cc deleted.
  • reporter changed from guest to Misha Aizatulin <avatar@hot.ee>.

05/27/08 09:45:57 changed by duncan

  • difficulty changed from normal to very hard (<1 week).

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.

(follow-up: ↓ 4 ) 05/28/08 07:30:19 changed by 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.

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?

(in reply to: ↑ 3 ) 06/10/08 14:40:20 changed by duncan

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.

06/10/08 14:41:17 changed by duncan

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.

06/12/08 06:30:34 changed by guest

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.

08/20/08 09:41:10 changed by duncan

See also #330.