Re: [Caml-list] ocamlbuild documentation (was: OCaml release 4.01.0)

[Romain Bardou <romain.bardou@inria.fr>]

Le 12/09/2013 17:41, Gabriel Kerneis a écrit :
> Hi Gabriel,
> 
> On Thu, Sep 12, 2013 at 05:25:30PM +0200, Gabriel Scherer wrote:
>> Note that the "ocamlbuild API" is mostly meant for rather advanced users
>> (which should be comfortable reading a .mli file in their favorite text
>> editor).
> 
> I disagree with that. I enjoy much more browsing ocamldoc's output than an mli
> file, mostly because of hyperlinks, and I'm not always developping on computers
> where I can, or wish to, rebuild it.
> 
> Moreover, if ocamlbuild is part of the standard ocaml distribution, I don't
> understand why its API is not hosted on http://caml.inria.fr/. What would it
> take it to dump to http://caml.inria.fr/pub/docs/manual-ocamlbuild/libref/ [*]
> just like http://caml.inria.fr/pub/docs/manual-ocaml/libref/ contains stdlib's
> API?
> 
> [*] or maybe http://caml.inria.fr/pub/docs/manual-ocaml/ocamlbuildref/ 

I agree, this is why I asked :)

>>   https://github.com/gasche/manual-ocamlbuild
>>
>> (I had planned to give myself more time to improve this documentation
>> draft, before making a call to contributions on the list, but your message
>> prompted an earlier response. Thanks for your interest.)
> 
> Thank you some much for your effort. I think it deserves its own email on this
> list (maybe in a few weeks) to gather more attention and feedback.

Indeed, this is a lot of effort and I hope you go to the end of the project.

It would be good to really understand what is wrong with the current
documentation before starting a new one, though.

One thing I can comment on is the "tags" section. Consider the same
phrasing for tag descriptions as the Wiki ("This produced file…", "This
source file…", see the List of tags section in the Tags page of the
Wiki). It took me some time to come up with this when I wrote the
documentation and I think it turned out rather well, but still, it could
be more precise.

Well, the phrasing is not actually important but the difficulty is that
tags can basically mean anything and be taken from anywhere. It makes it
very hard to understand how they work. In order to be certain of their
effect you not only need to know what they trigger (such as a flag), but
also from which files they are taken (target of the rule? dependency of
the rule?) and where in the command their corresponding "hole" is inserted.

Using -documentation could be interesting but it is still insufficient
as it does not show some crucial details, such as where flags are added
(at the beginning? at the end? some other complex rule?).

Well that's just food for thoughts.

-- 
Romain Bardou