--- a/doc/config-manual/model_of_transitions.tex	Mon May 10 21:47:24 2010 +0000
+++ b/doc/config-manual/model_of_transitions.tex	Wed May 12 11:35:25 2010 +0000
@@ -17,7 +17,7 @@
     (Implementation)
 \end{enumerate}
 
-%% TODO: Add a Screenshot of the GNV WebClient marking GUI elements for FIS,
+%% TODO to improve: Add a Screenshot of the GNV WebClient marking GUI elements for FIS,
 %% product, states and transitions
 
 Main entry point for the configuration also is the file {\tt conf/conf.xml }
@@ -80,12 +80,12 @@
 are gathered in the file {\tt conf/queries.properties}.
 
 
-\subsection{Explaining the background of the XML configuration}
+\subsection{Background information of the XML configuration}
 
 It is possible to configure the GNV in many ways.
 It is possible to add or remove FIS, add or remove products from a FIS or
-to manipulate the steps which must be gone until a product can be create
-a diagram or generate an CSV-export.
+to manipulate the steps which must be prepared until products like
+a diagram or CSV-export can be generated.
 
 The configuration of the provided FIS are divided in three main parts.
 
@@ -99,10 +99,11 @@
 
 \subsubsection{Configuration of a FIS}
 The point of entry into the system is to configure an {\tt artifact-factory}.
-Each {\tt artifact-factory} represents one FIS.
-It is possible to configure several {\tt artifact-factories}.
+Each artifact-factory represents one FIS.
+It is possible to configure several {\tt artifact-factories}, which
+represent the list of FIS in GUI.
 The {\tt artifact-factories} will be configured in the section 
-{\tt /artifact-database/artifact-factories} of the configurationfile.
+{\tt /artifact-database/artifact-factories} of the configuration-file.
 
 \begin{lstlisting}
 <artifact-factory name='fis_NEWFISNAME' 
@@ -113,12 +114,14 @@
 </artifact-factory>
 \end{lstlisting}
 
-At this moment the following attributes of an {\tt artifact-factory} are configurable.
+At this moment the following attributes of an {\tt artifact-factory} are
+configurable:
 \begin{itemize}
     \item {\tt name}: The name of the {\tt artifact}. Must be unique in one {\tt artifact-server}
     \item {\tt description}: Short description which job the {\tt artifact-factory} has to do.
-    \item {\tt ttl}: The time to live: The time using milliseconds an {\tt artifact}, created using this 
-                factory, can live without any user-interaction.
+    \item {\tt ttl}: The time to live: The time using milliseconds an
+    {\tt artifact}, created using this factory, can live without any
+    user-interaction.
     \item {\tt artifact}: The name of the class of the {\tt artifact} which should be created.
 \end{itemize}
 
@@ -169,7 +172,7 @@
 In the section {\tt /artifact/products} it is possible to define several products as 
 explained in the next section.
 
-\paragraph{Products to an FIS}
+\subsection{Products to an FIS}
 One FIS can provide several products.
 To do this it is required to configure them as shown below in the section 
 {\tt /artifact/products}
@@ -191,17 +194,18 @@
  </product>
  \end{lstlisting}
 
-Each {\tt product} is also represented by an {\tt artifact}. To create this {\tt artifact} we have to 
-use an {\tt artifact-factory} which is configured in each product 
+Each {\tt product} is also represented by an {\tt artifact}. In order to
+create this {\tt artifact}, the {\tt artifact-factory} has to be used.
+It is configured in each product 
 ({\tt /product/artifact-factory}).
 
-Each product can have several parameters ({\tt /product/parameters/parameters}).
-The {\tt parameter} named {\tt sourceid} and {\tt fisname} are required parameters.
+Each product can have several parameters ({\tt
+/product/parameters/parameters}).  The {\tt parameter} named {\tt
+sourceid} and {\tt fisname} are required parameters.
 
-The parameter {\tt fisname} contains the key to the name of the FIS. The key must be 
-unique.
-The parameter {\tt sourceid} contains the key to identify the FIS in the 
-datawarehouse. ({\tt MEDIAN.SOURCEINFO})
+The parameter {\tt fisname} contains the key to the name of the FIS. The
+key must be unique.  The parameter {\tt sourceid} contains the key to
+identify the FIS in the datawarehouse. ({\tt MEDIAN.SOURCEINFO})
 
 
 \subsubsection{Configuration of an Product}
@@ -212,8 +216,9 @@
 
 In those files the workflow of each product is configured.  Each step which is
 required to model a new diagram is represented using a {\tt state} in the
-configurationfile.
+configuration-file.
 
+%% FIXME: fix wording
 To move between those {\tt states} it is required to model {\tt transitions} which define
 between which states it is possible to move and which conditions must be
 fulfilled.
@@ -269,8 +274,8 @@
            the FIS in the current state.
 \end{itemize}
 
-WARNING: The order of the inputvalues is significant at which position the value will
-be put into the SQL-statement.
+{\bf WARNING: The order of the input-values is significant at which position the value will
+be put into the SQL-statement!}
 
 It is possible to add one inputvalue twice or more often to put its value at
 different positions of the SQL-statement.
@@ -332,12 +337,11 @@
 ORDER BY P.GERMANNAME
 \end{lstlisting}
 
-If there are put the inputvalues in it it will look like this
-if we assume that the inputvalues has got the following values
-which where feed by choosing this FIS ({\tt fisname}) and the Station
-({\tt featureid}: Arkona Basin Buoy ):
+Including inputvalues, the example for choosing the FIS ({\tt fisname})
+and the Station 342 ({\tt featureid}: Arkona Basin Buoy) will look like
+this: 
 \begin{itemize}
-    \item {\tt featureid}: 100011 (Marnet ==> Arkona Basin Buoy)
+    \item {\tt featureid}: 100011 (Marnet $\rightarrow$ Arkona Basin Buoy)
     \item {\tt fisname}: fis\_marnet
     \item {\tt parameterid}: not set because it's the value that should be 
                        chosen in this state. 
@@ -412,7 +416,7 @@
 \end{lstlisting}
 
 \begin{itemize}
-   \item {\tt featureid}: 100011 (Marnet ==> Arkona Basin Buoy)
+   \item {\tt featureid}: 100011 (Marnet $\rightarrow$ Arkona Basin Buoy)
    \item {\tt fisname}: fis\_marnet
    \item {\tt parameterid}: 2 (Salzgehalt [pSal])
    \item {\tt measurementid}: not set because it's the value that should be
@@ -458,25 +462,22 @@
 \end{lstlisting}
 
 The queries which are shown above are configurable.
-You can do this in the file {\tt queries.properties } which will
+Configuring takes place in the file \texttt{queries.properties } which will
 be explained in the next paragraph.
 
 \paragraph{Query-configuration (queries.properties)}
+\label{ref:queries.properties}
 
 This file contains key-value-pairs to define SQL-statements.
 All queries will be handle using the prepared-statement-syntax using "?"
 to define a place where an dynamic value should be placed into the statement.
  
 There is one special implementation to support spatial access to the 
-{\tt ArcSDE}, because the {\tt ArcSDE} does not support the access to 
-spatial objects using the definition of the Simple Feature Specification for 
-SQL of the OGC.
-
-It was necessary to implement this mechanism to realize the access to spatial-
+{\tt ESRI ArcSDE}-database. This mechanism is used to realize the access to spatial-
 objects.
 
-All queries which contains the following literals will be handle separate
-using the {\tt ArcSDE-API}.
+All queries containing the following literals will be handled separatly
+using the ESRI ArcSDE-API.
 
 \begin{itemize}
     \item {\tt ST\_ASTEXT(SHAPE)}: Will return the geometry as an WellKnowText (WKT)
@@ -489,9 +490,9 @@
 
 \paragraph{Transitions}
 
-To move between two states it is necessary to configure dependencies between
-the different states.
-This dependencies are called {\tt transitions}.
+To move between two states it is necessary to configure dependencies
+between the different states.  This dependencies are called {\tt
+transitions}.
 
 There are different kinds of {\tt transitions} which can be used.
 \begin{itemize}
@@ -520,9 +521,9 @@
 
 \paragraph{Outputstate}
 
-The {\tt outputstate} is an special {\tt state} which was created to define
+The {\tt outputstate} is a special {\tt state} which was created to define
 the different possibilities of outputs for each product.
-An {\tt outputstate} is handled as an {\tt state} which is described above.
+An {\tt outputstate} is handled as a {\tt state} which is described above.
 Additionally you are able to configure which kind of outputs should
 be provided.
 
@@ -542,10 +543,10 @@
 All these outputstates are implemented in {\tt package de.intevation.gnv.state}
 and its {\tt sub\-packages}. 
 
-You have to put the fullqualified name of the {\tt outputstate} to the attribute 
-{\tt state} as shown below.
+The fullqualified name of the {\tt outputstate} to the attribute 
+{\tt state} is shown below.
 
-You can configure an {\tt outputstate} as shown below:
+An example for an {\tt outputstate}:
 
 \begin{lstlisting}
 <state id="timeseries_calculate_results" description="timeseries_interval" state="de.intevation.gnv.state.timeseries.TimeSeriesOutputState">
@@ -565,14 +566,15 @@
 \paragraph{OutputModes}
 
 It is possible to configure several {\tt outputmodes} in one {\tt outputstate}.
-Inserting or deleting the configuration of an special
-{\tt outputmode} will cause that the pending item will be shown or hidden 
-in the {\tt GUI}.
+Inserting or deleting the configuration of a special
+{\tt outputmode} will control if an item in the GUI will be displayed.
 
+{\bf
 WARNING: IT MIGHT BE POSSIBLE THAT ONE OR MORE OUTPUTMODES ARE NOT
          SUPPORTED BY AN PRODUCT. IN THAT CASE IT IS NECESSARY TO
          IMPLEMENT THE REQUIRED FUNCTIONALITY BEFORE IT IS POSSIBLE
          TO OFFER THIS OUTPUTMODE.
+}
 
 Currently the following {\tt outputmodes} are supported:
 
@@ -603,7 +605,6 @@
 </outputsMode>
 \end{lstlisting}
 
-// TODO add simple OutputMode e.g. for CSV??
 
 \begin{itemize}
    \item {\tt name}: The name of the mode. This must not be changed because it 
@@ -615,22 +616,22 @@
 \end{itemize}
 
 
-\subsection{Adding a new FIS}
-In this section it will be explained which steps has to be done to integrate a
+\section{Adding a new FIS}
+In this section it will be explained which steps have to be done to integrate a
 new FIS into the {\tt artifact-server}.  This will be done using the configuration for
-an FIS which use data from {\tt MEDIAN.TIMESERIES} section of the datawarehouse e.g.
-MARNET or STAUN
+a FIS which uses data from the table {\tt MEDIAN.TIMESERIES} section of
+the datawarehouse (e.g. MARNET or STAUN).
 
-Pay attention that for publishing the changes to the {\tt artifact-server} you will 
-have to restart it. 
+For publishing the changes to the {\tt artifact-server}, it needs to be
+restarted. 
 
-\subsubsection{Adding a new Artifact-factory}
+\subsection{Adding a new Artifact-factory}
 First step is to add a new {\tt artifact-factory} to the configuration conf/conf.xml
 To do this you have to add a new XML-fragment into the section 
 /factories/artifact-factories  which look like that:
 
 \begin{lstlisting}
-<artifact-factory name='fis\_NEWFISNAME' 
+<artifact-factory name='fis_NEWFISNAME' 
                   description='Factory to create an artifact to be used with the FIS NEWFISNAME'  
                   ttl='3600000' 
                   artifact='de.intevation.artifactdatabase.ProxyArtifact'>
@@ -641,16 +642,16 @@
 In this XML-fragment you only have to replace the placeholder {\tt NEWFISNAME}
 with a unique short name for the new FIS.
 
-\paragraph{Example}
-This example shows how to add an FIS and which effects it took to the 
-REST-Server.
+\paragraph*{Example}
+This example shows how to add a FIS and illustrates the effect on the
+artifact-server's output.
 
-At first we add the following {\tt artifact-factory} into the file 
+First , the following {\tt artifact-factory} has to be added into the file 
 {\tt conf/conf.xml} in section {\tt /artifact-database/artifact-factories} 
-which add a new FIS called {\tt justanewfis} to the server:
+adding a new FIS called {\tt justanewfis} to the server:
 
 \begin{lstlisting}
-<artifact-factory name='fis\_justanewfis' 
+<artifact-factory name='fis_justanewfis' 
                   description='Factory to create an artifact to be used with the FIS NEWFISNAME'  
                   ttl='3600000' 
                   artifact='de.intevation.artifactdatabase.ProxyArtifact'>
@@ -658,30 +659,29 @@
 </artifact-factory>
 \end{lstlisting}
 
-Then we restart the {\tt artifact-database} executing the following command:
+Restart the {\tt artifact-database} executing:
 
 \begin{lstlisting}
-/etc/init.d/artifactdb restart
+/etc/init.d/artifact-server restart
 \end{lstlisting}
 
-Then we check if the new FIS is served by the REST-Server
+Checking if the new FIS is served by the REST-Server
 calling the following command:
 
 \begin{lstlisting}
-curl http://localhost:8181/factories | xmllint --format - | grep fis\_justanewfis
+curl http://localhost:8181/factories | xmllint --format - | grep fis_justanewfis
 \end{lstlisting}
 
-If the FIS was added the new {\tt artifact-factory} will be found in the generated 
-XML-output and it will be shown.
-Otherwise no XML-output will be shown.
+If the FIS was added, the new {\tt artifact-factory} will be found in the generated 
+XML-output. Otherwise no XML-output will be shown.
 
-\subsubsection{Adding a new Artifact for Artifact-factory}
+\subsection{Adding a new Artifact for Artifact-factory}
 The next step is to define the artifact itself.
 For this it is necessary to add an XML-fragment into the section 
 {\tt /artifacts} of the main configurationfile {\tt /conf/conf.xml}.
 
 \begin{lstlisting}
-<artifact name='fis\_NEWFISNAME'>
+<artifact name='fis_NEWFISNAME'>
     <products>
      ...
     </products>
@@ -693,43 +693,44 @@
 
 Now the {\tt artifact-server} can handle an additional FIS without any products yet.
 
-To prevent needless configuration-work it is useful way to clone an artifact 
-which handle the same kind of work as the new FIS.
+To prevent needless configuration-work, it is a useful way to clone an
+existing artifact handling the same kind of work.
 
 
-\paragraph{Example}
-Now we will configure an artifact to the FIS justanewfis.
+\paragraph*{Example}
+Now will an artifact to the FIS {\tt fis\_justanewfis}, will be configured.
 
-For this we have to add the following XML-fragment to the file 
+The following XML-fragment has to be added to the file 
 {\tt conf/conf.xml} in section {\tt /artifact-database/artifacts}:
 
 \begin{lstlisting}
-<artifact name='fis\_justanewfis'>
+<artifact name='fis_justanewfis'>
     <products>
     </products>
 </artifact>
 \end{lstlisting}
 
-Restart the artifact-database:
+Restart the artifact-server
 
 \begin{lstlisting}
-/etc/init.d/artifactdb restart
+/etc/init.d/artifact-server restart
 \end{lstlisting}
 
-Now we should be able to choose the artifact.
+Now it should be possible to choose the artifact.
 
-The Listbox with products will be empty.
+The listbox in the GUI would be empty.
 \begin{lstlisting}
 curl -d "@sample-documents/create-artifact.xml"  http://localhost:8181/create | xmllint --format -
 \end{lstlisting}
 
-\subsubsection{Adding removing Products to the specific Artifact}
-Now it is time to configure the different products which the FIS should be able 
-to provide.
-To do this it is necessary to copy the XML-fragments of the products into the
-XML-element {\tt products} of the previously integrated artifact.
+\subsection{Adding/Removing Products to the Specific Artifact}
+Next step is, to configure the different products which the FIS should
+be able to provide.  To do this it is necessary to copy the
+XML-fragments of the products into the XML-element {\tt products} of the
+previously integrated artifact.
+
 \begin{lstlisting}
-<artifact name='fis\_NEWFISNAME'>
+<artifact name='fis_NEWFISNAME'>
      <products>
          <product name= "timeSeries">
               <artifact-factory name="timeSeries" 
@@ -763,16 +764,15 @@
 </artifact>
 \end{lstlisting}
 
-In this XML-fragment you have to replace the placeholders {\tt NEWFISNAME}
-as before and {\tt VALUEOFSOURCEID} with the value for the new FIS as defined
-in the table {\tt MEDIAN.SOURCEINFO}.
+In this XML-fragment the placeholders {\tt NEWFISNAME} have to be
+replaced. The source-id {\tt VALUEOFSOURCEID} with the value for the new
+FIS as defined in the table {\tt MEDIAN.SOURCEINFO} needs to be added.
 
-\paragraph{Example}
-Now we will add a product to the new FIS.
-To let the products work we will choose a product which
-will contain the sourceid of an existing FIS (e.g 4 Marnet).
+\paragraph*{Example}
+Adding a product to the new FIS, choosing sourceid of an existing FIS
+(e.g 4 $\rightarrow$ Marnet).
 
-At first add the following XML-fragment to the new artifact.
+Add the following XML-fragment to the new artifact.
 \begin{lstlisting}
 <product name= "timeSeries">
     <artifact-factory name="timeSeries" 
@@ -790,36 +790,36 @@
 </product>
 \end{lstlisting}
 
-Restart the artifact-database:
+Restart the artifact-server
 
 \begin{lstlisting}
-/etc/init.d/artifactdb restart
+/etc/init.d/artifact-server restart
 \end{lstlisting}
 
-If we call 
+If 
 \begin{lstlisting}
 curl -d "@sample-documents/create-artifact.xml"  http://localhost:8181/create | xmllint --format -
 \end{lstlisting}
 
-the product {\tt timeSeries} should be available for the FIS {\tt justanewfis}.
+is called, the product {\tt timeSeries} should be available for the FIS {\tt justanewfis}.
  
-Now we should be able to choose the product.
-This product should work and you should be able to generate even the defined
-outputformats.
+Now, it should be able to choose the product.
+This product including the definied outputformats should be available in
+the GUI.
 
 \subsection{Adding a new Product}
 To add a new product to the system it is necessary that the required 
 artifact representation is implemented in the {\tt sourcecode}.
 Without doing that step it is not possible to create a new product.
 
-All products are configured in separate files that will be included into the 
+All products are configured in separated files that will be included into the 
 main configuration using Xlink-references.
 
-First step is to create a new file in the folder {\tt products} and there in the 
+First step is to create a new file in the folder {\tt products} and in the 
 sub-folder where the product belongs to ({\tt timeseries,verticalprofile,
 horizontalprofile,horizontal\-crosssection,layer,...})
 
-Then you have tor reference this file in the file {\tt /conf/conf.xml} in the
+Then the new product can be referenced in the file {\tt /conf/conf.xml} in the
 section {\tt/artifacts} using the following XML-fragment.
 
 \begin{lstlisting}
@@ -835,10 +835,10 @@
 Please note that the defined name of the {\tt artifact-factory} has to match to the 
 name of the added products which is also designed as an artifact.
 
-\subsection{Adding a additional Product to a FIS}
-To add a additional product to a FIS you only have to add the XML-fragment which 
+\subsection{Adding an additional Product to a FIS}
+To add an additional product to a FIS the XML-fragment which 
 represents the product to the artifact-configuration of the FIS in section
-{\tt /artifacts/artifact/products}.
+{\tt /artifacts/artifact/products} needs to be added.
 
 \begin{lstlisting}
  <product name= "timeSeries">
@@ -857,5 +857,4 @@
  </product>
  \end{lstlisting}
 
-Please note that you have to replace the Placeholders as explained above.
-
+Please note that the placeholders have to be explained above.