<?php /** * Data structures used in parsing XML DocBook-based tutorials * * Conversion of DocBook-based tutorials is performed using special * {@link Converter} class methods. By default, these methods simply retrieve * simple rules for replacement of tags and slight re-ordering from the * options.ini file present for every template. * * In future versions, there may be utilization of xslt or other more powerful * protocols. However, for most situations, the power of these classes will * be more than sufficient to handle very complex documentation. * * Note that an entire tutorial is contained in a single parserXMLDocBookTag, * matching the document model for DocBook. The top-level tag, <refentry>, * contains every other tag and all text. * * phpDocumentor :: automatic documentation generator * * PHP versions 4 and 5 * * Copyright (c) 2002-2008 Gregory Beaver * * 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 * * @category ToolsAndUtilities * @package phpDocumentor * @subpackage Tutorial * @author Gregory Beaver <cellog@php.net> * @copyright 2002-2008 Gregory Beaver * @license http://www.opensource.org/licenses/lgpl-license.php LGPL * @version CVS: $Id: PackagePageElements.inc 253643 2008-02-24 04:27:54Z ashnazg $ * @tutorial tutorials.pkg * @link http://www.phpdoc.org * @link http://pear.php.net/PhpDocumentor * @since 1.2.0 * @todo CS cleanup - change package to PhpDocumentor */ /** * Represents <![CDATA[ ]]> sections. * * These sections are interpreted as plain text * * @category ToolsAndUtilities * @package phpDocumentor * @subpackage Tutorial * @author Gregory Beaver <cellog@php.net> * @copyright 2002-2008 Gregory Beaver * @license http://www.opensource.org/licenses/lgpl-license.php LGPL * @version Release: 1.4.3 * @tutorial tutorials.pkg * @link http://www.phpdoc.org * @link http://pear.php.net/PhpDocumentor * @todo CS cleanup - change package to PhpDocumentor * @todo CS cleanup - change classname to PhpDocumentor_* */ class parserCData extends parserStringWithInlineTags { /** * calls the output conversion * * @param Converter &$c the output converter * @param bool $postprocess if postprocessing is needed * * @return string * @uses Converter::getCData() convert contents to text * @todo CS cleanup - rename to convert for camelCase rule */ function Convert(&$c, $postprocess = true) { $val = $this->value; if ($postprocess) { foreach ($this->value as $key => $value) { if (is_string($value)) { $this->value[$key] = $c->getCData($value); } } } $this->cache = false; $x = parent::Convert($c, false); $this->value = $val; return $x; } } /** * a standard XML DocBook Tag * * This class is designed to represent all DocBook tags. It is intelligent * enough to understand the <title> tag, and also the <refname> tag for * as title for <refentry> * * @category ToolsAndUtilities * @package phpDocumentor * @subpackage Tutorial * @author Gregory Beaver <cellog@php.net> * @copyright 2002-2008 Gregory Beaver * @license http://www.opensource.org/licenses/lgpl-license.php LGPL * @version Release: 1.4.3 * @tutorial tutorials.pkg * @link http://www.phpdoc.org * @link http://pear.php.net/PhpDocumentor * @since 1.2 * @todo CS cleanup - change package to PhpDocumentor * @todo CS cleanup - change classname to PhpDocumentor_* * @todo CS cleanup - rename to parserXmlDocBookTag for camelCase rule */ class parserXMLDocBookTag extends parserStringWithInlineTags { /** * Attributes from the XML tag * * Format: array(attrname => attrvalue, attrname => attrvalue,...) * @var array */ var $attributes = array(); /** * Name of the tag * @var string */ var $name; /**#@+ * @access private */ /** * @var parserCData */ var $_cdata; /** * @var parserTag */ var $_title; /** * @var parserIdLineTag */ var $_id; /** * Set to <refpurpose> in <refsynopsisdiv> * @var parserTag */ var $_description; /**#@-*/ /** * sets up the tag * * @param string $name tag name * * @todo CS cleanup - rename to parserXmlDocBookTag for camelCase rule */ function parserXMLDocBookTag($name) { $this->name = $name; } /** * calls the output conversion * * @param Converter &$c the output converter * @param bool $postprocess if postprocessing is needed * * @return string * @uses Converter::TranslateTag() Calls this to enclose the contents of the * DocBook tag based on the values in template options.ini file */ function Convert(&$c, $postprocess = true) { $value = parent::Convert($c, $postprocess); $simvalue = parent::Convert($c, false); foreach ($this->attributes as $a => $v) { $this->attributes[$a] = (is_string($v) ? $v : $v->Convert($c, $postprocess)); } if (isset($this->_title)) { list($this->attributes,$value) = $c->ConvertTitle($this->name, $this->attributes, $this->_title->Convert($c, $postprocess), $value); } return $c->TranslateTag($this->name, $this->attributes, $value, $simvalue); } /** * Begin a new CData section * * @return void * @see addCData() */ function startCData() { $this->_cdata = new parserCData; } /** * Adds {@link $_cdata} to {@link $value} * * @return void */ function endCData() { $this->value[] = $this->_cdata; unset($this->_cdata); } /** * Retrieve either the table of contents index, * or the location that the TOC will go * * @param false|integer $state either an index of the {@}toc} tag in $this->value * or false, if the next index value of $this->value * is needed * * @return int * @see setTOC() */ function getTOC($state = false) { if ($state !== false) { return $this->value[$state]; } return count($this->value); } /** * sets the TOC value * * @param integer $state index of the TOC in $this->value * @param parserTocInlineTag $val tag value * * @return void */ function setTOC($state, $val) { $this->value[$state] = $val; } /** * add a word to CData * * @param string $word word to add * * @return void */ function addCData($word) { $this->_cdata->add($word); } /** * Add an xml tag attribute name="value" pair * * if the attribute is id, value must be a {@link parserIdInlineTag} * * @param string $name attribute name * @param string|parserIdInlineTag $value value of attribute * * @return void */ function addAttribute($name, $value) { $this->attributes[$name] = $value; if ($name == 'id') { // fix 1153593 if (is_string($value)) { addWarning(PDERROR_ID_MUST_BE_INLINE, $this->name, $value, $this->name, $value); } else { $this->setId($value); } } } /** * Set the title of a DocBook tag section. * * For most DocBook tags, the title is represented with a <title></title> * tag pair. The <refentry> top-level tag is a little different. Instead * of using <title></title>, phpDocumentor uses the contents of the * <refname> tag in the <refnamediv> tag * * @param parserXMLDocBookTag $title the title element * * @return void */ function setTitle($title) { $this->_title = $title; } /** * If the id attribute is present, this method will set its id * * @param parserIdInlineTag $id the id value * * @return void */ function setId($id) { $this->_id = $id; } /** * Return converter-specific formatting of ID. * * Passes $c to {@link parserIdInlineTag::Convert()} * * @param Converter &$c the output converter * * @return string */ function getId(&$c) { if ($this->_id) { return trim($this->_id->Convert($c)); } } /** * Determine whether the docbook element has a title * * @return boolean */ function hasTitle() { return isset($this->_title); } /** * Retrieve Converter-specific formatting of the title of this element * * @param Converter &$c the output converter * * @return string */ function getTitle(&$c) { if ($this->name == 'refentry') { foreach ($this->value as $tag) { if (is_object($tag) && $tag->name == 'refnamediv') { return $tag->getTitle($c); } } } if ($this->name == 'refnamediv') { foreach ($this->value as $tag) { if (is_object($tag) && is_a($tag, 'parserXMLDocBookTag') && $tag->name == 'refname') { $t = new parserStringWithInlineTags; foreach ($tag->value as $val) { $t->add($val); } $this->_title = $t; } if (is_object($tag) && is_a($tag, 'parserXMLDocBookTag') && $tag->name == 'refpurpose') { $t = new parserStringWithInlineTags; foreach ($tag->value as $val) { $t->add($val); } $this->_description = $t; } } } if (isset($this->_title)) { return $this->_title->Convert($c); } if (is_object($this->value[0]) && is_a($tag, 'parserXMLDocBookTag')) { return $this->value[0]->getTitle($c); } if (isset($this->value[1])) { if (is_object($this->value[1]) && is_a($tag, 'parserXMLDocBookTag')) { return $this->value[1]->getTitle($c); } } return ''; } /** * Retrieve the contents of a subsection * * This method uses the $_id members of nested docbook tags to retrieve * the section defined by $subsection * * @param Converter &$c the output converter * @param string $subsection converter-specific subsection * * @return bool|string */ function getSubsection(&$c, $subsection) { if (!is_object($this->_id)) { return false; } $search = phpDocumentor_clone($this->_id); if (is_string($this->_id)) { return false; } if (phpDocumentor_get_class($search) != 'parseridinlinetag') { return false; } $search->id = $subsection; foreach ($this->value as $el) { if (phpDocumentor_get_class($el) == 'parserxmldocbooktag') { if ($el->getId($c) == $search->Convert($c)) { return $el; } elseif ($a = $el->getSubsection($c, $subsection)) { return $a; } } } return false; } /** * Add contents to this tag. * * There are four kinds of data in a DocBook tutorial: * 1. <b>tags</b> - normal tags like <refentry> * 2. <b>entities</b> - normal entities like ” * 3. <b><![CDATA[</b> - character data that should not be interpreted, * like <programlisting> contents * 4. <b>text</b> - normal non-markup text * * All four kinds of data are added here * * @param parserEntity|parserCData|parserXMLDocBookTag|string $el nested tag, * entity, or text * * @return mixed */ function add($el) { if (is_string($el)) { return parent::add($el); } if (phpDocumentor_get_class($el) == 'parserxmldocbooktag') { if ($el->name == 'title') { $this->setTitle($el); } else { return parent::add($el); } } else { return parent::add($el); } } } /** * a standard entity like ” * * This class is designed to represent all DocBook entities. * * @category ToolsAndUtilities * @package phpDocumentor * @subpackage Tutorial * @author Gregory Beaver <cellog@php.net> * @copyright 2002-2008 Gregory Beaver * @license http://www.opensource.org/licenses/lgpl-license.php LGPL * @version Release: 1.4.3 * @tutorial tutorials.pkg * @link http://www.phpdoc.org * @link http://pear.php.net/PhpDocumentor * @since 1.2 * @todo CS cleanup - change package to PhpDocumentor * @todo CS cleanup - change classname to PhpDocumentor_* */ class parserEntity { /** * sets up the entity * * @param string $name entity name */ function parserEntity($name) { $this->value = $name; } /** * calls the output conversion * * @param Converter &$c the output converter * @param bool $postprocess if postprocessing is needed * * @return string * @uses Converter::TranslateEntity() convert contents to text * @todo CS cleanup - rename to convert for camelCase rule */ function Convert(&$c, $postprocess = true) { if ($postprocess) { return $c->TranslateEntity($this->value); } else { $trans_tbl = get_html_translation_table(HTML_ENTITIES); $trans_tbl = array_flip($trans_tbl); $ret = strtr('&'.$this->value.';', $trans_tbl); return $ret; } } } ?>