archived-doc-fr/appendices/about.xml

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

<appendix xml:id="about" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>À propos du manuel</title>
 
 <sect1 xml:id="about.formats">
  <title>Formats</title>
  <para>
   Le manuel PHP est fourni en différents formats. Ces formats sont divisés en
   deux groupes : ceux qui sont disponibles en ligne et les téléchargeables.
  </para>
  <note>
   <para>
    Certains éditeurs ont fourni des versions imprimées de ce manuel. Nous n'en
    recommandons aucune, car elles sont rapidement obsolètes.
   </para>
  </note>
  <para>
   Le manuel peut être lu en ligne sur le site
   <link xlink:href="&url.php;">php.net</link>.
   La version en ligne du manuel PHP a actuellement deux rendus
   <acronym>CSS</acronym> : un rendu agréable à l'œil et un pratique pour
   l'impression.
  </para>
  <para>
   Deux avantages du manuel en ligne sur la plupart des formats
   téléchargeables, sont l'intégration des <link
   linkend="about.notes">notes des utilisateurs</link> et les <link
   xlink:href="&url.php.urlhowto;">URL de raccourci</link> qui permettent
   d'accéder rapidement à une partie du manuel. Un inconvénient
   évident est qu'il faut être en ligne pour profiter de ce format.
  </para>
  <para>
   Il y a de nombreux formats du manuel pour la consultation hors ligne, et
   le format le plus approprié dépend du système d'exploitation et des goûts personnels.
   Pour savoir comment le manuel est généré, se reporter à la section
   <link linkend="about.generate">'Comment le manuel est généré'</link> de cet
   appendice.
  </para>
  <para>
   Le format le plus portable est le HTML. Le manuel est fourni
   dans un format en une seule page HTML, ou comme un ensemble de fichiers
   de tailles réduites (mais un bon millier de fichiers tout de même). Nous
   fournissons ce format sous une forme compressée, il est donc nécessaire de disposer
   d'un utilitaire de décompression pour extraire les fichiers de l'archive.
  </para>
  <para>
   Pour les plates-formes Windows, le format
   <productname>Windows HTML Help</productname> fournit une version HTML
   du manuel à utiliser avec l'application <productname>Windows HTML Help</productname> :
   il intègre un moteur de recherche complet, un index et des signets. De
   nombreux IDE sous Windows fournissent des liens avec ce format pour une
   meilleure intégration. Il existe aussi des visualiseurs de CHM pour
   Linux. Consulter <link xlink:href="&url.xchm;">xCHM</link> ou <link
   xlink:href="&url.gnochm;">GnoCHM</link>.
  </para>
  <para>
   Il existe aussi une <link xlink:href="&url.php.echm;">version CHM
   étendue</link>, qui est mise à jour moins souvent mais qui fournit plus de
   fonctionnalités. Elle ne fonctionnera que sur <productname>Microsoft
   Windows</productname> à cause des technologies utilisées pour construire
   ces pages.
  </para>
 </sect1>
 
 <sect1 xml:id="about.notes">
  <title>À propos des notes utilisateurs</title>
  <para>
   Les notes des utilisateurs jouent un rôle très important dans le
   développement de ce manuel. En permettant aux lecteurs de contribuer par des
   exemples, des remarques et critiques, ou encore des clarifications, nous
   intégrons des aspects très importants du langage dans le manuel. Jusqu'à ce
   que les notes les plus importantes soient intégrées dans la documentation,
   elles sont disponibles sur le site lui-même, et dans certains formats
   hors ligne.
  </para>
  <note>
   <para>
    Les notes des utilisateurs ne sont pas modérées avant d'apparaître sur le
    site, et même si elles le sont, leur véracité ne peut être garantie,
    pas plus qu'il n'existe de garantie quant à l'exactitude du manuel lui-même.
   </para>
  </note>
  <note>
   <para>
    Pour des questions de portée de licence, les notes utilisateurs sont
    considérées comme faisant partie du manuel PHP, et sont donc couvertes par
    la même licence qui couvre cette documentation (Creative Commons Attribution
    à ce jour). Pour plus de détails, se reporter à la page <link
    linkend="copyright">Manual's Copyright</link>.
   </para>
  </note>
 </sect1>
 
 <sect1 xml:id="about.prototypes">
  <title>Comment lire la définition d'une fonction (prototype)</title>
  <para>
   Chaque fonction dans le manuel est documentée pour permettre une
   compréhension rapide. Savoir décoder le texte rend l'apprentissage plus
   facile. Plutôt que de dépendre d'exemples prêts à copier/coller, il est
   plus utile de savoir lire la définition d'une fonction (prototype).
   Voici comment :
  </para>
  <note>
   <title>
    Pré-requis : Connaissances de base des
    <link linkend="language.types">types</link>.
   </title>
   <para>
    Bien que PHP soit un langage sans typage fort, une connaissance
    de base des <link linkend="language.types">types</link> est essentielle,
    car ils ont quand même des sens importants.
   </para>
  </note>
  <para>
   Les définitions de fonctions indiquent quel type de données est
   <link linkend="functions.returning-values">retourné</link>. Examinons
   la fonction <function>strlen</function> comme exemple :
  </para>
  <para>
   <screen role="html">
<![CDATA[
strlen

(PHP 4, PHP 5, PHP 7)
strlen -- Retourne la taille de la chaîne

Description
strlen ( string $string ) : int

Retourne la taille de la chaîne $string.
]]>
   </screen>
  </para>
  <para>
   <table>
    <title>Explications de la définition de la fonction</title>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>Partie</entry>
       <entry>Description</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>
        strlen
       </entry>
       <entry>
        Le nom de la fonction.
       </entry>
      </row>
      <row>
       <entry>
        (PHP 4, PHP 5, PHP 7)
       </entry>
       <entry>
        strlen() est présente dans toutes les versions de PHP 4, 5 et 7.
       </entry>
      </row>
      <row>
       <entry>
        ( string $string )
       </entry>
       <entry>
        Le premier (et ici le seul) paramètre à fournir à cette fonction est
        le paramètre <parameter>string</parameter>, qui doit être du type
        &string;.
       </entry>
      </row>
      <row>
       <entry>
        int
       </entry>
       <entry>
        Type de valeur retournée par cette fonction, qui est, en l'occurrence,
        un &integer; (c.-à-d. la taille d'une chaîne est mesurée par
        un nombre).
       </entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
  <para>
   Nous pourrions réécrire ce prototype avec une version plus générique :
  </para>
  <para>
   <screen>
<![CDATA[
      nom de la fonction    ( type du paramètre   nom du paramètre ) : type de retour
]]>
   </screen>
  </para>
  <para>
   Plusieurs fonctions ont besoin de plusieurs paramètres,
   comme <function>in_array</function>.
   Son prototype est le suivant :
  </para>
  <para>
   <screen>
<![CDATA[
      in_array ( mixed $needle, array $haystack , bool $strict = false ) : bool
]]>
   </screen>
  </para>
  <para>
   Qu'est-ce que cela signifie ? <function>in_array</function> retourne
   un <link linkend="language.types.boolean">booléen</link> &true; en
   cas de réussite (le paramètre
   <parameter>needle</parameter> a été trouvé dans le tableau
   <parameter>haystack</parameter>)&return.falseforfailure;
   (le paramètre <parameter>needle</parameter> n'a pas été trouvé
   dans le tableau <parameter>haystack</parameter>). Le premier
   paramètre s'appelle <parameter>needle</parameter> et il peut être
   de différents <link linkend="language.types">types</link> : il porte
   donc la mention <emphasis>mixed</emphasis>.
   Le paramètre <parameter>needle</parameter> (ce que nous recherchons)
   peut être une valeur scalaire ( &string;, &integer;,
   ou <link linkend="language.types.float">float</link>), ou encore un <link linkend="language.types.array">array</link>.
   <parameter>haystack</parameter> (le <link linkend="language.types.array">array</link>,
   dans lequel nous recherchons) est
   le second paramètre. Le troisième paramètre, <emphasis>optionnel</emphasis>,
   <parameter>strict</parameter>,
   est optionnel. Tous les paramètres optionnels ont une valeur par défaut ;
   si la valeur par défaut est inconnue, elle est affichée en tant que <literal>?</literal>.
   Le manuel indique que le paramètre <parameter>strict</parameter> vaut par
   défaut &false;. Se reporter au manuel de chaque fonction pour savoir
   comment elle fonctionne.
  </para>
  <para> 
   De plus, le signe &amp; (é commercial) ajouté au début du paramètre d'une
   fonction permet de passer ce paramètre par
   <link linkend="language.references.pass">référence</link>, comme ceci : 
  </para>
  <para>
   <screen> 
<![CDATA[
       preg_match ( string $pattern , string $subject , array &$matches = null,
       int $flags = 0 , int $offset = 0 ) : int|false
]]>
     </screen>
  </para>
  <para>
   Dans cet exemple, nous pouvons voir que le troisième paramètre optionnel
   <parameter>&amp;$matches</parameter> va être passé par référence.
  </para>
  <para>
   Il y a aussi des fonctions avec des informations plus complexes
   concernant les versions de PHP. Prenons
   <function>html_entity_decode</function> comme exemple :
  </para>
  <para>
   <screen>
<![CDATA[
(PHP 4 >= 4.3.0, PHP 5, PHP 7)
]]>
   </screen>
  </para>
  <para>
   Cela signifie que cette fonction n'est disponible
   qu'à partir de PHP 4.3.0.
  </para>
 </sect1>
 
 <sect1 xml:id="about.phpversions">
  <title>Versions de PHP documentées dans ce manuel</title>
  <para>
   Ce manuel contient des informations sur les anciennes, actuelles et futures
   versions de PHP. Les modifications de comportement sont documentées sous
   la forme de notes, d'historiques de version, mais aussi dans les pages du manuel.
   La version documentée la plus ancienne est la version 7.0.0.
  </para>
  <para>
   Lorsque la documentation existe pour les dernières versions de développement (non publiées)
   de PHP, elle sera intitulée "disponible dans Git" ou "version de développement." Ces
   changements sont prévus, mais peuvent encore évoluer dans de rares cas.
  </para>
  <para>
   Tous les développements sont versionnés dans le dépôt Git et peuvent être récupérés comme décrit dans
   <link xlink:href="&url.php.anongit;">accès anonyme Git</link>.
  </para>
  <para>
   Et par souci de clarté, le manuel fera référence aux versions majeures, mineures et
   révisions de PHP. Par exemple PHP <literal>7.3.1</literal>, le <emphasis>7</emphasis>
   est la version majeure, <emphasis>3</emphasis> la mineure, et
   <emphasis>1</emphasis> la révision. Typiquement PHP n'ajoute de nouvelles fonctionnalités
   que dans les versions majeures ou mineures, et corrige des bugs dans les révisions. Cependant,
   cette convention n'est pas toujours vérifiée.
  </para>
  <para>
   Il est à noter aussi que le manuel concerne PHP présent et non futur, même pour les fonctionnalités
   documentées et qui ne sont pas encore disponibles. Ainsi le manuel peut perdurer dans le
   temps et ne requiert pas de mises à jour importantes à chaque sortie de PHP.
  </para>
  <para>
   À plusieurs reprises, le manuel de PHP liste les valeurs par défaut des
   directives PHP. Ces valeurs sont basées sur le comportement de PHP sans fichier de
   configuration &php.ini;, ainsi ceci peut changer des valeurs trouvées dans les fichiers
   distribués <filename>php.ini-development</filename> et <filename>php.ini-production</filename>
   . Les valeurs indiquées sont aussi celles de la dernière version de PHP, un changelog indique les
   valeurs précédemment employées. Voir <link linkend="ini.list">l'appendice sur les directives PHP
   </link> pour plus de détails sur ces valeurs et leurs évolutions.
  </para>
 </sect1>
 
 <sect1 xml:id="about.more">
  <title>Où trouver plus d'informations sur PHP ?</title>
  <para>
   Ce manuel n'a pas pour objectif de fournir des présentations sur les
   pratiques de programmation. Pour un néophyte total, ou même
   un programmeur débutant, il peut être difficile d'apprendre
   la programmation PHP avec uniquement ce manuel : il serait préférable de trouver
   des ressources plus orientées vers l'apprentissage.
  </para>
  <para>
   Il y a un bon nombre de listes de diffusion actives, traitant de tous les
   aspects du langage et de la programmation PHP. En cas de blocage,
   il est possible de trouver de l'aide auprès de ces listes.
   Il existe un recensement des listes de diffusion sur
   <link xlink:href="&url.php.support;">la page de support de php.net</link>.
  </para>
 </sect1>
 
 <sect1 xml:id="about.howtohelp">
  <title>Comment aider à l'amélioration de la documentation ?</title>
  <para>
   Il y a plusieurs façons de participer à l'amélioration de la documentation.
  </para>
  <para>
   Si une erreur est trouvée, dans n'importe quelle traduction de la
   documentation, veuillez rapporter le bogue sur le gestionnaire d'issue du
   dépôt de langue respectif à <link xlink:href="&url.php.git;">&url.php.git;</link>;
   par exemple, les erreurs dans le manuel anglais doivent être rapportées à
   <link xlink:href="&url.php.git;doc-en/issues">&url.php.git;doc-en/issues</link>.
   Toutes les issues en rapport avec la documentation, ainsi que ses formats,
   devraient être soumis comme des bogues.
  </para>
  <note>
   <para>
    Il ne faut pas abuser du gestionnaire d'issues pour envoyer des demandes d'aide. Il est préférable d'utiliser
    une des options proposées par le <link xlink:href="&url.php.support;">support</link>.
   </para>
  </note>
  <para>
   En contribuant aux notes, il est possible de fournir de nouveaux exemples,
   mettre en lumière des effets de bords et apporter des clarifications pour
   les autres lecteurs. Mais il ne faut pas utiliser le système d'annotation
   comme un système de soumission de bogues. Il est possible d'en savoir plus sur les
   annotations dans la section
   <link linkend="about.notes">'À propos des notes utilisateurs'</link>
  </para>
  <para>
   Il est aussi possible de soumettre des pull requests au
   <link xlink:href="&url.php.git.mirror;doc-en">miroir Github du repository de la documentation</link>.
  </para>
  <para>
   Le manuel PHP est traduit en de nombreux langages. La connaissance
   de l'anglais ainsi que d'une autre langue permet d'aider
   la documentation de PHP en travaillant avec une équipe de traduction.
   Pour plus d'informations sur la manière de démarrer une nouvelle traduction
   ou de contribuer à une version déjà traduite, il convient de lire
   <link xlink:href="&url.php.dochowto;">&url.php.dochowto;</link>.
  </para>
  <para>
   Le projet de documentation de PHP a un canal IRC où il est possible de venir
   et parler avec les auteurs du manuel ou trouver un certain aspect du manuel
   avec lequel il serait possible d'aider. Les coordonnées :
   <literal>#php.doc</literal> sur <literal>irc.efnet.org</literal>.
  </para>
 </sect1>
 
 <sect1 xml:id="about.generate">
  <title>Comment sont générées les documentations</title>
  <para>
   Ce manuel est écrit en <acronym>XML</acronym>, en utilisant
   la <link xlink:href="&url.docbook.xml;">DTD de DocBook XML</link>, et
   <link xlink:href="&url.phd;"><acronym>PhD</acronym></link> (Le moteur
   [PH]P d'affichage [D]ocBook) pour la maintenance et le formatage.
  </para>
  <para>
   Grâce au format <acronym>XML</acronym> comme source, nous avons
   la possibilité de générer de nombreux formats tout en ayant une
   seule source pour tous les formats. L'outil utilisé pour formater le manuel
   en ligne est <link xlink:href="&url.phd;">PhD</link>.
   Nous utilisons <link xlink:href="&url.winhelp;">Microsoft HTML Help
   Workshop</link> pour générer le format <productname>Windows HTML Help</productname> du manuel, et,
   bien sûr, PHP lui-même pour effectuer des conversions et du formatage.
  </para>
  <para>
   Le manuel PHP est généré en de nombreux langages et formats, consulter
   <link xlink:href="&url.php.docs;">&url.php.docs;</link> pour plus d'informations.
   Le code source <acronym>XML</acronym> peut être téléchargé depuis git et
   visualisé sur <link xlink:href="&url.php.git.mirror;doc-en">&url.php.git.mirror;doc-en</link>.
  </para>
 </sect1>
 
 <sect1 xml:id="about.translations">
  <title>Traductions</title>
  <para>
   Le manuel PHP est disponible non seulement en anglais, mais aussi dans
   différentes langues. Le texte du manuel est écrit d'abord en anglais, puis
   des équipes à travers le monde assurent la traduction du manuel dans leur
   langue natale. Si la traduction d'une section n'est pas encore disponible,
   le système de création de la documentation présentera alors la version
   anglaise.
  </para>
  <para>
   Les contributeurs aux documentations partent des codes sources
   <acronym>XML</acronym> disponibles à partir de
   <link xlink:href="&url.php.git.mirror;doc-en">&url.php.git.mirror;doc-en</link>.
   puis traduisent dans leur langue. Ils <emphasis>n'utilisent pas</emphasis>
   les versions générées (comme le <acronym>HTML</acronym> ou le texte plein)
   car c'est le système d'édition qui se charge de faire les
   conversions du format <acronym>XML</acronym> vers un format lisible.
  </para>
  <note>
   <para>
    Pour aider à la traduction de la documentation, il convient d'entrer en
    contact avec l'équipe de documentation en s'inscrivant à la liste de
    diffusion : <link
    xlink:href="mailto:&email.php.doc.subscribe;">&email.php.doc.subscribe;</link>.
    L'adresse de la liste de diffusion est <literal>&email.php.doc;</literal>.
    Indiquer dans le message l'intérêt pour la traduction de la
    documentation dans une nouvelle langue, et quelqu'un viendra aider à
    démarrer une nouvelle traduction, ou rejoindre l'équipe qui a pris en
    charge cette traduction.
   </para>
  </note>
  <para>
   Actuellement, le manuel est disponible, partiellement ou en totalité, dans
   plus de 10 langues.
  </para>
  <para>
   Ils peuvent tous être téléchargés ici :
   <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
-->