about.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: acf178ef8c40ad8d11f79da8619758ac624c9536 Maintainer: shein Status: ready -->
<!-- Reviewed: yes Maintainer: sergey -->
<!-- $Revision$ -->
<appendix xml:id="about" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Об этом руководстве</title>

 <sect1 xml:id="about.formats">
  <title>Форматы</title>
  <para>
   Руководство по PHP доступно в нескольких форматах. Эти форматы могут
   быть разделены на две группы: формат для чтения онлайн и форматы,
   доступные для загрузки.
  </para>
  <note>
   <para>
    Некоторые издательства выпустили печатные версии этого руководства.
    Однако, мы не рекомендуем пользоваться ими вследствие их быстрого
    устаревания.
   </para>
  </note>
  <para>
   Вы можете пользоваться руководством онлайн
   <link xlink:href="&url.php;">на сайте PHP.net</link>.
   В данный момент онлайн версия PHP
   руководства имеет два отдельных стиля <acronym>CSS</acronym> - для просмотра
   онлайн (веб) и предназначенный для печати.
  </para>
  <para>
   Преимуществом онлайн руководства над большинством оффлайн форматов
   является интеграция с <link linkend="about.notes">замечаниями
   пользователей</link> и <link xlink:href="&url.php.urlhowto;">быстрыми ссылками</link>,
   очень удобными для быстрого доступа к желаемой части руководства.
   Очевидным недостатком является то, что вам нужно находиться в онлайне,
   чтобы пользоваться руководством в онлайн форматах.
  </para>
  <para>
   Существуют несколько форматов для использования в оффлайн, и вы
   можете выбрать формат, наиболее подходящий для использования в
   вашей операционной системе и отвечающий вашим читательским предпочтениям.
   Чтобы узнать больше о том, каким образом создаётся такое количество
   форматов руководства, обратитесь к разделу
   <link linkend="about.generate">'Как мы создаём форматы руководства'</link>.
  </para>
  <para>
   Наиболее кроссплатформенным форматом этого руководства является
   HTML-версия. Она доступна как в виде одного HTML-файла, так и в виде архива,
   содержащего несколько тысяч файлов, каждый из которых является отдельной главой руководства.
   Мы предоставляем эти версии руководств сжатыми, поэтому вам понадобится
   утилита разархивирования для доступа к файлам внутри архива.
  </para>
  <!--
   PDF версия руководства по PHP "в настоящее время" недоступна.
   Возможно, в один прекрасный день она появится.
  <para>
   Другим популярным кросс-платформенным форматом, к тому же наиболее
   подходящим для печати, является PDF (также известный как Adobe
   Acrobat). Но прежде чем вы начнёте загрузку этого формата и нажмёте
   на кнопку Печать, имейте в виду, что руководство состоит примерно
   из 2000 страниц и постоянно обновляется.
  </para>
  <note>
   <para>
    Если у вас ещё нет программы для просмотра формата PDF, вам нужно
    будет загрузить <link xlink:href="&url.adobe.acrobat;">Adobe
    Acrobat Reader</link>.
   </para>
  </note>
  -->
  <para>
   На платформах Windows доступна версия руководства в формате
   <productname>Windows HTML Help</productname>,
   который может быть просмотрен с помощью приложения
   <productname>Windows HTML Help</productname>.
   Эта версия предусматривает поиск по тексту руководства, содержание
   и поддержку использования закладок. Многие среды
   разработки PHP-программ в Windows также используют эту версию из-за лёгкости
   доступа. Существуют также программы для просмотра CHM под Linux.
   Смотрите <link xlink:href="&url.xchm;">xCHM</link> или <link xlink:href="&url.gnochm;">GnoCHM</link>.
  </para>

  <para>
   Есть также <link xlink:href="&url.php.echm;">расширенная версия CHM</link>,
   она обновляется реже, но зато обеспечивает множество дополнительных
   возможностей. К сожалению, из-за используемых технологий создания этого формата,
   она работает только на <productname>Microsoft Windows</productname>.
  </para>
 </sect1>

 <sect1 xml:id="about.notes">
  <title>О заметках пользователей</title>
  <para>
   Заметки пользователей играют большую роль в процессе создания
   этого руководства. Позволяя читателям высылать нам примеры, выявленные
   опечатки и другие сведения с помощью их браузеров, мы имеем возможность
   интегрировать эти замечания в основной текст руководства. Пока замечания пользователей
   не были добавлены в руководство, с ними можно ознакомиться онлайн
   и в некоторых оффлайн форматах.
  </para>
  <note>
   <para>
    Заметки пользователей не подвергаются модерации перед тем, как стать
    публично доступными, таким образом, качество написания примеров кода
    и даже их корректность не может быть гарантирована. (Так же, как
    не может быть гарантировано качество и точность собственно текста
    руководства).
   </para>
  </note>
  <note>
   <para>
    По лицензионному соглашению заметки пользователей рассматриваются
    как часть самого руководства по PHP, поэтому к ним применима
    та же лицензия, что и к самому руководству (на данный момент
    Creative Commons Attribution). Подробности могут быть найдены на странице
    <link linkend="copyright">Авторские права данного руководства</link>.
   </para>
  </note>
 </sect1>

 <sect1 xml:id="about.prototypes">
  <title>Как читать определения функции (прототип)</title>
  <para>
   Документация к каждой функции в руководстве была написана с учётом
   быстрого обращения к этой документации.
   Зная как правильно читать и понимать текст, вам будет намного проще изучать PHP.
   Вместо того, чтобы полагаться на примеры или копирование/вставку, нужно просто
   понять как читать определения функции (прототипы). Давайте начнём:
  </para>
  <note>
   <title>
    Предпосылки: Базовое понимание <link linkend="language.types">типов</link>
   </title>
   <para>
    Хотя PHP и является слабо типизированным языком, важно иметь базовое
    представление о <link linkend="language.types">типах</link>, так как они играют
    большую роль в PHP.
   </para>
  </note>
  <para>
   Определения функций показывают нам какого типа значения они
   <link linkend="functions.returning-values">возвращают</link>.
   Для первого примера возьмём определение функции <function>strlen</function>:
  </para>
  <para>
   <screen role="html">
<![CDATA[
strlen

(PHP 4, PHP 5, PHP 7)
strlen -- Возвращает длину строки

Описание
strlen ( string $string ) : int

Возвращает длину переданной строки.
]]>
   </screen>
  </para>
  <para>
   <table>
    <title>Объяснение определения функции</title>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>Часть</entry>
       <entry>Описание</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>
        strlen
       </entry>
       <entry>
        Имя функции.
       </entry>
      </row>
      <row>
       <entry>
        (PHP 4, PHP 5, PHP 7)
       </entry>
       <entry>
        strlen() была во всех версиях PHP 4, 5 и PHP 7
       </entry>
      </row>
      <row>
       <entry>
        ( string $string )
       </entry>
       <entry>
        Первый (и в данном случае единственный) параметр/аргумент этой функции
        называется <parameter>string</parameter>, а его типом является
        строка (<type>string</type>).
       </entry>
      </row>
      <row>
       <entry>
        int
       </entry>
       <entry>
        Тип возвращаемого этой функцией значения, в данном случае
        число (<type>int</type>) (так как длина строки измеряется числом).
       </entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
  <para>
   Можно переписать вышеуказанное определение функции в более общем виде:
  </para>
  <para>
   <screen>
<![CDATA[
      имя функции    ( тип параметра   имя параметра ) : возвращаемый тип
]]>
   </screen>
  </para>
  <para>
   Много функций принимают несколько параметров, например, <function>in_array</function>.
   Её прототип выглядит так:
  </para>
  <para>
   <screen>
<![CDATA[
      in_array ( mixed $needle, array $haystack , bool $strict = false ) : bool
]]>
   </screen>
  </para>
  <para>
   Что это означает?  in_array() возвращает
   <link linkend="language.types.boolean">boolean</link>, &true; в случае
   успешного выполнения (если <parameter>needle</parameter> был найден в
   <parameter>haystack</parameter>)&return.falseforfailure; (если
   <parameter>needle</parameter> не был найден в
   <parameter>haystack</parameter>).  Первый параметр называется
   <parameter>needle</parameter> ("иголка") и может принимать много различных
   <link linkend="language.types">типов</link>, поэтому он называется
   "<emphasis>смешанным</emphasis>".  Этот смешанный <parameter>needle</parameter>
   (то, что мы ищем) может быть любым скалярным значением (string, integer,
   или <link linkend="language.types.float">float</link>), либо
   <link linkend="language.types.array">массивом</link>.
   <parameter>haystack</parameter> ("стог сена", массив, в котором мы ищем) -
   это второй параметр. Третий <emphasis>необязательный</emphasis> параметр
   называется <parameter>strict</parameter> ("строго"). Все необязательные параметры имеют
   значения по умолчанию; если значение по умолчанию неизвестно, оно отображается как <literal>?</literal>
   Руководство указывает, что параметр <parameter>strict</parameter>
   по умолчанию принимает значение boolean &false;.
   Смотрите отдельную страницу документации по каждой функции для более подробной
   информации по их работе.
  </para>
  <para>
   Символ &amp; (амперсанд), поставленный перед параметром функции позволяет передавать
   значение этого параметра по <link linkend="language.references.pass">ссылке</link>:
  </para>
  <para>
   <screen>
<![CDATA[
       preg_match ( string $pattern , string $subject , array &$matches = null,
       int $flags = 0 , int $offset = 0 ) : int|false
]]>
   </screen>
  </para>
  <para>
   В данном примере мы можем использовать третий опциональный параметр
   <parameter>&amp;$matches</parameter>, который будет передан по ссылке.
  </para>
  <para>
   Есть также функции с более сложной информацией о версиях PHP.
   Возьмём для примера <function>html_entity_decode</function>:
  </para>
  <para>
   <screen>
<![CDATA[
(PHP 4 >= 4.3.0, PHP 5, PHP 7)
]]>
   </screen>
  </para>
  <para>
   Это означает, что функция появилась в официальных версиях языка только с выхода PHP 4.3.0.
  </para>
 </sect1>

 <sect1 xml:id="about.phpversions">
  <title>Версии PHP, документированные в этом руководстве</title>
  <para>
   Данное руководство содержит информацию о прошлых, настоящих и будущих версиях PHP.
   Изменения поведения документированы замечаниями, историей изменений и
   непосредственно в тексте самого руководства.
   Самой ранней документируемой версией PHP является 7.0.0.
  </para>
  <para>
   Если документация доступна для самой последней (ещё невыпущенной) разрабатываемой версии
   PHP, она помечается либо как "доступно в Git", либо "разрабатываемая версия".
   И хотя эти изменения запланированы, в редких случаях они могут измениться.
  </para>
  <para>
   Вся разработка ведётся в Git и может быть получена способом, описанным
   на странице <link xlink:href="&url.php.anongit;">анонимный доступ к Git</link>.
  </para>
  <para>
   Для ясности, руководство указывает основную, промежуточную и дробную версию релизов PHP.
   Возьмём для примера версию PHP <literal>7.3.1</literal>, <emphasis>7</emphasis>
   является основной версией, <emphasis>3</emphasis> является промежуточной, и
   <emphasis>1</emphasis> является дробной версией. Обычно новые возможности в PHP добавляются
   только в основных и промежуточных версиях, а исправления ошибок - в дробных. Однако,
   это соглашение не всегда верно.
  </para>
  <para>
   Также учтите, что руководство по PHP пишется в настоящем, а не в будущем времени,
   даже для задокументированных, но ещё недоступных возможностей. Это сделано для того,
   чтобы облегчить испытание временем для данного руководства, таким образом можно
   избежать рутинных грамматических правок с каждой новой выпущенной версией PHP.
  </para>
  <para>
   Много раз в руководстве указываются "значения по умолчанию" для различных директив PHP.
   Эти значения основаны на том, как ведёт себя PHP без конфигурационного файла &php.ini;,
   поэтому они могут отличаться от тех, что приведены в распространяемых вместе с PHP файлах
   <filename>php.ini-development</filename> и <filename>php.ini-production</filename>.
   Они также относятся к последней версии PHP, хотя история изменений упоминает только прошлые значения.
   За подробной информацией об этих значениях и их истории изменений обращайтесь к
   <link linkend="ini.list">приложению со списком PHP директив</link>.
  </para>
 </sect1>

 <sect1 xml:id="about.more">
  <title>Как узнать больше о PHP</title>
  <para>
   Это руководство не пытается охватить вопросы общего программирования.
   Если вы являетесь новичком или даже начинающим программистом, написание
   PHP-программ может показаться вам трудным, если вы будете использовать
   только это руководство. Вам, скорее всего, может понадобиться материал,
   более подходящий для начинающих.
  </para>
  <para>
   Существует несколько списков рассылки, предназначенных для
   обсуждения всех аспектов программирования на PHP. Если вы чувствуете,
   что не можете найти решение какой-либо проблемы, кто-нибудь из подписчиков
   списка, вполне вероятно, сможет вам помочь. Все виды поддержки пользователей,
   в том числе и почтовые списки рассылки, перечислены на <link
   xlink:href="&url.php.support;">странице поддержки PHP.net</link>.
  </para>
 </sect1>

 <sect1 xml:id="about.howtohelp">
  <title>Как помочь в написании документации</title>
  <para>
   Существуют несколько способов помочь нам в улучшении документации.
  </para>
  <para>
   Если вам встречаются ошибки в этом руководстве, на любом языке, сообщайте о них
   с помощью системы сообщения об ошибках, доступной по адресу
   <link xlink:href="&url.php.bugs;">&url.php.bugs;</link>. Классифицируйте ваше
   сообщение как <literal>"Documentation Problem"</literal> ("Ошибка в документации").
   Все проблемы с документацией, включая ошибки с различными форматами руководства,
   должны быть отправлены как сообщение об ошибке.
  </para>
  <note>
   <para>
    Пожалуйста, не используйте систему сообщения об ошибках для того,
    чтобы получить какого-либо рода помощь. Вместо этого воспользуйтесь
    какими-либо <link xlink:href="&url.php.support;">видами поддержки</link>, упомянутыми выше.
   </para>
  </note>
  <para>
   Посылая заметки, пользователи могут предоставить различные примеры, предостережения
   и разъяснения для других читателей. Но, пожалуйста, не используйте систему аннотации
   для сообщений об ошибках. Более подробные сведения о заметках пользователей вы можете получить,
   ознакомившись с главой <link linkend="about.notes">'О заметках пользователей'</link>
   этого приложения.
  </para>
  <para>
   Также можно отправить пулреквесты в
   <link xlink:href="&url.php.git.mirror;doc-ru">зеркало репозитория документации на GitHub</link>.
  </para>
  <para>
   Руководство по PHP было переведено на много языков.
   Знание английского и другого иностранного языка даёт вам ещё один способ
   улучшить это руководство, работая в команде переводчиков. Если вы
   собираетесь приступить к переводу, обратитесь к
   <link xlink:href="&url.php.dochowto;">&url.php.dochowto;</link>.
  </para>
  <para>
   Проект документации PHP также имеет IRC канал (чат), где можно найти много
   авторов данного руководства. Заходите на <literal>#php.doc</literal> на сайте
   <literal>irc.efnet.org</literal> и обсуждайте различные способы улучшить
   данное руководство.
  </para>
 </sect1>

 <sect1 xml:id="about.generate">
  <title>Как создаются форматы документации</title>
  <para>
   Это руководство написано на <acronym>XML</acronym> с использованием <link
   xlink:href="&url.docbook.xml;">DocBook XML DTD</link>, с помощью <link
   xlink:href="&url.phd;"><acronym>PhD</acronym></link> (The [PH]P based
   [D]ocBook renderer, Генератор из формата Docbook на PHP) в целях поддержки и форматирования.
  </para>
  <para>
   Использование <acronym>XML</acronym> в качестве единственного исходного формата
   позволяет нам создавать документацию во многих форматах, позволяя
   в то же время редактировать только один исходный документ для всех форматов.
   Утилитой для форматирования руководства является <link
   xlink:href="&url.phd;">PhD</link>.
   Для создания руководства в формате <productname>Windows HTML Help</productname>
   мы используем <link xlink:href="&url.winhelp;">Microsoft HTML Help Workshop</link> и,
   разумеется, сам PHP для дополнительных преобразований и форматирования.
  </para>
  <para>
   Вы можете загрузить руководство на многих языках и во многих форматах,
   более подробно смотрите <link xlink:href="&url.php.docs;">&url.php.docs;</link>.
   Исходный код <acronym>XML</acronym> можно загрузить из Git и просмотреть онлайн
   по адресу <link xlink:href="&url.php.git.mirror;doc-ru">&url.php.git.mirror;doc-ru</link>.
  </para>
 </sect1>

 <sect1 xml:id="about.translations">
  <title>Переводы</title>
  <para>
   Руководство по PHP доступно не только в нескольких форматах,
   но и на различных языках. Сначала текст руководства пишется на
   английском, а затем команды людей по всему миру
   переводят его на свой родной язык. Если перевод документации какой-либо функции
   или главы ещё не был завершён, система сборки руководства
   использует соответствующий английский вариант.
  </para>
  <para>
   Люди, осуществляющие перевод документации, начинают с использования
   исходного кода в формате <acronym>XML</acronym>, доступного по адресу
   <link xlink:href="&url.php.git.mirror;doc-ru">&url.php.git.mirror;doc-ru"</link> и затем переводят его
   на свой родной язык. Для перевода <emphasis>не используются</emphasis>
   сгенерированные версии (например, <acronym>HTML</acronym> или обычный текст),
   так как система сборки документации сама заботится о преобразовании <acronym>XML</acronym> в читабельные форматы.
  </para>
  <note>
   <para>
    Если вы хотите принять участие в переводе документации на ваш родной язык,
    присоединитесь к команде перевода, подписавшись на список рассылки phpdoc:
    вышлите пустое сообщение на адрес <link
    xlink:href="mailto:&email.php.doc.subscribe;">&email.php.doc.subscribe;</link>.
    Адрес списка рассылки - <literal>&email.php.doc;</literal>. Укажите в
    сообщении, что вы заинтересованы в участии в переводе руководства
    и кто-нибудь поможет вам начать новый перевод или найти команду, занимающуюся
    переводом на ваш язык.
   </para>
  </note>
  <para>
   В настоящее время руководство доступно, частично или в полной мере, на более чем 10 языках.
  </para>
  <para>
   Все эти версии руководства доступны для загрузки по адресу
   <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
-->