Re: Configure.help editorial policy

[Riley Williams]

Hi Dominik.

>>>>> 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?

>> I like this!

> I second this. Being a translator of the file in question, I have to
> deal with ten slightly different versions of "You may also compile
> this as a module...". So I have ten slighlty different translations
> of this text, too, in the name of accuracy.

I have to admit that I hadn't considered translators, but perhaps it
could be made even simpler for you. How about having the help file start
with a set of standard definitions, such as the following...

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

DEFINE_MODULAR
  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.

DEFINE_UNITS
  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.

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

The rules would then reduce to "If the relevant condition applies,
append the text associated with the relevant DEFINE_ symbol to the help
text to be issued" and this could be done with an additional call to the
routine to extract the appropriate help text from the file. In addition,
your translation efforts would be restricted to just the COnfigure.help
file, and you wouldn't have to tweak the various configuration scripts
at the same time - and this would also ensure that the various config
scripts all used exactly the same help text.

> Although I thought there was an agreement that decimal kilobyte is
> kB, and binary kilobyte is KiB, decimal megabyte is MB, binary
> megabyte is MiB and so on, wasn't there?

That's the standard that the IEC has defined, and what this thread is
all about. Whether it'll get anywhere remains to be seen - ask Ted T'so
about the dangers of early adoption of proposed standards, and he'll
probably explain where his surname came from...

Best wishes from Riley.