1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
|
---------------------------------------------------------------------------
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
---------------------------------------------------------------------------
HOW TO WRITE PHPDOC FILES
---------------------------------------------------------------------------
If you are interested in information about how to
set up the tools needed, how to work with SVN and
DocBook on Linux or Windows, or what conventions you
should follow when writing phpdoc files, please refer
to the PHP Documentation HOWTO.
You can read the HOWTO online at:
http://doc.php.net/php/dochowto/
Or download a tar.gz containing the whole contents:
http://php.net/get/dochowto
If you are already working with the phpdoc module,
then you can find its XML source in the howto directory
of the module, and build it yourself with:
phd -d .manual.xml
However, PhD is a separate project which can be read about here:
http://wiki.php.net/doc/phd
---------------------------------------------------------------------------
GRAMMAR, NOMENCLATURE AND STYLE GUIDE
---------------------------------------------------------------------------
Please read the language style guidlines at:
http://wiki.php.net/doc/articles/nomenclature
---------------------------------------------------------------------------
FILE LOCATIONS
---------------------------------------------------------------------------
The file locations are as follows:
{lang}/reference/{extension}
/book.xml
/setup.xml
/configure.xml [often part of setup.xml]
/constants.xml
/ini.xml [often part of setup.xml]
When the extension defines functions:
/reference.xml
/functions/{function}.xml
When the exetnsion defines classess:
/{classname}.xml
/{classname}/{methodname}.xml
/entities.*.xml (autogenerated)
Translated files live within their own SVN directories.
(Skeletons for these files are available in RFC/skeletons/)
---------------------------------------------------------------------------
QUICK REFERENCE
---------------------------------------------------------------------------
[[source checkout]]
a) Check out the source
svn checkout http://svn.php.net/repository/phpdoc/modules/doc-en phpdoc
Change 'doc-en' if you would like to check out a different language.
The 'modules' directory contains 'svn externals' references, so the
above actually checks out:
svn checkout http://svn.php.net/repository/phpdoc/en/trunk phpdoc/en
svn checkout http://svn.php.net/repository/phpdoc/doc-base/trunk phpdoc/doc-base
Where en/ is contains the DocBook source files, and doc-base/ contains tools
and resources used in all languages.
[[edits]]
a) Make the change. Use spaces not tabs. Be sure to carefully
watch your whitespace!
b) Look at your unified diff, make sure it looks right and that
whitespace changes aren't mixed in:
svn diff path/to/file.xml
c) Make sure no errors are present, so at the command line in your
phpdoc source directory run:
php doc-base/configure.php
Always 'php configure.php' before commit!
d) Commit your changes
svn commit path/to/file.xml
Read the HOWTO for more information. After reading the HOWTO,
email the phpdoc mailing list (phpdoc@lists.php.net) 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
(php configure.php)
d) svn add path/to/yourfile.xml
e) svn commit path/to/yourfile.xml
Note that the 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 function's parameter/argument
<function> functions, this links to function pages or bolds if
already on the function's 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>
<link> external links via global.ent
<link xlink:href="&spec.cookies;">mmm cookies</link>
<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.
---------------------------------------------------------------------------
|
