<h1>Zend Framework Translator - Manual Compilation Instructions</h1>
<h2>Introduction</h2>
<p>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.</p>
<p>On Windows, you can compile the docbook using Cygwin. See: <a href="http://www.cygwin.com">http://www.cygwin.com</a></p>
<h2>Linting the Manual / Checking for Errors</h2>
<p>If you have an existing checkout of the ZF SVN, then update your Makefile:</p>
<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
$ svn update
$ autoconf
$ ./configure
]]></ac:plain-text-body></ac:macro>
<p>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 "<code>_temp</code>".</p>
<h3>Checking a single file you just edited</h3>
<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[make XMLFILE=Zend_Acl.xml check1]]></ac:plain-text-body></ac:macro>
<h3>Checking the entire manual</h3>
<p>Also, you can now manually xmllint the entire manual via:</p>
<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
xmllint --xinclude --output _temp_manual.xml manual.xml
xmllint --valid --noout --postvalid _temp_manual.xml
]]></ac:plain-text-body></ac:macro>
<p>.. or simply use:</p>
<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[make check]]></ac:plain-text-body></ac:macro>
<h2>Installation for Windows users</h2>
<p>Installation steps for Cygwin:</p>
<ol>
<li>Choose "Install from Internet", click [Next]</li>
<li>Choose the directory where you want to install Cygwin. Leave the other options on their "RECOMMENDED" selection. Click [Next]</li>
<li>Select a directory where you want downloaded files to be stored. Click [Next]</li>
<li>Select your way of connecting to the Internet. Click [Next]</li>
<li>Choose the most suitable mirror in the mirrorlist. Click [Next]</li>
<li>Select the following packages to install:</li>
</ol>
<ul>
<li>Devel > automake1.9</li>
<li>Devel > make</li>
<li>Libs > libxslt<br />
All dependent packages will automatically be selected for you. Click [Next]</li>
</ul>
<ol>
<li>Sit back and relax while Cygwin and the selected packages are being downloaded and installed. This may take a while.</li>
<li>Check the option "Create icon on Desktop" and "Add icon to Start Menu" to your liking. Click [Finish].</li>
</ol>
<h2>Building the manual (*nix AND Cygwin) </h2>
<p>Below are instructions for building the documentation into HTML.</p>
<p>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 <code><ZF_HOME>/documentation/manual/ru/</code> and you also need one sister directory <code><ZF_HOME>/documentation/manual/.build/</code>. 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.</p>
<ol>
<li>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)</li>
<li>Navigate to the directory where the documentation files are stored using the traditional Unix commands. For Cygwin users, drives are stored under "<code>/cygdrive</code>". So if your documentation files are stored under "<code>c:\ZF\documentation</code>", you'll need to run the command "<code>cd /cygdrive/c/ZF/documentation/</code>".<br />
You're under a Unix environment, so don't forget all paths are case sensitive!</li>
<li>To compile the doc, go to the directory in which manual.xml is located (e.g. documentation/manual/en), and run:<br />
<code>$ autoconf</code><br />
<code>$ ./configure</code><br />
<code>$ mkdir ../.build</code><br />
<code>$ touch ../.build/mkentities.sh</code><br />
<code>$ chmod +x ../.build/mkentities.sh</code><br />
<code>$ make</code></li>
<li>Now run the command below to see a list of errors (if any) in the XML:<br />
<code>xmllint --valid --noout manual.xml</code></li>
</ol>
<h2>Rebuilding the manual</h2>
<p>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:</p>
<p> <code>$ make clean</code><br />
<code>$ make</code></p>
<h2>Troubleshooting </h2>
<p>If you're encountering errors while trying the build instructions above...</p>
<ol>
<li>Remove all files from the html/ subdir except dbstyle.css</li>
</ol>
<ol>
<li>Remove all files from the root dir except <code>manual.xml</code>, <code>configure.in</code>, <code>Makefile.in</code> and <code>README</code>. The important one here is <code>entities.ent</code>.</li>
</ol>
<ol>
<li>You can optionally remove the "<code>/autom4te.cache</code>" and the "<code>/build/docbook-xsl</code>" directory</li>
</ol>
<ol>
<li>Try to build again following the instructions given above. If it still throws errors, post a message to the <a href="mailto:fw-docs@lists.zend.com">fw-docs@lists.zend.com</a> list.</li>
</ol>
<h2>References</h2>
<p><a class="external-link" href="http://www.sagehill.net/docbookxsl/ToolsSetup.html">http://www.sagehill.net/docbookxsl/ToolsSetup.html</a></p>
<h2>Introduction</h2>
<p>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.</p>
<p>On Windows, you can compile the docbook using Cygwin. See: <a href="http://www.cygwin.com">http://www.cygwin.com</a></p>
<h2>Linting the Manual / Checking for Errors</h2>
<p>If you have an existing checkout of the ZF SVN, then update your Makefile:</p>
<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
$ svn update
$ autoconf
$ ./configure
]]></ac:plain-text-body></ac:macro>
<p>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 "<code>_temp</code>".</p>
<h3>Checking a single file you just edited</h3>
<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[make XMLFILE=Zend_Acl.xml check1]]></ac:plain-text-body></ac:macro>
<h3>Checking the entire manual</h3>
<p>Also, you can now manually xmllint the entire manual via:</p>
<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
xmllint --xinclude --output _temp_manual.xml manual.xml
xmllint --valid --noout --postvalid _temp_manual.xml
]]></ac:plain-text-body></ac:macro>
<p>.. or simply use:</p>
<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[make check]]></ac:plain-text-body></ac:macro>
<h2>Installation for Windows users</h2>
<p>Installation steps for Cygwin:</p>
<ol>
<li>Choose "Install from Internet", click [Next]</li>
<li>Choose the directory where you want to install Cygwin. Leave the other options on their "RECOMMENDED" selection. Click [Next]</li>
<li>Select a directory where you want downloaded files to be stored. Click [Next]</li>
<li>Select your way of connecting to the Internet. Click [Next]</li>
<li>Choose the most suitable mirror in the mirrorlist. Click [Next]</li>
<li>Select the following packages to install:</li>
</ol>
<ul>
<li>Devel > automake1.9</li>
<li>Devel > make</li>
<li>Libs > libxslt<br />
All dependent packages will automatically be selected for you. Click [Next]</li>
</ul>
<ol>
<li>Sit back and relax while Cygwin and the selected packages are being downloaded and installed. This may take a while.</li>
<li>Check the option "Create icon on Desktop" and "Add icon to Start Menu" to your liking. Click [Finish].</li>
</ol>
<h2>Building the manual (*nix AND Cygwin) </h2>
<p>Below are instructions for building the documentation into HTML.</p>
<p>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 <code><ZF_HOME>/documentation/manual/ru/</code> and you also need one sister directory <code><ZF_HOME>/documentation/manual/.build/</code>. 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.</p>
<ol>
<li>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)</li>
<li>Navigate to the directory where the documentation files are stored using the traditional Unix commands. For Cygwin users, drives are stored under "<code>/cygdrive</code>". So if your documentation files are stored under "<code>c:\ZF\documentation</code>", you'll need to run the command "<code>cd /cygdrive/c/ZF/documentation/</code>".<br />
You're under a Unix environment, so don't forget all paths are case sensitive!</li>
<li>To compile the doc, go to the directory in which manual.xml is located (e.g. documentation/manual/en), and run:<br />
<code>$ autoconf</code><br />
<code>$ ./configure</code><br />
<code>$ mkdir ../.build</code><br />
<code>$ touch ../.build/mkentities.sh</code><br />
<code>$ chmod +x ../.build/mkentities.sh</code><br />
<code>$ make</code></li>
<li>Now run the command below to see a list of errors (if any) in the XML:<br />
<code>xmllint --valid --noout manual.xml</code></li>
</ol>
<h2>Rebuilding the manual</h2>
<p>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:</p>
<p> <code>$ make clean</code><br />
<code>$ make</code></p>
<h2>Troubleshooting </h2>
<p>If you're encountering errors while trying the build instructions above...</p>
<ol>
<li>Remove all files from the html/ subdir except dbstyle.css</li>
</ol>
<ol>
<li>Remove all files from the root dir except <code>manual.xml</code>, <code>configure.in</code>, <code>Makefile.in</code> and <code>README</code>. The important one here is <code>entities.ent</code>.</li>
</ol>
<ol>
<li>You can optionally remove the "<code>/autom4te.cache</code>" and the "<code>/build/docbook-xsl</code>" directory</li>
</ol>
<ol>
<li>Try to build again following the instructions given above. If it still throws errors, post a message to the <a href="mailto:fw-docs@lists.zend.com">fw-docs@lists.zend.com</a> list.</li>
</ol>
<h2>References</h2>
<p><a class="external-link" href="http://www.sagehill.net/docbookxsl/ToolsSetup.html">http://www.sagehill.net/docbookxsl/ToolsSetup.html</a></p>