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

[Gabriel Scherer <gabriel.scherer@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 2381 bytes --]

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

[-- Attachment #2: Type: text/html, Size: 3465 bytes --]