cvs: phpdoc / README

From: Date: Tue, 04 Sep 2001 14:47:06 +0000
Subject: cvs: phpdoc / README
Groups: php.doc 
Request: Send a blank email to phpdoc+get-969337455@lists.php.net to get a copy of this message
goba Tue Sep 4 10:47:06 2001 EDT Modified files: /phpdoc README Log: Somebody used *tabs* in the README. Weird. WS only fixes. Index: phpdoc/README diff -u phpdoc/README:1.19 phpdoc/README:1.20 --- phpdoc/README:1.19 Tue Aug 14 19:23:15 2001 +++ phpdoc/README Tue Sep 4 10:47:06 2001 @@ -2,9 +2,9 @@ This directory contains source files and a setup for converting PHP's XML documentation into presentation formats like HTML and - RTF. You should not have to bother with this unless you are - writing documentation yourself, or if you simply are curious about - how the XML stuff works. + RTF. You should not have to bother with this unless you are + writing documentation yourself, or if you simply are curious + about how the XML stuff works. If you just want to read the documentation, download it from http://www.php.net/docs.php @@ -24,7 +24,7 @@ There is a DTD reference for DocBook at - http://www.oreilly.com/catalog/docbook/chapter/book/docbook.html + http://www.oreilly.com/catalog/docbook/chapter/book/docbook.html RPMs with the necessary software can be found at ftp://sourceware.cygnus.com/pub/docbook-tools/ @@ -49,76 +49,76 @@ 4. The contents of examples with program listings start on column 0 in the XML code. - 5. All examples use the <?php ... ?> form instead of <? ... ?> - It can be useful to use <![CDATA[ ... ]]> for examples, since - it eliminates the need to change < to &lt;, etc. - - In examples, use the PEAR coding standard (it's in the manual). - - 6. The <refsect1><title> tag was set incorrectly when - converting from sgml-tools. For normal function references, the - text "Description" should be used instead of the function name. - - 7. Bracketing and naming conventions in examples should adhere to - other examples in the manual, and standards for function names. - Deprecated aliases and syntax should not be used in examples. + 5. All examples use the <?php ... ?> form instead of <? ... ?> + It can be useful to use <![CDATA[ ... ]]> for examples, since + it eliminates the need to change < to &lt;, etc. + + In examples, use the PEAR coding standard (it's in the manual). + + 6. The <refsect1><title> tag was set incorrectly when + converting from sgml-tools. For normal function references, the + text "Description" should be used instead of the function name. + + 7. Bracketing and naming conventions in examples should adhere to + other examples in the manual, and standards for function names. + Deprecated aliases and syntax should not be used in examples. - 8. If an example uses arguments specific to a newer version of - PHP, it is helpful to note this in the example: + 8. If an example uses arguments specific to a newer version of + PHP, it is helpful to note this in the example: - foo("bar", "baz"); // second argument was added in PHP 4.0.3 + foo("bar", "baz"); // second argument was added in PHP 4.0.3 - New arguments are denoted in the main text of the entry - using the form + New arguments are denoted in the main text of the + entry using the form - <note> - <simpara> - The second parameter was added in PHP 4.0.3. - </simpara> - </note>. - - 9. The language constants true, false and null should be written as - &true;, &false; and &null;. - - 10. All English XML files should have a <!-- $Revision comment as the - first line unless they contain an <?xml tag, in which case the revision - comment should be on the second line. Non-English files should not have - this comment. - - 11. Whitespace changes in the English tree should be prevented as much as - possible: it is more important to keep a good change-history - of real changes, because of the translations. - If a whitespace change is _really_ needed, do it at least in - a separate commit, with a clear comment such as 'WS fix' or - 'Whitespace fix'. - - 12. More on whitespace: Never use tabs, not even in example program - listings. XML should be indented with one space character - for each level of indentation; example code uses four spaces. - - 13. Types: In the docs, the types are denoted as: boolean (bool in - prototypes), integer (int in prototypes), float (not: double), - array, object (not: class), resource and null (lowercase). - - In prototypes, you can also use 'mixed' (various types), or 'number' - (either integer or float), or scalar (boolean, integer, float or - string). A callback is denoted as mixed(*), since it can be either - array or string. - - If a function requires no arguments, use <void/> in stead of - <parameter>void</parameter>, since the former renders to " ()", - and not " (void)", the former is of course more correct. - - If a function has an undefined return-value, use 'void'. - - 14. In a prototype, if there are multiple - really distinct - - possibilities, simply make it two! See math.xml:min() for an example. - - 15. Aliases: In refpurpose, put: Alias of <function>realfunc</function>. - Do _not_ specify a funcsynopsis, and nothing but simply - the text: This function is an alias of <function>realfunc</function>. + <note> + <simpara> + The second parameter was added in PHP 4.0.3. + </simpara> + </note>. + + 9. The language constants true, false and null should be written as + &true;, &false; and &null;. + + 10. All English XML files should have a <!-- $Revision --> comment as the + first line unless they contain an <?xml tag, in which case the revision + comment should be on the second line. Non-English files should not have + this comment. + + 11. Whitespace changes in the English tree should be prevented as much as + possible: it is more important to keep a good change-history + of real changes, because of the translations. + If a whitespace change is _really_ needed, do it at least in + a separate commit, with a clear comment such as 'WS fix' or + 'Whitespace fix'. + + 12. More on whitespace: Never use tabs, not even in example program + listings. XML should be indented with one space character + for each level of indentation; example code uses four spaces. + + 13. Types: In the docs, the types are denoted as: boolean (bool in + prototypes), integer (int in prototypes), float (not: double), + array, object (not: class), resource and null (lowercase). + + In prototypes, you can also use 'mixed' (various types), or 'number' + (either integer or float), or scalar (boolean, integer, float or + string). A callback is denoted as mixed(*), since it can be either + array or string. + + If a function requires no arguments, use <void/> in stead of + <parameter>void</parameter>, since the former renders to " ()", + and not " (void)", the former is of course more correct. + + If a function has an undefined return-value, use 'void'. + + 14. In a prototype, if there are multiple - really distinct - + possibilities, simply make it two! See math.xml:min() for an example. + + 15. Aliases: In refpurpose, put: Alias of <function>realfunc</function>. + Do _not_ specify a funcsynopsis, and nothing but simply + the text: This function is an alias of <function>realfunc</function>. - This way, people can click to realfunc straight from the ref.foo page. + This way, people can click to realfunc straight from the ref.foo page. (*) Better suggestions? I don't really like it this way... not simply 'function', or something alike? --Jeroen

« previous php.doc (#969337455) next »