On 27-08-2007, Stefano Zacchiroli <[EMAIL PROTECTED]> 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 -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
