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

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

>> 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?
> 
> A text with paragraph, words and explanations, not scattered phrases and 
> paragraphs without coherence. You know a structured document.

I'm actually very surprised here. If you look at the "Documentation" 
part of the index:

http://brion.inria.fr/gallium/index.php/Ocamlbuild

Except from the lists, which are, well, lists, like in an appendix, all 
pages meet what you ask. To me everything contains structure, paragraph, 
explanations, coherence, and is not scattered. Is, for instance, the 
"Solver mechanism" page really that badly written?

The "FAQ" part is not structured, but you should not need it (for "bare 
minimum" standards) except to find more plugin examples.

>> In my opinion, questions such as "can I use the flag function inside 
>> the rule function" are definitely not part of the bare minimum.
> 
> Not but maybe _when_ I'm supposed to call Plugin.flag is.
> 
>> (btw, the answer is: the use of the flag function inside the rule 
>> function is not specified, thus not documented)
> 
> What do you mean by "not specified", your beautiful "manual" doesn't 
> even tell me where/when I should call Plugin.flag.

Indeed, it is not exactly said and should be added in the API 
documentation, but because the API documentation is not a wiki, I cannot 
do that, and neither can you. However, the "Making plugins" page of the 
wiki does contain this sentence: "This is usually done After_rules." in 
the "Manage tags" part. It is true that it does not mention explicitely 
the "flag" function, but along with the examples it should be clear 
enough. Isn't it?

-- 
Romain Bardou