sigmasternchen/php-doc-en
1
0
Fork 0
mirror of https://github.com/sigmasternchen/php-doc-en synced 2025-03-15 16:38:54 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
php-doc-en/appendices/about.xml
Christoph Michael Becker 86e6094e86 Use canonical type names 
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@351133 c90b9560-bf6c-de11-be94-00142212c4b1
2020-11-02 15:39:04 +00:00

465 lines
18 KiB
XML
Raw Blame History

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<appendix xml:id="about" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>About the manual</title>
<sect1 xml:id="about.formats">
<title>Formats</title>
<para>
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>
The manual can be read online at the <link xlink:href="&url.php;">PHP.net website</link>.
The online version of the PHP manual has currently two
<acronym>CSS</acronym> stylesheets, web friendly and a printer-friendly stylesheet.
</para>
<para>
Two notable advantages of the online manual over most of the offline formats is the
integration of <link linkend="about.notes">user-contributed
notes</link> and the <link xlink:href="&url.php.urlhowto;">URL shortcuts</link> that
may be used to get to the desired manual parts quickly. An obvious disadvantage is
the requirement to be online to view this edition of the manual.
</para>
<para>
There are several offline formats of the manual, and the most appropriate
format for depends on the operating system, and personal
reading style. For information on how the manual is generated in so many
formats, read the <link linkend="about.generate">'How we generate the
formats'</link> section of this appendix.
</para>
<para>
The most cross-platform format of the manual is the HTML version. This
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).
We provide these versions compressed, so a decompression utility is
required to retrieve the files contained within the archives.
</para>
<!--
The PDF version of the PHP Manual is "currently" unavailable. Perhaps
one day it will exist.
<para>
Another popular cross-platform format, and the format most suited to
printing, is PDF (also known as Adobe Acrobat). But beware that the manual
is over 2000 pages in length, and constantly being revised.
</para>
<note>
<para>
Many programs exist to view <acronym>PDF</acronym> files, such as the
<link xlink:href="&url.adobe.acrobat;">Adobe Acrobat Reader</link>.
</para>
</note>
-->
<para>
For Windows platforms, the <productname>Windows HTML Help</productname>
version of the manual enhances the HTML format for use with the
<productname>Windows HTML Help</productname> 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. CHM viewers for
Linux desktops are also available. Check out
<link xlink:href="&url.xchm;">xCHM</link> or
<link xlink:href="&url.gnochm;">GnoCHM</link>.
</para>
<para>
There is also an <link xlink:href="&url.php.echm;">extended CHM version</link>
available, which is updated less frequently, but provides many additional
features. It will only work on <productname>Microsoft Windows</productname>
though, because of the technologies used to build the help pages.
</para>
</sect1>
<sect1 xml:id="about.notes">
<title>About user notes</title>
<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 may 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>
<note>
<para>
For the purposes of license coverage the user-contributed notes are
considered part of the PHP manual, and are therefore covered by the
same license that covers this documentation (Creative Commons Attribution
at the moment). For
more details see the <link linkend="copyright">Manual's Copyright</link>
page.
</para>
</note>
</sect1>
<sect1 xml:id="about.prototypes">
<title>How to read a function definition (prototype)</title>
<para>
Each function in the manual is documented for quick reference. Knowing how
to read and understand the text will make learning PHP
much easier. Rather than relying on examples or cut/paste, everyone should
know how to read function definitions (prototypes). Let's begin:
</para>
<note>
<title>
Prerequisite: Basic understanding of <link linkend="language.types">types</link>
</title>
<para>
Although PHP is a loosely typed language, it's important to have
a basic understanding of <link linkend="language.types">types</link> as
they have important meaning.
</para>
</note>
<para>
Function definitions tell us what
type of value is <link linkend="functions.returning-values">returned</link>.
Let's use the definition for <function>strlen</function> as our first example:
</para>
<para>
<screen role="html">
<![CDATA[
strlen
(PHP 4, PHP 5)
strlen -- Get string length
Description
strlen ( string $string ) : int
Returns the length of given string.
]]>
</screen>
</para>
<para>
<table>
<title>Explanation of a function definition</title>
<tgroup cols="2">
<thead>
<row>
<entry>Part</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>
strlen
</entry>
<entry>
The function name.
</entry>
</row>
<row>
<entry>
(PHP 4, PHP 5)
</entry>
<entry>
strlen() has been around in all versions of PHP 4 and PHP 5
</entry>
</row>
<row>
<entry>
( string $string )
</entry>
<entry>
The first (and in this case the only) parameter/argument for this
function is named <parameter>string</parameter>, and it's a
<type>string</type>.
</entry>
</row>
<row>
<entry>
int
</entry>
<entry>
Type of value this function returns, which is an
<type>int</type> (i.e. the length of a string is measured in
numbers).
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
We could rewrite the above function definition in a generic way:
</para>
<para>
<screen>
<![CDATA[
function name ( parameter type parameter name ) : returned type
]]>
</screen>
</para>
<para>
Many functions take on multiple parameters, such as <function>in_array</function>.
Its prototype is as follows:
</para>
<para>
<screen>
<![CDATA[
in_array ( mixed $needle, array $haystack [, bool $strict = FALSE ] ) : bool
]]>
</screen>
</para>
<para>
What does this mean? in_array() returns a
<link linkend="language.types.boolean">boolean</link> value, &true; on
success (if the <parameter>needle</parameter> was found in the
<parameter>haystack</parameter>)&return.falseforfailure; (if the
<parameter>needle</parameter> was not found in the
<parameter>haystack</parameter>). The first parameter is named
<parameter>needle</parameter> and it can be of many different
<link linkend="language.types">types</link>, so we call it
"<emphasis>mixed</emphasis>". This mixed <parameter>needle</parameter>
(what we're looking for) can be either a scalar value (string, integer,
or <link linkend="language.types.float">float</link>), or an
<link linkend="language.types.array">array</link>.
<parameter>haystack</parameter> (the array we're searching in) is the
second parameter. The third <emphasis>optional</emphasis> parameter is
named <parameter>strict</parameter>. All optional parameters are seen
in <emphasis>[</emphasis> brackets <emphasis>]</emphasis>. The manual
states that the <parameter>strict</parameter> parameter defaults to
boolean &false;. See the manual page on each function for details on
how they work.
</para>
<para>
In addition the &amp; (ampersand) symbol prepended to a function parameter
allows the parameter to be passed by <link linkend="language.references.pass">reference</link>, as seen below:
</para>
<para>
<screen>
<![CDATA[
preg_match ( string $pattern , string $subject [, array &$matches
[, int $flags = 0 [, int $offset = 0 ]]] ) : int
]]>
</screen>
</para>
<para>
In this example, we can see the third optional parameter <parameter>&amp;$matches</parameter> will be
passed as reference.
</para>
<para>
There are also functions with more complex PHP version information. Take
<function>html_entity_decode</function> as an example:
</para>
<para>
<screen>
<![CDATA[
(PHP 4 >= 4.3.0, PHP 5)
]]>
</screen>
</para>
<para>
This means that this function has only been
available in a released version since PHP 4.3.0.
</para>
</sect1>
<sect1 xml:id="about.phpversions">
<title>PHP versions documented in this manual</title>
<para>
The manual contains information about past, current, and future versions
of PHP. Changes in behaviour are documented as notes, changelogs, and
inline text within the manual pages.
The earliest documented version is PHP 7.0.0.
</para>
<para>
When documentation exists for the latest (unreleased) developmental versions
of PHP, it will be labeled as either "available in Git" or "development
version." And while these changes should be planned for, in rare cases they
may change.
</para>
<para>
All development takes place in Git and may be checked out
as described within the <link xlink:href="&url.php.anongit;">anonymous Git
access</link> page.
</para>
<para>
And to clarify, the manual will refer to major, minor and point PHP releases.
Using PHP <literal>7.3.1</literal> as an example, the <emphasis>7</emphasis>
refers to the major version, <emphasis>3</emphasis> to minor, and
<emphasis>1</emphasis> is the point release. Typically PHP only adds new features
to major and minor releases, and fixes bugs in point releases. However, this
convention is not always true.
</para>
<para>
Also note that the PHP manual is written in present tense, not future tense,
even for documented features that are not yet available. The reason for this
is so the manual can stand the test of time, thus not require tedious grammar
updates with every PHP release.
</para>
<para>
Many times the PHP manual lists "Default Values" for PHP directives. These
values are based on how PHP behaves without a &php.ini; configuration file,
so this may differ from values found in the distributed
<filename>php.ini-development</filename> and <filename>php.ini-production</filename>
files. They also refer to the latest version of PHP, although changelog entries
do mention past values. See the <link linkend="ini.list">PHP directive
appendix</link> for details regarding these values and changes.
</para>
</sect1>
<sect1 xml:id="about.more">
<title>How to find more information about PHP</title>
<para>
This manual does not attempt to provide instruction about general
programming practices. First-time - or even just beginning -
programmers may find it difficult to learn how to program in PHP using
this manual exclusively. Instead, seek out a text more oriented towards
beginners.
</para>
<para>
There are a number of active mailing lists for discussion on all aspects of
programming with PHP. If stuck with a problem, consider using these lists.
For support options, including mailing lists, view <link
xlink:href="&url.php.support;">the PHP.net support page</link>.
</para>
</sect1>
<sect1 xml:id="about.howtohelp">
<title>How to help improve the documentation</title>
<para>
There are three ways everyone can help improve this documentation.
</para>
<para>
If an error is found in this manual, in any language, please report them
using the bug system at <link xlink:href="&url.php.bugs;">&url.php.bugs;</link>.
Classify the bug as <literal>"Documentation Problem"</literal>. All documentation related
problems, including those about manual formats, should be submitted as bug
reports.
</para>
<note>
<para>
Please don't abuse the bug system by submitting requests for help.
Instead, use one of the many
<link xlink:href="&url.php.support;">support options</link>.
</para>
</note>
<para>
By contributing notes, users may provide additional examples, caveats, and
clarifications for other readers. But please do not submit bug reports using the
annotation system. For details, see the section titled <link
linkend="about.notes">'About user notes'</link>.
</para>
<para>
The PHP manual is translated into many languages. Knowing English and a
foreign language allows for another way to help improve the PHP manual by
working with a translation team. For information about starting a new
translation, or helping a currently translated version, please read
<link xlink:href="&url.php.dochowto;">&url.php.dochowto;</link>.
</para>
<para>
The PHP Documentation Project also has an IRC channel where many manual
authors hang out. Stop by <literal>#php.doc</literal> on
<literal>irc.efnet.org</literal> and discuss ways to improve
the PHP documentation.
</para>
</sect1>
<sect1 xml:id="about.generate">
<title>How we generate the formats</title>
<para>
This manual is written in <acronym>XML</acronym> using the <link
xlink:href="&url.docbook.xml;">DocBook XML DTD</link>, using <link
xlink:href="&url.phd;"><acronym>PhD</acronym></link> (The [PH]P based
[D]ocBook renderer) for maintenance and formatting.
</para>
<para>
Using <acronym>XML</acronym> as a source format gives
the ability to generate many output formats from the source
files, while only maintaining one source document for all formats.
The tool used for formatting the online manual is <link
xlink:href="&url.phd;">PhD</link>.
We use <link xlink:href="&url.winhelp;">Microsoft HTML Help
Workshop</link> to generate the <productname>Windows HTML Help</productname> format
of the manual, and of course PHP itself to do some
additional conversions and formatting.
</para>
<para>
The PHP manual is generated in various languages and formats, see
<link xlink:href="&url.php.docs;">&url.php.docs;</link> for additional details.
The <acronym>XML</acronym> source code may be downloaded from SVN and
viewed at <link xlink:href="&url.php.svn;">&url.php.svn;</link>. The
documentation is stored in the <literal>phpdoc</literal> module.
</para>
</sect1>
<sect1 xml:id="about.translations">
<title>Translations</title>
<para>
The PHP manual is available not only in various formats, but
also in various languages. The text of the
manual is first written in English, then teams of people across
the world take care of translating it to their native languages.
If a translation for a specified function or chapter has not yet
been made, the manual's build system falls back to the
English version of it.
</para>
<para>
People involved in the translations start from the <acronym>XML</acronym>
source code available from <link xlink:href="&url.php.svn;">&url.php.svn;</link>
and from it they translate to their mother language. They do
<emphasis>not use</emphasis> the generated versions (like
<acronym>HTML</acronym> or plain text) as it's the build system that takes
care of the conversions from <acronym>XML</acronym> to human readable
formats.
</para>
<note>
<para>
To help translate the documentation,
please get in touch with the translation/documentation team by
subscribing to the phpdoc mailing list: send an empty mail to <link
xlink:href="mailto:&email.php.doc.subscribe;">&email.php.doc.subscribe;</link>.
The mailing list address is <literal>&email.php.doc;</literal>. State in the
message an interest in translating the manual and someone will reply with
feedback on moving forward by helping start a new language translation, or
by contacting the existing team for the desired language.
</para>
</note>
<para>
At the moment the manual is available, partly or not, in over 10 languages.
</para>
<para>
They may all be downloaded here: <link xlink:href="&url.php.docs;">&url.php.docs;</link>.
</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
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/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
-->
Reference in a new issue View git blame Copy permalink