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=2.7 required=5.0 tests=AWL,DNS_FROM_RFC_POST, SPF_NEUTRAL autolearn=disabled version=3.1.3 X-Original-To: caml-list@yquem.inria.fr Delivered-To: caml-list@yquem.inria.fr Received: from mail2-relais-roc.national.inria.fr (mail2-relais-roc.national.inria.fr [192.134.164.83]) by yquem.inria.fr (Postfix) with ESMTP id 0B6ABBB84 for ; Mon, 9 Feb 2009 13:31:36 +0100 (CET) X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: Ao4CAEyxj0lIDtybkGdsb2JhbACTej8BAQEBCQkMBxEDrHGMcgEDAQOEFwaCMYFt X-IronPort-AV: E=Sophos;i="4.37,405,1231110000"; d="scan'208";a="20837359" Received: from fg-out-1718.google.com ([72.14.220.155]) by mail2-smtp-roc.national.inria.fr with ESMTP; 09 Feb 2009 13:31:35 +0100 Received: by fg-out-1718.google.com with SMTP id e21so1011824fga.43 for ; Mon, 09 Feb 2009 04:31:35 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=domainkey-signature:received:received:sender:message-id:from:to :in-reply-to:content-type:content-transfer-encoding:mime-version :subject:date:references:x-mailer; bh=b4FYgzP4DKU8oegZmrJtpwizKkf4jtznRoLrV4mpMgE=; b=dnCOQUCxr6ilbXfABRYcWDZbgTmUAyQY+JEKKlnnX2L1o0UkNArROOKjEGp2qTxxZQ LT3YSCtm+KMxqosY3+l7ly8rSJYA0xGqAYaVCyXaQXRwoSDJaaxhZAN29QJ/DDrH9AHG gVnkiQrPYhCdeBOhGZfXh/o5XA+pgxtgARKWo= DomainKey-Signature: a=rsa-sha1; c=nofws; d=gmail.com; s=gamma; h=sender:message-id:from:to:in-reply-to:content-type :content-transfer-encoding:mime-version:subject:date:references :x-mailer; b=MEqM6DgeprCDcUqKSjf9UDPJA8EtJ3fNCG1CTSH0a+FOPJcagjW3k5vfCQdq+THBTd fXBFEwTvd0Ub+QMZkBmB37GbM+L+EdSJ1b/TTualrNEB84bQs4eCJGcJ128jodGywz6k GL/awApi8ui8qEJ+fnJn3NGyLDQKHnsNp+pj4= Received: by 10.86.61.13 with SMTP id j13mr2674559fga.6.1234182695358; Mon, 09 Feb 2009 04:31:35 -0800 (PST) Received: from ?192.168.1.34? (163-119.77-83.cust.bluewin.ch [83.77.119.163]) by mx.google.com with ESMTPS id l19sm889426fgb.47.2009.02.09.04.31.34 (version=TLSv1/SSLv3 cipher=RC4-MD5); Mon, 09 Feb 2009 04:31:34 -0800 (PST) Sender: =?UTF-8?Q?Daniel_B=C3=BCnzli?= Message-Id: From: =?ISO-8859-1?Q?Daniel_B=FCnzli?= To: OCaml List In-Reply-To: <499018C2.9080007@lri.fr> Content-Type: text/plain; charset=ISO-8859-1; format=flowed; delsp=yes Content-Transfer-Encoding: quoted-printable Mime-Version: 1.0 (Apple Message framework v930.3) Subject: Re: ocamlbuild documentation (was Re: [Caml-list] Re: [ANN] OCaml Batteries Included, alpha 3) Date: Mon, 9 Feb 2009 13:30:54 +0100 References: <1233936696.6216.65.camel@Blefuscu> <200902071458.45000.jon@ffconsultancy.com> <498FF839.6090901@lri.fr> <499018C2.9080007@lri.fr> X-Mailer: Apple Mail (2.930.3) X-Spam: no; 0.00; bunzli:01 buenzli:01 ocaml:01 wiki:01 ocaml:01 wiki:01 lacks:01 mailling:98 highlighted:98 caml-list:01 argument:02 simplest:02 api:02 authors:03 well-written:03 Le 9 f=E9vr. 09 =E0 12:51, Romain Bardou a =E9crit : > Is it just a matter of copy/pasting the contents of the wiki into =20 > the OCaml manual? Are you serious ? > Or does the wiki really lacks important information? Yes, the way the plugin api works is still lagely undocumented (a =20 random example is it possible to use Plugin.flag inside a rule and =20 what would the effects be ? another is why is the tags argument of =20 Plugin.rule deprectated and thus how can I make a rule apply only if a =20= file has a given tag or maybe I shouldn't do that, etc.). There are a lot of things the authors of ocambuild know that are not =20 in the wiki and that I don't want to discover by trial/error/=20 understand the ocamlbuild source/consult mailling list/try to look at =20= the wiki and I'd be very grateful to them if they'd share this =20 knowledge in a well-written manual. > As far as I can tell it does answer a lot of the questions you =20 > highlighted. Many people don't understand that very often the barrier to adoption =20 is just a single, extensive source of documentation called a manual. =20 Let me repeat that again, a wiki (or its content) is not a substitute =20= for a manual. The whole carefully edited "big picture" documentation =20 is missing and you won't get that by copy and pasting random samples =20 from the wiki. We need this well-written thing called a manual that =20 any respectful tool should provide, they had a good start here [1] but =20= it is not sufficient as it covers only the simplest cases. Daniel [1] http://nicolaspouillard.fr/ocamlbuild/ocamlbuild-user-guide.html=