goba Tue Sep 4 11:14:45 2001 EDT
Modified files:
/phpdoc README
Log:
Adding a new convention about using Unix newlines, revording,
removing old SGML->XML convention, correcting some errors,
some WS
Index: phpdoc/README
diff -u phpdoc/README:1.20 phpdoc/README:1.21
--- phpdoc/README:1.20 Tue Sep 4 10:47:06 2001
+++ phpdoc/README Tue Sep 4 11:14:44 2001
@@ -6,70 +6,65 @@
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
+ If you just want to read the documentation, look at
http://www.php.net/docs.php
INTRODUCTION
- All the documentation is written with XML using the DocBook 3.0
- DTD. See:
-
+ All the documentation is written with XML using the DocBook DTD.
+ See:
+
http://www.oasis-open.org/docbook/
-
+
If you want to produce something viewable, you need Jade and
Norman Walsh's modular DocBook stylesheets. See:
-
+
http://www.jclark.com/jade/
http://nwalsh.com/docbook/dsssl/
-
+
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/
- Most major Linux distributions should already come with
+ ftp://sourceware.cygnus.com/pub/docbook-tools/
+
+ Most major Linux distributions should already come with
ready-to-use packages.
CONVENTIONS
1. Insert ID attributes in all major section tags such
- as part, chapter, sect1 etc. The HTML stylesheet will
+ as part, chapter, sect1 etc. The HTML stylesheet will
name the HTML files after these IDs.
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 since underscores
+ `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'.
+ 3. Function section IDs (<reference id="...">) look
+ like this: 'ref.category', for example: 'ref.ftp'.
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 <? ... ?>
+ 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.
+ 6. Indenting, bracketing and naming conventions in examples should
+ adhere to the PEAR coding standars (it's in the manual).
Deprecated aliases and syntax should not be used in examples.
- 8. If an example uses arguments specific to a newer version of
+ 7. 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
New arguments are denoted in the main text of the
- entry using the form
+ entry using the form
<note>
<simpara>
@@ -77,42 +72,49 @@
</simpara>
</note>.
- 9. The language constants true, false and null should be written as
+ 8. 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
+ 9. 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.
+ 10. 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
+ 11. 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.
+ for each level of indentation; example code uses four spaces
+ (see PEAR standards).
+
+ 12. Always use LF (Line Feed) for the only newline character in
+ files, this is the Unix standard. Never use CR LF (Windows) or
+ CR (Mac) even, when editing Windows specific files (such as
+ *.bat). It eases the editing works.
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).
+ array, object (not: class), resource and null (all 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 requires no arguments, use <void/> instead of
+ <parameter>void</parameter>, since the former is the correct
+ DocBook XML tag.
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.
+ 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
@@ -130,17 +132,18 @@
documented as separate functions. They instead should be
referenced in the parent function as an alias. Functions which
have completely different names, however, should be documented as
- separate entries, for ease of reference.
+ separate entries, for ease of reference. The aliases.xml appendix
+ is the place to store aliases not documented elsewhere.
Examples:
- mysql_db_name and mysql_dbname will be documented as the same
- function, with the latter being listed as an alias of the
- former.
+ mysql_db_name and mysql_dbname will be documented as the same
+ function, with the latter being listed as an alias of the
+ former.
- show_source and highlight_file will be documented as two
- different functions (one as an alias), as the names are
- completely different, and one name is not likely to be found
- if looking for the name of the other.
+ show_source and highlight_file will be documented as two
+ different functions (one as an alias), as the names are
+ completely different, and one name is not likely to be found
+ if looking for the name of the other.
2. Function names should be created, and documented, in lower-case
format with an underscore separating the name components. If
@@ -148,28 +151,30 @@
of components.
Good:
- 'mcrypt_enc_self_test'
- 'mysql_list_fields'
+ 'mcrypt_enc_self_test'
+ 'mysql_list_fields'
Ok:
- 'mcrypt_module_get_algo_supported_key_sizes'
- (could be 'mcrypt_mod_get_algo_sup_key_sizes'?)
- 'get_html_translation_table'
- (could be 'html_get_trans_table'?)
+ 'mcrypt_module_get_algo_supported_key_sizes'
+ (could be 'mcrypt_mod_get_algo_sup_key_sizes'?)
+ 'get_html_translation_table'
+ (could be 'html_get_trans_table'?)
Bad:
- 'hw_GetObjectByQueryCollObj'
- 'pg_setclientencoding'
+ 'hw_GetObjectByQueryCollObj'
+ 'pg_setclientencoding'
3. Functions which are kept only for backwards compatibility should
be listed under their current parent names, and not documented as
separate functions. Backwards compatible functions and
documentation for them should be maintained as long as the code
- can be reasonably kept as part of the PHP codebase.
+ can be reasonably kept as part of the PHP codebase. Also see
+ the appendix aliases.xml.
4. Short code examples are much more desirable than long ones.
If a function is extremely complex, a suitable place to put
- a longer example is in the chapter introduction.
+ a longer example is in the chapter introduction. This example
+ can hold code for other functions in the same chapter.
5. Brevity is appreciated. Long winded descriptions of each and
every function are not appropriate for the reference sections.
@@ -199,7 +204,7 @@
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
-sgml-default-dtd-file:"../manual.ced"
+sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
@@ -209,7 +214,6 @@
END OF SKELETON
-
FUNCTION REFERENCE ENTRY:
<refentry id="function.">
@@ -238,6 +242,10 @@
<example>
<title>Code examples</title>
<programlisting role="php">
+<![CDATA[
+
+// Use CDATA is you would like to add lots of < to the code
+
/* Do all indentation with spaces, not tabs, just to be sure.
* Don't try pushing the code to the right by adding spaces in
* front, this is the style sheet's job.
@@ -246,10 +254,11 @@
// a function example
function some_code($foo)
{
- /* we all agree that four spaces of indentation is good? */
+ /* use four spaces of indentation */
}
-// an example of bracket usage and spacing
+// an example of bracket usage and spacing, always use
+// brackets, even when they are phisicaly not needed
if (some_code($foo) == "foo") {
echo "foo";
} elseif (some_code($foo) == "bar") {
@@ -257,6 +266,9 @@
} else {
echo "No foo, no bar";
}
+
+// Include end of CDATA, if you started with CDATA
+]]>
</programlisting>
</example>
@@ -308,7 +320,6 @@
</refsect1>
</refentry>
-
END OF SKELETON
-Stig Bakken <[EMAIL PROTECTED]>
+Originally written by: Stig Bakken <[EMAIL PROTECTED]>
\ No newline at end of file
