[syslinux:elflink] doc: Further explanation for the PATH directive and lookup rules

[syslinux-bot for Matt Fleming]

Commit-ID:  a8458c8f748a430137e25bd3ade8600978c828c3
Gitweb:     http://www.syslinux.org/commit/a8458c8f748a430137e25bd3ade8600978c828c3
Author:     Matt Fleming <matt.fleming at intel.com>
AuthorDate: Tue, 4 Dec 2012 13:42:24 +0000
Committer:  Matt Fleming <matt.fleming at intel.com>
CommitDate: Tue, 4 Dec 2012 13:44:09 +0000

doc: Further explanation for the PATH directive and lookup rules

The PATH directive can be quite confusing when coupled with the fact
that the current working directory is always searched first when
opening files.

Signed-off-by: Matt Fleming <matt.fleming at intel.com>

---
 doc/syslinux.txt | 30 +++++++++++++++++++++++++++++-
 1 file changed, 29 insertions(+), 1 deletion(-)

diff --git a/doc/syslinux.txt b/doc/syslinux.txt
index e9923a6..34dcb97 100644
--- a/doc/syslinux.txt
+++ b/doc/syslinux.txt
@@ -455,7 +455,9 @@ PATH path
 	when attempting to load modules. This directive is useful for
 	specifying the directories containing the lib*.c32 library
 	files as other modules may be dependent on these files, but
-	may not reside in the same directory.
+	may not reside in the same directory. The list of directories
+	is searched in order. Please see the section below on PATH
+	RULES.
 
 Blank lines are ignored.
 
@@ -775,6 +777,32 @@ In recent versions of Linux, this ID is available as
 /proc/sys/kernel/bootloader_type.
 
 
+   ++++ PATH RULES ++++
+
+The current working directory is *always* searched first, before PATH,
+when attempting to open a filename. The current working directory is
+not affected when specifying a file with an absolute path. For
+example, given the following file system layout,
+
+	 /boot/
+		/bin/
+			ls.c32
+			libls.c32
+		/foo/
+			libls.c32
+
+assuming that the current working directory is /boot/foo, and assuming
+that libls.c32 is a dependency of ls.c32, executing /boot/bin/ls.c32
+will cause /boot/foo/libls.c32 to be loaded, not /boot/bin/libls.c32,
+even if /boot/bin is specified in the PATH directive of a config file.
+
+The reason that things work this way is that typically a user will
+install all library files in the Syslinux installation directory, as
+specified with the --directory installer option. This method allows
+the user to omit the PATH directive from their config file and still
+have things work correctly.
+
+
    ++++ BUG REPORTS ++++
 
 I would appreciate hearing of any problems you have with Syslinux.  I