Clarify glob() issues raised by user notes and add another example (#3647)

Author: jimwins

reference/filesystem/functions/glob.xml

@@ -19,6 +19,13 @@
    the libc glob() function, which is similar to the rules used by common
    shells.
   </para>
+  <simpara>
+   The behavior on Unix systems and macOS is determined by the system's
+   implementation of glob(). On Windows, an implementation that conforms
+   to the POSIX 1003.2 definition for glob() is used, and it includes
+   an extension to handle the <literal>[!...]</literal> convention for
+   negating a range.
+  </simpara>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -78,13 +85,9 @@
   <para>
    Returns an array containing the matched files/directories, an empty array
    if no file matched or &false; on error.
+   Unless <literal>GLOB_NOSORT</literal> was used, the names will
+   be sorted alphanumerically.
   </para>
-  <note>
-   <para>
-    On some systems it is impossible to distinguish between empty match and an
-    error.
-   </para>
-  </note>
  </refsect1>
 
  <refsect1 role="examples">
@@ -110,6 +113,30 @@ foreach (glob("*.txt") as $filename) {
 funclist.txt size 44686
 funcsummary.txt size 267625
 quickref.txt size 137820
+]]>
+    </screen>
+   </example>
+   <example>
+    <title>
+     Example with a more complex pattern
+    </title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+foreach (glob("path/*/*.{txt,md}", \GLOB_BRACE) as $filename) {
+    echo "$filename\n";
+}
+?>
+]]>
+    </programlisting>
+    &example.outputs.similar;
+    <screen>
+<![CDATA[
+path/docs/mailinglist-rules.md
+path/docs/README.md
+path/docs/release-process.md
+path/pear/install-pear.txt
+path/Zend/README.md
 ]]>
     </screen>
    </example>