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

Zend Framework 1.8.x – documentation CHM & PDF

Updated on 2009-05-17 for 1.8.1 release.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|||
| ^|||

Zend Framework CHM Compilation

Preparation

- Get last version of Zend Framework
- Follow installation’s intructions of this page
- I take example of english documentation, so all my link will refer to the english, you have to adapt for your preferred language.

Docbook to HTML

I make some modifications in the configuration file (‘manual/en/html.xsl.in’):

    <!-- Adding these lines-->
    <xsl:param name="suppress.navigation" select="0"/>
    <xsl:param name="chapter.autolabel" select="0" />
    <xsl:param name="navig.graphics" select="1" />
    <xsl:param name="navig.graphics.extension" select="'.png'" />
    <xsl:param name="navig.graphics.path">images/

The goal is to activate navigation with images at the top and the bottom of each page.
I also delete the prepend term ‘Chapter’. You need to put in ‘manual/en/html/images/’ this 9 images:

  • home: (http://www.mikaelkael.fr/dwld/home.png)
  • up: (http://www.mikaelkael.fr/dwld/up.png)
  • prev: (http://www.mikaelkael.fr/dwld/prev.png)
  • next: (http://www.mikaelkael.fr/dwld/next.png)
  • note: (http://www.mikaelkael.fr/dwld/note.png)
  • warning: (http://www.mikaelkael.fr/dwld/warning.png)
  • important: (http://www.mikaelkael.fr/dwld/important.png)
  • caution: (http://www.mikaelkael.fr/dwld/caution.png)
  • tip: (http://www.mikaelkael.fr/dwld/tip.png)

Furthermore, the created HTML pages link images in the directory ‘manual/en/html/modules_specs/figures/*’ instead of ‘manual/en/html/figures/*’. So you need to create the directory and copy the images into.

On the same point, under Windows, at the end of the HTML generation there is a copy of the directory ‘manual/en/modules_specs/figures/*’ to ‘manual/en/html/figures/*’. This create an unreachable directory ‘figures’. So I modify ‘manual/en/Makefile.in’:

# In html/index.html:
	@echo "Copying manual figures (recursively)..."
	-[ -d figures ] && cp figures/*.* html/module_specs/figures
    # instead of
	@echo "Copying manual figures (recursively)..."
	-[ -d figures ] && cp -r figures html/figures
# In clean:
	-rm -f html/module_specs/figures/*
    # instead of
	-rm -Rf html/figures

CSS enhancements

The purpose is to resemble the official site:
colour of link (#009EEB)

These are the modifications made in ‘manual/en/html/dbstyle.css’:

body {
	background: url("images/bkg_top.gif") repeat-x;
	margin: 6px 15px;
}
a {
	color:#009EEB;
}
h1 {
	margin: 0;
}
div.note, div.warning, div.tip {
	/*border: solid 1px green;*/
	background-color: #EEEEEE;
}
div.note img, div.warning img, div.tip img {
	/*border: solid 1px green;*/
}
pre.programlisting {
	border: 1px solid #D3E0EB;
	background-color: #EDF7FF;
}
div.navheader {
	/*border-bottom: solid 1px black;
	border-color: #aaa;*/
}
div.navfooter td {
	font-size: 0.80em;
}
a img {
	border: 0px;
}
div.navheader table {
	background: 50px 12px url("./images/logo_small.gif") no-repeat;
	page-break-before: always;
}
div.navheader img {
    position: relative;
	top: -14px;
}
div.table {
	text-align: center;
}
table {
	border: 0;
	border-collapse: collapse;
	margin: auto;
}
th {
	border-collapse: collapse;
	color: #444444;
}
td {
	border-collapse: collapse;
	color: #444444;
}
div.table th, div.table td {
	border: 1px solid #444444;
	font-size: 0.85em;
}
div.table th {
	background: #DDDDDD;
}
div.table p.title {
	font-size: 0.75em;
	margin-bottom: 0px
}

Tip: CSS in CHM

Problem with background image, they must be in html content with ‘<img>’ tag to be compile in CHM. See below.
no padding

Syntax highlighting PHP code

This is a PHP script which highlight the code after rendering HTML (« make » or « make -e ») and before CHM compilation. I create a dir ‘tools’ in my language dir (‘manual/en/tools’) and I put this script inside:

/**
 * Zend Framework
 *
 * LICENSE
 *
 * This source file is subject to the new BSD license that is bundled
 * with this package in the file LICENSE.txt.
 * It is also available through the world-wide-web at this URL:
 * http://framework.zend.com/license/new-bsd
 * If you did not receive a copy of the license and are unable to
 * obtain it through the world-wide-web, please send an email
 * to license@zend.com so we can send you a copy immediately.
 *
 * @category   Documentation
 * @copyright  Copyright (c) 2005-2008 Zend Technologies USA Inc. (http://www.zend.com)
 * @license    http://framework.zend.com/license/new-bsd     New BSD License
 * @version    $Id$
 */

/**
 * Run this code:
 *  - after HTML compilation ("make" or "make -e")
 *  - before CHM compilation ("C:/path/to/workshop/hhc htmlhelp.hhp")
 */

function highlight ($text)
{
    $code = $text{(2)};
    // Replace element create by html compilation
    $code = str_replace(array('&gt;' , '&lt;'), array('>' , ' all \n will create a new line, but we already have some
    $code = str_replace("\n", '', $code);
    // In English manual, there is space between })> and , we remode it
    $code = preg_replace('/(<br \/>)(\&nbsp\;)*(<\/span><\/code>)/', '$3', $code);
    $code = preg_replace('/(<br \/>)(\&nbsp\;)*(<\/span><\/code>)/', '$3', $code);
    return $text{(1)} . $code . $text{(3)};
}

class HTML_Filter extends FilterIterator
{

    public function accept ()
    {
        return (substr($this->current(), - 5) == '.html');
    }
}

$dir = new DirectoryIterator(dirname(__FILE__) . '/../html');
$filter = new HTML_Filter($dir);
foreach ($filter as $file) {
    $text = file_get_contents($file->getPathName());
    $text = preg_replace_callback('/(<pre class="programlisting">)(.*?)(<\/pre>)/s', 'highlight', $text);
    file_put_contents($file->getPathName(), $text);
}

CHM Compilation

You need to install HTML Help Workshop. You just call ‘C:/path/to/workshop/hhc’ on ‘manual/en/html/htmlhelp.hhp’.

Since background images aren’t import in CHM, we need to declare them like real images in HTML stream. There is 2 possibilities:
* the bad one, insert images in xml document like this:

<!-- for example in 'manual/en/refs/installation.xml' -->
<para>
<inlinegraphic align="center" fileref="../images/bkg_top.gif" format="PNG" scale="1" width="1" />
<inlinegraphic align="center" fileref="../images/logo_small.gif" format="PNG" scale="1" width="1" />
</para>

This result of an image of 1×1. I think it’s bad solution because the actual problem is HTML Help Workshop which omit to insert images only declared in css. (!!! Please note that I haven’t really test this modification !!!).

the other one, a modification of the highlight script to insert this line in the rendered ‘index.html’:

<!-- Before the ending tag body -->
<img src="images/bkg_top.gif" height="1" />
<img src="images/logo_small.gif" height="1" width="1" />

Other

Insert the version of ZF documentation (1.6.x) and why not SVN revision in ‘manual/en/manual.xml.in’:

/**
 * Zend Framework
 *
 * LICENSE
 *
 * This source file is subject to the new BSD license that is bundled
 * with this package in the file LICENSE.txt.
 * It is also available through the world-wide-web at this URL:
 * http://framework.zend.com/license/new-bsd
 * If you did not receive a copy of the license and are unable to
 * obtain it through the world-wide-web, please send an email
 * to license@zend.com so we can send you a copy immediately.
 *
 * @category   Documentation
 * @copyright  Copyright (c) 2005-2008 Zend Technologies USA Inc. (http://www.zend.com)
 * @license    http://framework.zend.com/license/new-bsd     New BSD License
 * @version    $Id$
 */

/**
 * Run this code:
 *  - after HTML compilation ("make" or "make -e")
 *  - before CHM compilation ("C:/path/to/workshop/hhc htmlhelp.hhp")
 */

define('WITH_ZF_VERSION', true);
define('WITH_SVN_VERSION', true);
define('UPDATE_LINK',
       'http://mikaelkael.fr/index.php?post/2008/08/21/Zend-Framework-CHM-Francais');

/**
 * Highlight a string
 */
function highlight ($text)
{
    $code = $text{(2)};
    // Replace element create by html compilation
    $code = str_replace(array('&gt;' , '&lt;'), array('>' , ' all \n will create a new line, but we already have some
    $code = str_replace("\n", '', $code);
    // In English manual, there is spaces between })> and, we remode it
    $code = preg_replace('/(<br \/>)(\&nbsp\;)*(<\/span><\/code>)/', '$3', $code);
    $code = preg_replace('/(<br \/>)(\&nbsp\;)*(<\/span><\/span><\/code>)/', '$3', $code);
    return $text{(1)} . $code . $text{(3)};
}

class HTML_Filter extends FilterIterator
{

    public function accept ()
    {
        return (substr($this->current(), - 5) == '.html');
    }
}

/**
 * Highlight all HTML files
 */
$dir = new DirectoryIterator(dirname(__FILE__) . '/../html');
$filter = new HTML_Filter($dir);
foreach ($filter as $file) {
    $text = file_get_contents($file->getPathName());
    $text = preg_replace_callback('/(<pre class="programlisting">)(.*?)(<\/pre>)/s',
                                  'highlight',
                                  $text);
    file_put_contents($file->getPathName(), $text);
}

/**
 * Retrieve ZF version
 * (assume that all trunk tree is available)
 */
$page_title = 'Zend Framework';
if (WITH_ZF_VERSION == true) {
    require_once dirname(__FILE__) . '/../../../../library/Zend/Version.php';
    $version = implode('.', array_slice(explode('.', Zend_Version::VERSION), 0, 2)) . '.x';
    $page_title .=  " $version";
}
/**
 * Retrieve SVN revision
 */
if (WITH_SVN_VERSION == true) {
    putenv('LANG=en_US.UTF-8');
    exec("svn info " . realpath(dirname(__FILE__) . '/..'), $svn_info);
    foreach ($svn_info as $info) {
        if (substr($info, 0, 9) == 'Revision:') {
            $svn = (int) substr($info, 10);
        }
    }
    $page_title .=  " (SVN $svn)";
}
/**
 * Modify index.html
 */
$index = file_get_contents(dirname(__FILE__) . '/../html/index.html');
$index = str_replace('<h2>Zend Framework</h2>',
                     "<h2 class=\"subtitle\">$page_title</h2>",
                     $index);
$index = preg_replace('#(<p class\="pubdate"\>)(.*?)(<\/p>)#',
        '$1Compilé le $2 (<a href="' . UPDATE_LINK . '">mise à jour</a>)$3',
        $index);
$index = str_replace('</body>',
                     '<img src="images/bkg_top.gif" height="1" />'
                   . PHP_EOL
                   . '<img src="images/logo_small.gif" height="1" width="1" />'
                   . PHP_EOL
                   . '</body>',
                     $index);
file_put_contents(dirname(__FILE__) . '/../html/index.html', $index);
/**
 * Make CHM
 */
exec('hhc ' . dirname(__FILE__) . '/../html/htmlhelp.hhp');

Result

See result!

Bugs

  • If you are using Microsoft Internet Explorer under Windows XP SP2 or later and you are going to download the documentation 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.
  • If you are using Microsoft Internet Explorer under Windows Vista: see this.

Zend Framework 1.7.x – documentation CHM & PDF

Updated on 2008-12-24 for 1.7.2 release.
No update for 1.7.3 release.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 |
|Français|||
| ^|||
|English|||
| ^|||
|Deutsch|||
| ^|||
|日本語|||
| ^|||