Re: ocamlbuild documentation (was Re: [Caml-list] Re: [ANN] OCaml Batteries Included, alpha 3)

[David Teller <David.Teller@univ-orleans.fr>]

(Here's hoping that this thread doesn't degenerate into a slugfest)

I have used OCamlBuild a lot. I can confirm that this is great software.
Unfortunately, I can also confirm that, to do anything besides compiling
trivial projects, the Wiki proved extremely elusive at best. My best
source of information (besides bugging ertai on IRC :)) was to dig in
the mostly uncommented source code of OCamlBuild, without being certain
of what was supposed to be public, what was supposed to be known by
users, etc.

Now, what needs to be written? That's hard to summarize in one sentence,
and that's probably why people tend not to contribute to the Wiki once
they have found what they need. My personal take would be the following:

* take the current official OCamlBuild manual and turn it into chapter 1
of "the OCamlBuild handbook"

* write a complete and detailed step-by-step tutorial on writing a _tags
file for a simple project, with an appendix detailing all the existing
available tags (including the commonly used tags which I believe are
automatically generated, such as [pack(...)] ) -- and please write that
tutorial for a newbie, not for me

* progressively complete that tutorial to add all sorts of
not-that-trivial cases such as using OCamlFind, then  building a library
which is going to be used by the rest of the build process, then
building a syntax extension which is going to be used by the rest of the
build process, ... (all sorts of things which are already on the Wiki,
just with more structure and more details)

* progressively complete further that tutorial to add quite complex
cases such as integrating things which are not OCaml at all, including C
code, LaTeX documentation compiled to both pdf and html, generation
of .ml/.mli files during compilation (we have an example of this kind of
thing in  Batteries, where we have to generate .mli from .mlpack to
allow ocamldoc to work on .mlpack files), etc. (some of this is on the
Wiki already, but needs more structure and more details)

* write a complete and detailed step-by-step tutorial on converting an
existing project based on a relatively complex Makefile to _tags and
myocamlbuild.ml

* add at least the first chapter (preferably everything) to the OCaml
manual

* ask a user who has used OCamlBuild for trivial projects (preferably
one who sits in an office close to that of either Romain Bardou or
Nicolas Pouillard) to comment the source code (first the .mli and
the .ml)

* be available to answer the questions of that user  :)

Just my two cents.

Cheers,
 David

P.S.: And if there's no room for this kind of tutorial in the OCaml
documentation, we'll be glad to have it into OCaml Batteries Included :)

On Mon, 2009-02-09 at 14:22 +0100, Romain Bardou wrote:
> Well I would disagree and say that the bare minimum is here. This is why 
> I stopped contributing to the wiki: I had nothing else interesting to 
> add. So now I ask: what exactly is missing from this bare minimum? In my 
> opinion, questions such as "can I use the flag function inside the rule 
> function" are definitely not part of the bare minimum.
> 
> (btw, the answer is: the use of the flag function inside the rule 
> function is not specified, thus not documented)
> 
-- 
David Teller-Rajchenbach
 Security of Distributed Systems
  http://www.univ-orleans.fr/lifo/Members/David.Teller
   « Ce matin Un crétin A tué un chercheur. » (air connu)
   Latest News of French Research: System being liquidated. Researchers angry.