goba Sat Nov 24 11:44:22 2001 EDT
Added files:
/phpdoc/en/appendices about.xml
Log:
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...
Index: phpdoc/en/appendices/about.xml
+++ phpdoc/en/appendices/about.xml
<?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
-->
