From e4917ba65438b1928b3e94d4b6330238ed54c29c Mon Sep 17 00:00:00 2001
From: Pierre Ambroise <pierre27.ambroise@gmail.com>
Date: Mon, 1 Dec 2025 14:02:00 +0100
Subject: [PATCH] Sync dir function with EN

---
 reference/dir/functions/closedir.xml  | 105 ++++++++++++--------
 reference/dir/functions/opendir.xml   | 133 ++++++++++++++------------
 reference/dir/functions/readdir.xml   | 129 ++++++++-----------------
 reference/dir/functions/rewinddir.xml |  71 +++++++++-----
 4 files changed, 227 insertions(+), 211 deletions(-)

diff --git a/reference/dir/functions/closedir.xml b/reference/dir/functions/closedir.xml
index 9856cde3d7..95f750a99d 100644
--- a/reference/dir/functions/closedir.xml
+++ b/reference/dir/functions/closedir.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: b0b19b66183b28cebc1ffbcf1e2b8763f9d9c7b3 Maintainer: yannick Status: ready -->
+<!-- EN-Revision: 5c7e9e1351240b5f9e0858cdeba8f754a366d1b7 Maintainer: yannick Status: ready -->
 <!-- Reviewed: no -->
 <refentry xml:id="function.closedir" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
@@ -13,60 +13,83 @@
    <type>void</type><methodname>closedir</methodname>
    <methodparam choice="opt"><type class="union"><type>resource</type><type>null</type></type><parameter>dir_handle</parameter><initializer>&null;</initializer></methodparam>
   </methodsynopsis>
-  <para>
+  <simpara>
    <function>closedir</function> ferme le pointeur de dossier
-   <parameter>dir_handle</parameter>. Le dossier devait avoir
-   été ouvert auparavant avec <function>opendir</function>.
-  </para>
+   <parameter>dir_handle</parameter>.
+  </simpara>
  </refsect1>
 
  <refsect1 role="parameters">
   &reftitle.parameters;
-  <para>
-   <variablelist>
-    <varlistentry>
-     <term><parameter>dir_handle</parameter></term>
-     <listitem>
-      <para>
-       La <type>ressource</type> de dossier ouverte précédemment avec
-       <function>opendir</function>.
-      </para>
-     </listitem>
-    </varlistentry>
-   </variablelist>
-  </para>
+  <variablelist>
+   <varlistentry>
+    <term><parameter>dir_handle</parameter></term>
+    <listitem>
+     <simpara>
+      Le gestionnaire de dossier <type>resource</type> précédemment ouvert
+      avec <function>opendir</function>.
+      Si <parameter>dir_handle</parameter> est &null; le dernier gestionnaire
+      ouvert avec <function>opendir</function> sera utilisé.
+     </simpara>
+    </listitem>
+   </varlistentry>
+  </variablelist>
  </refsect1>
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
-  <para>
+  <simpara>
    &return.void;
-  </para>
+  </simpara>
+ </refsect1>
+
+ <refsect1 role="changelog">
+  &reftitle.changelog;
+  <informaltable>
+   <tgroup cols="2">
+    <thead>
+     <row>
+      <entry>&Version;</entry>
+      <entry>&Description;</entry>
+     </row>
+    </thead>
+    <tbody>
+     <row>
+      <entry>8.5.0</entry>
+      <entry>
+       Utiliser &null; pour <parameter>dir_handle</parameter> est maintenant obsolète.
+       Au lieu de cela, le dernier gestionnaire de dossier ouvert doit être fourni explicitement.
+      </entry>
+     </row>
+     <row>
+      <entry>8.0.0</entry>
+      <entry>
+       <parameter>dir_handle</parameter> est désormais nullable.
+      </entry>
+     </row>
+    </tbody>
+   </tgroup>
+  </informaltable>
  </refsect1>
 
  <refsect1 role="examples">
   &reftitle.examples;
-  <para>
-   <example>
-    <title>Exemple avec <function>closedir</function></title>
-    <programlisting role="php">
-<![CDATA[
-<?php
-$dir = "/etc/php5/";
-
-// Ouverture d'un dossier connu, lecture du dossier et assignation à
-// une variable, ensuite fermeture du dossier
-if (is_dir($dir)) {
-    if ($dh = opendir($dir)) {
-        $directory = readdir($dh);
-        closedir($dh);
-    }
-}
-?>
-]]>
-    </programlisting>
-   </example>
-  </para>
+  <simpara>
+   Pour un exemple complet référez-vous à la documentation de
+   <function>opendir</function>.
+  </simpara>
+ </refsect1>
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <simplelist>
+   <member><function>opendir</function></member>
+   <member><function>readdir</function></member>
+   <member><function>rewinddir</function></member>
+   <member><function>dir</function></member>
+   <member><function>is_dir</function></member>
+   <member><function>glob</function></member>
+   <member><function>scandir</function></member>
+  </simplelist>
  </refsect1>
 </refentry>
 <!-- Keep this comment at the end of the file
diff --git a/reference/dir/functions/opendir.xml b/reference/dir/functions/opendir.xml
index 88e59a4952..427b3107ce 100644
--- a/reference/dir/functions/opendir.xml
+++ b/reference/dir/functions/opendir.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: b0b19b66183b28cebc1ffbcf1e2b8763f9d9c7b3 Maintainer: yannick Status: ready -->
+<!-- EN-Revision: 5c7e9e1351240b5f9e0858cdeba8f754a366d1b7 Maintainer: yannick Status: ready -->
 <!-- Reviewed: no -->
 <refentry xml:id="function.opendir" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
@@ -16,55 +16,54 @@
    <methodparam><type>string</type><parameter>directory</parameter></methodparam>
    <methodparam choice="opt"><type class="union"><type>resource</type><type>null</type></type><parameter>context</parameter><initializer>&null;</initializer></methodparam>
   </methodsynopsis>
-  <para>
+  <simpara>
    <function>opendir</function> retourne un pointeur sur un dossier
    qui pour être utilisé avec les fonctions
    <function>closedir</function>, <function>readdir</function>
    et <function>rewinddir</function>.
-  </para>
+  </simpara>
  </refsect1>
 
  <refsect1 role="parameters">
   &reftitle.parameters;
-  <para>
-   <variablelist>
-    <varlistentry>
-     <term><parameter>directory</parameter></term>
-     <listitem>
-      <para>
-       Le chemin du répertoire à ouvrir
-      </para>
-     </listitem>
-    </varlistentry>
-    <varlistentry>
-     <term><parameter>context</parameter></term>
-     <listitem>
-      <para>
-       Pour la description du paramètre <parameter>context</parameter>,
-       référez-vous à la <link linkend="ref.stream">section des flux</link> du manuel.
-      </para> 
-     </listitem>
-    </varlistentry>
-   </variablelist>
-  </para>
+  <variablelist>
+   <varlistentry>
+    <term><parameter>directory</parameter></term>
+    <listitem>
+     <simpara>
+      Le chemin du dossier à ouvrir.
+     </simpara>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term><parameter>context</parameter></term>
+    <listitem>
+     <simpara>
+      Pour une description du paramètre <parameter>context</parameter>,
+      référez-vous à la section <link linkend="ref.stream">les flux</link>
+      du manuel.
+     </simpara>
+    </listitem>
+   </varlistentry>
+  </variablelist>
  </refsect1>
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
-  <para>
-   Retourne la &resource; de dossier en cas de succès,
+  <simpara>
+   Renvoie un gestionnaire de dossier en cas de succès
    &return.falseforfailure;
-  </para>
+  </simpara>
  </refsect1>
 
  <refsect1 role="errors">
   &reftitle.errors;
   &fs.emits.warning.on.failure;
-  <para>
+  <simpara>
    Ceci peut se produire si <parameter>directory</parameter> n'est pas un dossier
    valide, le dossier ne peut être ouvert pour des raisons de permissions,
    ou à cause d'erreurs liées au système de fichiers.
-  </para>
+  </simpara>
  </refsect1>
 
  <refsect1 role="changelog">
@@ -81,7 +80,7 @@
      <row>
       <entry>8.0.0</entry>
       <entry>
-       <parameter>context</parameter> is now nullable.
+       <parameter>context</parameter> est désormais nullable.
       </entry>
      </row>
     </tbody>
@@ -91,49 +90,65 @@
 
  <refsect1 role="examples">
   &reftitle.examples;
-  <para>
-   <example>
-    <title>Exemple avec <function>opendir</function></title>
-    <programlisting role="php">
+  <example>
+   <title>
+    Liste toutes les entrées d'un dossier, en ignorant les entrées spéciales
+    <literal>.</literal> et <literal>..</literal>
+   </title>
+   <simpara>
+    Du fait que les entrées de dossier et de fichier peuvent être des chaînes et évaluer comme "faux"
+    (par exemple un dossier nommé <literal>"0"</literal>), et que
+    <function>readdir</function> retourne &false; lorsqu'il a lu toutes les
+    entrées d'un dossier, il faut utiliser 
+    <link linkend="language.operators.comparison">l'opérateur de comparaison</link>
+    <literal>===</literal> pour distingué proprement une entrée de dossier
+    dont le nom est "faux" d'une entrée de dossier qui a été lue
+    et qui est &false;.
+   </simpara>
+   <programlisting role="php">
 <![CDATA[
 <?php
-$dir = "/tmp/php5";
+if ($handle = opendir('/path/to/files')) {
+    echo "Entries:\n";
 
-// Ouvre un dossier bien connu, et liste tous les fichiers
-if (is_dir($dir)) {
-    if ($dh = opendir($dir)) {
-        while (($file = readdir($dh)) !== false) {
-            echo "fichier : $file : type : " . filetype($dir . $file) . "\n";
+    /* Correctly handling directory entries that may be considered falsy */
+    while (false !== ($entry = readdir($handle))) {
+        if ($entry === '.' || $entry === '..') {
+            continue;
         }
-        closedir($dh);
+        echo "$entry\n";
     }
+
+    closedir($handle);
 }
 ?>
 ]]>
-    </programlisting>
-    &example.outputs.similar;
-    <screen>
+   </programlisting>
+   &example.outputs.similar;
+   <screen>
 <![CDATA[
-fichier : . : type : dir
-fichier : .. : type : dir
-fichier : apache : type : dir
-fichier : cgi : type : dir
-fichier : cli : type : dir
+Entries:
+base
+en
+fr
+output.md
+test.php
 ]]>
-    </screen>
-   </example>
-  </para>
+   </screen>
+  </example>
  </refsect1>
 
  <refsect1 role="seealso">
   &reftitle.seealso;
-  <para>
-   <simplelist>
-    <member><function>is_dir</function></member>
-    <member><function>readdir</function></member>
-    <member><function>dir</function></member>
-   </simplelist>
-  </para>
+  <simplelist>
+   <member><function>readdir</function></member>
+   <member><function>rewinddir</function></member>
+   <member><function>closedir</function></member>
+   <member><function>dir</function></member>
+   <member><function>is_dir</function></member>
+   <member><function>glob</function></member>
+   <member><function>scandir</function></member>
+  </simplelist>
  </refsect1>
 </refentry>
 <!-- Keep this comment at the end of the file
diff --git a/reference/dir/functions/readdir.xml b/reference/dir/functions/readdir.xml
index 1585e8ac5f..a5b5fb14bb 100644
--- a/reference/dir/functions/readdir.xml
+++ b/reference/dir/functions/readdir.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: b0b19b66183b28cebc1ffbcf1e2b8763f9d9c7b3 Maintainer: yannick Status: ready -->
+<!-- EN-Revision: 5c7e9e1351240b5f9e0858cdeba8f754a366d1b7 Maintainer: yannick Status: ready -->
 <!-- Reviewed: no -->
 <refentry xml:id="function.readdir" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
@@ -13,38 +13,35 @@
    <type class="union"><type>string</type><type>false</type></type><methodname>readdir</methodname>
    <methodparam choice="opt"><type class="union"><type>resource</type><type>null</type></type><parameter>dir_handle</parameter><initializer>&null;</initializer></methodparam>
   </methodsynopsis>
-  <para>
-   <function>readdir</function> retourne le nom de la prochaine entrée
-   du dossier identifié par <parameter>dir_handle</parameter>.
-   Les entrées sont retournées dans l'ordre dans lequel elles sont enregistrées
+  <simpara>
+   Renvoie le nom de la prochaine entrée dans le dossier.
+   Les entrées sont renvoyées dans l'ordre dans lequel elles sont stockées
    dans le système de fichiers.
-  </para>
+  </simpara>
  </refsect1>
 
  <refsect1 role="parameters">
   &reftitle.parameters;
-  <para>
-   <variablelist>
-    <varlistentry>
-     <term><parameter>dir_handle</parameter></term>
-     <listitem>
-      <para>
-       La <type>ressource</type> de dossier ouverte précédemment avec
-       <function>opendir</function>. Si la ressource de dossier
-       n'est pas spécifiée, la dernière ressource ouverte avec la fonction
-       <function>opendir</function> sera utilisée.
-      </para>
-     </listitem>
-    </varlistentry>
-   </variablelist>
-  </para>
+  <variablelist>
+   <varlistentry>
+    <term><parameter>dir_handle</parameter></term>
+    <listitem>
+     <simpara>
+      Un gestionnaire de dossier <type>resource</type> précédemment ouvert
+      avec <function>opendir</function>.
+      Si <parameter>dir_handle</parameter> est &null; le dernier gestionnaire
+      ouvert avec <function>opendir</function> sera utilisé.
+     </simpara>
+    </listitem>
+   </varlistentry>
+  </variablelist>
  </refsect1>
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
-  <para>
+  <simpara>
    Retourne le nom de l'entrée en cas de réussite,&return.falseforfailure;.
-  </para>
+  </simpara>
   &return.falseproblem;
  </refsect1>
 
@@ -59,6 +56,13 @@
      </row>
     </thead>
     <tbody>
+     <row>
+      <entry>8.5.0</entry>
+      <entry>
+       Utiliser &null; pour <parameter>dir_handle</parameter> est maintenant dépréciée.
+       Au lieu de cela, le dernier gestionnaire de dossier ouvert doit être fourni explicitement.
+      </entry>
+     </row>
      <row>
       <entry>8.0.0</entry>
       <entry>
@@ -72,76 +76,23 @@
 
  <refsect1 role="examples">
   &reftitle.examples;
-  <para>
-   <example>
-    <title>Liste de toutes les entrées d'un dossier</title>
-    <para>
-     Notez la façon dont la valeur de retour de <function>dir</function>
-     est vérifiée dans l'exemple suivant. Nous testons si la valeur est
-     identique (égale et de même type que -- voyez <link
-     linkend="language.operators.comparison">opérateurs de comparaison</link>
-     pour plus de détails) &false; sinon, toute entrée dans le nom serait évalué
-     à &false; causera l'arrêt de la boucle (exemple, un répertoire nommé 0).
-    </para>
-    <programlisting role="php">
-<![CDATA[
-<?php
-
-if ($handle = opendir('/chemin/vers/fichiers')) {
-    echo "Gestionnaire du dossier : $handle\n";
-    echo "Entrées :\n";
-
-    /* Ceci est la façon correcte de traverser un dossier. */
-    while (false !== ($entry = readdir($handle))) {
-        echo "$entry\n";
-    }
-
-    /* Ceci est la MAUVAISE façon de traverser un dossier. */
-    while ($entry = readdir($handle)) {
-        echo "$entry\n";
-    }
-
-    closedir($handle);
-}
-?>
-]]>
-    </programlisting>
-   </example>
-  </para>
-  <para>
-   <example>
-    <title>
-     Liste toutes les entrées du dossier courant et enlève les
-     <literal>.</literal> et <literal>..</literal>
-    </title>
-    <programlisting role="php">
-<![CDATA[
-<?php
-if ($handle = opendir('.')) {
-    while (false !== ($entry = readdir($handle))) {
-        if ($entry != "." && $entry != "..") {
-            echo "$entry\n";
-        }
-    }
-    closedir($handle);
-}
-?>
-]]>
-    </programlisting>
-   </example>
-  </para>
+  <simpara>
+   Pour une exemple complet, référez-vous à la documentation de
+   la fonction <function>opendir</function>.
+  </simpara>
  </refsect1>
 
  <refsect1 role="seealso">
   &reftitle.seealso;
-  <para>
-   <simplelist>
-    <member><function>is_dir</function></member>
-    <member><function>glob</function></member>
-    <member><function>opendir</function></member>
-    <member><function>scandir</function></member>
-   </simplelist>
-  </para>
+  <simplelist>
+   <member><function>opendir</function></member>
+   <member><function>rewinddir</function></member>
+   <member><function>closedir</function></member>
+   <member><function>dir</function></member>
+   <member><function>is_dir</function></member>
+   <member><function>glob</function></member>
+   <member><function>scandir</function></member>
+  </simplelist>
  </refsect1>
 </refentry>
 <!-- Keep this comment at the end of the file
diff --git a/reference/dir/functions/rewinddir.xml b/reference/dir/functions/rewinddir.xml
index e714451138..b917d3e516 100644
--- a/reference/dir/functions/rewinddir.xml
+++ b/reference/dir/functions/rewinddir.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: b0b19b66183b28cebc1ffbcf1e2b8763f9d9c7b3 Maintainer: yannick Status: ready -->
+<!-- EN-Revision: 5c7e9e1351240b5f9e0858cdeba8f754a366d1b7 Maintainer: yannick Status: ready -->
 <!-- Reviewed: no -->
 <refentry xml:id="function.rewinddir" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
@@ -13,35 +13,35 @@
    <type>void</type><methodname>rewinddir</methodname>
    <methodparam choice="opt"><type class="union"><type>resource</type><type>null</type></type><parameter>dir_handle</parameter><initializer>&null;</initializer></methodparam>
   </methodsynopsis>
-  <para>
-   <function>rewinddir</function> retourne à la première
-   entrée du dossier identifiée par <parameter>dir_handle</parameter>.
-  </para>
+  <simpara>
+   Réinitialise le flux de dossier indiqué par <parameter>dir_handle</parameter>
+   au début du dossier.
+   Resets the directory stream indicated by <parameter>dir_handle</parameter>
+   to the beginning of the directory.
+  </simpara>
  </refsect1>
 
  <refsect1 role="parameters">
   &reftitle.parameters;
-  <para>
-   <variablelist>
-    <varlistentry>
-     <term><parameter>dir_handle</parameter></term>
-     <listitem>
-      <para>
-       La &resource; de dossier ouverte précédemment avec
-       <function>opendir</function>. Si la ressource de dossier n'est pas fournie,
-       la dernière ressource ouverte avec la fonction
-       <function>opendir</function> sera utilisée.
-      </para>
-     </listitem>
-    </varlistentry>
-   </variablelist>
-  </para>
+  <variablelist>
+   <varlistentry>
+    <term><parameter>dir_handle</parameter></term>
+    <listitem>
+     <simpara>
+      Un gestionnaire de dossier <type>resource</type> précédemment ouvert
+      avec <function>opendir</function>.
+      Si <parameter>dir_handle</parameter> est &null; le dernier gestionnaire
+      ouvert avec <function>opendir</function> sera utilisé.
+     </simpara>
+    </listitem>
+   </varlistentry>
+  </variablelist>
  </refsect1>
   <refsect1 role="returnvalues">
   &reftitle.returnvalues;
-  <para>
+  <simpara>
    &return.void;
-  </para>
+  </simpara>
  </refsect1>
 
  <refsect1 role="changelog">
@@ -55,6 +55,13 @@
      </row>
     </thead>
     <tbody>
+     <row>
+      <entry>8.5.0</entry>
+      <entry>
+       Utiliser &null; pour <parameter>dir_handle</parameter> est maintenant dépréciée.
+       A la place, le dernier gestionnaire de dossier ouvert doit être fourni explicitement.
+      </entry>
+     </row>
      <row>
       <entry>8.0.0</entry>
       <entry>
@@ -66,6 +73,26 @@
   </informaltable>
  </refsect1>
 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <simpara>
+   Pour un exemple complet, référez-vous à la documentation de
+   <function>opendir</function>.
+  </simpara>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <simplelist>
+   <member><function>opendir</function></member>
+   <member><function>readdir</function></member>
+   <member><function>closedir</function></member>
+   <member><function>dir</function></member>
+   <member><function>is_dir</function></member>
+   <member><function>glob</function></member>
+   <member><function>scandir</function></member>
+  </simplelist>
+ </refsect1>
 </refentry>
 <!-- Keep this comment at the end of the file
 Local variables: