Context Navigation

← Previous Changeset
Next Changeset →

Changeset 6422

Timestamp:

2004-01-09T18:06:22+13:00 (20 years ago)

Author:

kjdon

Message:

more changes

File:

: 1 edited

trunk/gsdl3/docs/manual/manual.tex (modified) (39 diffs)

Legend:

: Unmodified
: Added
: Removed

trunk/gsdl3/docs/manual/manual.tex

-              r6343
+              r6422
 This documentation consists of several parts. Section~\ref{sec:install} covers greenstone installation, how to access the library, and some administration issues. Section~\ref{sec:user} looks at using the sample collections, creating new collections, and how to make small customisations to the interface. The remaining sections are aimed towards  the Greenstone developer. Section~\ref{sec:develop-runtime} describes the run-time system, including the structure of the software, and the message format, while Section~\ref{sec:develop-build} describes the collection building process. Section~\ref{sec:new-features} describes how to add new features to Greenstone, such as how to add new services, new page types, new plugins for different document formats.  Section~\ref{sec:distributed} describes how to make Greenstone run in a distributed fashion, using SOAP as an example communications protocol. Finally, there are several appendices, including how to install Greenstone from CVS, and a comparison of greenstone 2 and greenstone 3 format statements.
+\newpage
 \section{Greenstone installation and administration}\label{sec:install}
 This section covers where to get Greenstone 3 from, how to install it and how to run it. The standard method of running Greenstone is as a Java servlet. We provide the Tomcat servlet container to serve the servlet :-). Standard web servers may  be able to be configured to provide servlet support, and thereby remove the need to use Tomcat. Please see your web server documentation for this. This documentation assumes that you are using Tomcat. To access Greenstone, tomcat must be started up, and then it can be accessed via a web browser.
+\subsection{Get and install Greenstone}
+Greenstone is available from www.... There are currently two distributions: a self-installing tar for Linux, and a Windows executable.
 Greenstone is also available through CVS (Concurrent Versioning System). This provides the absolute latest development version, and is not guaranteed to be stable. Appendix~\ref{app:cvs} describes how to download and install Greenstone from CVS.
-\subsection{Get and install Greenstone}
-Greenstone is available from www.... There are currently two distributions: a self-installing tar for Linux, and a Windows executable.
 \subsubsection{Linux}
+Download the file gsdl3-0.01-unix.sh. Then run it in a shell (./gsdl3-0.01-unix.sh). It will prompt you for where to install greenstone to, the name of your computer, what port to run tomcat on... Once Greenstone has been installed, you can start the library  by running ./gsdl3.sh, and opening up a browser pointing to localhost:8080/gsdl3 (or different computer name and port).
+** add more once installer finished **
+Download the latest version of the self-installing tar file, gsdl3-x.xx-unix.sh, and run it in a shell (./gsdl3-x.xx-unix.sh). It will prompt you for where to install greenstone to, the name of your computer, what port to run tomcat on... Once Greenstone has been installed, you can start the library  by running ./gsdl3.sh, and opening up a browser pointing to localhost:8080/gsdl3 (or different computer name and port).
 \subsubsection{Windows}
+Download the gsdl3-0.01-win32.exe file and double click it to start the installation. You will be prompted for ... Once Greenstone is installed, you can access the library by selecting Greenstone 3 Digital Library in the Start menu.
+\subsubsection{Other notes}
+To run Greenstone we are starting up the Tomcat server, and a mysql database server.
+Once Greenstone has been installed, you can run tomcat, and access it in a browser at\gst{http://localhost:8080/gsdl3}---this gets you to a welcome page. From here, you can select to run the test servlet, the standard library servlet, and the remote servlet.
+\noindent Note: Tomcat must be shutdown and restarted any time you make changes in the following for those changes to take effect:\\
+** add more once installer finished **
+Download the latest Windows executable, gsdl3-x.xx-win32.exe, and double click it to start the installation. You will be prompted for ... Once Greenstone is installed, you can access the library by selecting Greenstone 3 Digital Library in the Start menu.
+\subsubsection{Accessing the library in a browser}
+Once you have started up the library (see the previous sections for OS dependent instructions), you can access it in a browser at http://localhost:8080/gsdl3 (or http://your-computer-name/your-chosen-port/gsdl3). This gets you to a welcome page, with three links: one to run a test servlet (this allows you to check that tomcat is running properly), one to run the standard library servlet using localsite, and one to run a library servlet using the site soapsite. This site uses a SOAP connection to communicate with localsite, and demonstrates the library working in a distributed fashion. See Section~\ref{sec:distributed} for details about how to run Greenstone distributedly.
+\subsection{How the library works}
+The standard library program is a Java servlet.
+Other types of interfaces can be used, such as Java GUI programs. See Section~\ref{sec:new-interfaces} for details about how to make these.
+\subsubsection{Restarting the library}
+The library program (actually tomcat) can be restarted by ... (** put a mechanism in each install program **).
+Tomcat must be shutdown and restarted any time you make changes in the following for those changes to take effect:\\
 \begin{bulletedlist}
 \begin{gsc}
 …
 \item any classes or jar files used by the servlets
 \end{bulletedlist}
 \noindent Note: stdin and stdout for the servlets both go to\\
+\noindent Note: stdout and stderr for the servlets both go to\\
 \gst{\gsdlhome/comms/jakarta/tomcat/logs/catalina.out}
 …
 \caption{The Greenstone directory structure}
 \label{tab:dirs}
 \center{\footnotesize
+{\footnotesize
 \begin{tabular}{l p{8cm}}
+\hline
+\bf directory & \bf description \\
 \hline
 gsdl3
 …
 where they live, whats the difference, what each contains.\\
+There are two Greenstone {\em sites} that come with the checkout: localsite, and soapsite. localsite has three collections, while soapsite has none. Each site has a configuration file which specifies the site name, site-wide services if any, and a list of remote sites to connect to.
+localsite does not connect to any other sites. soapsite specifies a SOAP connection to localsite.
+Talk here about matching site with an interface.
+The file \gst{\gsdlhome/web/WEB-INF/web.xml} contains the setup information for Tomcat---tells it what servlets to load, what initial parameters to pass them, and what web names map to the servlets.
+There are three servlets specified in web.xml: one is a test servlet that just prints ``hello greenstone'' to a web page. This is useful if you are having trouble getting Tomcat set up. The other two are Greenstone library servlets, {\em library}, which serves localsite, and {\em library1} which serves soapsite.
+A site is comprised of a set of collections and possibly services. An interface is a set of images along with a set of xslt files used for translating xml output from the library into an appropriate form---html for the servlet case.
+One greenstone installation can have many sites and interfaces. One instantiation of a servlet uses one site and one interface. Sites and interfaces can be matched up in different ways. For example, a single site might be served with two different interfaces. This provides different modes of access to the same content. eg HTML vs WML, or perhaps providing completely different look and feel for different audiences. A standard interface may be used with many different sites---provides a consistent mode of access to a lot of different content.
+Collections live in the collect directory of a site. Any collections that are found in this directory when the servlet is initialised will be loaded up and presented to the user. Collections require valid configuration files, but apart from this, nothing needs to be done to the site to use new collections. Collection is added while tomcat is running will not be picked up: you can either restart the server, or send a configuration request to the servlet: these are described in Section~\ref{sec:runtime-config}.
+There are two Greenstone sites that come with the distribution: localsite, and soapsite. localsite has several demo  collections, while soapsite has none. soapsite specifies that a soap connection should be made to localsite. Getting this to work involves setting up a soap server for localsite: see Section~\ref{sec:distributed} for details.
+Each site and interface has a configuration file which specifies parameters for the site or interface---these are described in Section~\ref{sec:config}.
+The file \gst{\gsdlhome/web/WEB-INF/web.xml} contains the setup information for Tomcat. It tells Tomcat what servlets to load, what initial parameters to pass them, and what web names map to the servlets.
+There are three servlets specified in web.xml (these correspond to the three links in the welcome page for greenstone): one is a test servlet that just prints ``hello greenstone'' to a web page. This is useful if you are having trouble getting Tomcat set up. The other two are Greenstone library servlets, {\em library}, which serves localsite, and {\em library1} which serves soapsite. Both of these servlets use the standard interface (called {\em default}).
 \begin{table}
 \caption{Greenstone servlet initialisation parameters}
 \label{tab:serv-init}
+{\footnotesize
 \begin{tabular}{llp{5cm}}
+\hline
 \bf name & \bf sample value & \bf description \\
 \hline
 gsdl3home & /research/kjdon/gsdl3 & the base directory of the gsdl3 installation \\
 sitename & localsite & the site to use \\
 interfacename & default & the interface to use\\
 libraryname & library & the name of the library program \\
 defaultlang & en & the default language for the interface\\
 receptionist & NZDLReceptionist & (optional) specifies an alternative Receptionist to use\\
 messagerouter & NewMessageRouter & (optional) specifies an alternative MessageRouter to use\\
 \hline
 \end{tabular}
+gsdl3\_home & /research/kjdon/gsdl3 & the base directory of the gsdl3 installation \\
+site\_name & localsite & the name of the site to use \\
+interface\_name & default & the name or the interface to use\\
+library\_name & library & the web name of the servlet \\
+default\_lang & en & the default language for the interface\\
+receptionist\_class & NZDLReceptionist & (optional) specifies an alternative Receptionist to use\\
+messagerouter\_class & NewMessageRouter & (optional) specifies an alternative MessageRouter to use\\
+\hline
+\end{tabular}}
 \end{table}
+The initialisation parameters used by the library servlets are shown in Table~\ref{tab:serv-init}. The most important parameters are sitename and interface name. Each servlet running uses one site and one interface. You can run multiple servlets, all using different combinations of site and interface.
+\subsection{Configuring a greenstone installation}
+The initialisation parameters used by the library servlets are shown in Table~\ref{tab:serv-init}. This is where you define what site and interface each servlet uses. Any number of servlets can be specified here. See Appendix~\ref{app:tomcat} for more details about Tomcat.
+\subsection{Configuring a greenstone installation}\label{sec:config}
 Initial Greenstone3 system configuration is determined by a set of configuration files, all expressed in XML. Each site has a configuration file that binds parameters for the site, \gst{siteConfig.xml}. Each interface has a configuration file, \gst{interfaceConfig.xml}, that specifies Actions for the interface. Collections also have several configuration files; these are discussed in Section~\ref{sec:collconfig}.
 The configuration files are read in when the system is initialised, and their contents are cached in memory. This means that changes made to these files once the system is running will not take immediate effect. Tomcat needs to be restarted for changes to the interface configuration file to take effect. However, changes to the site configuration file can be incorporated sending a CGI-type command to the library. CGI command can be sent to the library are made to the interface configuration file, tomcat needs to be restarted. There are a series of CGI-type commands that can be sent to the library to induce reconfiguration of different modules, including reloading the whole site. This removes the need to shutdown and restart the system to reflect these changes. These commands are described in Section~\ref{sec:runtime-config}.
+The configuration files are read in when the system is initialised, and their contents are cached in memory. This means that changes made to these files once the system is running will not take immediate effect. Tomcat needs to be restarted for changes to the interface configuration file to take effect. However, changes to the site configuration file can be incorporated sending a CGI-type command to the library.  There are a series of CGI-type commands that can be sent to the library to induce reconfiguration of different modules, including reloading the whole site. This removes the need to shutdown and restart the system to reflect these changes. These commands are described in Section~\ref{sec:runtime-config}.
 \subsubsection{Site configuration file}\label{sec:siteconfig}
 …
 collections directory.
 The HTTP address is used for retrieving resources from a site outside the XML protocol. Because a site is HTTP accessible, any files (e.g. images) belonging to that site or to its collections can be specified in the HTML of a page by a URL. This avoids having to retrieve these files from a remote site via the XML protocol\footnote{Currently, sites live inside the Tomcat gsdl3 root context, and therefore all their content is accessible over HTTP via the Tomcat address. We need to see if parts can be restricted. Also, if we use a different protocol, then resources from remote sites may need to come through the XML. Also, if we are running locally without using Tomcat, we may want to get them via file:// rather than http://.}.
+The HTTP address is used for retrieving resources from a site outside the XML protocol. Because a site is HTTP accessible through Tomcat, any files (e.g. images) belonging to that site or to its collections can be specified in the HTML of a page by a URL. This avoids having to retrieve these files from a remote site via the XML protocol\footnote{Currently, sites live inside the Tomcat gsdl3 root context, and therefore all their content is accessible over HTTP via the Tomcat address. We need to see if parts can be restricted. Also, if we use a different protocol, then resources from remote sites may need to come through the XML. Also, if we are running locally without using Tomcat, we may want to get them via file:// rather than http://.}.
 Figure~\ref{fig:siteconfig} shows two example site configuration files. The first example is for a rudimentary site with no site-wide services,
 …
         <metadata name="Title">Collection builder</metadata>
         <metadata name="Description">Builds collections in a
                 gsdl2-style manner</metadata>
+           gsdl2-style manner</metadata>
       </metadataList>
       <serviceRackList>
 …
       <subaction name='home' xslt='home.xsl'/>
       <subaction name='about' xslt='about.xsl'/>
+      <subaction name='help' xslt='help.xsl'/>
+      <subaction name='pref' xslt='pref.xsl'/>
     </action>
     <action name='q' class='QueryAction' xslt='basicquery.xsl'/>
     <action name='b' class='BrowseAction' xslt='classifier.xsl'/>
+    <action name='b' class='GS2BrowseAction' xslt='classifier.xsl'/>
     <action name='a' class='AppletAction' xslt='applet.xsl'/>
     <action name='d' class='DocumentAction' xslt='document.xsl'/>
+    <action name='xd' class='XMLDocumentAction'>
+      <subaction name='toc' xslt='document-toc.xsl'/>
+      <subaction name='text' xslt='document-content.xsl'/>
+    </action>
     <action name='pr' class='ProcessAction' xslt='process.xsl'/>
     <action name='s' class='SystemAction' xslt='system.xsl'/>
 …
 </interfaceConfig>
 \end{verbatim}\end{gsc}
 \caption{A sample interface configuration file}
+\caption{Default interface configuration file}
 \label{fig:ifaceconfig}
 \end{figure}
 …
 \caption{Example run-time configuration arguments.}
 \label{tab:run-time config}
+{\footnotesize
 \begin{tabular}{lp{8cm}}
+\hline
 \gst{a=s\&sa=c} & reconfigures the whole site, reads in siteConfig.xml, reloads all the collections. Just part of this can be specified with another argument \gst{ss} (system subset). The valid values are \gst{collectionList}, \gst{siteList}, \gst{serviceList}, \gst{clusterList}. \\
 \gst{a=s\&sa=c\&sc=XXX} & reconfigures the XXX collection or cluster. \gst{ss} can also be used here, valid values are \gst{metadataList} and \gst{serviceList}. \\
 \gst{a=s\&sa=a} & (re)activate a specific module. Modules are specified using two arguments, \gst{st} (system module type) and \gst{sn} (system module name). Valid types are \gst{collection}, \gst{cluster} \gst{site}.\\
 \gst{a=s\&sa=d} & deactivate a module. \gst{st} and \gst{sn} can be used here too. Valid types are \gst{collection}, \gst{cluster}, \gst{site}, \gst{service}. Modules are removed from the current configuration, but will reappear if Tomcat is restarted.\\
+\gst{a=s\&sa=d\&sc=XXX} & deactivate a module belonging to the XXX collection or cluster. \gst{st} and \gst{sn} can be used here too. Valid types are \gst{service}. \\\end{tabular}
+\gst{a=s\&sa=d\&sc=XXX} & deactivate a module belonging to the XXX collection or cluster. \gst{st} and \gst{sn} can be used here too. Valid types are \gst{service}. \\
+\hline
+\end{tabular}}
 \end{table}
+\newpage
 \section{Using Greenstone 3}\label{sec:user}
 …
 \subsection{Collection configuration files}\label{sec:collconfig}
 Each collection has two configuration files, \gst{collectionConfig.xml} and \gst{buildConfig.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{siteConfig.xml} and \gst{interfaceConfig.xml} is new for Greenstone3, while \gst{collectionConfig.xml} and \gst{buildConfig.xml} replace \gst{collect.cfg} and \gst{build.cfg} in
 Greenstone2.}  The first includes user-defined presentation metadata for the collection,
 …
 the build-time process and includes any metadata that can be determined
 automatically. It also includes configuration information for any ServiceRacks needed by the collection.
+\subsubsection{collectionInit.xml}
+This optional file specifies a new collection class if the standrad one is not to be used. The only syntax so far is the class name:
+\begin{gsc}\begin{verbatim}
+<collectionInit class="XMLCollection"/>
+\end{verbatim}\end{gsc}
+Section~\ref{sec:new-coll-types} describes an example collection where this file is used. Depending on the type of collection that this is used for, one or both of the other config files may not be needed.
+\subsubsection{collectionConfig.xml}
 The collection configuration file is where the collection designer (e.g. a librarian) decides what form the collection should take. This includes the collection metadata such as title and description, and also includes what indexes and browsing structures should be built. The format of \gst{collectionConfig.xml} is still under consideration. However, Figure~\ref{fig:collconfig} shows the parts of it that have been defined so far. (Since collection building at this stage is still done using Greenstone2 Perl scripts and the old \gst{collect.cfg} file, we have only defined the format for the parts of \gst{collectionConfig.xml} that are used by the runtime-system.)
 …
     <classifier name="CL4">
       <format>
     <gsf:template match="documentNode">
+        <gsf:template match="documentNode">
           <br /><gsf:link><gsf:metadata name='Keyword' />
             </gsf:link></gsf:template>
 …
 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.
 \subsection{Building configuration file}\label{sec:buildconfig}
+\subsection{buildConfig.xml}\label{sec:buildconfig}
 The file \gst{buildConfig.xml} is produced by the collection building process, and contains  metadata and other information about the collection that can
 …
 </buildConfig>
 \end{verbatim}\end{gsc}
 \caption{Sample buildConfig.xml file}
+\caption{Sample buildConfig.xml file (mgppdemo collection)}
 \label{fig:buildconfig}
 \end{figure}
 …
 \caption{Format elements for GSF format language}
 \label{tab:gsf-format}
+\begin{tabular}{ll}
+{\footnotesize
+\begin{tabular}{p{6.5cm}p{6.5cm}}
+\hline
 \bf Element       & \bf Description \\
+\gst{<gsf:text/>} & The document's  text\\
+\hline
+\gst{<gsf:text/>} & The document's text\\
 \gst{<gsf:link>...</gsf:link>} & The HTML link to the document itself \\
+\gst{<gsf:link type='document'>...</gsf:link>} & Same as above\\
+\gst{<gsf:link type='classifier'>...</gsf:link>} & A link to a classification node (use in classifierNode templates)\\
+\gst{<gsf:link type='source'>...</gsf:link>} & The HTML link to the original file---set for documents that have been converted from e.g. Word, PDF, PS \\
+\gst{<gsf:link type='document'>...
+</gsf:link>} & Same as above\\
+\gst{<gsf:link type='classifier'>...
+</gsf:link>} & A link to a classification node (use in classifierNode templates)\\
+\gst{<gsf:link type='source'>...
+</gsf:link>} & The HTML link to the original file---set for documents that have been converted from e.g. Word, PDF, PS \\
 \gst{<gsf:icon/>}  & An appropriate icon\\
 \gst{<gsf:icon type='document'/>} & same as above\\
 …
 </gsf:choose-metadata>}
  & A choice of metadata. Will select the first existing one. the metadata elements can have the select, separator and multiple attributes like normal.\\
+\gst{<gsf:switch preprocess='preprocess-type'>
+<gsf:metadata name='Title'/><gsf:when test='test-type' test-value='xxx'>.....</gsf:when><gsf:when test='test-type' test-value='xxx'>...</gsf:when><gsf:otherwise>...</gsf:otherwise></gsf:switch>} & switch on the value of a particular metadata - the metadata is specified in gsf:metadata, has the same attributes as normal.\\
+\end{tabular}
+\gst{<gsf:switch preprocess=
+'preprocess-type'>
+<gsf:metadata name='Title'/>
+<gsf:when test='test-type'
+test-value='xxx'>...</gsf:when>
+<gsf:when test='test-type'
+test-value='yyy'>...</gsf:when>
+<gsf:otherwise>...</gsf:otherwise>
+</gsf:switch>} & switch on the value of a particular metadata - the metadata is specified in gsf:metadata, has the same attributes as normal.\\
+\hline
+\end{tabular}}
 \end{table}
 …
 To get the previous metadata, the format statement would have the following in it:
+\gst{<gsf:metadata name='Title' select='ancestors' separator='; '/>; <gsf:metadata name='Title'/>}
+\begin{gsc}
+\begin{verbatim}
+<gsf:metadata name='Title' select='ancestors' separator='; '/>;
+    <gsf:metadata name='Title'/>
+\end{verbatim}
+\end{gsc}
 \begin{table}
 \caption{Select types for metadata format elements}
 \label{tab:gsf-select-types}
+{\footnotesize
 \begin{tabular}{ll}
 \hline
 …
 descendents & All the descendent sections\\
 \hline
 \end{tabular}
+\end{tabular}}
 \end{table}
 …
 \begin{gsc}
 \begin{verbatim}
+<gsf:choose-metadata><gsf:option name='dc.Title'/><gsf:option name='dls.Title'/><gsf:option name='Title'/></gsf:choose-metadata>
+<gsf:choose-metadata>
+  <gsf:option name='dc.Title'/>
+  <gsf:option name='dls.Title'/>
+  <gsf:option name='Title'/>
+</gsf:choose-metadata>
 \end{verbatim}
 \end{gsc}
 …
 \begin{verbatim}
 <gsf:switch metadata='Organization' preprocess='toLower;stripSpace'>
+  <gsf:when test='equals' test-value='bostid'><!-- output BOSTID image --></gsf:when>
+  <gsf:when test='equals' test-value='worldbank'><!-- output world bank image --></gsf:when>
+  <gsf:when test='equals' test-value='bostid'>
+     <!-- output BOSTID image --></gsf:when>
+  <gsf:when test='equals' test-value='worldbank'>
+     <!-- output world bank image --></gsf:when>
   <gsf:otherwise><!-- output default image--></gsf:otherwise>
 </gsf:switch>
 …
   <search>
     <format> <!--Put here templates related to searching and
     the query page. The common one is the documentNode
     template -->
+        the query page. The common one is the documentNode
+        template -->
       <gsf:template match='documentNode'>...</gsf:template>
     </format>
 …
     <classifier name='xx'>
       <format><!-- put here templates related to formating a
     particular classifier page. Common ones are documentNode
     and classifierNode templates-->
+        particular classifier page. Common ones are documentNode
+        and classifierNode templates-->
         <gsf:template match='documentNode'>...</gsf:template>
         <gsf:template match='classifierNode'>...</gsf:template>
         <gsf:template match='classifierNode' mode='horizontal'>...
       </gsf:template>
+          </gsf:template>
       </format>
     </classifier>
 …
   <display>
     <format><!-- here goes any formatting relating to the display
     of the documents. These are generally named templates,
     and format options -->
+        of the documents. These are generally named templates,
+        and format options -->
       <gsf:template name='documentContent'>...</gsf:template>
       <gsf:option name='TOC' value='true'/>
 …
 \caption{Formatting options}
 \label{tab:format_options}
 \center{\footnotesize
+{\footnotesize
 \begin{tabular}{llp{5cm}}
 \hline
 …
 \subsection{Customising the interface}
+\subsection{Customising the interface}\label{sec:interface-customise}
 The interface can be customised in several ways.
 …
 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.
+\newpage
 \section{Developing Greenstone 3: Run-time system}\label{sec:develop-runtime}
 …
 \begin{table}
 \center{\footnotesize
+{\footnotesize
 \begin{tabular}{lll}
 \hline
 …
 \caption{Status codes currently used in Greenstone 3}
 \label{tab:status codes}
+{\footnotesize
 \begin{tabular}{llp{8cm}}
+\hline
 \bf code name & \bf code  & \bf meaning \\
 & \bf value & \\
+\hline
 SUCCESS &  1 & the request was accepted, and the process was  completed \\
 ACCEPTED & 2 & the request was accepted, and the process has been started, but it is not completed yet \\
 …
 HALTED & 12 & the process has stopped  \\
 INFO & 20 & just an info message that doesn't imply anything \\
+\end{tabular}
+\hline
+\end{tabular}}
 \end{table}
 …
 \caption{Configure CGI arguments}
 \label{tab:system-cgi}
+{\footnotesize
 \begin{tabular}{ll}
 \hline
 \bf arg & \bf description\\
+\hline
 a=s & system action\\
 sa=c$|$a$|$d & type of system request: c (configure), a (add/activate), \\
 …
 st=collection& \\
 \hline
 \end{tabular}
+\end{tabular}}
 \end{table}
 …
 \caption{The utility classes in org.greenstone.gsdl3.util}
 \label{tab:utils}
 \center{\footnotesize
+{\footnotesize
 \begin{tabular}{lp{3.75in}}
 \hline
 \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\\
 …
 XSLTUtil & contains static methods to be called from within XSLT \\
 \hline
+\end{tabular}
+}
+\end{tabular}}
 \end{table}
+\newpage
 \section{Collection building architecture}\label{sec:develop-build}
 **** GEORGE ****
 …
 modules API\\
+\newpage
 \section{Developing Greenstone 3: Adding new features}\label{sec:new-features}
 \subsection{Creating new services}
+\subsection{Creating new services}\label{sec:new-services}
 *inherit from ServiceRack - abstract base class. this handles the main process method, determines the service name and request type. if request type is describe, and to is empty, it returns a list of services (short\_service\_info) which is initialised in the configure method. a describe request to a particular service results in getServiceDescription being called, which must be supplied by the subclass.
 …
 * should a metadata retrieval service advertise what metadata is available??
 \subsection{creating new actions/pages}
 \subsection{new interfaces}
+\subsection{creating new actions/pages}\label{sec:new-pages}
+\subsection{new interfaces}\label{sec:new-interfaces}
 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.
 \subsection{Adding new classifiers}
+\subsection{Adding new classifiers}\label{sec:new-classifiers}
 *** GEORGE ***
 \subsection{Adding new plugins}
+\subsection{Adding new plugins}\label{sec:new-plugins}
 *** GEORGE ***
+\subsection{Documented examples}
+talk about the sample collections briefly - but most documentation is in the description
+\subsubsection{The NZDL web interface}
+We have created a second interface that can be seen at \gst{http://www.greenstone.org/greenstone3/nzdl}. There are some small differences between this and the standard greenstone interface.
+We created a new interface---called nzdl, put into the web/interfaces directory. It has a set of images and transform files like the standard interface. And most of the XSLT files have been overridden.
+* Along the navigation bar, it has search and classifiers. The standard interface has each service along there. We needed to modify the navigation bar XSLT code, but also we added a new receptionist.
+interface found at www...
+what did we have to do to get this interface?
+classifiers displayed instead of services, query services all have same button, hard coded query page.
+assumptions made, classes modified - new Receptionist, new XSLT.
+\subsection{New types of collections}\label{sec:new-coll-types}
+There are two types of standard Greenstone collections: collections built with the Greenstone 3 building system, and collections that are imported from Greenstone 2. There are many options to collection building but it is conceivable that these options don't meet the needs of all collection builders. Greenstone 3 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 Greenstone 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 Greenstone 2 MGPP collections were the first to be served in Greenstone 3. When we came to do Greenstone 2 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.
+To tell Greenstone 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.
+Currently, this is all that is specified in that file, but you may want to add parameters for the class etc.
+\gst{<collectionInit class="XMLCollection"/>}
+The display for the collection is also quite different. The home page for the collection  displays the list of documents. To achieve this, the describe response from the collection had to include the list, and a new XSLT was written for the collection that displayed this. Collection XSLT should be put in the transform directory of the collection\footnote{These are currently only used when running greenstone in a non-distributed fashion, but it will be added in properly at some stage}.
+Document display is  significantly different to standard greenstone. 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:
+\begin{gsc}\begin{verbatim}
+<action name='xd' class='XMLDocumentAction'>
+  <subaction name='toc' xslt='document-toc.xsl'/>
+  <subaction name='text' xslt='document-content.xsl'/>
+</action>
+\end{verbatim}\end{gsc}
+XSLT files are linked to subactions rather than the action as a whole. The collection supplies the two XSLT files written appropriately for the data it contains.
+All links that link to the documents have to be changed to use the xd action rather than the standard d action. These include the links from the home page, and the links from query results.
+Querying of the collection is almost the same as usual. The query service provides a list of parameters, does the query and then sends back a list of document identifiers. The standard query action was fine for this collection. The change occurs in the way that the results are displayed---this is accomplished using a format statement supplied in the collectionConfig file inside the search node.
+\begin{gsc}\begin{verbatim}
+<search>
+  <format>
+    <gsf:template match="documentNode">
+      <xsl:param name="collName"/>
+      <xsl:param name="serviceName"/>
+      <td>
+        <b><a href="{$library_name}?a=xd&amp;sa=text&amp;c={$collName}&
+            amp;d={@nodeID}&amp;p.a=q&amp;p.s={$serviceName}">
+             <xsl:choose>
+               <xsl:when test="metadataList/metadata[@name='Title']">
+                 <gsf:metadata name="Title"/>
+               </xsl:when>
+               <xsl:otherwise>(section)</xsl:otherwise>
+             </xsl:choose>
+           </a>
+         </b> from <b><a href="{$library_name}?a=xd&amp;sa=toc&amp;
+           c={$collName}&amp;d={@nodeID}.rt&amp;p.a=q&amp;p.s={$serviceName}">
+         <gsf:metadata name="Title" select="root"/></a></b>
+      </td>
+    </gsf:template>
+  </format>
+</search>
+\end{verbatim}\end{gsc}
+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 greenstone format language. As is shown here it is perfectly feasible to write a format statement that includes XSLT mixed in with greenstone 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 Greenstone'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 Greenstone 3 instead of Greenstone 2. 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 greenstone 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 Greenstone navigation bar lists all the services available for the collection. In Greenstone 2, 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.
+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.
+\newpage
 \section{Distributed Greenstone}\label{sec:distributed}
+\begin{figure}[t]
+Greenstone is designed to run in a distributed fashion. One greenstone installation can talk to several sites on different computers. This requires some sort of communication protocol. Any protocol can be used, however we have only implemented a simple SOAP protocol.
+more explanation..
+\begin{figure}[h]
   \centering
   \includegraphics[width=4in]{remote} %5.8
 …
 \end{figure}
-Greenstone is designed to run in a distributed fashion. One greenstone installation can talk to several sites on different computers. This requires some sort of communication protocol. Any protocol can be used, however we have only implemented a simple SOAP protocol.
-more explanation..
 We have used Apache SOAP for Java. This is run as a servlet in Tomcat.
 If you have obtained Greenstone through CVS, you will need to install soap separately, describe in Appendix~\ref{app:soap-cvs}. Debugging soap is described in Appendix~\ref{app:soap-debug}.
+\subsection{Serving a site using soap}
+what do we have to do?? resource file format, deploy the service etc.
 \appendix
+\newpage
+\section{Using Greenstone 3 from CVS}\label{app:cvs}
+*** need to make sure building stuff is in here ***
+Greenstone 3 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. Whats in CVS is quite different to what comes in a release. The code needs to be compiled, and some files need editing...
+To check out the greenstone code, use:
+\begin{quote}\begin{gsc}\begin{verbatim}
+cvs -d :pserver:cvs\[email protected]:2402/usr/local/
+           global-cvs/gsdl-src co 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.
+\subsection{Linux install}
+An install.sh script is provided to compile and install Greenstone3. What you need to do is:
+\begin{quote}\begin{gsc}
+cd gsdl3\\
+source setup.bash\\
+install.bash\\
+source setup.bash\\
+\end{gsc}\end{quote}
+Note: if you are using mozilla it doesn't seem to like localhost - you should edit the siteConfig files (web/sites/<sitename>/siteConfig.xml) to have your computer name instead of localhost.
+Note: \gst{source setup.bash} needs to be done once in any xterm window before doing a make or running Tomcat. setup.bash sets the environment variables \gst{CLASSPATH, PATH, JAVA\_HOME} etc.
+To shutdown or startup Tomcat, the commands are:
+\begin{quote}\begin{gsc}
+\gsdlhome/comms/jakarta/tomcat/bin/shutdown.sh\\
+\gsdlhome/comms/jakarta/tomcat/bin/startup.sh\\
+\end{gsc}\end{quote}
+You shouldn't run install.bash twice.
+To update your installation, you can run update.bash - this updates your code from CVS, and re-makes all the java stuff.
+\subsection{Windows install}
+\newpage
 \section{Tomcat}\label{app:tomcat}
 …
 Almost everything works fine when tomcat is running behind a proxy. The only time this causes trouble is if the servlet itself needs to make external http connections. We do this in the infomine demo collection for example. One of the service classes sends http requests to the infomine database at riverside. Since this is going through the proxy, a username and password is needed. It is not sufficient to prompt the user for a password because they are unlikely to have a password for the particular proxy that tomcat is using. What we have done at present is to put a proxy element in the siteConfig.xml file. Here you have to enter a suitable username and password for the proxy server. Unfortunately these are entered in plain text. And the file is viewable via the servlet. So we need a better solution.
+\newpage
 \section{SOAP}\label{app:soap}
 \subsection{Setting up SOAP from CVS}\label{app:soap-cvs}
 …
+\section{Using Greenstone 3 from CVS}\label{app:cvs}
+*** need to make sure building stuff is in here ***
+Greenstone 3 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. Whats in CVS is quite different to what comes in a release. The code needs to be compiled, and some files need editing...
+To check out the greenstone code, use:
+\begin{quote}\begin{gsc}\begin{verbatim}
+cvs -d :pserver:cvs\[email protected]:2402/usr/local/
+           global-cvs/gsdl-src co 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.
+\subsection{Linux install}
+An install.sh script is provided to compile and install Greenstone3. What you need to do is:
+\begin{quote}\begin{gsc}
+cd gsdl3\\
+source setup.bash\\
+install.bash\\
+source setup.bash\\
+\end{gsc}\end{quote}
+Note: if you are using mozilla it doesn't seem to like localhost - you should edit the siteConfig files (web/sites/<sitename>/siteConfig.xml) to have your computer name instead of localhost.
+Note: \gst{source setup.bash} needs to be done once in any xterm window before doing a make or running Tomcat. setup.bash sets the environment variables \gst{CLASSPATH, PATH, JAVA\_HOME} etc.
+To shutdown or startup Tomcat, the commands are:
+\begin{quote}\begin{gsc}
+\gsdlhome/comms/jakarta/tomcat/bin/shutdown.sh\\
+\gsdlhome/comms/jakarta/tomcat/bin/startup.sh\\
+\end{gsc}\end{quote}
+You shouldn't run install.bash twice.
+To update your installation, you can run update.bash - this updates your code from CVS, and re-makes all the java stuff.
+\subsection{Windows install}
+\newpage
 \section{Format statements: Greenstone 2 vs Greenstone 3}\label{app:format}
 The following table shows the Greenstone 2 format elements, and their equivalents in Greenstone 3
+\begin{table}
+\caption{Greenstone 3 equivalents of Greenstone 2 format statements}
+{\footnotesize
 \begin{tabular}{ll}
+\hline
 \bf Greenstone 2        & \bf Greenstone 3 \\
+\hline
 \gst{[Text]} & \gst{<gsf:text/>} \\
 \gst{[num]} & \gst{<gsf:metadata name='docnum'/>}\\
 …
 & \gst{     <td><gsf:metadata name='Subject'/></td>}\\
 & \gst{  </gsf:when></gsf:switch>}\\
+\end{tabular}
+\hline
+\end{tabular}}
+\end{table}
 \end{document}

Note: See TracChangeset for help on using the changeset viewer.

Context Navigation

Changeset 6422

Legend:

trunk/gsdl3/docs/manual/manual.tex

Download in other formats: