From: <and...@us...> - 2008-12-06 17:05:07
|
Revision: 9051 http://plplot.svn.sourceforge.net/plplot/?rev=9051&view=rev Author: andrewross Date: 2008-12-06 17:05:03 +0000 (Sat, 06 Dec 2008) Log Message: ----------- ANR for Hezekiah M. Carty. Commit of ocaml documentation - new file missing from AWI's previous commit. Added Paths: ----------- trunk/doc/docbook/src/ocaml.xml Added: trunk/doc/docbook/src/ocaml.xml =================================================================== --- trunk/doc/docbook/src/ocaml.xml (rev 0) +++ trunk/doc/docbook/src/ocaml.xml 2008-12-06 17:05:03 UTC (rev 9051) @@ -0,0 +1,109 @@ +<!-- -*- mode: nxml -*- --> +<!-- + ocaml.xml: "OCaml Language" chapter + +Copyright (C) 2008 Jerry Bauck (original Ada version used as base) +Copyright (C) 2008 Hezekiah M. Carty + +Redistribution and use in source (XML DocBook) and "compiled" forms +(HTML, PDF, PostScript, DVI, TeXinfo and so forth) with or without +modification, are permitted provided that the following conditions are +met: + +1. Redistributions of source code (XML DocBook) must retain the +above copyright notice, this list of conditions and the following +disclaimer as the first lines of this file unmodified. + +2. Redistributions in compiled form (transformed to other DTDs, +converted to HTML, PDF, PostScript, and other formats) must +reproduce the above copyright notice, this list of conditions and +the following disclaimer in the documentation and/or other +materials provided with the distribution. + +Important: THIS DOCUMENTATION IS PROVIDED BY THE PLPLOT PROJECT "AS IS" +AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, +THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE PLPLOT PROJECT BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR +BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, +WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR +OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, +EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +--> + + +<chapter id="OCaml"> + <title>OCaml Language</title> + <para> This document describes the OCaml bindings to the PLplot technical plotting software, how to obtain the necessary software components, and how to use them together.</para> + + <sect1 id="ocaml_overview"> + <title>Overview</title> + <para> The OCaml bindings for PLplot provide a way for OCaml programmers to access the powerful PLplot technical plotting facilities directly from OCaml programs while working completely in OCaml—the OCaml programmer never needs to know or worry that PLplot itself is written in another language.</para> + </sect1> + <sect1 id="ocaml_bindings"> + + <title>The Bindings</title> + <para>The bindings are a re-expression and extension of the C-language API and as such are a kind of abstract layer between the user's code and the PLplot binary library. Additionally, there are a few capabilities not in the official API but nonetheless which are available to the C programmer which are included in the bindings and thus are directly available to the OCaml programmer. The OCaml PLplot API is all defined within the Plplot module. In general, it is suggested to include the line "open Plplot" in OCaml code using PLplot. The function and constant definitions are named such that they should avoid namespace collisions with other libraries. PLplot functions have a "pl" prefix while constants/variant types have a "PL_" prefix.</para> + <para> The core binding provides a close to direct mapping to the underlying C code. It follows the C API very closely, with the exception of a few parameters which become redundant under OCaml (ex. array lengths are determined automatically by OCaml and function callbacks which are handled slightly differently than in C).</para> + <para> There are also a selection of functions which provide support for operations outside of the base C API.</para> + <sect2 id="ocaml_core"> + <title>Core Binding</title> + <para> The core binding is mostly a direct and obvious mapping of the C application programming interface (API) to OCaml. Thus, for example, where a C function such as plcol0 requires a single integer argument, there is a corresponding OCaml function also called plcol0 which also requires a single integer argument. (plcol0 happens to set the drawing color using a number which is associated with a set of colors). Various constants from the C API are also included here as OCaml variant types with a "PL_" prefix to avoid namespace clashes when the Plplot module is opened. For example, where the C PLplot API uses GRID_* to select between the data gridding methods, the OCaml API uses PL_GRID_*.</para> + </sect2> + <sect2 id="ocaml_specific"> + <title>OCaml specific functions and functionality</title> + <para> Several of the PLplot core functions allow the user to provide a transformation callback function to adjust the location of the plotted data. This is handled differently in the OCaml bindings than in order to keep the interface between C and OCaml as simple as possible. Rather than passing transformation functions directly to each PLplot function which supports a coordinate transformation, the coordinate tranform functions are set globally using the plset_pltr and plset_mapform functions. Similarly, the functions plunset_pltr and plunset_mapform can be used to clear the globally defined coordinate transformation function. Note that the transform functions are only used in the functions which support them in the C API (ex. plmap)- they are not automatically applied to plotted data in other function calls (ex. plline). For demonstrations of their use, see OCaml PLplot examples 16 and 20 for plset_pltr and example 19 for plset_mapform.</para> + </sect2> + </sect1> + <sect1 id="ocaml_examples"> + <title> The Examples</title> + <para> An important part of the OCaml bindings is the examples, some 28 of which demonstrate how to use many of the features of the PLplot package. These examples also serve as a testbed for the bindings in OCaml and other languages by checking the Postscript files that are generated by each example against those generated by the C versions. These examples have been completely re-written in OCaml (but retain a C flavor in the names that are given to objects). All of the OCaml examples generate exactly the same Postscript as the C versions, examples 14 and 17 excepted since they have not been translated yet.</para> + </sect1> + <sect1 id="ocaml_obtaining"> + <title>Obtaining the Software</title> + <para> There are three software components that you will need: the OCaml compiler, the PLplot library, and the camlidl OCaml >-< C binding generator. As of version 5.9.1, the OCaml bindings are included in the core PLplot distribution.</para> + <sect2 id="ocaml_obtaining_ocaml"> + <title>Obtaining the OCaml compiler</title> + <para> You will need the OCaml compiler in order to build and use the OCaml PLplot bindings. OCaml includes both a bytecode compiler (ocamlc) and a native code compiler (ocamlopt). Both of these are supported by PLplot.</para> + <para> Your computer may already have OCaml installed, or you can download it from <ulink url="http://caml.inria.fr/">caml.inria.fr</ulink>. Several Linux distributions including Debian, Ubuntu and Fedora have OCaml binary packages available. Another route to obtaining OCaml is by using GODI, a source-based distribution of OCaml and a number of OCaml libraries. GODI can be retrieved from <ulink url="http://godi.camlcity.org/">godi.camlcity.org</ulink>. GODI has support for building and installing under Linux, Apple's OS X and MS Windows.</para> + </sect2> + <sect2 id="ocaml_obtaining_plplot"> + <title>Download and install PLplot</title> + <para> PLplot can be downloaded from the PLplot home page at <ulink url="http://sourceforge.net/projects/plplot">sourceforge.net—plplot</ulink>. Follow the installation instructions after downloading. The installation process is more involved than other open source software and requires that your computer has cmake installed. Packages are available for several major Linux distributions, though the OCaml bindings are only included in versions 5.9.1 and later. OCaml bindings are available for versions 5.8.0 and 5.9.0 at <ulink url="http://ocaml-plplot.googlecode.com/">ocaml-plplot.googlecode.com</ulink>. These bindings are not as complete as the bindings included in the official PLplot releases but are still quite functional.</para> + </sect2> + </sect1> + <sect1 id="ocaml_howto"> + <title>How to use the OCaml bindings</title> + <sect2 id="ocaml_sample_project"> + <title>Sample command line project</title> + <para> It is instructive to present a simple example that can be compiled and run from the command line. Although this example is specific to one installation, it should be fairly straightforward to adapt it to another installation. Toward that end, it is helpful to understand the PLplot lingo of "build directory" and "installation directory."</para> + <para> Here is a simple program that will generate a plot of part of a parabola.</para> + <programlisting> + open Plplot + let simple_example () = + let xs = Array.init 21 (fun xi -> float xi -. 10.0) in + let ys = Array.map (fun x -> x**2.0) xs in + plinit (); + plenv (-10.0) 10.0 0.0 100.0 0 0; + plline xs ys; + plend (); + () + + let () = simple_example () + </programlisting> + <para> Next is a command line that will compile, bind, and link it. It requires that the OCaml findlib program is installed and in your $PATH and that the above code be saved as simple_example.ml</para> + <programlisting> + ocamlfind opt -package plplot -linkpkg -o simple_example simple_example.ml + </programlisting> + <para> The resulting binary program can be run by typing <command>./simple_example</command></para> + + </sect2> + </sect1> + <sect1 id="ocaml_known_issues"> + <title>Known Issues</title> + <para></para> + + </sect1> +</chapter> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <ai...@us...> - 2008-12-06 17:45:01
|
Revision: 9052 http://plplot.svn.sourceforge.net/plplot/?rev=9052&view=rev Author: airwin Date: 2008-12-06 17:44:55 +0000 (Sat, 06 Dec 2008) Log Message: ----------- Make properties of ocaml.xml the same as other xml files in this directory. Property Changed: ---------------- trunk/doc/docbook/src/ocaml.xml Property changes on: trunk/doc/docbook/src/ocaml.xml ___________________________________________________________________ Added: svn:keywords + Author Date Id Revision This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <and...@us...> - 2008-12-24 18:41:36
|
Revision: 9227 http://plplot.svn.sourceforge.net/plplot/?rev=9227&view=rev Author: andrewross Date: 2008-12-24 18:41:29 +0000 (Wed, 24 Dec 2008) Log Message: ----------- Andrew Ross on behalf of Hezekiah M Carty. Small typo fix for ocaml documentation. Modified Paths: -------------- trunk/doc/docbook/src/ocaml.xml Modified: trunk/doc/docbook/src/ocaml.xml =================================================================== --- trunk/doc/docbook/src/ocaml.xml 2008-12-24 18:25:58 UTC (rev 9226) +++ trunk/doc/docbook/src/ocaml.xml 2008-12-24 18:41:29 UTC (rev 9227) @@ -63,7 +63,7 @@ </sect1> <sect1 id="ocaml_obtaining"> <title>Obtaining the Software</title> - <para> There are three software components that you will need: the OCaml compiler, the PLplot library, and the camlidl OCaml >-< C binding generator. As of version 5.9.1, the OCaml bindings are included in the core PLplot distribution.</para> + <para> There are three software components that you will need: the OCaml compiler, the PLplot library, and the camlidl OCaml <-> C binding generator. As of version 5.9.1, the OCaml bindings are included in the core PLplot distribution.</para> <sect2 id="ocaml_obtaining_ocaml"> <title>Obtaining the OCaml compiler</title> <para> You will need the OCaml compiler in order to build and use the OCaml PLplot bindings. OCaml includes both a bytecode compiler (ocamlc) and a native code compiler (ocamlopt). Both of these are supported by PLplot.</para> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <hez...@us...> - 2009-09-20 19:23:14
|
Revision: 10440 http://plplot.svn.sourceforge.net/plplot/?rev=10440&view=rev Author: hezekiahcarty Date: 2009-09-20 19:23:02 +0000 (Sun, 20 Sep 2009) Log Message: ----------- Update OCaml section of PLplot documentation Modified Paths: -------------- trunk/doc/docbook/src/ocaml.xml Modified: trunk/doc/docbook/src/ocaml.xml =================================================================== --- trunk/doc/docbook/src/ocaml.xml 2009-09-20 18:14:45 UTC (rev 10439) +++ trunk/doc/docbook/src/ocaml.xml 2009-09-20 19:23:02 UTC (rev 10440) @@ -3,7 +3,7 @@ ocaml.xml: "OCaml Language" chapter Copyright (C) 2008 Jerry Bauck (original Ada version used as base) -Copyright (C) 2008 Hezekiah M. Carty +Copyright (C) 2008, 2009 Hezekiah M. Carty Redistribution and use in source (XML DocBook) and "compiled" forms (HTML, PDF, PostScript, DVI, TeXinfo and so forth) with or without @@ -38,7 +38,7 @@ <title>OCaml Language</title> <para> This document describes the OCaml bindings to the PLplot technical - plotting software, how to obtain the necessary software components, and + plotting software, how to obtain the necessary software components and how to use them together. </para> @@ -56,28 +56,34 @@ <sect1 id="ocaml_bindings"> <title>The Bindings</title> <para> - The bindings are a re-expression and extension of the C-language API and - as such are a kind of abstract layer between the user's code and the - PLplot binary library. Additionally, there are a few capabilities not in - the official API but nonetheless which are available to the C programmer - which are included in the bindings and thus are directly available to - the OCaml programmer. The OCaml PLplot API is all defined within the - Plplot module. In general, it is suggested to include the line "open - Plplot" in OCaml code using PLplot. The function and constant - definitions are named such that they should avoid namespace collisions - with other libraries. PLplot functions have a "pl" prefix while - constants/variant types have a "PL_" prefix. + The OCaml bindings for PLplot provide an interface the the PLplot C API. + In addition to providing access to the core functions of the C API, the + OCaml PLplot interface also includes a set of higher-level plotting + functions which, while built on top of the core PLplot API, retain more + of an OCaml flavor. </para> <para> + The OCaml PLplot API is defined within the Plplot module. In general, + it is suggested to include the line <command>open Plplot</command> in + OCaml code using PLplot. The function and constant definitions are + named such that they should avoid namespace collisions with other + libraries. Core PLplot functions have a "pl" prefix, while constant + constructors/variant types have a "PL_" prefix. + </para> + <para> The core binding provides a close to direct mapping to the underlying C - code. It follows the C API very closely, with the exception of a few + library. It follows the C API very closely, with the exception of a few parameters which become redundant under OCaml (ex. array lengths are determined automatically by OCaml and function callbacks which are - handled slightly differently than in C). + handled slightly differently than in C). An OCaml user of PLplot does + not need to worry about memory management issues as they are handled + automatically by the bindings. </para> <para> There are also a selection of functions which provide support for - operations outside of the base C API. + operations outside of the base C API. These higher level functions are + defined within the <command>Plplot.Plot</command> and + <command>Plplot.Quick_plot</command> modules. </para> <sect2 id="ocaml_core"> <title>Core Binding</title> @@ -96,7 +102,7 @@ </para> </sect2> <sect2 id="ocaml_specific"> - <title>OCaml specific functions and functionality</title> + <title>OCaml-specific variations to the core PLplot API</title> <para> Several of the PLplot core functions allow the user to provide a transformation callback function to adjust the location of the plotted @@ -114,6 +120,20 @@ examples 16 and 20 for plset_pltr and example 19 for plset_mapform. </para> </sect2> + <sect2 id="ocaml_high_level"> + <title>OCaml high level 2D plotting API</title> + <para> + In addition to the core PLplot API, the OCaml bindings provide two + modules which provide a more OCaml-like interface: + <command>Plplot.Plot</command> and + <command>Plplot.Quick_plot</command>. <command>Plplot.Plot</command> + provides a simlified naming scheme for plotting functions, as well as + the means to more easily track multiple plot streams at once. + <command>Plplot.Quick_plot</command> provides functions to quickly + plot points, lines, data arrays (images) and functions without the + need for any plot setup or boilerplate. + </para> + </sect2> </sect1> <sect1 id="ocaml_examples"> @@ -124,9 +144,9 @@ These examples also serve as a testbed for the bindings in OCaml and other languages by checking the Postscript files that are generated by each example against those generated by the C versions. These examples - have been completely re-written in OCaml (but retain a C flavor in the - names that are given to objects). All of the OCaml examples generate - exactly the same Postscript as the C versions. + have been completely re-written in OCaml (but retain a C flavor in their + structure and the names that are given to objects). All of the OCaml + examples generate exactly the same Postscript as the C versions. </para> </sect1> @@ -134,9 +154,8 @@ <title>Obtaining the Software</title> <para> There are three software components that you will need: the OCaml - compiler, the PLplot library, and the camlidl OCaml <-> C binding - generator. As of version 5.9.1, the OCaml bindings are included in the - core PLplot distribution. + compiler, the PLplot library, and the camlidl stub code generator for + OCaml bindings to C libraries. </para> <sect2 id="ocaml_obtaining_ocaml"> <title>Obtaining the OCaml compiler</title> @@ -158,68 +177,170 @@ and MS Windows. </para> </sect2> - <sect2 id="ocaml_obtaining_plplot"> - <title>Download and install PLplot</title> - <para> - PLplot can be downloaded from the PLplot home page at - <ulink url="http://sourceforge.net/projects/plplot">sourceforge.net—plplot</ulink>. - Follow the installation instructions after downloading. The - installation process is more involved than other open source software - and requires that your computer has cmake installed. Packages are - available for several major Linux distributions, though the OCaml - bindings are only included in versions 5.9.1 and later. OCaml bindings - are available for versions 5.8.0 and 5.9.0 at - <ulink url="http://ocaml-plplot.googlecode.com/">ocaml-plplot.googlecode.com</ulink>. - These bindings are not as complete as the bindings included in the - official PLplot releases but are still quite functional. - </para> - </sect2> </sect1> + <sect1 id="ocaml_howto"> <title>How to use the OCaml bindings</title> - <sect2 id="ocaml_sample_project"> - <title>Sample command line project</title> + <para> + The three examples provided below illustrate the available methods for + generating plots with PLplot from OCaml. They proceed in order from + lowest-level to highest-level. + </para> + <sect2 id="ocaml_findlib_setup"> + <title>How to setup findlib for use with the OCaml bindings</title> <para> - It is instructive to present a simple example that can be compiled and - run from the command line. Although this example is specific to one - installation, it should be fairly straightforward to adapt it to - another installation. Toward that end, it is helpful to understand the - PLplot lingo of "build directory" and "installation directory." + The following examples require that + <ulink url="http://projects.camlcity.org/projects/findlib.html"> + findlib + </ulink> + and its associated tools (ie., ocamlfind) are installed in in your + <command>$PATH</command>. </para> <para> - Here is a simple program that will generate a plot of part of a - parabola. + If PLplot was installed under a non-standard prefix, or any prefix + where findlib does not check automatically for OCaml libraries, then + the following enviroment variables can be set to tell findlib where to + look for PLplot: </para> <programlisting> - open Plplot + export OCAMLPATH=$PLPLOT_INSTALL_PREFIX/lib/ocaml/$OCAML_VERSION:$OCAMLPATH + export LD_LIBRARY_PATH=$PLPLOT_INSTALL_PREFIX/lib/ocaml/$OCAML_VERSION/stublibs:$LD_LIBRARY_PATH + </programlisting> + </sect2> + <sect2 id="ocaml_command_line_sample_project_core"> + <title>Sample command line project (core API)</title> + <para> + Here is a simple example that can be compiled and run from the command + line. The result will be a program that generates a plot of part of a + parabola using only the core PLplot API. + </para> + <programlisting> + (* Open the Plplot module to give access to all of the PLplot + values without the need to add the "Plplot." prefix. *) + open Plplot + let simple_example () = - let xs = Array.init 21 (fun xi -> float xi -. 10.0) in - let ys = Array.map (fun x -> x**2.0) xs in - plinit (); - plenv (-10.0) 10.0 0.0 100.0 0 0; - plline xs ys; - plend (); - () + (* Sample at 20 points, ranging from -10.0 to 10.0 *) + let xs = Array.init 21 (fun xi -> float xi -. 10.0) in + let ys = Array.map (fun x -> x**2.0) xs in + (* Initialize PLplot *) + plinit (); + + (* Draw the plot window axes *) + plenv (-10.0) 10.0 0.0 100.0 0 0; + + (* Draw the parabola points as a series of line segments *) + plline xs ys; + + (* End the plotting session *) + plend (); + () + let () = simple_example () </programlisting> <para> - Next is a command line that will compile, bind, and link it. It - requires that the OCaml findlib program is installed and in your $PATH - and that the above code be saved as simple_example.ml + Save this code as <command>simple_example_core.ml</command>. The + following command can then be used to build the example: </para> <programlisting> - ocamlfind opt -package plplot -linkpkg -o simple_example simple_example.ml + ocamlfind opt -package plplot -linkpkg -o simple_example_core simple_example_core.ml </programlisting> <para> The resulting binary program can be run by typing - <command>./simple_example</command> + <command>./simple_example_core</command> </para> </sect2> + <sect2 id="ocaml_command_line_sample_project_ocaml"> + <title>Sample command line project (OCaml-specific API)</title> + <para> + Here is another example that can be compiled and run from the command + line. The result will be a program that generates a plot of part of a + parabola similar to the above example, but now using the + OCaml-specific PLplot API rather than the core PLplot API. + </para> + <programlisting> + (* Open the Plplot module to give access to all of the PLplot + values without the need to add the "Plplot." prefix. + Aliasing the module P to the module Plot will save some typing + without further namespace pollution. *) + open Plplot + module P = Plot + + let simple_example () = + (* Initialize a new plot, using the windowed Cairo device + ("xcairo") *) + let p = P.init (-10.0) 10.0 0.0 100.0 P.Greedy (P.Window P.Cairo) in + + (* Draw the parabola *) + P.plot ~stream:p [P.func P.Blue (fun x -> x ** 2.0) (-10.0, 10.0)]; + + (* Draw the plot axes and close up the plot stream using the default + spacing between tick marks. *) + P.finish ~stream:p 0.0 0.0; + () + + let () = simple_example () + </programlisting> + <para> + Save this code as <command>simple_example_ocaml.ml</command>. The + following command can then be used to build the example: + </para> + <programlisting> + ocamlfind opt -package plplot -linkpkg -o simple_example_ocaml simple_example_ocaml.ml + </programlisting> + <para> + The resulting binary program can be run by typing + <command>./simple_example_ocaml</command> + </para> + </sect2> + <sect2 id="ocaml_toplevel_sample_project"> + <title>Sample toplevel project</title> + <para> + The OCaml interactive toplevel (<command>ocaml</command>) provides a + very useful tool for code testing, development and interactive data + analysis. + </para> + <para> + The Quick_plot module provides a set of functions for producing quick, + simple two-dimensional plots from both the toplevel and stand-alone + OCaml programs. Here is a set of commands which can be used in a + toplevel session to produce a plot of a portion of a parabola, similar + to the compiled examples above. + </para> + <programlisting> + # #use "topfind";; + # #require "plplot";; + # open Plplot;; + # Quick_plot.func ~names:["Parabola"] [(fun x -> x ** 2.0)] (-10.0, 10.0);; + </programlisting> + <para> + Conversely, the above <command>ocaml</command> session could be + expressed in a compiled OCaml program: + </para> + <programlisting> + Plplot.Quick_plot.func ~names:["Parabola"] [(fun x -> x ** 2.0)] (-10.0, 10.0) + </programlisting> + <para> + Save this code as <command>simple_example_quick.ml</command>. The + following command can then be used to build the example: + </para> + <programlisting> + ocamlfind opt -package plplot -linkpkg -o simple_example_quick simple_example_quick.ml + </programlisting> + <para> + The resulting binary program can be run by typing + <command>./simple_example_quick</command> + </para> + </sect2> </sect1> <sect1 id="ocaml_known_issues"> <title>Known Issues</title> - <para></para> + <para> + There are currently no known issues with the OCaml PLplot bindings. If + you discover any problems with PLplot or the OCaml bindings, please + report them to the PLplot development mailing list. + </para> </sect1> </chapter> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <hez...@us...> - 2014-07-04 10:59:46
|
Revision: 13135 http://sourceforge.net/p/plplot/code/13135 Author: hezekiahcarty Date: 2014-07-04 10:59:42 +0000 (Fri, 04 Jul 2014) Log Message: ----------- Update OCaml-specific documentation Modified Paths: -------------- trunk/doc/docbook/src/ocaml.xml Modified: trunk/doc/docbook/src/ocaml.xml =================================================================== --- trunk/doc/docbook/src/ocaml.xml 2014-07-03 14:46:13 UTC (rev 13134) +++ trunk/doc/docbook/src/ocaml.xml 2014-07-04 10:59:42 UTC (rev 13135) @@ -176,11 +176,9 @@ from <ulink url="http://caml.inria.fr/">caml.inria.fr</ulink>. Several Linux distributions including Debian, Ubuntu and Fedora have OCaml binary packages available. Another route to obtaining OCaml is by - using GODI, a source-based distribution of OCaml and a number of OCaml - libraries. GODI can be retrieved from - <ulink url="http://godi.camlcity.org/">godi.camlcity.org</ulink>. - GODI has support for building and installing under Linux, Apple's OS X - and MS Windows. + using opam, a source-based distribution of OCaml and a number of OCaml + libraries. opam can be retrieved from + <ulink url="http://opam.ocaml.org/">opam.ocaml.org</ulink>. </para> </sect2> </sect1> @@ -277,11 +275,11 @@ (* Initialize a new plot, using the windowed Cairo device ("xcairo") *) let p = - P.init (-10.0, 0.0) (10.0, 100.0) P.Greedy (P.Window P.Cairo) + P.init (-10.0, 0.0) (10.0, 100.0) `greedy (`window `cairo) in (* Draw the parabola *) - P.plot ~stream:p [P.func P.Blue (fun x -> x ** 2.0) (-10.0, 10.0)]; + P.plot ~stream:p [P.func `blue (fun x -> x ** 2.0) (-10.0, 10.0)]; (* Draw the plot axes and close up the plot stream using the default spacing between tick marks. *) This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <hez...@us...> - 2009-09-03 04:39:30
|
Revision: 10367 http://plplot.svn.sourceforge.net/plplot/?rev=10367&view=rev Author: hezekiahcarty Date: 2009-09-03 04:39:20 +0000 (Thu, 03 Sep 2009) Log Message: ----------- Whitespace cleanup for the OCaml-specific documentation Modified Paths: -------------- trunk/doc/docbook/src/ocaml.xml Modified: trunk/doc/docbook/src/ocaml.xml =================================================================== --- trunk/doc/docbook/src/ocaml.xml 2009-09-02 18:18:34 UTC (rev 10366) +++ trunk/doc/docbook/src/ocaml.xml 2009-09-03 04:39:20 UTC (rev 10367) @@ -36,50 +36,160 @@ <chapter id="OCaml"> <title>OCaml Language</title> - <para> This document describes the OCaml bindings to the PLplot technical plotting software, how to obtain the necessary software components, and how to use them together.</para> + <para> + This document describes the OCaml bindings to the PLplot technical + plotting software, how to obtain the necessary software components, and + how to use them together. + </para> <sect1 id="ocaml_overview"> <title>Overview</title> - <para> The OCaml bindings for PLplot provide a way for OCaml programmers to access the powerful PLplot technical plotting facilities directly from OCaml programs while working completely in OCaml—the OCaml programmer never needs to know or worry that PLplot itself is written in another language.</para> + <para> + The OCaml bindings for PLplot provide a way for OCaml programmers to + access the powerful PLplot technical plotting facilities directly from + OCaml programs while working completely in OCaml—the OCaml + programmer never needs to know or worry that PLplot itself is written in + another language. + </para> </sect1> + <sect1 id="ocaml_bindings"> - <title>The Bindings</title> - <para>The bindings are a re-expression and extension of the C-language API and as such are a kind of abstract layer between the user's code and the PLplot binary library. Additionally, there are a few capabilities not in the official API but nonetheless which are available to the C programmer which are included in the bindings and thus are directly available to the OCaml programmer. The OCaml PLplot API is all defined within the Plplot module. In general, it is suggested to include the line "open Plplot" in OCaml code using PLplot. The function and constant definitions are named such that they should avoid namespace collisions with other libraries. PLplot functions have a "pl" prefix while constants/variant types have a "PL_" prefix.</para> - <para> The core binding provides a close to direct mapping to the underlying C code. It follows the C API very closely, with the exception of a few parameters which become redundant under OCaml (ex. array lengths are determined automatically by OCaml and function callbacks which are handled slightly differently than in C).</para> - <para> There are also a selection of functions which provide support for operations outside of the base C API.</para> + <para> + The bindings are a re-expression and extension of the C-language API and + as such are a kind of abstract layer between the user's code and the + PLplot binary library. Additionally, there are a few capabilities not in + the official API but nonetheless which are available to the C programmer + which are included in the bindings and thus are directly available to + the OCaml programmer. The OCaml PLplot API is all defined within the + Plplot module. In general, it is suggested to include the line "open + Plplot" in OCaml code using PLplot. The function and constant + definitions are named such that they should avoid namespace collisions + with other libraries. PLplot functions have a "pl" prefix while + constants/variant types have a "PL_" prefix. + </para> + <para> + The core binding provides a close to direct mapping to the underlying C + code. It follows the C API very closely, with the exception of a few + parameters which become redundant under OCaml (ex. array lengths are + determined automatically by OCaml and function callbacks which are + handled slightly differently than in C). + </para> + <para> + There are also a selection of functions which provide support for + operations outside of the base C API. + </para> <sect2 id="ocaml_core"> <title>Core Binding</title> - <para> The core binding is mostly a direct and obvious mapping of the C application programming interface (API) to OCaml. Thus, for example, where a C function such as plcol0 requires a single integer argument, there is a corresponding OCaml function also called plcol0 which also requires a single integer argument. (plcol0 happens to set the drawing color using a number which is associated with a set of colors). Various constants from the C API are also included here as OCaml variant types with a "PL_" prefix to avoid namespace clashes when the Plplot module is opened. For example, where the C PLplot API uses GRID_* to select between the data gridding methods, the OCaml API uses PL_GRID_*.</para> + <para> + The core binding is mostly a direct and obvious mapping of the C + application programming interface (API) to OCaml. Thus, for example, + where a C function such as plcol0 requires a single integer argument, + there is a corresponding OCaml function also called plcol0 which also + requires a single integer argument. (plcol0 happens to set the drawing + color using a number which is associated with a set of colors). + Various constants from the C API are also included here as OCaml + variant types with a "PL_" prefix to avoid namespace clashes when the + Plplot module is opened. For example, where the C PLplot API uses + GRID_* to select between the data gridding methods, the OCaml API uses + PL_GRID_*. + </para> </sect2> <sect2 id="ocaml_specific"> <title>OCaml specific functions and functionality</title> - <para> Several of the PLplot core functions allow the user to provide a transformation callback function to adjust the location of the plotted data. This is handled differently in the OCaml bindings than in order to keep the interface between C and OCaml as simple as possible. Rather than passing transformation functions directly to each PLplot function which supports a coordinate transformation, the coordinate tranform functions are set globally using the plset_pltr and plset_mapform functions. Similarly, the functions plunset_pltr and plunset_mapform can be used to clear the globally defined coordinate transformation function. Note that the transform functions are only used in the functions which support them in the C API (ex. plmap)- they are not automatically applied to plotted data in other function calls (ex. plline). For demonstrations of their use, see OCaml PLplot examples 16 and 20 for plset_pltr and example 19 for plset_mapform.</para> + <para> + Several of the PLplot core functions allow the user to provide a + transformation callback function to adjust the location of the plotted + data. This is handled differently in the OCaml bindings than in order + to keep the interface between C and OCaml as simple as possible. + Rather than passing transformation functions directly to each PLplot + function which supports a coordinate transformation, the coordinate + tranform functions are set globally using the plset_pltr and + plset_mapform functions. Similarly, the functions plunset_pltr and + plunset_mapform can be used to clear the globally defined coordinate + transformation function. Note that the transform functions are only + used in the functions which support them in the C API (ex. plmap)- + they are not automatically applied to plotted data in other function + calls (ex. plline). For demonstrations of their use, see OCaml PLplot + examples 16 and 20 for plset_pltr and example 19 for plset_mapform. + </para> </sect2> </sect1> + <sect1 id="ocaml_examples"> <title> The Examples</title> - <para> An important part of the OCaml bindings is the examples, some 31 of which demonstrate how to use many of the features of the PLplot package. These examples also serve as a testbed for the bindings in OCaml and other languages by checking the Postscript files that are generated by each example against those generated by the C versions. These examples have been completely re-written in OCaml (but retain a C flavor in the names that are given to objects). All of the OCaml examples generate exactly the same Postscript as the C versions.</para> + <para> + An important part of the OCaml bindings is the examples, some 31 of + which demonstrate how to use many of the features of the PLplot package. + These examples also serve as a testbed for the bindings in OCaml and + other languages by checking the Postscript files that are generated by + each example against those generated by the C versions. These examples + have been completely re-written in OCaml (but retain a C flavor in the + names that are given to objects). All of the OCaml examples generate + exactly the same Postscript as the C versions. + </para> </sect1> + <sect1 id="ocaml_obtaining"> <title>Obtaining the Software</title> - <para> There are three software components that you will need: the OCaml compiler, the PLplot library, and the camlidl OCaml <-> C binding generator. As of version 5.9.1, the OCaml bindings are included in the core PLplot distribution.</para> + <para> + There are three software components that you will need: the OCaml + compiler, the PLplot library, and the camlidl OCaml <-> C binding + generator. As of version 5.9.1, the OCaml bindings are included in the + core PLplot distribution. + </para> <sect2 id="ocaml_obtaining_ocaml"> <title>Obtaining the OCaml compiler</title> - <para> You will need the OCaml compiler in order to build and use the OCaml PLplot bindings. OCaml includes both a bytecode compiler (ocamlc) and a native code compiler (ocamlopt). Both of these are supported by PLplot.</para> - <para> Your computer may already have OCaml installed, or you can download it from <ulink url="http://caml.inria.fr/">caml.inria.fr</ulink>. Several Linux distributions including Debian, Ubuntu and Fedora have OCaml binary packages available. Another route to obtaining OCaml is by using GODI, a source-based distribution of OCaml and a number of OCaml libraries. GODI can be retrieved from <ulink url="http://godi.camlcity.org/">godi.camlcity.org</ulink>. GODI has support for building and installing under Linux, Apple's OS X and MS Windows.</para> + <para> + You will need the OCaml compiler in order to build and use the OCaml + PLplot bindings. OCaml includes both a bytecode compiler (ocamlc) and + a native code compiler (ocamlopt). Both of these are supported by + PLplot. + </para> + <para> + Your computer may already have OCaml installed, or you can download it + from <ulink url="http://caml.inria.fr/">caml.inria.fr</ulink>. Several + Linux distributions including Debian, Ubuntu and Fedora have OCaml + binary packages available. Another route to obtaining OCaml is by + using GODI, a source-based distribution of OCaml and a number of OCaml + libraries. GODI can be retrieved from + <ulink url="http://godi.camlcity.org/">godi.camlcity.org</ulink>. + GODI has support for building and installing under Linux, Apple's OS X + and MS Windows. + </para> </sect2> <sect2 id="ocaml_obtaining_plplot"> <title>Download and install PLplot</title> - <para> PLplot can be downloaded from the PLplot home page at <ulink url="http://sourceforge.net/projects/plplot">sourceforge.net—plplot</ulink>. Follow the installation instructions after downloading. The installation process is more involved than other open source software and requires that your computer has cmake installed. Packages are available for several major Linux distributions, though the OCaml bindings are only included in versions 5.9.1 and later. OCaml bindings are available for versions 5.8.0 and 5.9.0 at <ulink url="http://ocaml-plplot.googlecode.com/">ocaml-plplot.googlecode.com</ulink>. These bindings are not as complete as the bindings included in the official PLplot releases but are still quite functional.</para> + <para> + PLplot can be downloaded from the PLplot home page at + <ulink url="http://sourceforge.net/projects/plplot">sourceforge.net—plplot</ulink>. + Follow the installation instructions after downloading. The + installation process is more involved than other open source software + and requires that your computer has cmake installed. Packages are + available for several major Linux distributions, though the OCaml + bindings are only included in versions 5.9.1 and later. OCaml bindings + are available for versions 5.8.0 and 5.9.0 at + <ulink url="http://ocaml-plplot.googlecode.com/">ocaml-plplot.googlecode.com</ulink>. + These bindings are not as complete as the bindings included in the + official PLplot releases but are still quite functional. + </para> </sect2> </sect1> <sect1 id="ocaml_howto"> <title>How to use the OCaml bindings</title> <sect2 id="ocaml_sample_project"> <title>Sample command line project</title> - <para> It is instructive to present a simple example that can be compiled and run from the command line. Although this example is specific to one installation, it should be fairly straightforward to adapt it to another installation. Toward that end, it is helpful to understand the PLplot lingo of "build directory" and "installation directory."</para> - <para> Here is a simple program that will generate a plot of part of a parabola.</para> + <para> + It is instructive to present a simple example that can be compiled and + run from the command line. Although this example is specific to one + installation, it should be fairly straightforward to adapt it to + another installation. Toward that end, it is helpful to understand the + PLplot lingo of "build directory" and "installation directory." + </para> + <para> + Here is a simple program that will generate a plot of part of a + parabola. + </para> <programlisting> open Plplot let simple_example () = @@ -93,17 +203,23 @@ let () = simple_example () </programlisting> - <para> Next is a command line that will compile, bind, and link it. It requires that the OCaml findlib program is installed and in your $PATH and that the above code be saved as simple_example.ml</para> + <para> + Next is a command line that will compile, bind, and link it. It + requires that the OCaml findlib program is installed and in your $PATH + and that the above code be saved as simple_example.ml + </para> <programlisting> ocamlfind opt -package plplot -linkpkg -o simple_example simple_example.ml </programlisting> - <para> The resulting binary program can be run by typing <command>./simple_example</command></para> - + <para> + The resulting binary program can be run by typing + <command>./simple_example</command> + </para> </sect2> </sect1> + <sect1 id="ocaml_known_issues"> <title>Known Issues</title> <para></para> - </sect1> </chapter> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <hez...@us...> - 2009-09-30 22:49:06
|
Revision: 10502 http://plplot.svn.sourceforge.net/plplot/?rev=10502&view=rev Author: hezekiahcarty Date: 2009-09-30 22:48:55 +0000 (Wed, 30 Sep 2009) Log Message: ----------- Typo fixes and general cleanup in the OCaml documentation Thanks to Alpounet on #ocaml for their comments! Modified Paths: -------------- trunk/doc/docbook/src/ocaml.xml Modified: trunk/doc/docbook/src/ocaml.xml =================================================================== --- trunk/doc/docbook/src/ocaml.xml 2009-09-30 22:48:10 UTC (rev 10501) +++ trunk/doc/docbook/src/ocaml.xml 2009-09-30 22:48:55 UTC (rev 10502) @@ -56,7 +56,7 @@ <sect1 id="ocaml_bindings"> <title>The Bindings</title> <para> - The OCaml bindings for PLplot provide an interface the the PLplot C API. + The OCaml bindings for PLplot provide an interface to the PLplot C API. In addition to providing access to the core functions of the C API, the OCaml PLplot interface also includes a set of higher-level plotting functions which, while built on top of the core PLplot API, retain more @@ -64,11 +64,12 @@ </para> <para> The OCaml PLplot API is defined within the Plplot module. In general, - it is suggested to include the line <command>open Plplot</command> in + it is suggested to include the line <literal>open Plplot</literal> in OCaml code using PLplot. The function and constant definitions are named such that they should avoid namespace collisions with other - libraries. Core PLplot functions have a "pl" prefix, while constant - constructors/variant types have a "PL_" prefix. + libraries. Core PLplot functions have a <literal>pl</literal> prefix, + while constant constructors/variant types have a <literal>PL_</literal> + prefix. </para> <para> The core binding provides a close to direct mapping to the underlying C @@ -82,23 +83,25 @@ <para> There are also a selection of functions which provide support for operations outside of the base C API. These higher level functions are - defined within the <command>Plplot.Plot</command> and - <command>Plplot.Quick_plot</command> modules. + defined within the <literal>Plplot.Plot</literal> and + <literal>Plplot.Quick_plot</literal> modules. </para> <sect2 id="ocaml_core"> <title>Core Binding</title> <para> The core binding is mostly a direct and obvious mapping of the C application programming interface (API) to OCaml. Thus, for example, - where a C function such as plcol0 requires a single integer argument, - there is a corresponding OCaml function also called plcol0 which also - requires a single integer argument. (plcol0 happens to set the drawing - color using a number which is associated with a set of colors). - Various constants from the C API are also included here as OCaml - variant types with a "PL_" prefix to avoid namespace clashes when the - Plplot module is opened. For example, where the C PLplot API uses - GRID_* to select between the data gridding methods, the OCaml API uses - PL_GRID_*. + where a C function such as <literal>plcol0</literal> requires a single + integer argument, there is a corresponding OCaml function also called + <literal>plcol0</literal> which also requires a single integer + argument. (<literal>plcol0</literal> happens to set the drawing color + using a number which is associated with a set of colors). Various + constants from the C API are also included here as OCaml variant types + with a <literal>PL_</literal> prefix to avoid namespace clashes when + the <literal>Plplot</literal> module is opened. For example, where + the C PLplot API uses <literal>GRID_*</literal> to select between the + data gridding methods, the OCaml API uses + <literal>PL_GRID_*</literal>. </para> </sect2> <sect2 id="ocaml_specific"> @@ -110,14 +113,17 @@ to keep the interface between C and OCaml as simple as possible. Rather than passing transformation functions directly to each PLplot function which supports a coordinate transformation, the coordinate - tranform functions are set globally using the plset_pltr and - plset_mapform functions. Similarly, the functions plunset_pltr and - plunset_mapform can be used to clear the globally defined coordinate - transformation function. Note that the transform functions are only - used in the functions which support them in the C API (ex. plmap)- - they are not automatically applied to plotted data in other function - calls (ex. plline). For demonstrations of their use, see OCaml PLplot - examples 16 and 20 for plset_pltr and example 19 for plset_mapform. + transform functions are set globally using the + <literal>plset_pltr</literal> and <literal>plset_mapform</literal> + functions. Similarly, the functions <literal>plunset_pltr</literal> + and <literal>plunset_mapform</literal> can be used to clear the + globally defined coordinate transformation function. Note that the + transform functions are only used in the functions which support them + in the C API (ex. <literal>plmap</literal>)- they are not + automatically applied to plotted data in other function calls (ex. + <literal>plline</literal>). For demonstrations of their use, see + OCaml PLplot examples 16 and 20 for <literal>plset_pltr</literal> and + example 19 for <literal>plset_mapform</literal>. </para> </sect2> <sect2 id="ocaml_high_level"> @@ -125,11 +131,11 @@ <para> In addition to the core PLplot API, the OCaml bindings provide two modules which provide a more OCaml-like interface: - <command>Plplot.Plot</command> and - <command>Plplot.Quick_plot</command>. <command>Plplot.Plot</command> - provides a simlified naming scheme for plotting functions, as well as + <literal>Plplot.Plot</literal> and + <literal>Plplot.Quick_plot</literal>. <literal>Plplot.Plot</literal> + provides a simplified naming scheme for plotting functions, as well as the means to more easily track multiple plot streams at once. - <command>Plplot.Quick_plot</command> provides functions to quickly + <literal>Plplot.Quick_plot</literal> provides functions to quickly plot points, lines, data arrays (images) and functions without the need for any plot setup or boilerplate. </para> @@ -194,12 +200,12 @@ findlib </ulink> and its associated tools (ie., ocamlfind) are installed in in your - <command>$PATH</command>. + <literal>$PATH</literal>. </para> <para> If PLplot was installed under a non-standard prefix, or any prefix where findlib does not check automatically for OCaml libraries, then - the following enviroment variables can be set to tell findlib where to + the following environment variables can be set to tell findlib where to look for PLplot: </para> <programlisting> @@ -240,7 +246,7 @@ let () = simple_example () </programlisting> <para> - Save this code as <command>simple_example_core.ml</command>. The + Save this code as <literal>simple_example_core.ml</literal>. The following command can then be used to build the example: </para> <programlisting> @@ -248,7 +254,7 @@ </programlisting> <para> The resulting binary program can be run by typing - <command>./simple_example_core</command> + <literal>./simple_example_core</literal> </para> </sect2> <sect2 id="ocaml_command_line_sample_project_ocaml"> @@ -283,7 +289,7 @@ let () = simple_example () </programlisting> <para> - Save this code as <command>simple_example_ocaml.ml</command>. The + Save this code as <literal>simple_example_ocaml.ml</literal>. The following command can then be used to build the example: </para> <programlisting> @@ -291,22 +297,22 @@ </programlisting> <para> The resulting binary program can be run by typing - <command>./simple_example_ocaml</command> + <literal>./simple_example_ocaml</literal> </para> </sect2> <sect2 id="ocaml_toplevel_sample_project"> <title>Sample toplevel project</title> <para> - The OCaml interactive toplevel (<command>ocaml</command>) provides a + The OCaml interactive toplevel (<literal>ocaml</literal>) provides a very useful tool for code testing, development and interactive data analysis. </para> <para> - The Quick_plot module provides a set of functions for producing quick, - simple two-dimensional plots from both the toplevel and stand-alone - OCaml programs. Here is a set of commands which can be used in a - toplevel session to produce a plot of a portion of a parabola, similar - to the compiled examples above. + The <literal>Quick_plot</literal> module provides a set of functions + for producing quick, simple two-dimensional plots from both the + toplevel and stand-alone OCaml programs. Here is a set of commands + which can be used in a toplevel session to produce a plot of a portion + of a parabola, similar to the compiled examples above. </para> <programlisting> # #use "topfind";; @@ -315,14 +321,14 @@ # Quick_plot.func ~names:["Parabola"] [(fun x -> x ** 2.0)] (-10.0, 10.0);; </programlisting> <para> - Conversely, the above <command>ocaml</command> session could be + Conversely, the above <literal>ocaml</literal> session could be expressed in a compiled OCaml program: </para> <programlisting> Plplot.Quick_plot.func ~names:["Parabola"] [(fun x -> x ** 2.0)] (-10.0, 10.0) </programlisting> <para> - Save this code as <command>simple_example_quick.ml</command>. The + Save this code as <literal>simple_example_quick.ml</literal>. The following command can then be used to build the example: </para> <programlisting> @@ -330,7 +336,7 @@ </programlisting> <para> The resulting binary program can be run by typing - <command>./simple_example_quick</command> + <literal>./simple_example_quick</literal> </para> </sect2> </sect1> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <hez...@us...> - 2009-10-05 21:39:38
|
Revision: 10516 http://plplot.svn.sourceforge.net/plplot/?rev=10516&view=rev Author: hezekiahcarty Date: 2009-10-05 21:39:29 +0000 (Mon, 05 Oct 2009) Log Message: ----------- Update OCaml tutorial in documentation to reflect recent API changes Modified Paths: -------------- trunk/doc/docbook/src/ocaml.xml Modified: trunk/doc/docbook/src/ocaml.xml =================================================================== --- trunk/doc/docbook/src/ocaml.xml 2009-10-05 21:13:09 UTC (rev 10515) +++ trunk/doc/docbook/src/ocaml.xml 2009-10-05 21:39:29 UTC (rev 10516) @@ -276,14 +276,16 @@ let simple_example () = (* Initialize a new plot, using the windowed Cairo device ("xcairo") *) - let p = P.init (-10.0) 10.0 0.0 100.0 P.Greedy (P.Window P.Cairo) in + let p = + P.init (-10.0, 0.0) (10.0, 100.0) P.Greedy (P.Window P.Cairo) + in (* Draw the parabola *) P.plot ~stream:p [P.func P.Blue (fun x -> x ** 2.0) (-10.0, 10.0)]; (* Draw the plot axes and close up the plot stream using the default spacing between tick marks. *) - P.finish ~stream:p 0.0 0.0; + P.finish ~stream:p (); () let () = simple_example () This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |