Re: Configure.help editorial policy

Riley Williams
2001-12-26T18:11:04Z

Hi Eric, Rik.

>> I take it this is your way of volunteering to always keep all
>> kernel documentation accurate as well as answer questions from
>> newbies who've never seen 'KiB' before ? ;)

> One of the arguments for the KiB declaration, despite the ugliness
> of "kibibytes", is that a newbie seeing "32KiB" is quite likely to
> deduce what's meant from context. Let's not exaggerate the
> difficulties here.

Alternatively, deal with this problem the same way the "This may also be
built as a module..." comment is - either include it several thousand
times in Configure.help or (better still) have the configuration tools
spit it out automatically every time the need for it crops up. The
following ruleset could easily be implemented even in the `make config`
and `make menuconfig` parsers, and should be just as easy in CML2.
Applying rule (1) will result in a considerable reduction in the size of
the file Documentation/Configure.help as it currently stands.

Comments, anybody?

Best wishes from Riley.

===============8<=============== CUT ===============>8===============

RULE 1: If a particular symbol is defined using a command that
allows it to be selected as "Modular", then tack the
following to the end of the help description for that
symbol when a user requests help:

This driver is also available as a module( = code
which can be inserted in and removed from the
running kernel whenever you want). If you want to
compile it as a module, say M here and read
Documentation/modules.txt in the kernel source.

RULE 2: If the help text for a particular symbol includes a word
matching either of the egrep patterns '[KkMmGgTt][Bb]' or
'[KkMmGgTt]i[Bb]' then tack the following to the end of
the help description for that symbol when a user requests
help:

Differing standards are used for the numeric
designators in the computing and engineering
worlds. For the purposes of this document, the
following designators are used with the stated
values:

Symbol Designation Number of Bytes
~~~~~~ ~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~
KiB Decimal Kilobyte 1,000
KB Binary Kilobyte 1,024

MiB Decimal Megabyte 1,000,000
MB Binary Megabyte 1,048,576

GiB Decimal Gigabyte 1,000,000,000
GB Binary Gigabyte 1,073,741,824

TiB Decimal Terabyte 1,000,000,000,000
TB Binary Terabyte 1,099,511,627,776

This difference has arisen as a direct consequence of
the fact that computers naturally talk in a binary
(base 2) number system rather than the decimal (base
10) system preferred by mere mortals.

RULE 3: If more than one of the above rules apply, all configuration
systems shall agree on a common order in which to apply them.