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 0/9]
Date: Wed, 20 Feb 2008 01:06:09 +1100	[thread overview]
Message-ID: <20080219140609.GA26619@tull.net> (raw)


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.

Rationale:

Even though I've been using Unix for 20+ years, I find it sometimes
daunting to configure a linux kernel. The help descriptions supplied
sometimes help, and sometimes they do not.


The problems I can see with the supplied help descriptions fall into
these areas:

  - Uses arcane terminology which only kernel developers can understand

  - Inconsistently describes safe response (if unsure, ...)

  - References out-of-date external resources (404 error)

  - Description has not kept pace with recent kernel changes or standards

  - Poor grammar or layout.


My approach to improving the descriptions is to go through each option
checking the correctness of the description, validating any references
it makes, finding inconsistency with the rest of the kernel config,
and trying to improve the usefulness of the explanation. I want to
end up with:

  1 - Single sentence summary of what the option does

  2 - Explain terminology or situation if necessary and possible, linking
  to validated information sources (Documentation directory, manpages,
  scripts, URLs, Wikipedia)

  3 - Suggest safe answer for people who just don't know what to do.

The patches are in 9 parts because I wouldn't want to overwhelm any
reviewers, and also because I might have got some of them wrong. I
learned some cool things while researching these kernel options, like
what POSIX message queues are, and about the SLAB allocator, but my
grasp of cgroups and cpusets is tenuous at best. Here's a list of
the patches and the affected config options:

Patch 1
	EXPERIMENTAL
	LOCALVERSION
	LOCALVERSION_AUTO
	SWAP
	SYSVIPC
	POSIX_MQUEUE
	BSD_PROCESS_ACCT
	BSD_PROCESS_ACCT_V3

Patch 2
	TASKSTATS
	TASK_DELAY_ACCT
	TASK_XACCT
	TASK_IO_ACCOUNTING

Patch 3
	USER_NS
	PID_NS

Patch 4
	AUDIT
	AUDITSYSCALL

Patch 5
	IKCONFIG
	IKCONFIG_PROC
	LOG_BUF_SHIFT
	SYSFS_DEPRECATED
	RELAY
	BLK_DEV_INITRD

Patch 6
	CGROUPS
	CGROUP_DEBUG
	CPUSETS
	FAIR_GROUP_SCHED
	FAIR_CGROUP_SCHED
	CGROUP_CPUACCT
	PROC_PID_CPUSET

Patch 7
	EMBEDDED
	SYSCTL_SYSCALL
	KALLSYMS
	KALLSYMS_ALL
	KALLSYMS_EXTRA_PASS
	HOTPLUG
	PRINTK
	BUG
	ELF_CORE
	BASE_FULL
	FUTEX
	EPOLL
	SIGNALFD
	TIMERFD
	EVENTFD

Patch 8
	SLUB_DEBUG
	SLAB
	SLUB
	SLOB

Patch 9
	MODULES
	MODULE_UNLOAD
	MODULE_FORCE_UNLOAD
	MODVERSIONS
	MODULE_SRCVERSION_ALL
	KMOD

Changelog:

Improve usefulness and consistency of kernel configuration help messages.

Signed-off-by: Nick Andrew <nick@nick-andrew.net>
-- 
PGP Key ID = 0x418487E7                      http://www.nick-andrew.net/
PGP Key fingerprint = B3ED 6894 8E49 1770 C24A  67E3 6266 6EB9 4184 87E7

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

Thread overview: 50+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2008-02-19 14:06 Nick Andrew [this message]
2008-02-19 14:09 ` Improve init/Kconfig help descriptions [PATCH 1/9] Nick Andrew
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=20080219140609.GA26619@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 0/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).