Index: /trunk/doc/draft/utils.tex
===================================================================
--- /trunk/doc/draft/utils.tex	(revision 258)
+++ /trunk/doc/draft/utils.tex	(revision 259)
@@ -185,4 +185,10 @@
   and \code{free}.
   
+\item
+  The file \file{psMemory.h} shall take steps to ensure that
+  code calling the functions \code{malloc}, \code{calloc}, \code{realloc},
+  or \code{free} shall not compile (\eg{} \code{#define malloc(S) for})
+  unless the symbol \code{PS_ALLOC_MALLOC} is defined.
+
 \item
   In all cases, application code will call
@@ -425,4 +431,7 @@
 that must be collected and saved, even in the production system.
 
+We envision that we will make extensive use of \code{psTrace} throughout
+the \PS{} code.
+
 \subsection{Tracing APIs}
 \hlabel{psTrace}
@@ -521,52 +530,68 @@
 For example, after the commands:
 \begin{verbatim}
-    psSetTraceLevel("aaa.bbb.ccc.ddd", 9);
-    psSetTraceLevel("aaa.bbb.ccc", 3);
-    psSetTraceLevel("aaa.bbb.ddd", 4);
-    psSetTraceLevel("aaa.BBB", 2);
-    psSetTraceLevel("BBB", 2);
-    psSetTraceLevel("BBB.XXX.YYY.ZZZ", 5);
-    psSetTraceLevel("aaa.bbb", 2);
-    psSetTraceLevel("aaa.bbb.ccc", 9);
-    psSetTraceLevel("aaa", 1);
+    psSetTraceLevel("utils.dlist.add.head", 9);
+    psSetTraceLevel("utils.dlist.add", 3);
+    psSetTraceLevel("utils.dlist.remove", 4);
+    psSetTraceLevel("coadd", 2);
+    psSetTraceLevel("coadd.CR.remove.morphology", 5);
+    psSetTraceLevel("utils.hash", 2);
+    psSetTraceLevel("utils.dlist.add", 9);
+    psSetTraceLevel("utils", 1);
 \end{verbatim}
 the command \code{psPrintTraceLevels()} should print:
 \begin{verbatim}
 (root)               0
- aaa                 1
-  bbb                2
-   ccc               9
-    ddd              9
-   ddd               4
-  BBB                2
- BBB                 2
-  XXX                .
-   YYY               .
-    ZZZ              5
-\end{verbatim}
+ utils               1
+  hash               2
+  dlist              .
+   remove            4
+   add               9
+    head             9
+ coadd               2
+  CR                 .
+   remove            .
+    morphology       5
+\end{verbatim}
+where \code{.} means that the trace level should be inherited from its parent.
 
 After this set of \code{psSetTraceLevel} commands, and if
 \code{PS_NTRACE} is not defined, the following commands
 \begin{verbatim}
-    psTrace("aaa.bbb.ddd", 2, "(aaa.bbb.ddd) Hello %s\n", "world");
-    psTrace("aaa", 2, "aaa\n");
-    psTrace("", 2, "\"\"\n");
-    psTrace("aaa.bbb", 2, "aaa.bbb\n");
-    psTrace("aaa.bbb.ddd", 2, "aaa.bbb.ddd\n");
-    psTrace("aaa.bbb.ddd", 4, "aaa.bbb.ddd\n");
-    psTrace("aaa.bbb.ddd", 2, "aaa.bbb.ddd\n");
-    psTrace("aaa.bbb.ccc", 1, "aaa.bbb.ccc\n");
-    psTrace("aaa.bbb.eee", 2, "aaa.bbb.eee\n");
+    psTrace("utils.dlist.remove", 2, "Removing psDList key \"%s\"\n", "my_key");
+    psTrace("utils", 2, "Initialising utilities library\n");
+    psTrace("", 2, "This is turned on by trace component \"\"");
+    psTrace("utils.dlist", 2, "Initialising psDList\n");
+    psTrace("utils.dlist.remove", 4, "Removing psDList key \"%s\" (value: \"%d\")\n", "my_key", 12345);
+    psTrace("utils.hash.remove", 4, "Removing hash key \"%s\" (value: \"%d\")\n", "my_key", 12345);
+    psTrace("utils.dlist.add", 1, "Adding psDList key \"%s\"\n", "your_key");
+    psTrace("utils.dlist.find", 2, "Looking up psDList key \"%s\"\n", "some_key");
+    psTrace("coadd.CR.remove", 4, "Removing CRs\n");
+    psTrace("coadd.CR.remove.morphology", 4, "CRs are not fuzzy\n");
 \end{verbatim}
 should produce this output:
 \begin{verbatim}
-  (aaa.bbb.ddd) Hello world
-  aaa.bbb
-  aaa.bbb.ddd
-    aaa.bbb.ddd
-  aaa.bbb.ddd
- aaa.bbb.ccc
-  aaa.bbb.eee
-\end{verbatim}
+  Removing psDList key "my_key"
+    Removing psDList key "my_key" (value: "12345")
+ Adding psDList key "your_key"
+    CRs are not fuzzy
+\end{verbatim}
+
+Note that
+\begin{description}
+\item
+  \code{utils.dlist} messages are at level 1, inherited from \code{utils}, so the
+  \code{Initialising utilities library}, \code{Initialising psDList}, and
+  \code{Looking up psDList key} messages are \emph{not} printed (the traces are at level 2).
+
+\item
+  \code{utils.dlist.remove} messages are at level 4, and are printed.
+
+\item
+  \code{utils.hash} messages are at level 2, and are not printed (the traces are at level 4)
+
+\item
+  \code{coadd.CR.remove} is at level 2 (inherited from \code{coadd}) so \code{Removing CRs}
+  isn't printed.  \code{coadd.CR.remove.morphology} is at level 4, so \code{CRs are not fuzzy} is printed.
+\end{description}
 
 \subsection{Message Logging}