Zend Framework Translator - Manual Compilation Instructions

Introduction

The manual is written in Docbook XML and requires a Unix-like operating system with the standard GNU toolchain and xsltproc or a similar XSLT processor to build the source XML into the HTML that is shipped with the Zend Framework distributions.

On Windows, you can compile the docbook using Cygwin. See: http://www.cygwin.com

Linting the Manual / Checking for Errors

If you have an existing checkout of the ZF SVN, then update your Makefile:

For all of the methods below, any errors reported are relative to a temporary file (not the original source file you edit). The temporary file name begins with "_temp".

Checking a single file you just edited

Checking the entire manual

Also, you can now manually xmllint the entire manual via:

.. or simply use:

Installation for Windows users

Installation steps for Cygwin:

1. Choose "Install from Internet", click [Next]
2. Choose the directory where you want to install Cygwin. Leave the other options on their "RECOMMENDED" selection. Click [Next]
3. Select a directory where you want downloaded files to be stored. Click [Next]
4. Select your way of connecting to the Internet. Click [Next]
5. Choose the most suitable mirror in the mirrorlist. Click [Next]
6. Select the following packages to install:

• Devel > automake1.9
• Devel > make
• Libs > libxslt
  All dependent packages will automatically be selected for you. Click [Next]

1. Sit back and relax while Cygwin and the selected packages are being downloaded and installed. This may take a while.
2. Check the option "Create icon on Desktop" and "Add icon to Start Menu" to your liking. Click [Finish].

Building the manual (*nix AND Cygwin)

Below are instructions for building the documentation into HTML.

NOTE: You don't necessarily need the whole distribution of source files for Zend Framework. All you need is the language directory you want to build, for example <ZF_HOME>/documentation/manual/ru/ and you also need one sister directory <ZF_HOME>/documentation/manual/.build/. The latter directory contains a shell script that is needed during the manual build process. Note that you will have to create the .build directory yourself and also the mkentities.sh file.

1. Go to a shell prompt, or Windows users will run Cygwin (you can double-click the icon on the Desktop or in the Start menu if you've chosen any of these options at install-time)
2. Navigate to the directory where the documentation files are stored using the traditional Unix commands. For Cygwin users, drives are stored under "/cygdrive". So if your documentation files are stored under "c:\ZF\documentation", you'll need to run the command "cd /cygdrive/c/ZF/documentation/".
   You're under a Unix environment, so don't forget all paths are case sensitive!
3. To compile the doc, go to the directory in which manual.xml is located (e.g. documentation/manual/en), and run:
   $ autoconf
   $ ./configure
   $ mkdir ../.build
   $ touch ../.build/mkentities.sh
   $ chmod +x ../.build/mkentities.sh
   $ make
4. Now run the command below to see a list of errors (if any) in the XML:
   xmllint --valid --noout manual.xml

Rebuilding the manual

If you have made changes to the documentation and need to rebuild the HTML pages, navigate a shell to the documentation tree that you wish to rebuild, and type the following commands:

$ make clean
$ make

Troubleshooting

If you're encountering errors while trying the build instructions above...

1. Remove all files from the html/ subdir except dbstyle.css

1. Remove all files from the root dir except manual.xml, configure.in, Makefile.in and README. The important one here is entities.ent.

1. You can optionally remove the "/autom4te.cache" and the "/build/docbook-xsl" directory

1. Try to build again following the instructions given above. If it still throws errors, post a message to the fw-docs@lists.zend.com list.

References

http://www.sagehill.net/docbookxsl/ToolsSetup.html