Syslinux - Jan 2011 - [PATCH] Documentation: introduce the working directory

LDLINUX.SYS uses a working directory. The documentation seems to improve
if that fact is made explicit. So the working directory is added to the
documentation (with a bit of vagueness and possibly not entirely
correct, to keep it readable).

Signed-off-by: Paul Bolle <pebolle at tiscali.nl>
---
This is a result of today's discussion of a previous patch ("Describe
the --directory option more precisely").

If a /boot/syslinux directory or /syslinux directory is used, is it used
as a working directory too? If so, the documentation may need to mention
that too (ie, in a follow up patch).

 doc/syslinux.txt |   22 ++++++++++++----------
 man/syslinux.1   |   10 +++++-----
 2 files changed, 17 insertions(+), 15 deletions(-)

diff --git a/doc/syslinux.txt b/doc/syslinux.txt
index 5b27a6e..0c07d79 100644
--- a/doc/syslinux.txt
+++ b/doc/syslinux.txt
@@ -56,11 +56,11 @@ In order to create a bootable Linux floppy using SYSLINUX,
prepare a
 normal MS-DOS formatted floppy.  Copy one or more Linux kernel files to
 it, then execute the DOS command:
 
-        syslinux [-sfrma][-d directory] a: [bootsecfile]
+        syslinux [-sfrma][-d subdirectory] a: [bootsecfile]
 
 (or whichever drive letter is appropriate; the [] meaning optional.)
 
-Use "syslinux.com" (in the dos subdirectory of the distribution) for
+Use "syslinux.com" (in the DOS subdirectory of the distribution) for
 plain DOS (MS-DOS, DR-DOS, PC-DOS, FreeDOS...) or Win9x/ME.
 
 Use "syslinux.exe" (in the win32 subdirectory of the distribution)
for
@@ -68,13 +68,15 @@ WinNT/2000/XP.
 
 Under Linux, execute the command:
 
-	syslinux [-sfr][-d directory][-o offset] /dev/fd0
+	syslinux [-sfr][-d subdirectory][-o offset] /dev/fd0
 
 (or, again, whichever device is the correct one.)
 
-This will alter the boot sector on the disk and copy a file named
-LDLINUX.SYS into its root directory (or a subdirectory, if the -d
-option is specified.)
+This will alter the boot sector of that device. A file named LDLINUX.SYS
+will be copied into its root directory. That root directory will the working
+directory of LDLINUX.SYS. (If the -d option is given, that file will be copied
+into the specified subdirectory and that subdirectory will be the working
+directory of LDLINUX.SYS.)
 
 The -s option, if given, will install a "safe, slow and stupid"
 version of SYSLINUX.  This version may work on some very buggy BIOSes
@@ -94,8 +96,8 @@ If the Shift or Alt keys are held down during boot, or the
Caps or Scroll
 locks are set, Syslinux will display a LILO-style "boot:" prompt. 
The
 user can then type a kernel file name followed by any kernel parameters.
 The Syslinux loader does not need to know about the kernel file in
-advance; all that is required is that it is a file located in the root
-directory on the disk.
+advance; all that is required is that it is a file located in its working
+directory.
 
 There are two versions of the Linux installer; one in the "mtools"
 directory which requires no special privilege (other than write
@@ -110,7 +112,7 @@ All options here apply to PXELINUX, ISOLINUX and EXTLINUX as
well as
 SYSLINUX unless otherwise noted.  See the respective .txt files.
 
 All the configurable defaults in SYSLINUX can be changed by putting a
-file called "syslinux.cfg" in the root directory of the boot disk.
+file called "syslinux.cfg" in its working directory.
 
 Starting with version 3.35, the configuration file can also be in
 either the /boot/syslinux or /syslinux directories (searched in that
@@ -564,7 +566,7 @@ as well as COMBOOT-style standalone executables (a subset of
DOS .COM
 files; see separate section below.)
 
 Chain loading requires the boot sector of the foreign operating system
-to be stored in a file in the root directory of the filesystem.
+to be stored in a file in the LDLINUX.SYS working directory.
 Because neither Linux kernels, boot sector images, nor COMBOOT files
 have reliable magic numbers, Syslinux will look at the file extension.
 The following extensions are recognized (case insensitive):
diff --git a/man/syslinux.1 b/man/syslinux.1
index d08ab0f..21efe12 100644
--- a/man/syslinux.1
+++ b/man/syslinux.1
@@ -31,8 +31,7 @@ locks are set, \fBsyslinux\fP will display a
 -style "boot:" prompt. The user can then type a kernel file name
 followed by any kernel parameters. The \s-1SYSLINUX\s+1 bootloader
 does not need to know about the kernel file in advance; all that is
-required is that it is a file located in the root directory on the
-disk.
+required is that it is a file located in its working directory.
 .PP
 \fBSyslinux\fP supports the loading of initial ramdisks (initrd) and the
 bzImage kernel format.
@@ -63,7 +62,8 @@ with an error message.  This is useful for RAID-1 booting.
 .TP
 \fB\-d\fP, \fB\-\-directory\fP \fIsubdirectory\fP
 Install the ldlinux.sys file in a subdirectory with the
-specified name (relative to the root directory on the device).
+specified name (relative to the root directory on the device). ldlinux.sys
+will then use this subdirectory as its working directory.
 .TP
 \fB\-t\fP, \fB\-\-offset\fP \fIoffset\fP
 Indicates that the filesystem is at an offset from the base of the
@@ -88,7 +88,7 @@ Assume zipdrive geometry (\fI\-\-heads 64 \-\-sectors 32).
 All the configurable defaults in \s-1SYSLINUX\s+1 can be changed by putting a
 file called
 .B syslinux.cfg
-in the install directory of the boot disk. This
+in the ldlinux.sys working directory. This
 is a text file in either UNIX or DOS format, containing one or more of
 the following items (case is insensitive for keywords).
 .PP
@@ -304,7 +304,7 @@ as well as COMBOOT-style standalone executables (a subset of
DOS .COM
 files; see separate section below.)
 .PP
 Chain loading requires the boot sector of the foreign operating system
-to be stored in a file in the root directory of the filesystem.
+to be stored in a file in the ldlinux.sys working directory.
 Because neither Linux kernels, boot sector images, nor COMBOOT files
 have reliable magic numbers, \fBsyslinux\fP will look at the file
 extension. The following extensions are recognised:
-- 
1.7.3.4

On 01/12/2011 01:55 PM, Paul Bolle wrote:
>  
> -Use "syslinux.com" (in the dos subdirectory of the distribution)
for
> +Use "syslinux.com" (in the DOS subdirectory of the distribution)
for
>  plain DOS (MS-DOS, DR-DOS, PC-DOS, FreeDOS...) or Win9x/ME.
>  
The subdirectory is called "dos".
> -This will alter the boot sector on the disk and copy a file named
> -LDLINUX.SYS into its root directory (or a subdirectory, if the -d
> -option is specified.)
> +This will alter the boot sector of that device. A file named LDLINUX.SYS
> +will be copied into its root directory. That root directory will the
working
> +directory of LDLINUX.SYS. (If the -d option is given, that file will be
copied
> +into the specified subdirectory and that subdirectory will be the working
> +directory of LDLINUX.SYS.)
We probably should lowercase ldlinux.sys, since it's a lower case name
on Unix.

	-hpa