mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-16 00:48:54 +00:00
Adding "more about this manual" appendix.
This should be expanded in the future with information on used conventions (eg. how to interpret a function usage example for newbies), and some more... git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@63159 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Gabor Hojtsy
parent
525a54f08e
commit
f4877c1226
1 changed files with 233 additions and 0 deletions
233
appendices/about.xml
Normal file
233
appendices/about.xml
Normal file
|
|
@ -0,0 +1,233 @@
|
|||
<?xml version="1.0" encoding="iso-8859-1"?>
|
||||
<!-- $Revision: 1.1 $ -->
|
||||
|
||||
<appendix id="moreabout">
|
||||
<title>More about this Manual</title>
|
||||
|
||||
<sect1 id="moreabout.formats">
|
||||
<title>PHP Manual 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 many 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. Using
|
||||
that you face the lack of offline search, but
|
||||
you gain the fast access to information anytime.
|
||||
</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 in a whole, as
|
||||
it can take so much reqources. 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 HTML Help (also known as CHM)
|
||||
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 only
|
||||
available on Windows operating systems.
|
||||
</para>
|
||||
</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>
|
||||
</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,
|
||||
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 busyest 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>.
|
||||
</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 to ways of doing this.
|
||||
</para>
|
||||
<para>
|
||||
If you find any 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". 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).
|
||||
</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.
|
||||
</para>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="moreabout.generate">
|
||||
<title>How we generate the formats</title>
|
||||
<para>
|
||||
This manual is written in <acronym>XML</acronym> using the <ulink
|
||||
url="&url.docbook.xml;">DocBook XML DTD</ulink>, using <ulink
|
||||
url="&url.dsssl;"><acronym>DSSSL</acronym></ulink> (Document
|
||||
Style and Semantics Specification Language) for formatting, and
|
||||
experimentaly the <ulink url="&url.xslt;"><acronym>XSLT</acronym>
|
||||
</ulink> (Extensible Stylesheet Language Transformations)
|
||||
for maintenance and formatting.
|
||||
</para>
|
||||
<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.
|
||||
The tools used for formatting <acronym>HTML</acronym> and
|
||||
<acronym>TeX</acronym> versions are
|
||||
<ulink url="&url.jade;">Jade</ulink>, written by <ulink
|
||||
url="&url.jclark;">James Clark</ulink> and <ulink
|
||||
url="&url.dbstyle;">The Modular DocBook Stylesheets</ulink>
|
||||
written by <ulink url="&url.nwalsh;">Norman Walsh</ulink>.
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
You can download the actual 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.
|
||||
</para>
|
||||
<para>
|
||||
You can find more information about downloading the
|
||||
<acronym>XML</acronym> source code of this documentation
|
||||
at <ulink url="&url.php.cvs;">&url.php.cvs;</ulink>. The
|
||||
documentation is stored in the <literal>phpdoc</literal> module.
|
||||
</para>
|
||||
</sect1>
|
||||
|
||||
</appendix>
|
||||
|
||||
<!-- Keep this comment at the end of the file
|
||||
Local variables:
|
||||
mode: sgml
|
||||
sgml-omittag:t
|
||||
sgml-shorttag:t
|
||||
sgml-minimize-attributes:nil
|
||||
sgml-always-quote-attributes:t
|
||||
sgml-indent-step:1
|
||||
sgml-indent-data:t
|
||||
sgml-parent-document:nil
|
||||
sgml-default-dtd-file:"../../manual.ced"
|
||||
sgml-exposed-tags:nil
|
||||
sgml-local-catalogs:nil
|
||||
sgml-local-ecat-files:nil
|
||||
End:
|
||||
vim600: syn=xml fen fdm=syntax fdl=2 si
|
||||
vim: et tw=78 syn=sgml
|
||||
vi: ts=1 sw=1
|
||||
-->
|
||||
Loading…
Reference in a new issue