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 <, 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 <, 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
