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 B96047EE49 for ; Thu, 12 Sep 2013 17:26:11 +0200 (CEST) Received-SPF: None (mail2-smtp-roc.national.inria.fr: no sender authenticity information available from domain of gabriel.scherer@gmail.com) identity=pra; client-ip=209.85.214.42; receiver=mail2-smtp-roc.national.inria.fr; envelope-from="gabriel.scherer@gmail.com"; x-sender="gabriel.scherer@gmail.com"; x-conformance=sidf_compatible Received-SPF: Pass (mail2-smtp-roc.national.inria.fr: domain of gabriel.scherer@gmail.com designates 209.85.214.42 as permitted sender) identity=mailfrom; client-ip=209.85.214.42; receiver=mail2-smtp-roc.national.inria.fr; envelope-from="gabriel.scherer@gmail.com"; x-sender="gabriel.scherer@gmail.com"; x-conformance=sidf_compatible; x-record-type="v=spf1" Received-SPF: None (mail2-smtp-roc.national.inria.fr: no sender authenticity information available from domain of postmaster@mail-bk0-f42.google.com) identity=helo; client-ip=209.85.214.42; receiver=mail2-smtp-roc.national.inria.fr; envelope-from="gabriel.scherer@gmail.com"; x-sender="postmaster@mail-bk0-f42.google.com"; x-conformance=sidf_compatible X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: ApwBAObbMVLRVdYqm2dsb2JhbABBGhaDKVKxbIYviEeBFAgWDgEBAQEBBgsLCRQogiUBAQRBARsdAQMBERBdAREBBQEiExuHVAEDCQYMNJ1fjFGDB4QaChknDWSIWwEFDI9bBIQkA5d5gS+OWxgphEw6 X-IPAS-Result: ApwBAObbMVLRVdYqm2dsb2JhbABBGhaDKVKxbIYviEeBFAgWDgEBAQEBBgsLCRQogiUBAQRBARsdAQMBERBdAREBBQEiExuHVAEDCQYMNJ1fjFGDB4QaChknDWSIWwEFDI9bBIQkA5d5gS+OWxgphEw6 X-IronPort-AV: E=Sophos;i="4.90,891,1371074400"; d="scan'208";a="32628526" Received: from mail-bk0-f42.google.com ([209.85.214.42]) by mail2-smtp-roc.national.inria.fr with ESMTP/TLS/RC4-SHA; 12 Sep 2013 17:26:10 +0200 Received: by mail-bk0-f42.google.com with SMTP id my10so4362550bkb.29 for ; Thu, 12 Sep 2013 08:26:10 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:from:date:message-id:subject:to:cc:content-type; bh=c37ojpliqYR9zm31xECOfz3db5H4l7hi6zjvroRnw4c=; b=rd8DovovVGZRMOTSqBeY3sMsNZlEP6I8Lc2IrWFwS8u4ro07xsxYzf/++Oed0Nip5P Wbd+mYhmYHanUduaCUi4zGBThqtHBl8R78WR8skikMG1HSxLGi8Ga9YYQMVLax1IY/ng uhL7EDKZgywtmeAGRwN+FitZ6PVZij7hokEzy/OMDUpF9Wiw9hCTVzGhNGR2U8HFLeaf MceaUdGTj9Eeq5/Xw5WoC9EhSDNtuVpErf1C+YCvL827O1nQl71IWf+FXIdzQ6mBy3Y7 LRPZ41kUoO9rxtvmwanYTEMv9DyFGCLNQgPFSG+bH77psZ7c3sbS5fGE+t2eIRfO5iXJ Yhfg== X-Received: by 10.204.167.74 with SMTP id p10mr7143241bky.26.1378999570822; Thu, 12 Sep 2013 08:26:10 -0700 (PDT) MIME-Version: 1.0 Received: by 10.204.236.193 with HTTP; Thu, 12 Sep 2013 08:25:30 -0700 (PDT) From: Gabriel Scherer Date: Thu, 12 Sep 2013 17:25:30 +0200 Message-ID: To: Romain Bardou Cc: caml users Content-Type: multipart/alternative; boundary=bcaec52c66ab91320f04e6315b78 Subject: [Caml-list] ocamlbuild documentation (was: OCaml release 4.01.0) --bcaec52c66ab91320f04e6315b78 Content-Type: text/plain; charset=ISO-8859-1 On Thu, Sep 12, 2013 at 4:28 PM, Romain Bardou wrote: > > - Christophe Troestler significantly improved the ocamlbuild API > > documentation, found in the "signatures.mli" file exporting > > user-visible interfaces for the OCamlbuild components accessible > > from a plugin > > Is this available anywhere else than from the source code? > http://brion.inria.fr/gallium/index.php/Ocamlbuild has a link to > http://gallium.inria.fr/~pouillar/ocamlbuild/html/Signatures.PLUGIN.html, > should > this be updated? The manual has an Ocamlbuild section, should there be a > link from there to the API? > No, this is currently not available anywhere else. For curious users, the source code can be browsed in various places, such as: http://caml.inria.fr/cgi-bin/viewvc.cgi/ocaml/trunk/ocamlbuild/signatures.mli?view=markup https://github.com/ocaml/ocaml/blob/trunk/ocamlbuild/signatures.mli 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). Assuming the availability of satisfying documentation (more on that later), the long-term picture is that most users should only use a tiny subset of the API -- currently mostly the `flag` command. Given that the wiki is not a great success in terms of crowd-writing documentation or visibility, I have decided to start another approach: I started writing a new ocamlbuild manual during August (trying to fix some of the complaints people had on the existing one), and a preview of the result can be seen here: https://github.com/gasche/manual-ocamlbuild I will gladly accept contributions, including porting content present on the Wiki, or just adding content. I am still investigating options to mechanically generate some parts of this documentation from the source code; I think the "reference section" could basically include the output of a beefed up `-documentation` output, but am not sure how to integrate the API signature. The best solution could be to simply run ocamldoc, and then include the .html in the result -- this is how the OCaml manual itself does it, and it seems to work ok. (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.) --bcaec52c66ab91320f04e6315b78 Content-Type: text/html; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable
On Thu, Sep 12, 2013 at 4:28 PM, Romain Bardou <ro= main.bardou@inria.fr> wrote:
> - Christophe Troestler significantl= y improved the ocamlbuild API
> =A0 documentation, found in the "signatures.mli" file export= ing
> =A0 user-visible interfaces for the OCamlbuild components accessible > =A0 from a plugin

Is this available anywhere else than from the source code?
http://brion.inria.fr/gallium/index.php/Ocamlbuild has a link to<= br> http://gallium.inria.fr/~pouillar/ocamlbuild/ht= ml/Signatures.PLUGIN.html, should
this be updated? The manual has an Ocamlbuild section, should there be a
link from there to the API?


<= div>No, this is currently not available anywhere else. For curious users, t= he source code can be browsed in various places, such as:
=A0=A0<= a href=3D"http://caml.inria.fr/cgi-bin/viewvc.cgi/ocaml/trunk/ocamlbuild/si= gnatures.mli?view=3Dmarkup">http://caml.inria.fr/cgi-bin/viewvc.cgi/ocaml/t= runk/ocamlbuild/signatures.mli?view=3Dmarkup

Note that the "ocamlbuild API&qu= ot; is mostly meant for rather advanced users (which should be comfortable = reading a .mli file in their favorite text editor). Assuming the availabili= ty of satisfying documentation (more on that later), the long-term picture = is that most users should only use a tiny subset of the API -- currently mo= stly the `flag` command.

Given that the wiki is not a great success in terms of = crowd-writing documentation or visibility, I have decided to start another = approach: I started writing a new ocamlbuild manual during August (trying t= o fix some of the complaints people had on the existing one), and a preview= of the result can be seen here:

I will gla= dly accept contributions, including porting content present on the Wiki, or= just adding content. I am still investigating options to mechanically gene= rate some parts of this documentation from the source code; I think the &qu= ot;reference section" could basically include the output of a beefed u= p `-documentation` output, but am not sure how to integrate the API signatu= re. The best solution could be to simply run ocamldoc, and then include the= .html in the result -- this is how the OCaml manual itself does it, and it= seems to work ok.

(I had planned to give myself more time to improve this= documentation draft, before making a call to contributions on the list, bu= t your message prompted an earlier response. Thanks for your interest.)
--bcaec52c66ab91320f04e6315b78--