compared with
Current by Martin de Keijzer
on Feb 14, 2011 13:33.

Key
This line was removed.
This word was removed. This word was added.
This line was added.

Changes (345)

View Page History
h1. Zend Framework Guide to DocBook
<h1>Zend Framework Guide to DocBook</h1>

h2. Introduction
<h2>Introduction</h2>

<p>This document describes the technology and process of working on the documentation for Zend Framework.</p>

h2. Getting Documentation Sources
<h2>Getting Documentation Sources</h2>

<p>This section details how to gain access to the sources so you can author or build the documentation.</p>

h3. Using Subversion
<h3>Using Subversion</h3>

<p>The documentation is available in DocBook XML source format in the Zend Framework subversion project. Point your subversion client to this location to download the files for all languages:</p>
* http://framework.zend.com/svn/framework/standard/trunk/documentation/manual/
<ul>
<li><a class="external-link" href="http://framework.zend.com/svn/framework/standard/trunk/documentation/manual/">http://framework.zend.com/svn/framework/standard/trunk/documentation/manual/</a></li>
</ul>

Each translation is stored in a separate subdirectory, using the locale code of the respective language. For example to access the files of the English manual, check out the *en* subdirectory:
* http://framework.zend.com/svn/framework/standard/trunk/documentation/manual/en/

To access the files for the French translation, you can check out the *fr* subdirectory:
* http://framework.zend.com/svn/framework/standard/trunk/documentation/manual/fr/
<p>Each translation is stored in a separate subdirectory, using the locale code of the respective language. For example to access the files of the English manual, check out the <strong>en</strong> subdirectory:</p>
<ul>
<li><a class="external-link" href="http://framework.zend.com/svn/framework/standard/trunk/documentation/manual/en/">http://framework.zend.com/svn/framework/standard/trunk/documentation/manual/en/</a></li>
</ul>

By default you will get files in a read-only form. To be granted permission to make edits, you must submit a Contributor License Agreement (CLA) and become part of the team of contributors.

h3. Using nightly snapshots
<p>To access the files for the French translation, you can check out the <strong>fr</strong> subdirectory:</p>
<ul>
<li><a class="external-link" href="http://framework.zend.com/svn/framework/standard/trunk/documentation/manual/fr/">http://framework.zend.com/svn/framework/standard/trunk/documentation/manual/fr/</a></li>
</ul>

The Zend Framework website offers nightly snapshots of the subversion project. This is identical to what you would get by exporting the files using a subversion client.
* http://framework.zend.com/download/snapshot/

h3. Using Fisheye
<p>By default you will get files in a read-only form. To be granted permission to make edits, you must submit a Contributor License Agreement (CLA) and become part of the team of contributors.</p>

The Zend Framework website operates a web application called Fisheye, which gives an interface to browse the ZF subversion project.
* http://framework.zend.com/fisheye/browse/Zend_Framework/trunk/documentation/manual
<h3>Using nightly snapshots</h3>

h4. Fisheye feeds
<p>The Zend Framework website offers nightly snapshots of the subversion project. This is identical to what you would get by exporting the files using a subversion client.</p>
<ul>
<li><a class="external-link" href="http://framework.zend.com/download/snapshot/">http://framework.zend.com/download/snapshot/</a></li>
</ul>

Fisheye provides RSS feeds so you can monitor changes in any file or directory. For example, translators may find it convenient to monitor changes to the English documentation with the following RSS feed:
* http://framework.zend.com/fisheye/changelog/~rss/Zend_Framework/trunk/documentation/manual/en/rss.xml

h4. Fisheye tarballs
<h3>Using WebSVN</h3>

Fisheye provides a facility to fetch zip or tar.gz archives of any directory level using the Fisheye interface. See the left side of the screen, and scroll down below the list of subdirectories. See a pane labeled, *Tarball*. Click on the *zip*, *tgz*, or *tbz2* links to download a dynamically-generated, compressed archive of the currently viewed directory in zip, tar.gz or tar.bz2 formats. Please be respectful of the bandwidth and server resources, and do not overuse this facility.
<p>The Zend Framework website operates a web application called WebSVN, which gives an interface to browse the ZF subversion project. </p>
<ul>
<li><a class="external-link" href="http://framework.zend.com/code">http://framework.zend.com/code</a></li>
</ul>

h2. Rendering DocBook

Each language directory contains scripts to configure and process the DocBook XML sources into HTML. This section detail how to use these scripts.
<h4>WebSVN feeds</h4>

h3. Tools to build DocBook
<p>WebSVN provides RSS feeds so you can monitor changes in any file or directory. For example, translators may find it convenient to monitor changes to the English documentation with the following RSS feed: </p>
<ul>
<li><a class="external-link" href="http://framework.zend.com/code/rss.php?repname=Zend+Framework&amp;path=%2Ftrunk%2Fdocumentation%2Fmanual%2Fen%2F&amp;isdir=1&amp;">http://framework.zend.com/code/rss.php?repname=Zend+Framework&amp;path=%2Ftrunk%2Fdocumentation%2Fmanual%2Fen%2F&amp;isdir=1&amp;</a></li>
</ul>

The tools you'll need to do this build are:

* make
* autoconf
* xsltproc
* xmllint
* standard UNIX/Linux shell and common tools
<h2>Rendering DocBook</h2>

If you are on Linux, these tools are usually part of the operating system distribution. If you are on Windows, you can get all of the above as parts of the Cygwin package (http://www.cygwin.com/).
<p>Each language directory contains scripts to configure and process the DocBook XML sources into HTML. This section detail how to use these scripts.</p>

h3. Rendering HTML
<h3>Tools to build DocBook</h3>

Change directory to the above-mentioned *en* directory or language directory. Configure and run the Makefile. The default target in the Makefile invokes html rendering of the manual:
<p>The tools you'll need to do this build are:</p>

{code} <ul>
<li>make</li>
<li>autoconf</li>
<li>xsltproc</li>
<li>xmllint</li>
<li>standard UNIX/Linux shell and common tools</li>
</ul>


<p>If you are on Linux, these tools are usually part of the operating system distribution. If you are on Windows, you can get all of the above as parts of the Cygwin package (<a class="external-link" href="http://www.cygwin.com/">http://www.cygwin.com/</a>).</p>

<h3>Rendering HTML</h3>

<p>Change directory to the above-mentioned <strong>en</strong> directory or language directory. Configure and run the Makefile. The default target in the Makefile invokes html rendering of the manual:</p>

<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
$ autoconf
$ ./configure
$ make
{code}
]]></ac:plain-text-body></ac:macro>

Subsequent rebuilds can be done as follows:
<p>Subsequent rebuilds can be done as follows:</p>

{code}
<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
$ make clean html
{code}
]]></ac:plain-text-body></ac:macro>

<p>The html output is built in a subdirectory *html*. <strong>html</strong>.</p>

h3. Rendering PDF
<h3>Rendering PDF</h3>

*todo:* enhance the Makefile with a *pdf* rule.
<p><strong>todo:</strong> enhance the Makefile with a <strong>pdf</strong> rule.</p>

h3. {anchor:performance}Improving build performance
<h3><ac:macro ac:name="anchor"><ac:default-parameter>performance</ac:default-parameter></ac:macro>Improving build performance</h3>

<p>You may find that building the manual is slow, because xsltproc has to fetch DTD and XSL files from framework.zend.com during the build. This is an improvement over fetching them from open-oasis.org, which is frequently down, but it is still slow to retrieve the files from a remote web site.</p>

<p>If you host copies of the DocBook DTD and DocBook-to-HTML XSL stylesheets locally, you can achieve much more reliable and quick manual builds.</p>

<p>Change directory to the above-mentioned *en* <strong>en</strong> directory or other language directory, and configure and run the Makefile as follows:</p>

{code}
<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
$ autoconf
$ ./configure
$ export DOCBOOK_XSL=/usr/local/lib/docbook-xsl/html/chunk.xsl
$ make -e
{code}
]]></ac:plain-text-body></ac:macro>

<p>The paths above are examples. Use your own locations of the DTD and XSL files.</p>

<p>Using make with the "-e" &quot;-e&quot; flag means that environment variables override Makefile variables of the same name. You only need to use the "-e" &quot;-e&quot; flag when you generate the TOC file and the XSL file. Subsequent rebuilds do not need the "-e" flag: &quot;-e&quot; flag:</p>

{code}
<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
$ make clean html
{code}
]]></ac:plain-text-body></ac:macro>

<p>Zend Framework's website hosts copies of the DocBook DTD and XSL scripts. If you want to download them for offline use, use the following links:</p>

* You can download the DTD files here: http://www.docbook.org/xml/4.5/
* You can download the XSL files here: http://sourceforge.net/project/showfiles.php?group_id=21935
<ul>
<li>You can download the DTD files here: <a class="external-link" href="http://www.docbook.org/xml/4.5/">http://www.docbook.org/xml/4.5/</a></li>
<li>You can download the XSL files here: <a class="external-link" href="http://sourceforge.net/project/showfiles.php?group_id=21935">http://sourceforge.net/project/showfiles.php?group_id=21935</a></li>
</ul>

h2. Authoring DocBook

This section describes Zend Framework's usage of DocBook XML and provides guidelines for using these XML tags.
<h2>Authoring DocBook</h2>

h3. DocBook file organization
<p>This section describes Zend Framework's usage of DocBook XML and provides guidelines for using these XML tags.</p>

Files are named according to the main class name that they document. ZF class names contain underscores, so additional words used in the filename are separated by dashes. For example: Zend_Console_Getopt-Configuration.xml is a file documenting the Zend_Console_Getopt class, and specifically this section relates to configuration of the class.
<h3>DocBook file organization</h3>

As in all writing, there is no strict guideline for how long a single file or section should be. Long enough to cover the subject, but short enough to keep it interesting.
<p>Files are named according to the main class name that they document. ZF class names contain underscores, so additional words used in the filename are separated by dashes. For example: Zend_Console_Getopt-Configuration.xml is a file documenting the Zend_Console_Getopt class, and specifically this section relates to configuration of the class.</p>

In each language directory, there is a kind of table-of-contents file called *manual.xml.in*. This describes how files are included from subdirectories to form the whole manual. Files that cover specific ZF components go under the directory *module_specs*. Files that cover other topics in the manual, but not specific to any single component go under the directory *ref*.
<p>As in all writing, there is no strict guideline for how long a single file or section should be. Long enough to cover the subject, but short enough to keep it interesting.</p>

h3. Using DocBook XML
<p>In each language directory, there is a kind of table-of-contents file called <strong>manual.xml.in</strong>. This describes how files are included from subdirectories to form the whole manual. Files that cover specific ZF components go under the directory <strong>module_specs</strong>. Files that cover other topics in the manual, but not specific to any single component go under the directory <strong>ref</strong>.</p>

The DocBook standard defines a lot of elements, but typically we use a short subset of them. For example:
* <sect1>, <sect2>, <sect3>
* <title>
* <para>
* <note>
* <itemizedlist>, <orderedlist>
* <example>, <programlisting>
* <table>
* <inlinegraphic>
* <code>
* <emphasis>
* <xref>, <link>, <ulink>
<h3>Using DocBook XML</h3>

For full reference documentation on the DocBook XML standard, see the online version of +DocBook: The Definitive Guide+: http://www.docbook.org/tdg/ Use the documentation of DocBook 4.x.
<p>The DocBook standard defines a lot of elements, but typically we use a short subset of them. For example:</p>
<ul>
<li>&lt;sect1&gt;, &lt;sect2&gt;, &lt;sect3&gt;</li>
<li>&lt;title&gt;</li>
<li>&lt;para&gt;</li>
<li>&lt;note&gt;</li>
<li>&lt;itemizedlist&gt;, &lt;orderedlist&gt;</li>
<li>&lt;example&gt;, &lt;programlisting&gt;</li>
<li>&lt;table&gt;</li>
<li>&lt;inlinegraphic&gt;</li>
<li>&lt;code&gt;</li>
<li>&lt;emphasis&gt;</li>
<li>&lt;xref&gt;, &lt;link&gt;, &lt;ulink&gt;</li>
</ul>

h4. Element id attributes

By convention we define the id attribute for sections and examples with a hierarchical notation. The id string combines the hierarchy of section identifiers separated by dots. This is a convention we use, though DocBook does not enforce this.
<p>For full reference documentation on the DocBook XML standard, see the online version of <span style="text-decoration: underline;">DocBook: The Definitive Guide</span>: <a class="external-link" href="http://www.docbook.org/tdg/">http://www.docbook.org/tdg/</a> Use the documentation of DocBook 4.x.</p>

<h4>Element id attributes</h4>
{code:xml}
<p>By convention we define the id attribute for sections and examples with a hierarchical notation. The id string combines the hierarchy of section identifiers separated by dots. This is a convention we use, though DocBook does not enforce this. </p>

<ac:macro ac:name="code"><ac:default-parameter>xml</ac:default-parameter><ac:plain-text-body><![CDATA[
<sect1 id="zend.console.getopt.configuration">
<title>Configuring Zend_Console_Getopt</title>
</sect2>
</sect1>
{code}
]]></ac:plain-text-body></ac:macro>

<p>All id values should start with the id string of the element's parent {{<sect>}} <code>&lt;sect&gt;</code> element. In the previous example, {{<sect2 id="zend.console.getopt.addrules">}} <code>&lt;sect2 id=&quot;zend.console.getopt.addrules&quot;&gt;</code> would not be correct, because it doesn't include the full id string of its parent {{<sect1>}}. <code>&lt;sect1&gt;</code>.</p>

<p>The id values must be unique. DocBook complains if you use duplicate values for id attributes. The id values must be unique over the whole set of DocBook files, not only within each file. Using id values in the hierarchical manner described above makes it easy to ensure they are unique.</p>

You should have an id attribute on each {{<sect*>}} elements, each {{<example>}} elements, and each {{<table>}} elements.
<p>You should have an id attribute on each <code>&lt;sect*&gt;</code> elements, each <code>&lt;example&gt;</code> elements, and each <code>&lt;table&gt;</code> elements. <br />
Recently I added id attributes to many example and table elements that lacked an id. I used generic id names like "example-1" &quot;example-1&quot; for many of these id strings, but you may use a more meaningful name.</p>

h4. Section elements
<h4>Section elements</h4>

Each {{<sect1>}} <p>Each <code>&lt;sect1&gt;</code> element starts a new XML file. When this file is rendered into HTML, all the content within that {{<sect1>}} <code>&lt;sect1&gt;</code> appears in a single HTML page. In other words, the documentation is _chunked_ <em>chunked</em> at {{<sect1>}} boundaries. <code>&lt;sect1&gt;</code> boundaries.</p>

<p>Subsections are in {{<sect2>}}, {{<sect3>}} <code>&lt;sect2&gt;</code>, <code>&lt;sect3&gt;</code> etc. Use good document outline design for the hierarchy of sections. For example, the material covered under a <sect2> &lt;sect2&gt; should be completely relevant to its parent {{<sect1>}}. <code>&lt;sect1&gt;</code>.</p>

<p>Some subsections are separated into additional files, which are included into their parent section using XInclude syntax. The subsection files typically start at {{<sect2>}} <code>&lt;sect2&gt;</code> boundaries. This does not affect chunking; a single HTML page is rendered from the total content within a {{<sect1>}} <code>&lt;sect1&gt;</code> section, even if it includes content from multiple subsection files.</p>

h4. Title elements
<h4>Title elements</h4>

Each section must contain a {{<title>}} element.
<p>Each section must contain a <code>&lt;title&gt;</code> element.</p>

{code:xml}
<ac:macro ac:name="code"><ac:default-parameter>xml</ac:default-parameter><ac:plain-text-body><![CDATA[
<sect2 id="...">
<title>TITLE ELEMENT IS REQUIRED IN EACH SECT</title>
...
</sect2>
{code}
]]></ac:plain-text-body></ac:macro>

You may also have a {{<title>}} element inside {{<example>}} and {{<note>}} elements, but it's not required.
<p>You may also have a <code>&lt;title&gt;</code> element inside <code>&lt;example&gt;</code> and <code>&lt;note&gt;</code> elements, but it's not required.</p>

h4. Paragraph elements
<h4>Paragraph elements</h4>

<p>Most text is set inside a {{<para>}} <code>&lt;para&gt;</code> element. This includes text inside list entries, notes, examples, etc.</p>

h4. Note elements
<h4>Note elements</h4>

<p>When you want to call attention to a short topic, set it inside a {{<note>}} <code>&lt;note&gt;</code> element. <br />
It may have a child {{<title>}} <code>&lt;title&gt;</code> element, but this is not required. <br />
Text of a {{<note>}} element must be within {{<para>}} elements.
Text of a <code>&lt;note&gt;</code> element must be within <code>&lt;para&gt;</code> elements.</p>

h4. List elements
<h4>List elements</h4>

<p>You can use {{<itemizedlist>}} <code>&lt;itemizedlist&gt;</code> for bulleted lists, or {{<orderedlist>}} <code>&lt;orderedlist&gt;</code> for numbered lists. These are good ways of presenting lists of items in a pleasant and easy-to-read manner.</p>

Each list entry must contain a {{<para>}} element.
<p>Each list entry must contain a <code>&lt;para&gt;</code> element.</p>

{code:xml}
<ac:macro ac:name="code"><ac:default-parameter>xml</ac:default-parameter><ac:plain-text-body><![CDATA[
<itemizedlist>
<listitem>
</listitem>
</itemizedlist>
{code}
]]></ac:plain-text-body></ac:macro>

h4. Program listing elements
<h4>Program listing elements</h4>

<p>Most manual sections contain PHP code samples. Here is an example:</p>

{code:xml}
<ac:macro ac:name="code"><ac:default-parameter>xml</ac:default-parameter><ac:plain-text-body><![CDATA[
<example id="...">
<title>Example title</title>
<programlisting role="php"><![CDATA[<?php
...PHP code...
?>]]]]><![CDATA[>
</example>
{code}
]]></ac:plain-text-body></ac:macro>

An {{<example>}} element may contain {{<title>}} and {{<para>}} elements, but these are not required. You may have an {{<example>}} that simply contains a {{<programlisting>}} element.
<p>An <code>&lt;example&gt;</code> element may contain <code>&lt;title&gt;</code> and <code>&lt;para&gt;</code> elements, but these are not required. You may have an <code>&lt;example&gt;</code> that simply contains a <code>&lt;programlisting&gt;</code> element.</p>

In some places of the manual, we use {{<programlisting>}} elements without an {{<example>}} element. This is okay.
<p>In some places of the manual, we use <code>&lt;programlisting&gt;</code> elements without an <code>&lt;example&gt;</code> element. This is okay.</p>

h4. Table elements
<h4>Table elements</h4>

<p>Tables in DocBook can be complex, but here is a template that shows typical use:</p>

{code:xml}
<ac:macro ac:name="code"><ac:default-parameter>xml</ac:default-parameter><ac:plain-text-body><![CDATA[
<table id="zend.db.adapter.list-describe.metadata">
<title>Metadata fields returned by describeTable()</title>
</tgroup>
</table>
{code}
]]></ac:plain-text-body></ac:macro>

h4. Figure elements
<h4>Figure elements</h4>

<p>Including a graphic figure in your DocBook section is simple. Use the {{<inlinegraphic>}} <code>&lt;inlinegraphic&gt;</code> element, within a {{<para>}} <code>&lt;para&gt;</code> element. Declare the width and height of the graphi, and use the fileref attribute to declare the location of the image file.</p>

{code:xml}
<ac:macro ac:name="code"><ac:default-parameter>xml</ac:default-parameter><ac:plain-text-body><![CDATA[
<para>
<inlinegraphic width="387" scale="100" align="center" valign="middle"
format="PNG" />
</para>
{code}
]]></ac:plain-text-body></ac:macro>

<p>Image files should be located in the subdirectory *figures* <strong>figures</strong> under the manual directory, and should be named after the subsection in which they appear, in a similar way to defining id values.</p>

h4. Code inline elements
<h4>Code inline elements</h4>

<p>Use the {{<code>}} <code>&lt;code&gt;</code> element to format text inline within a paragraph. Typically, inline references to variables, methods, or other code fragments use this formatting.</p>

{code:xml}
<ac:macro ac:name="code"><ac:default-parameter>xml</ac:default-parameter><ac:plain-text-body><![CDATA[
<para>
You can run a SQL SELECT query and retrieve its results in one
step using the <code>fetchAll()</code> method.
</para>
{code}
]]></ac:plain-text-body></ac:macro>

h4. Emphasis inline elements
<h4>Emphasis inline elements</h4>

Use the <emphasis> element to format text in italics or bold face. By default, <emphasis> is rendered italics. Specify the attribute {{role="strong"}} to format text in bold face.
<p>Use the &lt;emphasis&gt; element to format text in italics or bold face. By default, &lt;emphasis&gt; is rendered italics. Specify the attribute <code>role=&quot;strong&quot;</code> to format text in bold face.</p>

{code:xml}
<ac:macro ac:name="code"><ac:default-parameter>xml</ac:default-parameter><ac:plain-text-body><![CDATA[
<para>
The return value of the <code>insert()</code> method is
might not have an auto-incremented column.
</para>
{code}
]]></ac:plain-text-body></ac:macro>

h4. Link elements
<h4>Link elements</h4>

<p>Use the {{<link>}} <code>&lt;link&gt;</code> element to make text a hyperlink to another section of the manual.</p>

{code:xml}
<ac:macro ac:name="code"><ac:default-parameter>xml</ac:default-parameter><ac:plain-text-body><![CDATA[
<para>
This method dynamically loads the Adapter class file on demand,
Zend_Loader::loadClass()</link>.
</para>
{code}
]]></ac:plain-text-body></ac:macro>

<p>Use the {{<xref>}} <code>&lt;xref&gt;</code> element to make a hyperlink to another section of the manual. Use this when you want the link text to be generated automatically from the section number and title of the link target.</p>

{code:xml}
<ac:macro ac:name="code"><ac:default-parameter>xml</ac:default-parameter><ac:plain-text-body><![CDATA[
<para>
You are responsible for ensuring that any dynamic content is
for methods to help you do this.
</para>
{code}
]]></ac:plain-text-body></ac:macro>

Use the {{<ulink>}} element to make a hyperlink to an external internet URL.
<p>Use the <code>&lt;ulink&gt;</code> element to make a hyperlink to an external internet URL.</p>

{code:xml}
<ac:macro ac:name="code"><ac:default-parameter>xml</ac:default-parameter><ac:plain-text-body><![CDATA[
<para>
See <ulink url="http://en.wikipedia.org/wiki/SQL_Injection">
http://en.wikipedia.org/wiki/SQL_Injection</ulink>.
</para>
{code}
]]></ac:plain-text-body></ac:macro>

h3. DocBook pitfalls
<h3>DocBook pitfalls</h3>

{note:title=Para required}
The {{<listitem>}} and {{<note>}} elements each require a {{<para>}} element inside them:
<ac:macro ac:name="note"><ac:parameter ac:name="title">Para required</ac:parameter><ac:rich-text-body>
<p>The <code>&lt;listitem&gt;</code> and <code>&lt;note&gt;</code> elements each require a <code>&lt;para&gt;</code> element inside them:</p>

{code:xml}
<ac:macro ac:name="code"><ac:default-parameter>xml</ac:default-parameter><ac:plain-text-body><![CDATA[
<itemizedlist>
<listitem>
<para>NESTED PARA IS REQUIRED</para>
</note>
{code}
{note}
]]></ac:plain-text-body></ac:macro></ac:rich-text-body></ac:macro>

{note:title=Content preceding subsections}
<ac:macro ac:name="note"><ac:parameter ac:name="title">Content preceding subsections</ac:parameter><ac:rich-text-body>
<p>You can make content precede subsections, but not follow subsections:</p>

{code:xml}
<ac:macro ac:name="code"><ac:default-parameter>xml</ac:default-parameter><ac:plain-text-body><![CDATA[
<sect1>
<sect2></sect2>
<sect2></sect2>
</sect1>
{code}
{note}
]]></ac:plain-text-body></ac:macro></ac:rich-text-body></ac:macro>

{note:title=URL not HREF}
The attribute of the {{<ulink>}} element naming the URL is called "url", not "href".
<ac:macro ac:name="note"><ac:parameter ac:name="title">URL not HREF</ac:parameter><ac:rich-text-body>
<p>The attribute of the <code>&lt;ulink&gt;</code> element naming the URL is called &quot;url&quot;, not &quot;href&quot;.</p>

{code:xml}
<ac:macro ac:name="code"><ac:default-parameter>xml</ac:default-parameter><ac:plain-text-body><![CDATA[
<!-- WRONG -->
<ulink href="http://framework.zend.com">
<!-- RIGHT -->
<ulink url="http://framework.zend.com">
{code}
{note}
]]></ac:plain-text-body></ac:macro></ac:rich-text-body></ac:macro>

h3. DocBook table of contents
<h3>DocBook table of contents</h3>

<p>The TOC for the manual is defined in manual.xml.in. The format is pretty straightforward, so if you are adding a section you can just copy & &amp; paste a block for one of the existing components. For instance, I am working on Zend_Filter_Input right now and I have the following block in the manual.xml.in file:</p>

{code:xml}
<ac:macro ac:name="code"><ac:default-parameter>xml</ac:default-parameter><ac:plain-text-body><![CDATA[
<chapter id="zend.filter">
<title>Zend_Filter</title>
<xi:include href="module_specs/Zend_Filter_Input.xml" />
</chapter>
{code}
]]></ac:plain-text-body></ac:macro>

<p>In the translation directories, the manual.xml.in file defines fallback rules for files that are missing. If a file has not been translated yet, it is not present in the translation directory. The corresponding file in the English directory is substituted automatically.</p>

{code:xml}
<ac:macro ac:name="code"><ac:default-parameter>xml</ac:default-parameter><ac:plain-text-body><![CDATA[
<chapter id="zend.filter">
<title>Zend_Filter</title>
</xi:include>
</chapter>
{code}
]]></ac:plain-text-body></ac:macro>

h2. Testing DocBook
<h2>Testing DocBook</h2>

<p>You can also optionally use xmllint to validate your XML before building.</p>

{code}
<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
$ make check
{code}
]]></ac:plain-text-body></ac:macro>

*note:* <p><strong>note:</strong> this concatenates all the docs under module_specs, so any errors or warnings are reported on line numbers in the concatenated file "_temp_manual.xml". &quot;_temp_manual.xml&quot;.</p>

<p>This testing process reports a warning about the declaration of the "xi" &quot;xi&quot; namespace used by XInclude. This is okay; it appears to be a harmless warning.</p>

h2. Translating the Manual
<h2>Translating the Manual</h2>

<p>Zend Framework includes subdirectories for translations of the manual into more than 15 languages. Community volunteers from around the world contribute their time to provide these translations.</p>

h3. Volunteering as a translator
<h3>Volunteering as a translator</h3>

h4. Sign a CLA form
<h4>Sign a CLA form</h4>

<p>Like any contribution of code, documentation translations must be contributed to the Zend Framework project under the terms of the Contributor License Agreement (CLA). The first step to get started as a translator is to sign a the CLA form. See http://framework.zend.com/wiki/display/ZFPROP/Contributor+License+Agreement <a class="external-link" href="http://framework.zend.com/wiki/display/ZFPROP/Contributor+License+Agreement">http://framework.zend.com/wiki/display/ZFPROP/Contributor+License+Agreement</a> </p>

h4. Get authorized to commit changes
<h4>Get authorized to commit changes</h4>

<p>Email us at cla@zend.com and let us know you are interested in contributing to a translation project. We need to create an account for you and authorize it to make changes. If you volunteer to make a new translation that currently does not exist, we create the empty directory for you to get started.</p>

h4. Download documentation sources from subversion
<h4>Download documentation sources from subversion</h4>

<p>You need to use a subversion client (svn) if you want to commit changes. You cannot use the Zend Framework downloads or snapshots. These are read-only.</p>

<p>You do not need to check out the whole Zend Framework tree. You can check out the subdirectory for the language you use. For example, if you work on the French translation, you would use your svn client to check out http://framework.zend.com/svn/framework/trunk/documentation/manual/fr/ <a class="external-link" href="http://framework.zend.com/svn/framework/trunk/documentation/manual/fr/">http://framework.zend.com/svn/framework/trunk/documentation/manual/fr/</a></p>

You also need to check out the English directory: http://framework.zend.com/svn/framework/trunk/documentation/manual/en/
<p>You also need to check out the English directory: <a class="external-link" href="http://framework.zend.com/svn/framework/trunk/documentation/manual/en/">http://framework.zend.com/svn/framework/trunk/documentation/manual/en/</a> </p>

* Download the command-line svn client for Windows or Linux here: http://subversion.tigris.org/project_packages.html
* Download an easy-to-use graphical svn client for Windows here: http://tortoisesvn.tigris.org/
* A book on using Subversion is available online for free here: http://svnbook.red-bean.com/
<ul>
<li>Download the command-line svn client for Windows or Linux here: <a class="external-link" href="http://subversion.tigris.org/project_packages.html">http://subversion.tigris.org/project_packages.html</a></li>
<li>Download an easy-to-use graphical svn client for Windows here: <a class="external-link" href="http://tortoisesvn.tigris.org/">http://tortoisesvn.tigris.org/</a></li>
<li>A book on using Subversion is available online for free here: <a class="external-link" href="http://svnbook.red-bean.com/">http://svnbook.red-bean.com/</a></li>
</ul>

h4. Communicate with other translators

The mailing list fw-docs@lists.zend.com is for discussion of documentation issues, including the process of translating. You can cooperate with other translators and trade tips and suggestions. If you are on a team with multiple people, you should organize yourselves and decide who is working on each individual file, so you avoid duplicating work.
<h4>Communicate with other translators</h4>

h4. Edit, test, commit
<p>The mailing list fw-docs@lists.zend.com is for discussion of documentation issues, including the process of translating. You can cooperate with other translators and trade tips and suggestions. If you are on a team with multiple people, you should organize yourselves and decide who is working on each individual file, so you avoid duplicating work.</p>

Edit files one by one and translate them. After you have translated a file and tested the documentation by building it, commit it to the subversion repository.
<h4>Edit, test, commit</h4>

h3. Translating files
<p>Edit files one by one and translate them. After you have translated a file and tested the documentation by building it, commit it to the subversion repository.</p>

A new translation directory contains the build scripts such as Makefile.in, manual.xml.in, etc. It also contains the DocBook XML files subdirectories, module_specs and ref, but these directories contain no files to begin with.
<h3>Translating files</h3>

When you are ready to translate a file, copy the file from the English directory to the translation directory. Do not change the name of the file. For example, if you are working on the French translation, a typical sequence of commands is shown below:
<p>A new translation directory contains the build scripts such as Makefile.in, manual.xml.in, etc. It also contains the DocBook XML files subdirectories, module_specs and ref, but these directories contain no files to begin with.</p>

<p>When you are ready to translate a file, copy the file from the English directory to the translation directory. Do not change the name of the file. For example, if you are working on the French translation, a typical sequence of commands is shown below:</p>
{code}
<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
$ cd <zf home>/documentation/manual/fr
$ cp ../en/module_specs/Zend_Controller-ActionController.xml ./module_specs
{code}
]]></ac:plain-text-body></ac:macro>

<p>Edit the file and replace English text with text in your own language. </p>

{code}
<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
$ vim module_specs/Zend_Controller-ActionController.xml
{code}
]]></ac:plain-text-body></ac:macro>

<p>When you are done translating the file, test it by building the manual by the steps documented earlier. The manual build script automatically uses the file if it is present in your translation directory.</p>

{code}
<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
$ autoconf
$ ./configure
$ make -e
$ make check
{code}
]]></ac:plain-text-body></ac:macro>

<p>When you are satisfied with your translation and you have run a test and a builds to verify it is correct, commit the file to svn.</p>

{code}
<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
$ svn add module_specs/Zend_Controller-ActionController.xml
$ svn commit -m "initial translation of ActionController section"
{code}
]]></ac:plain-text-body></ac:macro>

<p>You may also translate some of the strings in the file manual.xml.in. Most of these are simply the names of classes in the Zend Framework, and so they should not be translated. But a few strings, such as the <title> &lt;title&gt; and <edition> &lt;edition&gt; of the document may be translated.</p>

h3. Monitoring changes
<h3>Monitoring changes</h3>

<p>Stay notified of changes in the English manual. </p>

* Subscribe to an email notification list by emailing fw-svn-docs-subscribe@lists.zend.com.
* Use an RSS feed from WebSVN: http://framework.zend.com/code/rss.php?repname=Zend+Framework&path=%2F&isdir=1&
<ul>
<li>Subscribe to an email notification list by emailing fw-svn-docs-subscribe@lists.zend.com.</li>
<li>Use an RSS feed from WebSVN: <a class="external-link" href="http://framework.zend.com/code/rss.php?repname=Zend+Framework&amp;path=%2F&amp;isdir=1&amp;">http://framework.zend.com/code/rss.php?repname=Zend+Framework&amp;path=%2F&amp;isdir=1&amp;</a></li>
</ul>

If any changes occur in files you have previously translated, you are responsible for updating your translation to match the new content.

h3. Translation tips
<p>If any changes occur in files you have previously translated, you are responsible for updating your translation to match the new content.</p>

{tip:title=Starter files}
Start by translating small files to learn how to work with DocBook. Here are suggestions for good files to use:
* ref/copyrights.xml
* ref/installation.xml
* ref/overview.xml
{tip}
<h3>Translation tips</h3>

{tip:title=Priority Components}
Focus on translating files for the most commonly used components:
* module_specs/Zend_Controller*.xml
* module_specs/Zend_Db*.xml
* module_specs/Zend_Search_Lucene*.xml
<ac:macro ac:name="tip"><ac:parameter ac:name="title">Starter files</ac:parameter><ac:rich-text-body>
<p>Start by translating small files to learn how to work with DocBook. Here are suggestions for good files to use:</p>
{tip} <ul>
<li>ref/copyrights.xml</li>
<li>ref/installation.xml</li>
<li>ref/overview.xml</li>
</ul>
</ac:rich-text-body></ac:macro>

<ac:macro ac:name="tip"><ac:parameter ac:name="title">Priority Components</ac:parameter><ac:rich-text-body>
<p>Focus on translating files for the most commonly used components:</p>
{tip:title=Testing} <ul>
<li>module_specs/Zend_Controller*.xml</li>
<li>module_specs/Zend_Db*.xml</li>
<li>module_specs/Zend_Search_Lucene*.xml</li>
</ul>
</ac:rich-text-body></ac:macro>

<ac:macro ac:name="tip"><ac:parameter ac:name="title">Testing</ac:parameter><ac:rich-text-body>
<p>Test your changes before committing them, and fix any errors reported.</p>
{code}
<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
$ make check
$ make html
{code}
]]></ac:plain-text-body></ac:macro>

<p>Open the rendered documentation under the html subdirectory to verify that your edited files appear as you expect them to.</p></ac:rich-text-body></ac:macro>
{tip}

{tip:title=Work faster offline}
<ac:macro ac:name="tip"><ac:parameter ac:name="title">Work faster offline</ac:parameter><ac:rich-text-body>
<p>Download an offline copy of DocBook DTD and XSL files to make building and testing your changes much quicker. See section [#performance] <ac:link ac:anchor="performance"><ac:link-body>#performance</ac:link-body></ac:link> earlier in this document.</p></ac:rich-text-body></ac:macro>
{tip}

h2. Editing DocBook
<h2>Editing DocBook</h2>

A great list of authoring tools for DocBook XML is found here: http://wiki.docbook.org/topic/DocBookAuthoringTools
<p>A great list of authoring tools for DocBook XML is found here: <a class="external-link" href="http://wiki.docbook.org/topic/DocBookAuthoringTools">http://wiki.docbook.org/topic/DocBookAuthoringTools</a></p>

h3. Vim
<h3>Vim</h3>

<p>I'm a fan of the venerable *vi* <strong>vi</strong> editor. With XML syntax highlighting, auto-indentation, this serves as a fine editor for DocBook. Most editors are bloated and slow, but not vim! On Windows I use *gvim* <strong>gvim</strong> with the XML plugin.</p>
* http://www.vim.org/download.php
* http://www.vim.org/scripts/script.php?script_id=301
<ul>
<li><a class="external-link" href="http://www.vim.org/download.php">http://www.vim.org/download.php</a></li>
<li><a class="external-link" href="http://www.vim.org/scripts/script.php?script_id=301">http://www.vim.org/scripts/script.php?script_id=301</a></li>
</ul>

h3. Emacs

I don't know emacs, but many people swear by it. There's an XML plugin for emacs.
* http://www.gnu.org/software/emacs/windows/big.html#introduction
* http://www.lysator.liu.se/~lenst/about_psgml/
<h3>Emacs</h3>

h3. XMLMind
<p>I don't know emacs, but many people swear by it. There's an XML plugin for emacs.</p>
<ul>
<li><a class="external-link" href="http://www.gnu.org/software/emacs/windows/big.html#introduction">http://www.gnu.org/software/emacs/windows/big.html#introduction</a></li>
<li><a class="external-link" href="http://www.lysator.liu.se/~lenst/about_psgml/">http://www.lysator.liu.se/~lenst/about_psgml/</a></li>
</ul>

The XMLMind XML Editor Personal Edition is a nice XML editor. It is free for working on open-source projects like Zend Framework.
* http://www.xmlmind.com/xmleditor

h3. oXygen
<h3>XMLMind</h3>

<p>The XMLMind XML Editor Personal Edition is a nice XML editor. It is free for working on open-source projects like Zend Framework.</p>
<ul>
<li><a class="external-link" href="http://www.xmlmind.com/xmleditor">http://www.xmlmind.com/xmleditor</a></li>
</ul>


<h3>oXygen</h3>

<p>The oXygen XML editor is a high-end product with many features, but it's not free.</p>
* http://www.oxygenxml.com/
<ul>
<li><a class="external-link" href="http://www.oxygenxml.com/">http://www.oxygenxml.com/</a></li>
</ul>