Re: [was: generation of ocamldoc HTML documentation for libs (via cdbs)] OCaml policy for documentation
On 27-08-2007, Stefano Zacchiroli <zack@debian.org> wrote:
>
> --7AUc2qLy4jB3hD7Z
> Content-Type: text/plain; charset=us-ascii
> Content-Disposition: inline
> Content-Transfer-Encoding: quoted-printable
>
> 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=20
>> /usr/share/doc/PACKAGE/html/ocamldoc (if upstream generated, using
>> another mean, a link must be made between this location and the=20
>> 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?
>
I would keep html part, because it is relevent. Concerning the fact that
it must be ocamldoc generated, i agree that there is no need for such a
restriction. If upstream generate anything using another way, lets go
for it. I think that each -dev package must have
/usr/share/doc/PACKAGE/html/api/ (can be a link).
>> * 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?
>
Yep, something like 3pm (3ml? 3o?) I am not sure if we can freely create
manpages section. If we decide that there is an interest doing this, we
should consider it. But i will only add this to policy when a proof of
concept will have been done (i.e. that we can easily generate manpage
out of current ocamldoc).
>> 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 ...
>
I was thinking of the semantic used in RFC.
http://www.ietf.org/rfc/rfc2119.txt
I.e. this is a policy violation not to have a MUST item (hence people
can fill non-wishlist bug).
>> 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 ... :)
>
Argh... So we need to stop talking about it before doing it ;-) The
ocamldoc generation using -load/-dump is efficient, but can take a long
time. I will try to do some benchmark "when i have time (c)" and give
you some result.
Regards,
Sylvain Le Gall
Reply to: