LKML Archive on lore.kernel.org
help / color / mirror / Atom feed
From: Nick Andrew <nick@nick-andrew.net>
To: trivial@kernel.org
Cc: linux-kernel@vger.kernel.org
Subject: Improve init/Kconfig help descriptions [PATCH 1/9]
Date: Wed, 20 Feb 2008 01:09:40 +1100	[thread overview]
Message-ID: <20080219140940.GA26697@tull.net> (raw)
In-Reply-To: <20080219140609.GA26619@tull.net>

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@nick-andrew.net>
 
--- 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)"

  reply	other threads:[~2008-02-19 14:17 UTC|newest]

Thread overview: 50+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2008-02-19 14:06 Improve init/Kconfig help descriptions [PATCH 0/9] Nick Andrew
2008-02-19 14:09 ` Nick Andrew [this message]
2008-02-19 14:11 ` Improve init/Kconfig help descriptions [PATCH 2/9] Nick Andrew
2008-02-19 14:33 ` Improve init/Kconfig help descriptions [PATCH 3/9] Nick Andrew
2008-02-19 14:42   ` Pavel Emelyanov
2008-02-19 15:10     ` Nick Andrew
2008-02-19 15:16       ` Pavel Emelyanov
2008-02-19 15:50         ` Serge E. Hallyn
2008-02-19 16:44         ` Randy Dunlap
2008-02-19 22:41           ` Nick Andrew
2008-02-20 12:19           ` [PATCH 2.6.25-rc2 3/9] config: Improve init/Kconfig help descriptions - namespaces Nick Andrew
2008-02-20 12:23             ` Pavel Emelyanov
2008-02-20 13:01               ` Nick Andrew
2008-02-20 13:07                 ` Pavel Emelyanov
2008-02-20 16:50             ` serge
2008-02-20 23:10               ` Nick Andrew
2008-02-19 14:38 ` Improve init/Kconfig help descriptions [PATCH 4/9] Nick Andrew
2008-02-20  3:42   ` Valdis.Kletnieks
2008-02-20 22:17     ` Nick Andrew
2008-02-19 14:53 ` Improve init/Kconfig help descriptions [PATCH 5/9] Nick Andrew
2008-02-19 20:17   ` Randy Dunlap
2008-02-19 15:12 ` Improve init/Kconfig help descriptions [PATCH 6/9] Nick Andrew
2008-02-19 15:39   ` Paul Jackson
2008-02-20 12:41     ` Nick Andrew
2008-02-20 16:43       ` Paul Jackson
2008-02-20  2:04   ` Paul Menage
2008-02-20  2:54     ` Nick Andrew
2008-02-20  3:12       ` Paul Menage
2008-02-20 16:55       ` serge
2008-02-20 21:31         ` Nick Andrew
2008-02-19 15:15 ` Improve init/Kconfig help descriptions [PATCH 7/9] Nick Andrew
2008-02-19 15:21 ` Improve init/Kconfig help descriptions [PATCH 8/9] Nick Andrew
2008-02-19 15:27 ` Improve init/Kconfig help descriptions [PATCH 9/9] Nick Andrew
2008-02-20 22:33 ` [PATCH 2.6.25-rc2 1/9] init: Improve init/Kconfig help descriptions part 1 Nick Andrew
     [not found] ` <200802220014.m1M0Dh5r022354@rgminet03.oracle.com>
2008-02-22  0:19   ` [PATCH 2.6.25-rc2 5/9] Kconfig: Improve init/Kconfig help descriptions - IKCONFIG etc Randy Dunlap
2008-02-22  0:48 ` [PATCH 2.6.25-rc2 1/9] Kconfig: Improve init/Kconfig help descriptions part 1 Nick Andrew
2008-02-22  0:49 ` [PATCH 2.6.25-rc2 2/9] Kconfig: Improve init/Kconfig help descriptions - TASKSTATS Nick Andrew
2008-02-22  0:51 ` [PATCH 2.6.25-rc2 3/9] Kconfig: Improve init/Kconfig help descriptions - NAMESPACES Nick Andrew
2008-02-27 23:00   ` Nick Andrew
2008-02-27 23:08     ` Serge E. Hallyn
2008-02-22  0:52 ` [PATCH 2.6.25-rc2 4/9] Kconfig: Improve init/Kconfig help descriptions - AUDIT Nick Andrew
2008-02-22  0:54 ` [PATCH 2.6.25-rc2 5/9] Kconfig: Improve init/Kconfig help descriptions - IKCONFIG etc Nick Andrew
2008-02-22  0:55 ` [PATCH 2.6.25-rc2 6/9] Kconfig: Improve init/Kconfig help descriptions - CGROUPS Nick Andrew
2008-02-22  0:56 ` [PATCH 2.6.25-rc2 7/9] Kconfig: Improve init/Kconfig help descriptions - EMBEDDED etc Nick Andrew
2008-02-22  0:58 ` [PATCH 2.6.25-rc2 8/9] Kconfig: Improve init/Kconfig help descriptions - SLAB Nick Andrew
2008-02-22  0:59 ` [PATCH 2.6.25-rc2 9/9] Kconfig: Improve init/Kconfig help descriptions - MODULES Nick Andrew
     [not found] ` <200802220010.m1M0Arr7024044@vzorg.swsoft.net>
2008-02-22  8:14   ` [PATCH 2.6.25-rc2 3/9] Kconfig: Improve init/Kconfig help descriptions - NAMESPACES Pavel Emelyanov
     [not found] ` <200802220010.m1M0Auqn024414@e5.ny.us.ibm.com>
2008-02-22 22:14   ` Serge E. Hallyn
2008-02-23  1:12     ` Nick Andrew
2008-02-23  3:45       ` Serge E. Hallyn

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20080219140940.GA26697@tull.net \
    --to=nick@nick-andrew.net \
    --cc=linux-kernel@vger.kernel.org \
    --cc=trivial@kernel.org \
    --subject='Re: Improve init/Kconfig help descriptions [PATCH 1/9]' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).