Docbook and Website installation is not an easy topic to cover since I must address multiple operating systems, pre-installed Docbook software etc. However, given that the reader audience is not expected to be a Linux geek, what I present here is a very simple, straightforward way of obtaining and installing the software which works and is repeatable. If you wish to use your own setup, then the modifications will need to reflect the differences.

The list of software needed is as follows. Appendix A lists the Websites from which you may obtain the software. It is all available as open source software. The appendix also lists some documentation you may find useful. The list of software needed and its purpose is shown below.

Installation location.

For no other reason than to suggest a location, Figure 1 shows a list of directories to be used for installation. If the directories don't exist, create them. If you don't have administrative rights (I.e. can't create the directories), then choose an alternative and make a note of what changes you are making!

This requires a copy of the java runtime system. I haven't shown it since a fully automatic install will put it in different places depending on your Operating System.

Installation is simply a matter of unzipping the distributions into a known location

Firstly install the main Docbook files (schemas and stylesheets) into /sgml/docbook.

Then install the Website files (schemas and stylesheets) into /sgml/docbook/website-2.6.0

It makes sense to me to keep all the Docbook files together, giving a layout as shown below.

This keeps them all together so you know at least where the start of the Docbook files are. Once you're used to it, it won't take long to find (or even refer to) a file you want.

Whilst this is straightforward, there is one twist. The Website stylesheets make reference to the current Docbook stylesheets, which are on the internet. This may cause you problems if you are not connected to the internet at the time you use the stylesheets. Since Docbook and Website are two separate installations, there can be no link between them on your disk. The current solution is to link to the copy on the internet. Hence a number of files make reference to the main Docbook stylesheets, using the XSLT import directive. As installed, the Website stylesheets import the files directly from the http://docbook.sourceforge.net/release/xsl/current/html/ Website from which they are distributed. This makes it easy to use, but may cause problems if you lose your internet connection or wish to speed up access (generally internet access is slower than file access from your own hard disk). It is your choice if you wish to address this issue. To resolve it you can do one of two things. Use Oasis catalog support (which is a method of redirecting internet access to certain sites to the same files on disk), outlined in Section 8 or simply change the stylesheet files to make them point to the appropriate files on your disk. If you want to use local files, the files to change are:

This is why you need to take note of where you have installed the main Docbook stylesheets. Within that distribution you will find a file hierarchy as shown below. As I said above, I'm assuming you have installed the main Docbook files in the directory /sgml/docbook. It would make sense to install the /docbook-xsl-1.73.x files (the main Docbook stylesheets) in the same directory simply to keep them together. Again, for simplicity, this is my assumption. Then the layout will include:

By the way, the 1.73.x refers to release 2 of revision 1.73. This may change but will only be a minor update (usually bug-fixes) to the base 1.73 release.

Yes, there are many more files, but those are the files and directories of interest at the moment. In particular look in the /docbook-xsl-1.73.x/html directory for docbook.xsland chunker.xsl files mentioned above. If you then wish to edit the import statements, you could open file website-common.xsl in your installed Website stylesheets, for example, and change the line

<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl"/>  

to

  <xsl:import href="/sgml/docbook/docbook-xsl-1.73.3/html/docbook.xsl"/>

This swaps out the use of the internet file and replaces it with a call to the main Docbook stylesheets that you installed in /sgml/docbook/. In a similar way the other two files may be amended to call up the installed files as apposed to the internet ones (from Sourceforge).

Warning

If you change these files, it could be a mistake to use the Oasis catalog solution discussed in Section 8, simply because the catalog file resolution sidesteps this issue using a different method Also, having once changed them, if you update the Website xsl files, then they will need changing again! If you update the main docbook-xsl files, their location will change, and the Website files will need to be updated! The note below does address this last issue

Version updates

This does leave one minor detail. Versions. From the above you can see that each directory (hence distribution) is named by it's version. This will help you realise what version you are working with. What it will also do is make it a little harder each time you update from one minor version to another. E.g. a reference to the path /sgml/docbook/docbook-xsl-1.73.3/html/docbook.xsl will become out of date once you've installed 1.73.4! This problem can be resolved without fuss by removing the version information. No, you won't lose the version information. The developers are ahead of you. Take a peak inside any one of the distributions. You'll find a file called VERSION. Inside the said file, you can find, marked up in XML, the version number. For instance, the Website file contains

  <fm:project>
  <fm:Project>DocBook</fm:Project>
  <fm:Branch>Website</fm:Branch>
  <fm:Version>2.6.0</fm:Version>

So, if you want to be version-lazy, try the following (replace whatever versions you have as appropriate

All I've done is truncate the directory names to make them version independent. E.g. docbook-xsl-1.73.2 is changed to docbook-xsl and the Website directory is similarly changed. This step is optional, it lets you keep up to date with fewer changes.

The changes marked above will need the locations modifying to match them.

Note what goes where, since you'll need to know what to change if your installation is any different to this.

The next install is the ant application. Download the binary distribution from the site linked from Appendix A, e.g. apache-ant-1.7.0-bin.zip and save it onto a temporary location on disk. unzip zip it using either a command line program or something like the Winzip program, into the directory /apps/ant. It may create a directory called apache-ant-1.7.0/l (or another such version). If so, rename it to ant, then add the path /apps/ant/bin to the PATH environmental variable. Ask around if you don't know how. You can test out if it has worked by simply typing

  $ant -version
$ ant -version
Apache Ant version 1.7.0 compiled on December 13 2006

The response should be similar to the one above

The next addition is the ant extension task for the file transfers (ftp). This is from apache.org. Select the binary zip file and save it to disk. Again unzip it, but this time you only need one file from the zip file, commons-net-1.4.1/commons-net-1.4.1.jar (or whichever is the appropriate version). Extract this one file save it directly to /apps/ant/lib, ready for ant to use it.

The next item is the resolver.jar jar file. This is not a part of ant, so I'm suggesting you put it in a different place. I use /myjava, so that's where it goes for this setup. Download the zip file xml-commons-resolver-1.2.zip and unzip the one file from xml-commons-resolver-1.2/resolver.jar into the /myjava directory

Finally, the xslt engine, saxon. Find the download from Appendix A, download the zip file and unzip it. Again you only need the one file. Extract the file saxon.jar and move it to /myjava

I find it convenient to remember which file it is by renaming it with the version, so saxon.jar is changed to saxon655.jar.

That's it for installation. You should now have all the files needed to transform and upload a Website..... unless you don't have Sun java installed?

If not, see the download site in Appendix A and select your platform (Windows, Solaris or Linux). For Linux this provides a self extracting binary file. For windows it is similarly an executable. Download it and install the file. If you accept the default installation, you can check if it has worked by opening a command line window and typing

$ java -version
java version "1.6.0_04"
Java(TM) SE Runtime Environment (build 1.6.0_04-b12)
Java HotSpot(TM) Client VM (build 10.0-b19, mixed mode, sharing)

	Which Java version
	If you install Java version 5 (otherwise known as 1.6), you may be missing the file tools.jar. Make sure if you use 1.6, you install the JDK!

Amonst all your other files, you should be able to see

/
-/apps
 -/ant  
  -/lib
   - commons-net-1.4.1.jar
-/myjava  
 -saxon655.jar 
 -resolver.jar 
-/sgml   
 -/docbook  
  -/docbook-xsl
  -/website 
-catalogManager.properties  []
-catalog.xml  

You may wish to check your installation before moving on.

If you need a catalogManager.properties file, and an initial catalog.xml file, see Section 8