jimw Sun Dec 16 17:17:40 2001 EDT
Modified files:
/phpdoc/en/appendices about.xml
Log:
clean up.
Index: phpdoc/en/appendices/about.xml
diff -u phpdoc/en/appendices/about.xml:1.5 phpdoc/en/appendices/about.xml:1.6
--- phpdoc/en/appendices/about.xml:1.5 Wed Dec 12 15:46:25 2001
+++ phpdoc/en/appendices/about.xml Sun Dec 16 17:17:40 2001
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.5 $ -->
+<!-- $Revision: 1.6 $ -->
<!--
TODO: add manual conventions section (eg. how to read
@@ -10,180 +10,151 @@
offline), and using "http://anymirror.php.net/funcname";
-->
<appendix id="moreabout">
- <title>More about this Manual</title>
+ <title>About the manual</title>
<sect1 id="moreabout.formats">
- <title>PHP Manual formats</title>
+ <title>Formats</title>
<para>
- 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.
- </para>
- <para>
- You can read the Manual online at <ulink url="&url.php;">
- &url.php;</ulink> 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 <link linkend="moreabout.notes">user notes</link>,
- 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.
- </para>
- <para>
- 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 <link linkend="moreabout.generate">How we
- generate the formats</link>.
- </para>
- <para>
- 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.
- </para>
- <para>
- 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 <ulink url="&url.adobe.acrobat;">Adobe
- Acrobat Reader</ulink> to read the PDF files.
- </para>
- <para>
- 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
- <ulink url="&url.palm.doc;">DOC</ulink>
- or <ulink url="&url.palm.isilo;">iSilo</ulink>
- 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.
- </para>
- <para>
- 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
- <acronym>CHM</acronym>) 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
- <ulink url="&url.vb4linux;">sourceforge
- page</ulink>, if you are interested in the progress.
+ 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 a 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="moreabout.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="moreabout.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 compressed tar files (using both gzip and bzip2) and ZIP
+ archives.
+ </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="moreabout.notes">
<title>About user notes</title>
<para>
- 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.
- </para>
- <para>
- Note, that the user notes are not moderated before
- they appear on the PHP sites, so the quality of
- content cannot be guaranteed.
- </para>
- <para>
- If you can't find a solution for your problem in
- the user notes, you may consider reading the
- section <link linkend="moreabout.more">How to find
- more information about PHP</link>.
- </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="moreabout.more">
<title>How to find more information about PHP</title>
<para>
- 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
- <ulink url="&url.php.books;">&url.php.books;</ulink>.
- 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.
- </para>
- <para>
- 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 <ulink
- url="&url.php.support;">&url.php.support;</ulink>.
- You can also find IRC channels linked on this
- page in the left bar.
- </para>
- <para>
- If you are not fan of mail discussions, you can also
- find many community sites listed on our links page at
- <ulink url="&url.php.links;">&url.php.links;</ulink>.
+ 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="moreabout.howtohelp">
<title>How to help improve the documentation</title>
<para>
- 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.
</para>
<para>
- If you find any errors within 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". 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.
- </para>
- <para>
- 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 <link
- linkend="moreabout.notes">About user notes</link> part.
+ 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="moreabout.notes">'About user notes'</link> section of this
+ appendix.
</para>
</sect1>
@@ -201,7 +172,7 @@
<para>
Using <acronym>XML</acronym> 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 <acronym>HTML</acronym> and
<acronym>TeX</acronym> versions are
<ulink url="&url.jade;">Jade</ulink>, written by <ulink
@@ -211,15 +182,15 @@
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
- conversions, and formatting.
+ additional conversions and formatting.
</para>
<para>
- You can download the actual manual in various languages and
+ 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 as the source XML files are changed.
+ The manuals are updated automatically as the text is updated.
</para>
<para>
You can find more information about downloading the
