[PHP-DOC] cvs: phpdoc /en/reference/dir/functions chdir.xml chroot.xml class.dir.xml closedir.xml getcwd.xml opendir.xml readdir.xml rewinddir.xml scandir.xml

[Philip Olson]

philip          Mon Apr 11 19:28:22 2005 EDT

  Modified files:              
    /phpdoc/en/reference/dir/functions  chdir.xml chroot.xml 
                                        class.dir.xml closedir.xml 
                                        getcwd.xml opendir.xml 
                                        readdir.xml rewinddir.xml 
                                        scandir.xml 
  Log:
  Moved to new doc style
  
  
http://cvs.php.net/diff.php/phpdoc/en/reference/dir/functions/chdir.xml?r1=1.12&r2=1.13&ty=u
Index: phpdoc/en/reference/dir/functions/chdir.xml
diff -u phpdoc/en/reference/dir/functions/chdir.xml:1.12 
phpdoc/en/reference/dir/functions/chdir.xml:1.13
--- phpdoc/en/reference/dir/functions/chdir.xml:1.12    Mon Apr 11 18:04:40 2005
+++ phpdoc/en/reference/dir/functions/chdir.xml Mon Apr 11 19:28:21 2005
@@ -1,21 +1,49 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.12 $ -->
+<!-- $Revision: 1.13 $ -->
 <!-- splitted from ./en/functions/dir.xml, last change in rev 1.2 -->
 <refentry id="function.chdir">
  <refnamediv>
   <refname>chdir</refname>
   <refpurpose>Change directory</refpurpose>
  </refnamediv>
- <refsect1>
+
+ <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
    <type>bool</type><methodname>chdir</methodname>
    
<methodparam><type>string</type><parameter>directory</parameter></methodparam>
   </methodsynopsis>
   <para>
-   Changes PHP's current directory to
-   <parameter>directory</parameter>. &return.success;
+   Changes PHP's current directory to 
+   <parameter>directory</parameter>.
   </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>directory</parameter></term>
+     <listitem>
+      <para>
+       The new current directory
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   &return.success;
+  </para> 
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
   <para>
    <example>
     <title><function>chdir</function> example</title>
@@ -34,7 +62,7 @@
 ?>
 ]]>
     </programlisting>
-    &example.outputs;
+    &example.outputs.similar;
     <screen>
 <![CDATA[
 /home/vincent
@@ -43,9 +71,19 @@
     </screen>
    </example>
   </para>
+ </refsect1>
+
+ <refsect1 role="notes">
+  &reftitle.notes;
   &note.sm.uidcheck.dir;
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
   <para>
-   See also <function>getcwd</function>.
+   <simplelist>
+    <member><function>getcwd</function></member>
+   </simplelist>
   </para>
  </refsect1>
 </refentry>
http://cvs.php.net/diff.php/phpdoc/en/reference/dir/functions/chroot.xml?r1=1.9&r2=1.10&ty=u
Index: phpdoc/en/reference/dir/functions/chroot.xml
diff -u phpdoc/en/reference/dir/functions/chroot.xml:1.9 
phpdoc/en/reference/dir/functions/chroot.xml:1.10
--- phpdoc/en/reference/dir/functions/chroot.xml:1.9    Mon Apr 11 18:04:40 2005
+++ phpdoc/en/reference/dir/functions/chroot.xml        Mon Apr 11 19:28:21 2005
@@ -1,12 +1,13 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.9 $ -->
+<!-- $Revision: 1.10 $ -->
 <!-- splitted from ./en/functions/dir.xml, last change in rev 1.11 -->
 <refentry id="function.chroot">
  <refnamediv>
   <refname>chroot</refname>
   <refpurpose>Change the root directory</refpurpose>
  </refnamediv>
- <refsect1>
+
+ <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
    <type>bool</type><methodname>chroot</methodname>
@@ -14,13 +15,40 @@
   </methodsynopsis>
   <para>
    Changes the root directory of the current process to
-   <parameter>directory</parameter>. &return.success;
+   <parameter>directory</parameter>.
   </para>
   <para>
    This function is only available if your system supports it and
-   you're using the CLI, CGI or Embed SAPI.
+   you're using the CLI, CGI or Embed SAPI. Also, this function
+   requires root priviledges.
+  </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>directory</parameter></term>
+     <listitem>
+      <para>
+       The new directory
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
   </para>
-  <note><simpara><function>chroot</function> requires root 
privileges.</simpara></note>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   &return.success;
+  </para> 
+ </refsect1>
+
+ <refsect1 role="notes">
+  &reftitle.notes;
   &note.no-windows;
  </refsect1>
 </refentry>
http://cvs.php.net/diff.php/phpdoc/en/reference/dir/functions/class.dir.xml?r1=1.9&r2=1.10&ty=u
Index: phpdoc/en/reference/dir/functions/class.dir.xml
diff -u phpdoc/en/reference/dir/functions/class.dir.xml:1.9 
phpdoc/en/reference/dir/functions/class.dir.xml:1.10
--- phpdoc/en/reference/dir/functions/class.dir.xml:1.9 Mon Apr 11 18:04:40 2005
+++ phpdoc/en/reference/dir/functions/class.dir.xml     Mon Apr 11 19:28:21 2005
@@ -1,12 +1,13 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.9 $ -->
+<!-- $Revision: 1.10 $ -->
 <!-- splitted from ./en/functions/dir.xml, last change in rev 1.2 -->
 <refentry id="class.dir">
  <refnamediv>
   <refname>dir</refname>
   <refpurpose>Directory class</refpurpose>
  </refnamediv>
- <refsect1>
+
+ <refsect1 role="description">
   &reftitle.description;
   <classsynopsis>
    <ooclass><classname>dir</classname></ooclass>
@@ -34,16 +35,22 @@
    the directory that was opened.  Three methods are available:
    read, rewind and close.
   </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
   <para>
-   Please note the fashion in which <function>dir</function>'s
-   return value is checked in the example below. We are explicitly
-   testing whether the return value is identical to (equal to and of
-   the same type as--see <link linkend="language.operators.comparison">
-   Comparison Operators</link> for more information) &false; since
-   otherwise, any directory entry whose name evaluates to &false; will
-   stop the loop.
    <example>
     <title><function>dir</function> example</title>
+    <para>
+     Please note the fashion in which <function>dir</function>'s
+     return value is checked in the example below. We are explicitly
+     testing whether the return value is identical to (equal to and of
+     the same type as--see <link linkend="language.operators.comparison">
+     Comparison Operators</link> for more information) &false; since
+     otherwise, any directory entry whose name evaluates to &false; will
+     stop the loop.
+    </para>
     <programlisting role="php">
 <![CDATA[
 <?php
@@ -71,6 +78,10 @@
     </screen>
    </example>
   </para>
+ </refsect1>
+
+ <refsect1 role="notes">
+  &reftitle.notes;
   <note>
    <para>
     The order in which directory entries are returned by the read method is
http://cvs.php.net/diff.php/phpdoc/en/reference/dir/functions/closedir.xml?r1=1.6&r2=1.7&ty=u
Index: phpdoc/en/reference/dir/functions/closedir.xml
diff -u phpdoc/en/reference/dir/functions/closedir.xml:1.6 
phpdoc/en/reference/dir/functions/closedir.xml:1.7
--- phpdoc/en/reference/dir/functions/closedir.xml:1.6  Mon Apr 11 18:04:40 2005
+++ phpdoc/en/reference/dir/functions/closedir.xml      Mon Apr 11 19:28:21 2005
@@ -1,22 +1,44 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.6 $ -->
+<!-- $Revision: 1.7 $ -->
 <!-- splitted from ./en/functions/dir.xml, last change in rev 1.2 -->
 <refentry id="function.closedir">
  <refnamediv>
   <refname>closedir</refname>
   <refpurpose>Close directory handle</refpurpose>
  </refnamediv>
- <refsect1>
+
+ <refsect1 role="description">
   &reftitle.description;
-   <methodsynopsis>
-    <type>void</type><methodname>closedir</methodname>
-    
<methodparam><type>resource</type><parameter>dir_handle</parameter></methodparam>
-   </methodsynopsis>
+  <methodsynopsis>
+   <type>void</type><methodname>closedir</methodname>
+   
<methodparam><type>resource</type><parameter>dir_handle</parameter></methodparam>
+  </methodsynopsis>
   <para>
    Closes the directory stream indicated by
    <parameter>dir_handle</parameter>. The stream must have previously
    been opened by <function>opendir</function>.
   </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>dir_handle</parameter></term>
+     <listitem>
+      <para>
+       The directory handle <type>resource</type> previously opened
+       with <function>opendir</function>.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
   <para>
    <example>
     <title><function>closedir</function> example</title>
http://cvs.php.net/diff.php/phpdoc/en/reference/dir/functions/getcwd.xml?r1=1.10&r2=1.11&ty=u
Index: phpdoc/en/reference/dir/functions/getcwd.xml
diff -u phpdoc/en/reference/dir/functions/getcwd.xml:1.10 
phpdoc/en/reference/dir/functions/getcwd.xml:1.11
--- phpdoc/en/reference/dir/functions/getcwd.xml:1.10   Mon Apr 11 18:04:40 2005
+++ phpdoc/en/reference/dir/functions/getcwd.xml        Mon Apr 11 19:28:21 2005
@@ -1,29 +1,40 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.10 $ -->
+<!-- $Revision: 1.11 $ -->
 <!-- splitted from ./en/functions/dir.xml, last change in rev 1.7 -->
 <refentry id="function.getcwd">
  <refnamediv>
   <refname>getcwd</refname>
   <refpurpose>Gets the current working directory</refpurpose>
  </refnamediv>
- <refsect1>
+
+ <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
    <type>string</type><methodname>getcwd</methodname>
    <void/>
   </methodsynopsis>
   <para>
-   Returns the current working directory, or &false; on failure.
+   Gets the current working directory.
   </para>
-  <note>
-   <para>
-    On some Unix variants, <function>getcwd</function> will return
-    &false; if any one of the parent directories does not have the
-    readable or search mode set, even if the current directory
-    does. See <function>chmod</function> for more information on
-    modes and permissions.
-   </para>
-  </note>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   Returns the current working directory on success, or &false; on
+   failure.
+  </para> 
+  <para>
+   On some Unix variants, <function>getcwd</function> will return
+   &false; if any one of the parent directories does not have the
+   readable or search mode set, even if the current directory
+   does. See <function>chmod</function> for more information on
+   modes and permissions.
+  </para>
+ </refsect1>
+ 
+ <refsect1 role="examples">
+  &reftitle.examples;
   <para>
    <example>
     <title><function>getcwd</function> example</title>
@@ -51,9 +62,15 @@
      </screen>
    </example>
   </para>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
   <para>
-   See also <function>chdir</function> and
-   <function>chmod</function>.
+   <simplelist>
+    <member><function>chdir</function></member>
+    <member><function>chmod</function></member>
+   </simplelist>
   </para>
  </refsect1>
 </refentry>
http://cvs.php.net/diff.php/phpdoc/en/reference/dir/functions/opendir.xml?r1=1.13&r2=1.14&ty=u
Index: phpdoc/en/reference/dir/functions/opendir.xml
diff -u phpdoc/en/reference/dir/functions/opendir.xml:1.13 
phpdoc/en/reference/dir/functions/opendir.xml:1.14
--- phpdoc/en/reference/dir/functions/opendir.xml:1.13  Mon Apr 11 18:04:40 2005
+++ phpdoc/en/reference/dir/functions/opendir.xml       Mon Apr 11 19:28:21 2005
@@ -1,22 +1,47 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.13 $ -->
+<!-- $Revision: 1.14 $ -->
 <!-- splitted from ./en/functions/dir.xml, last change in rev 1.2 -->
 <refentry id="function.opendir">
  <refnamediv>
   <refname>opendir</refname>
   <refpurpose>Open directory handle</refpurpose>
  </refnamediv>
- <refsect1>
+
+ <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
    <type>resource</type><methodname>opendir</methodname>
    <methodparam><type>string</type><parameter>path</parameter></methodparam>
   </methodsynopsis>
   <para>
-   Returns a directory handle to be used in subsequent
+   Opens up a directory handle to be used in subsequent
    <function>closedir</function>, <function>readdir</function>, and
    <function>rewinddir</function> calls.
   </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>path</parameter></term>
+     <listitem>
+      <para>
+       The directory path that is to be opened
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   Returns a directory handle <type>resource</type> on success, or
+   &false; on failure.
+  </para> 
   <para>
    If <parameter>path</parameter> is not a valid directory or the
    directory can not be opened due to permission restrictions or
@@ -27,6 +52,43 @@
    '<link linkend="language.operators.errorcontrol">@</link>' to the
    front of the function name.
   </para>
+ </refsect1>
+
+ <refsect1 role="changelog">
+  &reftitle.changelog;
+  <para>
+   <informaltable>
+    <tgroup cols="2">
+     <thead>
+      <row>
+       <entry>&Version;</entry>
+       <entry>&Description;</entry>
+      </row>
+     </thead>
+     <tbody>
+      <row>
+       <entry>5.0.0</entry>
+       <entry>
+        <parameter>path</parameter> supports the <literal>ftp://</literal> 
+        URL wrapper.
+       </entry>
+      </row>
+      <row>
+       <entry>4.3.0</entry>
+       <entry>
+        <parameter>path</parameter> can also be any URL which supports 
+        directory listing, however only the <literal>file://</literal>
+        URL wrapper supports this in PHP 4
+       </entry>
+      </row>
+     </tbody>
+    </tgroup>
+   </informaltable>
+  </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
   <para>
    <example>
     <title><function>opendir</function> example</title>
@@ -59,18 +121,17 @@
     </screen>
    </example>
   </para>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
   <para>
-   As of PHP 4.3.0 <parameter>path</parameter> can also
-   be any URL which supports directory listing, however only the 
<literal>file://</literal>
-   URL wrapper supports this in PHP 4.3.  As of
-   PHP 5.0.0, support for the <literal>ftp://</literal>
-   URL wrapper is included as well.
+   <simplelist>
+    <member><function>is_dir</function></member>
+    <member><function>readdir</function></member>
+    <member><link linkend="class.dir">Dir</link></member>
+   </simplelist>
   </para>
-  <para>
-   See also <function>is_dir</function>,
-   <function>readdir</function>, and
-   <link linkend="class.dir">Dir</link>
-   </para>
  </refsect1>
 </refentry>
 
http://cvs.php.net/diff.php/phpdoc/en/reference/dir/functions/readdir.xml?r1=1.8&r2=1.9&ty=u
Index: phpdoc/en/reference/dir/functions/readdir.xml
diff -u phpdoc/en/reference/dir/functions/readdir.xml:1.8 
phpdoc/en/reference/dir/functions/readdir.xml:1.9
--- phpdoc/en/reference/dir/functions/readdir.xml:1.8   Mon Apr 11 18:04:40 2005
+++ phpdoc/en/reference/dir/functions/readdir.xml       Mon Apr 11 19:28:21 2005
@@ -1,12 +1,13 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.8 $ -->
+<!-- $Revision: 1.9 $ -->
 <!-- splitted from ./en/functions/dir.xml, last change in rev 1.2 -->
 <refentry id="function.readdir">
  <refnamediv>
   <refname>readdir</refname>
   <refpurpose>Read entry from directory handle</refpurpose>
  </refnamediv>
- <refsect1>
+
+ <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
    <type>string</type><methodname>readdir</methodname>
@@ -17,19 +18,47 @@
    filenames are returned in the order in which they are stored by
    the filesystem.
   </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
   <para>
-   Please note the fashion in which <function>readdir</function>'s
-   return value is checked in the examples below. We are explicitly
-   testing whether the return value is identical to (equal to and of
-   the same type as--see <link
-   linkend="language.operators.comparison">Comparison
-   Operators</link> for more information) &false; since otherwise,
-   any directory entry whose name evaluates to &false; will stop the
-   loop (e.g. a directory named "0").
+   <variablelist>
+    <varlistentry>
+     <term><parameter>dir_handle</parameter></term>
+     <listitem>
+      <para>
+       The directory handle <type>resource</type> previously opened
+       with <function>opendir</function>.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
   </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   Returns the filename on success, or &false; on failure.
+  </para> 
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
   <para>
    <example>
     <title>List all files in a directory</title>
+    <para>
+     Please note the fashion in which <function>readdir</function>'s
+     return value is checked in the examples below. We are explicitly
+     testing whether the return value is identical to (equal to and of
+     the same type as--see <link
+     linkend="language.operators.comparison">Comparison
+     Operators</link> for more information) &false; since otherwise,
+     any directory entry whose name evaluates to &false; will stop the
+     loop (e.g. a directory named "0").
+    </para>
     <programlisting role="php">
 <![CDATA[
 <?php
@@ -57,10 +86,6 @@
    </example>
   </para>
   <para>
-   Note that <function>readdir</function> will return the <literal>.</literal>
-   and
-   <literal>..</literal> entries.  If you don't want these, simply strip
-   them out:
    <example>
     <title>
      List all files in the current directory and strip out <literal>.</literal>
@@ -82,9 +107,15 @@
     </programlisting>
    </example>
   </para>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
   <para>
-   See also <function>is_dir</function> and
-   <function>glob</function>.
+   <simplelist>
+    <member><function>is_dir</function></member>
+    <member><function>glob</function></member>
+   </simplelist>
   </para>
  </refsect1>
 </refentry>
http://cvs.php.net/diff.php/phpdoc/en/reference/dir/functions/rewinddir.xml?r1=1.5&r2=1.6&ty=u
Index: phpdoc/en/reference/dir/functions/rewinddir.xml
diff -u phpdoc/en/reference/dir/functions/rewinddir.xml:1.5 
phpdoc/en/reference/dir/functions/rewinddir.xml:1.6
--- phpdoc/en/reference/dir/functions/rewinddir.xml:1.5 Mon Apr 11 18:04:40 2005
+++ phpdoc/en/reference/dir/functions/rewinddir.xml     Mon Apr 11 19:28:21 2005
@@ -1,12 +1,13 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.5 $ -->
+<!-- $Revision: 1.6 $ -->
 <!-- splitted from ./en/functions/dir.xml, last change in rev 1.2 -->
 <refentry id="function.rewinddir">
  <refnamediv>
   <refname>rewinddir</refname>
   <refpurpose>Rewind directory handle</refpurpose>
  </refnamediv>
- <refsect1>
+
+ <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
    <type>void</type><methodname>rewinddir</methodname>
@@ -17,7 +18,23 @@
    <parameter>dir_handle</parameter> to the beginning of the
    directory.
   </para>
+ </refsect1>
 
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>dir_handle</parameter></term>
+     <listitem>
+      <para>
+       The directory handle <type>resource</type> previously opened
+       with <function>opendir</function>.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
  </refsect1>
 </refentry>
 
http://cvs.php.net/diff.php/phpdoc/en/reference/dir/functions/scandir.xml?r1=1.8&r2=1.9&ty=u
Index: phpdoc/en/reference/dir/functions/scandir.xml
diff -u phpdoc/en/reference/dir/functions/scandir.xml:1.8 
phpdoc/en/reference/dir/functions/scandir.xml:1.9
--- phpdoc/en/reference/dir/functions/scandir.xml:1.8   Mon Apr 11 18:04:40 2005
+++ phpdoc/en/reference/dir/functions/scandir.xml       Mon Apr 11 19:28:21 2005
@@ -1,13 +1,12 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.8 $ -->
+<!-- $Revision: 1.9 $ -->
 <refentry id="function.scandir">
  <refnamediv>
   <refname>scandir</refname>
-  <refpurpose>
-   List files and directories inside the specified path
-  </refpurpose>
+  <refpurpose>List files and directories inside the specified path</refpurpose>
  </refnamediv>
- <refsect1>
+
+ <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
    <type>array</type><methodname>scandir</methodname>
@@ -17,19 +16,59 @@
   </methodsynopsis>
   <para>
    Returns an <type>array</type> of files and directories from the
-   <parameter>directory</parameter>.  If <parameter>directory</parameter>
-   is not a directory, then boolean &false; is returned, and an error of
-   level <constant>E_WARNING</constant> is generated.
+   <parameter>directory</parameter>.
   </para>
+
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
   <para>
-   By default, the sorted order is alphabetical in ascending order.  If
-   the optional <parameter>sorting_order</parameter> is used (set to 1),
-   then sort order is alphabetical in descending order.
+   <variablelist>
+    <varlistentry>
+     <term><parameter>directory</parameter></term>
+     <listitem>
+      <para>
+       The directory that will be scanned.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>sorting_order</parameter></term>
+     <listitem>
+      <para>
+       By default, the sorted order is alphabetical in ascending order.  If
+       the optional <parameter>sorting_order</parameter> is used (set to 1),
+       then the sort order is alphabetical in descending order.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>context</parameter></term>
+     <listitem>
+      <para>
+       For a description of the <parameter>context</parameter> parameter, 
+       refer to <link linkend="ref.stream">the streams section</link> of
+       the manual.
+      </para> 
+     </listitem>
+    </varlistentry>
+   </variablelist>
   </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
   <para>
-   For a description of the <parameter>context</parameter> parameter, refer
-   to <xref linkend="ref.stream"/>.
-  </para>
+   Returns an <type>array</type> of filenames on success, or &false; on 
+   failure. If <parameter>directory</parameter> is not a directory, then 
+   boolean &false; is returned, and an error of level 
+   <constant>E_WARNING</constant> is generated.
+  </para> 
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
   <para>
    <example>
     <title>A simple <function>scandir</function> example</title>
@@ -114,13 +153,23 @@
     </screen>
    </example>
   </para>
+ </refsect1>
+
+ <refsect1 role="notes">
+  &reftitle.notes;
   &tip.fopen-wrapper;
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
   <para>
-   See also <function>opendir</function>,
-   <function>readdir</function>,
-   <function>glob</function>,
-   <function>is_dir</function>, and
-   <function>sort</function>.
+   <simplelist>
+    <member><function>opendir</function></member>
+    <member><function>readdir</function></member>
+    <member><function>glob</function></member>
+    <member><function>is_dir</function></member>
+    <member><function>sort</function></member>
+   </simplelist>
   </para>
  </refsect1>
 </refentry>