From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.1.3 (2006-06-01) on yquem.inria.fr X-Spam-Level: X-Spam-Status: No, score=0.2 required=5.0 tests=AWL,MISSING_HEADERS autolearn=disabled version=3.1.3 X-Original-To: caml-list@yquem.inria.fr Delivered-To: caml-list@yquem.inria.fr Received: from mail1-relais-roc.national.inria.fr (mail1-relais-roc.national.inria.fr [192.134.164.82]) by yquem.inria.fr (Postfix) with ESMTP id 00B2CBB84 for ; Mon, 9 Feb 2009 14:59:19 +0100 (CET) X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: Aq4FADfFj0mBrw8EgWdsb2JhbACNDYYQgRwBARYiuhuEGgY X-IronPort-AV: E=Sophos;i="4.37,405,1231110000"; d="scan'208";a="23794198" Received: from ext.lri.fr ([129.175.15.4]) by mail1-smtp-roc.national.inria.fr with ESMTP/TLS/ADH-AES256-SHA; 09 Feb 2009 14:59:19 +0100 Received: from localhost (localhost [127.0.0.1]) by ext.lri.fr (Postfix) with ESMTP id C3994A43AA for ; Mon, 9 Feb 2009 14:59:19 +0100 (CET) X-Virus-Scanned: Debian amavisd-new at lri.fr Received: from ext.lri.fr ([127.0.0.1]) by localhost (ext.lri.fr [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id Fx7jRF05WtFq for ; Mon, 9 Feb 2009 14:59:19 +0100 (CET) Received: from smtp.lri.fr (vhost3-23 [129.175.3.23]) by ext.lri.fr (Postfix) with ESMTP id AC0C5A42EB for ; Mon, 9 Feb 2009 14:59:19 +0100 (CET) Received: from [129.175.4.107] (lri4-107 [129.175.4.107]) by smtp.lri.fr (Postfix) with ESMTP id AA986E056A for ; Mon, 9 Feb 2009 14:59:19 +0100 (CET) Message-ID: <499036C6.5070504@lri.fr> Date: Mon, 09 Feb 2009 14:59:34 +0100 From: Romain Bardou User-Agent: Thunderbird 2.0.0.19 (X11/20090105) MIME-Version: 1.0 Cc: OCaml List Subject: Re: ocamlbuild documentation (was Re: [Caml-list] Re: [ANN] OCaml Batteries Included, alpha 3) References: <1233936696.6216.65.camel@Blefuscu> <200902071458.45000.jon@ffconsultancy.com> <498FF839.6090901@lri.fr> <499018C2.9080007@lri.fr> <499026F9.3030708@lri.fr> <997E6911-3D37-4FAA-A958-757AD21A9F4D@erratique.ch> <49902E11.2010101@lri.fr> <0520EBEC-B30C-4D83-9153-A72BC3C986BF@erratique.ch> In-Reply-To: <0520EBEC-B30C-4D83-9153-A72BC3C986BF@erratique.ch> Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit X-Spam: no; 0.00; lri:01 ocaml:01 wiki:01 coherence:01 coherence:01 solver:01 wiki:01 explicitely:01 faq:01 caml-list:01 api:02 api:02 btw:03 sentence:04 manual:06 >> 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