Updated to produce ~correct documentation

1 files changed, 88 insertions, 63 deletions

diff --git a/utils/doc.main b/utils/doc.main
index 2c708f3..364a939 100644
--- a/utils/doc.main
+++ b/utils/doc.main
@@ -7,14 +7,24 @@
  *	Laboratoire de Recherche en Informatique (LRI)
  *	Centre d'Etudes de la Navigation Aerienne (CENA)
  *
- *	documentation skeleton - to be updated
+ *	documentation skeleton
  *
  *	$Id$
  *	$CurLog$
  */
 
-\namedoc{Ccu}
+\documentstyle[11pt,mydoc,twoside]{doc}
+
+\pagestyle{ENTETE}
+\makeindex
+
 \def\utils{CCU}
+\namedoc{CENA C++ Utilities}
+
+\begin{document}
+\maketitle
+\cleardoublepage
+\tableofcontents
 
 \input{psfig}
 \chapter{Introduction}
@@ -29,13 +39,13 @@ This memory manager is well suited for the management of fixed size objects.
 
 \item dynamic arrays.
 
-\item a linked list package, with dynamic allocation of list cells.
+\item linked lists, with dynamic allocation of list cells.
 These lists are designed for the simple management of sets of any kind of elements in a 
 linked form, without node sharing.
 There are two classes, for single and double linked lists.
 This package also provides list-based implementations of stacks and queues.
 
-\item a hash table package.
+\item hash tables.
 Hash tables can be used for building associative arrays.
 Users can define their own hashing function.
 A derived class is also provided: it offers ready-to-use association tables
@@ -43,23 +53,23 @@ with strings as keys, i.e. dictionaries.
 
 \item a signal handling package, which makes it possible to disable or handle signals.
 
-\item a time package. Two classes
+\item a time handling package. Two classes
 implement time stamps and wall clocks. Another class, based on the {\it UNIX BSD\/} interval
 timer, implements alarm clocks and timers.
 
-\item a basic string package.
-It is designed in order to avoid many \typ{(char *)} manipulations when using strings.
+%\item a basic string package.
+%It is designed in order to avoid many \typ{(char *)} manipulations when using strings.
 
 \item a search path package, which mimics and generalizes the
 \com{PATH} environment variable of {\it UNIX}.
 
+\item a regular expression package, that encacpuslates the regular expressions
+from the C library.
+
 \item {\em smart pointers}.
 Smart pointers are more secure than usual pointers because they manage a reference
 count of the pointed to data. This makes it easy to manage shared data structures.
 
-\item a regular expression package, that encacpuslates the regular expressions
-from the C library.
-
 \end{itemize}
 
 \section{Using \utils}
@@ -72,12 +82,12 @@ from the C library.
   classes, functions and constants provided by \utils. 
 
   \item
-  the directory \com{ccu} contains headers 
+  the directory \com{ccu}, which contains headers for the different packages of CCU.
 
   \item
   \samepage 
-  {the archive file \com{libCcu.a}, which is usually instal\-led in \com{/usr/lib} 
-  or in \com{/usr/loc\-al/lib}, contains the library procedures. It must be loaded 
+  {the archive file \com{libCcu.a}, which is usually instal\-led in
+  \com{/usr/loc\-al/lib}, contains the library procedures. It must be loaded 
   with the object files which use \utils. This is usually performed
   by adding the flag \com{-lCcu} in the command line for your C++ compiler. 
   For instance, you can type~:
@@ -147,18 +157,17 @@ by the allocator being used.
 
 \chapter{Lists}
 
-In most languages, you often need to maintain dynamic
-sets of elements. Arrays provide a way to do this, but are inappropriate when 
-these sets vary frequently and randomly, and especially when you need
-to insert new elements at any position.
+In most languages, dynamic sets of elements are often needed.
+Arrays provide a way to do this, but are inappropriate when 
+these sets vary frequently and randomly, and especially when
+new elements have to be inserted at any position.
 
 The classes \typ{CcuList} and \typ{CcuDList} are designed to manage such sets.
 \typ{CcuList} implements single linked lists, while \typ{CcuDList} implements
 double linked lists.
 
-Elements of a list can be enumerated by an iterator.
-During the enumeration, several operations can be performed on the current element
-of the list.
+Elements of a list can be enumerated by an iterator. The classes \typ{CcuListIter}
+and \typ{CcuDListIter} provide such iterators.
 
 Lists can store objects of different types since the entries of the list are
 of type \typ{void *}.
@@ -199,22 +208,19 @@ The following example illustrates a common usage of lists.
 \chapter{Hash Tables}
 
 
-The following definitions are used by member functions of the class \typ{CcuHashTable},
-and by them only:
-\index{HASH_F}\index{HCP_F}\index{HCMP_F}\index{HENUM_F}\index{HDEL_F}
-\begin{ccode}
-        typedef int     (*HASH_F) (HashItem*, int);
-        typedef pointer (*HCP_F) (HashItem*);
-        typedef int     (*HCMP_F) (HashItem*, HashItem*);
-        typedef int     (*HENUM_F) (HashCell*, HashItem*);
-        typedef void    (*HDEL_F) (HashCell*);
-\end{ccode}
-
 #iclass CcuHashTable
-#class CcuHashCell
-#class CcuDictionnary
-#class CcuHashIter
-
+#iclass CcuHashCell
+\section{Iterating on hash tables}
+#iclass CcuHashCellIter
+#iclass CcuHashIter
+\section{Strings as keys: dictionnaries}
+#iclass CcuDictionnary
+\section{Generic classes}
+#iclass CcuHashTableOf
+#iclass CcuHashCellOf
+#iclass CcuHashCellIterOf
+#iclass CcuHashIterOf
+#iclass CcuDictionnaryOf
 
 \section{Example}
 
@@ -309,7 +315,8 @@ main ()
 \end{ccode}
 
 \chapter{Identifier tables}
-#iclass IdTable
+#iclass CcuIdTable
+#iclass CcuIdIter
 
 \chapter{Signal management}
 
@@ -320,20 +327,27 @@ main ()
 
 \chapter{Time management}
 
-#class CcuTimeStamp
-#class CcuTime
+\section{Measuring time}
+\utils\ provides two classes for measuring time.  The class
+\typ{CcuTimeStamp} provides a mean of dating events with reference to an absolute
+clock (the standard dating scheme of Unix), whereas the class \typ{CcuTime} makes it possible
+to measure time intervals.
 
-#class CcuBaseTimer
-#class CcuTimer
+#iclass CcuTimeStamp
+#iclass CcuTime
 
-\section{Example}
+\section{Timers}
+#iclass CcuCoreTimer
+
+\subsection{Signal-based timers}
+#iclass CcuBaseTimer
+#iclass CcuTimer
+
+\subsection{Example}
 
 This example creates three real time timers: the first one counts seconds,
 the second one counts minutes, and the third one counts three minutes once.
 The third timer stops the two other ones when it expires.
-In this example, the main program waits for the timer to expire.
-In most programs, the timers are used for background tasks, so that
-waiting for a timer is seldom used.
 Section \ref{Queues example} shows another example where a timer is used.
 
 \begin{ccode}
@@ -364,9 +378,19 @@ main ()
     CcuTimer eggs (done, 180000, 0);
     // wait for the eggs ...
     // usual programs do other things meanwhile
+    for (;;)
+        pause ();
 }
 \end{ccode}
 
+\subsection{Deriving new kinds of timers}
+If you have another source of interruptions than signals and
+you want to map timers on it, you will need to derive a new class from
+\typ{CcuCoreTimer}. The derived class must implement the functions
+\fun{StartAlarm} and \fun{StopAlarm}. Its constructor must also provide a timer set
+to the constructor of \typ{CcuCoreTimer}. This timer set will hold all the timers of the
+new class. It will belong to the class \typ{CcuTimerSet}.
+#iclass CcuTimerSet
 
 \chapter{Search paths}
 #class CcuDirPath
@@ -400,6 +424,26 @@ FreeString (file2);    // safe
 FreeString (file3);    // safe (default allocation now TRUE)
 \end{ccode}
 
+\chapter{Regular expressions}
+#class CcuRegExp
+
+\section{Example}
+This procedure matches a string against a regular expression.
+
+\begin{ccode}
+int
+match (const char* exp, const char* s)
+{
+    CcuRegExp re (exp);
+    if (!re.Compile ()) {
+        printf ("Cannot compile expression \"%s\"", exp);
+        return 0;
+    }
+    return re.Match (s);
+}
+\end{ccode}
+
+
 \chapter{Smart pointers}
 The classes described here implement what we call smart pointers.
 
@@ -503,25 +547,6 @@ the end
 However it is called with a smart pointer and its value is assigned to a smart pointer.
 Finally the two object \com{fun} and \com{foo} are deleted when returning from main.
 
-\chapter{Regular expressions}
-#class CcuRegExp
-
-\section{Example}
-This procedure matches a string against a regular expression.
-
-\begin{ccode}
-int
-match (const char* exp, const char* s)
-{
-    CcuRegExp re (exp);
-    if (!re.Compile ()) {
-        printf ("Cannot compile expression \"%s\"", exp);
-        return 0;
-    }
-    return re.Match (s);
-}
-\end{ccode}
-
 \newpage
 
 \appendix