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('>' , '<'), 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 \/>)(\ \;)*(<\/span><\/code>)/', '$3', $code);
$code = preg_replace('/(<br \/>)(\ \;)*(<\/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('>' , '<'), 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 \/>)(\ \;)*(<\/span><\/code>)/', '$3', $code);
$code = preg_replace('/(<br \/>)(\ \;)*(<\/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
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.