On Thu, Sep 12, 2013 at 4:28 PM, Romain Bardou <romain.bardou@inria.fr> wrote:
> - Christophe Troestler significantly improved the ocamlbuild API
>   documentation, found in the "signatures.mli" file exporting
>   user-visible interfaces for the OCamlbuild components accessible
>   from a plugin

Is this available anywhere else than from the source code?
http://brion.inria.fr/gallium/index.php/Ocamlbuild has a link to
http://gallium.inria.fr/~pouillar/ocamlbuild/html/Signatures.PLUGIN.html, should
this be updated? The manual has an Ocamlbuild section, should there be a
link from there to the API?


No, this is currently not available anywhere else. For curious users, the source code can be browsed in various places, such as:
  http://caml.inria.fr/cgi-bin/viewvc.cgi/ocaml/trunk/ocamlbuild/signatures.mli?view=markup
  https://github.com/ocaml/ocaml/blob/trunk/ocamlbuild/signatures.mli

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). Assuming the availability of satisfying documentation (more on that later), the long-term picture is that most users should only use a tiny subset of the API -- currently mostly the `flag` command.

Given that the wiki is not a great success in terms of crowd-writing documentation or visibility, I have decided to start another approach: I started writing a new ocamlbuild manual during August (trying to fix some of the complaints people had on the existing one), and a preview of the result can be seen here:
  https://github.com/gasche/manual-ocamlbuild

I will gladly accept contributions, including porting content present on the Wiki, or just adding content. I am still investigating options to mechanically generate some parts of this documentation from the source code; I think the "reference section" could basically include the output of a beefed up `-documentation` output, but am not sure how to integrate the API signature. The best solution could be to simply run ocamldoc, and then include the .html in the result -- this is how the OCaml manual itself does it, and it seems to work ok.

(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.)