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

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

[Gabriel Scherer]

[-- 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 --]

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

[Gabriel Kerneis]

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/ 

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

-- 
Gabriel

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

[Romain Bardou]

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