Menu
▾
▴
[Plplot-cvs] SF.net SVN: plplot:[10367] trunk/doc/docbook/src/ocaml.xml
|
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.
|
