Improve init/Kconfig help descriptions [PATCH 1/9]

[Nick Andrew]

On Wed, Feb 20, 2008 at 01:06:09AM +1100, Nick Andrew wrote:
> Here is a series of 9 patches to init/Kconfig intended to improve the
> usefulness and consistency of the help descriptions. The patches are
> against linux-2.6.24.2.
> [...]
> Patch 1
> 	EXPERIMENTAL
> 	LOCALVERSION
> 	LOCALVERSION_AUTO
> 	SWAP
> 	SYSVIPC
> 	POSIX_MQUEUE
> 	BSD_PROCESS_ACCT
> 	BSD_PROCESS_ACCT_V3

Changelog:

Improve usefulness and consistency of kernel configuration help messages.

Signed-off-by: Nick Andrew <nick@xxxxxxxxxxxxxxx>
 
--- a/init/Kconfig	2008-02-20 00:45:07.000000000 +1100
+++ b/init/Kconfig	2008-02-20 00:52:07.000000000 +1100
@@ -12,33 +12,45 @@ menu "General setup"
 config EXPERIMENTAL
 	bool "Prompt for development and/or incomplete code/drivers"
 	---help---
-	  Some of the various things that Linux supports (such as network
-	  drivers, file systems, network protocols, etc.) can be in a state
-	  of development where the functionality, stability, or the level of
-	  testing is not yet high enough for general use. This is usually
-	  known as the "alpha-test" phase among developers. If a feature is
-	  currently in alpha-test, then the developers usually discourage
-	  uninformed widespread use of this feature by the general public to
-	  avoid "Why doesn't this work?" type mail messages. However, active
-	  testing and use of these systems is welcomed. Just be aware that it
-	  may not meet the normal level of reliability or it may fail to work
-	  in some special cases. Detailed bug reports from people familiar
-	  with the kernel internals are usually welcomed by the developers
-	  (before submitting bug reports, please read the documents
-	  <file:README>, <file:MAINTAINERS>, <file:REPORTING-BUGS>,
-	  <file:Documentation/BUG-HUNTING>, and
-	  <file:Documentation/oops-tracing.txt> in the kernel source).
+	  This option enables you to choose kernel configuration
+	  options labeled as EXPERIMENTAL.
+
+	  Some of the various things that Linux supports (such as
+	  network drivers, file systems, network protocols, etc.) can
+	  be in a state of development where the functionality,
+	  stability, or the level of testing is not yet high enough
+	  for general use. This is usually known as the "alpha-test"
+	  phase among developers.
+
+	  If a feature is currently in alpha-test, then the
+	  developers usually discourage uninformed widespread use of
+	  this feature by the general public to avoid "Why doesn't
+	  this work?" type email messages. However, active testing
+	  and use of these systems is welcomed. Just be aware that
+	  it may not meet the normal level of reliability or it
+	  may fail to work in some special cases.
+
+	  Detailed bug reports from people familiar with
+	  the kernel internals are usually welcomed by the
+	  developers. Before submitting bug reports, please
+	  read the documents <file:README>, <file:MAINTAINERS>,
+	  <file:REPORTING-BUGS>, <file:Documentation/BUG-HUNTING>,
+	  and <file:Documentation/oops-tracing.txt> in the kernel
+	  source.
 
 	  This option will also make obsoleted drivers available. These are
 	  drivers that have been replaced by something else, and/or are
 	  scheduled to be removed in a future kernel release.
 
-	  Unless you intend to help test and develop a feature or driver that
-	  falls into this category, or you have a situation that requires
-	  using these features, you should probably say N here, which will
-	  cause the configurator to present you with fewer choices. If
-	  you say Y here, you will be offered the choice of using features or
-	  drivers that are currently considered to be in the alpha-test phase.
+	  Unless you intend to help test and develop a feature or driver
+	  that falls into this category, or you have a situation that
+	  requires using these features, you should probably say N here,
+	  which will cause the configurator to present you with fewer
+	  choices. If you say Y here, you will be offered the choice of
+	  using features or drivers that are currently considered to be
+	  in the alpha-test phase.
+
+	  If unsure, say N.
 
 config BROKEN
 	bool
@@ -66,11 +78,18 @@ config LOCALVERSION
 	string "Local version - append to kernel release"
 	help
 	  Append an extra string to the end of your kernel version.
-	  This will show up when you type uname, for example.
-	  The string you set here will be appended after the contents of
-	  any files with a filename matching localversion* in your
-	  object and source tree, in that order.  Your total string can
-	  be a maximum of 64 characters.
+	  This will show up when you type "uname -r", for example.
+
+	  If you have any files with names matching "localversion*"
+	  in your object or source trees, then the contents of these
+	  files will be appended to your kernel version name.
+
+	  The strings are appended from the object tree files and
+	  then the source tree files, then any string specified
+	  by CONFIG_LOCALVERSION_AUTO below, and finally the value
+	  specified here.
+
+	  The maximum length of a kernel version name is 64 characters.
 
 config LOCALVERSION_AUTO
 	bool "Automatically append version information to the version string"
@@ -85,38 +104,47 @@ config LOCALVERSION_AUTO
 	  appended after any matching localversion* files, and after the value
 	  set in CONFIG_LOCALVERSION.
 
-	  (The actual string used here is the first eight characters produced
+	  The actual string used here is the first eight characters produced
 	  by running the command:
 
 	    $ git rev-parse --verify HEAD
 
-	  which is done within the script "scripts/setlocalversion".)
+	  which is done within the script "scripts/setlocalversion".
 
 config SWAP
 	bool "Support for paging of anonymous memory (swap)"
 	depends on MMU && BLOCK
 	default y
 	help
-	  This option allows you to choose whether you want to have support
-	  for so called swap devices or swap files in your kernel that are
-	  used to provide more virtual memory than the actual RAM present
-	  in your computer.  If unsure say Y.
+	  This option allows you to choose whether you want to have
+	  support for swap devices or swap files in your kernel.
+
+	  Swap is used to provide more virtual memory than the
+	  actual RAM present in your computer. This can improve
+	  performance by moving less frequently used blocks of
+	  memory onto disk, which frees it up for improved disk
+	  caching or active processes.
+
+	  If unsure, say Y.
 
 config SYSVIPC
 	bool "System V IPC"
 	---help---
-	  Inter Process Communication is a suite of library functions and
+	  Inter-Process Communication is a suite of library functions and
 	  system calls which let processes (running programs) synchronize and
 	  exchange information. It is generally considered to be a good thing,
-	  and some programs won't run unless you say Y here. In particular, if
-	  you want to run the DOS emulator dosemu under Linux (read the
-	  DOSEMU-HOWTO, available from <http://www.tldp.org/docs.html#howto>),
-	  you'll need to say Y here.
+	  and some programs won't run without it.
+
+	  In particular, if you want to run the DOS emulator dosemu
+	  under Linux, you'll need to say Y here. You can find out
+	  more about dosemu at <http://dosemu.sourceforge.net/>
 
 	  You can find documentation about IPC with "info ipc" and also in
 	  section 6.4 of the Linux Programmer's Guide, available from
 	  <http://www.tldp.org/guides.html>.
 
+	  If unsure, say Y.
+
 config SYSVIPC_SYSCTL
 	bool
 	depends on SYSVIPC
@@ -127,42 +155,69 @@ config POSIX_MQUEUE
 	bool "POSIX Message Queues"
 	depends on NET && EXPERIMENTAL
 	---help---
-	  POSIX variant of message queues is a part of IPC. In POSIX message
-	  queues every message has a priority which decides about succession
-	  of receiving it by a process. If you want to compile and run
-	  programs written e.g. for Solaris with use of its POSIX message
-	  queues (functions mq_*) say Y here.
-
-	  POSIX message queues are visible as a filesystem called 'mqueue'
-	  and can be mounted somewhere if you want to do filesystem
-	  operations on message queues.
+	  POSIX Message Queues is a type of Inter-Process Communication
+	  (IPC). It provides similar functionality to System V message
+	  queues, with a different Application Programming Interface (API).
+
+	  In POSIX Message Queues, every message has a priority which
+	  determines the order in which each message is delivered to a
+	  receiving process. See mq_overview(7) for details of the
+	  API (functions mq_*).
+
+	  When POSIX Message Queues are enabled, a directory appears
+	  called /proc/sys/fs/mqueue which can be used to tune kernel
+	  parameters. See mq_overview(7) for details.
+
+	  POSIX Message Queues can also be mounted as a filesystem
+	  called 'mqueue', for example: "mount -t mqueue none /mqueue".
 
 	  If unsure, say Y.
 
 config BSD_PROCESS_ACCT
 	bool "BSD Process Accounting"
 	help
-	  If you say Y here, a user level program will be able to instruct the
-	  kernel (via a special system call) to write process accounting
-	  information to a file: whenever a process exits, information about
-	  that process will be appended to the file by the kernel.  The
-	  information includes things such as creation time, owning user,
-	  command name, memory usage, controlling terminal etc. (the complete
-	  list is in the struct acct in <file:include/linux/acct.h>).  It is
-	  up to the user level program to do useful things with this
-	  information.  This is generally a good idea, so say Y.
+	  BSD Process Accounting enables the kernel to write process
+	  accounting information to a file to track system resources
+	  utilisation and some user actions.
+
+	  Whenever a process exits, information about that process
+	  will be appended to the file. This includes things such as
+	  creation time, owning user, command name, memory usage,
+	  controlling terminal, etc.
+
+	  See sa(1), accton(8) and acct(2) for more details, also
+	  <file:include/linux/acct.h> (struct acct) for the complete
+	  list of stored data.
+
+	  You probably only need this if you have multiple users and
+	  you want to monitor or account for their system usage, and
+	  fine-tune system performance through analysis of the logfile.
+
+	  If unsure, say N.
 
 config BSD_PROCESS_ACCT_V3
 	bool "BSD Process Accounting version 3 file format"
 	depends on BSD_PROCESS_ACCT
 	default n
 	help
-	  If you say Y here, the process accounting information is written
-	  in a new file format that also logs the process IDs of each
-	  process and it's parent. Note that this file format is incompatible
-	  with previous v0/v1/v2 file formats, so you will need updated tools
-	  for processing it. A preliminary version of these tools is available
-	  at <http://www.physik3.uni-rostock.de/tim/kernel/utils/acct/>.
+	  BSD Process Accounting enables the kernel to write process
+	  accounting information to a file to track system resources
+	  utilisation and some user actions.
+
+	  Version 3 is a new file format that also logs the process
+	  ID and process parent ID.
+
+	  Note that this file format is incompatible with previous
+	  v0/v1/v2 file formats, so you will need updated tools
+	  for processing it. One such tool is "bootchart", and
+	  the GNU "acct" package should be able to read the v3
+	  file format too.
+
+	  You probably only need this if you have multiple users and
+	  you want to monitor or account for their system usage, and
+	  fine-tune system performance through analysis of the logfile.
+
+	  If unsure, say N.
 
 config TASKSTATS
 	bool "Export task/process statistics through netlink (EXPERIMENTAL)"
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/