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

[Romain Bardou <Romain.Bardou@lri.fr>]

>> Is it just a matter of copy/pasting the contents of the wiki into the 
>> OCaml manual?
> 
> Are you serious ?

You don't have to be so mean :(

> Yes, the way the plugin api works is still lagely undocumented (a random 
> example is it possible to use Plugin.flag inside a rule and what would 
> the effects be ? another is why is the tags argument of Plugin.rule 
> deprectated and thus how can I make a rule apply only if a file has a 
> given tag or maybe I shouldn't do that, etc.).

Unfortunately, while authors might be the best persons to answer these 
questions, they are also the ones who do not have any question ;) 
Finding the right questions is not easy and a Wiki is a nice way to find 
out.

> There are a lot of things the authors of ocambuild know that are not in 
> the wiki and that I don't want to discover by trial/error/understand the 
> ocamlbuild source/consult mailling list/try to look at the wiki and I'd 
> be very grateful to them if they'd share this knowledge in a 
> well-written manual.
> 
>> As far as I can tell it does answer a lot of the questions you 
>> highlighted.
> 
> Many people don't understand that very often the barrier to adoption is 
> just a single, extensive source of documentation called a manual. Let me 
> repeat that again, a wiki (or its content) is not a substitute for a 
> manual. The whole carefully edited "big picture" documentation is 
> missing and you won't get that by copy and pasting random samples from 
> the wiki. We need this well-written thing called a manual that any 
> respectful tool should provide, they had a good start here [1] but it is 
> not sufficient as it covers only the simplest cases.

While I agree that the documentation should answer most questions, I 
fail to see how "try to look at the wiki" is different from "try to look 
at the manual". The only problem I have with the wiki is that it is not 
in the same place as the OCaml manual. Do we have to rename "wiki" into 
"manual in which you can write your own notes" ? :)

-- 
Romain Bardou