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
PHP3's SGML 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 SGML stuff works.
If you just want to read the documentation, download it from
http://www.php.net/documentation.php3
INTRODUCTION
All the documentation is written with SGML using the DocBook DTD.
See:
http://ww.ora.com/davenport/
If you want to produce something viewable, you need Jade and
Norman Walsh's modular DocBook stylesheets. See:
http://www.jclark.com/jade/
http://www.berkshire.net/~norm/docbook/dsssl/
There is a DTD reference for DocBook at
http://www.ora.com/homepages/dtdparse/docbook/3.0/
RPMs with the necessary software can be found at
ftp://ftp.cygnus.com/pub/home/rosalia/docware/
CONVENTIONS
1. Insert ID attributes in all major section tags such
as part, chapter, sect1 etc. The HTML stylesheet will
name the HTML files after these IDs.
2. Function reference IDs look like this (case does not matter):
`function.imageloadfont'. Please note that underscores cannot
be used in IDs, they should be replaced by minus signs (-).
3. Function section titles (<reference><title>...</>...) look
like this: `ref.category'.
4. The contents of examples with program listings start on column
0 in the SGML code.
5. All examples use the <?php ... ?> form instead of <? ... ?>
6. The <refsect1><title> tag was set incorrectly when
converting from sgml-tools. For normal function reference, the
text "Description" should be used instead of the function name.
SKELETONS
Below are some "skeletons" to copy and paste from when adding
documentation.
FUNCTION REFERENCE FILE IN functions/:
<reference>
<title></title>
</reference>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
END OF SKELETON
FUNCTION REFERENCE ENTRY:
<refentry id="function.">
<refnamediv>
<refname></refname>
<refpurpose></refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcdef>RETURNTYPE <function>FUNCTIONNAME</function></funcdef>
<paramdef>ARGTYPE1 <parameter>ARGNAME1</parameter></paramdef>
<paramdef>ARGTYPE2 <parameter>ARGNAME2</parameter></paramdef>
<paramdef>ARGTYPE3 <parameter><optional>ARGNAME3</optional></parameter></paramdef>
</funcsynopsis>
<simpara>
A simple paragraph that can not contain anything that requires
fancy layout.
<para>
A normal paragraph that can contain lots of stuff. For example
<example>
<title>Code examples</title>
<programlisting>
/* 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.
*/
function some_code($foo)
{
/* we all agree that four spaces of indentation is good? */
}
</programlisting></example>
The text in a paragraph may continue after the example as well.
Here is how to make lists:
<itemizedlist>
<listitem><simpara>
List items must contain a container element such as
simpara or para (there are plenty of others too, see the
DocBook reference for the listitem element.
<listitem><simpara>
List items must contain simple paragraphs or paragraphs.
<listitem><para>
If you plan on making sub-lists, you must use para
<orderedlist>
<listitem><simpara> first list item
<listitem><simpara> second list item
</orderedlist>
You can also continue an ordered list you just left off
<orderedlist>
<listitem><simpara> third list item
<listitem><simpara> fourth list item
</orderedlist>
<simpara>
The documentation for a function should be wrapped up with
a "See also" list like this:
<simpara>
See also:
<link linkend="function.stripslashes">stripslashes</link>
<link linkend="function.quotemeta">quotemeta</link>
</refsect1>
</refentry>
END OF SKELETON
Stig Bakken <stig@php.net>
|
