Updating include and include_path documentation to be more clear and explicit.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@287153 c90b9560-bf6c-de11-be94-00142212c4b1

appendices/ini.xml

@@ -4638,6 +4638,16 @@ auto_prepend_file=security.php
         <envar>PATH</envar> environment variable: a list of directories
         separated with a colon in Unix or semicolon in Windows.
        </para>
+       <para>
+        PHP considers each entry in the include path separately when looking for
+        files to include. It will check the first path, and if it doesn't find
+        it, check the next path, until it either locates the included file or
+        returns with a 
+        <link linkend="errorfunc.constants.errorlevels.e-warning">warning</link>
+        or an <link linkend="errorfunc.constants.errorlevels.e-error">error</link>. 
+        You may modify or set your include path at runtime using
+        <function>set_include_path</function>.
+       </para>
        <para>
         <example>
          <title>Unix include_path</title>

language/control-structures/include.xml

@@ -9,29 +9,25 @@
  </simpara>
  <simpara>
   The documentation below also applies to <function>require</function>.
-  The two constructs are identical in every way except how they handle
-  failure. They both produce a
-  <link linkend="errorfunc.constants.errorlevels.e-warning">Warning</link>, but <function>require</function>
-  results in a <link linkend="errorfunc.constants.errorlevels.e-error">Fatal Error</link>.
-  In other words, use <function>require</function> if you want
-  a missing file to halt processing of the page.  <function>include</function> does
-  not behave this way, the script will continue regardless.  Be sure to have an
-  appropriate <link linkend="ini.include-path">include_path</link> setting as well.
-  Be warned that parse error in included file doesn't cause processing halting
-  in PHP versions prior to PHP 4.3.5. Since this version, it does.
  </simpara>
  <simpara>
-  Files for including are first looked for in each include_path entry
-  relative to the current working directory, and then in the directory of
-  current script.
-  E.g. if your include_path
-  is <literal>libraries</literal>, current working directory is <filename class="directory">/www/</filename>,
-  you included <filename>include/a.php</filename> and there is <literal>include "b.php"</literal>
-  in that file, <filename>b.php</filename> is first looked in <filename class="directory">/www/libraries/</filename>
-  and then in <filename class="directory">/www/include/</filename>.
-  If filename begins with <literal>./</literal> or <literal>../</literal>, it
-  is looked for only in the current working directory or parent of the
-  current working directory, respectively.
+  Files are included based on the file path given or, if none is given, the 
+  <link linkend="ini.include-path">include_path</link> specified. The 
+  <function>include</function> construct will emit a 
+  <link linkend="errorfunc.constants.errorlevels.e-warning">warning</link> if it
+  cannot find a file; this is different behavior from <function>require</a>, 
+  which will emit a 
+  <link linkend="errorfunc.constants.errorlevels.e-error">fatal error</link>.
+ </simpara>
+ <simpara>
+  If a path is defined (full or relative), the 
+  <link linkend="ini.include-path">include_path</link> will be ignored altogether.
+  For example, if a filename begins with <literal>../</literal>, the parser will
+  look in the parent directory to find the requested file.
+ </simpara>
+ <simpara>
+  For more information on how PHP handles including files and the include path,
+  see the documentation for <link linkend="ini.include-path">include_path</link>.
  </simpara>
  <simpara>
   When a file is included, the code it contains inherits the