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

From: Date: Thu, 06 May 2004 16:02:09 +0000
Subject: cvs: peardoc /en/guide/developers documentation.xml
Groups: php.pear.doc 
Request: Send a blank email to pear-doc+get-3911@lists.php.net to get a copy of this message
danielc Thu May 6 12:02:09 2004 EDT Modified files: /peardoc/en/guide/developers documentation.xml Log: Add info about the automatic test builds. http://cvs.php.net/diff.php/peardoc/en/guide/developers/documentation.xml?r1=1.18&r2=1.19&ty=u Index: peardoc/en/guide/developers/documentation.xml diff -u peardoc/en/guide/developers/documentation.xml:1.18 peardoc/en/guide/developers/documentation.xml:1.19 --- peardoc/en/guide/developers/documentation.xml:1.18 Mon Apr 19 01:04:31 2004 +++ peardoc/en/guide/developers/documentation.xml Thu May 6 12:02:09 2004 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1" ?> -<!-- $Revision: 1.18 $ --> +<!-- $Revision: 1.19 $ --> <!-- WORK IN PROGRESS, THERE IS PROBABLY LITTLE POINT IN TRANSLATING THIS DOCUMENT YET. @@ -70,7 +70,8 @@ <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 + 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 a installation instruction can be found in the @@ -81,6 +82,59 @@ completely read it. (Chapter II can be skipped, because it only contains information that is very PHP specific.) </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 every + two hours 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> + <ulink url="&url.doc.test.build.1.log;"> + &url.doc.test.build.1.log;</ulink> + (time zone: EET = UTC+2, EEST = UTC+3) + </member> + <member> + <ulink url="&url.doc.test.build.2.log;"> + &url.doc.test.build.2.log;</ulink> + (time zone: CET = UTC+1, CEST = UTC+2) + </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). + <simplelist> + <member> + <ulink url="&url.doc.test.build.1;"> + &url.doc.test.build.1;</ulink> + </member> + <member> + <ulink url="&url.doc.test.build.2;"> + &url.doc.test.build.2;</ulink> + </member> + </simplelist> + + <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:

« previous php.pear.doc (#3911) next »