cvs: peardoc / global.ent /en/guide/developers documentation.xml

mj Thu Oct 9 15:55:06 2003 EDT Added files: /peardoc/en/guide/developers documentation.xml Modified files: /peardoc global.ent Log: * Adding a first start for a documentation chapter inside the developers guide. # That's working in progress and thus not part of the build yet. Index: peardoc/global.ent diff -u peardoc/global.ent:1.21 peardoc/global.ent:1.22 --- peardoc/global.ent:1.21 Wed Oct 8 16:34:06 2003 +++ peardoc/global.ent Thu Oct 9 15:55:05 2003 @@ -1,6 +1,6 @@ <!-- -*- SGML -*- - $Id: global.ent,v 1.21 2003/10/08 20:34:06 mj Exp $ + $Id: global.ent,v 1.22 2003/10/09 19:55:05 mj Exp $ Contains global "macros" for all the XML documents. @@ -10,7 +10,7 @@ <!ENTITY url.corba.universe 'http://universe-phpext.sourceforge.net/'> <!ENTITY url.cybermut 'http://www.creditmutuel.fr/centre_commercial/vendez_sur_internet.html'> <!ENTITY url.docbook.book "http://www.docbook.org/"> -<!ENTITY url.docbook.xml "http://www.nwalsh.com/docbook/xml/"> +<!ENTITY url.docbook.xml "http://www.oasis-open.org/docbook/xml/"> <!ENTITY url.docbook.skeleton 'http://pear.php.net/downloads/skeleton.xml'> <!ENTITY url.dsssl "http://www.jclark.com/dsssl/"> <!ENTITY url.efnet "http://www.efnet.org/"> @@ -23,6 +23,7 @@ <!ENTITY url.java.oo 'http://java.sun.com/docs/books/tutorial/java/concepts/'> <!ENTITY url.junit 'http://www.junit.org/'> <!ENTITY url.kadm5 'http://oss.gonicus.de/project/?group_id=7'> +<!ENTITY url.kde 'http://www.kde.org/'> <!ENTITY url.kerberos.info 'http://web.mit.edu/kerberos/www/'> <!ENTITY url.kerberos.docs 'http://web.mit.edu/kerberos/www/krb5-1.2/krb5-1.2.8/doc/admin_toc.html'> <!ENTITY url.libxml 'http://www.xmlsoft.org/'> @@ -37,9 +38,11 @@ <!ENTITY url.phpdoc 'http://www.phpdoc.de/'> <!ENTITY url.phpdocumentor 'http://www.phpdoc.org/'> <!ENTITY url.phplib 'http://sourceforge.net/projects/phplib/'> +<!ENTITY url.php 'http://www.php.net/'> <!ENTITY url.php.anoncvs 'http://www.php.net/anoncvs.php'> <!ENTITY url.php.callback 'http://www.php.net/manual/language.pseudo-types.php'> <!ENTITY url.php.manual 'http://www.php.net/manual/'> +<!ENTITY url.php.manual.howto 'http://www.php.net/dochowto'> <!ENTITY url.php.manual.about 'http://www.php.net/manual/about.php'> <!ENTITY url.php.mailinglists 'http://www.php.net/mailing-lists.php'> <!ENTITY url.php.cvs 'http://cvs.php.net/'> Index: peardoc/en/guide/developers/documentation.xml +++ peardoc/en/guide/developers/documentation.xml <?xml version="1.0" encoding="iso-8859-1" ?> <!-- $Revision: 1.1 $ --> <!-- WORK IN PROGRESS, THERE IS PROBABLY LITTLE POINT IN TRANSLATING THIS DOCUMENT YET. --> <chapter id="developers.documentation"> <docinfo> <author> <firstname>Martin</firstname> <surname>Jansen</surname> </author> </docinfo> <title>Writing documentation</title> <para> This chapter provides a detailed description how to write documentation using one of the supported formats. It is aimed at both PEAR developers that are already maintaining packages in PEAR and at people who are planning to contribute a new package. </para> <sect1 id="developers.documentation.docbook"> <title>Using Docbook XML</title> <titleabbrev>Docbook</titleabbrev> <para> <ulink url="&url.docbook.xml;">Docbook</ulink> is an XML dialect that is used by a wide range of projects to maintain their documentation. Examples for Docbook usage in OpenSource projects are the documentations of <ulink url="&url.kde;">KDE</ulink> and <ulink url="&url.php;">PHP</ulink>. </para> <sect2> <title>Required software</title> <para> Even if Docbook XML can (like any other XML file) be written using a normal text editor, one needs to install some software on their machine in order to test the validity of the documenting efforts. A list of the requires software and a installation instruction can be found <ulink url="&url.php.manual.howto;">PHP Documentation HOWTO</ulink>. Apart from providing information about the software, this HOWTO does also provide a ton of other useful information that goes beyond this chapter. One is encouraged to completely read it. (Chapter II can be skipped, because it only contains information that is very PHP specific.) </para> <para> Once the necessary software is in place, one has to get the latest version of the XML sources from PEAR's CVS repository: </para> <screen> <userinput> &dollar; cvs -d :pserver:&lt;user&gt;@cvs.php.net:/repository login </userinput> [password] <userinput> &dollar; cvs co peardoc </userinput> </screen> <para> After that the directory <filename>./peardoc</filename> will contain a local copy (<quote>sandbox</quote>) of the latest sources. </para> </sect2> <sect2> <title>Directory structure</title> <para> In the directory <filename>peardoc</filename> one will find a bunch of files in the root directory and some subdirectories. The files in the root folder are not important yet. As a first step one should browse through the subdirectory <filename>en</filename>, which contains the english version of the manual. For developers who want to document their packages, only the subdirectory <filename>package</filename> is of importance now. </para> </sect2> </sect1> </chapter> <!-- 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 sgml-parent-document:nil sgml-default-dtd-file:"../../../manual.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 -->