Introduction
There are 2 possibilities to compile Zend Framework documentation (for 1.x or 2.x series):
- xsltproc : XSLT processor
- PhD: PHP tool used by http://php.net
I will show the 2 methods based on Ubuntu 11.10.
Get Zend Framework sources
For 1.x serie, you must use Subversion:
$ cd /path/you/want $ svn co http://framework.zend.com/svn/framework/standard/trunk/documentation/manual/ .
To update your sources:
$ svn up
For 2.x serie, you must use Git: read http://framework.zend.com/wiki/display/ZFDEV2/Zend+Framework+Git+Guide
XSLT Processor
You need to install some tools:
# apt-get install autoconf make xsltproc libxml2-util docbook-utils docbook-xsl
At this stade, you can simply go in your favorite language directory to check the manual:
$ autoconf $ ./configure $ make check
You should obtain something like:
sed -e 's!@DOCBOOK_DTD@!http://framework.zend.com/docbook/xml/4.5/docbookx.dtd!' ../en/manual.xml.in > manual.xml Checking the whole manual with /usr/bin/xmllint... OK
In this result, you can see that you use ‘docbook.dtd’ located on Zend server. You can use the file located on your computer (downloaded with apt-get above) by adding:
$ export DOCBOOK_DTD=/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd $ # then $ make cleanall $ autoconf $ ./configure $ make check
Now, you have:
sed -e 's!@DOCBOOK_DTD@!/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd!' ../en/manual.xml.in > manual.xml Checking the whole manual with /usr/bin/xmllint... OK
If the final result is ‘OK’, yon can compile the documentation in HTML with:
$ make
But this will use XSL stylesheets located on Zend server. In the initial ‘apt-get’ you downloaded these stylesheets. To automagically use them you should add:
$ export DOCBOOK_XSL=/usr/share/xml/docbook/stylesheet/docbook-xsl/html/chunk.xsl $ # then $ make cleanall $ autoconf $ ./configure $ make
It took me 19 minutes to compile English HTML documentation for trunk r24580. This is a rough version (no images for design, no color).
If you like PDF version of the documentation (around 1860 pages), you can also compile it with FOP, you need:
# apt-get install fop $ # then $ make cleanall $ autoconf $ ./configure $ make pdf
It took me 6 minutes to compile English PDF documentation for trunk r24580. This is a rough version (no images for design, no color).
If you prefer the CHM version, it’s a little more complicated on Ubuntu but it’s possible! First step you need:
# apt-get install wine
Then start at least one time Wine (Notepad for example) to generate default configuration. After that you can use the following script (provided in http://appdb.winehq.org/objectManager.php?sClass=version&iId=2978&iTestingId=15284):
#!/bin/bash -e
# -e Exit immediately if a command exits with a non-zero status.
# This installs Microsofts HHC (HTML Help Compiler)
# Copyright 2011 Timo Richter and others.
# Licensed under GNU GPLv3
# Depends on: wine, wget, cabextract
#
# Usage of HHC: wine c:\\htmlhelp\\hhc.exe c:\\test\\htmlhelp.hhp
#
# Changes: Set installation directory to c:\htmlhelp
# Copy also itcc.dll, this is neccessary
# No execution of htmlhelp.exe installer needed
# Abortion of install if anything fails, e.g. the download of HHC.
#
echo "Please wait"
cd "$(dirname "$0")" # cd to path of this script
WINEPREFIX=${WINEPREFIX:=$HOME/.wine}
test -d "$WINEPREFIX" || wineprefixcreate 2>> /dev/null
HHDIR="${WINEPREFIX}/dosdevices/c:/htmlhelp"
mkdir "$HHDIR"
# Setup the registry
# Set Wine's Windows version to Windows 2000 (or above), and add an override to use the native itss.dll, both via winecfg.
# wine regedit htmlhelp.reg
After chmod+x the script then launch it.
Now you have HTML Help Workshop on your machine, you need to create files to generate the CHM. The first DOCBOOK_XSL (chunk.xsl) doesn’t allow to create CHM, you need to change it to htmlhelp.xsl:
$ export DOCBOOK_XSL=/usr/share/xml/docbook/stylesheet/docbook-xsl/htmlhelp/htmlhelp.xsl $ # then $ make cleanall $ autoconf $ ./configure $ make
After some minutes (always 19 minutes in my case), you obtain all the files and especially a new one in ‘html’ subdirectory ‘htmlhelp.hhp’. You have to provide this file to HTML Help Workshop:
$ wine /home/mikaelkael/.wine/drive_c/htmlhelp/hhc.exe html/htmlhelp.hhp
You obtain the CHM in ‘html’ subdirectory, something like: ‘Zend_Framework_[LANG].chm’. It’s always without any colors or images.
PhD
First step, you need to retrieve PhD and dependencies from Zend sources:
$ cd /path/you/want $ svn co http://framework.zend.com/svn/framework/build-tools/trunk/build-tools/docs/ build-tools
To update your sources:
$ svn up
Then you have to convert documentation files in Docbook4 to Docbook5:
$ autoconf $ ./configure $ make manual.xml $ xsltproc --xinclude /path/to/build-tools/db4-upgrade.xsl manual.xml > manual-db5.xml
Now you can build the documentation:
/path/to/build-tools/pear/phd -g 'phpdotnet\phd\Highlighter_GeSHi' --xinclude -f zfpackage -d manual-db5.xml
You obtain in less than 1 minute:
[15:20:56 - Indexing] Indexing... [15:21:00 - Indexing] Indexing done [15:21:00 - Rendering Style] Running full build [15:21:00 - Rendering Format] Starting ZF-Package-Chunked-XHTML rendering [15:21:39 - Rendering Format] Finished rendering
You will find the documentation in ‘output’ subdirectory. With this version, all programlisting are syntax highlighted.
Enhancements
To go further, you can find the scripts I use to generate http://doczf.mikaelkael.fr in GitHub: https://github.com/mikaelkael/zfdocumentor. The are based on xsltproc. I am planning to migrate to PhD because of the time to render a documentation.
