cvs: peardoc /en/guide/developers documentation.xml /entities global.ent
[email protected] ("Christian Weiske")
| Newsgroups | php.pear.doc |
|---|---|
| Message-ID | <cvscweiske1241346418@cvsserver> |
cweiske Sun May 3 10:26:58 2009 UTC
Modified files:
/peardoc/en/guide/developers documentation.xml
/peardoc/entities global.ent
Log:
New documentation chapter - we use PhD now.
cweiske-20090503102658.txt
(text/plain, 48.2 KB)
http://cvs.php.net/viewvc.cgi/peardoc/en/guide/developers/documentation.xml?r1=1.50&r2=1.51&diff_format=u Index: peardoc/en/guide/developers/documentation.xml diff -u peardoc/en/guide/developers/documentation.xml:1.50 peardoc/en/guide/developers/documentation.xml:1.51 --- peardoc/en/guide/developers/documentation.xml:1.50 Thu Oct 9 15:16:18 2008 +++ peardoc/en/guide/developers/documentation.xml Sun May 3 10:26:58 2009 @@ -1,716 +1,484 @@ -<?xml version="1.0" encoding="utf-8"?> -<chapter xmlns="http://docbook.org/ns/docbook" version="lillet" xml:id="developers.documentation"> +<?xml version="1.0" encoding="UTF-8"?> +<chapter version="5.0" xml:id="developers.documentation" + xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink"> + <title>Documentation</title> + + <para>The documentation is a critical part of PEAR. The most interesting and + helpful package will not be used if there is no proper documentation that + tells users what the package is for and how to use it.</para> + + <para>Documentation for a package in PEAR means two things:</para> + + <itemizedlist> + <listitem> + <para>API documentation that explains all classes, methods and functions + a package provides</para> + </listitem> + + <listitem> + <para>Chapters and paragraphs about the package itself: What the package + can be used for, how to use it, and examples.</para> + </listitem> + </itemizedlist> + + <para>API documentation is automatically generated after a package has been + released on pear.php.net from the code using phpDocumentor.</para> + + <para>The second type of documentation needs to be created manually. It is + the documentation you see in this very manual below the <link + linkend="packages">packages</link> book.</para> + + <para>At first you will learn how to <link + linkend="developers.documentation.sources">obtain</link> and <link + linkend="developers.documentation.building">render</link> this manual before + going into detail about <link + linkend="developers.documentation.writing">writing documentation</link> for + your own package.</para> + + <section xml:id="developers.documentation.sources"> + <title>Obtaining the manual sources</title> - <info><title>Writing documentation</title><titleabbrev>Documentation</titleabbrev> - <author><personname><firstname>Daniel</firstname><surname>Convissor</surname></personname></author> - <author><personname><firstname>Martin</firstname><surname>Jansen</surname></personname></author> - </info> - - - - - <para> - This chapter provides a detailed description of 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> - - <section xml:id="developers.documentation.docbook"><info><title>The DocBook XML format</title><titleabbrev>DocBook XML</titleabbrev></info> - - - - <para> - <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.docbook.xml;">DocBook</link> 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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.kde;">KDE</link> and - <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.php;">PHP</link>. - - PEAR has opted for using DocBook, because we believe that it provides - a solid foundation for the technical documentation for PEAR packages. - </para> - - <para> - The trade-off for using DocBook is that it is relatively hard to use. - - Testing documentation requires a number of tools to be installed and one - needs to learn a (not very complicated) XML dialect. - - Once one is familiar with how DocBook works, they will - enjoy writing documentation with it though. - </para> - <para> - The book <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.docbook.book;"><citation>DocBook: The - Definitive Guide</citation></link>, written by Norman Walsh and - Leonard Muellner and published by <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.oreilly;">O'Reilly & Associates, Inc.</link>, is - <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.docbook.book.read;">available online</link> and it - makes up a great resource for people interested in learning DocBook. - </para> - <para> - Definitely check out the book's - <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.docbook.book.reference;"> - <quote>DocBook Element Reference</quote></link> section. - This portion provides detailed information about - <emphasis>each</emphasis> element, including which elements - can (and must) be used as parents and children. - </para> - - <section xml:id="developers.documentation.software"><info><title>Required software</title></info> - - - <para> - Even if DocBook XML can (like any other XML file) be written using - a normal text editor, it is optimal for users to install some - software on their machine in order to test the validity - of the documenting efforts. - - A list of the required software and installation - instructions can be found in the - <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.php.manual.howto;">PHP Documentation - HOWTO</link>. - - Apart from providing information about the software, - this HOWTO also provides a ton of other useful - information that goes far beyond this chapter. - - One is encouraged to read it completely. - (Chapter II can be skipped, because it only - contains information that is very PHP specific.) - - <note><info><title>Installation on OS X</title></info> - - <para> - The PHP Documentation HOWTO advises users of Mac OS X to use - packages provided by Fink. Alternatively packages from the - <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.macports;">MacPorts</link> project can be - used. After installing MacPorts, the toolchain can be - installed using the following command: - - <informalexample> - <programlisting> - <command> -sudo port install openjade docbook-dsssl - </command> - </programlisting> - </informalexample> - </para> - </note> - </para> - - <para> - Unfortunately, installing that software can be difficult - under some circumstances. - - If you are unable to get it working, - don't use that as an excuse for not writing documentation. - - There are two test servers that automatically download peardoc - from CVS and build the manual. - - Any parsing errors your changes cause will show up in the logs - the next time the build happens: - <simplelist> - <member> - <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.doc.test.build.1;">Build from Brett Bieber</link> - (<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.doc.test.build.1.log;">log</link>) - (updated every two hours) - </member> - <member> - <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.doc.test.build.2;en/">Build from TAKAGI Masahiro</link> - (<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.doc.test.build.2;en/build.log">log</link>) - (updated daily at 06:00 JST = 21:00 UTC) - </member> - </simplelist> - - These automatic builds also give you - an idea of what your changes will look like in - the actual manual. - - This is helpful because the manual on the PEAR website is only built once - per week (Sundays ~12:00 UTC). - - <warning> - <para> - The manual on the PEAR website is built only once per week. - - Any XML validation errors will cause the build to fail. - - If the main build fails, the old version remains in place, - meaning the manual will be out of date. - - Therefore, <emphasis>always</emphasis> check the test build logs - to ensure your changes are valid. - - More importantly, <emphasis>do not commit updates shortly before the - main build happens (Sundays ~12:00 UTC).</emphasis> - </para> - </warning> - </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> -$ cvs -d :pserver:<user>@cvs.php.net:/repository login - </userinput> - <replaceable> + <para>The Docbook XML sources of the documentation are hosted on php.net's + CVS server in the <literal>peardoc</literal> module.</para> + + <para>The checkout process is relatively simple:</para> + + <screen><![CDATA[$ cvs -d :pserver:<user>@cvs.php.net:/repository login [password] - </replaceable> - <userinput> -$ cvs -d :pserver:<user>@cvs.php.net:/repository co peardoc - </userinput> - </screen> - - <para> - If you do not own an account for cvs.php.net, please choose - <userinput>cvsread</userinput> as the username. - - When asked for the password, type <userinput>phpfi</userinput>. - </para> - - <para> - After that the directory <filename>./peardoc</filename> will - contain a local copy (<quote>sandbox</quote>) of the latest sources. - - If you are not yet familiar with CVS, then the online - book <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.cvs.book;"><quote>Open Source Development - with CVS</quote></link> will provide you with all the necessary - information. - </para> - </section> - - <section xml:id="developers.documentation.structure"><info><title>Directory structure</title></info> - - - <para> - This chapter will not describe all the details about the directory - structure, because one can find out the essentials about it by - browsing the previously created directory - <filename>peardoc</filename>. - - As a starting point for package - documenters <filename>peardoc/en/package/</filename> fits well. - - If one has further questions concerning the directory structure, they - can ask on the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="mailto:&email.pear.doc;">documentation - mailinglist</link>. - </para> - </section> - - <section xml:id="developers.documentation.writing"><info><title>Writing documentation</title></info> - - - <para> - Instead of a long and boring description for writing documentation - using DocBook, we would like to point you to a bunch of - <quote>reference documents</quote>, from which you should be - able to learn quickly: +$ cvs -d :pserver:<user>@cvs.php.net:/repository co +peardoc]]></screen> + + <para>Details about this process as well as anonymous login data can be + found on <link xlink:href="&url.php.anoncvs;">php.net's CVS + page</link>.</para> + + <note> + <para>You need rights for the <literal>peardoc</literal> CVS module to + be able to commit. Along with pear karma, every developer should have + gotten the appropriate rights to <literal>peardoc</literal>. This is how + it should be in theory, but one will probably have to send a mail to + [email protected] asking for documentation karma.</para> + </note> + </section> + + <section xml:id="developers.documentation.building"> + <title>Rendering the manual</title> + + <para>The PEAR documentation gets - like the PHP Manual - built using + PHP's very own DocBook rendering system called PhD. Installation is a + breeze using pear:</para> + + <screen><![CDATA[$ pear install doc.php.net/phd-beta +... +$ phd --version +PhD version: phd-from-cvs +Copyright (c) 2007-2009 The PHP Documentation Group]]></screen> + + <note> + <para>When using PEAR before verson 1.8.0, you need to <link + linkend="guide.users.commandline.channels.discovery">discover the + channel</link> first.</para> + </note> + + <para>Besides that, one only needs a <link + linkend="developers.documentation.sources">CVS checkout of the peardoc + module</link>.</para> + + <section xml:id="developers.documentation.building.preparing"> + <title>Preparing the build</title> + + <para>Before building, you need to use the + <filename>configure.php</filename> script provided by + <filename>peardoc</filename>. This script serves two purposes:</para> + + <itemizedlist> + <listitem> + <para>Validate XML</para> + </listitem> + + <listitem> + <para>Combine all xml files into one large single file to speed up + the build process</para> + </listitem> + </itemizedlist> + + <para>Just change into your <filename> peardoc </filename> source folder + and run:</para> + + <screen><![CDATA[$ php configure.php +Generating chapters.ent for en + 3376 xml files + 6 php example files + done +Loading manual into one giant file +Validating done +Now call phd: phd -L en -f xhtml -t pearchunkedhtml -o build/en -d .manual.xml]]></screen> + + <para>If you see that lines, everything is fine and you can continue + compiling the manual.</para> + + <note> + <para>Like with every proper unix tool, you can use <command>php + configure.php --help</command> to get an overview about the supported + command line parameters.</para> + </note> + + <para>In case something goes wrong, the config script will tell you + either where it failed, or which commands to execute to find the right + spot:</para> + + <screen><![CDATA[$ php configure.php +Generating chapters.ent for en + 3376 xml files + 6 php example files + done +Loading manual into one giant file +There were warnings loading the manual Warning: + DOMDocument::load(): Opening and ending tag mismatch: + set line 46 and book in + /home/cweiske/Dev/cvs/pear/peardoc/manual.xml, line: 67 in + /home/cweiske/Dev/cvs/pear/peardoc/configure.php on line 278 +.... +Exception: Failed to load manual.xml]]></screen> + + <para>Fix the error and run <filename>configure.php</filename> again + until it tells you everything is ok.</para> + </section> + + <section xml:id="developers.documentation.building.compiling"> + <title>Compiling the manual</title> + + <para>Now that you configured everything properly, run the command that + <filename>configure.php</filename> told you. The command will be + something along that:</para> + + <screen>$ phd -L en -f xhtml -t pearchunkedhtml -o build/en/ -d .manual.xml</screen> + + <note> + <para><filename>configure.php</filename> generated a giant manual file + named <filename>.manual.xml</filename>. If you use plain + <filename>manual.xml</filename> your build will take about double as + long as with <filename>.manual.xml</filename> (note the leading + dot).</para> + </note> + + <para>When PhD doesn't report any errors, your generated HTML + documentation will be available in + <filename>build/en/html/</filename>.</para> + + <section> + <title>Partial builds</title> + + <para>When writing documentation for a single package, you probably + don't always want to compile the whole manual. PhD allows you to + compile a small part of the manual which is faster than doing the + whole thing. Just pass "<literal>-p + package.category.packagename</literal>" as parameter to PhD, and only + the part of the manual below that ID will be created.</para> + + <note> + <para>At the time of writing, partial rendering in PhD is not + noticable faster than creating the whole manual. This will change in + the future, though.</para> + </note> + + <tip> + <para>In case you didn't change the structure (adding or removing + IDs), you can skip PhD index creation (<literal>-I</literal>) which + will save you about 15-20 seconds build time.</para> + </tip> + </section> + </section> + + <section xml:id="developers.documentation.building.buildservers"> + <title>Other sources to test your documentation</title> + + <para>Several PEAR members regularly build the documentation on their + own machine in shorter cycles than the pear.php.net server. When you + don't have the chance to test and build your changes, you can use any of + this build servers to check everything is fine:</para> + + <table> + <title>Regular builds provided by PEAR members</title> + + <tgroup cols="4"> + <thead> + <row> + <entry>PEAR member</entry> + + <entry>Build interval</entry> + + <entry>Format</entry> + + <entry>Build log</entry> + </row> + </thead> + + <tbody> + <row> + <entry><link xlink:href="&url.pear.developer;saltybeagle">Brett Bieber</link></entry> + + <entry>2 hours</entry> + + <entry><link xlink:href="&url.pear.docbuild.brett.chunk;">Chunked + HTML</link></entry> + + <entry><link xlink:href="&url.pear.docbuild.brett.log;">log</link></entry> + </row> + </tbody> + </tgroup> + </table> + </section> + </section> + + <section xml:id="developers.documentation.docbook"> + <title>Docbook XML</title> + + <para><link xlink:href="&url.docbook.book;">DocBook</link> 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 <link + xlink:href="&url.kde;">KDE</link> and <link xlink:href="&url.php;">PHP</link>. PEAR has + opted for using DocBook because we believe that it provides a solid + foundation for the technical documentation for PEAR packages.</para> + + <para>The trade-off for using DocBook is that it is relatively hard to + use. Testing documentation requires a special tool to be installed and one + needs to learn a (not very complicated) XML dialect. Once one is familiar + with how DocBook works they will enjoy writing documentation with it + though.</para> + + <para>The book <link xlink:href="&url.docbook.book.read;">DocBook: The Definitive + Guide</link>, written by Norman Walsh and Leonard Muellner and + published by <link xlink:href="&url.oreilly;">O'Reilly & + Associates, Inc.</link>, is <link + xlink:href="&url.docbook.book.read;">available online</link> and it + makes up a great resource for people interested in learning + DocBook.</para> + + <para>Definitely check out the book's <link + xlink:href="&url.docbook.book.reference;">DocBook + Element Reference</link> section. This portion provides detailed + information about <emphasis>each</emphasis> element, including which + elements can (and must) be used as parents and children.</para> + </section> + + <section xml:id="developers.documentation.writing"> + <title>Writing documentation</title> + + <para>Instead of a long and boring description for writing documentation + using DocBook, we would like to point you to a bunch of "reference + documents", from which you should be able to learn quickly:</para> + + <itemizedlist> + <listitem> + <para><link + linkend="package.console.console-progressbar">Console_ProgressBar</link> + - small documentation for a small package</para> + </listitem> + + <listitem> + <para><link + linkend="package.system.system-daemon">System_Daemon</link> - medium + sized documentation on several pages</para> + </listitem> + </itemizedlist> + + <para>The scope of your package's documentation should be:</para> - <itemizedlist> + <itemizedlist> <listitem> - <simpara> - <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.php.cvs.peardoc.authoring;">peardoc/en/authoring</link> - </simpara> - <simpara> - The CVS tree has a complete set of DocBook XML templates. - These files provide the standard of how PEAR - documentation should look. - </simpara> - <simpara> - The simplest way to utilize them is to copy them to - your working directory, rename them accordingly, edit - the contents to match the reality of your program and - then upload them to your package's directory in the - repository. - </simpara> + <para>Explain which problem your package solves</para> </listitem> + <listitem> - <simpara> - <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.pear.cvs.peardoc;en/package/http/http-request/">HTTP - Request</link> - </simpara> - <simpara> - The documentation for <classname>HTTP_Request</classname>, which - is a relatively small package, only consists of a bunch of - end-user documentation, which describes all of the basic - features of the package. - - Each feature description includes at - least one example. - - For small packages with only a handful of - methods this documentation type is absolutely enough. - </simpara> + <para>Describe differences to other packages solving identical or + similar problems</para> </listitem> + <listitem> - <simpara> - <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.pear.cvs.peardoc;en/package/xml/xml-beautifier/">XML - Beautifier</link> - </simpara> - <simpara> - <classname>XML_Beautifier</classname> is a package that is also - relatively compact, but which supports different configuration - options. - - These options are described in the documentation - Additionally the documentation gives usage examples and - (unlike <classname>HTTP_Request</classname>) also - includes API documentation for its methods. - </simpara> + <para>Give example how to use the package</para> </listitem> + <listitem> - <simpara> - <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.pear.cvs.peardoc;en/package/database/db/">DB</link> - </simpara> - <simpara> - <classname>DB</classname> is a large PEAR package and has - excellent documentation, including usage examples. - The <classname>DB</classname> docs carefully adhere - to the formatting specified in peardoc/authoring. - The link above goes to the DocBook source code in - the CVS repository. - - It might be helpful to examine - <link linkend="package.database.db">the HTML generated therefrom</link>. - </simpara> + <para>(Maybe) give an introduction to concepts your package uses and + that the user probably does not know/is not aware of</para> </listitem> - </itemizedlist> - </para> - <para> - In addition to the examples above, you will find much more - documentation examples by browsing the <filename>peardoc</filename> - directory, which contains your local version of the CVS - tree. - - Especially the directory - <filename>peardoc/en/packages/</filename> should be of interest for you. - - You can also browse the CVS module using the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.pear.cvs.peardoc;">web interface</link>, including the - <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.pear.cvs.peardoc;en/guide/developers/documentation.xml">raw - XML for the file you are presently reading</link>. - </para> - - <section xml:id="developers.documentation.writing.phpdocumentor"><info><title>Using phpDocumentor to generate documentation templates</title></info> - - - <para> - Creating dozens of files, one for each function in each class of your - package is rather boring. Luckily, we have the PhpDocumentor in PEAR - which has a renderer to generate templates for your classes and methods. - </para> - - <para> - Create a test directory and cd into it. Then, run the following command: - <command> - phpdoc -p on -f /path/to/my/package/source/File.php -t . - -o "XML:DocBook/peardoc2:default" -dc myPackageCategory - </command> - After creating the files, check if they are all ok and edit them - add - examples, additional documentation and remove unnecessary sections. - </para> - - <note> - <para> - <command>phpdoc</command> generates - <emphasis>documentation templates</emphasis>. The generated docs are - by no means complete, you need to edit them afterwards! - </para> - </note> + </itemizedlist> + + <para>The documentation should not repeat the API docs! You should only + <link xlink:href="&url.phd.pearapi;">link to + it</link>. The documentation for older packages often contains the whole + API reference, but that is not the manual's scope anymore - phpDocumentor + does a much better job at generating it automatically.</para> + + <section xml:id="developers.documentation.writing.filestructure"> + <title>Package documentation file structure</title> + + <table> + <title>Files in peardoc</title> + + <tgroup cols="2"> + <thead> + <row> + <entry>Filename</entry> + + <entry>Description</entry> + </row> + </thead> + + <tbody> + <row> + <entry><filename>packages/</filename></entry> + + <entry>Directory containing all package-specific + documentation</entry> + </row> + <row> + <entry><filename> category.xml</filename></entry> + + <entry>Description of a category</entry> + </row> + + <row> + <entry><filename> category-entities.xml</filename></entry> + + <entry>File with links to all packages in that category. Exists + in english documentation only.</entry> + </row> + + <row> + <entry><filename> category/</filename></entry> + + <entry>Directory with documentation of packages in that + category</entry> + </row> + + <row> + <entry><filename> package.xml</filename></entry> + + <entry>Main file for documentation of a specific package</entry> + </row> + + <row> + <entry><filename> package/</filename></entry> + + <entry>Files for the package documentation are collected in + here, e.g. <filename>examples.xml</filename></entry> + </row> + </tbody> + </tgroup> + </table> </section> - </section> + <section xml:id="developers.documentation.writing.committing"> + <title>Committing changes into CVS</title> - <section xml:id="developers.documentation.testing"><info><title>Testing documentation</title></info> - + <para>Before committing your changes into peardoc CVS, test and build + it! This is absolutely necessary - it makes sure that other people + writing documentation can build the manual without problems, and that + the official pear.php.net build works.</para> + + <warning> + <para>The manual on pear.php.net is build once a week, 12:00 UTC every + sunday. If it breaks, it will take a whole week until the next build + attempt is made!</para> + + <para>So do <emphasis>not</emphasis> commit updates shortly before the + main build happens.</para> + </warning> + </section> - <section xml:id="developers.documentation.testing.make"><info><title> - Using <acronym>GNU</acronym> <command>make</command> - </title></info> - - - <para> - Generating human-readable versions of the DocBook sources requires - the existence of the above-mentioned software. - The PEAR documentation system uses Unix style makefiles: - </para> - - <screen> - <userinput> -peardoc$ autoconf -peardoc$ ./configure --with-lang=<replaceable>en</replaceable> -peardoc$ make html - </userinput> - </screen> - - <para> - If you want to build a language other than English, - change <literal>en</literal>, above, to - the appropriate language code. - </para> - - <para> - It may be that the DSSSL stylesheets are not found, resulting - in the message - </para> - <screen> -checking for docbook.dsl... defaulting - WARNING!!! -DSSSL NOT FOUND - WON'T WORK THIS WAY - </screen> - <para> - In this case make sure you've installed the DSSSL packages. - On a Mac using Fink, you might have to specify the location - yourself: - <command>./configure --with-dsssl=/sw/share/sgml/dsssl/docbook-dsssl-nwalsh</command> - </para> - <para> - On Windows, the easiest way to get the DSSSL sheets is to check out - the <literal>phpdoc</literal> module on cvs.php.net - they can be - found in the <filename>dsssl/</filename> subdirectory. - </para> - - <para> - This will generate a "raw" <acronym>HTML</acronym> - version of the whole manual. - - The result will be placed in the subdirectory - <filename>html/</filename>. - </para> - - <para> - The command <command>make test</command> does not generate any - human-readable result, but it can be used to make sure that the - <acronym>XML</acronym> is syntactically correct and that the build - runs fine. - - And it is much faster than <command>make html</command>. - </para> - - <section><info><title>Problems when using <command>make html</command></title></info> - - - <para> - Numerous developers have reported problems when using the - <command>make html</command> command, namely that the output - was not written to a file but instead dumped on the console. - If you encounter this problem and have checked out the DocBook - sources into e.g. <filename>/home/you/cvs/peardoc</filename>, - checkout the <literal>phpdoc</literal> module (using the - procedure described above) into - <filename>/home/you/cvs/phpdoc</filename>, and run - <command>make html</command> again. - </para> - </section> - </section> + <section xml:id="developers.documentation.writing.tips"> + <title>Tips for good documentation</title> - <section xml:id="developers.documentation.testing.xmllint"><info><title>Using <command>xmllint</command></title></info> - + <para>This section of the chapter does not deal with the specifics of + organizing documentation in the peardoc standard, but instead with how + to organize documentation logically.</para> + + <orderedlist> + <listitem> + <para>Every package solves a problem. What is this problem? Try to + figure out what assumptions your end-users might not have about the + problem (they may not realize that this is a problem that needs + solving). For instance, a template package solves the problem of + both separating design from code, and separating business logic from + display logic. If possible, explain the problem in terms that even a + novice programmer can understand.</para> + </listitem> + + <listitem> + <para>Next, how does the package uniquely solve the problem? This is + something that most documentation lacks. For example, there are many + template engines. All of them solve the same problem, but none of + them do it in the same way. A block-based template engine does not + have any logic at all, whereas a template like Smarty defines a + whole new template language. Some template engines compile their + templates, others don't. What is unique about your package? Can + someone who has never seen the code get a good idea of how it solves + the problem?</para> + </listitem> + + <listitem> + <para>Provide examples! Start right away with simple examples that + show the basic feature set -- they will show users how to quickly + start using the package. More complex examples will help the users + in understanding advanced ways of using the package.</para> + </listitem> + + <listitem> + <para>If your package exposes complex interfaces or multiple + constants that can't be fully explained in one or two examples + (which is very likely), it is still important to explain them + thoroughly in the documentation. Document any interfaces that users + must use, such as a database DSN, command-line arguments for + applications, configuration file contents, or any other non-code + elements.</para> + </listitem> + + <listitem> + <para>Last, proofread your documentation. If possible, have someone + else who is not as familiar with your project take a look at the + documentation. They will catch assumptions that you have + missed.</para> + </listitem> + </orderedlist> + </section> - <para> - Alternatively one can use the - <command><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.libxml.xmllint;">xmllint</link></command> - program that is part of the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.libxml;">libxml2 - toolkit</link>. - - This is especially useful for systems where - the <acronym>DSSSL</acronym>/<command>make</command> setup - does not work properly. - </para> - - <para> - In addition to testing the well-formedness of the DocBook sources, - <command>xmllint</command> can also check the semantical - correctness with the help of RELAX NG schemas. - - The schema files for DocBook are available as a ZIP package from - <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.docbook.schema;">docbook.org</link>. - After unzipping the package into the directory - <filename>relaxng/</filename> inside the <filename>peardoc</filename> - source folder, one can run <command>xmllint</command> from the root - folder of the PEAR documentation as follows: - </para> - - <para> - <command> - xmllint --valid --noout --relaxng relaxng/ manual.xml - </command> - </para> - </section> - - <section xml:id="developers.documentation.testing.partial"><info><title>Partial builds</title></info> - - - <para> - The build process (not the test builds, which are reasonably - quick) actually takes a very long time which makes - debugging and testing a very hard task. - - In order to increase build performance, the script - <filename>make-partial.php</filename> in - the root directory of the documentation module may be used. - - This is an interactive command line script that will enable to you to - selectively include the different parts of the manual. - - In the following example a version of the manual is generated - which only contains a certain part of the Developer's Guide and the - documentation for the <acronym>HTTP</acronym> packages. - - Using these partial builds reduces the build time dramatically. - </para> - - <screen> - <userinput> -peardoc$ ./make-partial.php -Include about-pear? [NO] -Include guide-newmaint? [NO] -Include guide-developers? [NO] y -Include guide.developers.intro? [NO] -Include guide.developers.meaning? [NO] -Include guide.developers.contributing? [NO] -Include guide.developers.packagedef? [NO] -Include guide.developers.release? [NO] -Include guide.developers.supporting? [NO] -Include guide.developers.recommendations? [NO] -Include guide.developers.documentation? [NO] y -Include core? [NO] -Include packages? [NO] y -Include package.authentication? [NO] -Include package.benchmarking? [NO] -Include package.caching? [NO] -Include package.configuration? [NO] -Include package.console? [NO] -Include package.database? [NO] -Include package.datetime? [NO] -Include package.encryption? [NO] -Include package.fileformats? [NO] -Include package.filesystem? [NO] -Include package.gtk? [NO] -Include package.html? [NO] -Include package.http? [NO] y -Include package.images? [NO] -Include package.internationalization? [NO] -Include package.logging? [NO] -Include package.mail? [NO] -Include package.math? [NO] -Include package.networking? [NO] -Include package.numbers? [NO] -Include package.payment? [NO] -Include package.pear? [NO] -Include package.php? [NO] -Include package.science? [NO] -Include package.streams? [NO] -Include package.structures? [NO] -Include package.system? [NO] -Include package.text? [NO] -Include package.tools? [NO] -Include package.xml? [NO] -Include package.webservices? [NO] -CONFIG_FILES=manual.xml CONFIG_HEADERS= ./config.status -creating manual.xml -/usr/bin/jade -wno-idref -d html.dsl -V use-output-dir -t sgml ./phpdocxml.dcl manual.xml - </userinput> - </screen> - - <para> - In <filename>make-partial.php</filename>, takes a long time to - complete all questions. <command>make partial</command> with the correct - parameters is much faster, e.g. - <command>make partial INCLUDE="packages package.database"</command>. - The full list of IDs can be obtained by inspecting the output of - make. - </para> - </section> - </section> - - <section xml:id="developers.documentation.translating"><info><title>Translating documentation</title></info> - - <para> - Translating documentation is another important task. - Existing translations need to be brought - up to date because the English versions have been changed. - Help on how to perform the translation process is in the <link linkend="faq.translators-revision-tracking">Revision Tracking</link> - section of the manual. - </para> - <table><title> - Daily test builds for the translations (provided by TAKAGI Masahiro) - </title> - - <tgroup cols="4"> - <thead> - <row> - <entry>Language</entry> - <entry>Build</entry> - <entry>Log</entry> - <entry>Revcheck</entry> - </row> - </thead> - <tbody> - <row> - <entry>English</entry> - <entry> - <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.doc.test.build.2;en/">Build</link> - </entry> - <entry> - <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.doc.test.build.2;en/build.log">Log</link> - </entry> - <entry> - <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.doc.test.build.2;en/revcheck.html">Revcheck</link> - </entry> - </row> - <row> - <entry>French</entry> - <entry> - <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.doc.test.build.2;fr/">Build</link> - </entry> - <entry> - <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.doc.test.build.2;fr/build.log">Log</link> - </entry> - <entry> - <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.doc.test.build.2;fr/revcheck.html">Revcheck</link> - </entry> - </row> - <row> - <entry>German</entry> - <entry> - <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.doc.test.build.2;de/">Build</link> - </entry> - <entry> - <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.doc.test.build.2;de/build.log">Log</link> - </entry> - <entry> - <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.doc.test.build.2;de/revcheck.html">Revcheck</link> - </entry> - </row> - <row> - <entry>Japanese</entry> - <entry> - <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.doc.test.build.2;">Build</link> - </entry> - <entry> - <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.doc.test.build.2;build.log">Log</link> - </entry> - <entry> - <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.doc.test.build.2;revcheck.html">Revcheck</link> - </entry> - </row> - </tbody> - </tgroup> - </table> - </section> - - <section xml:id="developers.documentation.questions"><info><title>Questions?</title></info> - - - <simpara> - We are well aware that we cannot cover all questions about writing - DocBook documentation in this chapter. - - If you have more questions or problems, - do not hesitate to get in touch with the documentation - team at <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="mailto:&email.pear.doc;">&email.pear.doc;</link>. - To join the pear-doc list send an email to <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="mailto:&email.pear.doc-subscribe;">&email.pear.doc-subscribe;</link>. - </simpara> - - <para> - Also consider reading the <link linkend="faq.documentation">Documentation - FAQ</link>. - </para> - </section> + <section xml:id="developers.documentation.writing.software"> + <title>Software assistance</title> + <para>PEAR documentation is mostly written using plain text editors like + <literal>vim</literal> or <literal>Kate</literal>. XML editors mostly + don't help enough to be more useful than text editors; plus no tool yet + is able to work with the entity linking structure used in + peardoc.</para> + + <para>One way to get documentation easily is writing initial package + documentation using an XML editor like XXE, and make the necessary + adjustments for peardoc after that. After doing that, you probably won't + be able to use the XML editor anymore without losing data.</para> + </section> </section> - <section xml:id="developers.documentation.tips"><info><title>Tips for good documentation</title><titleabbrev>Documentation Tips</titleabbrev></info> + <section xml:id="developers.documentation.translating"> + <title>Translating PEAR's documentation</title> + + <warning> + <para>FIXME</para> + </warning> + </section> - - + <section xml:id="developers.documentation.questions"> + <title>Questions?</title> - <para> - This section of the chapter does not deal with the specifics of - organizing documentation in the <literal>peardoc</literal> standard, - but instead with how to organize documentation logically. - </para> - - <para> - <orderedlist> - <listitem> - <para> - First, every package solves a problem. - - What is this problem? - - Try to figure out what assumptions your end-users might not have - about the problem (they may not realize that this is a problem - that needs solving). - - For instance, a template package solves the problem of both separating - design from code, and separating business logic from display logic. - - If possible, explain the problem in terms that even a novice - programmer can understand. - </para> - </listitem> - <listitem> - <para> - Next, how does the package uniquely solve the problem? This is - something that most documentation lacks. - - For example, there are many template engines. - - All of them solve the same problem, but - none of them do it in the same way. - - A block-based template engine does not have any logic at all, - whereas a template like Smarty defines a whole new template language. - - Some template engines compile their templates, others don't. - - What is unique about your package? - - Can someone who has never seen the code get a good idea - of how it solves the problem? - </para> - </listitem> - <listitem> - <para> - Provide examples! Start right away with simple examples that - show the basic feature set -- they will show users how to - quickly start using the package. - - More complex examples will help the users in understanding advanced - ways of using the package. - </para> - </listitem> - <listitem> - <para> - If your package exposes complex interfaces or multiple constants - that can't be fully explained in one or two examples (which is - very likely), it is still important to explain them thoroughly - in the documentation. - - Document any interfaces that users must use, such - as a database DSN, command-line arguments for applications, - configuration file contents, or any other non-code elements. - </para> - </listitem> - <listitem> - <para> - Last, proofread your documentation. - - If possible, have someone else who is not as familiar with your project - take a look at the documentation. - - They will catch assumptions that you have missed. - </para> - </listitem> - </orderedlist> - </para> + <para>We are well aware that we cannot cover all questions about writing + DocBook documentation in this chapter. If you have more questions or + problems, do not hesitate to get in touch with the documentation team at + <link + xlink:href="mailto:&email.pear.doc;">&email.pear.doc;</link>. + To join the <literal>pear-doc</literal> list send an email to <link + xlink:href="mailto:&email.pear.doc-subscribe;">&email.pear.doc-subscribe;</link>.</para> </section> - </chapter> +</chapter> http://cvs.php.net/viewvc.cgi/peardoc/entities/global.ent?r1=1.11&r2=1.12&diff_format=u Index: peardoc/entities/global.ent diff -u peardoc/entities/global.ent:1.11 peardoc/entities/global.ent:1.12 --- peardoc/entities/global.ent:1.11 Fri Jan 23 13:21:05 2009 +++ peardoc/entities/global.ent Sun May 3 10:26:58 2009 @@ -1,6 +1,6 @@ <!-- -*- SGML -*- - $Id: global.ent,v 1.11 2009/01/23 13:21:05 izi Exp $ + $Id: global.ent,v 1.12 2009/05/03 10:26:58 cweiske Exp $ Contains global "macros" for all the XML documents. @@ -16,8 +16,8 @@ <!ENTITY url.debian.apt 'http://www.debian.org/doc/manuals/apt-howto/'> <!ENTITY url.delicious 'http://del.icio.us/'> <!ENTITY url.docbook.book "http://www.docbook.org/"> -<!ENTITY url.docbook.book.read "http://www.docbook.org/tdg/"> -<!ENTITY url.docbook.book.reference "http://www.docbook.org/tdg/en/html-ng/part2.html"> +<!ENTITY url.docbook.book.read "http://www.docbook.org/tdg5/"> +<!ENTITY url.docbook.book.reference "http://www.docbook.org/tdg5/en/html/ref-elements.html"> <!ENTITY url.docbook.xml "http://www.oasis-open.org/docbook/xml/"> <!ENTITY url.docbook.schema "http://www.docbook.org/rng/4.3/"> <!ENTITY url.doc.test.build.1 'http://ucommbieber.unl.edu/peardoc/build/html/'> @@ -77,6 +77,7 @@ <!ENTITY url.maxmind 'http://www.maxmind.com/'> <!ENTITY url.maxmind.db.free 'http://www.maxmind.com/app/geoip_country'> <!ENTITY url.maxmind.db.nonfree 'http://www.maxmind.com/app/products'> + <!ENTITY url.pear 'http://pear.php.net/'> <!ENTITY url.pear.account 'http://pear.php.net/accounts.php'> <!ENTITY url.pear.account.new 'http://pear.php.net/account-request.php'> @@ -110,9 +111,13 @@ <!ENTITY url.pear.support.lists 'http://pear.php.net/support/lists.php'> <!ENTITY url.pear.tasks.xsd 'http://pear.php.net/dtd/tasks-1.0.xsd'> <!ENTITY url.pear2.autoload 'http://svn.pear.php.net/wsvn/PEARSVN/Autoload/trunk/src/Autoload.php?op=file'> +<!ENTITY url.pear.docbuild.brett.chunk 'http://ucommbieber.unl.edu/peardoc/build/en/pear_manual_en/'> +<!ENTITY url.pear.docbuild.brett.log 'http://ucommbieber.unl.edu/peardoc/scripts/build.log'> + <!ENTITY url.pecl 'http://pecl.php.net/'> <!ENTITY url.phing 'http://phing.info/'> <!ENTITY url.phd 'http://doc.php.net/phd/'> +<!ENTITY url.phd.pearapi 'http://doc.php.net/phd/docs/#ext-phd-pearapi'> <!ENTITY url.phpdoc 'http://www.phpdoc.de/'> <!ENTITY url.phpdocumentor 'http://www.phpdoc.org/'> <!ENTITY url.phplib 'http://sourceforge.net/projects/phplib/'>