linux-kernel - Re: Documentation of kernel messages (Summary)

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-Id: <1184156116.11139.9.camel@localhost.localdomain>
Date:	Wed, 11 Jul 2007 14:15:16 +0200
From:	Michael Holzheu <holzheu@...ux.vnet.ibm.com>
To:	Rob Landley <rob@...dley.net>
Cc:	Gerrit Huizenga <gh@...ibm.com>, "H. Peter Anvin" <hpa@...or.com>,
	"Kunai, Takashi" <kunai@...ux-foundation.jp>,
	Andrew Morton <akpm@...ux-foundation.org>,
	linux-kernel@...r.kernel.org,
	lf_kernel_messages@...ux-foundation.org, mtk-manpages@....net,
	jack@...e.cz, randy.dunlap@...cle.com, gregkh@...e.de,
	pavel@....cz, tim.bird@...sony.com, arjan@...radead.org,
	sam@...nborg.org, jengelh@...putergmbh.de, joe@...ches.com,
	auke-jan.h.kok@...el.com, hansendc@...ibm.com, davem@...emloft.net,
	Valdis.Kletnieks@...edu, kenistoj@...ibm.com,
	schwidefsky@...ibm.com, heiko.carstens@...ibm.com,
	linux-doc@...r.kernel.org
Subject: Re: Documentation of kernel messages (Summary)

Hi Rob,

On Tue, 2007-07-10 at 12:12 -0400, Rob Landley wrote:

[snip]

> > Yeah, but it seems like having a translations directory in the kernel
> > avoids that problem - anyone can update, it is a single source, no digging
> > for sites that aren't tied to the kernel, available in the distros
> > directly, etc.
> 
> No.  It doesn't help.
> 
> 99% of the kernel directory is C.  That means any random passerby can review 
> code.  Everyone who has the kernel tarball should be able to review code 
> that's in there, plus when you compile it breaks.  So merging _code_ into the 
> kernel helps keep it up to date.
> 
> Merging documentation into the kernel doesn't help keep it up to date, because 
> documentation being out of date doesn't break the build.  It may get the 
> documentation more review, but the existing state of Documentation/* argues 
> against that.  It's a struggle to keep the english versions on the same 
> continent as "up to date" or "complete", and most of the _good_ documentation 
> is out in OLS papers and such (which I'm off indexing as we speak).

With the checker tool, which we suggested in the initial proposal, it is
possible to verify

 * that every marked message has a description
 * that there are no descriptions without corresponding messages
 * that format strings of message and description match

So when compiling the kernel using C=1, you will at least see warnings,
when a message has changed or a message disappeared:

>> make modules C=1
  CHK     include/linux/version.h
  CHK     include/linux/utsrelease.h
  CHECK   drivers/kmsgtest/kmsgtest.c
drivers/kmsgtest/kmsgtest.c: Missing description for: kmsgtest.1
drivers/kmsgtest/kmsgtest.c: Description without message for: kmsgtest.3

Michael



-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@...r.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/