From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Original-To: caml-list@sympa.inria.fr Delivered-To: caml-list@sympa.inria.fr Received: from mail2-relais-roc.national.inria.fr (mail2-relais-roc.national.inria.fr [192.134.164.83]) by sympa.inria.fr (Postfix) with ESMTPS id 579367EE49 for ; Thu, 12 Sep 2013 19:14:51 +0200 (CEST) X-IronPort-AV: E=Sophos;i="4.90,891,1371074400"; d="scan'208";a="32641882" Received: from unknown (HELO [10.1.202.3]) ([194.254.61.161]) by mail2-relais-roc.national.inria.fr with ESMTP/TLS/DHE-RSA-CAMELLIA256-SHA; 12 Sep 2013 19:14:50 +0200 Message-ID: <5231F68A.2000707@inria.fr> Date: Thu, 12 Sep 2013 19:14:50 +0200 From: Romain Bardou User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:10.0.12) Gecko/20130116 Icedove/10.0.12 MIME-Version: 1.0 To: Gabriel Kerneis CC: Gabriel Scherer , caml users References: <20130912154112.GA28924@kerneis.info> In-Reply-To: <20130912154112.GA28924@kerneis.info> X-Enigmail-Version: 1.4.1 Content-Type: text/plain; charset=windows-1252 Content-Transfer-Encoding: 8bit X-Validation-by: romain.bardou@inria.fr Subject: Re: [Caml-list] ocamlbuild documentation (was: OCaml release 4.01.0) Le 12/09/2013 17:41, Gabriel Kerneis a écrit : > Hi Gabriel, > > On Thu, Sep 12, 2013 at 05:25:30PM +0200, Gabriel Scherer wrote: >> Note that the "ocamlbuild API" is mostly meant for rather advanced users >> (which should be comfortable reading a .mli file in their favorite text >> editor). > > I disagree with that. I enjoy much more browsing ocamldoc's output than an mli > file, mostly because of hyperlinks, and I'm not always developping on computers > where I can, or wish to, rebuild it. > > Moreover, if ocamlbuild is part of the standard ocaml distribution, I don't > understand why its API is not hosted on http://caml.inria.fr/. What would it > take it to dump to http://caml.inria.fr/pub/docs/manual-ocamlbuild/libref/ [*] > just like http://caml.inria.fr/pub/docs/manual-ocaml/libref/ contains stdlib's > API? > > [*] or maybe http://caml.inria.fr/pub/docs/manual-ocaml/ocamlbuildref/ I agree, this is why I asked :) >> https://github.com/gasche/manual-ocamlbuild >> >> (I had planned to give myself more time to improve this documentation >> draft, before making a call to contributions on the list, but your message >> prompted an earlier response. Thanks for your interest.) > > Thank you some much for your effort. I think it deserves its own email on this > list (maybe in a few weeks) to gather more attention and feedback. Indeed, this is a lot of effort and I hope you go to the end of the project. It would be good to really understand what is wrong with the current documentation before starting a new one, though. One thing I can comment on is the "tags" section. Consider the same phrasing for tag descriptions as the Wiki ("This produced file…", "This source file…", see the List of tags section in the Tags page of the Wiki). It took me some time to come up with this when I wrote the documentation and I think it turned out rather well, but still, it could be more precise. Well, the phrasing is not actually important but the difficulty is that tags can basically mean anything and be taken from anywhere. It makes it very hard to understand how they work. In order to be certain of their effect you not only need to know what they trigger (such as a flag), but also from which files they are taken (target of the rule? dependency of the rule?) and where in the command their corresponding "hole" is inserted. Using -documentation could be interesting but it is still insufficient as it does not show some crucial details, such as where flags are added (at the beginning? at the end? some other complex rule?). Well that's just food for thoughts. -- Romain Bardou