zorba-coders team mailing list archive

[Chris Hillery <chillery+launchpad@xxxxxxxxx>]

Chris Hillery has proposed merging lp:~zorba-coders/zorba/bug-857263-build-doc into lp:zorba.

Requested reviews:
  Chris Hillery (ceejatec)
Related bugs:
  Bug #857263 in Zorba: "Build/install doc is terrible"
  https://bugs.launchpad.net/zorba/+bug/857263

For more details, see:
https://code.launchpad.net/~zorba-coders/zorba/bug-857263-build-doc/+merge/104360
-- 
https://code.launchpad.net/~zorba-coders/zorba/bug-857263-build-doc/+merge/104360
Your team Zorba Coders is subscribed to branch lp:zorba.

=== modified file 'doc/zorba/build.dox'
--- doc/zorba/build.dox	2012-04-24 12:39:38 +0000
+++ doc/zorba/build.dox	2012-05-02 10:43:20 +0000
@@ -1,254 +1,18 @@
 /** \page build Zorba Build Instructions
 
-\section requirements Requirements
-
-\subsection buildsystem Build System
-
-In order to build Zorba, you need the Cross-Platform Make CMake 2.6 or later
-(except CMake 2.6.3 that has a serious bug preventing Zorba from building).
-You can download CMake from http://www.cmake.org/.
-
-\subsection compilers Compilers
-Zorba is tested with the following compilers:
-- GNU Compiler: GCC 3.4.x (32-bit & 64-bit) and GCC 4.x.x
-- Microsoft Compiler: MS VC++ 2008, and MS VC++ 2010 (including Express)
-
-\subsection required_libs Required Libraries
-In order to build Zorba, you need the following libraries and development headers:
-
-\subsubsection required_core_zorba Required for Core Zorba
-The following packages are mandatory to build the core part of Zorba.
-
-<ul>
-  <li>Libxml2 2.2.16 or later (http://xmlsoft.org/)</li>
-  <li>Iconv 1.12 (used by Libxml2; http://www.gnu.org/software/libiconv/)</li>
-  <li>ICU4C 3.6 or later (http://www.icu-project.org/)</li>
-</ul>
-
-\subsubsection optional_core_zorba Optional for Core Zorba
-The following packages are only required to build Zorba with some features (e.g. XML Schema or HTTP support).
-
-<ul>
-  <li>Xerces-C 2.8.0, 3.0.0 or later (http://xerces.apache.org/xerces-c/). This package is only required if built
-    with XML schema support. This feature is enabled by default. In order to disable XML schema support, you need
-    to provide the CMake configuration variable \c ZORBA_NO_XMLSCHEMA=ON.
-  </li>
-  <li>CURL 7.12 or later (http://curl.haxx.se/). This package is only required if
-    <a href="../../zorba/xqdoc/xhtml/www.zorba-xquery.com_modules_http-client.html">Zorba's HTTP module</a>
-    should be available.
-    Zorba will automatically be built with this module if the curl packages are installed. In order to suppress
-    HTTP support even though curl is installed, please set the CMake configuration variable \c ZORBA_SUPPRESS_CURL=ON.
-    Please note that other modules depend on this module (i.e. import it). Hence, those depending modules
-    will not work if the http module is not available. Please see our
-    <a href="../../zorba/xqdoc/xhtml/images/modules.svg">module dependency graph</a> for the
-    module inter-dependencies.
-  </li>
-  <li>LibXslt version 1.1.24 or later (http://xmlsoft.org/XSLT/). The LibXslt package is required for XQueryX support
-    (XQuery 1.0, XQuery 3.0, XQuery Update, and XQuery Full Text). This feature is not enabled by default.
-    It can be enabled if Zorba is compiled using the the CMake configuration variable \c ZORBA_XQUERYX=ON.
-  </li>
-  <li>Flex 2.5.33 or later (http://flex.sourceforge.net/) and Bison 2.4 or later (http://www.gnu.org/software/bison/)
-    are required to generate the XQuery scanner and XQuery parser. These packages are optional and only required
-    if you want to make modifications to the scanner or parser, respectively.
-  </li>
-</ul>
-
-\subsubsection required_language_bindings Required for Language Bindings
-In order to build the various language bindings that come with Zorba, you need
-at least Swig 1.3.40 or later (http://www.swig.org/download.html).
-All bindings are generated using Swig.
-
-For a particular language binding, you need the corresponding language tools
-and development headers.
-
-- Java (http://java.sun.com/javase/downloads/index.jsp)
-- Ruby (http://www.ruby-lang.org/en/downloads/)
-- PHP (http://www.php.net/downloads.php)
-- Python (http://www.python.org/download/)
-
-  
-\section buildingzorba Building Zorba
--# Install the Zorba source distribution (see \ref installation).
-  The directory in which the Zorba sources are installed
-  is referred to as \c [ZORBA] in the following.
--# If desired, also install or download the source for any non-core modules
-  that you would like to build along with Zorba, and ensure that you have
-  any libraries required by those modules available. See \ref build_noncore
-  for more details.
--# Zorba requires an
-   <a href="http://www.cmake.org/Wiki/CMake_FAQ#What_is_an_.22out-of-source.22_build.3F"; target="_blank">out-of-source build</a>.
-   We suggest to create the directory \c [ZORBA]/build
-   and refer to this directory as \c [ZORBABUILD] in the following.
--# Change the working directory into the \c [ZORBABUILD] directory
-   and execute cmake as follows:
-   <tt>cmake [ZORBA]</tt>.
-   In case the \c [ZORBABUILD]
-   is located directly within the \c [ZORBA] directory,
-   you can just type <tt>cmake ..</tt> .
-   This command should configure Zorba and prepare for the build.
-   CMake will tell you if your installation is missing
-   some of the required libraries or development headers.
--# If CMake executed successfully,
-   you should be able to build the project. For Makefile-based builds,
-   just type \c make (or \c make -j2 to do a parallel build on a multi-core
-   machine). For IDE-based builds, open the project created in the previous
-   step and build the \c ALL target.
-   The build will take some time.
-   If it finishes successfully,
-   you're ready to install and run Zorba
-   (see \ref installation).
-
-\subsection buildoptions Build Options
-
-- CMake is a meta build system,
-  meaning that it is able to generate native makefiles
-  (e.g. GNU Make or NMake)
-  and workspaces
-  (e.g. KDevelop or Visual Studio Projects).
-  For example,
-  you can create a KDevelop Project by executing the following command
-  in the \c [ZORBA] directory:
-  <tt>cmake -G KDevelop3 [ZORBABUILD]</tt>.
-- CMake supports multiple build configurations
-  (e.g. Debug, Release, or MinSizeRel).
-  By default,
-  Zorba is built in the Release configuration.
-  To change the build mode (to Debug, Release, RelWithDebInfo or MinSizeRel),
-  you can pass an additional parameter to CMake, e.g.,
-  <tt>cmake -D CMAKE_BUILD_TYPE=Debug [ZORBA]</tt>.
-- Zorba has other build options as well
-  (see \ref build_options).
-  You can tweak the performance and library footprint
-  by enabling or disabling various features from Zorba.
-
-\section mac Notes for Mac OS X Users 
-
-The easiest way to install the required packages (like CMake or Xerces-C) is
-to use Macports (http://macports.org/).
-
-Once all the required packages are installed you can execute CMake.
-By default,
-CMake on Mac OS X uses the Makefile generator.
-Alternatively,
-you can specify different generators (e.g., Xcode)
-by starting CMake using the -G option (e.g., -G Xcode). 
-
-\subsection swig Swig Version
-Due to a bug in older swig version,
-Zorba with SWIG support requires SWIG 
-version 1.3.40 or later.
-
-To do this,
-the swig package from macports should be installed
-and point cmake to use the new version:
-
-\code
-sudo port install swig
-cmake -DCMAKE_PREFIX_PATH=/opt/local ..
-\endcode
-
-\section windows Notes for Windows Users
-- In order to compile Zorba on Windows,
-  you need a working Visual Studio (Express) installation (2008, 2010).
-- If you want to compile Zorba using Visual Studio 2008,
-  you will need to install the
-  <a href="http://www.microsoft.com/downloads/en/details.aspx?FamilyId=D466226B-8DAB-445F-A7B4-448B326C48E7"; target="_blank">Visual C++ 2008 Feature Pack Release</a>.
-- Make sure that the libraries required for Zorba
-  are built with the same version of Visual Studio that you use.
-- The Windows version of some required packages
-  are distributed by other web sites
-  (all of them are pointed to from the main package web sites
-  indicated in the \ref required_libs section):
-  - Libxml2 and Iconv: http://www.zlatkovic.com/libxml.en.html
-  - CURL: http://curl.haxx.se/download.html
-  - Libxslt: http://www.zlatkovic.com/pub/libxml/
-
-- Zorba has in place an automatic DLL detection mechanism.
-  This will try to automatically gather all the DLLs
-  from the third party librbaries
-  and install them with Zorba when you do "name install"
-  or you build the Visual Studio INSTALL project.
-  Zorba will search for the third party libraries in order in:
-  - all the directories pointed by the \c ZORBA_THIRD_PARTY_REQUIREMENTS
-    cmake variable
-    - e.g. if you have Xerces in "C:\tools" and IConv in "D:\tools",
-      you must build with 
-      \code
-      -D ZORBA_THIRD_PARTY_REQUIREMENTS=C:\tools;D:\tool
-      \endcode
-      and Zorba will find all it needs from Xerces and Iconv.
-      (The directory names must contain "xerces" and "iconv" respectively, case insensitive)
-  - in the program files directory on your system
-    - e.g. if you have cURL installed in "C:\Program Files\*cURL*",
-      Zorba will find all it needs from cURL.
-      (The directory must contain "curl" case insensitive.)
-  - all the paths in the \c PATH variable
-    - e.g. if you have "C:\tools\*ICU*\bin" in your path,
-      Zorba will find all it needs from ICU.
-      (The directory must only contain "icu".)
-- Note: you can also use CMake's graphical interface.
-  This can usually be found in the \e Start menu.
-  This eases the setup and makes it more intuitive.
-
-\subsection nmake Building Zorba using a NMake Project
--# Start a Visual Studio Command Line.
--# Change the current working directory to the \c [ZORBA] directory.
--# It is not allowed to have
-   <a href="http://www.cmake.org/Wiki/CMake_FAQ#What_is_an_.22out-of-source.22_build.3F"; target="_blank">in-source builds</a>.
-   So you must create a build directory (e.g., <tt>[ZORBA]/build</tt>).
-   We refer to this directory as \c [ZORBABUILD] in the following steps.
--# Change the current working directory to the \c [ZORBABUILD] directory.
--# Execute CMake as follows <tt>cmake -G "NMake Makefiles" [ZORBA]</tt>.
-   CMake will try to find the necessary packages
-   in the program files directory
-   on your system and in the \c PATH environment variable. If one of the required dependencies were not found, CMake will stop with an error. See the next step only if this step did not find the required third party dependencies on your system.
--# If the command above fails or if you see that some optional packages were not found, you can help CMake a little by providing the lists of path where it should look for the libraries you need. In this case the CMake command should look like:
-\code
-"cmake" -G "NMake Makefiles" -D ZORBA_THIRD_PARTY_REQUIREMENTS=path\to\dir1;path\to\dir2;...
-\endcode
-
-But you can also manually set the paths to individual libraries and include directory by directly providing the variables set by each find package module (in the \c cmake_modules directory).
-
-In order to add XQueryX support you have to add ZORBA_XQUERYX=ON and add the paths to libxslt
-\code
--D ZORBA_XQUERYX=ON
--D LIBXSLT_INCLUDE_DIR="path_to_libxslt\include"
--D LIBXSLT_LIBRARIES="path_to_libxslt\lib\libxslt.lib"
-\endcode
-
-Now you are ready to call \c nmake from the \c [ZORBABUILD] directory.
-
-\subsection visualstudio Building Visual Studio Project
--# Start Visual Studio Command Line
--# Change the current working directory into the \c [ZORBA] directory.
--# Execute CMake as described above
-   but with the appropriate CMake Visual Studio generator
-   (<tt>-G "Visual Studio ..."</tt> instead of <tt>-G "NMake Makefiles"</tt>.
--# Start Visual Studio,
-   open the generated \c zorba.sln project file,
-   and start compilation.
-
-\subsection https_support HTTPS support
-- In order to have SSL support in Zorba,
-  you have to use the CURL library that has SSL support. 
-- There is one more thing:
-  in order to validate the server's certificate,
-  CURL+SSL needs to know about the root Certificates of Authenticity (CA):
-  a set of public keys freely available on the internet. 
-- On Windows,
-  Zorba expects this file to be called \c cacert.pem
-  and searches for it in the current directory and system paths. 
-- This \c cacert.pem file can be found on the curl page:
-  http://curl.haxx.se/docs/caextract.html .
-- In order to disable the validation of the server certificate,
-  the \c ZORBA_VERIFY_PEER_SSL_CERTIFICATE can be set to \c OFF
-  in cmake 
-  (and actually this is the default value).
-  Set it to \c ON to validate server certificate chain
-  on every access to \c https:// .
-- To read more about CURL+SSL: http://curl.haxx.se/docs/sslcerts.html .
-- As an \c https test page,
-  we used for example the rss feed
-  fn:doc('https://www.npr.org/rss/rss.php?id=1001') .
+The following pages describe how to build Zorba from source.
+
+- \ref build_prerequisites
+- \ref build_prepare
+- \ref configure_zorba
+- \ref build_and_install
+
+In addition, some platform-specific notes regarding building Zorba are
+available on the following pages. Please refer to them for
+clarifications and hints regarding the build process on your platform.
+
+- \ref build_ubuntu
+- \ref build_windows
+- \ref build_macos
 
 */

=== added file 'doc/zorba/build_and_install.dox'
--- doc/zorba/build_and_install.dox	1970-01-01 00:00:00 +0000
+++ doc/zorba/build_and_install.dox	2012-05-02 10:43:20 +0000
@@ -0,0 +1,59 @@
+/** \page build_and_install Building and Installing Zorba
+
+\section build_zorba Building Zorba
+
+Once you have successfully configured your Zorba build (as described
+in \ref configure_zorba), you should now be able to build the project.
+
+- For Makefile-based builds, just type \c make (or <tt>make j2</tt> to
+do a parallel build on a multi-core machine) from inside the \c
+{ZORBABUILD} directory.
+
+- For IDE-based builds, open the project created in the previous step
+ and build the \c ALL target.
+
+The build will take some time.  If it finishes successfully, you're
+ready to install and run Zorba.
+
+\section install_zorba Installing Zorba
+
+- For Makefile-based builds, just type <tt>make install</tt>.  There
+is also a <tt>make uninstall</tt> target.
+
+- For IDE-based builds, invoke the \c INSTALL project.
+
+In either case, Zorba will be installed into the location specified by
+the CMake configuration parameter \c CMAKE_INSTALL_PREFIX, as
+described in \ref configure_parameters.
+
+\section install_paths Setting the PATH
+
+In order for users on your system to use Zorba, the \c bin/ subdirectory
+of your installation directory must be on their path.
+
+\section testing_install Testing your Zorba Installation
+
+Once Zorba is installed and on your path, try it out! Type:
+
+\code
+zorba -q "1+1"
+\endcode
+
+You should get the following output:
+
+\code
+<?xml version="1.0" encoding="UTF-8"?>
+2
+\endcode
+
+If so - congratulations! You're done and ready to use Zorba.
+
+\section build_help Help!
+
+If you have any problems building or running Zorba, contact the \c
+zorba-users mailing list. Sign up and see other instructions at
+https://lists.sourceforge.net/lists/listinfo/zorba-users .
+
+
+*/
+

=== added file 'doc/zorba/build_configure.dox'
--- doc/zorba/build_configure.dox	1970-01-01 00:00:00 +0000
+++ doc/zorba/build_configure.dox	2012-05-02 10:43:20 +0000
@@ -0,0 +1,137 @@
+/** \page configure_zorba Configuring a Zorba Build Using CMake
+
+\section configure_overview Overview
+
+We will now configure the Zorba build by running CMake. We assume that
+the appropriate build preparations (described in \ref build_prepare)
+have been performed.
+
+\note
+The instructions in this section are based on executing commands at
+the command line. It is also possible configure Zorba using CMake's
+GUI configuration utility if you prefer. On Linux distributions, this
+is often a separate package named \"\c cmake-gui\". On Windows, the
+GUI is installed by default and can be started via the Start menu.  On
+MacOS, it is available as the \"\c gui\" variant of the \c cmake
+package.
+
+\note
+The important configuration parameters - source and build directory;
+CMake generator; configuration flags - are the same whether you use
+the command-line or the GUI form of CMake. Only the method by which
+you specify them will change.
+
+The basic steps to configure Zorba are:
+
+-# Change the working directory into the \c {ZORBABUILD} directory:
+\code
+cd {ZORBABUILD}
+\endcode
+-# Execute cmake:
+\code cmake [ -G generator ] [ -D option=value ... ] {ZORBASRC}
+\endcode
+where \c {ZORBASRC} may be an absolute or a relative path to your
+Zorba source directory. For example, if you used the convention of
+creating the build directory as a subdirectory of the source
+directory, you can just type \code cmake .. \endcode
+along with any necessary \c -G or \c -D options.
+
+This command should configure Zorba and prepare for the build.  CMake
+will tell you if your environment is missing some of the required
+libraries or development headers.
+
+The meaning of the \c -G and \c -D arguments are described below.
+
+\note
+If you need to re-configure the project later, CMake will remember
+your chosen generator and \c -D configuration parameters; it is not
+necessary to specify \c -G / \c -D every time.
+
+\section configure_generator CMake Generators (the -G argument)
+
+CMake is a meta build system. It is able to generate both native
+makefiles (e.g. GNU Make or NMake) and IDE workspaces (e.g. Visual
+Studio or KDevelop Projects), depending on which CMake \a generator is
+selected. By default it will generate a UNIX-style Makefile-based
+project.
+
+You specify the generator to use with the \c -G arguments to \c cmake.
+For example, on Windows, you can create a Visual Studio 10 solution by
+executing the following command in the \c {ZORBASRC} directory: \code
+cmake -G "Visual Studio 10" {ZORBASRC} \endcode
+
+The list of available Generators for your CMake installation
+can be seen by typing \" <tt>cmake --help</tt> \".
+
+\section configure_parameters Configuration Parameters (the -D arguments)
+
+In most circumstances it will be necessary to specify a few parameters to
+CMake, such as the various configuration parameters mentioned above in
+\ref third_party_libs. You do this with a series of \c -D arguments to
+CMake. For example, to build Zorba without ICU (Unicode) support:
+
+\code
+cmake -D ZORBA_NO_ICU=ON {ZORBASRC}
+\endcode
+
+A complete list of Zorba's configuration parameters can be found here:
+\ref configuration_parameters. CMake itself also has some
+configuration parameters that may be important for you; here are three
+of the most common:
+
+-# CMake will look for third-party libraries in a variety of standard
+  locations. If you have any installed in unusual locations, you will
+  need to provide it with additional paths to search. You do this by
+  specifying the parameter \c CMAKE_PREFIX_PATH. This parameter is a
+  semicolon-separated list of directories where CMake should look.
+  For instance, if you have Xerces-C installed in \c /opt, try the
+  following:
+\code
+cmake -D CMAKE_PREFIX_PATH=/opt {ZORBASRC}
+\endcode
+  \par On Linux and MacOS:
+  In command lines, the semicolon is
+  interpretted by the shell as a command separator. In order to pass a
+  semicolon-separated list of paths for this parameter, be sure to
+  enlose the list in single- or double-quotes.
+  \par On Windows:
+  Zorba uses a custom mechanism for specifying the paths to
+  third-party dependencies on Windows, which handles some additional
+  features such as collecting the runtime DLLs for installation.  You
+  should use this mechanism instead of \c CMAKE_PREFIX_PATH on Windows. See
+  \ref windows_autodll for more information.
+
+-# After you build Zorba, you will likely want to install it into a
+  final location. You specify this location with the \c
+  CMAKE_INSTALL_PREFIX parameter. By default, this directory will be
+  \c {ZORBABUILD}/dist, which is not likely to be a useful location.
+  \par Note:
+  After installation, the directory specified here will contain
+  subdirectories such as \c bin/, \c lib/, and \c share/. On Unix and
+  MacOS installations, a common value for \c CMAKE_INSTALL_PREFIX is
+  \c /usr/local. On Windows, something like <tt>C:\\Program
+  Files\\Zorba</tt> is suggested.
+  \par Note for Makefile-based projects:
+  The Makefiles produced by CMake do support the common \c DESTDIR
+  variable. However, specifying this variable at compile time <em>will
+  not work</em> with Zorba, because certain installation paths are
+  hard-coded into the Zorba binaries. Be sure to only use \c
+  CMAKE_INSTALL_PREFIX.
+
+-# When generating a Makefile-based project, CMake supports multiple
+  build configurations.  By default, Zorba is built in the Release
+  configuration, which enables compiler optimizations and does not
+  build debug information into the resulting product.  To change the
+  build mode to Debug, you can specify the \c CMAKE_BUILD_TYPE
+  parameter as follows:
+  \code cmake -D CMAKE_BUILD_TYPE=Debug {ZORBASRC} \endcode
+  This is not necessary for IDE-based workspaces;
+  in that case, you may select the type of build from within the IDE.
+
+
+\section configure_next What's next?
+
+Once CMake runs without reporting any configuration errors, move on to
+\ref build_and_install.
+
+*/

=== added file 'doc/zorba/build_macos.dox'
--- doc/zorba/build_macos.dox	1970-01-01 00:00:00 +0000
+++ doc/zorba/build_macos.dox	2012-05-02 10:43:20 +0000
@@ -0,0 +1,33 @@
+/** \page build_macos Zorba Build Notes for Mac OS X Users 
+
+\section macos_macports Using Macports
+
+The easiest way to install the required packages (like CMake or
+Xerces-C) is to use Macports (http://macports.org/). You can install
+various tools and libraries using e.g.
+\code
+sudo port install cmake
+\endcode
+
+Once all the required packages are installed you can execute CMake.
+By default,
+CMake on Mac OS X uses the Makefile generator.
+Alternatively,
+you can specify different generators (e.g., Xcode)
+by starting CMake using the \c -G option (e.g., <tt>-G Xcode</tt>). 
+
+\section macos_swig Swig Version
+
+Due to a bug in older swig version, Zorba with SWIG support requires
+SWIG version 1.3.40 or later. SWIG is included in stock MacOS, but in
+at least some versions of MacOS it is an older version. Therefore, you
+must install a newer SWIG from Macports. This will be installed in
+<tt>/opt/local</tt>, so you then must point CMake at that directory to
+ensure it finds the newer version:
+
+\code
+sudo port install swig
+cmake -DCMAKE_PREFIX_PATH=/opt/local {ZORBASRC}
+\endcode
+
+*/

=== removed file 'doc/zorba/build_noncore.dox'
--- doc/zorba/build_noncore.dox	2012-04-24 12:39:38 +0000
+++ doc/zorba/build_noncore.dox	1970-01-01 00:00:00 +0000
@@ -1,218 +0,0 @@
-/** \page build_noncore Building Non-core Zorba Modules
-
-\section noncore_download Downloading source code for non-core modules
-
-Currently, the Zorba team does not provide source downloads for the
-non-core modules. However, there is a simple CMake script inside Zorba
-which will allow you to check out these modules from source control
-easily. Note that this requires having the Subversion utility available
-on your system.
-
-From your [ZORBA] directory, type
-\code
-  cmake -Doutdir=../zorba_modules -Dmodname=NAME -P modules/DownloadModules.cmake
-\endcode
-
-to download the particular module package NAME (see \ref
-non_core_modules for a complete list of module packages and their
-contents), or
-
-\code
-  cmake -Doutdir=../zorba_modules -Dallmodules=1 -P modules/DownloadModules.cmake
-\endcode
-
-to download all the modules. (On Windows, you will need to use backslashes instead of forward slashes in the above paths.)
-
-This will place the downloaded module source code in the directory
-\c ../zorba_modules, which is where the Zorba build will look for them by
-default. If you wish to download them to some other location, you may do
-so; in that case, when you configure the Zorba build with CMake, provide
-the \c -DZORBA_MODULES_DIR=/full/path/to/modules argument.
-
-\subsection noncore_dependencies Dependencies among Non-core Modules
-
-Please note that some of these modules depend on other modules.  Most
-notably, the EXPath http-client module (in the \c http-client module
-package) depends on the \c tidy module, which is in the \c data-converters module package. So, if you download the \c http-client package, you must also download the \c data-converters package (and ensure that libtidy is installed, as mentioned below).
-
-Please see our <a
-href="../../zorba/xqdoc/xhtml/images/modules.svg">module-interdependency
-graph</a> for details.
-
-
-\section noncore_requirements Non-core Module Requirements
-For many of the non-core modules, you need additional libraries.
-All such modules are not built if the library (and development headers) they require are not available.
-Here is a list of the libraries required by the current non-core modules packages:
-
-- data-converters (JSon, CSV, HTML)
-  - Tidy (http://tidy.sourceforge.net)
-  - Jansson (http://www.digip.org/jansson/)
-- data-formatting (XSL-FO)
-  - Java (http://java.sun.com/javase/downloads/index.jsp)
-  - Apache FOP (http://xmlgraphics.apache.org/fop/download.html)
-- email
-  - IMAP CClient (http://www.washington.edu/imap/)
-- geo
-  - GEOS version 3.2.2 or later (http://trac.osgeo.org/geos/)
-- EXPath http-client
-  - CURL 7.12 or later (http://curl.haxx.se/)
-- image
-  - ImageMagick (http://www.imagemagick.org)
-- languages (XSLT)
-  - LibXslt version 1.1.24 or later (http://xmlsoft.org/XSLT/)
-
-
-In many cases you can find binary packages for these dependencies, which 
-will be the quickest and easiest way to meet the requirements. We have
-provided links or instructions for downloading binary packages for these
-libraries below, along with some instructions that we have found when
-building these libraries from source.
-
-
-\subsection buildcclient Building IMAP CClient
-
-Zorba provides email support using the CClient library part of the <a href="http://www.washington.edu/imap/"; target="_blank">UW IMAP toolkit</a>.
-
-\subsubsection cclientunix Unix/Linux/Mac OS X
-Notes:
-- There are some known issues with the CClient packages
-  that come with different Linux distributions.
-- On x32 bit OpenSuse and also on x64 bit Ubuntu,
-  we noticed that the CClient shared library is broken
-  (undefined symbol: mm_dlog).
-- Due to that fact that Mark Crispin
-  (the creator of CClient library)
-  does not support CClient as a shared library but only as a static library
-  (see <a href="http://www.washington.edu/imap/IMAP-FAQs/index.html#6.3"; target="_blank">FAQs shared library</a>),
-  we strongly suggest you want to get the
-  <a href="http://www.washington.edu/imap/"; target="_blank">UW IMAP toolkit</a>
-  and compile it yourself.
-- On Linux 64-bit,
-  you might discover a problem with the optional package cclient.
-  E.g. on Ubuntu 64-bit, you might discover the following:
-  \code
-Linking CXX shared library libsmtp.so
-/usr/bin/ld: /usr/lib/gcc/x86_64-linux-gnu/4.4.3/../../../../lib/libc-client.a(osdep.o): relocation R_X86_64_32 against
-  `server_input_wait' can not be used when making a shared object; recompile with -fPIC
-/usr/lib/gcc/x86_64-linux-gnu/4.4.3/../../../../lib/libc-client.a: could not read symbols: Bad value
-  \endcode
-  To fix this,
-  you need to compile CClient yourself.
-  The commands to compile CClient correctly are:
-  \code
-cd <some_directory>
-wget ftp://ftp.cac.washington.edu/imap/imap-2007e.tar.gz
-tar -xf imap-2007e.tar.gz
-cd imap-2007e
-make slx EXTRACFLAGS="-I/usr/include/openssl -fPIC"
-  \endcode
-
-- Also please keep in mind that if SSL/TLS authentication is required
-  by the SMTP server,
-  then you first need to install
-  <a href="http://www.openssl.org/"; target="_blank">OpenSSL</a>
-  and configure CClient to use it.
-- Make sure the name of the library is prefixed by \c lib
-  and suffixed with \c .a
-  (for example \c libc-client.a on Linux/Unix
-  or \c libc-client4.a on Mac OS X).
-
-Use the following extra CMake arguments when building Zorba:
-\code
--D "CCLIENT_INCLUDE=path_to_imap-2007e/c-client"
--D "CCLIENT_LIBRARY=path_to_imap-2007e/c-client/libc-client.a"
-\endcode
-
-Here are some quick suggestions to build CClient on Linux:
-- x32-bit Linux: <tt>make lnp</tt>
-- x64-bit Linux: <tt>make lnp  EXTRACFLAGS="-I/usr/include/openssl -fPIC" EXTRAAUTHENTICATORS=gss</tt> in order to build with SSL and Kerberos support.<br />
-
-For more detailed build instructions,
-please see the
-<a href="http://www.washington.edu/imap/documentation"; target="_blank">UW IMAP toolkit "Server Documentation"</a>
-and the <a href="http://www.washington.edu/imap/IMAP-FAQs/index.html"; target="_blank">UW IMAP FAQs</a>.
-
-\subsubsection cclientwindows Windows
-
-You must build the
-<a href="http://www.washington.edu/imap/"; target="_blank">UW IMAP toolkit</a>.
-
-Use the following extra CMake arguments when building Zorba:
-\code
--D "CCLIENT_INCLUDE=path_to_imap-2007e\c-client"
--D "CCLIENT_LIBRARY=path_to_imap-2007e\c-client\release\cclient.lib"
-\endcode
-
-\subsection buildjansson Building Jansson
-
-Zorba provides Json manipulation support
-using the Jansson Library (http://www.digip.org/jansson/).
-
-\subsubsection janssonunix Unix/Linux/Mac OS X
-
-For Linux/Unix systems,
-download the Jansson library from http://www.digip.org/jansson/releases/.
-Then follow the instructions from
-http://www.digip.org/jansson/doc/2.0/gettingstarted.html#compiling-and-installing-jansson.
-
-The source use GNU Autotools
-(autoconf, automake, libtool),
-so compiling and installing is extremely simple:
-\code
-./configure
-make
-make check
-make install
-\endcode
-
-On Fedora starting with version 12, Jansson is also available as a package,
-so (as root) you can simply run: 
-\code
-yum install -y jansson-devel
-\endcode
-
-Ubuntu packages are available from PPA of
-https://launchpad.net/~petri/+archive/ppa
-
-\subsubsection janssonwindows Windows
-
-For Windows please follow these steps:
-- download Jansson from https://github.com/akheron/jansson/zipball/master
-- rename src/jansson_config.h.win32 to src/jansson_config.h
-- replace \c snprintf with \c _snprintf in \c src/dump.c lines 188 and 202
-  and \c load.c lines 96 and 108
-- replace \c json_strtoint with \c strtol in \c load.c line 481
-- add all headers and source files in src folder and create a static library
-
-There will be a new Jansson 2.0.1 release
-that will include the fixed described above.
-
-\subsection buildimagemagick Building ImageMagick
-
-Zorba provides image manipulation support
-using the ImageMagick Library (http://www.imagemagick.org).
-
-\subsubsection imagemagickunix Unix/Linux/Mac OS X
-
-For Linux/Unix systems,
-just use the package manager to install the
-magick++, magickwand, magickcore packages
-including the developer versions of these packages
-(that inlcude the header files).
-
-On OSX, use macports to install imagemagick.
-
-\subsubsection imagemagickwindows Windows
-
-For Windows,
-just download the ImageMagick windows binary (Q8-windows-dll) and install it.
-
-\subsection buildtidy Libtidy
-
-\subsubsection buildtidywindows Windows
-
-A binary installer for Tidy is available at: http://dev.int64.org/tidy.html
-
-
-*/

=== removed file 'doc/zorba/build_options.dox'
--- doc/zorba/build_options.dox	2011-10-31 21:31:40 +0000
+++ doc/zorba/build_options.dox	1970-01-01 00:00:00 +0000
@@ -1,35 +0,0 @@
-/** \page build_options Zorba Build Options
-
-\section ZORBA_WITH_BIG_INTEGER Big Integer Support (ZORBA_WITH_BIG_INTEGER)
-
-The Zorba XQuery processor
-by default
-has arbitrary precision
-for the \c xs:integer type.
-Compared to a C++ \c int,
-however,
-arbitrary precision integers
-are orders of magnitude slower.
-If arbitrary precision integers are not needed,
-they can be disabled
-by configuring Zorba
-with the
-\c ZORBA_WITH_BIG_INTEGER
-option set to \c OFF.
-
-When arbitrary precision integers are disabled,
-Zorba uses a C++ <code>long long</code>
-for \c xs:integer,
-the precision for which
-is dependent on your C++ implementation.
-Typically, however,
-the precision is at least 64 bits.
-However,
-in order to maintain the condition
-that the value space for \c xs:nonNegativeInteger
-is a subset of that of \c xs:integer,
-one less bit is allowed
-for \c xs:nonNegativeInteger.
-
-*/
-/* vim:set et sw=2 ts=2: */

=== added file 'doc/zorba/build_parameters.dox'
--- doc/zorba/build_parameters.dox	1970-01-01 00:00:00 +0000
+++ doc/zorba/build_parameters.dox	2012-05-02 10:43:20 +0000
@@ -0,0 +1,99 @@
+/** \page configuration_parameters Zorba Configuration Parameters
+
+This is a list of all published Zorba configuration parameters.  You
+specify these parameters at CMake configuration time with the \c -D
+argument. See \ref configure_parameters for more information.
+
+\section configure_enable Enabling/Disabling Zorba Features
+
+\subsection ZORBA_WITH_JSON Integral JSON Support
+
+Zorba 2.5 introduces support for JSON data as a first-class citizen in
+the XQuery world. See http://www.jsoniq.org/ for more information
+about this exciting development.
+
+To enable this support, configure with <tt>-D ZORBA_WITH_JSON=ON</tt>.
+
+\subsection ZORBA_WITH_BIG_INTEGER Big Integer Support
+
+The Zorba XQuery processor by default has arbitrary precision for the
+\c xs:integer type.  Compared to a C++ \c int, however, arbitrary
+precision integers are orders of magnitude slower.  If arbitrary
+precision integers are not needed, they can be disabled by configuring
+Zorba with the \c ZORBA_WITH_BIG_INTEGER option set to \c OFF,
+i.e. <tt>-D ZORBA_WITH_BIG_INTEGER=OFF</tt>
+
+When arbitrary precision integers are disabled, Zorba uses a C++
+<code>long long</code> for \c xs:integer, the precision for which is
+dependent on your C++ implementation.  Typically, however, the
+precision is at least 64 bits.  However, in order to maintain the
+condition that the value space for \c xs:nonNegativeInteger is a
+subset of that of \c xs:integer, one less bit is allowed for \c
+xs:nonNegativeInteger.
+
+\subsection ZORBA_NO_FULL_TEXT XQuery Full-Text Support
+
+Zorba by default supports the XQuery Full-Text specification
+(http://www.w3.org/TR/xpath-full-text-10/ ). If you wish to disable
+this support, configure with <tt>-D ZORBA_NO_FULL_TEXT=ON</tt>.
+
+\subsection ZORBA_XQUERX XQueryX Support
+
+Zorba by default does not build with support for XQueryX (which is an
+alternate representation of XQuery using pure XML). To enable this
+support, configure with <tt>-DZORBA_XQUERYX=ON</tt>. Note that
+building with XQueryX support requires LibXslt to be available.
+
+\subsection ZORBA_VERIFY_PEER_SSL_CERTIFICATE Enabling SSL Peer Verification
+
+By default, Zorba's HTTP module does not validate the SSL certificate
+sent to it by HTTPS servers. This is because not all systems have a
+complete or valid set of root certificates against which to validate
+said server certificates. If you wish to enable SSL peer validation,
+configure with <tt>-D ZORBA_VERIFY_PEER_SSL_CERTIFICATE=ON</tt>.
+
+\section configure_deps Disabling Zorba Library Requirements
+
+\subsection ZORBA_NO_ICU Disable ICU (Unicode) Support
+
+The ICU library provides Unicode functionality, and is required by
+default when building Zorba. To disable this requirement, configure
+with <tt>-D ZORBA_NO_ICU=ON</tt>.
+
+\subsection ZORBA_NO_XMLSCHEMA Disable Xerces (XML Schema) Support
+
+The Xerces-C library provides XML Schema functionality, and is
+required by default when building Zorba. To disable this requirement,
+configure with <tt>-D ZORBA_NO_XMLSCHEMA=ON</tt>.
+
+\subsection ZORBA_SUPPRESS_CURL Disable Curl (HTTP) Support
+
+The Curl library provides HTTP functionality. Zorba will automatically
+build with HTTP support (via the built-in \c http-client module) if it
+detects \c libcurl. To suppress this check (so you can build Zorba
+without HTTP support even if Curl is installed on your system),
+configure with <tt>-D ZORBA_SUPPRESS_CURL=ON</tt>.
+
+\section configure_buildparams Parameters for Compiling
+
+\subsection ZORBA_MODULES_DIR Specifying the Directory for Non-Core Modules
+
+By default, Zorba will automatically build any non-core module
+packages it finds in a directory named \c zorba_modules that is a
+sibling to the directory containing Zorba's own source (that is,
+\"<tt>../zorba_modules</tt>\" from the source directory).  See \ref
+noncore_download for more information.
+
+If you wish to build non-core modules from a different location,
+configure with <tt>-D ZORBA_MODULES_DIR=/path/to/modules</tt>.
+
+\subsection ZORBA_THIRD_PARTY_REQUIREMENTS Specifying the Location of Third-Party Requirements on Windows
+
+On Windows, you should configure with <tt>-D
+ZORBA_THIRD_PARTY_REQUIREMENTS=/path1;/path2</tt> to indicate the
+path(s) to third-party libraries, instead of \c
+CMAKE_PREFIX_PATH. This is described in detail at \ref
+windows_autodll.
+
+*/
+/* vim:set et sw=2 ts=2: */

=== added file 'doc/zorba/build_prepare.dox'
--- doc/zorba/build_prepare.dox	1970-01-01 00:00:00 +0000
+++ doc/zorba/build_prepare.dox	2012-05-02 10:43:20 +0000
@@ -0,0 +1,104 @@
+/** \page build_prepare Preparing to Build Zorba
+
+The following outlines the common steps for building Zorba once the
+required and optional tools and libraries (as described in \ref
+build_prerequisites) have been installed.
+
+\section build_gettingsrc Getting the Zorba Source Code
+
+You may get the Zorba source code in one of two ways: downloading a
+released source distribution, or getting the code from our Launchpad
+code repository. The directory that the Zorba source code is placed
+into will be referred to as \c {ZORBASRC} in later instructions.
+
+\subsection download_source Getting a Source Code Release
+
+You may download the latest Zorba release source code as either a \c
+.zip or \c .tar.gz file from Launchpad:
+https://launchpad.net/zorba/+download .
+
+\subsection checkout_source Getting the Latest Code from Launchpad
+
+If you want the very latest and greatest Zorba source, you can check
+out our source code trunk from our Launchpad repository. This is
+actually a pretty "safe" option, compared to many projects, as Zorba
+attempts to enforce a "trunk is always releasable" policy through
+extensive regression testing on every trunk checkin.
+
+Launchpad uses the Bazaar distributed version control system from
+Canonical, the producers of Ubuntu Linux and Launchpad. So you will
+need to install Bazaar in order to check out our code
+repositories. Installers are available from Canonical's website,
+http://bazaar.canonical.com/ . Bazaar packages are also available for
+all Linux distributions (the package name may be "bazaar" or "bzr"),
+and in Macports for MacOS X.
+
+Once you have Bazaar installed, check out the Zorba trunk:
+
+\code
+bzr checkout --lightweight lp:zorba
+\endcode
+
+\section noncore_download Downloading source code for non-core modules
+
+Zorba offers a number of optional ("non-core") modules which provide
+additional functionality; see \ref non_core_modules for a list. When
+you build Zorba, you may also build any non-core modules at the same
+time, and these modules will then be available in your Zorba
+installation.
+
+Currently, the Zorba team does not provide source downloads for the
+non-core modules. However, there is a simple CMake script inside Zorba
+which will allow you to check out these modules from source control
+easily. Note that this requires having the Bazaar utility available
+on your system; see \ref checkout_source for more information.
+
+From your {ZORBASRC} directory, type
+\code
+  cmake -Doutdir=../zorba_modules -Dmodname=NAME -P modules/DownloadModules.cmake
+\endcode
+
+to download the particular module package NAME (see \ref
+non_core_modules for a complete list of module packages and their
+contents), or
+
+\code
+  cmake -Doutdir=../zorba_modules -Dallmodules=1 -P modules/DownloadModules.cmake
+\endcode
+
+to download all the modules. (On Windows, you will need to use backslashes instead of forward slashes in the above paths.)
+
+This will place the downloaded module source code in the directory
+<tt>../zorba_modules</tt>, which is where the Zorba build will look
+for them by default. If you wish to download them to some other
+location, you may do so; in that case, when you configure the Zorba
+build with CMake, provide the \c
+-DZORBA_MODULES_DIR=/full/path/to/modules argument.
+
+\note
+Please note that some of these modules depend on other modules.  Most
+notably, the EXPath http-client module (in the \c http-client module
+package) depends on the \c html module, which is in the \c
+data-converters module package. So, if you download the \c http-client
+package, you must also download the \c data-converters package (and
+ensure that \c libtidy is installed; see \ref noncore_requirements).
+\note
+Please see our <a
+href="../../zorba/xqdoc/xhtml/images/modules.svg">module-interdependency
+graph</a> for details.
+
+\section create_build_dir Creating a Build Directory
+
+Zorba requires an <a
+href="http://www.cmake.org/Wiki/CMake_FAQ#What_is_an_.22out-of-source.22_build.3F";
+target="_blank">out-of-source build</a>, which means you need to
+create a separate (empty) build directory. A common convention is to
+create a directory named \"\c build\" in the Zorba source directory,
+but you may name it and place it anywhere you like.  We refer to this
+directory as \c {ZORBABUILD} in the following steps.
+
+\section prepare_next What's next?
+
+Now, go on to \ref configure_zorba.
+
+*/

=== added file 'doc/zorba/build_prerequisites.dox'
--- doc/zorba/build_prerequisites.dox	1970-01-01 00:00:00 +0000
+++ doc/zorba/build_prerequisites.dox	2012-05-02 10:43:20 +0000
@@ -0,0 +1,138 @@
+/** \page build_prerequisites Prerequisites for Building Zorba
+
+The following tools and libraries are utilized by Zorba.
+
+\section cmake Configuration System
+
+In order to build Zorba, you need the cross-platform build system
+CMake, version 2.6 or later (except CMake 2.6.3 that has a serious bug
+preventing Zorba from building).  CMake's homepage is
+http://www.cmake.org/, and this is the best source for the Windows
+CMake installer. It is also available packaged for most Linux
+distributions, as well as in Macports for MacOS builds.
+
+\section compilers Compilers
+
+Zorba is tested with the following compilers:
+- GNU Compiler: GCC 3.4.x (32-bit & 64-bit) and GCC 4.x.x
+- Microsoft Compiler: MS VC++ 2008, and MS VC++ 2010 (including Express)
+
+\section third_party_libs Library Dependencies
+
+Zorba uses a number of libraries from third parties. A few of these
+are required for all Zorba installations, but we have tried to keep
+this number as low as possible. Several others are required to enable
+certain Zorba features.
+
+\note The following descriptions sometimes reference "CMake
+configuration parameters". These are passed to CMake during the
+configuration step; see \ref configure_zorba.
+
+\subsection required_core_zorba Required for Core Zorba
+The following packages are mandatory to build the core part of Zorba.
+
+- Libxml2 2.2.16 or later (http://xmlsoft.org/)
+- Iconv 1.12 (used by Libxml2; http://www.gnu.org/software/libiconv/)
+
+\subsection recommended_core_zorba Recommended for Core Zorba
+
+The following packages are necessary to enable certain features in
+Zorba. These features are normally desired, so you will need to
+explicitly disable them in order to build without these libraries.
+
+- Xerces-C 2.8.0, 3.0.0 or later
+    (http://xerces.apache.org/xerces-c/). This package is required to
+    enable XML schema support. This feature is enabled by default. In
+    order to disable XML schema support, you need to provide the CMake
+    configuration parameter \c ZORBA_NO_XMLSCHEMA=ON.
+
+- ICU4C 3.6 or later (http://www.icu-project.org/). This package is
+  required to enable Unicode support as well as some other
+  internationalization features. This feature is enabled by
+  default. To build without ICU, you need to provide the CMake
+  configuration parameter \c ZORBA_NO_ICU=ON.
+
+\subsection optional_core_zorba Optional for Core Zorba
+
+The following packages are also necessary to enable certain features
+in Zorba. These features will automatically be disabled (or are not
+enabled by default) if the corresponding dependencies are not detected
+by CMake.
+
+- CURL (libcurl) 7.12 or later (http://curl.haxx.se/). This package is
+    required if <a
+    href="../../zorba/xqdoc/xhtml/www.zorba-xquery.com_modules_http-client.html">Zorba's built-in
+    HTTP module</a> should be available.  Zorba will automatically be
+    built with this module if the curl packages are installed.
+    \note Please note that other modules depend on the http-client module
+    (i.e., import it). Hence, those dependent modules will not work if
+    the http module is not available. Please see our <a
+    href="../../zorba/xqdoc/xhtml/images/modules.svg">module
+    dependency graph</a> for the module inter-dependencies.
+    \note Also note that Zorba internally uses this module when resolving
+    http: URIs in queries, module/schema imports, and so on. If this
+    module is not installed, Zorba will be unable to download such
+    URIs from the web.
+    \note If you happen to have libcurl installed but would like to build
+    Zorba without HTTP support, you may set the CMake configuration
+    parameter \c ZORBA_SUPPRESS_CURL=ON.
+
+- LibXslt version 1.1.24 or later (http://xmlsoft.org/XSLT/). The
+    LibXslt package is required for XQueryX support. This feature is
+    not enabled by default.  To enable XQueryX support, you need to
+    provide the CMake configuration parameter \c ZORBA_XQUERYX=ON.
+
+- Flex 2.5.33 or later (http://flex.sourceforge.net/) and
+    Bison 2.4 or later (http://www.gnu.org/software/bison/) are
+    used to generate the XQuery scanner and XQuery parser. The Zorba
+    source includes pre-generated versions of these, so Flex and Bison
+    are only required if you are developing Zorba itself and need to
+    modify the scanner or parser.
+
+\subsection required_language_bindings Required for Language Bindings
+In order to build the various language bindings that come with Zorba, you need
+at least Swig 1.3.40 or later (http://www.swig.org/download.html).
+All bindings are generated using Swig.
+
+For a particular language binding, you need the corresponding language
+tools and development headers. CMake will automatically enable the
+language bindings for any language that is detected.
+
+- Java (http://java.sun.com/javase/downloads/index.jsp)
+- Ruby (http://www.ruby-lang.org/en/downloads/)
+- PHP (http://www.php.net/downloads.php)
+- Python (http://www.python.org/download/)
+
+\subsection noncore_requirements Non-core Module Requirements
+For many of the non-core modules, you need additional libraries.
+All such modules are not built if the library (and development headers) they require are not available.
+Here is a list of the libraries required by the current non-core modules packages:
+
+- data-converters (CSV, HTML)
+  - Tidy (http://tidy.sourceforge.net)
+- data-formatting (XSL-FO)
+  - Java (http://java.sun.com/javase/downloads/index.jsp)
+  - Apache FOP (http://xmlgraphics.apache.org/fop/download.html)
+- email
+  - IMAP CClient (http://www.washington.edu/imap/)
+- geo
+  - GEOS version 3.2.2 or later (http://trac.osgeo.org/geos/)
+- EXPath http-client
+  - CURL 7.12 or later (http://curl.haxx.se/)
+- image
+  - ImageMagick (http://www.imagemagick.org)
+- languages (XSLT)
+  - LibXslt version 1.1.24 or later (http://xmlsoft.org/XSLT/)
+
+In many cases you can find binary packages for these dependencies, which 
+will be the quickest and easiest way to meet the requirements. We have
+provided links or instructions for downloading binary packages for some
+libraries on the "Build Notes" pages for various platforms; see \ref build.
+
+
+\section prereq_next What's Next?
+
+Once you have obtained all the prerequisite tools and libraries for
+your installation, move on to \ref build_prepare.
+
+*/

=== modified file 'doc/zorba/build_ubuntu.dox'
--- doc/zorba/build_ubuntu.dox	2012-04-24 12:39:38 +0000
+++ doc/zorba/build_ubuntu.dox	2012-05-02 10:43:20 +0000
@@ -1,32 +1,86 @@
 /**
 
-\page build_ubuntu Build Zorba on Ubuntu Linux
-
-\section bu_instructions Instructions
-
-For building Zorba on Ubuntu 11.04 (gcc version 4.5.2) folow the next steps:
-
-Install tools
-\code
+\page build_ubuntu Zorba Build Notes for Ubuntu/Debian Linux Users
+
+\section ubuntu_packages Ubuntu Packages
+
+Most of the tools and libraries you might need to build Zorba are
+available in the standard Ubuntu/Debian repositories.  Here we list
+the packages that you should install to meet the requirements
+specified at \ref build_prerequisites.
+
+\subsection ubuntu_tools Tools
+To install the gcc compiler and CMake:
+\code
+sudo apt-get install build-essential cmake
+\endcode
+
+To install Bazaar (for building the latest Zorba source, or for
+building non-core modules):
+\code
+sudo apt-get install bzr
+\endcode
+
+\subsection ubuntu_libs Core Zorba Library Dependencies
+Required libraries for core Zorba:
+\code
+sudo apt-get install libxml2-dev
+\endcode
+
+Recommended libraries for core Zorba:
+\code
+sudo apt-get install libicu-dev libxerces-c-dev
+\endcode
+
+Optional libraries for core Zorba:
+\code
+sudo apt-get install libxslt-dev libcurl4-openssl-dev libxerces-c-dev
+\endcode
+
+SWIG and development requirements for Zorba language bindings:
+\code
+sudo apt-get install swig python-dev php5-dev ruby-dev openjdk-6-jdk libaccess-bridge-java-jni
+\endcode
+
+\subsection ubuntu_noncore_libs Non-Core Module Library Dependencies
+
+\subsubsection ubuntu_html HTML Module (data-converters package)
+\code
+sudo apt-get install libtidy-dev
+\endcode
+
+\subsubsection ubuntu_geos Geo Module
+
+To install libgeos for the Geo Module, first ensure that the version
+available for your distribution is at least 3.2.2:
+
+\code
+apt-cache show libgeos-dev | grep Version:
+\endcode
+
+If it is lower than 3.2.2, then you may add our PPA to your list of
+repositories to get a later version:
+
+\code
+sudo add-apt-repository ppa:juan457/zorba
 sudo apt-get update
-sudo apt-get install subversion bzr build-essential cmake
-\endcode
-
-Optional
-\code
-sudo apt-get install valgrind
-\endcode
-
-Required libraries
-\code
-sudo apt-get install libxml2-dev libxslt-dev libicu-dev libcurl4-openssl-dev libtidy-dev libxerces-c-dev libz-dev
-\endcode
-
-
-\section bu_cclient Build C-Client library
-
-One option is to install the c-client lib from
-<a href=" http://launchpad.net/~juan457/+archive/zorba/+packages";>ppa:juan457/zorba</a>.
+\endcode
+
+In either case, install libgeos with:
+\code
+sudo apt-get install libgeos-dev
+\endcode
+
+\subsubsection ubuntu_imagemagick ImageMagick (for image modules)
+
+\code
+sudo apt-get install imagemagick libmagick++-dev libmagickwand-dev
+\endcode
+
+\subsubsection ubuntu_cclient Email Module
+
+We recommend using our PPA to install the C-Client module, as the
+Ubuntu packages are not built correctly at least on 64-bit platforms.
 
 \code
 sudo add-apt-repository ppa:juan457/zorba
@@ -34,8 +88,8 @@
 sudo sudo apt-get install libc-client2007e libc-client2007e-dev
 \endcode
 
-
-Or build it localy using the -I/usr/include/openssl -fPIC options:
+Or, you may build it yourself from source, so long as you force the
+-fPIC option:
 
 \code
 wget ftp://ftp.cac.washington.edu/imap/imap-2007e.tar.gz
@@ -45,96 +99,14 @@
 make lnp EXTRACFLAGS="-I/usr/include/openssl -fPIC"
 \endcode
 
-Note: To try again in case of errors, delete all, untar and make again, don't trust make clean.
-
-
-\section bu_imagemagick Install ImageMagick (for image modules)
-
-\code
-sudo apt-get install imagemagick libmagick++-dev
-\endcode
-
-
-
-\section bu_geos Install GEOS (for geo module)
-
-\code
-sudo apt-get install libgeos-dev
-\endcode
-
-If the version is older than 3.2.2 then there are two options:
-
-a. install it from <a href=" http://launchpad.net/~juan457/+archive/zorba/+packages";>ppa:juan457/zorba</a>.
-
-\code
-sudo add-apt-repository ppa:juan457/zorba
-sudo apt-get update
-sudo apt-get install libgeos libgeos-dev
-\endcode 
-
-b. or compile it manually:
-
-\code
-sudo apt-get remove libgeos-dev
-svn checkout http://svn.osgeo.org/geos/trunk geos-svn
-cd geos-svn
-mkdir build
-cd build
-cmake ..
-make
-sudo make install
-\endcode
-
-
-
-\section bu_jansson Install Jansson (for JSON module)  from ppa:petri/ppa
-
-\code
-sudo add-apt-repository ppa:petri/ppa
-sudo apt-get update
-sudo apt-get install libjansson4 libjansson-dev
-\endcode
-
-
-
-\section bu_build_zorba Get and build Zorba
-
-\code
-bzr branch lp:zorba
-cd zorba
-cmake -Doutdir=../zm -Dallmodules=1 -P modules/DownloadModules.cmake
-mkdir build
-cd build
-\endcode
-
-If all libraries were installed from ppa-s:
-\code
-cmake ..
-make
-\endcode
-
-Otherwise specify the location of c-client library:
-\code
-cmake -DCMAKE_BUILD_TYPE="Debug" -DCMAKE_PREFIX_PATH="~/imap-2007e/c-client" ../
-make
-\endcode
-
-
-
-\section bu_running_tests Run tests
-
-To run all Zorba tests:
-\code
-ctest
-\endcode
-
-
-
-\section bu_install Installation
-
-To install this version of Zorba:
-\code
-make install
-\endcode
-
-**/
+Note: In case of errors, delete all, untar and make again, don't trust
+make clean.
+
+If you do this, be sure to pass the path to the \"\c c-client\"
+subdirectory of your build to CMake when configuring Zorba, e.g.:
+\code
+cmake -DCMAKE_PREFIX_PATH="~/imap-2007e/c-client" ../
+make
+\endcode
+
+*/

=== added file 'doc/zorba/build_windows.dox'
--- doc/zorba/build_windows.dox	1970-01-01 00:00:00 +0000
+++ doc/zorba/build_windows.dox	2012-05-02 10:43:20 +0000
@@ -0,0 +1,109 @@
+/** \page build_windows Zorba Build Notes for Windows Users
+
+\section windows_requirements Requirements for Windows Builds
+- In order to compile Zorba on Windows,
+  you need a working Visual Studio (Express) installation (2008, 2010).
+- If you want to compile Zorba using Visual Studio 2008,
+  you will need to install the
+  <a href="http://www.microsoft.com/downloads/en/details.aspx?FamilyId=D466226B-8DAB-445F-A7B4-448B326C48E7"; target="_blank">Visual C++ 2008 Feature Pack Release</a>.
+- Make sure that the libraries required for Zorba
+  are built with the same version of Visual Studio that you use.
+- The Windows version of some required packages
+  are distributed by other web sites
+  (all of them are pointed to from the main package web sites
+  indicated in the \ref third_party_libs section):
+  - Libxml2 and Iconv: http://www.zlatkovic.com/libxml.en.html
+  - CURL: http://curl.haxx.se/download.html
+  - Libxslt: http://www.zlatkovic.com/pub/libxml/
+
+\section windows_autodll Zorba's Automatic DLL Detection Mechanism
+
+Zorba has in place an automatic DLL detection mechanism.  This will
+try to automatically gather all the DLLs from the third party
+libraries and install them with Zorba when you do "make install" or
+you build the Visual Studio INSTALL project, to ensure that your
+installation will function regardless of the system or user's PATH.
+
+Zorba will search for the third party libraries in order in:
+-# all the directories pointed by the \c ZORBA_THIRD_PARTY_REQUIREMENTS
+   CMake configuration parameter
+    - e.g. if you have Xerces in "C:\tools" and IConv in "D:\tools",
+      you must configure your build as follows:
+      \code
+      cmake -D ZORBA_THIRD_PARTY_REQUIREMENTS=C:\tools;D:\tool {ZORBASRC}
+      \endcode
+      and Zorba will find all it needs from Xerces and Iconv.
+      (The directory names must contain "xerces" and "iconv" respectively, case insensitive)
+-# the <tt>Program Files</tt> directory on your system
+    - e.g. if you have cURL installed in "C:\Program Files\*cURL*",
+      Zorba will find all it needs from cURL.
+      (The directory must contain "curl", case insensitive.)
+-# all the paths in the \c PATH variable
+    - e.g. if you have "C:\tools\*ICU*\bin" in your path,
+      Zorba will find all it needs from ICU.
+      (The directory must only contain "icu".)
+
+The important thing to note here is that if you have any third-party
+requirements installed in unusual locations, you should use the CMake
+configuration parameter \c ZORBA_THIRD_PARTY_REQUIREMENTS instead of
+\c CMAKE_PREFIX_PATH to specify those locations when configuring
+Zorba.
+
+\section windows_nmake Building Zorba using a NMake Project
+-# Start a Visual Studio Command Line.
+-# Change the current working directory to the \c {ZORBABUILD} directory (as described in \ref create_build_dir).
+-# Execute CMake as follows:
+\code
+cmake -G "NMake Makefiles" {ZORBASRC}
+\endcode
+-# Now you are ready to call \"\c nmake\" from the \c {ZORBABUILD} directory.
+
+\section windows_visualstudio Building Zorba using a Visual Studio Project
+-# Start Visual Studio Command Line
+-# Change the current working directory into the \c {ZORBABUILD} directory (as described in \ref create_build_dir).
+-# Execute CMake with the appropriate CMake Visual Studio generator for your installation (see <tt>cmake --help</tt> for a list of generators). For instance,
+\code
+cmake -G "Visual Studio 10" {ZORBASRC}
+\endcode
+-# Start Visual Studio,
+   open the generated \c zorba.sln project file in \c {ZORBABUILD},
+   and build the \c ALL project.
+
+\section windows_https_support HTTPS support
+- In order to have SSL support in Zorba,
+  you have to use the CURL library that has SSL support. 
+- There is one more thing:
+  in order to validate the server's certificate,
+  CURL+SSL needs to know about the root Certificates of Authenticity (CA):
+  a set of public keys freely available on the internet. 
+- On Windows,
+  Zorba expects this file to be called \c cacert.pem
+  and searches for it in the current directory and system paths. 
+- This \c cacert.pem file can be found on the curl page:
+  http://curl.haxx.se/docs/caextract.html .
+- In order to disable the validation of the server certificate,
+  the \c ZORBA_VERIFY_PEER_SSL_CERTIFICATE can be set to \c OFF
+  in cmake 
+  (and actually this is the default value).
+  Set it to \c ON to validate server certificate chain
+  on every access to \c https:// .
+- To read more about CURL+SSL: http://curl.haxx.se/docs/sslcerts.html .
+- As an \c https test page,
+  we used for example the rss feed
+  fn:doc('https://www.npr.org/rss/rss.php?id=1001') .
+
+\section windows_noncore_modules Downloads for Non-Core Modules
+
+\subsection windows_imagemagick ImageMagick (image-processing modules)
+
+Just download the ImageMagick Windows binary from http://www.imagemagick.org/script/binary-releases.php and install it. We recommend the latest "Q8-windows-dll" version.
+
+\subsection windows_tidy HTML (data-converters modules)
+
+A binary installer for Tidy used to be available at:
+http://dev.int64.org/tidy.html, but as of this time of writing that
+site is down.
+
+
+
+*/

=== modified file 'doc/zorba/indexpage.dox.in'
--- doc/zorba/indexpage.dox.in	2012-04-24 18:22:23 +0000
+++ doc/zorba/indexpage.dox.in	2012-05-02 10:43:20 +0000
@@ -1,9 +1,7 @@
 /*! \mainpage Zorba ${ZORBA_MAJOR_NUMBER}.${ZORBA_MINOR_NUMBER}.${ZORBA_PATCH_NUMBER} Documentation
 
-\section installbuild Installation and Build
-  - \ref installation
+\section installbuild Building Zorba
   - \ref build
-  - \ref build_ubuntu
   - \ref php_ubuntu_tutorial
   - \ref php_windows_tutorial
   - \ref python_windows_tutorial

=== removed file 'doc/zorba/installation.dox'
--- doc/zorba/installation.dox	2012-04-24 12:39:38 +0000
+++ doc/zorba/installation.dox	1970-01-01 00:00:00 +0000
@@ -1,96 +0,0 @@
-/** \page installation Installation
-
-\section SourceInstallation Installing the Source Distribution
-
-The Zorba source is available as tar.gz and zip files.
-The Zorba sources can be installed by extracting the compressed files 
-(e.g., <tt>tar xvfz zorba-</tt><em>version</em><tt>.tar.gz</tt>).
-This creates a <tt>zorba-</tt><em>version</em> directory
-in your current working directory.
-
-To build Zorba,
-please follow the build instructions (see \ref buildingzorba). 
-
-\section Installing Installing
-
-Once you have successfully built Zorba using the "Unix Makefile" generator
-(see \ref SourceInstallation),
-you can execute <tt>make install</tt>
-from within the build directory
-to install Zorba.
-This will install Zorba
-into the path specified by the \c CMAKE_INSTALL_PREFIX variable. 
-
-Note that for setting the install prefix,
-you can use the \c CMAKE_INSTALL_PREFIX variable.
-For example,
-in order to install Zorba in <tt>/opt</tt>
-use <tt>cmake -D CMAKE_INSTALL_PREFIX=/opt </tt><em>zorba source directory</em>.
-(Note that while CMake-generated Makefiles support the \c DESTDIR variable,
-this will NOT work with Zorba as certain installation paths are hard-coded
-in the binary files.)
-
-There is also a <tt>make uninstall</tt> command available
-(also to be called from the build directory).
-
-Alternatively,
-you can use one of Zorba's binary distributions
-if it is available for your platform.
-For example,
-download and decompress the tar-ball
-for Mac OS X (e.g., <tt>zorba-</tt><em>version</em><tt>-Darwin-i386.tar.gz</tt>).
-
-For both installations,
-you will need to add Zorba's bin directory
-(e.g., \c CMAKE_INSTALL_PREFIX/bin or 
-<tt>zorba-0.9.2541-Darwin-i386/bin</tt>)
-to your \c PATH environment variable. 
-
-Additionally,
-you will need to add the corresponding library search path
-(e.g., \c LD_LIBRARY_PATH on Linux,
-\c DYLD_LIBRARY_PATH on Mac,
-and \c PATH on Windows)
-to point to the lib directory
-(e.g., \c CMAKE_INSTALL_PREFIX/lib or
-<tt>zorba-</tt><em>version</em><tt>-Darwin-i386/lib</tt>).
-Also,
-please make sure that the directories of the required libraries
-(see \ref build)
-are present in your library search path.
-  
-After that,
-try typing
-<tt>%zorba -q "1+1"</tt>
-and you should see 
-\code
-<?xml version="1.0" encoding="UTF-8"?>
-2
-\endcode
-
-as a result.
-Congratulations -- you're done and ready to use Zorba.
-Otherwise, please consult the zorba-users mailing list for help.
-
-For programming against the Zorba library,
-we refer to the API examples
-provided with the source and binary distribution
-(see \link simple.cpp \endlink for an example).
-
-In order to make the installation process easier,
-we also provide graphical installers
-for Windows and Mac OS X.
-  
-\section UbuntuInstallation Additional notes for Ubuntu systems installations
-  
-The recommended way of installing the Zorba library on an Ubuntu system
-is to add the lib directory as a \c .conf file in \c /etc/ld.so.conf
-and then run <tt>sudo ldconfig</tt>.
-For a personal (non-root non-system wide) installation,
-employing \c LD_LIBRARY_PATH is the only valid approach,
-but it needs to be done in the shell's \c .rc file
-not in the \c .profile file.
-Additional information can be found here: 
-<a href="https://edge.launchpad.net/ubuntu/+bug/366728";>LD_LIBRARY_PATH not loading from .profile nor /etc/environment</a>.  
-
-*/