Subversion-Projekte lars-tiefland.php_share

<refentry id="{@id}">

 <refnamediv>

  <refname>{@link http://pear.php.net/package/PhpDocumentor phpDocumentor} Tutorial</refname>

  <refpurpose>An in-depth look at using phpDocumentor to document PHP Source Code, and phpDocumentor internals</refpurpose>

 </refnamediv>

 <refsynopsisdiv>

  <author>

   Gregory Beaver

   <authorblurb>

    Tutorial written by {@link mailto:cellog@php.net cellog@php.net}

   </authorblurb>

  </author>

 </refsynopsisdiv>

 {@toc}

 <refsect1 id="{@id intro}">

   <title>Introduction</title>

   <para>phpDocumentor is the most advanced automatic documentation system written for PHP, in PHP. This package has many features:</para>

   <para>

    <itemizedlist>

	 <listitem><para><emphasis>NEW</emphasis> The first auto-documentor with PHP 5 support</para></listitem>

     <listitem><para>Extended documentation in docbook format with linking to any element and to other documentation,

      including sub-sections, from the source code (see {@tutorial tutorials.pkg})</para></listitem>

     <listitem><para>docblock templates to cut down on repetition</para></listitem>

     <listitem><para>XML:DocBook:peardoc2 templates for PEAR developers</para></listitem>

     <listitem><para>Greater ease of extending a Converter, see {@tutorial Converters/Converters.pkg}</para></listitem>

     <listitem><para>ability to parse any PHP file, regardless of documentation format</para></listitem>

     <listitem><para>conforms loosely to the {@link http://java.sun.com/docs/books/jls/first_edition/html/18.doc.html JavaDOC protocol},

     and will be familiar to Java programmers</para></listitem>

     <listitem><para>documents all includes, constants, functions, static functions, classes,

      methods, static variables, class variables, and can document global variables and

      external tutorials</para></listitem>

     <listitem><para>auto-linking to pre-defined PHP functions</para></listitem>

     <listitem><para>Output in HTML, CHM, PDF, XML DocBook formats</para></listitem>

     <listitem><para>templateable with many bundled templates</para></listitem>

     <listitem><para>automatic linking to elements in any documented package</para></listitem>

     <listitem><para>documents name conflicts between packages to help avoid PHP errors</para></listitem>

     <listitem><para>document CVS repository directly.</para></listitem>

     <listitem><para>support for JavaDoc doclet-like output through Converters</para></listitem>

     <listitem><para>error/warning tracking system</para></listitem>

     <listitem><para>extreme class intelligence: inherits documentation, package</para></listitem>

     <listitem><para>complete phpdoc.de DocBlock tag support.  Additions include @var, @magic, @deprec, @todo, and phpdoc.de parsing of @param.</para></listitem>

     <listitem><para>alphabetical indexing of all elements by package and overall</para></listitem>

     <listitem><para>class trees</para></listitem>

     <listitem><para>MUCH more than just this short list</para></listitem>

    </itemizedlist>

   </para>

 </refsect1>

 <refsect1 id="{@id basics}">

  <title>phpDocumentor Basics</title>

  <refsect2 id="{@id starting}">

   <title>Starting Out From Scratch</title>

   <para>The documentation process begins with the most basic element of phpDocumentor: a

    <emphasis>Documentation block </emphasis> or <emphasis>DocBlock</emphasis>. A basic

    DocBlock looks like this:

   </para>

   <para>

    <programlisting role="php">

    <![CDATA[

/**

 *

 */

    ]]>

    </programlisting>

   </para>

   <para>A DocBlock is an extended C++-style PHP comment that begins with &quot;/**&quot; and has

    an "*" at the beginning of every line.  DocBlocks precede the element they are documenting.

   </para>

   <caution>Any line within a DocBlock that doesn't begin with a * will be ignored.</caution>

   <para>To document function &quot;foo()&quot;, place the DocBlock immediately before the function declaration:</para>

   <para>

    <programlisting role="php">

    <![CDATA[

/**

 * Defies imagination, extends boundaries and saves the world ...all before breakfast!

 */

function foo()

{

}

    ]]>

    </programlisting>

   </para>

   <para>This example will apply the DocBlock to &quot;define('me',2);&quot; instead of to &quot;function foo()&quot;:

   <programlisting role="php">

   <![CDATA[

/**

 * DocBlock for function foo?

 *

 * No, this will be for the constant me!

 */

define('me',2);

function foo($param = me)

{

}

   ]]>

   </programlisting>

   </para>

   <para>define() statements, functions, classes, class methods, and class vars, include()

    statements, and global variables can all be documented, see

    {@tutorial phpDocumentor.howto.pkg#documenting.elements}

   </para>

  </refsect2>

  <refsect2 id="{@id docblock}">

   <title>DocBlocks</title>

   <para>A DocBlock contains three basic segments in this order:</para>

   <para>

    <itemizedlist>

     <listitem><para>Short Description</para></listitem>

     <listitem><para>Long Description</para></listitem>

     <listitem><para>Tags</para></listitem>

    </itemizedlist>

   </para>

   <para>The Short Description starts on the first line, and can be terminated with a blank line

    or a period. A period inside a word (like example.com or 0.1 %) is ignored. If the Short

    Description would become more than three lines long, only the first line is taken. The Long

    Description continues for as many lines as desired and may contain html markup for display

    formatting.  Here is a sample DocBlock with a Short and a Long Description:

   </para>

   <para>

    <programlisting role="php">

    <![CDATA[

/**

 * return the date of Easter

 *

 * Using the formula from "Formulas that are way too complicated for anyone to

 * ever understand except for me" by Irwin Nerdy, this function calculates the

 * date of Easter given a date in the Ancient Mayan Calendar, if you can also

 * guess the birthday of the author.

 */

    ]]>

    </programlisting>

   </para>

   <para>Optionally, you may enclose all paragraphs in a &lt;p&gt;&lt;/p&gt; tag.  Be careful,

    if the first paragraph does not begin with <p>, phpDocumentor will assume that the

    DocBlock is using the simple double linebreak to define paragraph breaks as in:

   </para>

   <para>

    <programlisting role="php">

    <![CDATA[

/**

 * Short desc

 *

 * Long description first sentence starts here

 * and continues on this line for a while

 * finally concluding here at the end of

 * this paragraph

 *

 * The blank line above denotes a paragraph break

 */

    ]]>

    </programlisting>

   </para>

   <para>Here is an example of using &lt;p&gt;</para>

   <para>

    <programlisting role="php">

    <![CDATA[

/**

 * Short desc

 *

 * <p>Long description first sentence starts here

 * and continues on this line for a while

 * finally concluding here at the end of

 * this paragraph</p>

 * This text is completely ignored! it is not enclosed in p tags

 * <p>This is a new paragraph</p>

 */

    ]]>

    </programlisting>

   </para>

   <para>phpDocumentor also supports JavaDoc's DocBlock format through the command-line

    option {@tutorial phpDocumentor.howto.pkg#using.command-line.javadocdesc}.  Due to

    the non-xhtml compliant unmatched p tag, we highly recommend you avoid this syntax

    whenever possible

   </para>

   <para>

    <programlisting role="php">

    <![CDATA[

/**

 * <p>

 * Short desc is only to the first period.

 * This means a sentence like:

 * "Parses Mr./Mrs. out of $_GET." will

 * parse a short description of "Parses Mr."

 * which is rather silly.  Long description is

 * the entire DocBlock description including the

 * Short desc, and paragraphs begin where p is like:

 * <p>

 * The p above denotes a paragraph break

 */

    ]]>

    </programlisting>

   </para>

   <para>phpDocumentor will convert all whitespace into a single space in the

    long description, use paragraph breaks to define newlines, or <pre>,

    as discussed in the next section.</para>

  </refsect2>

  <refsect2 id="{@id desc}">

   <title>DocBlock Description details</title>

   <para>As of phpDocumentor 1.2.0, the long and short description of a DocBlock

    is parsed for a few select html tags that determine additional formatting.  Due

    to the nature of phpDocumentor's output as multiple-format, straight html is not

    allowed in a DocBlock, and will be converted into plain text by all of the

    converters unless it is one of these tags:

    <itemizedlist>

     <listitem><para>&lt;b&gt; -- emphasize/bold text</para></listitem>

     <listitem><para>&lt;code&gt; -- Use this to surround php code, some converters will highlight it</para></listitem>

     <listitem><para>&lt;br&gt; -- hard line break, may be ignored by some converters</para></listitem>

     <listitem><para>&lt;i&gt; -- italicize/mark as important</para></listitem>

     <listitem><para>&lt;kbd&gt; -- denote keyboard input/screen display</para></listitem>

     <listitem><para>&lt;li&gt; -- list item</para></listitem>

     <listitem><para>&lt;ol&gt; -- ordered list</para></listitem>

     <listitem><para>&lt;p&gt; -- If used to enclose all paragraphs, otherwise it will be considered text</para></listitem>

     <listitem><para>&lt;pre&gt; -- Preserve line breaks and spacing, and assume all tags are text (like XML's CDATA)</para></listitem>

     <listitem><para>&lt;samp&gt; -- denote sample or examples (non-php)</para></listitem>

     <listitem><para>&lt;ul&gt; -- unordered list</para></listitem>

     <listitem><para>&lt;var&gt; -- denote a variable name</para></listitem>

    </itemizedlist>

    Do not think of these tags as text, they are parsed into objects and converted

    into the appropriate output format by the converter.  So, a b tag may become

    &lt;emphasis&gt; in DocBook, and a &lt;p&gt; tag might become <![CDATA["    "]]> (4 spaces)

    in the PDF converter!  The text output is determined by the template options file

    options.ini found in the base directory of every template.  For instance, the

    options.ini file for the HTML:frames:default template is in

    phpDocumentor/Converters/HTML/frames/templates/default/options.ini

   </para>

   <para>For the rare case when the text &quot;&lt;b&gt;&quot; is needed in a DocBlock,

    use a double delimiter as in <<b>>.  phpDocumentor will automatically

    translate that to the physical text "<b>".

   </para>

   <para>Similarly, if you need an actual &quot;@&quot; in your DocBlock's description parts,

   you should be careful to either ensure it is not the first character on a line,

   or else escape it ("\@") to avoid it being interpreted as a PhpDocumentor tag marker.

   </para>

   <para>

    <programlisting role="php">

    <![CDATA[

/**

 * Demonstrate an @include file

 * line in a code block:

 *

 * <code>

 * \@include somefile.php

 * </code>

 */

    ]]>

    </programlisting>

   </para>

   <para>This will parse as if it were:</para>

   <para>

    <programlisting role="php">

    <![CDATA[

/**

 * Demonstrate an @include file

 * line in a code block:

 *

 * <code>

 * @include somefile.php

 * </code>

 */

    ]]>

    </programlisting>

   </para>

   <para>

   </para>

   <note>

    <title>Using &lt;code&gt; &lt;kbd&gt; &lt;pre&gt;</title>

    The <code>, <kbd>, and <pre> tags ignore any html listed above

    except for their own closing tags (</code> </kbd> </pre>).

    This is obviously necessary for each of those tag's behavior of controlling the appearance of the text

    inside their tag blocks, without allowing other nested tags (like <b>) interfering inside them.

    In general, other tags will allow other tags to be nested in them

    (i.e. <samp><b>bold_my_sample</b></samp>).

   </note>

   <para><emphasis>New 1.2.0rc1:</emphasis> If you need to use the closing comment &quot;*/&quot;

    in a DocBlock, use the special escape sequence "{@*}."  Here's an example:

   </para>

   <para>

    <programlisting role="php">

    <![CDATA[

/**

 * Simple DocBlock with a code example containing a docblock

 *

 * <code>

 *  /**

 *   * My sample DocBlock in code

 *   {@}*}

 * </code>

 */

    ]]>

    </programlisting>

   </para>

   <para>This will parse as if it were:</para>

   <para>

    <programlisting role="php">

    <![CDATA[

/**

 * Simple DocBlock with a code example containing a docblock

 *

 * <code>

 *  /**

 *   * My sample DocBlock in code

 *   */

 * </code>

 */

    ]]>

    </programlisting>

   </para>

   <para><emphasis>New 1.2.0rc1:</emphasis> The phpEdit tool supports very clever list

    extraction from DocBlocks, and now phpDocumentor supports the same cleverness.  This example:

   </para>

   <para>

    <programlisting role="php">

    <![CDATA[

/**

 * Simple DocBlock with simple lists

 *

 * Here's a simple list:

 * - item 1

 * - item 2, this one

 *   is multi-line

 * - item 3

 * end of list.  Next list is ordered

 * 1 ordered item 1

 * 2 ordered item 2

 * end of list. This is also ordered:

 * 1. ordered item 1

 * 2. ordered item 2

 */

    ]]>

    </programlisting>

   </para>

   <para>phpDocumentor recognizes any simple list that begins with &quot;-&quot;,

    "+", "#" and "o", and any ordered list with

    sequential numbers or numbers followed by "." as above.  The list

    delimiter must be followed by a space (not a tab!) and whitespace must line

    up exactly, or phpDocumentor will not recognize the list items as being in

    the same list.

   </para>

   <para>

    <programlisting role="php">

    <![CDATA[

/**

 * Simple DocBlock with screwy lists

 *

 * +not a list at all, no space

 * Here's 3 lists!

 * - item 1

 *  - item 2, this one

 *   is multi-line

 *- item 3

 */

    ]]>

    </programlisting>

   </para>

   <para>Again, you must line up the list iterators in the same vertical column

     in order for those list items to be considered "on the same list".

     Also, you cannot create nested lists using the simple list iterators...

     doing so means it's no longer a "simple" list!  Varying the spacing

     of the list iterators does not create nesting of the lists... it only starts up

     new simple lists.  If you specifically need a nested list, you must use the list

     tags (<ol>, <ul>):

   </para>

   <para>

    <programlisting role="php">

    <![CDATA[

/**

 * DocBlock with nested lists

 *

 * Here's the "complex" list:

 * <ul>

 * <li>outer item 1</li>

 * <li>outer item 2, this one

 *   is multi-line</li>

 * <li>item 3 is a nested inner list

 * <ul>

 * <li>inner item 1</li>

 * <li>inner item 2</li>

 * </ul>

 * <li>outer item 4</li>

 * </ul>

 */

    ]]>

    </programlisting>

   </para>

   <para>In some cases, the text description in a doc tag can contain a list, be it simple

     or complex.  Notice that a title line is needed, with the list items themselves

     beginning on the next line:

   </para>

   <para>

    <programlisting role="php">

    <![CDATA[

/**

 * DocBlock with nested lists

 * in the tag descriptions

 * @todo My Simple TODO List

 *    - item 1

 *    - item 2

 *    - item 3

 * @todo My Complex TODO List

 *    <ol>

 *      <li>item 1.0</li>

 *      <li>item 2.0</li>

 *      <li>item 3.0</li>

 *        <ol>

 *          <li>item 3.1</li>

 *          <li>item 3.2</li>

 *        </ol>

 *      <li>item 4.0</li>

 *    </ol>

 */

    ]]>

    </programlisting>

   </para>

   <para>Tagged lists are always a more robust and predictable option for you to

     use.  Simple lists are convenient, but if you find yourself trying to bend

     a simple list into displaying a certain way in your generated docs, you may

     be better served by switching to a tagged list instead.

   </para>

   <para>For in-depth information on how phpDocumentor parses the description

    field, see {@link ParserDescCleanup.inc}

   </para>

  </refsect2>

  <refsect2 id="{@id docblocktemplate}">

   <title>DocBlock Templates</title>

   <para>New for version 1.2.0, phpDocumentor supports the use of DocBlock

    templates.  The purpose of a DocBlock template is to reduce redundant

    typing.  For instance, if a large number of class variables are private,

    one would use a DocBlock template to mark them as private.  DocBlock templates

    simply augment any normal DocBlocks found in the template block.

   </para>

   <para>A DocBlock template is distinguished from a normal DocBlock by its header.

    Here is the most basic DocBlock template:

   </para>

   <para>

    <programlisting role="php">

     <![CDATA[

/**#@+

 *

 */

     ]]>

    </programlisting>

   </para>

   <para>The text that marks this as a DocBlock template is &quot;/**#@+&quot;

    - all 6 characters must be present.  DocBlock templates are applied to all

    documentable elements until the ending template marker:

   </para>

   <para>

    <programlisting role="php">

     <![CDATA[

/**#@-*/

     ]]>

    </programlisting>

   </para>

   <para>Note that all 8 characters must appear as &quot;/**#@-*/&quot; in order

    for phpDocumentor to recognize them as a template.  Here is an example of a

    DocBlock template in action:

   </para>

   <para>

    <programlisting role="php">

    <![CDATA[

class Bob

{

    // beginning of docblock template area

    /**#@+

     * @access private

     * @var string

     */

    var $_var1 = 'hello';

    var $_var2 = 'my';

    var $_var3 = 'name';

    var $_var4 = 'is';

    var $_var5 = 'Bob';

    var $_var6 = 'and';

    var $_var7 = 'I';

    /**

     * Two words

     */

    var $_var8 = 'like strings';

    /**#@-*/

    var $publicvar = 'Lookee me!';

}

    ]]>

    </programlisting>

   </para>

   <para>This example will parse as if it were:</para>

   <para>

    <programlisting role="php">

    <![CDATA[

class Bob

{

    // beginning of docblock template area

    /**

     * @access private

     * @var string

     */

    var $_var1 = 'hello';

    /**

     * @access private

     * @var string

     */

    var $_var2 = 'my';

    /**

     * @access private

     * @var string

     */

    var $_var3 = 'name';

    /**

     * @access private

     * @var string

     */

    var $_var4 = 'is';

    /**

     * @access private

     * @var string

     */

    var $_var5 = 'Bob';

    /**

     * @access private

     * @var string

     */

    var $_var6 = 'and';

    /**

     * @access private

     * @var string

     */

    var $_var7 = 'I';

    /**

     * Two words

     * @access private

     * @var string

     */

    var $_var8 = 'like strings';

    var $publicvar = 'Lookee me!';

}

    ]]>

    </programlisting>

   </para>

   <para>Note that for <varname>$_var8</varname> the DocBlock template merged

    with the DocBlock.  The rules for merging are simple:

    <itemizedlist>

     <listitem><para>The long description of the docblock template is added to

      the front of the long description.  The short description is ignored.

     </para></listitem>

     <listitem><para>All tags are merged from the docblock template</para></listitem>

    </itemizedlist>

   </para>

  </refsect2>

  <refsect2 id="{@id tags}">

   <title>Tags</title>

   <para>Tags are single words prefixed by a &quot;@&quot; symbol.  Tags inform

    phpDocumentor how to present information and modify display of documentation.

    All tags are optional, but if you use a tag, they do have specific requirements

    to parse properly.

   </para>

   <para>A list of all possible tags in phpDocumentor follows:</para>

   <para>

    <programlisting role="php">

    <![CDATA[

/**

 * The short description

 *

 * As many lines of extendend description as you want {@}link element}

 * links to an element

 * {@}link http://www.example.com Example hyperlink inline link} links to

 * a website. The inline

 * source tag displays function source code in the description:

 * {@}source}

 *

 * In addition, in version 1.2+ one can link to extended documentation like this

 * documentation using {@}tutorial phpDocumentor/phpDocumentor.howto.pkg}

 * In a method/class var, {@}inheritdoc may be used to copy documentation from

 * the parent method

 * {@internal

 * This paragraph explains very detailed information that will only

 * be of use to advanced developers, and can contain

 * {@}link http://www.example.com Other inline links!} as well as text}}

 *

 * Here are the tags:

 *

 * @abstract

 * @access       public or private

 * @author       author name <author@email>

 * @copyright    name date

 * @deprecated   description

 * @deprec       alias for deprecated

 * @example      /path/to/example

 * @exception    Javadoc-compatible, use as needed

 * @global       type $globalvarname

   or

 * @global       type description of global variable usage in a function

 * @ignore

 * @internal     private information for advanced developers only

 * @param        type [$varname] description

 * @return       type description

 * @link         URL

 * @name         procpagealias

   or

 * @name         $globalvaralias

 * @magic        phpdoc.de compatibility

 * @package      package name

 * @see          name of another element that can be documented,

 *               produces a link to it in the documentation

 * @since        a version or a date

 * @static

 * @staticvar    type description of static variable usage in a function

 * @subpackage	sub package name, groupings inside of a project

 * @throws       Javadoc-compatible, use as needed

 * @todo         phpdoc.de compatibility

 * @var		type	a data type for a class variable

 * @version	version

 */

function if_there_is_an_inline_source_tag_this_must_be_a_function()

{

// ...

}

    ]]>

    </programlisting>

   </para>

   <para>In addition, tutorials allow two addition inline tags: {@}id}, used to

    allow direct linking to sections in a tutorial, and {@}toc}, used to generate

    a table of contents from {@}id}s in the file.  Think of {@}id} like an <a

    name="idname"> HTML tag, it serves the same function.

   </para>

   <para>See {@tutorial tags.inlineid.pkg} and {@tutorial tags.inlinetoc.pkg} for

    detailed information

   </para>

   <para>In the example below, {@}id} is used to name the refsect1 "mysection"

    and the refsect2 "mysection.mysubsection" - note that the sub-sections inherit

    the parent section's id.

   </para>

   <para>

    <example role="xml">

    <![CDATA[

<refentry id="{@}id}">

 <refsect1 id="{@}id mysection}">

  <refsect2 id="{@}id mysubsection}">

  </refsect2>

 </refsect1>

</refentry>

    ]]>

    </example>

   </para>

   <para>For an in-depth look at phpDocumentor tags, read {@tutorial tags.pkg},

    and for an in-depth look at inline tags, read {@tutorial inlinetags.pkg}.

   </para>

  </refsect2>

 </refsect1>

 <refsect1 id="{@id documenting}">

  <title>Documenting your PHP project</title>

  <refsect2 id="{@id intro}">

   <title>Where to begin</title>

   <para>Before you begin documenting your PHP project, you might want to try

    a test run on your undocumented source code to see what kind of information

    phpDocumentor will automatically extract from the source code.  phpDocumentor

    is designed to make the task of documenting minimally redundant.  This means

    less work, and better, up-to-date documentation with less effort than it used

    to take.

   </para>

   <caution>phpDocumentor is a great tool, but it will not write good documentation

    for you.  Please read the {@tutorial phpDocumentor.pkg}

   </caution>

  </refsect2>

  <refsect2 id="{@id elements}">

   <title>Elements of the source code that can be documented</title>

   <refsect3 id="{@id packages}">

    <title>Dividing projects into packages</title>

    <para>To understand the role of packages and how to use {@tutorial tags.package.pkg},

     it is important to know the logic behind packaging in PHP.  The quest for structured

     programming led to the invention of functions, then classes, and finally packages.

     Traditionally, a re-usable software module was a collection of variables, constants

     and functions that could be used by another software package.  PHP is an example of

     this model, as their are many extensions that consist of constants and functions like

     the tokenizer extension.  One can think of the tokenizer extension as a package: it

     is a complete set of data, variables and functions that can be used in other programs.

     A more structured format of this model is of course objects, or classes.  A class

     contains variables and functions (but no constants in PHP).  A single class packages

     together related functions and variables to be re-used.

    </para>

    <para>phpDocumentor defines package in two ways:

     <orderedlist>

      <listitem><para>Functions, Constants and Global Variables are grouped into files

       (by the filesystem), which are in turn grouped into packages using the @package

       tag in a page-level DocBlock

      </para></listitem>

      <listitem><para>Methods and Class Variables are grouped into classes (by PH),

       which are in turn grouped into packages in a Class DocBlock

      </para></listitem>

     </orderedlist>

     These two definitions of package are exclusive.  In other words, it is possible

     to have classes of a different package of the file that contains it!  Here's an example:

    </para>

    <caution>It may be possible, but don't put classes into a different package from the

     file they reside in, that will be very confusing and unnecessary.  This behavior is

     deprecated, in version 2.0, phpDocumentor will halt parsing upon this condition.

    </caution>

    <para>

     <programlisting role="php">

     <![CDATA[

<?php

/**

 * Pretend this is a file

 *

 * Page-level DocBlock is here because it is the first DocBlock

 * in the file, and is immediately followed by the second

 * DocBlock before any documentable element is declared

 * (function, define, class, global variable, include)

 * @package pagepackage

 */

/**

 * Here is the class DocBlock

 *

 * The class package is different from the page package!

 * @package classpackage

 */

class myclass

{

}

?>

     ]]>

     </programlisting>

    </para>

    <para>For more information on page-level versus class-level packaging, see {@tutorial elements.pkg#procedural}</para>

    <para>Perhaps the best way to organize packages is to put all procedural code

     into separate files from classes.  {@link http://pear.php.net PEAR} recommends

     putting every class into a separate file.  For small, utility classes, this may

     not be the best solution for all cases, but it is still best to separate packages

     into different files for consistency.

    </para>

   </refsect3>

  </refsect2>

  <refsect2 id="{@id tutorials}">

   <title>Advanced phpDocumentor: tutorials and extended Documentation</title>

   <para>phpDocumentor developers have received a number of requests to allow linking

    to external documentation, and to sections of that documentation.  If phpDocumentor

    only could create HTML documents, this would be a simple task, but the presence of

    PDF and now XML converters as well as future possibilities complicates this question

    tremendously.  What is the solution?

   </para>

   <para>Give phpDocumentor the ability to parse external documentation in a common format

    and then convert it to the appropriate format for each converter.  The implementation

    of this solution in version 1.2.0 is very versatile.  Making use of the standard DocBook

    XML format, external documentation can be designed and then reformatted for any output.

    No longer is external documentation tied down to one "look."  Here's a short

    list of the benefits of this approach:

   </para>

   <para>

    Benefits of using DocBook as the format:

    <itemizedlist>

     <listitem><para>DocBook is very similar to HTML at the basic level and very

      easy to learn.

     </para></listitem>

     <listitem><para>Each template has its own options.ini file which determines

      how the DocBook tags will be translated into the output language - no need

      to learn xslt.

     </para></listitem>

     <listitem><para>Adding in xslt support will be very easy to allow for future

      customization

     </para></listitem>

    </itemizedlist>

    Benefits of integrating tutorials/external documentation into phpDocumentor:

    <itemizedlist>

     <listitem><para>Linking to external documentation from within API docs is possible</para></listitem>

     <listitem><para>Linking to API docs from external documentation is also possible</para></listitem>

     <listitem><para>Customizable table of contents, both of all tutorials and within

      a tutorial via {@tutorial tags.inlinetoc.pkg}

     </para></listitem>

     <listitem><para>It is possible to create User-level documentation that has direct

      access to Programmer-level documentation

     </para></listitem>

    </itemizedlist>

   </para>

   <para>User-level documentation generally consists of tutorials and information on how

    to use a package, and avoids extreme detail.  On the other hand, programmer-level

    documentation has all the details a programmer needs to extend and modify a package.

    phpDocumentor has been assisting the creation of programmer-level documentation since

    its inception.  With the addition of tutorials, it can now ease the creation of user-level

    documentation.

   </para>

   <para>For an in-depth look at how to use tutorials, read {@tutorial tutorials.pkg}</para>

  </refsect2>

 </refsect1>

 <refsect1 id="{@id using}">

  <title>Running phpDocumentor</title>

  <para>There are two bundled ways of invoking phpDocumentor, the command-line phpdoc,

   or the web interface phpdoc.php/new_phpdoc.php.

  </para>

  <refsect2 id="{@id docbuilder}">

   <title>Using the new Web Interface docbuilder</title>

   <para>The new web interface requires a working installation of PHP with a web server,

    and must be accessible from the document root.  Docbuilder is the creation of Andrew

    Eddies, and it combines some slick formatting with the functionality of the old web

    interface.  The docbuilder interface can be accessed via index.html in the install

    directory of phpDocumentor, or the docbuilder subdirectory.

   </para>

  </refsect2>

  <refsect2 id="{@id web}">

   <title>Using the old Web Interface {@link phpdoc.php} or {@link new_phpdoc.php}</title>

   <para>In order to use the web interface, there are a number of factors that must

    be set up before anything else can occur.  First, you need a working web server

    with php (it had to be said).  This manual will not assist with that setup.  Next,

    the phpdoc.php or new_phpdoc.php file needs to be accessible by the webserver.  In

    unix, place a symbolic link using ln -s to the desired interface into the public

    html directory.

   </para>

   <caution>Security is always an issue with the internet.  Do not place phpDocumentor

    into the web server publicly available path on a server connected to the internet.

    Make sure that phpDocumentor will not have the power to overwrite <emphasis>ANY</emphasis>

    system or user files.

   </caution>

   <para>Note that since the webserver runs as user nobody in unix, the generated files

    will be owned by nobody.  The only way to change this is to either run phpDocumentor

    from the command-line or to add a chuser wrapper around httpd.  <emphasis>We do not

    recommend using a chuser wrapper or running phpDocumentor as root.</emphasis>  It is

    much easier and safer to use a config file (see {@tutorial phpDocumentor.howto.pkg#using.config-files})

    from the command line.

   </para>

  </refsect2>

  <refsect2 id="{@id command-line}">

   <title>Using the Command-line tool</title>

   <refsect3 id="{@id windows}">

    <title>Running the command-line in MS Windows</title>

    <para>Running phpDocumentor from the command-line is fairly straightforward, even in

     windows.  It is recommended to use the web interface in windows, from a non-publicly

     accessible server root, as none of the permissions issues exist that exist in unix.

     However, to use phpDocumentor from the command line is possible.  First, put the

     location of php into the system path, then type:

    </para>

    <para>

     <screen>

<![CDATA[

C:\>php-cli C:\path\to\phpdoc\phpdoc [commandline]

]]>

     </screen>

    </para>

    <para>An alternative is to edit the phpdoc.bat file, and place phpdoc in the path,

     then you can run phpdoc as a normal command.

    </para>

   </refsect3>

   <refsect3 id="{@id unix}">

    <title>Running the command-line in unix</title>

    <para>Running the command-line tool phpdoc is very easy in unix:</para>

     <screen>

<![CDATA[

.\phpdoc [commandline]

]]>

     </screen>

   </refsect3>

   <table frame="all" id="{@id summary}">

    <tgroup cols="3">

     <thead align="center">

      <row>

       <entry morerows="2">

        <emphasis>Command-line switches</emphasis>

       </entry>

      </row>

     </thead>

    <tbody>

     <row>

      <entry>-cp</entry>

      <entry>--converterparams</entry>

      <entry>dynamic parameters for a converter, separate values with commas</entry>

     </row>

     <row>

      <entry>-ct</entry>

      <entry>--customtags</entry>

      <entry>comma-separated list of non-standard @tags to pass to the converter as valid tags</entry>

     </row>

     <row>

      <entry>-d</entry>

      <entry>--directory</entry>

      <entry>name of a directory(s) to parse directory1,directory2</entry>

     </row>

  	 <row>

      <entry>-dc</entry>

      <entry>--defaultcategoryname</entry>

      <entry>name to use for the default category.  If not specified, uses 'default'</entry>

     </row>

     <row>

      <entry>-dh</entry>

      <entry>--hidden</entry>

      <entry>set equal to on (-dh on) to descend into hidden directories (directories

       starting with '.'), default is off

      </entry>

     </row>

  	 <row>

      <entry>-dn</entry>

      <entry>--defaultpackagename</entry>

      <entry>name to use for the default package.  If not specified, uses 'default'</entry>

     </row>

     <row>

      <entry>-ed</entry>

      <entry>--examplesdir</entry>

      <entry>full path of the directory to look for example files from @example tags</entry>

     </row>

     <row>

      <entry>-f</entry>

      <entry>--filename</entry>

      <entry>name of file(s) to parse ',' file1,file2.  Can contain complete path and * ? wildcards</entry>

     </row>

     <row>

      <entry>-i</entry>

      <entry>--ignore</entry>

      <entry>file(s) that will be ignored, multiple separated by ','.  Wildcards * and ? are ok</entry>

     </row>

     <row>

      <entry>-is</entry>

      <entry>--ignoresymlinks</entry>

      <entry>Explicitly ignore symlinks, both symlinked directories and symlinked files.

      Valid options are &quot;on&quot; and &quot;offn&quot; default value is &quot;off&quot;</entry>

     </row>

     <row>

      <entry>-it</entry>

      <entry>--ignore-tags</entry>

      <entry>tags to ignore for this parse.  @package, @subpackage, @access and @ignore may not be ignored.</entry>

     </row>

     <row>

      <entry>-j</entry>

      <entry>--javadocdesc</entry>

      <entry>use JavaDoc-compliant description (short desc is part of description, and is everything up to first .)</entry>

     </row>

     <row>

      <entry>-o</entry>

      <entry>--output</entry>

      <entry>output information, format:converter:template (HTML:frames:phpedit for example)</entry>

     </row>

     <row>

      <entry>-p</entry>

      <entry>--pear</entry>

      <entry>Parse a PEAR-style repository (package is directory, _members are @access private) on/off default off</entry>

     </row>

     <row>

      <entry>-po</entry>

      <entry>--packageoutput</entry>

      <entry>output documentation only for selected packages.  Use a comma-delimited list</entry>

     </row>

     <row>

      <entry>-pp</entry>

      <entry>--parseprivate</entry>

      <entry>parse elements marked private with @access.  Valid options are &quot;on&quot;

       and "off" default value is "off"

      </entry>

     </row>

     <row>

      <entry>-q</entry>

      <entry>--quiet</entry>

      <entry>do not display parsing/conversion messages.  Useful for cron jobs.  Valid options are &quot;on&quot;

       and &quot;off&quot; default value is &quot;off&quot;</entry>

     </row>

     <row>

      <entry>-ric</entry>

      <entry>--readmeinstallchangelog</entry>

      <entry>Specify custom filenames to parse like README, INSTALL or CHANGELOG files</entry>

     </row>

     <row>

      <entry>-s</entry>

      <entry>--sourcecode</entry>

      <entry>generate highlighted sourcecode for every parsed file (PHP 4.3.0+ only) on/off default off</entry>

     </row>

     <row>

      <entry>-t</entry>

      <entry>--target</entry>

      <entry>path where to save the generated files</entry>

     </row>

     <row>

      <entry>-ti</entry>

      <entry>--title</entry>

      <entry>title of generated documentation, default is 'Generated Documentation'</entry>

     </row>

     <row>

      <entry>-tb</entry>

      <entry>--templatebase</entry>

      <entry>base location of all templates for this parse.  Note that if -tb /path/to/here, then

       templates for HTML:frames:default must be in /path/to/here/Converters/HTML/frames/templates/default/templates

       and the /path/to/here/Converters/HTML/frames/templates/default/templates_c directory must

       exist, or Smarty will bail on attempting to compile the templates.

      </entry>

     </row>

     <row>

      <entry>-ue</entry>

      <entry>--undocumentedelements</entry>

      <entry>Enable warnings for undocumented elements. Useful for identifying classes and methods that haven't yet been documented.

      Valid options are &quot;on&quot; and &quot;offn&quot; default value is &quot;off&quot;</entry>

     </row>

    </tbody>

    </tgroup>

   </table>