- Updates to the documentation

SKIPPED:
	psi/velodorn.h

doc/programmer/reference.tex

@@ -76,42 +76,76 @@ recommended.
 \end{description}
 
 \subsection{Building SICS}
-This document describes how to build the SICS software and where to find it.
-There are two sections: Building the SICS applications and building the Java
- clients. For both categories tarballs with all necessary files can be
- found in the /data/lnslib/src/sics directory. There are two tar files: 
- sics.tar which contains the sources for the SICS server and additional C or
- F77 applications and java.tar which contains the code for the Java clients.
+A SICS distribution is best be obtained from the cvs
+repository. Access details are available on demand from Mark.Koennecke@psi.ch.
+A source distribution can be downloaded with:
+\begin{verbatim}
+cvs checkout sics
+\end{verbatim}
+This creates a new directory, sics, and copies a lot of files.
 
-\subsubsection{Building the SICS Server and Applications}
-The first step is to untar the sics.tar file. As a result a directory sics 
- with several subdirectories will be created. These subdirectories are:
+\subsubsection{SICS Directory Layout}
+Underneath the sics directory there are further sub directories:
 \begin{description}
-\item[psi]PSI specific commands and code. 
-\item[hardsup] contains David Madens and other hardware drivers.
-\item[motor] contains the unix version of David Madens el734\_test program.
-\item[doc/programmer]holds programming documentation for SICS. 
-\item[doc/user] The html sources for the user documentation. Also everything 
- necessary for creating the printed documentation.
-\item[bin] Holds the final binary files.
-\item[tcl] Some Tcl helper code.
-\item[doc/manager]The SICS managers documentation.
-\item[difrac] The DIFRAC four circle diffraction subsystem. This is
-not used anymore.  
-\item[matrix] A matrix manipulation package.
-\end{description}   
-For most programs makefiles are provided. 
- Makefiles may need a little editing to correct the location of libraries. 
- All necessary headers should be available in /data/lnslib/include and the
- libraries in /data/lnslib/lib.
-Building things within this hierarchy basically require to steps:
-\begin{enumerate}
-\item cd into the hardsup and difrac directories and type make in 
-each. This builds required libraries for linking other applications.
-\item cd into the directory of the program you wish to compile and type make.
-For instance for building the SICServer, move into the main sics directory and
- type make. 
-\end{enumerate}
+\item[doc] Contains documentation. Further subdirectories to doc:
+\begin{description}
+\item[user] User documentation.
+\item[manager] Manager documentation
+\item[programmer] Reference documentation for SICS programmers.
+\end{description}
+\item[matrix]A package for matrix manipulations
+\item[tcl]Tcl scripts
+\item[dummy]An example directory for a new site
+\item[psi]PSI specific parts of SICS
+\begin{description}
+\item[hardsup] Hardware support routines
+\item[sinqhm]The vxWorks histogram memory software
+\item[tecs]The tecs environment control software
+\item[motor]Utilities for the motor controller
+\item[utils]various utilities
+\begin{description}
+\item[check]The Tcl syntax checker for SICS
+\end{description}
+\end{description}
+\end{description}
+The sics directory is meant to contain the generic parts of
+SICS. Then there are site specific directories (dummy, psi) which hold
+code special for particular instruments or hardware. The selection for
+which configuration SICS is being compiled is made in the makefile, by
+linking against the appropriate site specific libraries. 
+
+\subsubsection{SICS Makefiles}
+The SICS makefile system is not perfect but is far better then
+compiling the whole stuff manually. There are various makefiles:
+\begin{description}
+\item[linux\_def, alpha\_def] contains the path to the HDF libraries,
+the flags necessary to run sub makefiles in sub directories etc. This
+is included by all other makefiles. 
+\item[make\_gen] and children contains most of the makefile content and
+is included by the other makefiles.
+\item[makefile\_linux, makefile\_alpha] are makefiles for their
+respective platforms.  
+\end{description}
+Some editing of makefiles will always be necessary. The path to the
+HDF libraries has usually to be adapted in the \_def files. If there
+is a different platfrom a new makefile has to be cloned from the
+existing ones. In order to support a new site a new make\_gen and a new
+makefile are have to be cloned. This system is similar in the
+subdirectories to the SICS directory. Once this has been setup typing:
+\begin{verbatim}
+make -f makefile_alpha clean
+\end{verbatim}
+will clean all object files etc. and
+\begin{verbatim}
+make -f makefile_alpha 
+\end{verbatim}
+will build everything. May be you need to replace alpha by linux on
+some platforms. Please note, that I have been to lazy to generate
+dependencies for all the SICS files. This means that if you make
+changes to the major SICS header files (especially the kernel files)
+it is better do recompile everything. Otherwise you might find
+yourself chasing obscure bugs. 
+ 
 
 \subsubsection{Building Java Clients}
 Again the first step is the untaring of tha java.tar file. This creates a
@@ -139,6 +173,10 @@ Again the first step is the untaring of tha java.tar file. This creates a
 \item[amor] The AMOR user interface program.
 \item[tas] The Triple Axis user interface program.
 \item[trics] The TRICS user interface program.
+\item[JQF] A state machine framework used for implementing a new I/O
+system.
+\item[psi] The start of a new hierarchy of SICS applications and
+library classes.
 \end{description} 
 Furthermore there are some Java source file in the main directory together 
  with some htm files and makefiles. For each of the Java clients a makefile