sigmasternchen/php-doc-en
1
0
Fork 0
mirror of https://github.com/sigmasternchen/php-doc-en synced 2025-03-16 00:48:54 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Minor rewrite: improved readability and removed the use of "you"

Browse source 
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@193007 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Philip Olson 2005-08-11 00:38:53 +00:00
parent dc97f59b99
commit 5515ca026a
1 changed files with 79 additions and 85 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

164
appendices/about.xml
View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.41 $ -->
<!-- $Revision: 1.42 $ -->
<appendix id="about">
<title>About the manual</title>
@ -18,22 +18,22 @@
</para>
</note>
<para>
You can read the manual online at the <ulink url="&url.php;">PHP.net website</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
The manual can be read online at the <ulink url="&url.php;">PHP.net website</ulink>,
and on the numerous mirror sites. For best performance, choose
the closest mirror. The HTML version of the PHP manual is in either 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>
Two notable advantages of the online manual over most of the offline formats is the
integration of <link linkend="about.notes">user-contributed
notes</link> and the <ulink url="&url.php.urlhowto;">URL shortcuts</ulink> which you
can use to get to the desired manual parts quickly. An obvious disadvantage is
that you have to be online to view this edition of the manual.
notes</link> and the <ulink url="&url.php.urlhowto;">URL shortcuts</ulink> that
may be used to get to the desired manual parts quickly. An obvious disadvantage is
the requirement to be online to view this edition of the manual.
</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
format for depends on the operating system, and 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.
@ -42,25 +42,27 @@
The most cross-platform format of the manual is the HTML version. This
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).
We provide these versions compressed, you will need some sort of decompression
utility to get the files contained in the archives.
We provide these versions compressed, so a decompression utility is
required to retrieve the files contained within the archives.
</para>
<!--
The PDF version of the PHP Manual is "currently" unavailable. Perhaps
one day it will exist.
<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
more than 2000 pages long, and constantly being revised.
printing, is PDF (also known as Adobe Acrobat). But beware that the manual
is over 2000 pages in length, 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>.
Many programs exist to view <acronym>PDF</acronym> files, such as the
<ulink url="&url.adobe.acrobat;">Adobe Acrobat Reader</ulink>.
</para>
</note>
-->
<para>
For Windows platforms, the <productname>Windows HTML Help</productname>
version of the manual soups up the HTML format for use with the
version of the manual enhances the HTML format for use with the
<productname>Windows HTML Help</productname> application. This
version provides full-text search, a full index, and bookmarking. Many
popular Windows PHP development environments also integrate with this
@ -72,9 +74,9 @@
<para>
There is also an <ulink url="&url.php.echm;">extended CHM version</ulink>
available, which is updated less frequently, but provides much more
available, which is updated less frequently, but provides many additional
features. It will only work on <productname>Microsoft Windows</productname>
though, because of the technologies used to build up the help pages.
though, because of the technologies used to build the help pages.
</para>
</sect1>
@ -85,8 +87,8 @@
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.
notes have been incorporated, they may be viewed in their submitted form
online, and in some of the offline formats.
</para>
<note>
<para>
@ -113,8 +115,8 @@
<para>
Each function in the manual is documented for quick reference. Knowing how
to read and understand the text will make learning PHP
much easier. Rather than relying on examples or cut/paste, you will want
to know how to read function definitions (prototypes). Let's begin:
much easier. Rather than relying on examples or cut/paste, everyone should
know how to read function definitions (prototypes). Let's begin:
</para>
<note>
<title>
@ -265,22 +267,21 @@ Returns the length of string.
versions are documented in notes and inline text in the manual.
</para>
<para>
You may find documentation pieces for the CVS version of PHP, which
always means the very latest development version available through
the CVS version handling system. If you are not a developer of PHP
itself, and you are not keen on using the very latest development
version of PHP, features marked with the "available in CVS" wording
are not accessible to you. These features, though, will probably be
available in the next stable version of PHP. If you would like to
download the CVS version, see the <ulink url="&url.php.anoncvs;">anonymous
Documentation partly exists for the CVS version of PHP, which
always means the very latest development version. This has yet to
be released so is only available through the CVS version handling system,
or via a <ulink url="&url.php.snapshots;">snapshot</ulink>. So be aware that
features marked "available in CVS" are typically unavailable. These
features, though, will most likely be available in the next stable version
of PHP. To download the CVS version, see the <ulink url="&url.php.anoncvs;">anonymous
CVS access page</ulink>.
</para>
<para>
You may also encounter documentation for a PHP version which is
not released (something like PHP 5.0.0 while the latest stable version
Also, documentation may exist for PHP versions that aren't yet released.
(something like PHP 5.0.0 while the latest stable version
is 4.3.x). Most of the time, this is not an error in the documentation.
Explanation is often added for features not available in the current
PHP release, but which will be available in a known future PHP version.
PHP release, but will be available as a known future PHP version.
Typically, PHP only adds new features in major releases otherwise only bugs
are fixed. Using the A.B.C versioning format, a major release increments A
or B whereas minor releases increment C. So for example it's not uncommon
@ -301,59 +302,59 @@ Returns the length of string.
<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
this manual only. You may want to seek out a text more oriented towards
beginners. You can find a list of PHP-related books at <ulink
programming practices. First-time - or even just beginning -
programmers may find it difficult to learn how to program in PHP using
this manual exclusively. Instead, seek out a text more oriented towards
beginners. Or a book, see also 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;">the PHP.net support page</ulink>, as well as links to
the mailing list archives and other online support resources. Furthermore, at
<ulink url="&url.php.links;">the PHP.net links page</ulink> there is a list of
websites devoted to PHP articles, forums, and code galleries.
There are a number of active mailing lists for discussion on all aspects of
programming with PHP. If stuck with a problem, consider using these lists.
For support options, including mailing lists, view <ulink
url="&url.php.support;">the PHP.net support page</ulink>. Furthermore,
there is a list of websites devoted to PHP articles, forums, and code galleries
at <ulink url="&url.php.links;">the PHP.net links page</ulink> .
</para>
</sect1>
<sect1 id="about.howtohelp">
<title>How to help improve the documentation</title>
<para>
There are three ways you can help to improve this documentation.
There are three ways everyone can help improve this documentation.
</para>
<para>
If you find errors in this manual, in any language, please report them
If an error is found 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 there.
Classify the bug as "Documentation Problem". All documentation related
problems, including those about manual formats, should be submitted as bug
reports.
</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.
Please don't abuse the bug system by submitting requests for help.
Instead, one of the many
<ulink url="&url.php.support;">support options</ulink>
</para>
</note>
<para>
By contributing notes, you can provide additional examples, caveats, and
By contributing notes, users may provide additional examples, caveats, and
clarifications for other readers. But please do not submit bug reports using the
annotation system. You can read more about annotations in the <link
linkend="about.notes">'About user notes'</link> section of this
appendix.
annotation system. For details, see the section titled <link
linkend="about.notes">'About user notes'</link>.
</para>
<para>
If you know English and some foreign language, you may also
help out in the translations. If you would like to start a new
translation, or help in a translation project, please read
The PHP manual is translated into many languages. Knowing English and a
foreign language allows for another way to help improve the PHP manual by
working with a translation team. For information about starting a new
translation, or helping a currently translated version, please read
<ulink url="&url.php.dochowto;">&url.php.dochowto;</ulink>.
</para>
<para>
The PHP Documentation Project has an IRC channel where you
can come and talk with manual authors or find some aspect
of the manual with which you might help. It's
<literal>#phpdoc</literal> on <literal>irc.freenode.net</literal>.
The PHP Documentation Project also has an IRC channel where many manual
authors hang out. Stop by <literal>#phpdoc</literal> on
<literal>irc.freenode.net</literal> and discuss ways to improve
the PHP documentation.
</para>
</sect1>
@ -369,7 +370,7 @@ Returns the length of string.
for maintenance and formatting.
</para>
<para>
Using <acronym>XML</acronym> as a source format gives us
Using <acronym>XML</acronym> as a source format gives
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
@ -384,18 +385,10 @@ Returns the length of string.
additional conversions and formatting.
</para>
<para>
You can download the manual in various languages and
formats, including 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>.
Note that due to technical reasons, some formats may
be unavailable.
</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
The PHP manual is generated in various languages and formats, see
<ulink url="&url.php.docs;">&url.php.docs;</ulink> for additional details.
The <acronym>XML</acronym> source code may be downloaded from CVS and
viewed at <ulink url="&url.php.cvs;">&url.php.cvs;</ulink>. The
documentation is stored in the <literal>phpdoc</literal> module.
</para>
</sect1>
@ -415,20 +408,21 @@ Returns the length of string.
People involved in the translations start from the <acronym>XML</acronym>
source code available from <ulink url="&url.php.cvs;">&url.php.cvs;</ulink>
and from it they translate to their mother language. They do
<emphasis>not use</emphasis> the <acronym>HTML</acronym>, the plain text,
or the <acronym>PDF</acronym> version. It is the build system which takes
care of the conversions from <acronym>XML</acronym> to human readable formats.
<emphasis>not use</emphasis> the generated versions (like
<acronym>HTML</acronym> or plain text) as it's the build system that takes
care of the conversions from <acronym>XML</acronym> to human readable
formats.
</para>
<note>
<para>
If you would like to help translate the documentation to your native
language, please get in touch with the translation/documentation team by
To help translate the documentation,
please get in touch with the translation/documentation team by
subscribing to the phpdoc mailing list: send an empty mail to <ulink
url="mailto:&email.php.doc.subscribe;">&email.php.doc.subscribe;</ulink>.
The mailing list address is <literal>&email.php.doc;</literal>. State in the
message that you are interested in translating the manual to a language
and someone will get back to you, helping you start a new language translation
or reach the already active documentation team for your language.
message an interest in translating the manual and someone will reply with
feedback on moving forward by helping start a new language translation, or
by contacting the existing team for the desired language.
</para>
</note>
<para>
@ -439,7 +433,7 @@ Returns the length of string.
Turkish.
</para>
<para>
They can all be downloaded here: <ulink url="&url.php.docs;">&url.php.docs;</ulink>.
They may all be downloaded here: <ulink url="&url.php.docs;">&url.php.docs;</ulink>.
</para>
</sect1>