<refentry id="{@id}">
 <refnamediv>
  <refname>inline {@}example}</refname>
  <refpurpose>Display source code of an example file inline</refpurpose>
 </refnamediv>
 <refsynopsisdiv>
  <refsynopsisdivinfo>
   <author>
    Gregory Beaver
    <authorblurb>Tag Documentation written by {@link mailto:cellog@php.net cellog@php.net}</authorblurb>
   </author>
   <copyright>Copyright 2004, Gregory Beaver</copyright>
   <releaseinfo>phpDocumentor 1.2+</releaseinfo>
  </refsynopsisdivinfo>
  <cmdsynopsis>
   <command>{@}example</command>
   <arg choice="req">/path/to/example.php</arg>
   <arg choice="opt">
    <option>startline <arg choice="opt"><option>number of lines</option></arg></option>
   </arg>
   <arg choice="plain">
    <option>}</option>
   </arg>
  </cmdsynopsis>
  <cmdsynopsis>
   <command>{@}example</command>
   <arg choice="req">url://path/to/example.php</arg>
   <arg choice="opt">
    <option>startline <arg choice="opt"><option>number of lines</option></arg></option>
   </arg>
   <arg choice="plain">
    <option>}</option>
   </arg>
  </cmdsynopsis>
  <cmdsynopsis>
   <command>{@}example</command>
   <arg choice="req">relative/path/to/example.php</arg>
   <arg choice="opt">
    <option>startline <arg choice="opt"><option>number of lines</option></arg></option>
   </arg>
   <arg choice="plain">
    <option>}</option>
   </arg>
  </cmdsynopsis>
 </refsynopsisdiv>
 <refsect1 id="{@id description}">
  <title>Description</title>
  <para>Like the {@tutorial tags.example.pkg} tag, the inline example tag can be used to parse an example file for syntax highlighting and linking to documentation.  This versatile tag attempts to read the file from the full path specified, and will accept any path that {@link fopen()} will accept.  phpDocumentor checks the path to ensure that the file retrieved has a valid .php extension as defined in phpDocumentor.ini, and then opens the file.  It will parse the file, and output syntax-highlighted source with line numbers, links to documentation and will then add a link to the documentation to that file.</para>
  <para>If given an absolute path, phpDocumentor will not search for the example file any further.  If given a relative path (no leading c:\ or /) phpDocumentor searches for examples files first in the directory specified by the {@tutorial phpDocumentor.howto.pkg#using.command-line.examplesdir} command-line, if present.  As of phpDocumentor 1.2.1, it will next search for the file in an examples/ subdirectory of the current file's directory.  Otherwise, it will search for a subdirectory named &quot;examples&quot; in the top-level parsing directory, and if not found, in the top-level directory.</para>
  <para>The top-level parsing directory is simply the directory that every file parsed has in common.</para>
  <para>The {@tutorial tags.inlinesource.pkg} tag serves a similar purpose, but instead of parsing a separate file, it parses the current function or method's source.</para>
  <para>The {@}example} tag has two optional parameters, the starting line number to display and the ending line number to display.  If only the first parameter is present, {@}example} will print the source code starting on that line number to the end of the function source code.  If both parameters are present, {@}example} will print an excerpt of the source code beginning on the starting line number, and concluding with the ending line number.</para>
 </refsect1>
 <refsect1 id="{@id example}">
  <title>Example</title>
  <para>Here's an example:</para>
  <para>
   <programlisting role="php">
   <![CDATA[
/**
 * My function
 *
 * Here is an inline example:
 * <code>
 * <?php
 * echo strlen('6');
 * ?>
 * </code>
 * and using an external example file:
 * {@}example /path/to/example.php}
 *
 * Display only the first 2 lines:
 * {@}example /path/to/example.php 0 2}
 * @example /path/to/example.php How to use this function
 * @example anotherexample.inc This example is in the "examples" subdirectory
 */
function mine()
{
}
   ]]>
   </programlisting>
  </para>
 </refsect1>
</refentry>