Index: ossp-pkg/val/val.pod
RCS File: /v/ossp/cvs/ossp-pkg/val/val.pod,v
rcsdiff -q -kk '-r1.14' '-r1.15' -u '/v/ossp/cvs/ossp-pkg/val/val.pod,v' 2>/dev/null
--- val.pod	2003/02/17 13:49:39	1.14
+++ val.pod	2003/02/17 14:27:40	1.15
@@ -32,7 +32,7 @@
 
 =head1 NAME
 
-B<OSSP val> - Value Access Library
+B<OSSP val> - Value Access
 
 =head1 SYNOPSIS
 
@@ -88,17 +88,21 @@
 
 In general, this is used for accessing ISO-C variables without having to
 know the actual symbol/address. The typical use cases are in combination
-with flexible configuration parsing and supporting loosly-coupled
+with flexible configuration parsing and supporting loosely-coupled
 DSO-based module architectures.
 
 =head1 STRUCTURED NAMES
 
-Whenever the APIs calls for a name, it supports structured names where
+Whenever the API calls for a name, it supports structured names where
 elements are separated by a dot. It is assumed that the leading elements
 are references to other C<val_t> structures and only the very last
 element is a reference to an actual variable.
 
-=head1 API CONSTANTS
+=head1 APPLICATION PROGRAMMING INTERFACE (API)
+
+=head2 API CONSTANTS
+
+The following constants exist in the B<OSSP val> API:
 
 =over 4
 
@@ -111,13 +115,15 @@
 
 Type of value when registering a variable using B<val_reg>() or querying
 for the type using B<val_query>(). Most are self-explanatory because
-directly correspond to the basic C data types. C<VAL_TYPE_VAL> is used
+directly correspond to the basic ISO-C data types. C<VAL_TYPE_VAL> is used
 to mount a C<val_t> structure into an existing C<val_t> structure to
 support structured names (see example section for details).
 
-The following particular types exist: C<VAL_TYPE_VAL>, C<VAL_TYPE_PTR>,
-C<VAL_TYPE_CHAR>, C<VAL_TYPE_SHORT>, C<VAL_TYPE_INT>, C<VAL_TYPE_LONG>,
-C<VAL_TYPE_FLOAT>, C<VAL_TYPE_DOUBLE>
+The following particular types exist: C<VAL_TYPE_VAL> (C<val_t
+*>), C<VAL_TYPE_PTR> (C<void *>), C<VAL_TYPE_CHAR> (C<char>),
+C<VAL_TYPE_SHORT> (C<short int>), C<VAL_TYPE_INT> (C<int>),
+C<VAL_TYPE_LONG> (C<long int>), C<VAL_TYPE_FLOAT> (C<float>),
+C<VAL_TYPE_DOUBLE> (C<double float>).
 
 =item C<VAL_OK>, C<VAL_ERR_>I<ID>
 
@@ -134,7 +140,9 @@
 
 =back
 
-=head1 API DATA TYPES
+=head2 API DATA TYPES
+
+The following data types exist in the B<OSSP val> API:
 
 =over 4
 
@@ -154,17 +162,20 @@
 
 =back
 
-=head1 API FUNCTIONS
+=head2 API FUNCTIONS
+
+The following functions exist in the B<OSSP val> API:
 
 =over 4
 
 =item val_rc_t B<val_create>(val_t **I<pval>);
 
-Creates a new value structure and updates the given pointer to reference it.
+Creates a new value access structure and updates the given pointer
+I<pval> to reference it.
 
 =item val_rc_t B<val_destroy>(val_t *I<val>);
 
-Destroys a I<val> structure.
+Destroys the value access structure referenced by I<val>.
 
 =item val_rc_t B<val_reg>(val_t *I<val>, const char *I<name>, int I<type>, const char *I<desc>, void *I<storage>);
 
@@ -173,21 +184,21 @@
 queried through B<val_query>() and is also passed to the callback of
 B<val_apply>(). The value that belongs to the given I<name> is expected
 to be found at I<storage>. Passing C<NULL> as I<storage> will create
-an internal data storage in I<val> so it can only be access through
+an internal data storage in I<val> so it can only be accessed through
 B<val_get>(), B<val_set>() or after the actual storage address was
 queried using B<val_query>().
 
 =item val_rc_t B<val_unreg>(val_t *I<val>, const char *I<name>);
 
-Unregisters the value under I<name> in I<val>.
+Unregisters the value under I<name> from I<val>.
 
 =item val_rc_t B<val_query>(val_t *I<val>, const char *I<name>, int *I<ptype>, char **I<pdesc>, void **I<pstorage>);
 
 Queries a value I<name> in I<val> and returns its type, description and
-storage address. All of I<ptype>, I<pdesc> and I<pstorage> are optional and
-C<NULL> can be passed in if this information is not needed. Passing C<NULL> to
-all query result pointers just checks for existence of the value I<name> in
-I<val>.
+storage address. All of I<ptype>, I<pdesc> and I<pstorage> are optional
+and C<NULL> can be passed in if this information is not needed. Passing
+C<NULL> to all query result pointers just checks for existence of the
+value I<name> in I<val>.
 
 =item val_rc_t B<val_set>(val_t *I<val>, const char *I<name>, ...);
 
@@ -196,21 +207,22 @@
 Unless the actual storage address was queried using B<val_query>() this
 operation is mandatory for internally stored data. If external storage
 is used, not the value but a pointer to it is stored in the library, so
-the value is allowed to be be modified without notice to the library.
+the value is allowed to be be modified without explicit notice to the
+library.
 
 =item val_rc_t B<val_get>(val_t *I<val>, const char *I<name>, ...);
 
-Gets the value I<name> in I<val> and stores it whereever the passed variable
+Gets the value I<name> in I<val> and stores it wherever the passed variable
 argument points to. The storage location is expected to be of the I<type>
 specified at B<val_reg>() time.
 
 =item val_rc_t B<val_vset>(val_t *I<val>, const char *I<name>, va_list I<ap>);
 
-Exactly like B<val_set>() but uses a C<va_list>.
+Exactly like B<val_set>() but uses a C<va_list> for the variable arguments.
 
 =item val_rc_t B<val_vget>(val_t *I<val>, const char *I<name>, va_list I<ap>);
 
-Exactly like B<val_get>() but uses a C<va_list>.
+Exactly like B<val_get>() but uses a C<va_list> for the variable arguments.
 
 =item val_rc_t B<val_apply>(val_t *I<val>, const char *I<name>, int I<depth>, val_cb_t I<cb>, void *I<ctx>);
 
@@ -338,12 +350,15 @@
 
 =head1 HISTORY
 
-B<OSSP val> was invented in January 2002 by Thomas Lotterer and Ralf S.
-Engelschall for use with the B<OSSP lmtp2nntp> project.
+B<OSSP val> was invented in January 2002 by Thomas Lotterer
+E<lt>thomas@lotterer.netE<gt> and Ralf S. Engelschall
+E<lt>rse@engelschall.comE<gt> for use in the B<OSSP> project. Its
+creation was prompted by the requirement to locate values for B<OSSP
+var> based expansions in B<OSSP lmtp2nntp>.
 
 =head1 AUTHORS
 
- Thomas Lotterer     <thomas.lotterer@cw.com>
+ Thomas Lotterer     <thomas@lotterer.net>
  Ralf S. Engelschall <rse@engelschall.com>
 
 =cut