From 3afe662a497f4821a99999231c8e28929e74435b Mon Sep 17 00:00:00 2001
From: Michal Soltys <soltys@ziu.info>
Date: Sat, 14 Aug 2010 23:23:33 +0200
Subject: [PATCH] chain.c: adjust usage(), update placeholder doc/chain.txt

Make usage() info more precise, adjust indentation.
Update placeholder docs.

Signed-off-by: Michal Soltys <soltys@ziu.info>
---
 com32/chain/chain.c |  55 +++++++-------
 doc/chain.txt       | 208 +++++++++++++++++++++++++++-------------------------
 2 files changed, 138 insertions(+), 125 deletions(-)

diff --git a/com32/chain/chain.c b/com32/chain/chain.c
index 7e0b09d..76a475d 100644
--- a/com32/chain/chain.c
+++ b/com32/chain/chain.c
@@ -14,7 +14,7 @@
  * ----------------------------------------------------------------------- */
 
 /*
- * Please see doc/chain.txt for detailed documentation.
+ * Please see doc/chain.txt for the detailed documentation.
  */
 
 #include <com32.h>
@@ -410,31 +410,32 @@ bail:
 static void usage(void)
 {
     static const char usage[] = "\
-Usage:   chain.c32 [options]\n\
-         chain.c32 hd<disk#> [<partition>] [options]\n\
-         chain.c32 fd<disk#> [options]\n\
-         chain.c32 mbr:<id> [<partition>] [options]\n\
-         chain.c32 guid:<guid> [<partition>] [options]\n\
-         chain.c32 label:<label> [<partition>] [options]\n\
-         chain.c32 boot [<partition>] [options]\n\
-         chain.c32 fs [options]\n\
-Options: file=<loader>      Load and execute file, instead of boot sector\n\
-         isolinux=<loader>  Load another version of ISOLINUX\n\
-         ntldr=<loader>     Load Windows NTLDR, SETUPLDR.BIN or BOOTMGR\n\
-         cmldr=<loader>     Load Recovery Console of Windows NT/2K/XP/2003\n\
-         freedos=<loader>   Load FreeDOS KERNEL.SYS\n\
-         msdos=<loader>     Load MS-DOS IO.SYS\n\
-         pcdos=<loader>     Load PC-DOS IBMBIO.COM\n\
-         drmk=<loader>      Load DRMK DELLBIO.BIN\n\
-         grub=<loader>      Load GRUB Legacy stage2\n\
-         grubcfg=<filename> Set alternative config filename for GRUB Legacy\n\
-         grldr=<loader>     Load GRUB4DOS grldr\n\
-         seg=<segment>      Jump to <seg>:0000, instead of 0000:7C00\n\
-         swap               Swap drive numbers, if bootdisk is not fd0/hd0\n\
-         hide               Hide primary partitions, except selected partition\n\
-         sethidden          Set the FAT/NTFS hidden sectors field\n\
-         keeppxe            Keep the PXE and UNDI stacks in memory (PXELINUX)\n\
-See syslinux/com32/modules/chain.c for more information\n";
+Usage:\n\
+    chain.c32 [options]\n\
+    chain.c32 {fd|hd}<disk> [<partition>] [options]\n\
+    chain.c32 mbr{:|=}<id> [<partition>] [options]\n\
+    chain.c32 guid{:|=}<guid> [<partition>] [options]\n\
+    chain.c32 label{:|=}<label> [<partition>] [options]\n\
+    chain.c32 boot{,| }[<partition>] [options]\n\
+    chain.c32 fs [options]\n\
+\nOptions:\n\
+    file=<loader>      Load and execute file, instead of boot sector\n\
+    isolinux=<loader>  Load another version of ISOLINUX\n\
+    ntldr=<loader>     Load Windows NTLDR, SETUPLDR.BIN or BOOTMGR\n\
+    cmldr=<loader>     Load Recovery Console of Windows NT/2K/XP/2003\n\
+    freedos=<loader>   Load FreeDOS KERNEL.SYS\n\
+    msdos=<loader>     Load MS-DOS IO.SYS\n\
+    pcdos=<loader>     Load PC-DOS IBMBIO.COM\n\
+    drmk=<loader>      Load DRMK DELLBIO.BIN\n\
+    grub=<loader>      Load GRUB Legacy stage2\n\
+    grubcfg=<filename> Set alternative config filename for GRUB Legacy\n\
+    grldr=<loader>     Load GRUB4DOS grldr\n\
+    seg=<segment>      Jump to <seg>:0000, instead of 0000:7C00\n\
+    swap               Swap drive numbers, if bootdisk is not fd0/hd0\n\
+    hide               Hide primary partitions, except selected partition\n\
+    sethidden          Set the FAT/NTFS hidden sectors field\n\
+    keeppxe            Keep the PXE and UNDI stacks in memory (PXELINUX)\n\
+\nPlease see doc/chain.txt for the detailed documentation.\n";
     error(usage);
 }
 
@@ -637,7 +638,7 @@ int main(int argc, char *argv[])
     if (cur_part)
 	whichpart = cur_part->index;
 
-    /* If nothing was found, try fs/boot first */
+    /* If nothing was found, try fs first */
     if (!cur_part && fs_lba) {
 	cur_part = pi_begin(&diskinfo);
 	/* search for matching fs_lba, must be partition */
diff --git a/doc/chain.txt b/doc/chain.txt
index 8999c1d..5cba3a5 100644
--- a/doc/chain.txt
+++ b/doc/chain.txt
@@ -1,100 +1,112 @@
 			    chain.c32 documentation
 
-Although syslinux features simple native chainloading capability (through .bss
-and .bs options - see doc/syslinux.txt), it also provides very roboust and
-feature rich com32 module designed for such purpose - which should allow you to
-boot virtually anything.
-
-FIXME: initial move from chain.c below
-
-/*
- * chain.c
- *
- * Chainload a hard disk (currently rather braindead.)
- *
- * Usage: chain [options]
- *	  chain hd<disk#> [<partition>] [options]
- *	  chain fd<disk#> [options]
- *	  chain mbr:<id> [<partition>] [options]
- *	  chain guid:<guid> [<partition>] [options]
- *	  chain label:<label> [<partition>] [options]
- *	  chain boot [<partition>] [options]
- *
- * For example, "chain msdos=io.sys" will load DOS from the current Syslinux
- * filesystem.  "chain hd0 1" will boot the first partition on the first hard
- * disk.
- *
- * When none of the "hdX", "fdX", "mbr:", "guid:", "label:", "boot" or "fs"
- * options are specified, the default behaviour is equivalent to "boot".
- * "boot" means to use the current Syslinux drive, and you can also specify
- * a partition.
- *
- * The mbr: syntax means search all the hard disks until one with a
- * specific MBR serial number (bytes 440-443) is found.
- *
- * Partitions 1-4 are primary, 5+ logical, 0 = boot MBR (default.)
- *
- * "fs" will use the current Syslinux filesystem as the boot drive/partition.
- * When booting from PXELINUX, you will most likely wish to specify a disk.
- *
- * Options:
- *
- * file=<loader>
- *	loads the file <loader> **from the Syslinux filesystem**
- *	instead of loading the boot sector.
- *
- * seg=<segment>
- *	loads at and jumps to <seg>:0000 instead of 0000:7C00.
- *
- * isolinux=<loader>
- *	chainload another version/build of the ISOLINUX bootloader and patch
- *	the loader with appropriate parameters in memory.
- *	This avoids the need for the -eltorito-alt-boot parameter of mkisofs,
- *	when you want more than one ISOLINUX per CD/DVD.
- *
- * ntldr=<loader>
- *	equivalent to seg=0x2000 file=<loader> sethidden,
- *	used with WinNT's loaders
- *
- * cmldr=<loader>
- *	used with Recovery Console of Windows NT/2K/XP.
- *	same as ntldr=<loader> & "cmdcons\0" written to
- *	the system name field in the bootsector
- *
- * freedos=<loader>
- *	equivalent to seg=0x60 file=<loader> sethidden,
- *	used with FreeDOS' kernel.sys.
- *
- * msdos=<loader>
- * pcdos=<loader>
- *	equivalent to seg=0x70 file=<loader> sethidden,
- *	used with DOS' io.sys.
- *
- * grub=<loader>
- *	same as seg=0x800 file=<loader> & jumping to seg 0x820,
- *	used with GRUB Legacy stage2 files.
- *
- * grubcfg=<filename>
- *	set an alternative config filename in stage2 of Grub Legacy,
- *	only applicable in combination with "grub=<loader>".
- *
- * grldr=<loader>
- *	pass the partition number to GRUB4DOS,
- *	used with GRUB4DOS' grldr.
- *
- * swap
- *	if the disk is not fd0/hd0, install a BIOS stub which swaps
- *	the drive numbers.
- *
- * hide
- *	change type of primary partitions with IDs 01, 04, 06, 07,
- *	0b, 0c, or 0e to 1x, except for the selected partition, which
- *	is converted the other way.
- *
- * sethidden
- *	update the "hidden sectors" (partition offset) field in a
- *	FAT/NTFS boot sector.
- *
- * keeppxe
- *	keep the PXE and UNDI stacks in memory (PXELINUX only).
- */
+Although syslinux is capable of (very simple) native chainloading (through .bss
+and .bs options - see doc/syslinux.txt), it also has a very roboust and
+feature-rich com32 module designed for such purpose. This module should allow
+you to boot virtually anything.
+
+
+!FIXME: initial move from chain.c below
+
+
+Chainload a hard disk.
+
+Usage: chain [options]
+       chain hd<disk#> [<partition>] [options]
+       chain fd<disk#> [options]
+       chain mbr:<id> [<partition>] [options]
+       chain guid:<guid> [<partition>] [options]
+       chain label:<label> [<partition>] [options]
+       chain boot [<partition>] [options]
+
+For example, "chain msdos=io.sys" will load DOS from the current Syslinux
+filesystem.  "chain hd0 1" will boot the first partition on the first hard
+disk.
+
+When none of the "hdX", "fdX", "mbr:", "guid:", "label:", "boot" or "fs"
+options are specified, the default behaviour is equivalent to "boot".
+"boot" means to use the current Syslinux drive, and you can also specify
+a partition.
+
+The mbr: syntax means search all the hard disks until one with a
+specific MBR serial number (bytes 440-443) is found.
+
+Partitions 1-4 are primary, 5+ logical, 0 = boot MBR (default.)
+
+"fs" will use the current Syslinux filesystem as the boot drive/partition.
+When booting from PXELINUX, you will most likely wish to specify a disk.
+
+Options:
+
+file=<loader>
+     loads the file <loader> **from the Syslinux filesystem**
+     instead of loading the boot sector.
+
+seg=<segment>
+     loads at and jumps to <seg>:0000 instead of 0000:7C00.
+
+isolinux=<loader>
+     chainload another version/build of the ISOLINUX bootloader and patch
+     the loader with appropriate parameters in memory.
+     This avoids the need for the -eltorito-alt-boot parameter of mkisofs,
+     when you want more than one ISOLINUX per CD/DVD.
+
+ntldr=<loader>
+     equivalent to seg=0x2000 file=<loader> sethidden,
+     used with WinNT's loaders
+
+cmldr=<loader>
+     used with Recovery Console of Windows NT/2K/XP.
+     same as ntldr=<loader> & "cmdcons\0" written to
+     the system name field in the bootsector
+
+freedos=<loader>
+     equivalent to seg=0x60 file=<loader> sethidden,
+     used with FreeDOS' kernel.sys.
+
+msdos=<loader>
+pcdos=<loader>
+     equivalent to seg=0x70 file=<loader> sethidden,
+     used with DOS' io.sys.
+
+grub=<loader>
+     same as seg=0x800 file=<loader> & jumping to seg 0x820,
+     used with GRUB Legacy stage2 files.
+
+grubcfg=<filename>
+     set an alternative config filename in stage2 of Grub Legacy,
+     only applicable in combination with "grub=<loader>".
+
+grldr=<loader>
+     pass the partition number to GRUB4DOS,
+     used with GRUB4DOS' grldr.
+
+swap
+     if the disk is not fd0/hd0, install a BIOS stub which swaps
+     the drive numbers.
+
+hide
+     change type of primary partitions with IDs 01, 04, 06, 07,
+     0b, 0c, or 0e to 1x, except for the selected partition, which
+     is converted the other way.
+
+sethidden
+     update the "hidden sectors" (partition offset) field in a
+     FAT/NTFS boot sector.
+
+keeppxe
+     keep the PXE and UNDI stacks in memory (PXELINUX only).
+
+
+    file=<loader>      Load and execute file; boot sector is also\n\
+    msdos7=<loader>    Load MS-DOS 7+ IO.SYS\n\
+    seg=<s[:o[:i]]>    Load file at <s:o>, jump to <s:i>\n\
+    segbs=<s[:o[:i]]>  Load boot sector at <s:o>, jump to <s:i>;\n\
+    sethidden          Set the FAT/NTFS hidden sectors field\n\
+    setgeometry        Set the FAT/NTFS sectors per track and heads fields\n\
+    setdrive@<offset>  Set the FAT/NTFS drive unit field at <offset>;\n\
+                           setdrive option alone defaults to 0x24\n\
+    setbpb             Enable set{hidden,geometry} options\n\
+    writebs            Write updated boot sector to the disk\n\
+    filebpb            Also mangle file with bpb options\n\
+    bsnomap            Don't map boot sector into real memory.\n\
-- 
2.7.4