archived-doc-ru/appendices/about.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: e8ac70bf549a723cb36465667a6109d9933b8619 Maintainer: shein Status: ready -->
<!-- Reviewed: no -->
<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 и 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">логическое значение</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>
   по умолчанию принимает логическое значение &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>
   Версию отметят как «доступна в Git», либо «разрабатываемая версия»,
   если существует документация для последних (ещё невыпущенных) версий
   PHP.
   И хотя эти изменения стоит учитывать в планировании, в редких случаях они могут измениться.
  </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.git;">&url.php.git;</link>;
   об ошибках в руководстве на английском языке сообщайте по адресу <link xlink:href="&url.php.git;doc-en/issues">&url.php.git;doc-en/issues</link>.
   Проблемы с документацией, включая ошибки с форматами руководства,
   необходимо отправлять как сообщение об ошибке.
  </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>. Файлы PHP-документации обрабатывает <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>,
   мы пользуемся компилятором CHM-файлов <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
-->