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.1 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 129FEBBC1 for ; Sun, 2 Mar 2008 13:54:03 +0100 (CET) X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: AgAAAHQyykfAbSoIh2dsb2JhbACQcQEBAQgKKZkO X-IronPort-AV: E=Sophos;i="4.25,434,1199660400"; d="scan'208";a="8850175" Received: from einhorn.in-berlin.de ([192.109.42.8]) by mail1-smtp-roc.national.inria.fr with ESMTP; 02 Mar 2008 13:54:02 +0100 X-Envelope-From: oliver@first.in-berlin.de X-Envelope-To: Received: from einhorn.in-berlin.de (localhost [127.0.0.1]) by einhorn.in-berlin.de (8.13.6/8.13.6/Debian-1) with ESMTP id m22Cs1bf026262 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NOT) for ; Sun, 2 Mar 2008 13:54:02 +0100 Received: (from www-data@localhost) by einhorn.in-berlin.de (8.13.6/8.13.6/Submit) id m22Cs1A3026260 for caml-list@yquem.inria.fr; Sun, 2 Mar 2008 13:54:01 +0100 X-Authentication-Warning: einhorn.in-berlin.de: www-data set sender to oliver@first.in-berlin.de using -f Received: from dslb-088-073-095-216.pools.arcor-ip.net (dslb-088-073-095-216.pools.arcor-ip.net [88.73.95.216]) by webmail.in-berlin.de (IMP) with HTTP for ; Sun, 2 Mar 2008 13:54:01 +0100 Message-ID: <1204462441.47caa369bed13@webmail.in-berlin.de> Date: Sun, 2 Mar 2008 13:54:01 +0100 From: Oliver Bandel Cc: caml-list@yquem.inria.fr Subject: documentation (Re: Re : [Caml-list] Not Rocket Science) References: <200803021041.55208.jon@ffconsultancy.com> <666572260803020346v3137bbd9t29900c2ca97c2dce@mail.gmail.com> In-Reply-To: <666572260803020346v3137bbd9t29900c2ca97c2dce@mail.gmail.com> MIME-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 8bit User-Agent: Internet Messaging Program (IMP) 3.2.6 X-Scanned-By: MIMEDefang_at_IN-Berlin_e.V. on 192.109.42.8 X-Spam: no; 0.00; bandel:01 in-berlin:01 gnuplot:01 gnuplot:01 bindings:01 printf:01 fprintf:01 camlimages:01 camlimages:01 sourceforge:01 imho:01 imho:01 oliver:01 oliver:01 caml-list:01 Zitat von Adrien : > There are working binding to gnuplot in fact : > http://sourceforge.net/projects/ocaml-gnuplot/ > > And there is also plplot and another one which name I can't remember. > > As a side note, I recently used gnuplot but not with these bindings : > a very easy way to create plots with gnuplot is to write the plot > coordinates to a file (in human-readable format) and then run gnuplot > with the file as argument. That's as easy as : > let log_c=open_out_bin "./results/pour_gnuplot.txt" in > Printf.fprintf log_c "%d %f\n" !i !mistake > (* this is an excerpt from an actual code *) [...] Using gnuplot is easiest to start with, but when it comes to more sophisticated needs, you soon will be stopped. plplot is more powerful here, so this is nice even for complex things (e.g. 3D-stuff with text also rotated in 3D). But plplot's documentation is noc ecomplete, and IMHO the usage of only 2D-arrays for 3D-data seems to be not the best design decision. So the API looks not that good. The documentation is big, but some necessary things are not explained. And the examples in use use functions, that are not explained in the documentation. So, one has to do reverse engineering, isnetad of straightforwad using the docs and start to code. But this is a common problem in nearly all programming stuff, open or closed source, applications or libraries... IMHO the biggest necessity is better documentation. This also gholds for a lot of OCaml-libraries, like Camlimages and others. It's fine to have the documentation showing all types and values. It's even better to explain, what modules can plugged in in which other modules, meaning here: which types of the modules in use fit together. yes, one can find out that by reading all docs and re-organizing the stuff. A documentation IMHO should help the reader here. A documentation can reflect the possible plug-in's. I'm not a monads-specialits, but as far as I have grasped the concept (on the surface I think), it is this way, how also a documentation could be done: Plug A in into B or C and it will work this way: ... Plug in C in F or Z, and it will work in this way.... Plug in F in G and it will work like ... Plug in C into U or W and it will work also: it will do... So, you can Plug in A into C, and C into U or W. And this can be shown as a graphic. I have heard, computers in the year 2008 can use text as well as graphics... ;-) This would enhance readability and adaption of new things. But it's also possible to only show the interfaces... ...when there are many module with types that can be used in many ways, the reader needs more time to get an overview. So, only some hints on how to make things more clear. The above mentioned is meant in gerenal, but I had tried to use CamlImages twice, and there was a while between both trials, and I ended up now in using jpeglib with C. ;-( (But I already has used jpeglib a while ago, so this compoarision is a littlebit unfair ;-)) Ciao, Oliver