philip Wed Aug 10 20:38:55 2005 EDT
Modified files:
/phpdoc/en/appendices about.xml
Log:
Minor rewrite: improved readability and removed the use of "you"
http://cvs.php.net/diff.php/phpdoc/en/appendices/about.xml?r1=1.41&r2=1.42&ty=u
Index: phpdoc/en/appendices/about.xml
diff -u phpdoc/en/appendices/about.xml:1.41 phpdoc/en/appendices/about.xml:1.42
--- phpdoc/en/appendices/about.xml:1.41 Tue Apr 12 03:19:49 2005
+++ phpdoc/en/appendices/about.xml Wed Aug 10 20:38:53 2005
@@ -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 @@
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 @@
<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 @@
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 @@
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 @@
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 @@
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>
