Final touches

diff --git a/README.md b/README.md
index 2517ac7..f54c482 100644 (file)
--- a/README.md
+++ b/README.md
@@ -13,7 +13,7 @@ INSTALLATION
 
 Index Data provides ready to use yaz4j RPMs for CentOS 5 and 6, available from
 our public YUM repository. On Windows yaz4j can be installed with the YAZ
 
 Index Data provides ready to use yaz4j RPMs for CentOS 5 and 6, available from
 our public YUM repository. On Windows yaz4j can be installed with the YAZ

-[installer][4]. Those methods are the simplest ways to get yaz4j up and running
+[installer][4] (select _Windows_ in the _Downloads_ section on the right)  Those methods are the simplest ways to get yaz4j up and running

 on the particular platforms and are highly recommended.
 
 
 on the particular platforms and are highly recommended.
 
 

@@ -33,14 +33,14 @@ contents:
     enabled=1
     priority=1
 
     enabled=1
     priority=1
 

-at `/etc/yum.repos.d/indexdata.repo`.
+under `/etc/yum.repos.d/indexdata.repo`.

 
 With the above repository enabled, yaz4j can be simply installed with:
 
     yum install yaz4j
 
 
 With the above repository enabled, yaz4j can be simply installed with:
 
     yum install yaz4j
 

-And the installation can be verified by running a provided test program which
-executes a search against a public Index Data Z39.50 test server:
+The installation can be verified by running a provided command-line test 
+program, which executes a search against a public Index Data Z39.50 test server:

 
     java -jar /usr/share/java/yaz4j.jar
 
 
     java -jar /usr/share/java/yaz4j.jar
 

@@ -48,16 +48,21 @@ executes a search against a public Index Data Z39.50 test server:
 YAZ Installer (Windows)
 -----------------------
 
 YAZ Installer (Windows)
 -----------------------
 

-YAZ Windows installer can be downloaded from [here][4]. Yaz4j is bundled with
-the installer: just make sure during the installation yaz4j box is checked. 
-It is also recommended to check the box for updating updating PATH environment
-variable with a path to yaz binaries. After installation yaz4j can be tested
-with (Java runtime environment required):
+YAZ Windows installer can be downloaded from [here][4] (select _Windows_ in 
+the _Downloads_ section on the right). Yaz4j is bundled with
+the installer: just make sure that during the installation yaz4j box is checked.
+It is also recommended to check the box for updating the `PATH` environment
+variable with a path to yaz binaries and DLLs. 
+
+After installation yaz4j can be tested with (Java runtime environment be [installed][1] separately):

 
     java -jar C:\Program Files\YAZ\java\yaz4j.jar
 
 
     java -jar C:\Program Files\YAZ\java\yaz4j.jar
 

-All native libraries and binaries are located in `C:\Program Files\YAZ\bin\`
-after installation.
+All native libraries and binaries are installed to `C:\Program Files\YAZ\bin\`
+while the `yaz4j.jar` is installed to `C:\Program Files\YAZ\java`. 
+  
+`C:\Program Files\YAZ\` is the default YAZ location on a 64-bit Windows and 
+it is assumed for `yaz-path` in the yaz4j build process.

 
 COMPILATION FROM SOURCE
 =======================
 
 COMPILATION FROM SOURCE
 =======================

@@ -82,12 +87,12 @@ Compilation requires [JDK][1], [Maven][2], [Swig][3] and [YAZ][4] development
 packages installed.
 
 Installing build dependencies can be done through the package manager specific 
 packages installed.
 
 Installing build dependencies can be done through the package manager specific 

-for the distribution (subject to availability), for CentOS 5/6 (YUM) JDK and Swig RPMs can be installed  with:
+for the distribution (subject to availability). For CentOS 5/6 (YUM) JDK and Swig RPMs can be installed  with:

 
     yum install java-1.7.0-openjdk-devel swig
 
 
     yum install java-1.7.0-openjdk-devel swig
 

-While YAZ development package needs to be installed from Index Data's YUM 
-repository (see INSTALLATION on how to enable the YUM repo):
+YAZ development package needs to be installed from Index Data's YUM 
+repository (see the INSTALLATION section on how to enable the YUM repo):

 
     yum install libyaz5-devel
 
 
     yum install libyaz5-devel
 

@@ -98,7 +103,7 @@ installed with:
 
     yum install maven3-indexdata
 
 
     yum install maven3-indexdata
 

-in which case Maven program is called `mvn-id` rather than `mvn`.
+in which case the Maven program is called `mvn-id` rather than `mvn`.

 
 With all dependencies in place you can continue the yaz4j compilation with:
 
 
 With all dependencies in place you can continue the yaz4j compilation with:
 

@@ -108,26 +113,27 @@ With all dependencies in place you can continue the yaz4j compilation with:
 Which will also run tests that open a connection to Index Data's public Z39.50
 server.
 
 Which will also run tests that open a connection to Index Data's public Z39.50
 server.
 

-Notice that `yaz-config` binary must be on the PATH (this is assured when 
+Notice that `yaz-config` binary must be on the `PATH` (this is assured when 

 `libyaz5-devel` package is installed), if it isn't e.g if a local YAZ (source) 
 installation is used, the binary location can be specified with:
 
     mvn -Dyaz.config=/path/to/yaz-config install
 
 `libyaz5-devel` package is installed), if it isn't e.g if a local YAZ (source) 
 installation is used, the binary location can be specified with:
 
     mvn -Dyaz.config=/path/to/yaz-config install
 

-The compiled jar file ends up in any/target/yaz4j.jar while the native library
-in unix/target/libyaz4j.so.
+The compiled jar file ends up in `any/target/yaz4j.jar` while the native library
+in `unix/target/libyaz4j.so`.

 
 Compilation on generic Unix
 ---------------------------
 
 You will need the JDK, Maven, Swig and YAZ development packages.
 
 Compilation on generic Unix
 ---------------------------
 
 You will need the JDK, Maven, Swig and YAZ development packages.

-Consult your package manager on how to install those.
+Consult your package manager on how to install those. For compilation
+of YAZ please consult YAZ [manual][8].

 
 

-If yaz-config is in your PATH, the following command should suffice:
+If yaz-config is in your `PATH`, the following command should suffice:

 
     mvn install
 
 
     mvn install
 

-If yaz-config is not in your PATH, you'll have to tell where YAZ is located:
+If yaz-config is not in your `PATH`, you'll have to tell where YAZ is located:

 
     mvn -Dyaz.config=/path/to/yaz-config install
 
 
     mvn -Dyaz.config=/path/to/yaz-config install
 

@@ -144,51 +150,57 @@ source directory and run:
 
     mvn install
 
 
     mvn install
 

-Default 64-bit YAZ installer location is assumed for the 'yaz.path' property.
-Nothing is assumed for 'swig', so you either need to specify an absolute path
-or update the PATH environment to include the directory containing swig.exe.
-Both can be specified with:
+Default 64-bit YAZ installer location, that is`C:\Program Files\YAZ\`,
+is assumed for the `yaz.path` property. Nothing is assumed for `swig`, 
+so you either need to specify an absolute path or update the `PATH` 
+environment variable to include the directory containing 
+`swig.exe`. Both can be specified with:

 
     mvn -Dyaz.path=/path/to/yaz/installdir -Dswig=/path/to/swig/binary install
 
 
     mvn -Dyaz.path=/path/to/yaz/installdir -Dswig=/path/to/swig/binary install
 

+The compiled jar file ends up in `any/target/yaz4j.jar` while the native library
+in `win32/target/libyaz4j.dll`.
+
+

 YAZ4J AND A SERVLET CONTAINER
 =============================
 
 If you are coding a web application that uses yaz4j there's a couple of things
 to keep in mind. First, you are not invoking the JVM directly, but the servlet
 YAZ4J AND A SERVLET CONTAINER
 =============================
 
 If you are coding a web application that uses yaz4j there's a couple of things
 to keep in mind. First, you are not invoking the JVM directly, but the servlet

-container (e.g Tomcat) run/init script is doing that for you and that's the place
-to configure any environment settings (e.g the PATH). Second, yaz4j includes
-static initializers to load the native part and can't be packaged along with the
-webapp as that would break on consecutive redeployments. It must be deployed to
-the servlet container common classloader similar to JDBC drivers.
+container (e.g Tomcat) run/init script is doing that for you and that's the 
+place to configure any environment settings (e.g the `PATH`). Second, yaz4j 
+includes static initializers to load the native part and can't be packaged 
+along with the webapp as that would break on consecutive redeployments. It must
+be deployed to the servlet container common classloader, similarly to JDBC 
+drivers.

 
 For convenience, `yaz4j-tomcat6` RPM is provided in the ID's YUM repo which will
 
 For convenience, `yaz4j-tomcat6` RPM is provided in the ID's YUM repo which will

-set up the default RPM-provided Tomcat 6 with yaz4j automatically:
+set up the default CentOS-provided Tomcat 6 with yaz4j automatically:

 
     sudo yum install yaz4j-tomcat6
 
 Linux (CentOS)
 --------------
 
 
     sudo yum install yaz4j-tomcat6
 
 Linux (CentOS)
 --------------
 

-In case when yaz4j is installed through the RPM (Index Data's YUM repo) the
+In the case when yaz4j is installed through the RPM (Index Data's YUM repo) the

 native libraries are placed in the standard system locations (/usr/lib/.. etc)
 and are readily available to all applications, including Tomcat. The only other
 thing to configure is to add yaz4j.jar (the pure Java component) to Tomcat's
 common class loader (further down).
 
 native libraries are placed in the standard system locations (/usr/lib/.. etc)
 and are readily available to all applications, including Tomcat. The only other
 thing to configure is to add yaz4j.jar (the pure Java component) to Tomcat's
 common class loader (further down).
 

-In case when yaz4j is built from source or for some other reason the native
-pars are not present in the standard system library locations, they need to be
-placed on the servlet  container's shared libraries load path. One way
+In the case when yaz4j is built from source or for some other reason the native
+parts are not present in the standard system library locations, they need to be
+placed on the servlet container's shared libraries load path. One way

 to do this in Tomcat (assuming Tomcat is run from a tarball rather than RPM) is
 to do this in Tomcat (assuming Tomcat is run from a tarball rather than RPM) is

-by editing  (create it if it does not exist) the CATALINA_HOME/bin/setenv.sh`
+by editing  (create it if it does not exist) the `CATALINA_HOME/bin/setenv.sh`

 script and putting the following lines in there:
 
     LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/libyaz4j.so
     export LD_LIBRARY_PATH
 
 Notice, that this has to be done for all native libraries that `yaz4j.so`
 script and putting the following lines in there:
 
     LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/libyaz4j.so
     export LD_LIBRARY_PATH
 
 Notice, that this has to be done for all native libraries that `yaz4j.so`

-dependson, e.g `libyaz5.so` and so on, unless they are already on the default s
-ystem library paths (e.g when installed from RPMs).
+depends on, e.g `libyaz5.so` and so on, unless they are already on the default 
+system library paths (e.g when installed from RPMs).

 
 If Tomcat is started by a custom init scripts similar operation needs to be
 performed there.
 
 If Tomcat is started by a custom init scripts similar operation needs to be
 performed there.

@@ -198,7 +210,7 @@ it becomes available to all deployed webapps and is loaded only once. There
 are a couple ways to do that.
 
 One (employed by `yaz4j-tomcat6` RPM) is to place (or symlink) `yaz4j.jar` to
 are a couple ways to do that.
 
 One (employed by `yaz4j-tomcat6` RPM) is to place (or symlink) `yaz4j.jar` to

-to `$CATALINA_BASE/lib` (CATALINA_BASE is `/usr/share/tomcat6` when Tomcat was
+to `CATALINA_BASE/lib` (`CATALINA_BASE` is `/usr/share/tomcat6` when Tomcat is

 installed from RPMs on CentOS):
 
     ln -s /path/to/yaz4j.jar /usr/share/tomcat6/lib
 installed from RPMs on CentOS):
 
     ln -s /path/to/yaz4j.jar /usr/share/tomcat6/lib

@@ -220,27 +232,29 @@ Windows
 
 On Windows Tomcat will most likely be run from the binary distribution which
 includes `CATALINA_BASE/bin/setenv.bat` for the purpose of setting up the 
 
 On Windows Tomcat will most likely be run from the binary distribution which
 includes `CATALINA_BASE/bin/setenv.bat` for the purpose of setting up the 

-environment. Unless, you have installed yaz4j.dll with the YAZ Installer and 
-checked the option to update the global PATH and include all native YAZ and
-yaz4j components, edit setenv.bat with the following:
+environment. Unless, you have installed yaz4j.dll through the YAZ Installer and 
+checked the option to update the global `PATH` and include all native YAZ and
+yaz4j components or you have set up the global `PATH` on your own, edit 
+`setenv.bat` with the following:

 
     set PATH=%PATH;X:\path\to\yaz\bin;X:\path\to\yaz4j.dll
 
 The `X:\path\to\yaz\bin` is `C:\Program Files\YAZ\bin` when the installer was
 used and includes also yaz4j.dll.
 
 
     set PATH=%PATH;X:\path\to\yaz\bin;X:\path\to\yaz4j.dll
 
 The `X:\path\to\yaz\bin` is `C:\Program Files\YAZ\bin` when the installer was
 used and includes also yaz4j.dll.
 

-In case Tomcat is start up does not execute `setenv.sh`, e.g when custom startup
+In case Tomcat start up does not execute `setenv.sh`, e.g when custom startup

 script is used, please include similar steps there.
 
 script is used, please include similar steps there.
 

-To deploy `yaz4j.jar` you must follow steps identical to those from the Linux 
-section. Again, when installer is used `yaz4j.jar` is located at `C:\Program Files\YAZ\java\yaz4j.jar`.
+To deploy `yaz4j.jar` you must edit `catalina.properties` files, see the Linux 
+section for details. Again, when the YAZ installer is used `yaz4j.jar` is 
+located at `C:\Program Files\YAZ\java\yaz4j.jar` by default.

 
 
 Deploy a test app
 -----------------
 
 
 
 Deploy a test app
 -----------------
 

-Under yaz4j/examples you'll find a small zgate app. This can be deployed
-to Tomcat to test the yaz4j installation. To do so:
+Under `yaz4j/examples` you'll find a small webapp called `zgate`. This can be 
+deployed to Tomcat to test the yaz4j installation. To do so:

 
     cd yaz4j/examples/zgate
     mvn install
 
     cd yaz4j/examples/zgate
     mvn install

@@ -252,6 +266,8 @@ If successful you can run the application with a URL as follows:
 
 [http://localhost:8080/zgate/?zurl=z3950.indexdata.com/marc&query=computer&syntax=usmarc](http://localhost:8080/zgate/?zurl=z3950.indexdata.com/marc&query=computer&syntax=usmarc)
 
 
 [http://localhost:8080/zgate/?zurl=z3950.indexdata.com/marc&query=computer&syntax=usmarc](http://localhost:8080/zgate/?zurl=z3950.indexdata.com/marc&query=computer&syntax=usmarc)
 

+You should see results from the Index Data's test z3950 server.
+

 PREPARING A DEVELOPMENT ENVIRONMENT
 ===================================
 
 PREPARING A DEVELOPMENT ENVIRONMENT
 ===================================
 

@@ -280,7 +296,7 @@ Yaz4j API dependency (put under `<dependencies/>` in pom.xml):
 
 
 It's crucial that the scope of this dependency is set to `provided` for web
 
 
 It's crucial that the scope of this dependency is set to `provided` for web

-application type projecets, otherwise the library would end up packaged in 
+application type projects, otherwise the library would end up packaged in 

 the .war archive and we wouldn't want that.
 
 Yaz4j includes a trivial HTTP to z3590 gateway under `examples/zgate` that shows
 the .war archive and we wouldn't want that.
 
 Yaz4j includes a trivial HTTP to z3590 gateway under `examples/zgate` that shows

@@ -288,11 +304,6 @@ best how to use yaz4j in a servlet. There's also a blog entry on building the
 gateway [here][7]
 
 
 gateway [here][7]
 
 

-LINKS
-=====
-
-The following is most probably already outdated, consult Google.
-

 [1]: http://www.oracle.com/technetwork/java/javase/downloads/index.html "JDK"
 
 [2]: http://maven.apache.org/download.cgi "Maven"
 [1]: http://www.oracle.com/technetwork/java/javase/downloads/index.html "JDK"
 
 [2]: http://maven.apache.org/download.cgi "Maven"

@@ -306,3 +317,5 @@ The following is most probably already outdated, consult Google.
 [6]: https://tomcat.apache.org/tomcat-6.0-doc/class-loader-howto.html "Tomcat 6 class loading"
 
 [7]: http://www.indexdata.com/blog/2010/02/building-simple-http-z3950-gateway-using-yaz4j-and-tomcat "Building a simple HTTP-to-Z39.50 gateway using Yaz4j and Tomcat"
 [6]: https://tomcat.apache.org/tomcat-6.0-doc/class-loader-howto.html "Tomcat 6 class loading"
 
 [7]: http://www.indexdata.com/blog/2010/02/building-simple-http-z3950-gateway-using-yaz4j-and-tomcat "Building a simple HTTP-to-Z39.50 gateway using Yaz4j and Tomcat"

+
+[8]: http://www.indexdata.com/yaz/doc/installation.html "YAZ Compilation"