Add prereq and remove Windows guides.

Also change the formatting and include codeblocks. Windows section was
removed - we will add windows build on request.

diff --git a/examples/zgate/doc/ARTICLE b/examples/zgate/doc/ARTICLE
index 2abf564..f105fb1 100644 (file)
--- a/examples/zgate/doc/ARTICLE
+++ b/examples/zgate/doc/ARTICLE
@@ -15,11 +15,20 @@ the Java Servlet technology.
 ## COMPILING AND INSTALLING YAZ4J
 
 Yaz4j is still an experimental piece of software and as such is not distributed
-via Index Data's public Debian apt repository and there is no Windows installer
+via Index Data's public Debian Apt repository and there is no Windows build (yet)
 either. While it is possible to use the pre-built Linux binaries, users of 
-other OSes will have compile yaz4j from source. No need to worry (yet) - the 
+other OSes will have to compile yaz4j from source. No need to worry (yet) - the 
 process of compiling yaz4j is quite simple and we will be up and running in no 
-time :). The source code can be checked-out out from our 
+time :).
+
+As a prerequisite, to complete th build process you will need JDK, Maven, Swig
+and Yaz (development package) installed on your machine. On Debian/Ubuntu you
+can get those easily via apt:
+
+    apt-get install sun-java6-jdk maven2 libyaz3-dev swig
+
+
+The Yaz4j's source code can be checked-out out from our 
 [Git repository](http://git.indexdata.com/?p=yaz4j.git;a=summary), and assuming
 you have Git installed on your machine you can do that with:
 
@@ -52,23 +61,23 @@ a bit more complicated. First, you are not invoking the JVM directly, but the
 servlet container (e.g Tomcat) run-script is doing that for you. At this 
 point the shared library (so or dll) has to be placed on the servlet container's
 shared libraries load path. Unless your library is deployed to the standard 
-system location for shared libs (/usr/lib on Linux) or it's location is already 
-added to the path, the easiest way to do this in Tomcat is by editing 
-(create it if it does not exist) the CATALINA_HOME/bin/setenv.sh (setenv.bat on
-Windows) script and putting the following lines in there:
+system location for shared libs (`/usr/lib` on Linux) or it's location is 
+already added to the path, the easiest way to do this in Tomcat is by editing 
+(create it if it does not exist) the `CATALINA_HOME/bin/setenv.sh` (setenv.bat 
+on Windows) script and putting the following lines in there:
 
     LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/libyaz4j.so
     export LD_LIBRARY_PATH
 
-on Windows
+on Windows (though no Windows build is yet provided)
 
      set PATH=%PATH;X:\path\to\yaz4j.dll
 
 That's one way of doing it, another would be to alter the standard set of
 arguments passed to the JVM before the Tomcat starts and add 
--Djava.library.path=/path/to/lib there. Depending on a situation this might be 
-preferable/easier (on Debian/Ubuntu you can specify JVM arguments using 
-/etc/default/tomcat6).
+`-Djava.library.path=/path/to/lib there`. Depending on a situation this might 
+be preferable/easier (on Debian/Ubuntu you can specify JVM arguments in the
+`/etc/default/tomcat6` file).
 
 With the shared library installed we need to install the pure-Java yaz4j-any*jar
 with ZOOM API classes by placing it in Tomcat's `lib` directory 
@@ -88,6 +97,8 @@ a project. To generate a skeleton for our webapp use the Maven archetype plugin:
 
 This will generate a basic webapp project structure:
 
+<blockcode>
+
 |-- pom.xml
 `-- src
 |-- main
@@ -105,10 +116,14 @@ This will generate a basic webapp project structure:
             `-- indexdata
                 `-- zgate
 
+</blockcode>
+
 Maven has already added basic JEE APIs for web development as the project 
 dependencies, we need to do the same for yaz4j, so edit the `pom.xml` and 
 add the following lines in the `dependencies` section:
 
+<blockcode type="xml">
+
 <dependency>
   <groupId>org.yaz4j</groupId>
   <artifactId>yaz4j-any</artifactId>
@@ -116,6 +131,8 @@ add the following lines in the `dependencies` section:
   <scope>provided</scope>
 </dependency>
 
+</blockcode>
+
 It's crucial that the scope of this dependency is set to `provided` otherwise
 the library would end up packaged in the .war archive and we don't want that.
 
@@ -124,6 +141,8 @@ The implementation of our simple gateway will be contained in a single servlet -
 The gateway will work by answering HTTP GET requests and will be controlled 
 solely by HTTP parameters, the servlet doGet method is shown below:
 
+<blockcode type="java">
+
 protected void doGet(HttpServletRequest request, HttpServletResponse response)
   throws ServletException, IOException {
     String zurl = request.getParameter("zurl");
@@ -170,6 +189,7 @@ protected void doGet(HttpServletRequest request, HttpServletResponse response)
     }
   }
 
+</blockcode>
 
 With the code in-place we can try to compile the project:
 
@@ -178,6 +198,8 @@ With the code in-place we can try to compile the project:
 If all is OK, the next step is to register our servlet and map it to an URL in 
 src/main/webapp/WEB-INF/web.xml:
 
+<blockcode type="xml">
+
 <servlet>
   <servlet-name>ZgateServlet</servlet-name>
   <servlet-class>com.indexdata.zgate.ZgateServlet</servlet-class>
@@ -187,27 +209,36 @@ src/main/webapp/WEB-INF/web.xml:
   <url-pattern>/zgate</url-pattern>
 </servlet-mapping>
 
+</blockcode>
+
 On top of that, we will also  make sure that our servlet is automatically 
 triggered when accessing the root path of our application:
 
+<blockcode type="xml">
+
 <welcome-file-list>
   <welcome-file>zgate</welcome-file>
   <welcome-file>index.jsp</welcome-file>
 </welcome-file-list>
 
+</blockcode>
+
 Now we are ready to build our webapp:
 
-  mvn package
+    mvn package
 
 The resulting .war archive is located under `target/zgate.war`, we can deploy
 it on tomcat (e.g by using the /admin Tomcat admin  console) and test by issuing
 the follwoing request with your browser or curl 
 (assuming Tomcat is running on localhost:8080):
 
-  http://localhost:8080/zgate/?zurl=z3950.loc.gov:7090/voyager&query=@attr%201=7%200253333490&syntax=usmarc
+    http://localhost:8080/zgate/?zurl=z3950.loc.gov:7090/voyager&query=@attr%201=7%200253333490&syntax=usmarc
 
   
 That's it! You just build yourself a HTTP-to-Z3950 gateway! Just be careful
-with exposing it to the outside world - it's not very secure and could be easily
-exploited. The source code and the gateway's Maven project is available in the
-yaz4j repository under examples/zgate. In the meantime, IndexData is working on a Debian/Ubuntu package (and maybe even a Windows installer :)) so installation of yaz4j and Tomcat configuration will be greatly simplified - so stay tuned!
+with exposing it to the outside world - it's not very secure and could be 
+easily exploited. The source code and the gateway's Maven project is available 
+in the Yaz4j's Git repository under examples/zgate. In the meantime, IndexData 
+is working on a Debian/Ubuntu package to make the installation of Yaz4j and 
+Tomcat configuration greatly simplified - so stay tuned!. If you are interested in Windows support - e.g. Visual Studio based build or an installer - please 
+let us know.