Search code examples
phpexternalphpdoc

How to write code block using phpDocumentor, tutorials/extended documentation?

How to write code blocks using phpDocumentor while writing tutorials/extended documentation?

I have tried <programlisting>, it can generate the <code> tag , but it does not parse its contents.

<refentry id="{@id}">  

 <refnamediv>  
  <refname>Guide for MyApp</refname>  
  <refpurpose>To demonstrate ...</refpurpose>  
 </refnamediv>  

 <refsynopsisdiv>  
  <author>  
   My Name
   <authorblurb>  
    {@link [email protected] My Name}  
   </authorblurb>  
  </author>  
 </refsynopsisdiv>  

 {@toc}  
 <refsect1 id="{@id intro}">  
  <title>User Guide for MyApp</title>  

  <para>  
   Some Description
  </para>

      <programlisting>

            $some = 'code';

      </programlisting>

 </refsect1>
</refentry>
Solution

  • This is actually very easy once you know how. You just need to set the role attribute on the programlisting element.

    <programlisting role="php">
  $some = 'code';
</programlisting>

    I couldn't find this documented anywhere, other than a brief mention in the release notes, but from looking at the code, there seem to be four roles that are supported:

    1. php - adds PHP syntax highlighting to the content and includes a line number on every line.
    2. tutorial - adds HTML syntax hightlighting to the content and includes a line number on every line.
    3. xml - adds pre tags around the content, but otherwise no syntax hightlighting and no line numbers.
    4. html - treats the content as raw HTML, so you can use whatever markup you like.

    Any time you want to use angle brackets, though, you will need to escape those characters or wrap the content in a CDATA section. This even applies when you want to use raw HTML. If not, the parser will try and interpret the content as XML.

    For example, a raw HTML sample would look something like this:

    <programlisting role="html">
  <![CDATA[
    <b>This sentence will be bold.</b>
  ]]>
</programlisting>

    Also note that all of this applies to the initial version of phpDocumentor. The new version (phpDocumentor 2) doesn't appear to support tutorials/extended documentation as far as I can tell.