diff --git a/appendices/about.xml b/appendices/about.xml index 205fc7146d..e5c561cdf4 100644 --- a/appendices/about.xml +++ b/appendices/about.xml @@ -1,5 +1,5 @@ - + About the manual @@ -18,22 +18,22 @@ - You can read the manual online at the PHP.net website - 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 PHP.net website, + 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. Two notable advantages of the online manual over most of the offline formats is the integration of user-contributed - notes and the URL shortcuts 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 and the URL shortcuts 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. 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 'How we generate the formats' 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. + For Windows platforms, the Windows HTML Help - 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 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 @@ -72,9 +74,9 @@ There is also an extended CHM version - 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 Microsoft Windows - though, because of the technologies used to build up the help pages. + though, because of the technologies used to build the help pages. @@ -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. @@ -113,8 +115,8 @@ 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: @@ -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 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 &url.php.books;. - 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 the PHP.net support page, as well as links to - the mailing list archives and other online support resources. Furthermore, at - the PHP.net links page 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 the PHP.net support page. Furthermore, + there is a list of websites devoted to PHP articles, forums, and code galleries + at the PHP.net links page . How to help improve the documentation - There are three ways you can help to improve this documentation. + There are three ways everyone can help improve this documentation. - 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 &url.php.bugs;. - 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. - 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 + support options - 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 'About user notes' section of this - appendix. + annotation system. For details, see the section titled 'About user notes'. - 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 &url.php.dochowto;. - 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 - #phpdoc on irc.freenode.net. + The PHP Documentation Project also has an IRC channel where many manual + authors hang out. Stop by #phpdoc on + irc.freenode.net and discuss ways to improve + the PHP documentation. @@ -369,7 +370,7 @@ Returns the length of string. for maintenance and formatting. - Using XML as a source format gives us + Using XML 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 HTML and @@ -384,18 +385,10 @@ Returns the length of string. additional conversions and formatting. - You can download the manual in various languages and - formats, including plain HTML, - PDF, PalmPilot DOC, PalmPilot iSilo, and - Windows HTML Help, from - &url.php.docs;. - Note that due to technical reasons, some formats may - be unavailable. - - - You can find more information about downloading the - XML source code of this documentation - at &url.php.cvs;. The + The PHP manual is generated in various languages and formats, see + &url.php.docs; for additional details. + The XML source code may be downloaded from CVS and + viewed at &url.php.cvs;. The documentation is stored in the phpdoc module. @@ -415,20 +408,21 @@ Returns the length of string. People involved in the translations start from the XML source code available from &url.php.cvs; and from it they translate to their mother language. They do - not use the HTML, the plain text, - or the PDF version. It is the build system which takes - care of the conversions from XML to human readable formats. + not use the generated versions (like + HTML or plain text) as it's the build system that takes + care of the conversions from XML to human readable + formats. - 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 &email.php.doc.subscribe;. The mailing list address is &email.php.doc;. 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. @@ -439,7 +433,7 @@ Returns the length of string. Turkish. - They can all be downloaded here: &url.php.docs;. + They may all be downloaded here: &url.php.docs;.