Syslinux - Jan 2011 - [PATCH v2] 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).

While we're at it, also convert the name ldlinus.sys to lowercase
everywhere, even if it's clear its name is used in a DOS context.

Signed-off-by: Paul Bolle <pebolle at tiscali.nl>
---
This is a result of yesterday's discussion of a previous patch
("Describe the --directory option more precisely"). That patch is now
merged into this one too (I forgot to do that in the first version of
this patch).

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   |   16 ++++++++--------
 2 files changed, 20 insertions(+), 18 deletions(-)

diff --git a/doc/syslinux.txt b/doc/syslinux.txt
index 5b27a6e..41ec193 100644
--- a/doc/syslinux.txt
+++ b/doc/syslinux.txt
@@ -56,7 +56,7 @@ 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.)
 
@@ -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 be 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):
@@ -686,7 +688,7 @@ Ctrl key while booting disables this feature.
 Any file that SYSLINUX uses can be marked hidden, system or readonly
 if so is convenient; SYSLINUX ignores all file attributes.  The
 SYSLINUX installed automatically sets the readonly/hidden/system
-attributes on LDLINUX.SYS.
+attributes on ldlinux.sys.
 

    ++++ NOTES ON BOOTABLE CD-ROMS ++++
diff --git a/man/syslinux.1 b/man/syslinux.1
index af44979..9de2864 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.
@@ -62,8 +61,9 @@ the boot sequence (usually the next hard disk) instead of
stopping
 with an error message.  This is useful for RAID-1 booting.
 .TP
 \fB\-d\fP, \fB\-\-directory\fP \fIsubdirectory\fP
-Install the \s-1SYSLINUX\s+1 control files in a subdirectory with the
-specified name (relative to the root directory on the device).
+Install the ldlinux.sys file in a subdirectory with the
+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:
@@ -355,11 +355,11 @@ Ctrl key while booting disables this feature.
 .PP
 The compile time and date of a specific \fBsyslinux\fP version can be obtained
 by the DOS command "type ldlinux.sys". This is also used as the
-signature for the LDLINUX.SYS file, which must match the boot sector
+signature for the ldlinux.sys file, which must match the boot sector
 .PP
 Any file that \fBsyslinux\fP uses can be marked hidden, system or readonly if
 so is convenient; \fBsyslinux\fP ignores all file attributes.  The
\s-1SYSLINUX\s+1
-installed automatically sets the readonly attribute on LDLINUX.SYS.
+installed automatically sets the readonly attribute on ldlinux.sys.
 .SS Bootable CD-ROMs
 \s-1SYSLINUX\s+1 can be used to create bootdisk images for El
 Torito-compatible bootable CD-ROMs. However, it appears that many
-- 
1.7.3.4

Paul Bolle <pebolle at tiscali.nl> writes:
> If a /boot/syslinux directory or /syslinux directory is used, is it used
> as a working directory too?
When any Syslinux variant starts up, its working directory is set to the
installation directory, ie. where ldlinux.sys/isolinux.bin/pxelinux.0
was loaded from.
> -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 be 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.)
In my opinion the original text is better.  The working directory stuff
could be discussed later.
>  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.
Neither is true.  What's actually needed is that the file must reside in
the same filesystem.  Of course, if some file is in the working
directory, one can access it without supplying its path.  Basically,
Syslinux works as if PATH=. (ie. working directory only).
>  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.
Rather in its installation directory.  Which coincides with the working
directory at startup, but loading a new config file via the CONFIG
directive or config.c32 can change that.  The text in 5e50b4d4 or in the
corresponding 4.00 changelog should be molded into the documentation of
CONFIG to make this clear.
>  Starting with version 3.35, the configuration file can also be in
>  either the /boot/syslinux or /syslinux directories (searched in that
I wonder if this part is still relevant...  No time for experiments.
>  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.
Again, this isn't a requirement, just like with kernel images.
>  Any file that SYSLINUX uses can be marked hidden, system or readonly
>  if so is convenient; SYSLINUX ignores all file attributes.  The
>  SYSLINUX installed automatically sets the readonly/hidden/system
           /
    installer
>  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.
Same thing again.
> -Install the \s-1SYSLINUX\s+1 control files in a subdirectory with the
> -specified name (relative to the root directory on the device).
> +Install the ldlinux.sys file in a subdirectory with the
> +specified name (relative to the root directory on the device). ldlinux.sys
> +will then use this subdirectory as its working directory.
At initial startup, yes.
>  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
Again, I find the original text clearer...
>  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.
The usual thing again: only the same filesystem is required.
> -installed automatically sets the readonly attribute on LDLINUX.SYS.
> +installed automatically sets the readonly attribute on ldlinux.sys.
     /
installer

Thanks for tackling this, hope you don't get discouraged by my
comments.  We should make the documentation understandable for the
newcomers, not us corrupted by following the mailling list for years
(thus taking a lot of things granted).
-- 
Regards,
Feri.