diff options
Diffstat (limited to 'buildscripts/PhpDocumentor/phpDocumentor/PackagePageElements.inc')
| -rwxr-xr-x | buildscripts/PhpDocumentor/phpDocumentor/PackagePageElements.inc | 513 |
1 files changed, 513 insertions, 0 deletions
diff --git a/buildscripts/PhpDocumentor/phpDocumentor/PackagePageElements.inc b/buildscripts/PhpDocumentor/phpDocumentor/PackagePageElements.inc new file mode 100755 index 00000000..24e991ee --- /dev/null +++ b/buildscripts/PhpDocumentor/phpDocumentor/PackagePageElements.inc @@ -0,0 +1,513 @@ +<?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; + } + } +} +?> |