Changeset 6930

Timestamp:

2004-03-04T17:06:26+13:00 (20 years ago)

Author:

kjdon

Message:

more changes

Location:

trunk/gsdl3/docs/manual

Files:

• manual.pdf (modified) ( previous)
• manual.tex (modified) (18 diffs)

trunk/gsdl3/docs/manual/manual.tex

@@ -395 +395 @@
 Collections live in the collect directory of a site. As described in Section~\ref{sec:sites-and-ints}, there can be several sites per \gsiii\  installation. The collect directory is at \$GSDL3HOME/web/sites/site-name/collect, where site-name is the name of the site you want your new collection to belong to.
 
-The following two sections describe how to create a collection from scratch, and how to import a \gsii\  collection. Once a collection has been built, the library server needs to be notified that there is a new collection. This can be accomplished in two ways\footnote{eventually there will also probably be automatic polling for new collections}. If you are the library administrator, you can restart Tomcat. The library servlet will then be created afresh, and will discover the new collection when it scans the collect directory for the collection list. Alternatively, there is a CGI command to reload a collection which can also load a new one. Use the CGI arguments \gst{a=s\&sa=a\&st=collection\&sn=collname}---this tells the library program to reload the collname collection.
+The following two sections describe how to create a collection from scratch, and how to import a \gsii\  collection. Once a collection has been built (and is located in the collect directory), the library server needs to be notified that there is a new collection. This can be accomplished in two ways\footnote{eventually there will also probably be automatic polling for new collections}. If you are the library administrator, you can restart Tomcat. The library servlet will then be created afresh, and will discover the new collection when it scans the collect directory for the collection list. Alternatively, an activate collection command can be issued to the servlet, using the arguments \gst{a=s\&sa=a\&st=collection\&sn=collname}, where \gst{collname} should be replaced with the collection name---this tells the library program to (re)load the \gst{collname} collection.
 
 
@@ -439 +439 @@
 The collectionConfig.xml file controls the all of these options for collection building, and the format is described in Section~\ref{sec:collconfig}.
 
-If a collectionConfig.xml file is not found, the \gsiii\  build process will import and use options, wherever possible, from a \gsii\  \gst{collect.cfg} file.  However, it is strongly recommended that a proper \gst{collectionConfig.xml} file is used wherever possible. [NOTE: I think we should require a proper config file for gs3 building--kjdon]
+If a collectionConfig.xml file is not found, the \gsiii\  build process will import and use options, wherever possible, from a \gsii\  \gst{collect.cfg} file.  However, it is strongly recommended that a proper \gst{collectionConfig.xml} file is used wherever possible. [NOTE: I think we should require a proper config file for gs3  building--kjdon]
 
 To build a collection, execute \gst{gs3build.sh sitename collectionname}.  The process will run, placing the new indexes in the \gst{building} subdirectory of the collection's directory. You must have mysql running before you start building---running \gst{gs3-launch.sh} will start up the mysql server as well as tomcat.
@@ -452 +452 @@
 The \gsiii\  run time system requires different configuration files for a collection, so you need to run a conversion script. All this does is create the new collectionConfig.xml and buildConfig.xml from the old collect.cfg and build.cfg files. It does not change the collection in any way, so it can still be used by \gsii\  software.
 
-The conversion script is \gst{convert\_coll\_from\_gs2.pl}. To run it, make sure you have sourced setup.bash (or run setup in Windows) in your top-level gsdl directory of the \gsii\  installation. Then you need to specify the path to the collect directory, and the collection name as parameters to the conversion script. For example, 
-
-\gst{convert\_coll\_from\_gs2.pl -collectdir \$GSDL3HOME/web/\-sites/\-localsite/\-collect demo}
-
-The script attempts to create gs3 format statements from the old \gsii\  ones. The conversion may not always work properly, so if the collection looks a bit strange under \gsiii\ , you should check the format statements. Format statements are described in Section~\ref{sec:formatstmt}.
+The conversion script is \gst{convert\_coll\_from\_gs2.pl}. To run it, make sure you have run \gst{source setup.bash} (or run setup in Windows) in your top-level gsdl directory of the \gsii\  installation (as well as running the standard \gst{gs3-setup} command). Then you need to specify the path to the collect directory and the collection name as parameters to the conversion script. For example, 
+
+\begin{gsc}
+\begin{verbatim}
+convert_coll_from_gs2.pl -collectdir 
+   $GSDL3HOME/web/sites/localsite/collect demo
+\end{verbatim}
+\end{gsc}
+%$
+The script attempts to create \gsiii\  format statements from the old \gsii\  ones. The conversion may not always work properly, so if the collection looks a bit strange under \gsiii\ , you should check the format statements. Format statements are described in Section~\ref{sec:formatstmt}.
 
 Once again, to have the collection recognised by the library servlet, you can either restart Tomcat, or load it dynamically.
@@ -462 +467 @@
 \subsection{Collection configuration files}\label{sec:collconfig}
 
-Each collection has two, or possibly three, configuration files, \gst{collectionConfig.xml} and \gst{buildConfig.xml}, and optionally \gst{collectionInit.xml} that give metadata, display and other information for the
+Each collection has two, or possibly three, configuration files, \gst{collectionConfig.xml} and \gst{buildConfig.xml}, and optionally \gst{collectionInit.xml}, that give metadata, display and other information for the
 collection.\footnote{\gst{collectionConfig.xml} and \gst{buildConfig.xml} replace \gst{collect.cfg} and \gst{build.cfg} in
 \gsii.}  The first includes user-defined presentation metadata for the collection,
@@ -550 +555 @@
 \end{figure}
 
-The \gst{<metadataList>} element specifies some collection metadata, such as creator. The \gst{<displayItemList>} specifies some language dependent information that is used for collection display, such as collection name and short description. These displayItem elements can be specified in different languages. If languages other than English are used, the configuration file should be encoded in UTF-8.
+The \gst{<metadataList>} element specifies some collection metadata, such as creator. The \gst{<displayItemList>} specifies some language dependent information that is used for collection display, such as collection name and short description. These displayItem elements can be specified in different languages. 
  
-The \gst{<search>} element specifies what indexes should be built, and provides some display and formatting information for each one. Search has an attribute, type, which specifies which indexer to be used for indexing. Currently, mg and mgpp are available. If type is not specified, mg is used. Multiple search elements may be specified, if more than one indexer is to be used.
+The \gst{<search>} element specifies what indexes should be built, and provides some display and formatting information for each one. Search has an attribute, \gst{type}, which specifies which indexer to be used for indexing. Currently, \gst{mg} and \gst{mgpp} are available. If type is not specified, mg is used. Multiple search elements may be specified, if more than one indexer is to be used. (Note, this is not yet recognised by the run-time system.)
 
 Search indexes appear as individual \gst{<index>} elements within the \gst{<search>} element. Some choices for the index are made using attributes of the element itself, and some through child elements.  
@@ -596 +601 @@
 The \gst{<display>} element contains optional formatting information for the display of documents. Templates that can be specified here include \gst{documentHeading}, \gst{DocumentContent}, and other information that could be specified (in a yet to be decided format) are things such as  whether or not to display the cover image, table of contents etc. 
 
-Format elements are desribed in more detail in Section~\ref{sec:formatstmt}.
+Format elements are desribed in Section~\ref{sec:formatstmt}.
 
 \subsection{buildConfig.xml}\label{sec:buildconfig}
@@ -605 +610 @@
 be determined automatically,  such as the number of
 documents it contains.  It also includes a list of ServiceRack classes that are
-required at runtime to provide the services that have been built into the
+required to provide the services that have been built into the
 collection.  The serviceRack names are Java classes that are loaded
 dynamically at runtime. Any information inside the serviceRack element is
-specific to that service---there is no set format. Figure~\ref{fig:buildconfig} shows an example. This configuration file specifies that the collection should load up 3 ServiceRacks: GS2MGPPRetrieve,  GS2MGPPSearch, and PhindPhraseBrowse. The contents of each \gst{<serviceRack>} element are passed to the appropriate ServiceRack objects for configuration. The collectionConfig.xml file is also passed to the ServiceRack objects at configure time---the \gst{format} and \gst{displayItem} information is used directly from the \gst{collectionConfig.xml} file rather than added into \gst{buildConfig.xml} during building. This enables changes in \gst{collectionConfig.xml} to take effect in the collection without rebuilding being necessary.
+specific to that service---there is no set format. Figure~\ref{fig:buildconfig} shows an example. This configuration file specifies that the collection should load up 3 ServiceRacks: \gst{GS2MGPPRetrieve},  \gst{GS2MGPPSearch}, and \gst{PhindPhraseBrowse}. The contents of each \gst{<serviceRack>} element are passed to the appropriate ServiceRack objects for configuration. The \gst{collectionConfig.xml} file content is also passed to the ServiceRack objects at configure time---the \gst{format} and \gst{displayItem} information is used directly from the \gst{collectionConfig.xml} file rather than added into \gst{buildConfig.xml} during building. This enables formatting and metadata changes in \gst{collectionConfig.xml} to take effect in the collection without rebuilding being necessary. However, as these files are cached, the collection needs to be reloaded for the changes to appear in the library.
 
 
@@ -663 +668 @@
 Part of collection design involves deciding how the collection should look. \gsiii\  has a default 'look' for a collection, so this is optional. However, the default may not suit the purposes of some collections, so many parts to the look of a collection can be determined by the collection designer.
 
-In standard \gsiii\ , the library is served to a web browser by a servlet, and the html is generated using XSLT. XSLT templates are used to format all the parts of the pages. Some commonly overwritten templates are those for formatting lists: search results list, classifier browsing hierarchies, and for parts of the document display. 
+In standard \gsiii\ , the library is served to a web browser by a servlet, and the HTML is generated using XSLT. XSLT templates are used to format all the parts of the pages. These templates can be overridden by including them in the \gst{collectionConfig.xml} file. Some commonly overridden templates are those for formatting lists: search results list, classifier browsing hierarchies, and for parts of the document display. 
 
 Real XSLT templates for formatting search results or classifier lists are quite complicated, and not at all easy for a new user to write. For example, the following is a sample template for formatting a classifier list, to show Keyword metadata as a link to the document.
@@ -680 +685 @@
 To write this, the user would need to know that:
 \begin{bulletedlist}
-\item the variable \$library\_name exists,
-\item the collection name is passed in as a parameter called collName
-\item metadata for a document is found in a metadataList and that its form is \gst{<metadata name="Keyword">the value</metadata>}
-\item the arguments needed for the link to the document are a, sa, c, d and dt.
+\item the variable \gst{\$library\_name} exists,
+\item the collection name is passed in as a parameter called \gst{collName}
+\item metadata for a document is found in a \gst{<metadataList>} and that its form is \gst{<metadata name="Keyword">the value</metadata>}
+\item the arguments needed for the link to the document are \gst{a, sa, c, d, a, dt}.
 \end{bulletedlist}
  
-Since XSLT is written in XML, we can use XSLT to transform XML into XSLT. \gsiii\  provides a simplified set of formatting commands, written in XML, which will be transformed into proper XSLT. Table~\ref{tab:gsf-format} shows the set of 'gsf' (Greenstone Format) elements. If you have come from a \gsii\  background, Appendix~\ref{app:format} shows \gsii\  format elements and their equivalents in \gsiii\ .
+Since XSLT is written in XML, we can use XSLT to transform XML into XSLT. \gsiii\  provides a simplified set of formatting commands, written in XML, which will be transformed into proper XSLT. The user specifies a \gst{<gsf:template>} for what they want to format---these typically match \gst{documentNode} or \gst{classifierNode} (for node in a classification hierarchy).
+ 
+The template at the start of this section can be represented as:
+ 
+\begin{gsc}\begin{verbatim}
+<gsf:template match='documentNode'>
+  <td><gsf:link><gsf:metadata name='Keyword'/></gsf:link></td>
+</gsf:template>
+\end{verbatim}\end{gsc}
+
+Table~\ref{tab:gsf-format} shows the set of 'gsf' (Greenstone Format) elements. If you have come from a \gsii\  background, Appendix~\ref{app:format} shows \gsii\  format elements and their equivalents in \gsiii\ .
  
 \begin{table}
@@ -734 +749 @@
 \end{table}
 
-The \gst{<gsf:metadata>} elements are used to output metadata values. The simplest case is \gst{<gsf:metadata name='Title'/>}---this outputs the Title metadata for the current document or section. Namespaces are important here: if the Title metadata is in the Dublin Core (dc) namespace, then the element should look like \gst{<gsf:metadata name='dc.Title'/>}. There are three other attributes for this element. 'multiple' is used when there may be more than one value for the selected metadata. For instance, one document may fall into several classification categories, and therefore may have multiple Subject metadata values. Adding \gst{multiple='true'} to the gsf:metadata element will retrieve all values, not just the first one. Multiple values are separated by commas by default. The separator attribute is used to change the separating string. For example, adding \gst{separator=': '} to the element will separate all values by a colon and a space.
-
-Sometimes you may want to display metadata values for sections other than the current one. For example, in the mgppdemo collection, in a search list we display the Title of all the enclosing sections, followed by the Title of the current section, all separated by semi-colons. The display ends up looking something like:
-Farming snails 2; Starting out; Selecting your snails
-where Selecting your snails is the Title of the section in the results list, and Farming snails 2 and Starting out are the Titles of the enclosing sections. The select attribute is used to display metadata for sections other than the current one. Table~\ref{tab:gsf-select-types} shows the options available for this attribute. The separator attribute is used here also, to specify the separating text.
+The \gst{<gsf:metadata>} elements are used to output metadata values. The simplest case is \gst{<gsf:metadata name='Title'/>}---this outputs the Title metadata for the current document or section. Namespaces are important here: if the Title metadata is in the Dublin Core (dc) namespace, then the element should look like \gst{<gsf:metadata name='dc.Title'/>}. There are three other attributes for this element. The attribute \gst{multiple} is used when there may be more than one value for the selected metadata. 
+For instance, one document may fall into several classification categories, and therefore may have multiple Subject metadata values. Adding \gst{multiple='true'} to the \gst{<gsf:metadata>} element will retrieve all values, not just the first one. Multiple values are separated by commas by default. The \gst{separator} attribute is used to change the separating string. For example, adding \gst{separator=':~'} to the element will separate all values by a colon and a space.
+
+Sometimes you may want to display metadata values for sections other than the current one. For example, in the mgppdemo collection, in a search list we display the Titles of all the enclosing sections, followed by the Title of the current section, all separated by semi-colons. The display ends up looking something like:
+\emph{Farming snails 2; Starting out; Selecting your snails}
+where \emph{Selecting your snails} is the Title of the section in the results list, and \emph{Farming snails 2} and \emph{Starting out} are the Titles of the enclosing sections. The \gst{select} attribute is used to display metadata for sections other than the current one. Table~\ref{tab:gsf-select-types} shows the options available for this attribute. The \gst{separator} attribute is used here also, to specify the separating text.
 
 To get the previous metadata, the format statement would have the following in it:
@@ -762 +778 @@
 root & The root or topmost section \\
 siblings & All the sibling sections\\
-children & The immediate children sections of the current section\\
+children & The immediate child sections of the current section\\
 descendents & All the descendent sections\\
 \hline
@@ -768 +784 @@
 \end{table}
 
-The gsf:choose-metadata element selects the first available metadata value from the list of options. 
+The \gst{<gsf:choose-metadata} element selects the first available metadata value from the list of options. 
 \begin{gsc}
 \begin{verbatim}
@@ -781 +797 @@
 This will display the dls.Title metadata if available, otherwise it will use the dc.Title metadata if available, otherwise it will use the Title metadata. If there are no values for any of these metadata elements, then nothing will be displayed.
 
-The gsf:switch element allows different formatting depending on the value of a specified metadata element. For example, the following switch statement could be used to display a different icon for each document in a list depending on which organisation it came from. 
+The \gst{<gsf:switch>} element allows different formatting depending on the value of a specified metadata element. For example, the following switch statement could be used to display a different icon for each document in a list depending on which organisation it came from. 
 
 \begin{gsc}
@@ -795 +811 @@
 \end{gsc}
 
-Preprocessing of the metadata value is optional. The preprocess types are toLower (make the value lowercase), toUpper (make the value uppercase), stripSpace (removes any whitespace from the value). These operations are carried out on the value of the selected metadata before the test is carried out. Multiple processing types can be specified, separated by ; and they will be applied in the order specified (from left to right).
-
-Each option specifies a test and a test value. Test values are just text. Tests include startsWith, contains, exists, equals, endsWith. Exists doesn't need a test value. Having an otherwise option ensures that something will be displayed even when none of the tests match.
-
+Preprocessing of the metadata value is optional. The preprocess types are \gst{toLower} (make the value lowercase), \gst{toUpper} (make the value uppercase), \gst{stripSpace} (removes any whitespace from the value). These operations are carried out on the value of the selected metadata before the test is carried out. Multiple processing types can be specified, separated by ; and they will be applied in the order specified (from left to right).
+
+Each option specifies a test and a test value. Test values are just text. Tests include \gst{startsWith}, \gst{contains}, \gst{exists}, \gst{equals}, \gst{endsWith}. Exists doesn't need a test value. Having an otherwise option ensures that something will be displayed even when none of the tests match.
 
 If none of the gsf elements meets your needs for formatting, XSLT can be entered directly into the format element, giving the collection designer full flexibility over how the collection appears. 
 
-The collection specific templates are added into the configuration file \gst{collectionConfig.xml}. Any templates found in the XSLT files can be overwritten.
+The collection specific templates are added into the configuration file \gst{collectionConfig.xml}. Any templates found in the XSLT files can be overridden.
 The important part to adding templates into the configuration file is determining where to put them. Formatting templates cannot go just anywhere---there are standard places for them. Figure~\ref{fig:format-places} shows the positions that templates can occur.
 
@@ -847 +862 @@
 \end{figure} 
 
-The user specifies a \gst{<gsf:template>} for what they want to format---these can match \gst{documentNode} or \gst{classifierNode} (for node in a classification hierarchy).
- 
-The template at the start of this section  is now represented as:
- 
-\begin{gsc}\begin{verbatim}
-<gsf:template match='documentNode'>
-  <td><gsf:link><gsf:metadata name='Keyword'/></gsf:link></td>
-</gsf:template>
-\end{verbatim}\end{gsc}
  
 There are also formatting instructions that are not templates but are options. 
@@ -876 +882 @@
 Note, format templates are added into the XSLT files before transforming, while the options are added into the page source, and used in tests in the XSLT.
 
-For local collections\footnote{and eventually remote collections} whole XSLT files can be overridden. A collection can have a transform directory. Any XSLT files in here will be used in preference to the interface files when using this collection. For example, if you want to have a completely different about page for the collection, you can put a new about.xsl into the collections transform directory, and this will be used instead. This is what we do for the Gutenberg sample collection.
-
-
 \subsection{Customising the interface}\label{sec:interface-customise}
 
-The interface can be customised in several ways.
-adding a new interface, adding a new language, \\
-changing the look and feel for an interface vs a site vs a collection\\
-
-what needs a Tomcat restart?
+Format statements in the collection configuration files provide a way to change small parts of the collection display. For large scale customisations to a collection, or ones that apply to a site as a whole, a second mechanism is available. The interface is defined by a set of XSLT files that transform the page data into HTML. Any of these files can be overridden to provide specialised display, on a site or collection basis. 
+
+The first section looks at customizing the existing interface, while the second section looks at defining a whole new interface. The last section describes how to ad a new language translation of an interface.
+
+\subsubsection{Modifying an existing interface}
+
+Most of an interface is defined by XSLT files, which are stored in \gst{\$GSDL3HOME/\-web/\-interfaces/\-interface-name/\-transform}. These can be changed and the changes will take effect straight away. If changes only apply to certain collections or sites, not everything that uses the interface, you can override some of the files by putting new ones in a different place. XSLT files are looked for in the following  order: collection, site, interface, default interface. (This currently only apples to sites, and therefore collections, that reside in the same \gs\  installation as the interface.) 
+
+Sites and collections can have a transform directory, which is where customised XSLT files should go. Any XSLT files in here will be used in preference to the interface files when using this collection. For example, if you want to have a completely different layout for the about page of a collection, you can put a new \gst{about.xsl} file into the collection's \gst{transform} directory, and this will be used instead. This is what we do for the Gutenberg sample collection.
+
+This also applies to files that are included from other XSLT files. For example the query.xsl for the query pages includes a file called querytools.xsl. To have a particular site show a different query interface either of these files may need to be modified. Creating a new version of either of these and putting it in the site transform directory will work. Either the new query.xsl will include the default querytools, or the default query.xsl will include the new querytools.xsl. The xsl:include directives are preprocessed by the java code and full paths added based on availability of the files, so that the correct one is used.
+
+Note that you cannot include a file with the same name as the including file. For example query.xsl cannot include query.xsl (it is tempting to want to do this if you just want to change one template for a particular file, and then include the default. but you cant).
+
+\subsubsection{Defining a new interface}
+
+A new interface may be needed if different instantiations of the library require different interfaces, or different developers want their own look and feel. Creating a new interface will allow modifications to be made while leaving the original one intact. 
+
+A new interface needs a directory in \gst{\$GSDL3HOME/web/interfaces}, the name of this directory becomes the interface name. Inside, it needs images and transform directories,  and an interfaceConfig.xml file. Any XSLT may be overridden for a new interface by putting the replacement in the new transform directory. If the appropriate XSLT file is not there, the  one from the default interface will be used - this enables just overriding a few XSLT files as needed.
+
+To use a new interface, the Tomcat web.xml must be edited: either change the interface that a current servlet instance is using, or add another servlet instantiation to the file (see Section~\ref{sec:sites-and-ints} or Appendix~\ref{app:tomcat}). The Tomcat server must be restarted for this to take effect.
 
 \subsubsection{Changing the interface language}
 
-The interface language can be changed by going to the preferences page, and choosing a language from the list. The list lists (:-)) all languages in which the interface has been defined  so far.
-
-It is easy to add a new interface language to \gs\ .  Language specific text strings are separated out from the rest of the system to allow for easy incorporation of new languages. These text strings are contained in Java resource bundle properties files. These are plain text files consisting of key-value pairs, located in resources/java. Each interface has one named interface\_name.properties (where `name' is the interface name). Each service class has one with the same name as the class (e.g. GS2Search.properties). To add another language all of the base .properties  files must be translated. The translated files keep the same names, but with a language extension added. For example, a French version of interface\_default.properties would be named interface\_default\_fr.properties.
-
-Keys will be looked up in the properties file closest to the specified language. For example, if language fr\_CA was specified (french language, country Canada), and the default locale was en\_GB,  java would look at properties files in the following order, until it found the key: XXX\_fr\_CA.properties, XXX\_fr.properties,  XXX\_en\_GB.properties, then XXX\_en.properties, and finally the default XXX.properties.
-
-You can tell \gs\  about a new language by adding it in to the languageList in the interfaceConfig.xml file. This will add it in to the list of languages on the preferences page. Modification of this file requires a restart of the Tomcat server for the changes to be recognised.
-
-
-\subsubsection{Modifying an existing interface}
-
-Most of an interface is defined by XSLT files, which are stored in \$GSDL3HOME/\-web/\-interfaces/\-interface-name/\-transform. These can be changed and the changes will take affect straight away. If changes only apply to certain collections or sites, not everything that uses the interface, you can override some of the files by putting new ones in a different place. XSLT files are looked for in the following  order: collection, site, interface, default interface. (This currently only apples to sites, and therefore collections, that reside in the same \gs\  installation as the interface.) This also applies to files that are included from other XSLT files. For example the query.xsl for the query pages includes a file called querytools.xsl. To have a particular site show a different query interface either of these files may need to be modified. Creating a new version of either of these and putting it in the site transform directory will work. Either the new query.xsl will include the default querytools, or the default query.xsl will include the new querytools.xsl. The xsl:include directives are preprocessed by the java code and full paths added based on availability of the files, so that the correct one is used.
-
-Note that you cannot include a file with the same name as the including file. For example query.xsl cannot include query.xsl (it is tempting to want to do this if you just want to change one template for a particular file, and then include the default. but you cant).
-
-\subsubsection{Defining a new interface}
-
-A new interface may be needed if different instantiations of the library require different interfaces, or different developers want their own look and feel. Creating a new interface will allow modifications to be made while leaving the original one intact. 
-
-A new interface needs a directory in \$GSDL3HOME/web/interfaces, the name of this directory becomes the interface name. Inside, it needs images and transform directories,  and an interfaceConfig.xml file. Any XSLT may be overridden for a new interface by putting the replacement in the new transform directory. If the appropriate XSLT file is not there, the  one from the default interface will be used - this enables just overriding a few XSLT files as needed.
-
-To use a new interface, the Tomcat web.xml must be edited: either change the interface that a current version of the servlet is using, or add another servlet instantiation to the file (see Section~\ref{sec:sites-and-ints} or Appendix~\ref{app:tomcat}). The Tomcat server must be restarted for this to take effect.
+The interface language can be changed by going to the preferences page, and choosing a language from the list, which includes all languages into which the interface has been translated.
+
+It is easy to add a new interface language to \gs\ .  Language specific text strings are separated out from the rest of the system to allow for easy incorporation of new languages. These text strings are contained in Java resource bundle properties files. These are plain text files consisting of key-value pairs, located in \gst{resources/java}. Each interface has one named \gst{interface\_name.properties} (where `name' is the interface name). Each service class has one with the same name as the class (e.g. \gst{GS2Search.properties}). To add another language all of the base .properties  files must be translated. The translated files keep the same names, but with a language extension added. For example, a French version of \gst{interface\_default.properties} would be named \gst{interface\_default\_fr.properties}.
+
+Keys will be looked up in the properties file closest to the specified language. For example, if language \gst{fr\_CA} was specified (french language, country Canada), and the default locale was \gst{en\_GB},  java would look at properties files in the following order, until it found the key: \gst{XXX\_fr\_CA.properties}, \gst{XXX\_fr.properties},  \gst{XXX\_en\_GB.properties}, then \gst{XXX\_en.properties}, and finally the default \gst{XXX.properties}.
+
+These new files are available straight away---to use the new language, add e.g. \gst{l=fr} to the arguments in the URL. To get \gs\ to add it in to the list of languages on the preferences page, an entry needs to be added into the languagss list in the \gst{interfaceConfig.xml} file (see Section~\ref{sec:interfaceconfig}). Modification of this file requires a restart of the Tomcat server for the changes to be recognised.
 
 \newpage 
-\section{Developing \gsiii\ : Run-time system}\label{sec:develop-runtime}
+\section{Developing \gsiii : Run-time system}\label{sec:develop-runtime}
 
 [TODO: rewrite this!!]
@@ -1965 +1969 @@
 * should a metadata retrieval service advertise what metadata is available??
 
-standard service type vs new service type - standrad needs some xml response syntax.
+standard service type vs new service type - standard needs some xml response syntax.
 
 \subsection{creating new actions/pages}\label{sec:new-pages}
@@ -2076 +2080 @@
 
 \subsection{Serving a site using soap}
-what do we have to do?? resource file format, deploy the service etc.
+
+A script has been created to setup a SOAP server for a site. On Linux, from the gsdl3 directory, run
+\gst{./gs3-soap-deploy-site.sh <sitename> <siteuri>}
+
+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}.
+
+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}).
+
+In the \gst{<siteList>} element, add the following (substituting the chosen site uri for siteAuri):
+
+\begin{gsc}\begin{verbatim}
+<site name="siteAuri"
+  address="http://localhost:8080/soap/servlet/rpcrouter"
+  type="soap"/>
+\end{verbatim}\end{gsc}
+
+(Note that localhost and 8080 should be changed to the values you entered when installing \gsiii).
 
 \appendix