cvs: peardoc /en/guide/developers documentation.xml
| From: | Daniel Convissor | 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: