torben Thu Aug 9 21:10:28 2001 EDT
Modified files:
/phpdoc README
Log:
Various cleanups and clarifications.
Index: phpdoc/README
diff -u phpdoc/README:1.14 phpdoc/README:1.15
--- phpdoc/README:1.14 Thu Aug 9 19:58:19 2001
+++ phpdoc/README Thu Aug 9 21:10:28 2001
@@ -29,8 +29,8 @@
RPMs with the necessary software can be found at
ftp://sourceware.cygnus.com/pub/docbook-tools/
- Most major linux distributions should already come with
- ready to use packages.
+ Most major Linux distributions should already come with
+ ready-to-use packages.
CONVENTIONS
@@ -40,8 +40,8 @@
2. Function reference IDs look like this (case should be consistent
with the rest of the function naming standards, i.e. lowercase):
- `function.imageloadfont'. Please note that underscores cannot
- be used in IDs, they should be replaced by minus signs (-).
+ `function.imageloadfont'. Please note that since underscores
+ cannot be used in IDs, they should be replaced by minus signs (-).
3. Function section titles (<reference><title>...</>...) look
like this: `ref.category'.
@@ -53,42 +53,52 @@
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 itself)
+ 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 reference, the
+ 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 of using arguments specific to a newer version of
- php, it is helpful to note that 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
- Usually, in the form <note><simpara>Added in PHP 4.0.3</simpara></note>
+ 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
+ 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, or in case of a <?xml tag, second line.
- For non-english files, this isn't true.
+ 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 en-tree should be prevented as much as
+ 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 as comment: 'WS fix' or 'Whitespace fix'.
+ a separate commit, with a clear comment such as 'WS fix' or
+ 'Whitespace fix'.
- 12. More on whitespace: Never use tabs. Indentation should be done
- with one space character for each level of indentation.
+ 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.
WHAT TO DOCUMENT
- 1. Only major functions should be documented, functions which are
+ 1. Only major functions should be documented; functions which are
deprecated variants may be mentioned, but should not be
documented as separate functions. They instead should be
referenced in the parent function as an alias. Functions which
