Menu
▾
▴
[Plplot-cvs] SF.net SVN: plplot:[9020] trunk/doc/docbook/src
|
From: <and...@us...> - 2008-11-26 18:47:52
|
Revision: 9020
http://plplot.svn.sourceforge.net/plplot/?rev=9020&view=rev
Author: andrewross
Date: 2008-11-26 18:47:40 +0000 (Wed, 26 Nov 2008)
Log Message:
-----------
Update documentation of non-common API functions. Change the api-c.xml
file to include only files intended for external use. Internal
functions are now documented in api-internal.xml. Also document which
languages these non-common API functions are available in.
Newly documented functions include those related command line options
and the usage message. Also include documentation of the PLGraphicsIn
and PLOptionTable structures.
Modified Paths:
--------------
trunk/doc/docbook/src/CMakeLists.txt
trunk/doc/docbook/src/api-c.xml
trunk/doc/docbook/src/plplotdoc.xml.in
trunk/doc/docbook/src/schemas.xml
Added Paths:
-----------
trunk/doc/docbook/src/api-internal.xml
Modified: trunk/doc/docbook/src/CMakeLists.txt
===================================================================
--- trunk/doc/docbook/src/CMakeLists.txt 2008-11-26 08:32:25 UTC (rev 9019)
+++ trunk/doc/docbook/src/CMakeLists.txt 2008-11-26 18:47:40 UTC (rev 9020)
@@ -38,6 +38,7 @@
${CMAKE_CURRENT_SOURCE_DIR}/api-compat.xml
${CMAKE_CURRENT_SOURCE_DIR}/api-fortran77.xml
${CMAKE_CURRENT_SOURCE_DIR}/api-fortran95.xml
+${CMAKE_CURRENT_SOURCE_DIR}/api-internal.xml
${CMAKE_CURRENT_SOURCE_DIR}/api-obsolete.xml
${CMAKE_CURRENT_SOURCE_DIR}/bibliography.xml
${CMAKE_CURRENT_SOURCE_DIR}/c.xml
Modified: trunk/doc/docbook/src/api-c.xml
===================================================================
--- trunk/doc/docbook/src/api-c.xml 2008-11-26 08:32:25 UTC (rev 9019)
+++ trunk/doc/docbook/src/api-c.xml 2008-11-26 18:47:40 UTC (rev 9020)
@@ -40,123 +40,19 @@
<title>The Specialized C API for PLplot</title>
<para>
- The purpose of this chapter is to document the API for every C function
- in PLplot (other than language bindings) that
- is <emphasis>not</emphasis> part of the common API that has already been
- documented in <xref linkend="API"/>.
+ The purpose of this chapter is to document the PLPlot C functions that are
+ currently not part of the common API,
+ either because they are C/C++ specific utility
+ functions (e.g. &plAlloc2dGrid;, &plFree2dGrid;) or because they are not
+ easily implemented in other languages (e.g. &plGetCursor;). Some of these
+ functions are used in the examples and may be helpful for other users of
+ plplot.
</para>
-
<para>
- This chapter is a work that is just starting. There are many C functions
- in the code base that are not part of the common API, and we haven't even
- gotten to the point of listing them all. What gets documented here now
- is whatever C-explicit code we are trying to understand at the time.
+ This chapter also documents some of the data types and structures
+ defined by plplot and used by the functions.
</para>
- <para>
- The functions currently documented here are either C specific utility
- functions (e.g. &plAlloc2dGrid;, &plFree2dGrid;) or internal functions
- which might of use to developers (e.g. &plP_checkdriverinit;). Some of
- the utility functions are also implemented in some other languages (e.g.
- &plGetCursor;).
- </para>
-
- <sect1 id="plP_checkdriverinit" renderas="sect3">
- <title>
- <function>plP_checkdriverinit</function>: Checks to see if any
- of the specified drivers have been initialized
- </title>
-
- <para>
- <funcsynopsis>
- <funcprototype>
- <funcdef>
- <function>plP_checkdriverinit</function>
- </funcdef>
- <paramdef><parameter>list</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </para>
-
- <para> Checks to see if any of the specified drivers have been
- initialized. Function tests a space-delimited list of driver names to
- see how many of the given drivers have been initialized, and how often.
- The return code of the function is: <literal>0</literal> if no matching
- drivers were found to have been initialized; <literal>-1</literal> if
- an error occurred allocating the internal buffer; or, a positive number
- indicating the number of streams encountered that belong to drivers on
- the provided list. This function invokes &plP_getinitdriverlist;
- internally to get a <emphasis>complete</emphasis> list of drivers that have been initialized
- in order to compare with the driver names specified in the argument list
- to &plP_checkdriverinit;.
- </para>
-
- <variablelist>
- <varlistentry>
- <term>
- <parameter>list</parameter>
- (<literal>char *</literal>, input)
- </term>
- <listitem>
- <para>
- Pointer to character string specifying a space-delimited
- list of driver names, e.g., <literal>"bmp jpeg tiff"</literal>.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>
- This function is not used in any examples.
- </para>
-
- </sect1>
-
- <sect1 id="plP_getinitdriverlist" renderas="sect3">
- <title>
- <function>plP_getinitdriverlist</function>: Get the initialized-driver
- list
- </title>
-
- <para>
- <funcsynopsis>
- <funcprototype>
- <funcdef>
- <function>plP_getinitdriverlist</function>
- </funcdef>
- <paramdef><parameter>text_buffer</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </para>
-
- <para> Get the initialized-driver list. Function returns a
- space-delimited list of the currently initialized drivers or streams. If more
- than one stream is using the same driver, then its name will be returned
- more than once. The function can be analogously thought of as also
- returning the names of the active streams. Invoked internally by
- &plP_checkdriverinit;. </para>
-
- <variablelist>
- <varlistentry>
- <term>
- <parameter>text_buffer</parameter>
- (<literal>char *</literal>, output)
- </term>
- <listitem>
- <para>
- Pointer to a user-allocated buffer to hold the result. The user
- must ensure the buffer is big enough to hold the result.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>
- This function is not used in any examples.
- </para>
-
- </sect1>
-
<sect1 id="plabort" renderas="sect3">
<title>
<function>plabort</function>: Error abort
@@ -196,6 +92,10 @@
</variablelist>
<para>
+ This function is currently available in C, f77, f95 and python.
+ </para>
+
+ <para>
This function is used in example 20.
</para>
@@ -257,6 +157,10 @@
</variablelist>
<para>
+ This function is currently available in C, C++, perl and tk.
+ </para>
+
+ <para>
This function is used in examples 8, 9, 11, 14, 16, 20, 21, 22, 28, 30.
</para>
@@ -281,7 +185,7 @@
<para>
This routine is called in case an error is encountered during
execution of a PLplot routine. It prints the error message, tries to
- release allocated resources, calls the handler prvided by &plsexit;
+ release allocated resources, calls the handler provided by &plsexit;
and then exits. If cleanup needs to be done in the driver program
then the user may want to supply his/her own exit handler and pass it
in via &plsexit;. This function should either call &plend; before
@@ -302,6 +206,10 @@
</varlistentry>
</variablelist>
+ <para>
+ This function is currently available in C and ada.
+ </para>
+
<para>
This function is not used in any examples.
</para>
@@ -357,6 +265,10 @@
</variablelist>
<para>
+ This function is currently available in C, C++, perl and tk.
+ </para>
+
+ <para>
This function is used in examples 8, 9, 11, 14, 16, 20, 21, 22, 28, 30.
</para>
@@ -389,11 +301,11 @@
<varlistentry>
<term>
<parameter>gin</parameter>
- (<literal>PLGraphicsIn *</literal>, output)
+ (<literal>&PLGraphicsIn; *</literal>, output)
</term>
<listitem>
<para>
- Pointer to PLGraphicsIn structure which will contain the
+ Pointer to &PLGraphicsIn; structure which will contain the
output. The structure is not allocated by the routine
and must exist before the function is called.
</para>
@@ -401,10 +313,17 @@
</varlistentry>
</variablelist>
+ <para>
+ This function is currently only available with the C, C++, Ocaml,
+ Octave, Perl, Python and Ada language bindings.
+ </para>
+
<para>
This function is used in examples 1 and 20.
</para>
+
+
</sect1>
<sect1 id="plgfile" renderas="sect3">
@@ -441,12 +360,90 @@
</varlistentry>
</variablelist>
+ <para>
+ This function is currently available in C, C++ and Ocaml.
+ </para>
+
<para>
This function is not used in any examples.
</para>
</sect1>
+ <sect1 id="plMergeOpts" renderas="sect3">
+ <title>
+ <function>plMergeOpts</function>: Merge use option table into
+ internal info structure.
+ </title>
+
+ <para>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>
+ <function>plMergeOpts</function>
+ </funcdef>
+ <paramdef><parameter>options</parameter></paramdef>
+ <paramdef><parameter>name</parameter></paramdef>
+ <paramdef><parameter>notes</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </para>
+
+ <para>
+ Merges in a set of user supplied command line options with the
+ internal options table. This allows use options to be used along
+ with the built-in plplot options to set device driver, output file
+ etc. See &plparseopts; for details of how to parse these options in
+ a program.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <parameter>options</parameter>
+ (<literal>PLOptionTable *</literal>, input)
+ </term>
+ <listitem>
+ <para>
+ User option table to merge.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>name</parameter>
+ (<literal>const char *name</literal>, input)
+ </term>
+ <listitem>
+ <para>
+ Label to preface the options in the program help.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>notes</parameter>
+ (<literal>const char **</literal>, input)
+ </term>
+ <listitem>
+ <para>
+ A null-terminated array of notes which appear after
+ the options in the program help.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ This function is currently available in C, C++ and Ocaml.
+ </para>
+
+ <para>
+ This function is used in examples 1, 8, 16, 20 and 21.
+ </para>
+
+ </sect1>
+
<sect1 id="plMinMax2dGrid" renderas="sect3">
<title>
<function>plMinMax2dGrid</function>: Find the minimum and
@@ -510,11 +507,111 @@
</variablelist>
<para>
+ This function is currently available in C, C++, Java, Ocaml
+ and Python.
+ </para>
+
+ <para>
This function is used in examples 8, 11, 20 and 21.
</para>
</sect1>
+ <sect1 id="plOptUsage" renderas="sect3">
+ <title>
+ <function>plOptUsage</function>: Print usage and syntax message.
+ </title>
+
+ <para>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>
+ <function>plOptUsage</function>
+ </funcdef>
+ <paramdef></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </para>
+
+ <para>
+ Prints the usage and syntax message. The message can also be
+ display using the -h command line option. There is a default
+ message describing the default plplot options. The usage
+ message is also modified by &plSetUsage; and &plMergeOpts;.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <parameter>program_string</parameter>
+ (<literal>const char *</literal>, input)
+ </term>
+ <listitem>
+ <para>
+ String to appear as the name of program.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>usage_string</parameter>
+ (<literal>const char *</literal>, input)
+ </term>
+ <listitem>
+ <para>
+ String to appear as the usage text.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ This function is currently available in C, C++, Java, Ocaml, Octave
+ and Python.
+ </para>
+
+ <para>
+ This function is not used in any examples.
+ </para>
+
+ </sect1>
+
+ <sect1 id="plResetOpts" renderas="sect3">
+ <title>
+ <function>plMergeOpts</function>: Reset internal option table
+ info structure.
+ </title>
+
+ <para>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>
+ <function>plResetOpts</function>
+ </funcdef>
+ <paramdef></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </para>
+
+ <para>
+ Resets the internal command line options table to the default
+ builtin value. Any user options added with &plMergeOpts; will be
+ cleared. See &plparseopts; for details of how to parse these
+ options in a program.
+ </para>
+
+ <para>
+ This function is currently available in C, C++, Java, Ocaml and
+ Octave, although it is not much use in Java or Octave since they
+ don't have plMergeOpts.
+ </para>
+
+ <para>
+ This function is not used in any examples.
+ </para>
+
+ </sect1>
+
<sect1 id="plsabort" renderas="sect3">
<title>
<function>plsabort</function>: Set abort handler
@@ -549,12 +646,75 @@
</varlistentry>
</variablelist>
+ <para>
+ This function is currently available in C and Ocaml.
+ </para>
+
<para>
This function is not used in any examples.
</para>
</sect1>
+ <sect1 id="plSetUsage" renderas="sect3">
+ <title>
+ <function>plSetUsage</function>: Set the strings used in usage
+ and syntax messages.
+ </title>
+
+ <para>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>
+ <function>plSetUsage</function>
+ </funcdef>
+ <paramdef><parameter>program_string</parameter></paramdef>
+ <paramdef><parameter>usage_string</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </para>
+
+ <para>
+ Sets the program string and usage string displayed by the command
+ line help option (-h) and by &plOptUsage;.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <parameter>program_string</parameter>
+ (<literal>const char *</literal>, input)
+ </term>
+ <listitem>
+ <para>
+ String to appear as the name of program.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>usage_string</parameter>
+ (<literal>const char *</literal>, input)
+ </term>
+ <listitem>
+ <para>
+ String to appear as the usage text.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ This function is currently available in C, C++, Java, Ocaml, Octave
+ and Python.
+ </para>
+
+ <para>
+ This function is not used in any examples.
+ </para>
+
+ </sect1>
+
<sect1 id="plsexit" renderas="sect3">
<title>
<function>plsexit</function>: Set exit handler
@@ -589,6 +749,10 @@
</varlistentry>
</variablelist>
+ <para>
+ This function is currently available in C, C++ and Ocaml.
+ </para>
+
<para>
This function is not used in any examples.
</para>
@@ -635,6 +799,10 @@
</varlistentry>
</variablelist>
+ <para>
+ This function is currently available in C, C++ and Ocaml.
+ </para>
+
<para>
This function is not used in any examples.
</para>
@@ -729,6 +897,11 @@
</varlistentry>
</variablelist>
+ <para>
+ This function is currently available in C, C++, Ocaml, Perl, Python
+ and Tcl.
+ </para>
+
<para>
This function is not used in any examples.
</para>
@@ -824,6 +997,11 @@
</varlistentry>
</variablelist>
+ <para>
+ This function is currently available in C, C++, Ocaml, Perl, Python
+ and Tcl.
+ </para>
+
<para>
This function is used in examples 9 and 16.
</para>
@@ -920,10 +1098,225 @@
</varlistentry>
</variablelist>
+ <para>
+ This function is currently available in C, C++, Ocaml, Perl, Python
+ and Tcl.
+ </para>
+
<para>
This function is used in example 22.
</para>
</sect1>
+ <sect1 id="PLGraphicsIn" renderas="sect3">
+ <title><structname>PLGraphicsIn</structname>: PLplot Graphics Input structure</title>
+
+ <para>
+ The <structname>PLGraphicsIn</structname> structure is used by
+ &plGetCursor; to return information
+ on the current cursor position and key / button state for
+ interactive drivers. The structure contains the following fields:
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <structfield>type</structfield>
+ (<literal>int</literal>)
+ </term>
+ <listitem>
+ <para>
+ Type of event (currently unused?).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <structfield>state</structfield>
+ (<literal>unsigned int</literal>)
+ </term>
+ <listitem>
+ <para>
+ Key or button mask.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <structfield>keysym</structfield>
+ (<literal>unsigned int</literal>)
+ </term>
+ <listitem>
+ <para>
+ Key selected.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <structfield>button</structfield>
+ (<literal>unsigned int</literal>)
+ </term>
+ <listitem>
+ <para>
+ Mouse button selected.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <structfield>subwindow</structfield>
+ (<literal>PLINT</literal>)
+ </term>
+ <listitem>
+ <para>
+ Subwindow (or subpage / subplot) number.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <structfield>string</structfield>
+ (<literal>char [PL_MAXKEY]</literal>)
+ </term>
+ <listitem>
+ <para>
+ Translated string.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <structfield>pX, pY</structfield>
+ (<literal>int</literal>)
+ </term>
+ <listitem>
+ <para>
+ Absolute device coordinates of pointer.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <structfield>dX, dY</structfield>
+ (<literal>PLFLT</literal>)
+ </term>
+ <listitem>
+ <para>
+ relative device coordinates of pointer.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <structfield>wX, wY</structfield>
+ (<literal>PLFLT</literal>)
+ </term>
+ <listitem>
+ <para>
+ World coordinates of pointer.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </sect1>
+
+ <sect1 id="PLOptionTable" renderas="sect3">
+ <title><structname>PLOptionTable</structname>: PLplot command line options table structure</title>
+
+ <para>
+ The <structname>PLOptionTable</structname> structure is used by
+ &plMergeOpts; to pass information on user-defined command line
+ options to plplot. The structure contains the following fields:
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <structfield>opt</structfield>
+ (<literal>const char*</literal>)
+ </term>
+ <listitem>
+ <para>
+ Name of option.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <structfield>handler</structfield>
+ (<literal>int (*func) (const char *, const char *, void *)</literal>)
+ </term>
+ <listitem>
+ <para>
+ User-defined handler function to be called when option is set. A
+ NULL value indicates that no user-defined handler is required.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <structfield>client_data</structfield>
+ (<literal>void *</literal>)
+ </term>
+ <listitem>
+ <para>
+ Pointer to client data. A
+ NULL value indicates that no client data is required.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <structfield>var</structfield>
+ (<literal>void *</literal>)
+ </term>
+ <listitem>
+ <para>
+ Pointer to variable to set to the value specified on the
+ command line option.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <structfield>mode</structfield>
+ (<literal>long</literal>)
+ </term>
+ <listitem>
+ <para>
+ Type of variable <parameter>var</parameter>. Allowed values
+ are PL_OPT_FUNC, PL_OPT_BOOL, PL_OPT_INT, PL_OPT_FLOAT,
+ PL_OPT_STRING.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <structfield>syntax</structfield>
+ (<literal>const char *</literal>)
+ </term>
+ <listitem>
+ <para>
+ Syntax for option (used in the usage message).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <structfield>desc</structfield>
+ (<literal>const char *</literal>)
+ </term>
+ <listitem>
+ <para>
+ Description of the option (used in the usage message).
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </sect1>
+
</chapter>
Added: trunk/doc/docbook/src/api-internal.xml
===================================================================
--- trunk/doc/docbook/src/api-internal.xml (rev 0)
+++ trunk/doc/docbook/src/api-internal.xml 2008-11-26 18:47:40 UTC (rev 9020)
@@ -0,0 +1,147 @@
+<!-- -*- mode: nxml -*- -->
+<!--
+ api-internal.xml: "Internal C function in PLplot" chapter
+
+Copyright (C) 1994 Geoffrey Furnish and Maurice LeBrun
+Copyright (C) 1999, 2000, 2001, 2002, 2003 Alan W. Irwin
+Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004 Rafael Laboissiere
+Copyright (C) 2003 Joao Cardoso
+Copyright (C) 2008 Andrew Ross
+
+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="API-Internal">
+ <title>Internal C functions in PLplot</title>
+
+ <para>
+ The purpose of this chapter is to document the API for every internal
+ C function in PLplot (other than language bindings) that
+ is <emphasis>not</emphasis> part of the common API that has already been
+ documented in <xref linkend="API"/> or elsewhere. The functions documented
+ here are internal plplot functions. They are not intended for external use
+ and may change between releases.
+ </para>
+
+ <para>
+ This chapter is a work that is just starting. There are many C functions
+ in the code base that are not part of the common API, and we haven't even
+ gotten to the point of listing them all. What gets documented here now
+ is whatever C-explicit code we are trying to understand at the time.
+ </para>
+
+ <sect1 id="plP_checkdriverinit" renderas="sect3">
+ <title>
+ <function>plP_checkdriverinit</function>: Checks to see if any
+ of the specified drivers have been initialized
+ </title>
+
+ <para>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>
+ <function>plP_checkdriverinit</function>
+ </funcdef>
+ <paramdef><parameter>list</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </para>
+
+ <para> Checks to see if any of the specified drivers have been
+ initialized. Function tests a space-delimited list of driver names to
+ see how many of the given drivers have been initialized, and how often.
+ The return code of the function is: <literal>0</literal> if no matching
+ drivers were found to have been initialized; <literal>-1</literal> if
+ an error occurred allocating the internal buffer; or, a positive number
+ indicating the number of streams encountered that belong to drivers on
+ the provided list. This function invokes &plP_getinitdriverlist;
+ internally to get a <emphasis>complete</emphasis> list of drivers that have been initialized
+ in order to compare with the driver names specified in the argument list
+ to &plP_checkdriverinit;.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <parameter>list</parameter>
+ (<literal>char *</literal>, input)
+ </term>
+ <listitem>
+ <para>
+ Pointer to character string specifying a space-delimited
+ list of driver names, e.g., <literal>"bmp jpeg tiff"</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </sect1>
+
+ <sect1 id="plP_getinitdriverlist" renderas="sect3">
+ <title>
+ <function>plP_getinitdriverlist</function>: Get the initialized-driver
+ list
+ </title>
+
+ <para>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>
+ <function>plP_getinitdriverlist</function>
+ </funcdef>
+ <paramdef><parameter>text_buffer</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </para>
+
+ <para> Get the initialized-driver list. Function returns a
+ space-delimited list of the currently initialized drivers or streams. If more
+ than one stream is using the same driver, then its name will be returned
+ more than once. The function can be analogously thought of as also
+ returning the names of the active streams. Invoked internally by
+ &plP_checkdriverinit;. </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <parameter>text_buffer</parameter>
+ (<literal>char *</literal>, output)
+ </term>
+ <listitem>
+ <para>
+ Pointer to a user-allocated buffer to hold the result. The user
+ must ensure the buffer is big enough to hold the result.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </sect1>
+
+
+</chapter>
Modified: trunk/doc/docbook/src/plplotdoc.xml.in
===================================================================
--- trunk/doc/docbook/src/plplotdoc.xml.in 2008-11-26 08:32:25 UTC (rev 9019)
+++ trunk/doc/docbook/src/plplotdoc.xml.in 2008-11-26 18:47:40 UTC (rev 9020)
@@ -67,6 +67,7 @@
<!ENTITY chap-api-fortran77 SYSTEM "api-fortran77.xml">
<!ENTITY chap-api-compat SYSTEM "api-compat.xml">
<!ENTITY chap-api-obsolete SYSTEM "api-obsolete.xml">
+<!ENTITY chap-api-internal SYSTEM "api-internal.xml">
<!ENTITY plplot-symbols SYSTEM "plplot-symbols.txt">
<!ENTITY plplot-structs SYSTEM "plplot-structs.txt">
<!ENTITY chap-os-notes SYSTEM "os_notes.xml">
@@ -144,12 +145,14 @@
<!ENTITY plline '<link linkend="plline"><function>plline</function></link>'>
<!ENTITY plline3 '<link linkend="plline3"><function>plline3</function></link>'>
<!ENTITY pllsty '<link linkend="pllsty"><function>pllsty</function></link>'>
+<!ENTITY plMergeOpts '<link linkend="plMergeOpts"><function>plMergeOpts</function></link>'>
<!ENTITY plmesh '<link linkend="plmesh"><function>plmesh</function></link>'>
<!ENTITY plmeshc '<link linkend="plmeshc"><function>plmeshc</function></link>'>
<!ENTITY plmeshfortran95 '<link linkend="plmeshfortran95"><function>plmeshfortran95</function></link>'>
<!ENTITY plmeshfortran77 '<link linkend="plmeshfortran77"><function>plmeshfortran77</function></link>'>
<!ENTITY plmkstrm '<link linkend="plmkstrm"><function>plmkstrm</function></link>'>
<!ENTITY plmtex '<link linkend="plmtex"><function>plmtex</function></link>'>
+<!ENTITY plOptUsage '<link linkend="plOptUsage"><function>plOptUsage</function></link>'>
<!ENTITY plot3d '<link linkend="plot3d"><function>plot3d</function></link>'>
<!ENTITY plot3dc '<link linkend="plot3dc"><function>plot3dc</function></link>'>
<!ENTITY plot3dfortran95 '<link linkend="plot3dfortran95"><function>plot3dfortran95</function></link>'>
@@ -165,6 +168,7 @@
<!ENTITY plpsty '<link linkend="plpsty"><function>plpsty</function></link>'>
<!ENTITY plptex '<link linkend="plptex"><function>plptex</function></link>'>
<!ENTITY plreplot '<link linkend="plreplot"><function>plreplot</function></link>'>
+<!ENTITY plResetOpts '<link linkend="plResetOpts"><function>plResetOpts</function></link>'>
<!ENTITY plrgbhls '<link linkend="plrgbhls"><function>plrgbhls</function></link>'>
<!ENTITY plsabort '<link linkend="plsabort"><function>plsabort</function></link>'>
<!ENTITY plschr '<link linkend="plschr"><function>plschr</function></link>'>
@@ -187,6 +191,7 @@
<!ENTITY plsescfortran95 '<link linkend="plsescfortran95"><function>plsescfortran95</function></link>'>
<!ENTITY plsescfortran77 '<link linkend="plsescfortran77"><function>plsescfortran77</function></link>'>
<!ENTITY plsetopt '<link linkend="plsetopt"><function>plsetopt</function></link>'>
+<!ENTITY plSetUsage '<link linkend="plSetUsage"><function>plSetUsage</function></link>'>
<!ENTITY plsexit '<link linkend="plsexit"><function>plsexit</function></link>'>
<!ENTITY plsfam '<link linkend="plsfam"><function>plsfam</function></link>'>
<!ENTITY plsfci '<link linkend="plsfci"><function>plsfci</function></link>'>
@@ -233,6 +238,7 @@
<!ENTITY plw3d '<link linkend="plw3d"><function>plw3d</function></link>'>
<!ENTITY plwid '<link linkend="plwid"><function>plwid</function></link>'>
<!ENTITY plwind '<link linkend="plwind"><function>plwind</function></link>'>
+<!ENTITY PLGraphicsIn '<link linkend="PLGraphicsIn"><function>PLGraphicsIn</function></link>'>
<!ENTITY PLplot-website '@PLPLOT_WEBSITE@'>
<!ENTITY % Math-Entities SYSTEM "math.ent">
%Math-Entities;
@@ -297,7 +303,7 @@
<holder>Andrew Roach</holder>
</copyright>
<copyright>
- <year>2004</year>
+ <year>2004,2008</year>
<holder>Andrew Ross</holder>
</copyright>
<copyright>
@@ -397,6 +403,7 @@
&chap-api-fortran77;
&chap-api-compat;
&chap-api-obsolete;
+ &chap-api-internal;
&chap-os-notes;
</part>
Modified: trunk/doc/docbook/src/schemas.xml
===================================================================
--- trunk/doc/docbook/src/schemas.xml 2008-11-26 08:32:25 UTC (rev 9019)
+++ trunk/doc/docbook/src/schemas.xml 2008-11-26 18:47:40 UTC (rev 9020)
@@ -7,6 +7,7 @@
<uri resource="api-compat.xml" typeId="DocBook"/>
<uri resource="api-fortran77.xml" typeId="DocBook"/>
<uri resource="api-fortran95.xml" typeId="DocBook"/>
+ <uri resource="api-internal.xml" typeId="DocBook"/>
<uri resource="api-obsolete.xml" typeId="DocBook"/>
<uri resource="api.xml" typeId="DocBook"/>
<uri resource="bibliography.xml" typeId="DocBook"/>
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
