Skip to end of metadata
Go to start of metadata
You are viewing an old version of this page. View the current version. Compare with Current  |   View Page History

Zend Framework Guide to DocBook

Introduction

This document describes the technology and process of working on the documentation for Zend Framework.

Getting Documentation Sources

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

Using Subversion

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.

Using nightly snapshots

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.

Using WebSVN

The Zend Framework website operates a web application called WebSVN, which gives an interface to browse the ZF subversion project.

WebSVN feeds

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:

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.

Tools to build DocBook

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

  • make
  • autoconf
  • xsltproc
  • xmllint
  • 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/).

Rendering HTML

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.

Rendering PDF

todo: enhance the Makefile with a pdf rule.

Improving build performance

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:

Authoring DocBook

This section describes Zend Framework's usage of DocBook XML and provides guidelines for using these XML tags.

DocBook file organization

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.

Using DocBook XML

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>

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.

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.

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.

Section elements

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.

Title elements

Each section must contain a <title> element.

You may also have a <title> element inside <example> and <note> elements, but it's not required.

Paragraph elements

Most text is set inside a <para> element. This includes text inside list entries, notes, examples, etc.

Note elements

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.

List 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.

Program listing elements

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.

Table elements

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

Figure elements

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.

Code inline elements

Use the <code> element to format text inline within a paragraph. Typically, inline references to variables, methods, or other code fragments use this formatting.

Emphasis inline elements

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.

Link elements

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.

DocBook pitfalls

Para required
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".

DocBook table of contents

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.

Testing DocBook

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.

Translating the Manual

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.

Volunteering as a translator

Sign a CLA form

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

Get authorized to commit changes

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.

Download documentation sources from subversion

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/

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.

Edit, test, commit

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.

Translating files

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.

Monitoring changes

Stay notified of changes in the English manual.

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

Translation tips

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
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
Testing
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.

Editing DocBook

A great list of authoring tools for DocBook XML is found here: http://wiki.docbook.org/topic/DocBookAuthoringTools

Vim

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.

Emacs

I don't know emacs, but many people swear by it. There's an XML plugin for emacs.

XMLMind

The XMLMind XML Editor Personal Edition is a nice XML editor. It is free for working on open-source projects like Zend Framework.

oXygen

The oXygen XML editor is a high-end product with many features, but it's not free.

Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.