sigmasternchen/php-doc-en
1
0
Fork 0
mirror of https://github.com/sigmasternchen/php-doc-en synced 2025-03-16 00:48:54 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

clean up.

Browse source 
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@65344 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
jim winstead 2001-12-16 22:17:40 +00:00
parent a2ad995036
commit e166aad083
1 changed files with 113 additions and 142 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

255
appendices/about.xml
View file

@ -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