cvs: phpdoc /howto howto.xml /howto/thequicky exceptions.xml

From: Date: Wed, 06 Aug 2008 11:05:56 +0000
Subject: cvs: phpdoc /howto howto.xml /howto/thequicky exceptions.xml
Groups: php.doc.cvs 
Request: Send a blank email to doc-cvs+get-1991@lists.php.net to get a copy of this message
bjori Wed Aug 6 11:05:56 2008 UTC Added files: /phpdoc/howto/thequicky exceptions.xml Modified files: /phpdoc/howto howto.xml Log: Add a quick'n'dirty article on howto document exceptions for first timers http://cvs.php.net/viewvc.cgi/phpdoc/howto/howto.xml?r1=1.56&r2=1.57&diff_format=u Index: phpdoc/howto/howto.xml diff -u phpdoc/howto/howto.xml:1.56 phpdoc/howto/howto.xml:1.57 --- phpdoc/howto/howto.xml:1.56 Mon Jan 7 23:29:39 2008 +++ phpdoc/howto/howto.xml Wed Aug 6 11:05:56 2008 @@ -159,6 +159,13 @@ &howto.preface; + <!-- + "The quicky" series. + Mostly Docbook markupified version of various mails from bjori :] + (Yes. More to come, I hope :) + --> + <xi:include href="thequicky/exceptions.xml" parse="xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <part xml:id="part-getting-started"> <title>Getting Started</title> &howto.framework; http://cvs.php.net/viewvc.cgi/phpdoc/howto/thequicky/exceptions.xml?view=markup&rev=1.1 Index: phpdoc/howto/thequicky/exceptions.xml +++ phpdoc/howto/thequicky/exceptions.xml <?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[ # Login to the CVS server anonymously $ cvs -d:pserver:cvsread@cvs.php.net/repository login # The password is "phpfi", see http://php.net/anoncvs # Checkout the XML documentation sources $ cvs -d:pserver:cvsread@cvs.php.net/repository co phpdoc $ cd phpdoc # Install the PHP based Docbook renderer (PhD) $ pear channel-discover doc.php.net $ pear install doc.php.net/phd-beta # Configuring the XML and validate it $ php configure.php # Render the documentations $ phd -d .manual.xml -t chunkedhtml ]]> </programlisting> </example> <para> After running the <command>phd</command> command you should now have a <emphasis>html/</emphasis> directory containing few thousends 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>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>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>html/</filename> directory and locate the new exception you just documented <filename>html/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 CVS. </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 -->

« previous php.doc.cvs (#1991) next »