mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-16 00:48:54 +00:00
clean up.
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@65344 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
parent
a2ad995036
commit
e166aad083
1 changed files with 113 additions and 142 deletions
|
@ -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.
|
||||
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>
|
||||
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.
|
||||
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>
|
||||
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>.
|
||||
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 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.
|
||||
</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.
|
||||
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>
|
||||
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.
|
||||
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>.
|
||||
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.
|
||||
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>
|
||||
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>.
|
||||
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.
|
||||
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 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.
|
||||
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
|
||||
|
|
Loading…
Reference in a new issue