Index: /trunk/doc/pslib/psLibSDRS.tex
===================================================================
--- /trunk/doc/pslib/psLibSDRS.tex	(revision 396)
+++ /trunk/doc/pslib/psLibSDRS.tex	(revision 397)
@@ -1,3 +1,3 @@
-%%% $Id: psLibSDRS.tex,v 1.32 2004-04-07 03:26:07 eugene Exp $
+%%% $Id: psLibSDRS.tex,v 1.33 2004-04-08 02:13:17 price Exp $
 \documentclass[panstarrs]{panstarrs}
 
@@ -487,4 +487,38 @@
 
 \tbd{REF}.
+
+\subsubsection{Relation of Memory Management to Structures}
+
+In this document, we specify several C \code{struct}s.  It is expected
+that instances of, for example, \code{struct psMyType} will be
+constructed using \code{psMyTypeAlloc()} calls, and destructed using
+\code{psMyTypeFree()} calls.  The allocator will allocate the required
+memory with \code{psAlloc} and increment the appropriate
+\code{refCounter}.  The destructor will decrement the appropriate
+\code{refCounter} and free the memory with \code{psFree} \emph{if and
+only if} the new value of the \code{refCounter} is zero.
+
+This allows the \code{psMyType} to be imported into the metadata
+(\S\ref{sec:metadata}) without the user worrying about the details of
+the memory allocation/deallocation.  For example:
+
+\begin{verbatim}
+void psFooMetadata(psMetadata *md)
+{
+    psFoo *foo = psFooAlloc();
+    (void) psMetaDataAppend(md, psMetaDataItemAlloc(PS_META_FOO,foo,"Comment","foo.bar"));
+    (void) psFooFree(foo);
+}
+\end{verbatim}
+
+In the above case, \code{foo} is created, stuffed into the metadata,
+and then the programmer follows the rule of ``for every \code{alloc},
+there is an equal and opposite free'' before the function returns.
+However, the metadata needs to carry around the \code{psFoo}, and so
+it is important that \code{psFooFree} does not free the memory for
+\code{foo}, but only decrements its \code{refCounter}.  Hence, at the
+conclusion of the function, the memory pointed to by \code{foo} in the
+course of the function remains allocated, and the corresponding
+\code{refCounter} is 1 (specifically, the reference in the metadata).
 
 \subsection{Tracing and Logging}
@@ -1016,6 +1050,8 @@
 \code{psDlist} may have changed.  The value of \code{where} specifies
 if the specified data item should be placed on the front of the list
-(\code{PS_DLIST_HEAD}), or at the end of the list
-(\code{PS_DLIST_TAIL}).
+(\code{PS_DLIST_HEAD}), at the end of the list (\code{PS_DLIST_TAIL}),
+to add after (\code{PS_DLIST_NEXT}) or before (\code{PS_DLIST_PREV})
+the current element (specified by the iteration cursor), or an index
+that the new \code{data} should inhabit.
 
 A data item may be retrieved from the list with the function:
@@ -2329,4 +2365,5 @@
 
 \subsection{Metadata}
+\label{sec:metadata}
 
 \subsubsection{Conceptual Overview}
@@ -2397,9 +2434,9 @@
 manipulation of the data should be reflected in the metadata where
 appropriate.  This is always an issue of concern.  For example,
-consider an image of dimensions \code{Nx, Ny}.  If a function extracts
-a subraster, it must change the values of \code{Nx, Ny} to match the
+consider an image of dimensions \code{nX, nY}.  If a function extracts
+a subraster, it must change the values of \code{nX, nY} to match the
 new dimensions.  What should it do to the corresponding metadata?
 Clearly, it should change the corresponding value which defines
-\code{Nx, Ny}.  However, it is not quite so simple: there may be other
+\code{nX, nY}.  However, it is not quite so simple: there may be other
 metadata values which depend on those values.  These must also be
 changed appropriately.  What if the metadata element points to a
@@ -2414,14 +2451,14 @@
 image exposure time is a notorious example in astronomy.  Different
 observatories use different header keywords (ie, metadata names) for
-the same concept of the exposure time (EXPTIME, EXPOSURE, OPENTIME,
-INTTIME, etc).  Any system which operates on these metadata needs to
-address the issue of identifying these names.  This issue seems like an
-argument for hardwiring metadata in the structure, but in fact it does
-not present such a strong case.  If the metadata are hardwired, some
-function will still have to know how to interpret the various names to
-populate the structure.  The concept can still be localized with
-generic metadata containers by including abstract metadata names
-within the code which are tied to the various implementations-specific
-metadata names.  
+the same concept of the exposure time (\code{EXPTIME},
+\code{EXPOSURE}, \code{OPENTIME}, \code{INTTIME}, etc).  Any system
+which operates on these metadata needs to address the issue of
+identifying these names.  This issue seems like an argument for
+hardwiring metadata in the structure, but in fact it does not present
+such a strong case.  If the metadata are hardwired, some function will
+still have to know how to interpret the various names to populate the
+structure.  The concept can still be localized with generic metadata
+containers by including abstract metadata names within the code which
+are tied to the various implementations-specific metadata names.
 
 \subsubsection{Metadata Representation}
@@ -2510,10 +2547,20 @@
 \end{verbatim}
 
-The type \code{psMetaDataSet} is a container class for metadata. Note that there are
-in fact \emph{two} representations of the metadata (each \code{psMetaDataItem} appears
-on both).
-
-We are using the standard \PS{} doubly-linked list types
-\code{psDlist} and \code{psHash}.  For example:
+The type \code{psMetaDataSet} is a container class for metadata. Note
+that there are in fact \emph{two} representations of the metadata
+(each \code{psMetaDataItem} appears on both).  The first
+representation employs a doubly-linked list that allows the order of
+the metadata to be preserved (e.g., if FITS headers are read in a
+particular order, they should be written in the same order).  The
+second representation employs a hash table which allows fast look-up
+given a specific metadata keyword.
+
+When we refer to ``metadata'' (especially in the case of images), we
+generally mean a \code{psMetaDataSet}:
+\begin{verbatim}
+typedef psMetaDataSet psMetadata;
+\end{verbatim}
+
+An example of the usage of the metadata APIs is as follows:
 \begin{verbatim}
     for (int i = 0; i < 10; i += 5) {
@@ -2574,9 +2621,11 @@
 \end{verbatim}
 
-It is an unfortunate fact that certain metadata keywords (such as \code{COMMENT} in a FITS header)
-may be repeated with different values.  The \code{psMetaDataAppend} routine is required
-to check that all metadata names are unique unless the type is qualified as \code{PS_META_NON_UNIQUE};
-in this case a unique integer will be added to each name that you specify. In this case,
-you may either delete individual element separately or as a complete set:
+It is an unfortunate fact that certain metadata keywords (such as
+\code{COMMENT} and \code{HISTORY} in a FITS header) may be repeated
+with different values.  The \code{psMetaDataAppend} routine is
+required to check that all metadata names are unique unless the type
+is qualified as \code{PS_META_NON_UNIQUE}; in this case a unique
+integer will be added to each name that you specify. In this case, you
+may either delete individual element separately or as a complete set:
 \begin{verbatim}
 psMetaDataItemFree(psMetaDataRemove(ms, "lang.hello.0"));
@@ -2585,4 +2634,16 @@
 
 \subsubsection{MetaData APIs}
+
+In this section, we explain the metadata APIs more fully.
+
+The allocator for \code{psMetaDataItem} returns a full
+\code{psMetaDataItem} ready for insertion into the
+\code{psMetaDataSet}.  It is important to note that, in order to
+support multiple types, the data being input must be a pointer, even
+if it is a \code{float} or \code{int}, for example.  The name of the
+\code{psMetaDataItem} takes a \code{sprintf} format string, with the
+corresponding arguments following.
+
+Note that the destructor does not 
 
 \begin{verbatim}