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
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
|
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.11 $ -->
<!--
TODO: add manual conventions section (eg. how to read
function usage parts, what is fixed width, what is
bold, what is linked
add some tips about combining the versions (online-
offline), and using "http://anymirror.php.net/funcname"
-->
<appendix id="about">
<title>About the manual</title>
<sect1 id="about.formats">
<title>Formats</title>
<para>
The PHP manual is provided in several formats. These formats can be divided
into two groups: online readable formats, and downloadable packages.
</para>
<note>
<para>
Some publishers have made available printed versions of this manual. We
cannot recommend any of those, as they tend to become out-of-date very
quickly.
</para>
</note>
<para>
You can read the manual online at <ulink url="&url.php;"> &url.php;</ulink>
and on the numerous mirror sites. For best performance, you should choose
the mirror site closest to you. You can view the manual in either its plain
(print-friendly) HTML format or an HTML format that integrates the manual
into the look and feel of the PHP website itself.
</para>
<para>
An advantage of the online manual over most of the offline formats is the
integration of <link linkend="about.notes">user-contributed
notes</link>. An obvious disadvantage is that you have to be online to view
the manual in the online formats.
</para>
<para>
There are several offline formats of the manual, and the most appropriate
format for you depends on what operating system you use and your personal
reading style. For information on how the manual is generated in so many
formats, read the <link linkend="about.generate">'How we generate the
formats'</link> section of this appendix.
</para>
<para>
The most cross-platform formats of the manual are the HTML and plain-text
versions. The HTML format is provided both as a single HTML file and as
a package of individual files for each section (which results in a
collection of several thousand files). The HTML and plaintext formats are
provided as tar files compressed using the bzip2 archiver.
</para>
<para>
Another popular cross-platform format, and the format most suited to
printing, is PDF (also known as Adobe Acrobat). But before you rush to
download this format and hit the Print button, be warned that the manual is
nearly 2000 pages long, and constantly being revised.
</para>
<note>
<para>
If you do not already have a program capable of viewing PDF format
files, you may need to download <ulink url="&url.adobe.acrobat;">Adobe
Acrobat Reader</ulink>.
</para>
</note>
<para>
For owners of Palm-compatible handhelds, the Palm document and iSilo
formats are ideal for this platform. You can bring your handheld with you
on your daily commute and use a <ulink url="&url.palm.doc;">DOC</ulink>
or <ulink url="&url.palm.isilo;">iSilo</ulink> reader to brush up on your
PHP knowledge, or just use it as a quick reference.
</para>
<para>
For Windows platforms, the Windows HTML Help version of the manual soups up
the HTML format for use with the Windows HTML Help application. This
version provides full-text search, a full index, and bookmarking. Many
popular Windows PHP development environments also integrate with this
version of the documentation to provide easy access.
</para>
<note>
<para>
A Visual Basic for Linux project is in the planning stage, which will
include the development of a CHM Creator and Viewer for Linux. See their
<ulink url="&url.vb4linux;">SourceForge.net page</ulink> if you are
interested in the progress.
</para>
</note>
</sect1>
<sect1 id="about.notes">
<title>About user notes</title>
<para>
The user-contributed notes play an important role in the development of
this manual. By allowing readers of the manual to contribute examples,
caveats, and further clarifications from their browser, we are able to
incorporate that feedback into the main text of the manual. And until the
notes have been incorporated, they can be viewed in their submitted form
online and in some of the offline formats.
</para>
<note>
<para>
The user-contributed notes are not moderated before they appear online, so
the quality of the writing or code examples, and even the veracity of the
contribution, cannot be guaranteed. (Not that there is any guarantee of
the quality or accuracy of the manual text itself.)
</para>
</note>
</sect1>
<sect1 id="about.more">
<title>How to find more information about PHP</title>
<para>
This manual does not attempt to provide instruction about general
programming practices. If you are a first-time, or even just a beginning,
programmer, you may find it difficult to learn how to program in PHP using
just this manual. You may want to seek out a text more oriented towards
beginners. You can find a list of PHP-related books at <ulink
url="&url.php.books;">&url.php.books;</ulink>.
</para>
<para>
There are a number of active mailing lists for discussion of all aspects of
programming with PHP. If you find yourself stuck on a problem for which you
can't find your own solution, you may be able to get help from someone on
these lists. You can find a list of the mailing lists at <ulink
url="&url.php.support;">&url.php.support;</ulink>, as well as links to the
mailing list archives and other online support resources. Furthermore, at
<ulink url="&url.php.links;">&url.php.links;</ulink> there is a list of
websites devoted to PHP articles, forums, and code galleries.
</para>
</sect1>
<sect1 id="about.howtohelp">
<title>How to help improve the documentation</title>
<para>
There are two ways you can help to improve this documentation.
</para>
<para>
If you find errors in this manual, in any language, please report them
using the bug system at <ulink url="&url.php.bugs;">&url.php.bugs;</ulink>.
Classify the bug as "Documentation Problem". You can also submit problems
related to specific manual formats here.
</para>
<note>
<para>
Please don't abuse the bug system by submitting requests for help. Use the
mailing lists or community sites mentioned earlier, instead.
</para>
</note>
<para>
By contributing notes, you can provide additional examples, caveats, and
clarifications for other readers. But do not submit bug reports using the
annotation system please. You can read more about annotations in the <link
linkend="about.notes">'About user notes'</link> section of this
appendix.
</para>
</sect1>
<sect1 id="about.generate">
<title>How we generate the formats</title>
<para>
This manual is written in <acronym>XML</acronym> using the <ulink
url="&url.docbook.xml;">DocBook XML DTD</ulink>, using <ulink
url="&url.dsssl;"><acronym>DSSSL</acronym></ulink> (Document
Style and Semantics Specification Language) for formatting, and
experimentally the <ulink url="&url.xslt;"><acronym>XSLT</acronym>
</ulink> (Extensible Stylesheet Language Transformations)
for maintenance and formatting.
</para>
<para>
Using <acronym>XML</acronym> as a source format gives us
the ability to generate many output formats from the source
files, while only maintaining one source document for all formats.
The tools used for formatting <acronym>HTML</acronym> and
<acronym>TeX</acronym> versions are
<ulink url="&url.jade;">Jade</ulink>, written by <ulink
url="&url.jclark;">James Clark</ulink> and <ulink
url="&url.dbstyle;">The Modular DocBook Stylesheets</ulink>
written by <ulink url="&url.nwalsh;">Norman Walsh</ulink>.
We use <ulink url="&url.winhelp;">Microsoft HTML Help
Workshop</ulink> to generate the Windows HTML Help format
of the manual, and of course PHP itself to do some
additional conversions and formatting.
</para>
<para>
You can download the manual in various languages and
formats, including plain text, plain <acronym>HTML</acronym>,
<acronym>PDF</acronym>, PalmPilot DOC, PalmPilot iSilo and
Windows HTML Help, from
<ulink url="&url.php.docs;">&url.php.docs;</ulink>.
The manuals are updated automatically as the text is updated.
</para>
<para>
You can find more information about downloading the
<acronym>XML</acronym> source code of this documentation
at <ulink url="&url.php.cvs;">&url.php.cvs;</ulink>. The
documentation is stored in the <literal>phpdoc</literal> module.
</para>
</sect1>
</appendix>
<!-- 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
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
|
