On Sun, Aug 26, 2007 at 05:55:46PM +0000, Sylvain Le Gall wrote:
> * every cmi file MUST come with a human readable mli file * there MUST
> be at least one mli file per -dev package
Both agreed.
> * at least one ocamldoc generated HTML file MUST be placed in
> /usr/share/doc/PACKAGE/html/ocamldoc (if upstream generated, using
> another mean, a link must be made between this location and the
> generated path location
I don't know if I like this. It's not really relevant that the API doc
have been generated with ocamldoc, it's relevant that it is available.
(Though of course choosing a consistent mechanism in the implementation
of our tools can give us the benefits I described in a separate post.)
So I would go for something like /usr/share/doc/PACKAGE/api/, even
dropping the html/ part of the dir name. But I'm not really sure about
that ... comments?
> * a set of manpage MUST be generated out of the same source of ocamldoc
> HTML file
That's interesting, are you thinking at something like the "3pm" manual
section for Perl modules? Do we have example in our packages of a "3o"
manpage or something (I remember something like that, but I can't find
examples right now)? Are we free to create new manual sections without
trying to reach agreement on the section naming somewhere?
> Today, this are only SHOULD clause in our policy. I think the first 3
> items are quite common and should cause no problem for most of ocaml
> packages. The manpage stuff is more problematic, but should be a good
> step (if possible).
General comment, what's the (Debian-)semantics of "MUST"? Do you guys
interpret this meaning that if there is a must a non-wishlist bugreport
can be filed, while if there is a should only a wishlist one can be?
If that is the intended semantics I agree with the MUST, otherwise I'd
stay with the SHOULD. In the former case I think our policy should be
rechecked for consistency ...
> There is a comment about this in our policy, concerning the use of
> "-dump" and "-load" in ocamldoc. We could use this file to only ship
> ocamldoc dump file and register generated documentation
> (HTML/manpage/info) on the host system, depending on user system
> configuration (only HTML or HTML + man...).
Well, right, but before going that path I would like to see performance
figures, I don't really want to add yet another postinst registration
mechanism which takes ages to be completed ... :)
Cheers.
--
Stefano Zacchiroli -*- PhD in Computer Science ............... now what?
zack@{cs.unibo.it,debian.org,bononia.it} -%- http://www.bononia.it/zack/
(15:56:48) Zack: e la demo dema ? /\ All one has to do is hit the
(15:57:15) Bac: no, la demo scema \/ right keys at the right time
Attachment:
signature.asc
Description: Digital signature