phpDocumentor phpDocumentor
Tutorial
[ class tree: phpDocumentor ] [ index: phpDocumentor ] [ all elements ]

Source for file PackagePageElements.inc

Documentation is available at PackagePageElements.inc

  1. <?php
  2. /**
  3.  * Data structures used in parsing XML DocBook-based tutorials
  4.  *
  5.  * Conversion of DocBook-based tutorials is performed using special
  6.  * {@link Converter} class methods.  By default, these methods simply retrieve
  7.  * simple rules for replacement of tags and slight re-ordering from the
  8.  * options.ini file present for every template.
  9.  *
  10.  * In future versions, there may be utilization of xslt or other more powerful
  11.  * protocols.  However, for most situations, the power of these classes will
  12.  * be more than sufficient to handle very complex documentation.
  13.  *
  14.  * Note that an entire tutorial is contained in a single parserXMLDocBookTag,
  15.  * matching the document model for DocBook.  The top-level tag, <refentry>,
  16.  * contains every other tag and all text.
  17.  * 
  18.  * phpDocumentor :: automatic documentation generator
  19.  * 
  20.  * PHP versions 4 and 5
  21.  *
  22.  * Copyright (c) 2002-2006 Gregory Beaver
  23.  * 
  24.  * LICENSE:
  25.  * 
  26.  * This library is free software; you can redistribute it
  27.  * and/or modify it under the terms of the GNU Lesser General
  28.  * Public License as published by the Free Software Foundation;
  29.  * either version 2.1 of the License, or (at your option) any
  30.  * later version.
  31.  * 
  32.  * This library is distributed in the hope that it will be useful,
  33.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  34.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  35.  * Lesser General Public License for more details.
  36.  * 
  37.  * You should have received a copy of the GNU Lesser General Public
  38.  * License along with this library; if not, write to the Free Software
  39.  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
  40.  *
  41.  * @package    phpDocumentor
  42.  * @subpackage Tutorial
  43.  * @author     Gregory Beaver <cellog@php.net>
  44.  * @copyright  2002-2006 Gregory Beaver
  45.  * @license    http://www.opensource.org/licenses/lgpl-license.php LGPL
  46.  * @version    CVS: $Id: PackagePageElements.inc,v 1.4 2006/05/22 01:07:28 cellog Exp $
  47.  * @tutorial tutorials.pkg
  48.  * @link       http://www.phpdoc.org
  49.  * @link       http://pear.php.net/PhpDocumentor
  50.  * @since      1.2.0
  51.  */
  52. /**
  53.  * Represents <![CDATA[ ]]> sections.
  54.  *
  55.  * These sections are interpreted as plain text
  56.  * @package phpDocumentor
  57.  * @subpackage Tutorial
  58.  */
  59. {
  60.     /**
  61.      * @uses Converter::getCData() convert contents to text
  62.      * @param Converter 
  63.      */
  64.     function Convert(&$c$postprocess true)
  65.     {
  66.         $val $this->value;
  67.         if ($postprocess)
  68.         foreach($this->value as $key => $value)
  69.         {
  70.             if (is_string($value)) $this->value[$key$c->getCData($value);
  71.         }
  72.         $this->cache false;
  73.         $x parent::Convert($cfalse);
  74.         $this->value = $val;
  75.         return $x;
  76.     }
  77. }
  78. /**
  79.  * a standard XML DocBook Tag
  80.  *
  81.  * This class is designed to represent all DocBook tags.  It is intelligent
  82.  * enough to understand the <title> tag, and also the <refname> tag for
  83.  * as title for <refentry>
  84.  * @since 1.2
  85.  * @package phpDocumentor
  86.  * @subpackage Tutorial
  87.  */
  88. {
  89.     /**
  90.      * Attributes from the XML tag
  91.      *
  92.      * Format: array(attrname => attrvalue, attrname => attrvalue,...)
  93.      * @var array 
  94.      */
  95.     var $attributes = array();
  96.     /**
  97.      * Name of the tag
  98.      * @var string 
  99.      */
  100.     var $name;
  101.     /**#@+ @access private */
  102.     /** @var parserCData */
  103.     var $_cdata;
  104.     /** @var parserTag */
  105.     var $_title;
  106.     /** @var parserIdLineTag */
  107.     var $_id;
  108.     /**
  109.      * Set to <refpurpose> in <refsynopsisdiv>
  110.      * @var parserTag 
  111.      */
  112.     var $_description;
  113.     /**#@-*/
  114.     /**
  115.      * @param string tag name
  116.      */
  117.     function parserXMLDocBookTag($name)
  118.     {
  119.         $this->name = $name;
  120.     }
  121.     
  122.     /**
  123.      * @param Converter 
  124.      * @param boolean 
  125.      * @uses Converter::TranslateTag() Calls this to enclose the contents of the
  126.      *        DocBook tag based on the values in template options.ini file
  127.      */
  128.     function Convert(&$c$postprocess true)
  129.     {
  130.         $value parent::Convert($c$postprocess);
  131.         $simvalue parent::Convert($cfalse);
  132.         foreach($this->attributes as $a => $v)
  133.         {
  134.             $this->attributes[$a(is_string($v$v $v->Convert($c$postprocess));
  135.         }
  136.         if (isset($this->_title))
  137.         {
  138.             list($this->attributes,$value$c->ConvertTitle($this->name$this->attributes$this->_title->Convert($c$postprocess)$value);
  139.         }
  140.         return $c->TranslateTag($this->name,$this->attributes,$value,$simvalue);
  141.     }
  142.     
  143.     /**
  144.      * Begin a new CData section
  145.      * @see addCData()
  146.      */
  147.     function startCData()
  148.     {
  149.         $this->_cdata new parserCData;
  150.     }
  151.     
  152.     /**
  153.      * Adds {@link $_cdata} to {@link $value}
  154.      */
  155.     function endCData()
  156.     {
  157.         $this->value[$this->_cdata;
  158.         unset($this->_cdata);
  159.     }
  160.     
  161.     /**
  162.      * Retrieve either the table of contents index, or the location that
  163.      * the TOC will go
  164.      * @see setTOC()
  165.      * @param false|integereither an index of the {@}toc} tag in $this->value
  166.      *                       or false, if the next index value of $this->value
  167.      *                       is needed
  168.      */
  169.     function getTOC($state false)
  170.     {
  171.         if ($state !== falsereturn $this->value[$state];
  172.         return count($this->value);
  173.     }
  174.     
  175.     /**
  176.      * @param integer index of the TOC in $this->value
  177.      * @param parserTocInlineTag 
  178.      */
  179.     function setTOC($state$val)
  180.     {
  181.         $this->value[$state$val;
  182.     }
  183.     
  184.     /**
  185.      * add a word to CData
  186.      * @param string 
  187.      */
  188.     function addCData($word)
  189.     {
  190.         $this->_cdata->add($word);
  191.     }
  192.     
  193.     /**
  194.      * Add an xml tag attribute name="value" pair
  195.      *
  196.      * if the attribute is id, value must be a {@link parserIdInlineTag}
  197.      * @param string attribute name
  198.      * @param string|parserIdInlineTagvalue of attribute
  199.      */
  200.     function addAttribute($name,$value)
  201.     {
  202.         $this->attributes[$name$value;
  203.         if ($name == 'id')
  204.         {
  205.             // fix 1153593
  206.             if (is_string($value))
  207.             {
  208.                 addWarning(PDERROR_ID_MUST_BE_INLINE,$this->name,$value,$this->name,$value);
  209.             else {
  210.                 $this->setId($value);
  211.             }
  212.         }
  213.     }
  214.     
  215.     /**
  216.      * Set the title of a DocBook tag section.
  217.      *
  218.      * For most DocBook tags, the title is represented with a <title></title>
  219.      * tag pair.  The <refentry> top-level tag is a little different.  Instead
  220.      * of using <title></title>, phpDocumentor uses the contents of the
  221.      * <refname> tag in the <refnamediv> tag
  222.      * @param parserXMLDocBookTag the title element
  223.      */
  224.     function setTitle($title)
  225.     {
  226.         $this->_title $title;
  227.     }
  228.     
  229.     /**
  230.      * If the id attribute is present, this method will set its id
  231.      * @param parserIdInlineTag 
  232.      */
  233.     function setId($id)
  234.     {
  235.         $this->_id $id;
  236.     }
  237.     
  238.     /**
  239.      * Return converter-specific formatting of ID.
  240.      *
  241.      * Passes $c to {@link parserIdInlineTag::Convert()}
  242.      * @param Converter 
  243.      * @return string 
  244.      */
  245.     function getId(&$c)
  246.     {
  247.         if ($this->_idreturn trim($this->_id->Convert($c));
  248.     }
  249.     
  250.     /**
  251.      * Determine whether the docbook element has a title
  252.      * @return boolean 
  253.      */
  254.     function hasTitle()
  255.     {
  256.         return isset($this->_title);
  257.     }
  258.     
  259.     /**
  260.      * Retrieve Converter-specific formatting of the title of this element
  261.      * @return string 
  262.      * @param Converter 
  263.      */
  264.     function getTitle(&$c)
  265.     {
  266.         if ($this->name == 'refentry')
  267.         {
  268.             foreach($this->value as $tag)
  269.             {
  270.                 if (is_object($tag&& $tag->name == 'refnamediv')
  271.                 {
  272.                     return $tag->getTitle($c);
  273.                 }
  274.             }
  275.         }
  276.         if ($this->name == 'refnamediv')
  277.         {
  278.             foreach($this->value as $tag)
  279.             {
  280.                 if (is_object($tag&& is_a($tag'parserXMLDocBookTag'&& $tag->name == 'refname')
  281.                 {
  282.                     $t new parserStringWithInlineTags;
  283.                     foreach($tag->value as $val$t->add($val);
  284.                     $this->_title $t;
  285.                 }
  286.                 if (is_object($tag&& is_a($tag'parserXMLDocBookTag'&& $tag->name == 'refpurpose')
  287.                 {
  288.                     $t new parserStringWithInlineTags;
  289.                     foreach($tag->value as $val$t->add($val);
  290.                     $this->_description $t;
  291.                 }
  292.             }
  293.         }
  294.         if (isset($this->_title))
  295.         return $this->_title->Convert($c);
  296.         if (is_object($this->value[0]&& is_a($tag'parserXMLDocBookTag')) {
  297.             return $this->value[0]->getTitle($c);
  298.         }
  299.         if (isset($this->value[1])) {
  300.             if (is_object($this->value[1]&& is_a($tag'parserXMLDocBookTag')) {
  301.                 return $this->value[1]->getTitle($c);
  302.             }
  303.         }
  304.         return '';
  305.     }
  306.     
  307.     /**
  308.      * Retrieve the contents of a subsection
  309.      *
  310.      * This method uses the $_id members of nested docbook tags to retrieve
  311.      * the section defined by $subsection
  312.      * @param Converter 
  313.      * @param string converter-specific subsection
  314.      */
  315.     function getSubsection(&$c,$subsection)
  316.     {
  317.         if (!is_object($this->_id)) {
  318.             return false;
  319.         }
  320.         $search phpDocumentor_clone($this->_id);
  321.         if (is_string($this->_id)) return false;
  322.         if (phpDocumentor_get_class($search!= 'parseridinlinetag'return false;
  323.         $search->id $subsection;
  324.         foreach($this->value as $el)
  325.         {
  326.             if (phpDocumentor_get_class($el== 'parserxmldocbooktag')
  327.             {
  328.                 if ($el->getId($c== $search->Convert($c))
  329.                 {
  330.                     return $el;
  331.                 elseif ($a $el->getSubsection($c,$subsection))
  332.                 {
  333.                     return $a;
  334.                 }
  335.             }
  336.         }
  337.         return false;
  338.     }
  339.     
  340.     /**
  341.      * Add contents to this tag.
  342.      *
  343.      * There are four kinds of data in a DocBook tutorial:
  344.      *  1. <b>tags</b> - normal tags like <refentry>
  345.      *  2. <b>entities</b> - normal entities like &rdquo;
  346.      *  3. <b><![CDATA[</b> - character data that should not be interpreted,
  347.      *     like <programlisting> contents
  348.      *  4. <b>text</b> - normal non-markup text
  349.      *
  350.      * All four kinds of data are added here
  351.      * @param parserEntity|parserCData|parserXMLDocBookTag|stringnested tag,
  352.      *         entity, or text
  353.      */
  354.     function add($el)
  355.     {
  356.         if (is_string($el)) return parent::add($el);
  357.         if (phpDocumentor_get_class($el== 'parserxmldocbooktag')
  358.         {
  359.             if ($el->name == 'title')
  360.             {
  361.                 $this->setTitle($el);
  362.             else return parent::add($el);
  363.         else return parent::add($el);
  364.     }
  365. }
  366.  
  367. /**
  368.  * a standard entity like &rdquo;
  369.  *
  370.  * This class is designed to represent all DocBook entities.
  371.  * @since 1.2
  372.  * @package phpDocumentor
  373.  * @subpackage Tutorial
  374.  */
  375. {
  376.     /**
  377.      * @param string entity name
  378.      */
  379.     function parserEntity($name)
  380.     {
  381.         $this->value $name;
  382.     }
  383.     
  384.     /**
  385.      * @uses Converter::TranslateEntity() convert contents to text
  386.      * @param Converter 
  387.      * @return string 
  388.      */
  389.     function Convert(&$c$postprocess true)
  390.     {
  391.         if ($postprocess)
  392.         return $c->TranslateEntity($this->value);
  393.         else
  394.         {
  395.             $trans_tbl get_html_translation_table (HTML_ENTITIES);
  396.             $trans_tbl array_flip ($trans_tbl);
  397.             $ret strtr ('&'.$this->value.';'$trans_tbl);
  398.             return $ret;
  399.         }
  400.     }
  401. }
  402. ?>

Documentation generated on Tue, 24 Oct 2006 09:24:09 -0500 by phpDocumentor 1.3.1