cvs: phpdoc /howto howto.xml /howto/thequicky exceptions.xml
| From: | Hannes Magnusson | 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/<extension>/<exceptionname>.xml</filename>
(replacing <emphasis><extension></emphasis> and
<emphasis><exceptionname></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/<extension>/</filename>)
with the same name as your <emphasis><exceptionname></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/<extension>/book.xml</filename> and add
<emphasis>&reference.<extension>.<exceptionname></emphasis>
to the end of the list (before <literal><book></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.<exceptionname></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
-->