philip Wed Feb 12 14:08:25 2003 EDT
Modified files:
/phpdoc README
Log:
Add quickref information for adding new functions, and list some popular
tags/entities. And, some minor beautification.
Index: phpdoc/README
diff -u phpdoc/README:1.29 phpdoc/README:1.30
--- phpdoc/README:1.29 Wed Dec 4 01:38:03 2002
+++ phpdoc/README Wed Feb 12 14:08:24 2003
@@ -1,16 +1,18 @@
+---------------------------------------------------------------------------
READ THIS FIRST
-
+---------------------------------------------------------------------------
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.
- If you just want to read the documentation, look at
- http://www.php.net/docs.php
+ If you just want to read the documentation, look at:
+ http://www.php.net/docs.php
+---------------------------------------------------------------------------
HOW TO WRITE PHPDOC FILES
-
+---------------------------------------------------------------------------
If you are interested in information about how to
set up the tools needed, how to work with CVS and
DocBook on Linux or Windows, or what conventions you
@@ -33,9 +35,10 @@
Translation information is located in the HOWTO.
http://www.php.net/anoncvs.php
-
-FILE LOCATIONS
+---------------------------------------------------------------------------
+FILE LOCATIONS
+---------------------------------------------------------------------------
The old archived phpdoc files still live in the phpdoc module
for historical purposes, do NOT edit them. For example:
@@ -54,7 +57,10 @@
/functions.xml (autogenerated)
-QUICKREF
+---------------------------------------------------------------------------
+QUICK REFERENCE
+---------------------------------------------------------------------------
+ [[edits]]
a) Make the change. Use spaces not tabs. Be sure to carefully
watch your whitespace!
@@ -78,3 +84,54 @@
Read the HOWTO for more information. After reading the HOWTO,
email the phpdoc mailing list ([EMAIL PROTECTED]) with questions
and concerns.
+
+ [[new functions]]
+
+ a) Copy an existing xml file or use a skeleton from the HOWTO.
+ Rename and place it into the appropriate directory.
+
+ b) Edit. Be sure no leftover text exists. No tabs either.
+
+ c) Now test locally before commit by first running
+ ./configure along with 'make test' as usual.
+
+ d) cvs add path/to/yourfile.xml
+
+ e) cvs commit path/to/yourfile.xml
+
+ Note that ./configure adds your function to functions.xml as
+ this allows 'make test' to test your new function. Also, note
+ that version numbers are taken care of elsewhere (don't worry
+ about them)
+
+ [[some popular tags and entities]]
+
+ <filename> filenames
+ <constant> constants
+ <varname> variables
+ <parameter> a functions parameter/argument
+ <function> functions, this links to function pages or bolds if
+ already in functions page. it also adds ().
+
+ <literal> teletype/mono-space font <tt>
+ <emphasis> italics
+ <example> see HOWTO, includes many other tags.
+ <link> internal manual links
+ <link linkend="language.variables">variables</link>
+
+ <url> external links via global.ent
+ <ulink url="&spec.cookies;">mmm cookies</ulink>
+
+
+ <type> types, this links to the given types manual
+ page: <type>object</type> -> php.net/types.object
+
+
+ &return.success; see: language-snippets.ent
+ &true; <constant>TRUE</constant>
+ &false; <constant>FALSE</constant>
+ &php.ini; <filename>php.ini</filename>
+
+ Be sure to check out globals.ent and language-snippets.ent for
+ more information for entities and urls.
+
+---------------------------------------------------------------------------
--
PHP Documentation Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
