<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V5.0//EN" "../../docbook/docbook-xml/docbook.dtd">

<article xml:id="article.thequicky.exceptions" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>The quicky; Documenting exceptions</title>
  <section xml:id="article.thequicky.exceptions.environment">
   <title>Setting up the environment</title>
   <para>
    The first thing you should do is get your environment setup to build the
    documentations locally;
   </para>
   <example xml:id="article.thequicky.exceptions.environment.example.setup">
    <title>Getting the sources and installing the tools</title>
    <programlisting role="shell">
<![CDATA[
# Checkout the XML documentation sources
$ svn co http://svn.php.net/repository/phpdoc/modules/doc-en phpdoc

$ cd phpdoc

# Install the PHP based Docbook renderer (PhD)
$ pear channel-discover doc.php.net
$ pear install doc.php.net/phd
$ pear install doc.php.net/phd_php

# Configuring the XML and validate it
$ php doc-base/configure.php

# Render the documentations
$ phd -d doc-base/.manual.xml -P PHP -f xhtml
]]>
    </programlisting>
   </example>

   <para>
    After running the <command>phd</command> command you should now have a
    <emphasis>output/php-xhtml/</emphasis> directory containing few thousands files.
    Feel free to click them and browse the docs in your browser just to make
    sure everything went fine.
   </para>
  </section>

  <section xml:id="article.thequicky.exceptions.thefunpart">
   <title>The fun part; documenting</title>
   <para>
    Copy <filename>doc-base/RFC/skeletons/exceptionname.xml</filename> to
    <filename>en/reference/&lt;extension&gt;/&lt;exceptionname&gt;.xml</filename>
    (replacing <emphasis>&lt;extension&gt;</emphasis> and
    <emphasis>&lt;exceptionname&gt;</emphasis> with the actual exception name
    and extenion directory.
    <note>
     <para>
      All file and directory names <emphasis>SHOULD</emphasis> be lowercased.
     </para>
    </note>
   </para>

   <para>
    Open the file now in your favorite text editor and read through it. It
    contains some comments to guide you through what needs to be changed and
    were to write the documentations.
   </para>
   <para>
    A good file to keep open and learn from is
    <filename>en/language/predefined/errorexception.xml</filename>. If the
    exception you are documenting doesn't define any extra properties then you
    can obviously ignore that part of the file.
   </para>

   <para>
    If the exception introduces new methods, not documented by the inherited
    exceptions, then you'll need to document those too:
   </para>

   <para>
    Create a folder (in <filename>en/reference/&lt;extension&gt;/</filename>)
    with the same name as your <emphasis>&lt;exceptionname&gt;</emphasis>
    previously. Copy <filename>doc-base/RFC/skeletons/method.xml</filename> into that
    folder and rename it to the methodname you will be documenting (all
    lowercased). The file, like <filename>exceptionname.xml</filename>,
    contains lots of comments to guide you through the process.
   </para>
   <para>
    A good file to keep open and learn from is
    <filename>en/language/predefined/errorexception/getseverity.xml</filename>.
   </para>

   <para>
    After having filled out the template/skeletons and written some paragraphs
    its time to add the exceptions to the extension book:
   </para>
   <para>
    Open <filename>en/reference/&lt;extension&gt;/book.xml</filename> and add
    <emphasis>&amp;reference.&lt;extension&gt;.&lt;exceptionname&gt;</emphasis>
    to the end of the list (before <literal>&lt;book&gt;</literal>).
   </para>

  </section>

  <section xml:id="article.thequicky.exceptions.testing">
   <title>Testing and building the changes</title>
   <para>
    Now its time to test the docs!
   </para>
   <example xml:id="article.thequicky.exceptions.testing.example.configure">
    <programlisting role="shell">
<![CDATA[
$ php configure.php
]]>
    </programlisting>
   </example>
   <para>
    If everything worked out OK you should see a message saying <literal>All
    good. Saving .manual.xml... done."</literal>. If you however got
    <literal>Eyh man. No worries. Happ shittens. Try again after fixing the
    errors above.</literal> then check the error messages above and try fixing
    the errors and try again :)
   </para>

   <para>
    Now its time to build the docs:
   </para>
   <example xml:id="article.thequicky.exceptions.testing.example.phd">
    <programlisting role="shell">
<![CDATA[
$ phd -d .manual.xml -t chunkedhtml
]]>
    </programlisting>
   </example>
   <para>
    Now, poke around the <filename>output/php-xhtml/</filename> directory and locate the
    new exception you just documented
    <filename>output/php-xhtml/class.&lt;exceptionname&gt;</filename>.
   </para>
  </section>

  <section xml:id="article.thequicky.exceptions.bragging">
   <title>The important part: Bragging</title>
   <para>
    Now onto the important part: bragging about your achievments and getting
    the documentations committed to the php.net SVN.
   </para>
   <para>
    Create an archive from all the new files you added and put that archive
    online somewhere. Send a quick mail to
    <link xlink:href="mailto:phpdoc@lists.php.net">phpdoc@lists.php.net</link>
    introducing yourself and what you documented, and don't forget to paste in
    the link to the archive :D
   </para>
  </section>

 </article>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"howto.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->