Source for file CHMdefaultConverter.inc

Documentation is available at CHMdefaultConverter.inc

<?php
/**
* CHM (Compiled Help Manual) output converter for Smarty Template.
*
* phpDocumentor :: automatic documentation generator
*
* PHP versions 4 and 5
*
*
* LICENSE:
*
* This library is free software; you can redistribute it
* and/or modify it under the terms of the GNU Lesser General
* Public License as published by the Free Software Foundation;
* either version 2.1 of the License, or (at your option) any
* later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*
* @package Converters
* @subpackage CHMdefault
* @author Joshua Eichorn <jeichorn@phpdoc.org>
* @author Greg Beaver <cellog@php.net>
* @license http://www.opensource.org/licenses/lgpl-license.php LGPL
* @version CVS: $Id: CHMdefaultConverter.inc,v 1.12 2007/04/19 20:20:57 ashnazg Exp $
* @filesource
* @link http://www.phpdoc.org
* @link http://pear.php.net/PhpDocumentor
* @since 1.0rc1
*/
/**
* Generates files that MS HTML Help Worshop can use to create a MS Windows
* compiled help file (CHM)
*
* The free MS HTML Help compiler takes the project file (phpdoc.hhp) and reads
* the table of contents file specified in the project (which is always contents.hhc
* in phpDocumentor). When the converter reaches stable state, it will also
* output an index file index.hhk. The free download for MS HTML Help Workshop
* is available below
* @link http://www.microsoft.com/downloads/release.asp?releaseid=33071 MS HTML Help Workshop download
* @package Converters
* @subpackage CHMdefault
* @author Greg Beaver <cellog@php.net>
* @since 1.0rc1
* @version $Revision: 1.12 $
*/
class CHMdefaultConverter extends Converter
{
/**
* CHMdefaultConverter wants elements sorted by type as well as alphabetically
* @see Converter::$sort_page_contents_by_type
* @var boolean
*/
var $sort_page_contents_by_type = true;
/** @var string */
var $outputformat = 'CHM';
/** @var string */
var $name = 'default';
/**
* indexes of elements by package that need to be generated
* @var array
*/
var $leftindex = array('classes' => true, 'pages' => true, 'functions' => true, 'defines' => false, 'globals' => false);
/**
* output directory for the current procedural page being processed
* @var string
*/
var $page_dir;
/**
* target directory passed on the command-line.
* {@link $targetDir} is malleable, always adding package/ and package/subpackage/ subdirectories onto it.
* @var string
*/
var $base_dir;
/**
* output directory for the current class being processed
* @var string
*/
var $class_dir;
/**
* array of converted package page names.
* Used to link to the package page in the left index
* @var array Format: array(package => 1)
*/
var $package_pages = array();
/**
* controls formatting of parser informative output
*
* Converter prints:
* "Converting /path/to/file.php... Procedural Page Elements... Classes..."
* Since CHMdefaultConverter outputs files while converting, it needs to send a \n to start a new line. However, if there
* is more than one class, output is messy, with multiple \n's just between class file output. This variable prevents that
* and is purely cosmetic
* @var boolean
*/
var $juststarted = false;
/**
* contains all of the template procedural page element loop data needed for the current template
* @var array
*/
var $current;
/**
* contains all of the template class element loop data needed for the current template
* @var array
*/
var $currentclass;
var $wrote = false;
var $ric_set = array();
/**
* Table of Contents entry for index.hhk
* @var array
*/
var $KLinks = array();
/**
* sets {@link $base_dir} to $targetDir
* @see Converter()
*/
function CHMdefaultConverter(&$allp, &$packp, &$classes, &$procpages, $po, $pp, $qm, $targetDir, $templateDir, $title)
{
Converter::Converter($allp, $packp, $classes, $procpages,$po, $pp, $qm, $targetDir, $templateDir, $title);
$this->base_dir = $targetDir;
}
/**
* @deprecated in favor of PHP 4.3.0+ tokenizer-based source highlighting
*/
function unmangle($sourcecode)
{
$sourcecode = str_replace('<code>','<pre>',$sourcecode);
$sourcecode = str_replace('</code>','</pre>',$sourcecode);
$sourcecode = str_replace('<br />',"\n",$sourcecode);
$sourcecode = str_replace(' ',' ',$sourcecode);
$sourcecode = str_replace('<','<',$sourcecode);
$sourcecode = str_replace('>','>',$sourcecode);
$sourcecode = str_replace('&','&',$sourcecode);
return $sourcecode;
}
/**
* @param string full path to the source file
* @param string fully highlighted source code
*/
function writeSource($path, $value)
{
$templ = &$this->newSmarty();
$pathinfo = $this->proceduralpages->getPathInfo($path, $this);
$templ->assign('source',$value);
$templ->assign('package',$pathinfo['package']);
$templ->assign('subpackage',$pathinfo['subpackage']);
$templ->assign('name',$pathinfo['name']);
$templ->assign('source_loc',$pathinfo['source_loc']);
$templ->assign('docs',$pathinfo['docs']);
$templ->assign("subdir",'../');
$templ->register_outputfilter('CHMdefault_outputfilter');
$this->setTargetDir($this->getFileSourcePath($this->base_dir));
$this->addSourceTOC($pathinfo['name'],$this->getFileSourceName($path),$pathinfo['package'],$pathinfo['subpackage'], true);
phpDocumentor_out("\n");
$this->setSourcePaths($path);
$this->writefile($this->getFileSourceName($path).'.html',$templ->fetch('filesource.tpl'));
}
function writeExample($title, $path, $source)
{
$templ = &$this->newSmarty();
$templ->assign('source',$source);
if (empty($title))
{
$title = 'example';
addWarning(PDERROR_EMPTY_EXAMPLE_TITLE, $path, $title);
}
$templ->assign('title',$title);
$templ->assign('file',$path);
$templ->assign("subdir",'../');
$templ->register_outputfilter('CHMdefault_outputfilter');
$pathinfo = $this->proceduralpages->getPathInfo($path, $this);
$this->setTargetDir($this->base_dir . PATH_DELIMITER . '__examplesource');
$this->addSourceTOC($title,'exsource_'.$path,$pathinfo['package'],$pathinfo['subpackage'], false);
phpDocumentor_out("\n");
$this->writefile('exsource_'.$path.'.html',$templ->fetch('examplesource.tpl'));
}
function getExampleLink($path, $title)
{
return $this->returnLink('../__examplesource' . PATH_DELIMITER . 'exsource_'.$path.'.html',$title);
}
function getSourceLink($path)
{
return $this->returnLink('../__filesource/' .
$this->getFileSourceName($path).'.html','Source Code for this file');
}
/**
* Retrieve a Converter-specific anchor to a segment of a source code file
* parsed via a {@tutorial tags.filesource.pkg} tag.
* @param string full path to source file
* @param string name of anchor
* @param string link text, if this is a link
* @param boolean returns either a link or a destination based on this
* parameter
* @return string link to an anchor, or the anchor
*/
function getSourceAnchor($sourcefile,$anchor,$text = '',$link = false)
{
if ($link) {
return $this->returnLink('../__filesource/' .
$this->getFileSourceName($sourcefile) . '.html#a' . $anchor, $text);
} else {
return '<a name="a'.$anchor.'"></a>';
}
}
/**
* Return a line of highlighted source code with formatted line number
*
* If the $path is a full path, then an anchor to the line number will be
* added as well
* @param integer line number
* @param string highlighted source code line
* @param false|stringfull path to @filesource file this line is a part of,
* if this is a single line from a complete file.
* @return string formatted source code line with line number
*/
function sourceLine($linenumber, $line, $path = false)
{
$extra = '';
if (strlen(str_replace("\n", '', $line)) == 0) {
$extra = ' ';
}
if ($path)
{
return '<li><div class="src-line">' . $this->getSourceAnchor($path, $linenumber) .
str_replace("\n",'',$line) . $extra .
"</div></li>\n";
} else
{
return '<li><div class="src-line">' . str_replace("\n",'',$line) .
"$extra</div></li>\n";
}
}
/**
* Used to convert the <<code>> tag in a docblock
* @param string
* @param boolean
* @return string
*/
function ProgramExample($example, $tutorial = false, $inlinesourceparse = null/*false*/,
$class = null/*false*/, $linenum = null/*false*/, $filesourcepath = null/*false*/)
{
return $this->PreserveWhiteSpace(parent::ProgramExample($example, $tutorial, $inlinesourceparse, $class, $linenum, $filesourcepath));
}
/**
* @param string
*/
function TutorialExample($example)
{
$trans = $this->template_options['desctranslate'];
$this->template_options['desctranslate'] = array();
$example = '<ol>' . parent::TutorialExample($example)
.'</ol>';
$this->template_options['desctranslate'] = $trans;
if (!isset($this->template_options['desctranslate'])) return $example;
if (!isset($this->template_options['desctranslate']['code'])) return $example;
$example = $this->template_options['desctranslate']['code'] . $example;
if (!isset($this->template_options['desctranslate']['/code'])) return $example;
return $example . $this->template_options['desctranslate']['/code'];
}
function getCurrentPageLink()
{
return $this->curname . '.html';
}
/**
* Uses htmlspecialchars() on the input
*/
function postProcess($text)
{
if ($this->highlightingSource) {
return str_replace(array(' ',"\t"), array(' ', '   '),
htmlspecialchars($text));
}
return htmlspecialchars($text);
}
/**
* Use the template tutorial_toc.tpl to generate a table of contents for HTML
* @return string table of contents formatted for use in the current output format
* @param array format: array(array('tagname' => section, 'link' => returnsee link, 'id' => anchor name, 'title' => from title tag),...)
*/
function formatTutorialTOC($toc)
{
$template = &$this->newSmarty();
$template->assign('toc',$toc);
return $template->fetch('tutorial_toc.tpl');
}
function &SmartyInit(&$templ)
{
if (!isset($this->package_index))
foreach($this->all_packages as $key => $val)
{
if (isset($this->pkg_elements[$key]))
{
if (!isset($start)) $start = $key;
$this->package_index[] = array('link' => "li_$key.html", 'title' => $key);
}
}
$templ->assign("packageindex",$this->package_index);
$templ->assign("subdir",'');
return $templ;
}
/**
* Writes out the template file of {@link $class_data} and unsets the template to save memory
* @see registerCurrentClass()
* @see parent::endClass()
*/
function endClass()
{
$a = '../';
if (!empty($this->subpackage)) $a .= '../';
if ($this->juststarted)
{
$this->juststarted = false;
phpDocumentor_out("\n");
flush();
}
$this->setTargetDir($this->base_dir . PATH_DELIMITER . $this->class_dir);
$this->class_data->assign("subdir",$a);
$this->class_data->register_outputfilter('CHMdefault_outputfilter');
$this->addTOC($this->class,$this->class,$this->package,$this->subpackage, true);
$this->writefile($this->class . '.html',$this->class_data->fetch('class.tpl'));
unset($this->class_data);
}
/**
* Writes out the template file of {@link $page_data} and unsets the template to save memory
* @see registerCurrent()
* @see parent::endPage()
*/
function endPage()
{
$this->package = $this->curpage->package;
$this->subpackage = $this->curpage->subpackage;
$a = '../';
if (!empty($this->subpackage)) $a .= '../';
$this->setTargetDir($this->base_dir . PATH_DELIMITER . $this->page_dir);
$this->page_data->assign("package",$this->package);
$this->page_data->assign("subdir",$a);
$this->page_data->register_outputfilter('CHMdefault_outputfilter');
$this->addTOC($this->curpage->file,$this->page,$this->package,$this->subpackage);
$this->writefile($this->page . '.html',$this->page_data->fetch('page.tpl'));
unset($this->page_data);
}
/**
* @param string
* @param string
* @return string <a href="'.$link.'">'.$text.'</a>
*/
function returnLink($link,$text)
{
return '<a href="'.$link.'">'.$text.'</a>';
}
/**
* CHMdefaultConverter chooses to format both package indexes and the complete index here
*
* This function formats output for the elementindex.html and pkgelementindex.html template files. It then
* writes them to the target directory
* @see generateElementIndex(), generatePkgElementIndex()
*/
function formatPkgIndex()
{
list($package_indexes,$packages,$mletters) = $this->generatePkgElementIndexes();
for($i=0;$i<count($package_indexes);$i++)
{
$template = &$this->newSmarty();
$this->package = $package_indexes[$i]['package'];
$this->subpackage = '';
$template->assign("index",$package_indexes[$i]['pindex']);
$template->assign("package",$package_indexes[$i]['package']);
$template->assign("letters",$mletters[$package_indexes[$i]['package']]);
$template->assign("title","Package ".$package_indexes[$i]['package']." Element Index");
$template->assign("subdir",'../');
$template->register_outputfilter('CHMdefault_outputfilter');
$this->setTargetDir($this->base_dir . PATH_DELIMITER . $package_indexes[$i]['package']);
$this->addTOC($package_indexes[$i]['package']." Alphabetical Index",'elementindex_'.$package_indexes[$i]['package'],$package_indexes[$i]['package'],'');
$this->writefile('elementindex_'.$package_indexes[$i]['package'].'.html',$template->fetch('pkgelementindex.tpl'));
}
phpDocumentor_out("\n");
flush();
}
/**
* CHMdefaultConverter uses this function to format template index.html and packages.html
*
* This function generates the package list from {@link $all_packages}, eliminating any
* packages that don't have any entries in their package index (no files at all, due to @ignore
* or other factors). Then it uses the default package name as the first package index to display.
* It sets the right pane to be either a blank file with instructions on making package-level docs,
* or the package-level docs for the default package.
* @global string Used to set the starting package to display
*/
function formatIndex()
{
global $phpDocumentor_DefaultPackageName;
list($elindex,$mletters) = $this->generateElementIndex();
$template = &$this->newSmarty();
$template->assign("index",$elindex);
$template->assign("letters",$mletters);
$template->assign("title","Element Index");
$template->assign("date",date("r",time()));
$template->register_outputfilter('CHMdefault_outputfilter');
phpDocumentor_out("\n");
flush();
$this->setTargetDir($this->base_dir);
$this->addTOC("Alphabetical Index Of All Elements",'elementindex',"Index",'');
$this->writefile('elementindex.html',$template->fetch('elementindex.tpl'));
usort($this->package_index,"CHMdefault_pindexcmp");
$index = &$this->newSmarty();
foreach($this->all_packages as $key => $val)