/
about.xml
executable file
·463 lines (450 loc) · 18.5 KB
/
about.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: fc7fe7faecea431a37e1f809b2ba3056e4ef2e1b 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> que vous pouvez utiliser
pour accéder rapidement à une partie du manuel. Un inconvénient
évident est que vous devez ê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 de votre OS et de vos goûts personnels.
Pour savoir comment le manuel est généré, lisez 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, vous aurez donc besoin
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. Visitez <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 quand à 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, lisez 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 rendra votre 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 vous 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; (i.e. 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 <type>array</type>.
<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;. Reportez-vous au manuel de chaque fonction pour savoir
comment elle fonctionne.
</para>
<para>
De plus, le signe & (é 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>&$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
que depuis 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épot 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>
Notez 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. Voyez <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. Si vous êtes un néophyte total, ou même
un programmeur débutant, vous pouvez trouver difficile d'apprendre
la programmation PHP avec uniquement ce manuel : il serait mieux 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. Si vous êtes bloqué par un
problème, vous pourrez sûrement 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="https://github.com/php/?q=doc">https://github.com/php</link>;
par exemple, les erreurs dans le manuel anglais doivent être rapporté à
<link xlink:href="https://github.com/php/doc-en/issues">https://github.com/php/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>
N'abusez pas du gestionnaire d'issues pour envoyer des demandes d'aide. Utilisez
plutôt une des options proposées par le <link xlink:href="&url.php.support;">support</link>.
</para>
</note>
<para>
En contribuant aux notes, vous pouvez fournir de nouveaux exemples,
mettre en lumière des effets de bords et apporter des clarifications pour
les autres lecteurs. Mais ne prenez pas le système d'annotation pour
un système de soumission de bogues. Vous pouvez 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 peut vous permettre d'aider
la documentation de PHP en travaillant avec une équipe de traduction.
Pour plus d'informations sur le commencement d'une traduction, ou
sur l'aide d'une version déjà traduite, commencez par lire
<link xlink:href="&url.php.dochowto;">&url.php.dochowto;</link>.
</para>
<para>
Le projet de documentation de PHP a un canal IRC où vous pouvez venir
et parler avec les auteurs du manuel ou trouver un certain aspect du manuel
avec lequel vous pourriez 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, lisez
<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>
La 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>
Si vous voulez aider à la traduction de la documentation, entrez en
contact avec l'équipe de documentation en vous 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>.
Indiquez dans le message que vous êtes intéressé par la traduction de la
documentation dans une nouvelle langue, et quelqu'un viendra vous 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
-->