archived-doc-uk/appendices/about.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: e8ac70bf549a723cb36465667a6109d9933b8619 Maintainer: mproshchuk Status: ready -->

<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;">ярлики URL-адрес</link>, які 
   використовуються для швидкого переходу до потрібних частин посібника. 
   Очевидним недоліком є обов'язкове інтернет-з'єднання, аби переглядати 
   найновішу редакцію даного посібника.
  </para>
  <para>
   Серед багатьох офлайн-форматів посібника ви можете обрати найбільш доречний, 
   опираючись на операційну систему вашого комп'ютера, чи особистий стиль 
   читання. Щоб дізнатися, як, власне, посібник генерується у стількох форматах,
   прочитайте в цьому додатку розділ 
   <link linkend="about.generate">"Як ми генеруємо формати"</link>.
  </para>
  <para>
   Найбільш крос-платформний формат посібника — це HTML-версія. Вона надається як
   один HTML-файл, так і пакунок окремих файлів для кожного розділу (результат —
   масив з декількох тисяч файлів). Ми надаємо цю версію стиснутою, тож щоб 
   отримати файли, що містяться в архіві, потрібна утиліта-архіватор.
  </para>
  <!--
   PDF-версія Посібника з PHP "наразі" не доступна. Можливо, одного дня вона 
   буде існувати.
  <para>
   Інший популярний крос-платформний формат, а також той, що найкраще підходить 
   для друку — це PDF (ще відомий як Adobe Acrobat). Проте, майте на увазі, що 
   посібник має більш ніж 2000 сторінок, і він постійно оновлюватиметься.
  </para>
  <note>
   <para>
    Існує багато програм для перегляду файлів <acronym>PDF</acronym>, наприклад
    <link xlink:href="&url.adobe.acrobat;">Adobe Acrobat Reader</link>.
   </para>
  </note>
  -->
  <para>
   Для платформ Windows є версія <productname>"Windows HTML Help"</productname> 
   з форматом HTML, підлаштованим для читання в програмі 
   <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>
    З метою покриття ліцензією (на цей момент Creative Commons Attribution), 
    нотатки, внесені користувачами вважаються частиною посібника з PHP і тому на
    них поширюється та сама ліцензія, яка охоплює цю документацію. За
    докладнішою інформацією перейдіть на сторінку 
    <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> та чому вони 
    важливі.
   </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>mixed</emphasis>" (змішаним).  Це <parameter>needle</parameter> 
   (шукане) зі змішаним типом може мати скалярне значення (рядок, ціле 
   число, <link linkend="language.types.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>
   Якщо існуватиме документація до останньої версії 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 поводиться, коли 
   відсутній файл налаштувань &php.ini;, тож вони можуть відрізнятися від 
   значень в файлах <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-en">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> та обговоріть шляхи вдосконалення 
   PHP-документації.
  </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> ([PH]P, що 
   базується на візуалізаторі [D]ocBook).
  </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>
   Посібник з PHP генерується різними мовами та у різних форматах, дивіться 
   <link xlink:href="&url.php.docs;">&url.php.docs;</link> для додаткової 
   інформації. Сирцевий код на <acronym>XML</acronym> можна завантажити чи
   переглянути на <link xlink:href="&url.php.git.mirror;doc-en">
   &url.php.git.mirror;doc-en</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-en">
   &url.php.git.mirror;doc-en</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>
   На даний момент посібник доступний більш ніж десятьма мовами (повністю або 
   частково).
  </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
-->