Index: /trunk/gsdl3/docs/manual/manual.tex
===================================================================
--- /trunk/gsdl3/docs/manual/manual.tex	(revision 7825)
+++ /trunk/gsdl3/docs/manual/manual.tex	(revision 7826)
@@ -462,4 +462,6 @@
 
 Once the build process is complete, the building directory should be renamed to index (after deleting or renaming the existing index directory, if any), and Tomcat prompted to reload the collection---either by restarting the server, or by sending an activate collection command to the library servlet.
+
+Summary:
 
 [TODO: need to describe namespaces somewhere? ]
@@ -1011,9 +1013,9 @@
 \subsection{Overview of modules??}
 
-A \gsiii\  'library' system consists of many components: MessageRouter, Receptionist, Actions, Collections, ServiceRacks etc.  Figure~\ref{fig:local} shows how they fit together in a stand-alone system. There is a one-to-one correspondance between modules and Java classes, with the exception of services: for coding and/or run-time efficiency reasons, several Service modules may be grouped together into one ServiceRack class.
+A \gsiii\  'library' system consists of many components: MessageRouter, Receptionist, Actions, Collections, ServiceRacks etc.  Figure~\ref{fig:local} shows how they fit together in a stand-alone system. The top left part is concerned with displaying the data, while the bottom right part is the collection data serving part. The two sides communicate through the MessaegRouter. There is a one-to-one correspondance between modules and Java classes, with the exception of services: for coding and/or run-time efficiency reasons, several Service modules may be grouped together into one ServiceRack class.
 
 \begin{figure}[t]
   \centering
-  \includegraphics[width=4in]{local} %5.8
+  \includegraphics[width=4in]{newlocal} %5.8
   \caption{A simple stand-alone site.}
   \label{fig:local}
@@ -1023,12 +1025,12 @@
 {\em MessageRouter}: this is the central module for a site. It controls the site, loading up all the collections, clusters, communicators needed. All messages pass through the MessageRouter. Communication between remote sites is always done between MessageRouters, one for each site.
 
-{\em Collection and ServiceCluster}: these are very similar. They both provide some metadata about the collection/cluster, and a list of services. The services are provided by ServiceRack objects that the collection/cluster loads up. A Collection is a specific type of ServiceCluster. A ServiceCluster groups services that are related conceptually, e.g. all the building services may be part of a cluster. What is part of a cluster is specified by the site configuration file. A Collection's services are grouped by the fact that they all operate on some common data---the documents in the collection.
+{\em Collection and ServiceCluster}: these are very similar, and group a set of services into a conceptual group.. They both provide some metadata about the collection/cluster, and a list of services. The services are provided by ServiceRack objects that the collection/cluster loads up. A Collection is a specific type of ServiceCluster. A ServiceCluster groups services that are related conceptually, e.g. all the building services may be part of a cluster. What is part of a cluster is specified by the site configuration file. A Collection's services are grouped by the fact that they all operate on some common data---the documents in the collection.
 Functionally Collection and ServiceCluster are very similar, but conceptually, and to the user, they are quite different.
 
-{\em Service}: these provide the core functionality of the system e.g. searching, retrieving documents, building collections etc. One or more may be grouped into a single Java class (ServiceRack) for code reuse, or to avoid instantiating the same objects several times. For example, MGPP searching services all need to have the index loaded into memory. Services provide the core functionality for the system, e.g. searching, retrieving documents, building collections etc.
+{\em Service}: these provide the core functionality of the system e.g. searching, retrieving documents, building collections etc. One or more may be grouped into a single Java class (ServiceRack) for code reuse, or to avoid instantiating the same objects several times. For example, MGPP searching services all need to have the index loaded into memory. 
 
 {\em Communicator/Server}: these facilitate communication between remote modules. For example, if you want MR1 to talk to MR2, you need a Communicator-Server pair. The Server sits on top of MR2, and MR1 talks to the Communicator. Each communication type needs a new pair. So far we have only been using SOAP, so we have a SOAPCommunicator and a SOAPServer.
 
-{\em Receptionist}: this is the point of contact for the 'front end'. Its core functionality involves routing requests to the Actions, but it may do more than that. For example, a Receptionist may: modify the request in some way before sending it to the appropriate Action; add some data to the page responses that is common to all pages; transform the response into another form using XSLT for example. There is a hierarchy of different Receptionist types, which is described in Section~\ref{sec:recepts}.
+{\em Receptionist}: this is the point of contact for the 'front end'. Its core functionality involves routing requests to the Actions, but it may do more than that. For example, a Receptionist may: modify the request in some way before sending it to the appropriate Action; add some data to the page responses that is common to all pages; transform the response into another form using XSLT. There is a hierarchy of different Receptionist types, which is described in Section~\ref{sec:recepts}.
 
 {\em Actions}: these do the job of creating the 'pages'. There is a different action for each type of page, for example PageAction handles semi-static pages, QueryAction handles queries, DocumentAction displays documents. They know a little bit about specific service types. Based on the 'CGI' arguments passed in to them, they construct requests for the system, and put together the responses into data for the page. This data is returned to the Receptionist, which may transform it to HTML. The various actions are described in  more detail in Section~\ref{sec:pagegen}.
@@ -1052,11 +1054,13 @@
 If the Receptionist is a TransformingReceptionist, a mapping between shortnames  and XSLT file names is also created. 
 
-The MessageRouter reads in its site configuration file \gst{siteConfig.xml} (see Section~\ref{sec:siteconfig}). It creates a module map that maps names to objects. This is used for routing the messages. It also keeps small chunks of XML---serviceList, collectionList, clusterList and siteList. These are what get returned in response to a describe request (see Section~\ref{sec:describe}.).
+The MessageRouter reads in its site configuration file \gst{siteConfig.xml} (see Section~\ref{sec:siteconfig}). It creates a module map that maps names to objects. This is used for routing the messages. It also keeps small chunks of XML---serviceList, collectionList, clusterList and siteList. These are part of what get returned in response to a describe request (see Section~\ref{sec:describe}.).
+
 Each ServiceRack specified in the configuration file is created, then queried for its list of services. Each service name is added to the map, pointing to the ServiceRack object. Each service is also added to the serviceList. After this stage, ServiceRacks are transparent to the system, and each service is treated as a separate module.
+
 ServiceClusters are created and passed the \gst{<serviceCluster>} element for configuration. They are added to the map as is, with the cluster name as a key. A serviceCluster is also added to the serviceClusterList.
-For each site specified, the MessageRouter creates an appropriate type of Communicator object. Then it tries to get the site description. If the server for the remote site is up and running, this should  be successful. The site will be added to the mapping with its site name as a key. The site's collections, services and clusters will also be added into the static xml lists. If the server for the remote site is not running, the site will not be included in the siteList or module map. To try again to access the site, either Tomcat must be restarted, or a run-time reconfigure-sites commands must be sent (see Section~\ref{sec:runtime-config}).
-
-The MessageRouter also looks inside the site's \gst{collect} directory, and  loads up a Collection object for each valid collection found.
-
+
+For each site specified, the MessageRouter creates an appropriate type of Communicator object. Then it tries to get the site description. If the server for the remote site is up and running, this should  be successful. The site will be added to the mapping with its site name as a key. The site's collections, services and clusters will also be added into the static xml lists. If the server for the remote site is not running, the site will not be included in the siteList or module map. To try again to access the site, either Tomcat must be restarted, or a run-time reconfigure-site command must be sent (see Section~\ref{sec:runtime-config}).
+
+The MessageRouter also looks inside the site's \gst{collect} directory, and  loads up a Collection object for each valid collection found. If a \gst{collectionInit.xml} file is present, a subclass of Collection may be used.
 The Collection object reads its \gst{buildConfig.xml} and \gst{collectionConfig.xml}
 files, determines the metadata, and loads ServiceRack classes based on the 
@@ -1067,77 +1071,12 @@
 
 There are two types of messages used by the system: external and internal messages. All messages have an enclosing \gst{<message>} element, which contains either one or more requests, or one or more responses. In the following descriptions, the message element is not shown, but is assumed to be present.  
-Action in \gsiii\  is originated by a request coming in from the outside. In the standard web-based \gs\ , this comes from a servlet into the receptionist. This ``external'' type request is a request for a page of data, and contains a representation of the CGI style arguments. A page of XML is returned, which can be in HTML format or other depending on the output parameter to the request. 
-
-Messages inside the system (``internal'' messages) all follow the same basic format: message elements contain multiple request elements, or multiple response elements. Messaging is all synchronous. The same number of responses as requests will be returned. Currently all requests are individual, so any requests can be combined into the same message, and they will be answered separately, with their responses being sent back in a single message.
-
-When a page request comes in to the Receptionist, it looks at the action attribute to determine which action to send it to. The response is returned from the action. The page that the receptionist returns contains the original request, the response from the action and other info as needed (depends on the type of Receptionist). The data may be transformed in some way --- for the servlet \gs\  we transform using XSLT to generate html pages which get returned to the servlet.
+Action in \gsiii\  is originated by a request coming in from the outside. In the standard web-based \gs, this comes from a servlet and is passed into the Receptionist. This ``external'' type request is a request for a page of data, and contains a representation of the CGI style arguments. A page of XML is returned, which can be in HTML format or other depending on the output parameter of the request. 
+
+Messages inside the system (``internal'' messages) all follow the same basic format: message elements contain multiple request elements, or multiple response elements. Messaging is all synchronous. The same number of responses as requests will be returned. Currently all requests are independent, so any requests can be combined into the same message, and they will be answered separately, with their responses being sent back in a single message.
+
+When a page request (external request) comes in to the Receptionist, it looks at the action attribute and passes the request to the appropriate Action module. The Action will fire one or more internal requests to the MessageRouter, based on the arguments. The data is gathered into a  response, which is returned to the Receptionist.  The page that the receptionist returns contains the original request, the response from the action and other info as needed (depends on the type of Receptionist). The data may be transformed in some way --- for the \gs\ servlet  we transform using XSLT to generate html pages.
 
 Actions send internal style messages to the MessageRouter. Some can be answered by it, others are passed on to collections, and maybe on to services. Internal requests are for simple actions, such as search, retrieve metadata, retrieve document text
-There are different request types: describe, process, system... 
-
-The message formats for each request type, and the response formats for each module are described in the following section.
-
-\subsection{an attempt at an API: message formats}
-
-\subsubsection{external$->$action}\label{sec:page-requests}
-
-request:
-These are the special 'external'-style messages. Requests originate from outside \gs\ , for example from a servlet, or java application. They are requests for a 'page' of data---for example, the home page for a site; the query page for a collection; the text of a document. They contain, in XML, a list of arguments specifying what type of page is required. If the external context is a servlet, the arguments represent the 'CGI' arguments in a \gs\  URL.  The two main arguments are \gst{a} (action) and \gst{sa} (subaction). All other arguments are encoded as parameters.
-
-Here are some examples of  requests\footnote{In a servlet context, these correspond to the arguments \gst{a=p\&sa=about\&c=demo\&l=fr}, and \gst{a=q\&l=en\&s=TextQuery\&c=demo\&rt=r\&ca=0\&st=1\&m=10\&q=snail}.}:
-
-\begin{quote}\begin{gsc}\begin{verbatim}
-<request type='page' action='p' subaction='about'
-         lang='fr' output='html'>
-  <paramList>
-    <param name='c' value='demo'/>
-  </paramList>
-</request>
-\end{verbatim}\end{gsc}\end{quote}
-
-\begin{quote}\begin{gsc}\begin{verbatim}
-<request type='page' action='q' lang='en' output='html'>
-  <paramList>
-    <param name='s' value='TextQuery'/>
-    <param name='c' value='demo'/>
-    <param name='rt' value='r'/>
-    <!-- the rest are the service specific params -->
-    <param name='ca' value='0'/> <!-- casefold -->
-    <param name='st' value='1'/> <!-- stem -->
-    <param name='m' value='10'/> <!-- maxdocs -->
-    <param name='q' value='snail'/> <!-- query string -->
-  </paramList>
-</request>
-\end{verbatim}\end{gsc}\end{quote}
-
-The Receptionist routes the message to the appropriate Action (determined by looking up its shortname$->$Action object map). The actions determine what information is needed from the server and retrieves it, making one or more internal requests to the MessageRouter. This information is gathered together into a single response, and returned to the Receptionist. The Receptionist may process the result further, depending on what type of Receptionist is it.
-
-
-\begin{table}
-{\footnotesize
-\begin{tabular}{lll}
-\hline
-\bf Argument & \bf Meaning &\bf Typical values \\
-\hline
-a & action & a (applet), q (query), b (browse), p (page), pr (process) \\
-& & s (system)\\
-sa & subaction & home, about (page action)\\
-c & collection or  & demo, build \\
-& service cluster \\
-s & service name & TextQuery, ImportCollection \\
-rt & request type & d (display), r (request), s (status) \\
-ro & response only & 0 or 1 - if set to one, the request is carried out \\
-& & but no processing of the results is done \\
-& & currently only used in process actions \\
-o & output type & XML, html, WML \\
-l & language & en, fr, zh ...\\
-d & document id & HASHxxx \\
-r & resource id & ???\\
-pid & process handle & an integer identifying a particular process request \\
-\hline
-\end{tabular}}
-\caption{Generic arguments that can appear in a \gs\  URL}
-\label{tab:args}
-\end{table}
+There are different internal request types: describe, process, system, format, status. Process requests do the actual work of the system, while the other types get auxiliary information. The format of the requests and responses for each internal request type are described in the following sections. External style requests, and their page responses are described in the Section about page generation (Section~\ref{sec:pagegen}).
 
 \subsection{'describe'-type messages}\label{sec:describe}
@@ -1176,6 +1115,6 @@
 
 It is possible to ask just for a specific part of the information provided by a
-describe request, rather than the whole thing.  For example, these two
-messages get the \gst{collectionList} and the \gst{siteList} respectively:
+describe request, rather than the whole thing. For example, these two
+messages get the \gst{collectionList} and the \gst{siteList} respectively: 
 \begin{quote}\begin{gsc}\begin{verbatim}
 <request lang='en' type='describe' to=''>
@@ -1192,6 +1131,7 @@
 \end{verbatim}\end{gsc}\end{quote}
 
-When a collection or service cluster is asked to describe itself, what is returned is a list of metadata, some display elements, and  a list of services.  For example, here is such
-a message, along with a sample response.
+Subset options for the MessageRouter include \gst{collectionList}, \gst{serviceClusterList}, \gst{serviceList}, \gst{siteList}.
+
+When a collection or service cluster is asked to describe itself, what is returned is a list of metadata, some display elements, and  a list of services.  For example, here is such a message, along with a sample response.
 
 \begin{quote}\begin{gsc}\begin{verbatim}
@@ -1231,5 +1171,5 @@
 \end{verbatim}\end{gsc}\end{quote}
 
-The subset parameter can also be used in a describe request to a collection, to retrieve just the \gst{metadataList} or \gst{serviceList}.
+Subset options for a collection or serviceCluster include \gst{metadataList}, \gst{serviceList}, and \gst{displayItemList}.
 
 This collection provides many typical services. Notice how this response lists the services available, while the collection configuration file for this collection (Figure~\ref{fig:collconfig}) described serviceRacks. Once the service racks have been configured, they become transparent in the system, and only services are referred to.
@@ -1237,7 +1177,7 @@
 
 A \gst{describe} request sent to a service returns a list of parameters that
-the service accepts, some display information, (and in future may describe the content type for the request and response).
-
-Parameters can by in the following formats:
+the service accepts and some display information, (and in future may describe the content type for the request and response). Subset options for the request include \gst{paramList} and \gst{displayItemList}.
+
+Parameters can be in the following formats:
 \begin{quote}\begin{gsc}\begin{verbatim}
 <param name='xxx' type='integer|boolean|string|invisible' default='yyy'/>
@@ -1280,5 +1220,5 @@
 A service description also contains some display information---this includes the name of the service, and the text  for the submit button. 
 
-Here is a sample describe request to the FieldQuery service of collection mgppdemo, along with its response. The parameters in this example include their display information. Figure~\ref{fig:query-display} gives an example html search form that may be generated from this describe response. 
+Here is a sample describe request to the FieldQuery service of collection mgppdemo, along with its response. The parameters in this example include their display information. Figure~\ref{fig:query-display} shows an example html search form that may be generated from this describe response. 
 
 \begin{quote}\begin{gsc}\begin{verbatim}
@@ -1394,7 +1334,7 @@
 Note that the library parameter has been left blank. This is because library refers to the current servlet that is running and the name is not necessarily known in advance. So either the applet action or the Receptionist must fill in this parameter before displaying the html.
 
-\subsubsection{'system'-type messages}\label{sec:system}
-
-``System'' requests are used to tell a MessageRouter, Collection or ServiceCluster to update its cached information and activate or deactivate other modules. For example, the MessageRouter has a set of Collection modules that it can talk to. It also holds some XML information about those collections---this is returned when a request for a collection list comes in. If a collection is deleted or modified, or a new one created, this information may need to change, and the list of available modules may also change. Currently they are initiated by particular CGI parameters (see Section~\ref{sec:runtime-config}).
+\subsection{'system'-type messages}\label{sec:system}
+
+``System'' requests are used to tell a MessageRouter, Collection or ServiceCluster to update its cached information and activate or deactivate other modules. For example, the MessageRouter has a set of Collection modules that it can talk to. It also holds some XML information about those collections---this is returned when a request for a collection list comes in. If a collection is deleted or modified, or a new one created, this information may need to change, and the list of available modules may also change. Currently these requests are initiated by particular CGI requests (see Section~\ref{sec:runtime-config}).
 
 The basic format of a system request is as follows:
@@ -1417,13 +1357,11 @@
 The third request is to activate collection demo. This could be a new collection, or a reactivation of an old one. If a collection module already exists, it will be deleted, and a new one loaded. The final request deactivates the site site1---this removes the site from the siteList and module map, and also removes any of that sites collections/services from the static lists.
 
-
-A response just contains a status message, for example:
-\begin{quote}\begin{gsc}\begin{verbatim}
-<response from="">
-  <status>collectionList reconfigured successfully</status>
-</response>
-\end{verbatim}\end{gsc}\end{quote}
-
-At some stage, an error or status code should be included.
+A response just contains a status message\footnote{TODO: add in error/status codes}, for example:
+\begin{quote}\begin{gsc}\begin{verbatim}
+<status>MessageRouter reconfigured successfully</status>
+<status>Error on reconfiguring collectionList</status>
+<status>collection:demo activated</status>
+<status>site:site1 deactivated</status>
+\end{verbatim}\end{gsc}\end{quote}
 
 System requests are mainly answered by the MessageRouter. However, Collections and ServiceClusters will respond to a subset of these requests. 
@@ -1445,10 +1383,10 @@
 \end{verbatim}\end{gsc}\end{quote}
 
-The actual format statements are described in Section~\ref{sec:formatstmt}. They are templates written directly in XSLT, or in GSF, which  stands for Greenstone Format, and is a simple XML representation of the more complicated XSLT templates. 
-GSF style format statements need to be converted to proper XSLT. This is currently done by the Receptionist (but may be moved to an ActionHelper): the format XML is transformed to XSLT using XSLT with the config\_format.xsl stylesheet.
+The actual format statements are described in Section~\ref{sec:formatstmt}. They are templates written directly in XSLT, or in GSF (GreenStone Format) which is a simple XML representation of the more complicated XSLT templates. 
+GSF-style format statements need to be converted to proper XSLT. This is currently done by the Receptionist (but may be moved to an ActionHelper): the format XML is transformed to XSLT using XSLT with the config\_format.xsl stylesheet.
 
 \subsection{'status'-type messages}\label{sec:status}
 
-These are only used with process-type services, which are those where a request is sent to start some type of process (see Section~\ref{sec:process}). The initial response states whether the process had successfully started, and whether its still continuing. If the process is not finished, status requests can be sent repeatedly to the service to poll the status, using the pid to identify the  process.  Status codes are used to identify the state of a process. The values used at the moment are listed in Table~\ref{tab:status codes}\footnote{A more standard set of codes should probably be used, for example, the HTTP codes}.
+These are only used with process-type services, which are those where a request is sent to start some type of process (see Section~\ref{sec:process}). An initial 'process' request to a 'process' service generates a response which states whether the process had successfully started, and whether its still continuing. If the process is not finished, status requests can be sent repeatedly to the service to poll the status, using the pid to identify the  process.  Status codes are used to identify the state of a process. The values used at the moment are listed in Table~\ref{tab:status codes}\footnote{A more standard set of codes should probably be used, for example, the HTTP codes}.
 
 \begin{table}
@@ -1506,5 +1444,5 @@
 \end{verbatim}\end{gsc}\end{quote}
 
-\subsubsection{process messages}
+\subsection{'process'-type messages}
 
 Process requests and responses  provide  the major functionality of the system---these are the ones that do the actual work. The format depends on the service they are for, so I'll describe these by service.
@@ -1760,5 +1698,5 @@
 \end{verbatim}\end{gsc}\end{quote}
 
-The \gst{code} attribute in the response specifies whether the command has been successfully stated, whether its still going, etc (see Table~\ref{tab:status codes} for a list of currently used codes). The pid attribute specifies a process id number that can be used when querying the status of this process. The content of the status element is (currently) just the output from the process so far. Status messages, which are described in Section~\ref{sec:status}, are used to find out how the process is going, and whether it has finished or not.
+The \gst{code} attribute in the response specifies whether the command has been successfully stated, whether its still going, etc (see Table~\ref{tab:status codes} for a list of currently used codes). The pid attribute specifies a process id number that can be used when querying the status of this process. The content of the status element is (currently) just the output from the process so far. Status messages, which were described in Section~\ref{sec:status}, are used to find out how the process is going, and whether it has finished or not.
 
 \subsubsection{'applet'-type services}
@@ -1812,5 +1750,5 @@
 
 Enrich services typically take some text of documents (inside \gst{<nodeContent>} tags) and returns the text marked up in some way. One example of this is the GatePOSTag service: this identifies Dates, Locations, People and Organizations in the text, and annotates the text with the labels. In the following example, the request is for Location and Dates to be identified.
-*** TODO ****
+
 \begin{quote}\begin{gsc}\begin{verbatim}
 <request lang="en" to="GatePOSTag" type="process">
@@ -1837,5 +1775,5 @@
 	FOOD AND AGRICULTURE ORGANIZATION OF THE UNITED NATIONS
 	<annotation type="Location">Rome</annotation> 
-          <annotation type="Date">1986</annotation>
+        <annotation type="Date">1986</annotation>
         P-69
         ISBN 92-5-102397-2
@@ -1847,18 +1785,82 @@
 \end{verbatim}\end{gsc}\end{quote}
 
-\subsection{Page generation}\label{sec:pagegen} **** REDO ********
-
-* talk general first: get data, get format info, transform gsf->xsl. transfrom xml->html
-
-* state saving. the XSLT files assume that arguments are saved somehow. This needs to be implemented outside \gs\  proper - we do this in the servlet, using something or other.
-
-URL-style requests are received by the Receptionist. Based on the arguments, a page of data must be returned to the servlet. As described in Section~\ref{sec:page-requests}, the requests are XML representations of \gs\  URLs. One of the arguments is action (a). This tells the Receptionist which Action module to pass the request to. Action modules decode the rest of the CGI-arguments to determine what requests need to be made to the system. 
-System requests are received by the MessageRouter, which answers them one by one, either itself or by passing them on to the appropriate module. 
-
-Once the data needed from the system has been accumulated, it is put into a 'page' of XML. The page is transformed to its output form, currently HTML, via XSLT transformations, and returned to the user.
+\subsection{Page generation}\label{sec:pagegen} 
+
+A 'page' is some XML or HTML (or other?) data returned in response to an 
+external 'page'-type request. These requests originate from outside \gs\ , for example from a servlet, or java application, and are received by the Receptionist. As described below in Section~\ref{sec:page-requests}, the requests are XML representations of \gs\  URLs. One of the arguments is action (a). This tells the Receptionist which Action module to pass the request to. 
+
+Action modules decode the rest of the arguments to determine what requests need to be made to the system. One or more internal requests may be made to the MessageRouter. A request for format information from the Collection/Service may also be made. The resulting data is gathered together into a single XML response, \gst{<page>}, and returned to the Receptionist. 
+
+The page format is described in Section~\ref{sec:page-format}. The XML may be returned as is, or may be modified by the Receptionist. The various Receptionists are described in Section~\ref{sec:recepts}. The default receptionist used by a servlet transforms the XML into HTML using XSL stylesheets. Section~\ref{sec:collformat} looks at collection specific formatting, in particular for HTML output.
+Sections~\ref{sec:pageaction} to \ref{sec:systemaction} look at the various actions and what kind of data they gather.
+
+\subsubsection{'page'-type requests and their arguments}\label{sec:page-requests}
+
+These are requests for a 'page' of data---for example, the home page for a site; the query page for a collection; the text of a document. They contain, in XML, a list of arguments specifying what type of page is required. If the external context is a servlet, the arguments represent the 'CGI' arguments in a \gs\  URL.  The two main arguments are \gst{a} (action) and \gst{sa} (subaction). All other arguments are encoded as parameters.
+
+Here are some examples of  requests\footnote{In a servlet context, these correspond to the arguments \gst{a=p\&sa=about\&c=demo\&l=fr}, and \gst{a=q\&l=en\&s=TextQuery\&c=demo\&rt=r\&ca=0\&st=1\&m=10\&q=snail}.}:
+
+\begin{quote}\begin{gsc}\begin{verbatim}
+<request type='page' action='p' subaction='about'
+         lang='fr' output='html'>
+  <paramList>
+    <param name='c' value='demo'/>
+  </paramList>
+</request>
+\end{verbatim}\end{gsc}\end{quote}
+
+\begin{quote}\begin{gsc}\begin{verbatim}
+<request type='page' action='q' lang='en' output='html'>
+  <paramList>
+    <param name='s' value='TextQuery'/>
+    <param name='c' value='demo'/>
+    <param name='rt' value='r'/>
+    <!-- the rest are the service specific params -->
+    <param name='ca' value='0'/> <!-- casefold -->
+    <param name='st' value='1'/> <!-- stem -->
+    <param name='m' value='10'/> <!-- maxdocs -->
+    <param name='q' value='snail'/> <!-- query string -->
+  </paramList>
+</request>
+\end{verbatim}\end{gsc}\end{quote}
+
+There are some standard arguments used in Greenstone, and they are described in Table~\ref{tab:args}. These are used by Receptionists and Actions. The GSParams class specifies all the general basic arguments, and whether they should be saved or not (Some arguments need to be saved during a session, and this needs to be implemented outside \gs\  proper --- currently we do this in the servlet, using servlet session handling). The servlet has an init parameter \gst{params\_class} which specifies which params class to use: GSParams can be subclassed if necessary. The Receptionist and Actions must not have conflicting argument names.
+
+Other arguments are used dynamically and come from the Services. Service arguments must always be saved during a session. Services may be created by different people, and may reside on a different site. There is no guarantee that there is no conflict with argument names between services and actions. Therefore service parameters are namespaced when they are put on the page, whereas interface (receptionist and action) parameters have no namespace. The default namespace is s1 (service1) --- any parameters that are for the service will be prefixed by this. For example, the case parameter for a search will be put in the page as s1.case, and the resulting argument in a search URL will be s1.case. When actions are deciding which parameters need to be sent in a request to a service, they can use the namespace information.
+
+If there are  two or more services combined on a page with a single submit button, they will use namespaces s1, s2, s3 etc as needed. The s  (service) parameter will end up with a list of services. For example, \gst{s=TextQuery,MusicQuery,} and the order of these determines the mapping order of the namespaces, i.e. s1 will map to TextQuery, s2 to MusicQuery.
+
+\begin{table}
+{\footnotesize
+\begin{tabular}{lll}
+\hline
+\bf Argument & \bf Meaning &\bf Typical values \\
+\hline
+a & action & a (applet), q (query), b (browse), p (page), pr (process) \\
+& & s (system)\\
+sa & subaction & home, about (page action)\\
+c & collection or  & demo, build \\
+& service cluster \\
+s & service name & TextQuery, ImportCollection \\
+rt & request type & d (display), r (request), s (status) \\
+ro & response only & 0 or 1 - if set to one, the request is carried out \\
+& & but no processing of the results is done \\
+& & currently only used in process actions \\
+o & output type & XML, html, WML \\
+l & language & en, fr, zh ...\\
+d & document id & HASHxxx \\
+r & resource id & ???\\
+pid & process handle & an integer identifying a particular process request \\
+\hline
+\end{tabular}}
+\caption{Generic arguments that can appear in a \gs\  URL}
+\label{tab:args}
+\end{table}
+
+\subsubsection{page format}\label{sec:page-format}
 
 The basic  page format  is:
 \begin{quote}\begin{gsc}\begin{verbatim}
-<page>
+<page lang='en'>
   <pageRequest/>
   <pageResponse/>
@@ -1896,27 +1898,21 @@
 NZDLReceptionist: (do we want to talk about this?) This is an example of a custom receptionist. For a look-alike nzdl.org system, even more information is needed for each page, namely the list of classifiers available from the ClassifierBrowse service. 
 
-By default, the LibraryServlet uses DefaultReceptionist. However, there is an init-param called receptionist which can be set to make the servlet use a different one.
-
+By default, the LibraryServlet uses DefaultReceptionist. However, there is a servlet init-param called \gst{receptionist} which can be set to make the servlet use a different one.
+
+\subsubsection{Collection specific formatting}\label{sec:collformat}
+get format info, transform gsf->xsl. transfrom xml->html
+
+config params are passed in to the transformation
 \subsubsection{CGI arguments}
 
-The arguments used by the page come from several sources. Receptionist uses a couple, actions use some and services. the receptionist and actions are treated as a whole so must not have conflicting arguments. GSParams class specifies all the general basic arguments, and whether they should be saved or not. servlet has an init parameter params\_class, that specifies which params class to use - if subclass it. actions or receptionist  may specify some new ones
-
-services may be created by different people, may be on a different site. cant guarantee no conflict with action params, or even with other services.
-so service params are namespaced when they are put on the page. interface (recept and action) params will have no namespace) the default namespace is s1 (service1) - any parameters that are for the service will be prefixed by this. e.g. the case parameter for a search will be put in the page as s1.case.
-The actions must now look for all the s1 parameters to send to the service.
-
-if there are  two or more services combined on a page with a single submit button, they will use s1, s2, s3 etc as needed. the s parameter (service) will end up with a list e.g. s=TextQuery,MusicQuery, and the order of these determines the mapping order of the namespaces, ie s1 will be TextQuery, s2 MusicQuery.
-
-also talk about saving arguments - save ones that GSParams says to save, and any service ones should always save.
-
-\subsubsection{Page action}
-* kind of info pages. other actions are associated with specific services.
-* uses describe requests to modules
-Depending on the subaction argument, different pages can be generated. For the 'home' page, a 'describe' request is sent to the MessageRouter---this returns a list of all the collections, services, serviceClusters and sites known about. For each collection, its metadata is retrieved via a 'describe' request. This metadata is added into the previous result, which is then added into the page.  The page is
-transformed using \gst{home.xsl}.  For the 'about' page, a \gst{describe} request is sent to the module that the about page is about: this may be a collection or a service cluster.  This returns a list of metadata
-and a list of services, and the result is transformed using \gst{about.xsl}.
-
-
-\subsubsection{Query action}
+
+\subsubsection{Page action}\label{sec:pageaction}
+
+PageAction is responsible for displaying kinds of information pages, such as the home page of the library, or the home page of a collection, or the help and preferenecs pages. These pages are not associated with specific services like the other page types. In general, the data comes from describe requests to various modules.
+The different pages are requested using the subaction argument. For the 'home' page, a 'describe' request is sent to the MessageRouter---this returns a list of all the collections, services, serviceClusters and sites known about. For each collection, its metadata is retrieved via a 'describe' request. This metadata is added into the previous result, which is then added into the page.    For the 'about' page, a \gst{describe} request is sent to the module that the about page is about: this may be a collection or a service cluster.  This returns a list of metadata
+and a list of services.
+
+
+\subsubsection{Query action}\label{sec:queryaction}
 
 The basic URL is \gst{a=q\&s=TextQuery\&c=demo\&rt=d/r}.
@@ -1925,8 +1921,7 @@
 displayed, but should be cached. The description includes a list of the parameters available for the query, such as case/stem, max num docs to return, etc. If the request type (rt) parameter is set to d for display, the action only needs to display the form, and this is the only request to the service. Otherwise, the submit button has been pressed, and a query request to the TextQuery service is sent. This has  all the parameters from the URL put into the parameter list. A list of document identifiers
 is returned. A followup query is sent to the MetadataRetrieve service of the collection: the content includes the list of
-documents, with a request for some of their metadata. Which metadata to retrieve is determined by looking through the XSLT that will be used to transform the page (Formatter object??). The service description and query result are combined into a page of XML, which is
-transformed using \gst{basicquery.xsl} to produce the html page.
-
-\subsubsection{Applet action}
+documents, with a request for some of their metadata. Which metadata to retrieve is determined by looking through the XSLT that will be used to transform the page. The service description and query result are combined into a page of XML, which is returned to the Receptionist.
+
+\subsubsection{Applet action}\label{sec:appletaction}
 
 There are two types of request to the applet action: \gst{a=a \& rt=d\/} and
@@ -1935,23 +1930,7 @@
 into the page, and the servlet returns the HTML.
 
-The value \gst{rt=r} signals a request from the applet.  The result is returned
-directly to the applet code, in XML.  The other parameters are sent to the
-service untransformed, and the result is passed directly back to the applet.
-Applet action can therefore work with any applet whose service understands the
-messages.
-
-Here are two examples of requests generated by the Applet action, along with their corresponding responses.
-
-The first request corresponds to the URL arguments \gst{a=a \&
-rt=d \& sn=Phind \& c=mgppdemo\/}, which translate to ``display the Phind
-applet for the mgppdemo collection''.
-
-
-The second request corresponds to the  arguments \gst{a=a \& rt=r \& sn=Phind \& c=mgppdemo \& pc=1 \& pptext=health \& pfe=0 \& ple=10 \& pfd=0 \& pld=10 \& pfl=0 \& pll=10}---this 
-indicates a request to the service itself. The extra arguments (not a, sa, sn, c)  are simply copied into the
-request as parameters. The response is in a form suitable for the applet, placed inside
-\gst{<appletData>} in a standard \gs\  message.  AppletAction returns the
-contents of appletData to the browser, i.e. to the applet itself.
-
+The value \gst{rt=r} signals a request from the applet. A process request containing all the parameters is sent to the applet service. The result contains an appletData element, which contains a single  element - this element is returned
+directly to the applet, in XML. No transformation is done. 
+Because the AppletAction doesn't know or care anything about the applet data, it can work with any applet-service pair.
 
 Note that the applet HTML may need to know the name of the \gst{library}
@@ -1962,14 +1941,24 @@
 <PARAM NAME='library' VALUE=''/>
 \end{verbatim}\end{gsc}\end{quote}
-When the Applet action encounters this parameter it inserts the name of the
+When the AppletAction encounters this parameter it inserts the name of the
 current library servlet as its value.
 
-\subsubsection{Document action}
-
-DocumentAction sends a query to the DocumentRetrieve service of the collection requesting the text of the specified document.  At this stage no additional information is obtained, but in future stuff like Title and
-table of contents would be needed to make the display nicer.
-
-
-\subsubsection{System action}\label{sec:system-action}
+\subsubsection{Document action}\label{sec:documentaction}
+
+DocumentAction is responsible for displaying a document to the user. The display might involve some metadata and/or text for a document or part of a document. For hierarchical documents, a table of contents may be shown, while for paged documents (those with a single linear list of sections), next and previous page buttons may be shown. These different display types require different information about the document. Depending on the arguments, DocumentAction will send requests to several services: DocumentMetadataRetrieve, DocumentStructureRetrieve and DocumentContentRetrieve.
+
+A basic display, for example, Title and text, involves a metadata request to get the Title, and a content request to get the text. Hierarchical table of contents display requires a structure request. If the entire contents is to be displayed, the parameter \gst{structure=entire} would be sent in the request. Otherwise, parameters \gst{structure=ancestors}, \gst{structure=children} and possibly \gst{structure=siblings} may be used, depending in the position of the current node in the document. These return a hierarchical structure of nodes, containing ancestor nodes, child nodes and sibling nodes, respectively.
+For paged display, the structure is not actually needed. A structure request is still sent, but this time it requests some information, rather the structure itself. The information requested includes the number of siblings and the current position of the current node, or the number of children (if the current node is the root of the document).
+
+Metadata may be requested for the current node, or for any nodes in the structure, and content also. The metadata and content are added into the appropriate nodes in the structure hierarchy, and this is returned as the page data.
+
+\subsubsection{XML Document action}\label{sec:xmldocumentaction}
+
+XMLDOcumentAction is a little different to the standard DocumentAction. It operates in two modes, \gst{text} and \gst{toc}. In \gst{text} mode, it will retrieve the content of the current document node using a DocumentContentRetrieve request. In \gst{toc} mode, it retrieves the entire table of contents for the document using a DocumentStructureRetrieve request. Either mode may also retrieve metadata for the current section or each section in the table of contents.
+
+\subsubsection{GS2Browse action}\label{sec:browseaction}
+
+GS2BrowseAction is for displaying Greenstone 2 style classifiers. 
+\subsubsection{System action}\label{sec:systemaction}
 
 SystemAction allows for manual reconfiguration of various components at run-time. There is no interactive web-page displaying the options, it merely turns a set of CGI arguments into an XML system request. The response from a system request is a message which is displayed to the user.
@@ -1999,5 +1988,8 @@
 
 
-\subsubsection{Some class info - where should this go??}
+\subsection{Other code information}
+
+Greenstone has a set of Utility classes, which are briefly described in Table~\ref{tab:utils}.
+
 \begin{table}[h]
 \caption{The utility classes in org.greenstone.gsdl3.util}
@@ -2008,10 +2000,13 @@
 \bf Utility class & \bf Description\\
 \hline
-ConfigVars & holds the servlet startup variables, including library name, site name, interface name, default language\\
-Dictionary & wrapper around a Resource Bundle, providing strings with parameter\\
-GSCGI & class to map between short name CGI arguments and long name request parameters \\
+Dictionary & wrapper around a Resource Bundle, providing strings with parameters\\
+GSConstants & holds some constants used for servlet arguments and configuration variables\\
+GSEntityResolver & an EntityResolver which can be used to find resources such as DTDs\\
 GSFile & class to create all \gs\  file paths e.g. used to locate configuration files, XSLT files and collection data. \\
 GSHTML & provides convenience methods for dealing with HTML, e.g. making strings HTML safe\\
+GSParams & contains names and default values for interface parameters\\
+NZDLParams & a subclass of GSParams which holds default service parameters too, necessary for the classic style interface.\\
 GSPath & used to create, examine and modify message address paths\\
+GSSQL & contains static strings for all the SQL table/field names\\
 GSStatus & some static codes for status messages\\ 
 GSXML & lots of methods for extracting information out of \gs\  XML, and creating some common types of elements. Also has static Strings for element and attribute names used by \gs\ .\\
@@ -2019,4 +2014,6 @@
 Misc & miscellaneous functions\\
 OID & class to handle \gs\  (2) OIDs\\
+GS3OID & subclass of OID to handle \gsiii\ OIDs\\
+SQLQuery & contains a connection to a SQL database, along with some methods for accessing the data, such as converting MG numbers to and from Greenstone OIDs.\\
 XMLConverter & provides methods to create new Documents, parse Strings or Files into Documents, and convert Nodes to Strings\\
 XMLTransformer & methods to transform XML using XSLT \\
@@ -2054,5 +2051,17 @@
 
 \subsection{new interfaces}\label{sec:new-interfaces}
+
+It is easy to create new interfaces to \gsiii. Here we are talking about interfaces other than those to display in typical browser.
+
+Handheld devices: Use the standard servlet setup, but with a different set of XSLT files to format the pages for small screens, or use WML.
+
+Java GUI Interface: There are couple of alternatives. Depending on what you want to display in the GUI, you could talk to either a Receptionist or a MessageRouter. The library classes can be set up and compiled into the GUI program.
+Talking to a Receptionist will give you access to pages of XML. It is likely that the standard Receptionist class would be used - this doesn't transform the data to HTML. Queries such as ``give me the home page of a collection'' and ``do the following search'' can be issued. All teh data needed for the result view is returned. Queries are quite simple, but are limited to what kinds of Actions are available in the library. 
+Talking to a MessageRouter requires a bit more effort on the part of the GUI program, but results in greater flexibility. The kinds of queries that can be issued are individual units of action, such as ``describe yourself'', ``search'', ``retrieve the content for this document''. More than one request may need to be made for a particular feature of the GUI. However you can ask for any combination of data available in the system, you are not relying on Actions. What you will implemenet though, may be a lot like the Action code in terms of request sequences.
+
+Interfaces in other programming languages: Because the communication is all XML based, other interfaces can talk to the Java library if a communication protocol is set up. This could be done using SOAP for example. LIke for Java GUI interfaces, the program could talk to a Receptionist or to a MessageRouter. 
 e.g. java interface. where you can interface to. MR vs Receptionist. diff receptionists. egs, handheld - using servlet, transforming recpt, but new set of XSLT java program other program - talk to recpt but just get back XML data for pages. java gui - just talk to MR, do all processing itself.
+
+Remote interfaces: remote interfaces can be set up in the same way as above, using a communication protocol between the interface, and the library program.
 
 \subsection{Adding new classifiers}\label{sec:new-classifiers}
@@ -2065,12 +2074,9 @@
 There are two types of standard \gs\  collections: collections built with the \gsiii\  building system, and collections that are imported from \gsii\ . There are many options to collection building but it is conceivable that these options don't meet the needs of all collection builders. \gsiii\  has an ability to use any type of collection you can come up with, assuming  some java code is provided. 
 
-
 There are four levels of customisation that may be needed with new collections: service, collection, interface XSLT, and action levels. We will use the example collections that come with \gs\  to describe these different levels.
 
 Firstly, new service classes need to be written to provide the functionality to search/browse/whatever the collection. If the services have similar interfaces and functionality to the standard services, this may be all that is needed. For example, the \gsii\  MGPP collections were the first to be served in \gsiii\ . When we came to do \gsii\  MG collections, all we had to do was write some new service classes that interacted with MG instead of MGPP. Because these collections used the same type of services, this was all we had to do. The format of the configuration files was similar, they just specified MG serviceRack classes rather than MGPP ones.
 
-The nzmaps collection used the same level of customisation, just implementing new services and fitting all the extra display elements into the standard query/display framework using javascript.
-
-The gberg collection, however, was done quite differently to the standard collections. New services were provided to search the database (built with Lucene) and to provide the documents and parts of documents (using XSLT to transform the raw XML files). The collectionConfig file had some extra information in it: a list of the documents in the collection along with their Titles. Because the standard collection class has no notion of document lists, a new class was created (org.greenstone.gsdl3.collection.XMLCollection). This class is basically the same as a standard collection class except that it looks for and stores in memory the documentList from the collectionConfig file.
+The XML Sample Texts (gberg) collection, however, was done quite differently to the standard collections. New services were provided to search the database (built with Lucene) and to provide the documents and parts of documents (using XSLT to transform the raw XML files). The collectionConfig file had some extra information in it: a list of the documents in the collection along with their Titles. Because the standard collection class has no notion of document lists, a new class was created (org.greenstone.gsdl3.collection.XMLCollection). This class is basically the same as a standard collection class except that it looks for and stores in memory the documentList from the collectionConfig file.
 
 To tell \gs\  to load up a different type of collection class, we use another configuration file: etc/collectionInit.xml. This  specifies the name of the collection class to use.
@@ -2083,5 +2089,5 @@
 Document display is  significantly different to standard \gs\ . There are two modes of display: table of contents mode, and content mode. Clicking on a document link from the collection home page takes the user to the table of contents for the collection. Clicking on one of the sections in the table of contents takes them to a display of that section. To facilitate this, not only do we need new XSLT files , we also needed a new action. XMLDocumentAction was created, that used two subactions, toc and text, for the different modes of display.
 
-The Receptionist was told about this new action by the addition of the following to the interfaceConfig.xml file: 
+The Receptionist was told about this new action by the addition of the following element to the interfaceConfig.xml file: 
 
 \begin{gsc}\begin{verbatim}
@@ -2125,17 +2131,17 @@
 Instead of displaying an icon and the Title, it displays the Title of the section and the title of the document. Both of these are linked to the document: the section title to the content of that section, the document title to the table of contents for the document. Because these require non-standard arguments to the library, these parts of the template are written in XSLT not \gs\  format language. As is shown here it is perfectly feasible to write a format statement that includes XSLT mixed in with \gs\  format elements.
 
-The document display uses CSS to format the output---these are kept in the collection and specified in the collections XSLT files. The documents also specify DTD files. Due to the way we read in the XML files, Tomcat sometimes has trouble locating the DTDs. One option is to may all the links absolute links to files in the collection folder, the other option is to put them in \gs\ 's DTD folder gsdl3/resources/dtd. 
-
-\subsection{The NZDL mirror site}
-
-The library seen at \gst{http://www.greenstone.org/greenstone3/nzdl} is like a mirror to \gst{http://www.nzdl.org}---it aims to present the same collections, in the same way but using \gsiii\  instead of \gsii\ . It uses a new site and a new interface. The web.xml file had a new servlet entry in it to specify the combination of nzdl site and interface.
-
-The site was created by making a directory called nzdl in the sites folder. A siteConfig file was created. Because its running on Linux, we were able to link to all the collections in the old \gs\  installation. The convert\_coll\_from\_gs2.pl script was run over all the collections to produce the new XML configuration files.
-
-A new interface, also called nzdl, was created in the interfaces directory.
-In many cases, creating a new interface just requires the new images and XSLT  to be added to the new directory(see Sections~\ref{sec:sites-and-ints} and \ref{sec:interface-customise}). This setup also required a bit more customisation.
-
-The standard \gs\  navigation bar lists all the services available for the collection. In \gsii\ , the navigation bar provided the search option, and the different classifiers. This is not service specific, but hard coded to the search and classifiers. The XSLT that produced the navigation bar needed to be altered to produce this. But also, a new Receptionist was needed. 
-The standard receptionist (DefaultReceptionist) gathers a little bit of extra info for each page of XML before transforming it: this is the list of services for the collection and their display information, allowing the services to be listed along the navigation bar. This is information that is needed by every page (except for the library home page) and therefore is obtained by the receptionist instead of by each action. The nzdl interface needed a bit more information than this: for the ClassifierBrowse service, if there was one, the list of classifiers and their display elements must be obtained. So a new Receptionist was written that inherited from DefaultReceptionist, and added this new info into the page.
+The document display uses CSS to format the output---these are kept in the collection and specified in the collections XSLT files. The documents also specify DTD files. Due to the way we read in the XML files, Tomcat sometimes has trouble locating the DTDs. One option is to make all the links absolute links to files in the collection folder, the other option is to put them in \gs\ 's DTD folder gsdl3/resources/dtd. 
+
+\subsection{The Classic Interface}
+
+The library seen at \gst{http://www.greenstone.org/greenstone3/nzdl} is like a mirror to \gst{http://www.nzdl.org}---it aims to present the same collections, in the same way but using \gsiii\  instead of \gsii\ . It uses a new site (nzdl) with the classic interface. The web.xml file had a new servlet entry in it to specify the combination of nzdl site and classic interface.
+
+The site was created by making a directory called nzdl in the sites folder. A siteConfig file was created. Because it is running on Linux, we were able to link to all the collections in the old \gs\  installation. The convert\_coll\_from\_gs2.pl script was run over all the collections to produce the new XML configuration files.
+
+The classic interface was created to be used by this site (and is now a standard part of Greenstone).
+In many cases, creating a new interface just requires the new images and XSLT  to be added to the new directory(see Sections~\ref{sec:sites-and-ints} and \ref{sec:interface-customise}). This classic interface required a bit more customisation.
+
+The standard \gsiii\  navigation bar lists all the services available for the collection. In \gsii\ , the navigation bar provides the search option, and the different classifiers. This is not service specific, but hard coded to the search and classifiers. The XSLT that produces the navigation bar needed to be altered to produce this. But also, a new Receptionist was needed. 
+The standard receptionist (DefaultReceptionist) gathers a little bit of extra information for each page of XML before transforming it: this is the list of services for the collection and their display information, allowing the services to be listed along the navigation bar. This is information that is needed by every page (except for the library home page) and therefore is obtained by the receptionist instead of by each action. The nzdl interface needed a bit more information than this: for the ClassifierBrowse service, if there was one, the list of classifiers and their display elements must be obtained. So a new Receptionist (NZDLReceptionist) was written that inherited from DefaultReceptionist, and added this new info into the page.
 
 One of the servlet initialisation parameters is the receptionist class: this was added to the servlet definition in the web.xml file so that the LibraryServlet would load up the right receptionist class.
@@ -2166,5 +2172,5 @@
 Sitename is the name of the site's directory, eg localsite. The siteuri is the identifier that will be used for the SOAP resource, eg org.greenstone.localsite. It should be a unique name amongst all the SOAP services that you want to connect to.
 
-The script makes sure that the SOAP servlet is deployed on Tomcat, and then deploys the service for the site specified. A resource file (\gst{sitename.xml}) is created which is used to specify the service. It can be found in \gst{gsdl3/resources/soap}, and is generated from \gst{site.xml.in}.
+The script  deploys the service for the site specified. A resource file (\gst{sitename.xml}) is created which is used to specify the service. It can be found in \gst{gsdl3/resources/soap}, and is generated from \gst{site.xml.in}.
 
 To get siteA to talk to siteB, you need to deploy a SOAP server on siteB, then add a \gst{<site>} element to the \gst{<siteList>} of siteA's \gst{siteConfig.xml} file (in \gst{gsdl3/web/sites/siteA/siteConfig.xml}).
@@ -2185,5 +2191,5 @@
 \section{Using \gsiii\  from CVS}\label{app:cvs}
 
-*** need to make sure building stuff is in here ***
+[TODO: need to make sure building stuff is in here]
 
 \gsiii\  is also available via CVS. You can download the latest version of the code. This is not guaranteed to be stable, in fact it is likely to be unstable. The advantage of using CVS is that you can update the code and get the latest fixes. 
@@ -2195,14 +2201,14 @@
 \begin{quote}\begin{gsc}\begin{verbatim}
 cvs -d :pserver:cvs\_anon@cvs.scms.waikato.ac.nz:2402/usr/local/
-           global-cvs/gsdl-src co gsdl3
+           global-cvs/gsdl-src co -P gsdl3
 \end{verbatim}\end{gsc}\end{quote}
 
 If you need it, the password for anonymous CVS access is \gst{anonymous}. Note that some older versions of CVS have trouble accessing this repository due to the port number being present. We are using version 1.11.1p1. 
 
-The software needs to be compiled and installed. The installation procedure has been semi-automated. The following sections describe installation under Linux and windows. 
+The software needs to be compiled and installed. The installation procedure has been semi-automated. The following sections describe installation under Linux and windows. The most up to date instructions may be found in the README.txt file in the top level gsdl3 directory.
 
 \subsection{Linux install}
 
-An install.sh script is provided to compile and install \gsiii\ . What you need to do is:
+What you need to do is:
 
 \begin{quote}\begin{gsc}
@@ -2210,7 +2216,10 @@
 source gs3-setup.sh\\
 ./gs3-prepare.sh\\
-./gs3-configure.sh \\
-./gs3-compile.sh \\
+./configure \\
+make \\
+make install \\
+\[make docs\] \\
 ./gs3-finalise.sh\\
+source gs3-setup.sh \\
 \end{gsc}\end{quote}
 
@@ -2225,4 +2234,5 @@
 \subsection{Windows install}
 
+[TODO: check that these are correct]
 Make sure that the following environment variables are set: JAVA\_HOME (where the JAva 2 SDK is installed); PATH (should include the CVS program, and \%JAVA\_HOME\%$\backslash$bin). The following commands should be run in a DOS prompt.
 
@@ -2247,49 +2257,4 @@
 
 To run \gs\ , run gs3-launch.bat. This will start the Tomcat server in a new DOS window (stop it by closing the window), and open a broser window showing the \gsiii\  homepage.
-
-\subsection{Creating a distribution}
-
-The installation scripts have been set up in such a way that it is easy to create different distribution types (for linux). To create a standard binary distribution, carry out the following steps:
-
-\begin{gsc}\begin{verbatim}
-cvs co gsdl3
-cd gsdl3
-source gs3-setup.sh
-./gs3-prepare.sh
-./gs3-configure.sh
-./gs3-compile.sh
-./gs3-for-distribution.sh
-
-mv Header ../
-cd ../
-tar czvf gsdl3.tgz gsdl3/
-cat Header gsdl3.tgz > gsdl3-x.xx-unix.sh
-\end{verbatim}\end{gsc}
-
-Note that gs3-for-distribution.sh removes some files that are not needed for the distribution, including all the CVS directories. Once you have run this, you will no longer be able to update your gsdl3 code via cvs.
-
-To create a source distribution, you can do:
-\begin{gsc}\begin{verbatim}
-cvs co gsdl3
-cd gsdl3
-source gs3-setup.sh
-./gs3-prepare.sh
-<delete unnecessary files>
-cd ../
-tar czvf gsdl3-x.xx-src.tgz gsdl3/
-\end{verbatim}\end{gsc}
-
-Some of the gs3-for-distribution script will need to be run (at the stage of delete unnecessary files), and there needs to be instructions on what to do when someone downloads the source distro.
- 
-I think it would be:
-\begin{gsc}\begin{verbatim}
-tar xzvf gsdl3-x.xx-src.tgz
-cd gsdl3
-source gs3-setup.sh
-./gs3-configure.sh
-./gs3-compile.sh
-./gs3-finalise.sh
-\end{verbatim}\end{gsc}
-
 
 \newpage
