diff --git a/appendices/about.xml b/appendices/about.xml index d55d7c6086..20bdf20c35 100644 --- a/appendices/about.xml +++ b/appendices/about.xml @@ -1,5 +1,5 @@ - + - More about this Manual + About the manual - PHP Manual formats + Formats - We provide the PHP Manual in several formats. For first - glance, these formats can be devided into two groups, - online readable formats and downloadable packages. + The PHP manual is provided in several formats. These formats can be divided + into two groups: online readable formats, and downloadable packages. + + + + 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. + + + + You can read the manual online at &url.php; + 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 a an HTML format that integrates the manual + into the look and feel of the PHP website itself. - You can read the Manual online at - &url.php; and on the several mirror sites. We advise - you to choose one nearby mirror site, if you would like - to use this form of our Manual, as you can get better - speed. For the online Manual you can choose from two - layouts, so you always have the ability to view the printer - friendly version if you have a slow connection, or would - like to print out one page. The main advantage of these - online Manuals is that you can read the most actual manual - along the user notes, - and you don't need to set up any software, as you only need - a web browser to see it. The major disadvantage is that you - need to always be online, you can face with server - availability problems, you can't do a full text search on - the manual, and there is no full index of manual pages. + An advantage of the online manual over most of the offline formats is the + integration of user-contributed + notes. An obvious disadvantage is that you have to be online to view + the manual in the online formats. - If you decide to download the PHP Manual, you can choose - from many different formats we provide. What you choose - depends on your operating system, and your personal - reading style. If you are interested, how we can generate - these various formats, read on the technical part of this - appendix named How we - generate the formats. + 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 'How we generate the + formats' section of this appendix. - The HTML and text files may be the most crossplatform - format, as there is a text viewer and/or a browser - on all operating systems. We provide the HTML files - in several compressed formats for the different - operating systems. Using the all-on-one-page HTML - or text version is not ideal for day to day work, - although full text search is easy in such files. - Note, that the compressed file with several HTML - files contain more than 2000 files. You can serach in - these files using your OS search capabilities such as the - global search dialog on Windows or grep on unix like - systems. Since it is not very comfortable using these tools, - avail yourself of the online search as often as needed. + 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 compressed tar files (using both gzip and bzip2) and ZIP + archives. - PDF is also a popular cross platform format. This - is the best for printing, although we do not - recommend printing out the manual on the whole, as - it can take so much resources. As the manual - changes from day to day, think twice before - you print out the whole manual. Viewing PDF, - you have the full text search ability. Note, that - you need Adobe - Acrobat Reader to read the PDF files. + 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. + + + + If you do not already have a program capable of viewing PDF format + files, you may need to download Adobe + Acrobat Reader. + + + + 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 DOC + or iSilo reader to brush up on your + PHP knowledge, or just use it as a quick reference. - The PalmPilot DOC and iSilo formats are ideal - if you travel a lot and would like to learn - more from the manual while on road or in air. - You can bring your Palm with you, with the - DOC - or iSilo - reader installed respectively for the format - you downloaded. This is not the best way to - learn PHP, but can be handy to get answers - quickly. - - - At last, but not least, we have a Windows - HTML Help version of the PHP Manual. It is - actually a spiced up HTML package. The biggest - advantage of the Compiled HTML (also known as - CHM) version is that the viewer - provides full text search, search in search results, - full index, and bookmarking. This format also kindly - integrates with many popular PHP IDEs on Windows. - The biggest disadvantage is that it is currently only - available on Windows operating systems. You also - need the MS Internet Explorer 4.0 or newer to access the - CHM version, if you are on an older Windows system. - A Visual Basic for Linux project is under the planing - stage, which would include the development of a CHM - Creator and Viewer for Linux. See their - sourceforge - page, if you are interested in the progress. + 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. + + + 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 + SourceForge.net page if you are + interested in the progress. + + About user notes - User notes are an important part while reading the - PHP Manual. Some user notes contain very valuable - information. We basically set up the user note system, - to let people add their own examples, warnings about - functions, language elements, etc. - - - Note, that the user notes are not moderated before - they appear on the PHP sites, so the quality of - content cannot be guaranteed. - - - If you can't find a solution for your problem in - the user notes, you may consider reading the - section How to find - more information about PHP. + 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. + + + 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.) + + How to find more information about PHP - This Manual is not intended to be a full programmers - quide. If you are completely a beginner in programming, - you might not get used to PHP by only reading the Manual. - You may consider buying a book with deeper explanation - on simple programming tasks. You can find a listing - of books at - &url.php.books;. - We do not recommend you to buy a reprint of the PHP - Manual, because these are commonly quite outdated. - Consider that the PHP manual is changing from day - to day. + 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 &url.php.books;. - If you think someone already faced the exact problem and - you are stuggling, you can ask your questions on - one of our popular mailing lists. There are plenty - of them grouped by subject. You may receive an answer - for your question in minutes in the busiest hours. - You can subscribe to one mailing list at &url.php.support;. - You can also find IRC channels linked on this - page in the left bar. - - - If you are not fan of mail discussions, you can also - find many community sites listed on our links page at - &url.php.links;. + 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 &url.php.support;, as well as links to the + mailing list archives and other online support resources. Furthermore, at + &url.php.links; there is a list of + websites devoted to PHP articles, forums, and code galleries. How to help improve the documentation - Of course you can help to improve our documentation. - There are basically two ways of doing this. + There are two ways you can help to improve this documentation. - If you find any errors within this manual, in any language, - please report them using the bug system at: - &url.php.bugs;. - Classify the bug as "Documentation Problem". This way - we can follow every bug and track the things done to - eliminate them from the documentation. You can also - submit format problems (eg. PHP Manual PDF displayed - incorrectly). Please don't abuse the bug system by submitting - requests for help, use the mailing lists or community sites - mentioned above, instead. + If you find errors 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 here. + + + Please don't abuse the bug system by submitting requests for help. Use the + mailing lists or community sites mentioned earlier, instead. + + - By adding annotations to pages, you can provide more - examples to readers than any single manual writer. - Readers very much appreciate useable user comments. - Do not submit bug reports using the annotation system - please. Read more about annotations in the About user notes part. + 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 'About user notes' section of this + appendix. @@ -201,7 +172,7 @@ Using XML as a source format gives us the ability to generate many output formats from the source - files, only maintaining one source document for all formats. + files, while only maintaining one source document for all formats. The tools used for formatting HTML and TeX versions are Jade, written by Microsoft HTML Help Workshop to generate the Windows HTML Help format of the manual, and of course PHP itself to do some - conversions, and formatting. + additional conversions and formatting. - You can download the actual manual in various languages and + You can download the manual in various languages and formats, including plain text, plain HTML, PDF, PalmPilot DOC, PalmPilot iSilo and Windows HTML Help, from &url.php.docs;. - The manuals are updated as the source XML files are changed. + The manuals are updated automatically as the text is updated. You can find more information about downloading the