This document describes the technology and process of working on the documentation for Zend Framework.
This section details how to gain access to the sources so you can author or build the documentation.
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:
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:
To access the files for the French translation, you can check out the fr subdirectory:
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.
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.
The Zend Framework website operates a web application called Fisheye, which gives an interface to browse the ZF subversion project.
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:
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.
Each language directory contains scripts to configure and process the DocBook XML sources into HTML. This section detail how to use these scripts.
The tools you'll need to do this build are:
- standard UNIX/Linux shell and common tools
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/).
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:
Subsequent rebuilds can be done as follows:
The html output is built in a subdirectory html.
todo: enhance the Makefile with a pdf rule.
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.
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.
Change directory to the above-mentioned en directory or other language directory, and configure and run the Makefile as follows:
The paths above are examples. Use your own locations of the DTD and XSL files.
Using make with the "-e" flag means that environment variables override Makefile variables of the same name. You only need to use the "-e" flag when you generate the TOC file and the XSL file. Subsequent rebuilds do not need the "-e" flag:
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:
- 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
This section describes Zend Framework's usage of DocBook XML and provides guidelines for using these XML tags.
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.
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.
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.
The DocBook standard defines a lot of elements, but typically we use a short subset of them. For example:
- <sect1>, <sect2>, <sect3>
- <itemizedlist>, <orderedlist>
- <example>, <programlisting>
- <xref>, <link>, <ulink>
For full reference documentation on the DocBook XML standard, see the online version of : http://www.docbook.org/tdg/ Use the documentation of DocBook 4.x.
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.
All id values should start with the id string of the element's parent <sect> element. In the previous example, <sect2 id="zend.console.getopt.addrules"> would not be correct, because it doesn't include the full id string of its parent <sect1>.
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.
You should have an id attribute on each <sect*> elements, each <example> elements, and each <table> elements.
Recently I added id attributes to many example and table elements that lacked an id. I used generic id names like "example-1" for many of these id strings, but you may use a more meaningful name.
Each <sect1> element starts a new XML file. When this file is rendered into HTML, all the content within that <sect1> appears in a single HTML page. In other words, the documentation is chunked at <sect1> boundaries.
Subsections are in <sect2>, <sect3> etc. Use good document outline design for the hierarchy of sections. For example, the material covered under a <sect2> should be completely relevant to its parent <sect1>.
Some subsections are separated into additional files, which are included into their parent section using XInclude syntax. The subsection files typically start at <sect2> boundaries. This does not affect chunking; a single HTML page is rendered from the total content within a <sect1> section, even if it includes content from multiple subsection files.
Each section must contain a <title> element.
You may also have a <title> element inside <example> and <note> elements, but it's not required.
Most text is set inside a <para> element. This includes text inside list entries, notes, examples, etc.
When you want to call attention to a short topic, set it inside a <note> element.
It may have a child <title> element, but this is not required.
Text of a <note> element must be within <para> elements.
You can use <itemizedlist> for bulleted lists, or <orderedlist> for numbered lists. These are good ways of presenting lists of items in a pleasant and easy-to-read manner.
Each list entry must contain a <para> element.
Most manual sections contain PHP code samples. Here is an example:
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.
In some places of the manual, we use <programlisting> elements without an <example> element. This is okay.
Tables in DocBook can be complex, but here is a template that shows typical use:
Including a graphic figure in your DocBook section is simple. Use the <inlinegraphic> element, within a <para> element. Declare the width and height of the graphi, and use the fileref attribute to declare the location of the image file.
Image files should be located in the subdirectory figures under the manual directory, and should be named after the subsection in which they appear, in a similar way to defining id values.
Use the <code> element to format text inline within a paragraph. Typically, inline references to variables, methods, or other code fragments use this formatting.
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.
Use the <link> element to make text a hyperlink to another section of the manual.
Use the <xref> 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.
Use the <ulink> element to make a hyperlink to an external internet URL.
The <listitem> and <note> elements each require a <para> element inside them:
|Content preceding subsections|
You can make content precede subsections, but not follow subsections:
|URL not HREF|
The attribute of the <ulink> element naming the URL is called "url", not "href".
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 & 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:
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.
You can also optionally use xmllint to validate your XML before building.
note: 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".
This testing process reports a warning about the declaration of the "xi" namespace used by XInclude. This is okay; it appears to be a harmless warning.
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.
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
Email us at firstname.lastname@example.org 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.
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.
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/
You also need to check out the English directory: http://framework.zend.com/svn/framework/trunk/documentation/manual/en/
- 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/
The mailing list email@example.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.
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.
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.
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:
Edit the file and replace English text with text in your own language.
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.
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.
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> and <edition> of the document may be translated.
Stay notified of changes in the English manual.
- Subscribe to an email notification list by emailing firstname.lastname@example.org.
- Use an RSS feed from Fisheye: http://framework.zend.com/fisheye/changelog/~rss/Zend_Framework/trunk/documentation/manual/en/rss.xml
If any changes occur in files you have previously translated, you are responsible for updating your translation to match the new content.
Start by translating small files to learn how to work with DocBook. Here are suggestions for good files to use:
Focus on translating files for the most commonly used components:
Test your changes before committing them, and fix any errors reported.
Open the rendered documentation under the html subdirectory to verify that your edited files appear as you expect them to.
|Work faster offline|
Download an offline copy of DocBook DTD and XSL files to make building and testing your changes much quicker. See section performance earlier in this document.
A great list of authoring tools for DocBook XML is found here: http://wiki.docbook.org/topic/DocBookAuthoringTools
I'm a fan of the venerable vi 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 with the XML plugin.
I don't know emacs, but many people swear by it. There's an XML plugin for emacs.
The XMLMind XML Editor Personal Edition is a nice XML editor. It is free for working on open-source projects like Zend Framework.
The oXygen XML editor is a high-end product with many features, but it's not free.