This document describes the format of the Apache HTTP Server documentation xml source files and the technique used to transform them to html.

A DTD is located in the style directory of the manual. An example of the format with extensive comments is also available in mod_template.txt. Obviously, the file extension should be xml. It was changed to make online viewing simpler.

To ensure that your documentation follows the defined format, you should parse it using the DTD. Some help using Emacs with XML files is available from IBM developerWorks.

The easiest way to view the tranformed docs is to simply open the xml file directly in a recent verions of MSIE, Netscape, or Mozilla. (MSIE 6 seems to work consistently. The Gecko/Mozilla based browsers, however, do not incorporate the referenced DTDs, so they have problems with documents containing character entities). These browsers will read the xsl file and perform the transformation for you automatically, so that you can see what the final output will look like. This means that you can work on the docs and check your work without any special transformation setup.

For the final presentation, it is still necessary to transform to html to accomodate older browsers. Although any standards-compliant xslt engine should do, changing engines can lead to massive diffs on the transformed files. Therefore, we have chosen a single recommended transformation system based on Xalan+Xerces Java and Ant. These are all Apache projects distributed under the Apache license.

The only prerequisite for the transformation is a Java 1.2 or greater JVM (which can be obtained free from Sun). Assuming you already have httpd/httpd/branches/2.0.x/docs/ (or the equivalent from another branch) checked out from SVN, here is what you need to do to build: (If you need instructions on setting up SVN, see this page.)

$ cd docs/manual
$ svn co http://svn.apache.org/repos/asf/httpd/docs-build/trunk build
$ cd build
$ ./build.sh

If you are running under win32, the build.sh script will work if cygwin is installed. Alternatively, on Win32, you should be able to run the build.bat script.

If you don't want to get the build files from SVN, you can download a pkzipped version of the current build tools from our distribution directory.

The default target builds only the english-language docs. To build other docs, you should specify the language-code (ja, de, etc) as an argument. To find the available languages, please see our translations page.

You can get an overview of all possible build targets by typing:

./build.sh -projecthelp

When adding a new module, the transformation process tries to generate an appropriate entry within mod/allmodules.xml and to create an accompanying metafile (newfilename.xml.meta). Since these tasks are written in perl, you'll need a working perl installation for this. If not, you should take these steps manually, or just leave a note on the project mailing list so that someone else can do it.

The PDF version of the docs is generated by transforming the xml files to LaTeX using the "latex-en" Ant target. The XSLT style files for the transformation are under style/latex/. Once you have the .tex equivalent of each .xml file, you can use pdflatex to convert this into a pdf file. Recommended versions of pdflatex can be obtained as part of TeTeX (unix) or MikTeX (win32), but any version of TeX should be fine, as long as it is sufficiently complete and modern. To generate the PDF, you should process the sitemap.tex file, which contains the main LaTeX document code and will include all the other files. The outputed PDF will then be called sitemap.pdf, which you can rename how you choose.

Some notes about the XML to LaTeX conversion are necessary. Although HTML and LaTeX have many similarities, there are enough differences between the two to make targetting both outputs a difficult task. In particular, the methods for handling tables are very different. To aid in the conversion to LaTeX of tables designed for HTML, a <columnspec> section should be added to each table. Inside the <columnspec>, place a <column width=".xx"/> for each column in the table, where xx is the percentage of the line-width devoted to that column. This will assist in the conversion of basic tables. More complex stuff (like spanning rows or columns) is not currently convertible.

Further, pdflatex cannot incorporate GIF files in a generated PDF, so any graphics must be available in PNG format.

There are various other restrictive assumptions embedded in the XSLT that work for the current docs, but may need to be modified in the future. For example, the code that transforms HTML-style links to LaTeX cross-references will only work within the main directory and one level of subdirectory. Also, <pre> sections rarely work well in LaTeX because of differences in escaping and formatting rules in verbatim sections.

Finally, there are various differences in escaping rules between XML/HTML and LaTeX. Some characters need to be backslash-escaped in LaTeX, and all XML entitites (&whatever;) must be converted to LaTeX equivalents. This is currently handled for a limited set of characters using a big, ugly search-replace in the XSLT. This may need to be modified in the future, especially to handle translations. Pre-processing with a perl script and a substitution table may be a better solution.