Re: [Caml-list] man, doc, … and opam

["Daniel Bünzli" <daniel.buenzli@erratique.ch>]

Hello,

Incidentally I learned more about all this today.

> After reading the opam documentation, I'm not sure anything specific has been done about the extra resources of packages (man and doc files for example).
Some things have been done, read section 1.2.5 of the developer manual. An install file allow you to specify exactly what to install and where in `bin`, `doc` and `lib`.  

In fact this it can completely replace an `ocamlfind install` or `ocaml setup.ml -install`. Just make sure you add the `META` in `lib`, and `ocamlfind` will find your package.

I also discovered that the `remove:` section with the usual `ocamlfind remove PKG` is not needed. This is all due to the fact the IIUC  `ocamlfind` uses the file system as the database so there's no worry to bypass it in these circumstances, opam will just remove the lib/PKG directory et voilà.
  
> The only things, I found in the documentation is build-doc switch to indicate how to build the doc. For example, utop.1.5.opam contains
> build-doc: [ "ocaml" "setup.ml" "-doc" ]
>  
> I was expecting to find the doc of utop but on my .opam repository, the doc directory of utop is empty. Furthermore, in the utop.install file there is no doc command.
The problem is that apparently the utop package has a static .install file in the package description and that this file doesn't list the things generated by build-doc in the `doc:` section. As written in the manual section mentioned above it's much better if the .install file is actually generated by the underlying build system according to the artefacts it has built. But to the best of my knowledge none of the current build systems in use support the generation of such a file (you can easily do it yourself though).

So the idea is that the `build:` section has commands that eventually generate a file PKG.install in the root directory of your distribution and opam then uses that file to install the files associated to the package. (Unfortunately the example of the online documentation uses an static .install file added to the package description *itself* which makes it believe that this was the only way to use them).

> More generally, my question also apply to man pages not found anywhere in the opam documentation.
I have created an issue about this a few hours ago: https://github.com/OCamlPro/opam/issues/673

I think the support is mostly right, the only thing that is missing is install in man folders and a way to easily get to the doc directory of a particular package, instead of having to hunt in the .opam directory. This means that we can put the README and CHANGES in there aswell for people to read.

The conclusion of this is that the problem seems more to be that the install file of most packages is crap rather than a lack of support from opam itself. Though the documentation about all this could be improved on the opam side aswell.

Best,

Daniel