How to compile Zend Framework documentation

Introduction

There are 2 possibilities to compile Zend Framework documentation (for 1.x or 2.x series):

  • xsltproc : XSLT processor
  • PhD: PHP tool used by http://php.net

I will show the 2 methods based on Ubuntu 11.10.

Get Zend Framework sources

For 1.x serie, you must use Subversion:

$ cd /path/you/want
$ svn co  http://framework.zend.com/svn/framework/standard/trunk/documentation/manual/ .

To update your sources:

$ svn up

For 2.x serie, you must use Git: read http://framework.zend.com/wiki/display/ZFDEV2/Zend+Framework+Git+Guide

XSLT Processor

You need to install some tools:

# apt-get install autoconf make xsltproc libxml2-util docbook-utils docbook-xsl

At this stade, you can simply go in your favorite language directory to check the manual:

$ autoconf
$ ./configure
$ make check

You should obtain something like:

sed -e 's!@DOCBOOK_DTD@!http://framework.zend.com/docbook/xml/4.5/docbookx.dtd!' ../en/manual.xml.in > manual.xml
Checking the whole manual with /usr/bin/xmllint...
OK

In this result, you can see that you use ‘docbook.dtd’ located on Zend server. You can use the file located on your computer (downloaded with apt-get above) by adding:

$ export DOCBOOK_DTD=/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd
$ # then
$ make cleanall
$ autoconf
$ ./configure
$ make check

Now, you have:

sed -e 's!@DOCBOOK_DTD@!/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd!' ../en/manual.xml.in > manual.xml
Checking the whole manual with /usr/bin/xmllint...
OK

If the final result is ‘OK’, yon can compile the documentation in HTML with:

$ make

But this will use XSL stylesheets located on Zend server. In the initial ‘apt-get’ you downloaded these stylesheets. To automagically use them you should add:

$ export DOCBOOK_XSL=/usr/share/xml/docbook/stylesheet/docbook-xsl/html/chunk.xsl
$ # then
$ make cleanall
$ autoconf
$ ./configure
$ make

It took me 19 minutes to compile English HTML documentation for trunk r24580. This is a rough version (no images for design, no color).

If you like PDF version of the documentation (around 1860 pages), you can also compile it with FOP, you need:

# apt-get install fop
$ # then
$ make cleanall
$ autoconf
$ ./configure
$ make pdf

It took me 6 minutes to compile English PDF documentation for trunk r24580. This is a rough version (no images for design, no color).

If you prefer the CHM version, it’s a little more complicated on Ubuntu but it’s possible! First step you need:

# apt-get install wine

Then start at least one time Wine (Notepad for example) to generate default configuration. After that you can use the following script (provided in http://appdb.winehq.org/objectManager.php?sClass=version&iId=2978&iTestingId=15284):

#!/bin/bash -e
# -e Exit immediately if a command exits with a non-zero status.

# This installs Microsofts HHC (HTML Help Compiler)
# Copyright 2011 Timo Richter and others.
# Licensed under GNU GPLv3
# Depends on: wine, wget, cabextract
#
# Usage of HHC: wine c:\\htmlhelp\\hhc.exe c:\\test\\htmlhelp.hhp
#
# Changes: Set installation directory to c:\htmlhelp
# Copy also itcc.dll, this is neccessary
# No execution of htmlhelp.exe installer needed
# Abortion of install if anything fails, e.g. the download of HHC.
#

echo "Please wait"

cd "$(dirname "$0")" # cd to path of this script

WINEPREFIX=${WINEPREFIX:=$HOME/.wine}
test -d "$WINEPREFIX" || wineprefixcreate 2>> /dev/null
HHDIR="${WINEPREFIX}/dosdevices/c:/htmlhelp"
mkdir "$HHDIR"

# Setup the registry
# Set Wine's Windows version to Windows 2000 (or above), and add an override to use the native itss.dll, both via winecfg.
# wine regedit htmlhelp.reg

After chmod+x the script then launch it.

Now you have HTML Help Workshop on your machine, you need to create files to generate the CHM. The first DOCBOOK_XSL (chunk.xsl) doesn’t allow to create CHM, you need to change it to htmlhelp.xsl:

$ export DOCBOOK_XSL=/usr/share/xml/docbook/stylesheet/docbook-xsl/htmlhelp/htmlhelp.xsl
$ # then
$ make cleanall
$ autoconf
$ ./configure
$ make

After some minutes (always 19 minutes in my case), you obtain all the files and especially a new one in ‘html’ subdirectory ‘htmlhelp.hhp’. You have to provide this file to HTML Help Workshop:

$ wine /home/mikaelkael/.wine/drive_c/htmlhelp/hhc.exe html/htmlhelp.hhp

You obtain the CHM in ‘html’ subdirectory, something like: ‘Zend_Framework_[LANG].chm’. It’s always without any colors or images.

PhD

First step, you need to retrieve PhD and dependencies from Zend sources:

$ cd /path/you/want
$ svn co http://framework.zend.com/svn/framework/build-tools/trunk/build-tools/docs/ build-tools

To update your sources:

$ svn up

Then you have to convert documentation files in Docbook4 to Docbook5:

$ autoconf
$ ./configure
$ make manual.xml
$ xsltproc --xinclude /path/to/build-tools/db4-upgrade.xsl manual.xml > manual-db5.xml

Now you can build the documentation:

/path/to/build-tools/pear/phd -g 'phpdotnet\phd\Highlighter_GeSHi' --xinclude -f zfpackage -d manual-db5.xml

You obtain in less than 1 minute:

[15:20:56 - Indexing] Indexing...
[15:21:00 - Indexing] Indexing done
[15:21:00 - Rendering Style] Running full build
[15:21:00 - Rendering Format] Starting ZF-Package-Chunked-XHTML rendering
[15:21:39 - Rendering Format] Finished rendering

You will find the documentation in ‘output’ subdirectory. With this version, all programlisting are syntax highlighted.

Enhancements

To go further, you can find the scripts I use to generate http://doczf.mikaelkael.fr in GitHub: https://github.com/mikaelkael/zfdocumentor. The are based on xsltproc. I am planning to migrate to PhD because of the time to render a documentation.

Implémentation Glicko2 en PHP 5.3

Glicko2 est le nom d’une méthode de calcul de la valeur de joueurs qui s’affrontent lors de compétition. J’ai eu besoin d’implémenter ce calcul pour un site que j’ai mis en place, j’ai donc naturellement choisi PHP.

Préambule

Glicko2 est le nom d’une méthode de calcul de la valeur de joueurs qui s’affrontent lors de compétition. Pour eux qui connaissent les échecs, l’esprit est le même que le calcul ELO.

Les informations originales correspondant à ce système sont disponibles sur le site de l’auteur Mark E. Glickman.

Le calcul

Chaque joueur démarre avec un niveau de départ (Rating) et une fiabilité de ce niveau (Rating Deviation). Son niveau et sa fiabilité vont évoluer en fonction des joueurs qu’il va rencontrer.

Le code

Le code et les tests associés sont disponibles sur GitHub : http://github.com/mikaelkael/Ranking. Celui-ci est exclusivement destiné à PHP5.3 minimum puisqu’il utilise les espaces de noms.

Le principe

Vous déclarez une partie :

use Mkk\Game\Ranking\Glicko2 as RankingGlicko2;
$game = new RankingGlicko2();

Vous déclarez 2 joueurs :

use Mkk\Game\Player\Glicko2 as PlayerGlicko2;
$player1 = new PlayerGlicko2(array('id' => 1,
                                   'rating' => 1500,
                                   'ratingDeviation' => 350,
                                   'volatility' => 0.06));
$player2 = new PlayerGlicko2(array('id' => 2,
                                   'rating' => 1500,
                                   'ratingDeviation' => 350,
                                   'volatility' => 0.06));

Vous les associez à la partie dans l’ordre vainqueur->perdant donc si le joueur 1 à battu le joueur 2 :

$game->addPlayers(array($player1, $player2));

Ceci est le fonctionnement par défaut. L’interface Mkk\Game\PlayerInterface propose setPosition() et getPosition(). La position par défaut d’un joueur est « null ». Lors de l’utilisation d’addPlayer() ou addPlayers(), la position du joueur est testée. Si elle vaut nulle, la position suivante lui est attribuée.

Si toutefois vous souhaitez forcer une position dans le cas par exemple d’un match nul, vous pouvez faire :

$game->addPlayers(array($player1->setPosition(1),
                        $player2->setPosition(1)));

Ou le faire lors à la construction :

use Mkk\Game\Player\Glicko2 as PlayerGlicko2;
$player1 = new PlayerGlicko2(array('id' => 1,
                                   'rating' => 1500,
                                   'ratingDeviation' => 350,
                                   'volatility' => 0.06,
                                   'position' => 1));

Vous demandez la mise à jour de leur niveau :

$game->updateRanking();

Vous obtenez le nouveau niveau, la nouvelle fiabilité et la nouvelle volatilité en récupérant les joueurs :

$player = $game->getPlayerById(1);
echo $player->getNewRating();
echo $player->getNewRatingDeviation();
echo $player->getNewVolatility();

Comme le fait remarquer eMeRiKa, ces 3 chiffres (incluant la volatilité) sont nécessaires pour le calcul suivant. La volatilité est forte quand les résultats sont erratiques, si les résultats sont constants alors elle est faible.

Quelques exemples

Dans les exemples suivants, j’ai volontairement effacé la volatilité qui alourdit le nombre des informations et qui n’est pas nécessaire à l’établissement de la valeur d’un joueur mais elle est nécessaire à l’établissement de sa variation.

2 joueurs de même niveau avec une fiabilité faible (c’est-à-dire une valeur forte) s’affrontent :

Info Avant Après
Joueur 1 Niveau 1500 1578.8
Fiabilité 200 180.1
Joueur 2 Niveau 1500 1421.2
Fiabilité 200 180.1

2 joueurs de même niveau avec une fiabilité forte (c’est-à-dire une valeur forte) s’affrontent :

Info Avant Après
Joueur 1 Niveau 1500 1507.3
Fiabilité 50 50.5
Joueur 2 Niveau 1500 1492.7
Fiabilité 50 50.5

1 joueur fort bat 1 joueur faible tous les 2 avec fiabilité forte :

Info Avant Après
Joueur 1 Niveau 1800 1800.5
Fiabilité 50 51
Joueur 2 Niveau 1200 1199.5
Fiabilité 50 51

1 joueur faible bat 1 joueur fort tous les 2 avec fiabilité faible :

Info Avant Après
Joueur 1 Niveau 1800 1623.2
Fiabilité 200 195.8
Joueur 2 Niveau 1200 1376.8
Fiabilité 200 195.8

Les autres systèmes

Zend Framework 1.10.x – documentation HTML & CHM

Mis à jour le 31/03/2010 pour la sortie de la version 1.10.3 (HTM, CHM & ZIP associé et documentation API)

Mis à jour le 27/01/2010 pour la sortie de la version 1.10.0 (PDF & ZIP associé)Si vous utilisez Microsoft Internet Explorer sous Windows XP SP2 (ou plus récent) et que vous téléchargez le format CHM, vous devez « Débloquer » le fichier après téléchargement, en cliquant droit sur celui-ci et en sélectionnant le menu « Propriétés ». Ensuite cliquez sur le bouton « Débloquer ». Si vous ne faites pas ceci, vous ne pourrez pas lire le contenu dufichier CHM.

PDF CHM HTML
English
PDF - 9.1 Mo
ZF_1.10.x_EN.pdf (9.1M)
Windows compile help file format - 4.7 Mo
ZF_1.10.x_EN.chm (4.7M)
http://doczf.mikaelkael.fr/1.10/en/
Zip - 5.9 Mo
ZF_1.10.x_EN.pdf.zip (5.9M)
Zip - 4.7 Mo
ZF_1.10.x_EN.chm.zip (4.7M)
Deutsch
PDF - 9.2 Mo
ZF_1.10.x_DE.pdf (9.2M)
Windows compile help file format - 5.2 Mo
ZF_1.10.x_DE.chm (5.2M)
http://doczf.mikaelkael.fr/1.10/de/
Zip - 6.3 Mo
ZF_1.10.x_DE.pdf.zip (6.3M)
Zip - 5.2 Mo
ZF_1.10.x_DE.chm.zip (5.2M)
French
PDF - 9.5 Mo
ZF_1.10.x_FR.pdf (9.5M)
Windows compile help file format - 5 Mo
ZF_1.10.x_FR.chm (5.0M)
http://doczf.mikaelkael.fr/1.10/fr/
Zip - 6.2 Mo
ZF_1.10.x_FR.pdf.zip (6.2M)
Zip - 5 Mo
ZF_1.10.x_FR.chm.zip (5.0M)
Japanese
PDF - 8.2 Mo
ZF_1.10.x_JA.pdf (8.2M)
Windows compile help file format - 5.5 Mo
ZF_1.10.x_JA.chm (5.5M)
http://doczf.mikaelkael.fr/1.10/ja/
Zip - 5.1 Mo
ZF_1.10.x_JA.pdf.zip (5.1M)
Zip - 5.5 Mo
ZF_1.10.x_JA.chm (5.5M)
Portuguese
Windows compile help file format - 4.8 Mo
ZF_1.10.x_PT-BR.chm (4.8M)
http://doczf.mikaelkael.fr/1.10/pt-br/
Zip - 4.8 Mo
ZF_1.10.x_PT-BR.chm.zip (4.8M)
Spanish
Windows compile help file format - 5 Mo
ZF_1.10.x_ES.chm (5.0M)
http://doczf.mikaelkael.fr/1.10/es/
Zip - 5 Mo
ZF_1.10.x_ES.chm.zip (5.0M)

Zend_Barcode – part 1 : using

Zend Framework 1.10 will integrate Zend_Barcode initially called Zend_Image_Barcode in the proposals.

The main difference between this first proposition and Zend_Barcode, it’s the separation between Objects and Renderers. This allowed to write an image generator (Zend_Barcode_Renderer_Image) and a PDF generator (Zend_Barcode_Renderer_Pdf).

This component internally uses a new version of Zend_Validate_Barcode specially rewritten for 1.10 by Thomas (http://www.thomasweidner.com/flatpress/2009/12/17/validating-barcodes/).

The official documentation will of course integrate the examples showing how to use the component but here is some use cases.

1. The image generator file ‘barcode.php’

You can put at the root of your Web server:

<?php
set_include_path('../library');
require_once 'Zend/Barcode.php';
Zend_Barcode::render($_GET['barcodeType'],
                     'image',
                     $_GET,
                     $_GET);

2. A call in your view and… a first error

<img src="barcode.php?barcodeType=code39" />

This will of course give you an image of error:

Because no text is provided.

3. Your first barcode

You obtain it by simply adding the ‘text’ parameter:

<img src="barcode.php?barcodeType=code39&text=ZEND-FRAMEWORK" />

You have your first barcode in 5 lines of code:

4. A better font

If you use the image renderer (based on GD extension) and if you don’t specify a TTF font, the built-in fonts will be used. You can set your own font in the options of the barcode or by global definition:

<?php
set_include_path('../library');
require_once 'Zend/Barcode.php';
Zend_Barcode::setBarcodeFont('../data/fonts/tahoma.ttf');
Zend_Barcode::render($_GET['barcodeType'], 'image', $_GET, $_GET);

You will obtain:

Zend Framework 1.10.x – documentation HTML & CHM

Updated on 2010-03-31 for 1.10.3 release (HTM, CHM & associated ZIP and API Doc)

Updated on 2010-01-27 for 1.10.0 release (PDF & associated ZIP)If you are using Microsoft Internet Explorer under Windows XP SP2 or later and you are going to download in CHM format, you should « unblock » the file after downloading it, by right-clicking on it and selecting the properties menu item. Then click on the ’Unblock’ button. Failing to do this may lead to errors in the visualization of the file, due to a Microsoft bug.

| | PDF | CHM | HTML |
|English||| http://doczf.mikaelkael.fr/1.10/en/ |
| ^|||^|
|Deutsch||| http://doczf.mikaelkael.fr/1.10/de/ |
| ^|||^|
|French||| http://doczf.mikaelkael.fr/1.10/fr/ |
| ^|||^|
|Japanese||| http://doczf.mikaelkael.fr/1.10/ja/ |
| ^|||^|
|Portuguese| || http://doczf.mikaelkael.fr/1.10/pt-br/ |
| ^| ||^|
|Spanish| || http://doczf.mikaelkael.fr/1.10/es/ |
| ^| ||^|

| API DOC CHM | |
|||

Zend_Barcode – partie 1 : utilisation

Zend Framework 1.10 intégrera Zend_Barcode initialement appelé dans les proposals Zend_Image_Barcode.

La différence primordiale entre la première proposition et Zend_Barcode, c’est le découplage entre les objets et les générateurs de rendu. Ceci a permis d’écrire un générateur Image (Zend_Barcode_Renderer_Image) et un générateur PDF (Zend_Barcode_Renderer_Pdf).

Ce composant s’appuie sur une nouvelle version de Zend_Validate_Barcode spécialement réécrit pour la version 1.10 par Thomas (http://www.thomasweidner.com/flatpress/2009/12/17/validating-barcodes/).

La documentation officielle intégrera bien sûr les exemples permettant de faire fonctionner ce composant mais voyons quelques exemples d’utilisations.

1. Le fichier de génération d’image « barcode.php »

Vous le placez à la racine de votre serveur Web :

<?php
set_include_path('../library');
require_once 'Zend/Barcode.php';
Zend_Barcode::render($_GET('barcodeType'), 'image', $_GET, $_GET);

2. Un appel dans votre vue et … une première erreur

<img src="barcode.php?barcodeType=code39" />

Ce qui vous donnera bien sûr une image d’erreur :

Car aucun texte n’a été fourni.

3. Votre premier code-barres

Vous l’obtenez en ajoutant, simplement le paramètre « text » :

<img src="barcode.php?barcodeType=code39&text=ZEND-FRAMEWORK" />

Vous obtenez donc en 5 lignes de code votre premier code-barres:

4. Une police plus attrayante

Si vous utilisez le générateur Image basé sur l’extension GD et que vous ne spécifiez pas de police TTF, les polices internes de GD seront utilisées. Vous pouvez spécifier votre police soit dans les options de génération soit de manière plus globale :

<?php
set_include_path('../library');
require_once 'Zend/Barcode.php';
Zend_Barcode::setBarcodeFont('../data/fonts/tahoma.ttf');
Zend_Barcode::render($_GET('barcodeType'), 'image', $_GET, $_GET);

Vous obtiendrez ainsi :

New website design and online documentation

Updated on 2011-12-24 to include 2.0 release.
Updated on 2010-12-30 to include 1.11 release.

I propose now on my website the online documentation for 1.6, 1.7, 1.8, 1.9, 1.10, 1.11 and 2.0:

Language 1.6 1.7 1.8 1.9 1.10 1.11 2.0
Deutsch See See See See See See
English See See See See See See See
French See See See See See See
Japanese See See See See See See
Portuguese See See
Spanish See See

I choose the main languages that are up-to-date.

It includes: syntax highlighting, extra documentation and a search engine (for each release).

All CHM versions have been reviewed to integrate these functionalities.

Zend Framework 1.9.x – documentation CHM & PDF

Updated on 2009-11-25 for 1.9.6 release (CHM, API documentation & associated ZIP)

Updated on 2009-08-11 for 1.9.1 release (PDF & associated ZIP)Attention for those which use Vista (thanks to Julien for the link).

If you are using Microsoft Internet Explorer under Windows XP SP2 or later and you are going to download in CHM format, you should « unblock » the file after downloading it, by right-clicking on it and selecting the properties menu item. Then click on the ’Unblock’ button. Failing to do this may lead to errors in the visualization of the file, due to a Microsoft bug.

| | PDF | CHM |
|English|||
| ^|||
|Deutsch|||
| ^|||
|Japanese|||
| ^|||
|French|||
| ^|||

| API DOC CHM | |
|||

Breizh Défi

Le Cercle Celtique de Guérande, champion de Bretagne en titre de danse bretonne, organise le plus grand Bal Paludier jamais effectué le 7 août 2009. A l’occasion de cet événement, ils ont lancé un site dédié : http://www.bro-gwenrann.org/breizhdefi/index.php (avec une petite couche de Zend Framework : Zend_Form et Zend_Pdf entre autres).

Mais ils ont surtout lancé une série de teasers, afin de trouver les 2000 danseurs attendus :

N’hésitez pas à les regarder, c’est très bien fait !