Write all the help text for the util-linux utilities. Allow

people to locate the mtab file somewhere other that /etc to
accomodate read only root filesystems.
 -Erik

1 files changed, 152 insertions, 34 deletions

diff --git a/util-linux/Config.in b/util-linux/Config.in
index 2494e6e1c..be56020f4 100644
--- a/util-linux/Config.in
+++ b/util-linux/Config.in
@@ -10,100 +10,144 @@ config CONFIG_DMESG
 	bool "dmesg"
 	default n
 	help
-	  Please submit a patch to add help text for this item.
+	  dmesg is used to examine or control the kernel ring buffer.  When the
+	  Linux kernel prints messages to the system log, they are stored in
+	  the kernel ring buffer.  You can use dmesg to print the kernel's ring
+	  buffer, clear the kernel ring buffer, change the size of the kernel
+	  ring buffer, and change the priority level at which kernel messages
+	  are also logged to the system console.  Enable this option if you
+	  wish to enable the 'dmesg' utility.
 
 config CONFIG_FBSET
 	bool "fbset"
 	default n
 	help
-	  Please submit a patch to add help text for this item.
+	  fbset is used to show or change the settings of a Linux frame buffer
+	  device.  The frame buffer device provides a simple and unique
+	  interface to access a graphic display.  Enable this option if you wish
+	  to enable the 'fbset' utility.
+
 
 config CONFIG_FEATURE_FBSET_FANCY
 	bool "  Turn on extra fbset options"
 	default n
 	depends on CONFIG_FBSET
 	help
-	  Please submit a patch to add help text for this item.
+	  This option enables extended fbset options, allowing one to set the
+	  framebuffer size, color depth, etc.  interface to access a graphic
+	  display.  Enable this option if you wish to enable extended fbset
+	  options.
 
 config CONFIG_FEATURE_FBSET_READMODE
 	bool "  Turn on fbset readmode support"
 	default n
 	depends on CONFIG_FBSET
 	help
-	  Please submit a patch to add help text for this item.
+	  This option allows fbset to read the video mode database stored by
+	  default as /etc/fb.modes, which can be used to set frame buffer
+	  device to pre-defined video modes.
 
 config CONFIG_FDFLUSH
 	bool "fdflush"
 	default n
 	help
-	  Please submit a patch to add help text for this item.
+	  Fdflush is only needed when changing media on slightly-broken
+	  removable media drives.  It is used to make Linux believe that a
+	  hardware disk-change switch has been actuated, which causes Linux to
+	  forget anything it has cached from the previous media.  If you have
+	  such a slightly-broken drive, you will need to run fdflush every time
+	  you change a disk.  Most people have working hardware and can safely
+	  say leave this disabled.
 
 config CONFIG_FDISK
 	bool "fdisk"
 	default n
 	help
-	  Please submit a patch to add help text for this item.
+	  The fdisk utility is used to divide hard disks into one or more
+	  logical disks, which are generally called partitions.  This utility
+	  can be used to list and edit the set of partitions or BSD style 
+	  'disk slices' that are defined on a hard drive.
 
 config CONFIG_FEATURE_FDISK_WRITABLE
 	bool "  Write support" 
 	default y
 	depends on CONFIG_FDISK
 	help
-	  Allow changes to be written to disk, without this you
-	  will only be able to view the partition table. 
+	  Enabling this option allows you to create or change a partition table
+	  and write those changes out to disk.  If you leave this option
+	  disabled, you will only be able to view the partition table.
 
 config CONFIG_FEATURE_AIX_LABEL
 	bool "  Support AIX disklabels"
 	default n
 	depends on CONFIG_FDISK && CONFIG_FEATURE_FDISK_WRITABLE  
 	help
-	  Please submit a patch to add help text for this item.
+	  Enabling this option allows you to create or change AIX disklabels.
+	  Most people can safely leave this option disabled.
 
 config CONFIG_FEATURE_SGI_LABEL
 	bool "  Support SGI disklabels"
 	default n
 	depends on CONFIG_FDISK && CONFIG_FEATURE_FDISK_WRITABLE
 	help
-	  Please submit a patch to add help text for this item.
+	  Enabling this option allows you to create or change SGI disklabels.
+	  Most people can safely leave this option disabled.
 
 config CONFIG_FEATURE_SUN_LABEL
 	bool "  Support SUN disklabels"
 	default n
  	depends on CONFIG_FDISK && CONFIG_FEATURE_FDISK_WRITABLE	
 	help
-	  Please submit a patch to add help text for this item.
+	  Enabling this option allows you to create or change SUN disklabels.
+	  Most people can safely leave this option disabled.
 
 config CONFIG_FEATURE_OSF_LABEL
 	bool "  Support BSD disklabels"
 	default n
 	depends on CONFIG_FDISK && CONFIG_FEATURE_FDISK_WRITABLE
 	help
-	  Please submit a patch to add help text for this item.
+	  Enabling this option allows you to create or change BSD disklabels
+	  and define and edit BSD disk slices.
 
 config CONFIG_FEATURE_FDISK_ADVANCED
 	bool "  Support expert mode"
 	default n
 	depends on CONFIG_FDISK && CONFIG_FEATURE_FDISK_WRITABLE
 	help
-	  Please submit a patch to add help text for this item.
+	  Enabling this option allows you to do terribly unsafe things like
+	  define arbitrary drive geometry, move the beginning of data in a
+	  partition, and similarly evil things.  Unless you have a very good
+	  reason you would be wise to leave this disabled.
 
 config CONFIG_FREERAMDISK
 	bool "freeramdisk"
 	default n
 	help
-	  Please submit a patch to add help text for this item.
+	  Linux allows you to create ramdisks.  This utility allows you to
+	  delete them and completely free all memory that was used for the
+	  ramdisk.  For example, if you boot Linux into a ramdisk and later
+	  pivot_root, you may want to free the memory that is allocated to the
+	  ramdisk.  If you have no use for freeing memory from a ramdisk, leave
+	  this disabled.
 
 config CONFIG_FSCK_MINIX
 	bool "fsck_minix"
 	default n
 	help
-	  Please submit a patch to add help text for this item.
+	  The minix filesystem is a nice, small, compact, read-write filesystem
+	  with little overhead.  It is not a journaling filesystem however and
+	  can encounted corruption if it is not properly unmounted or if the
+	  power goes off in the middle of a write.  This utility allows you to
+	  check for and attempt to repair any corruption that occurs to a minix
+	  filesystem.
 
 config CONFIG_MKFS_MINIX
 	bool "mkfs_minix"
 	default n
 	help
-	  Please submit a patch to add help text for this item.
+	  The minix filesystem is a nice, small, compact, read-write filesystem
+	  with little overhead.  If you wish to be able to create minix filesystems
+	  this utility will do the job for you.
 
 comment "Minix filesystem support"
     depends on CONFIG_FSCK_MINIX || CONFIG_MKFS_MINIX
@@ -113,57 +157,87 @@ config CONFIG_FEATURE_MINIX2
 	default y
 	depends on CONFIG_FSCK_MINIX || CONFIG_MKFS_MINIX
 	help
-	  Please submit a patch to add help text for this item.
+	  If you wish to be able to create version 2 minix filesystems, enable this.
+	  If you enabled 'mkfs_minix' then you almost certainly want to be using the
+	  version 2 filesystem support.
 
 config CONFIG_GETOPT
 	bool "getopt"
 	default n
 	help
-	  Please submit a patch to add help text for this item.
+	  The getopt utility is used to break up (parse) options in command
+	  lines to make it easy to write complex shell scripts that also check
+	  for legal (and illegal) options.  If you want to write horribly
+	  complex shell scripts, or use some horribly complex shell script
+	  written by others, this utility may be for you.  Most people will
+	  wisely leave this disabled.
 
 config CONFIG_HEXDUMP
 	bool "hexdump"
 	default n
 	help
-	  Please submit a patch to add help text for this item.
+	  The hexdump utility is used to display binary data in a readable
+	  way that is comparable to the output from most hex editors.
 
 config CONFIG_HWCLOCK
 	bool "hwclock"
 	default n
 	help
-	  Please submit a patch to add help text for this item.
+	  The hwclock utility is used to read and set the hardware clock
+	  on a system.  This is primarily used to set the correct time in
+	  the hardware close, so the hardware will keep the correct time 
+	  when Linux is _not_ running.
 
 config CONFIG_FEATURE_HWCLOCK_LONGOPTIONS
 	bool "  Support long options (--hctosys,...)"
 	default n
 	depends on CONFIG_HWCLOCK
 	help
-	  Please submit a patch to add help text for this item.
+	  By default, the hwclock utility only uses short options.  If you
+	  are overly fond of the long options, such as --hctosys, --utc, etc)
+	  then enable this option.
 
 config CONFIG_LOSETUP
 	bool "losetup"
 	default n
 	help
-	  Please submit a patch to add help text for this item.
+	  losetup is used to associate or detach a loop device with a regular
+	  file or block device, and to query the status of a loop device.  This
+	  version does not currently support enabling data encryption.
 
 config CONFIG_MKSWAP
 	bool "mkswap"
 	default n
 	help
-	  Please submit a patch to add help text for this item.
+	  The mkswap utility is used to configure a file or disk partition as
+	  Linux swap space.  This allows Linux to use the entire file or
+	  partition as if it were additional RAM, which can greatly increase
+	  the capability of low-memory machines.  This additional memory is
+	  much slower than real RAM, but can be very helpful at preventing your
+	  applications being killed by the Linux out of memory (OOM) killer.  Once
+	  you have created swap space using 'mkswap' you need to enable the swap
+	  space using the 'swapon' utility.
 
 config CONFIG_MORE
 	bool "more"
 	default n
 	help
-	  Please submit a patch to add help text for this item.
+	  More is a simple utility which allows you to read text one screen
+	  sized page at a time.  If you want to read text that is larger than
+	  the screen, and you are using anything faster than a 300 baud modem,
+	  you will probably find this utility very helpful.  If you don't have
+	  any need to reading text files, you can leave this disabled.
 
 config CONFIG_FEATURE_USE_TERMIOS
 	bool "  Use termios to manipulate the screen"
 	default y
 	depends on CONFIG_MORE
 	help
-	  Please submit a patch to add help text for this item.
+	  This option allows utilities such as 'more' and 'top' to determine
+	  the size of the screen.  If you leave this disabled, your utilities
+	  that display things on the screen with be especially primitive and
+	  will be unable to determine the current screen size, and will be
+	  unable to move the cursor.
 
 comment "Common options for ls and more"
 	depends on CONFIG_LS || CONFIG_MORE
@@ -173,31 +247,51 @@ config CONFIG_FEATURE_AUTOWIDTH
 	default y
 	depends on CONFIG_LS || CONFIG_MORE
 	help
-	  Please submit a patch to add help text for this item.
+	  This option allows utilities such as 'ls' and 'more' to determine the
+	  width of the screen, which can allow them to display additional text
+	  or avoid wrapping text onto the next line.  If you leave this
+	  disabled, your utilities will be especially primitive and will be
+	  unable to determine the current screen width.
 
 config CONFIG_PIVOT_ROOT
 	bool "pivot_root"
 	default n
 	help
-	  Please submit a patch to add help text for this item.
+	  The pivot_root utility swaps the mount points for the root filesystem
+	  with some other mounted filesystem.  This allows you to do all sorts
+	  of wild and crazy things with your Linux system and is far more
+	  powerful than 'chroot'.
 
 config CONFIG_RDATE
 	bool "rdate"
 	default n
 	help
-	  Please submit a patch to add help text for this item.
+	  The rdate utility allows you to syncronize the date and time of your 
+	  system clock with the date and time of a remote networked system using
+	  the RFC868 protocol, which is built into the inetd daemon on most
+	  systems.
 
 config CONFIG_SWAPONOFF
 	bool "swaponoff"
 	default n
 	help
-	  Please submit a patch to add help text for this item.
+	  This option enables both the 'swapon' and the 'swapoff' utilities.
+	  Once you have created some swap space using 'mkswap', you also need
+	  to enable your swap space with the 'swapon' utility.  The 'swapoff'
+	  utility is used, typically at system shutdown, to disable any swap
+	  space.  If you are not using any swap space, you can leave this
+	  option disabled.
 
 config CONFIG_MOUNT
 	bool "mount"
 	default n
 	help
-	  Please submit a patch to add help text for this item.
+	  All files and filesystems in Unix are arranged into one big directory
+	  tree.  The 'mount' utility is used to graft a filesystem onto a
+	  particular part of the tree.  A filesystem can either live on a block
+	  device, or it can be accessible over the network, as is the case with
+	  NFS filesystems.  Most people using BusyBox will also want to enable
+	  the 'mount' utility.
 
 config CONFIG_NFSMOUNT
 	bool "  Support mounting nfs file systems"
@@ -210,14 +304,18 @@ config CONFIG_UMOUNT
 	bool "umount"
 	default n
 	help
-	  Please submit a patch to add help text for this item.
+	  When you want to remove a mounted filesystem from its current mount point,
+	  for example when you are shutting down the system, the 'umount' utility is
+	  the tool to use.  If you enabled the 'mount' utility, you almost certainly
+	  also want to enable 'umount'.
 
 config CONFIG_FEATURE_MOUNT_FORCE
 	bool "  Support forced filesystem unmounting"
 	default n
 	depends on CONFIG_UMOUNT
 	help
-	  Please submit a patch to add help text for this item.
+	  This allows you to _force_ a filesystem to be umounted.  This is generally
+	  only useful when you want to get rid of an unreachable NFS system.
 
 comment "Common options for mount/umount"
 	depends on CONFIG_MOUNT || CONFIG_UMOUNT
@@ -227,14 +325,34 @@ config CONFIG_FEATURE_MOUNT_LOOP
 	default n
 	depends on CONFIG_MOUNT || CONFIG_UMOUNT
 	help
-	  Please submit a patch to add help text for this item.
+	  Enabling this feature allows mount to use the '-o' loop options,
+	  which lets you loop mount files.  Mount will automagically setup and
+	  free the necessary loop devices so you do not need to mess with the
+	  'losetup' utility unless you really want to.  This is really only useful
+	  if you plan to loop mount files.
 
 config CONFIG_FEATURE_MTAB_SUPPORT
 	bool "  Support for a real /etc/mtab (instead of /proc/mounts)"
 	default n
 	depends on CONFIG_MOUNT || CONFIG_UMOUNT
 	help
-	  Please submit a patch to add help text for this item.
+	  If your root filesystem is writable and you wish to have the 'mount'
+	  utility create an mtab file listing the filesystems which have been
+	  mounted then you should enable this option.  Most people that use
+	  BusyBox have a read-only root filesystem, so they will leave this
+	  option disabled and BusyBox will use the /proc/mounts file.
+
+config CONFIG_FEATURE_MTAB_FILENAME
+	string "  mtab file location"
+	default "/etc/mtab"
+	depends on CONFIG_FEATURE_MTAB_SUPPORT
+	help
+	  Some people have a read only root filesystem, but they also wish to
+	  have the 'mount' utility create an mtab file listing the filesystems
+	  which have been mounted.  This option allows you to specify an alternative
+	  location for the mtab file, such as /var/mtab, or /tmp/mtab.  The default
+	  value is /etc/mtab, which is where this file is located on most desktop
+	  Linux systems.
 
 endmenu