linux-kernel - Re: [RFC/PATCH] Documentation of kernel messages

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]

Date:	Wed, 13 Jun 2007 19:11:48 +0200
From:	Sam Ravnborg <sam@...nborg.org>
To:	Dave Hansen <hansendc@...ibm.com>
Cc:	holzheu@...ux.vnet.ibm.com, linux-kernel@...r.kernel.org,
	randy.dunlap@...cle.com, akpm@...l.org, gregkh@...e.de,
	mtk-manpages@....net, schwidefsky@...ibm.com,
	heiko.carstens@...ibm.com
Subject: Re: [RFC/PATCH] Documentation of kernel messages

On Wed, Jun 13, 2007 at 09:37:29AM -0700, Dave Hansen wrote:
> On Wed, 2007-06-13 at 17:06 +0200, holzheu wrote:
> > The operation of a Linux system sometimes requires to decode the
> > meaning of a specific kernel message, e.g. an error message of a
> > driver. Especially on our mainframe zSeries platform system
> > administrators want to have descriptions for Linux kernel messages.
> > They are used to that, because all other operating systems on that
> > platform like z/OS, z/VM or z/VSE have message catalogs with detailed
> > descriptions about the semantics of the messages.
> 
> I'm not sure we want to make Linux more like z/* in this regard. :)
> 
> The problem with your proposal is that every time a new message in the
> kernel is created or modified, you need somebody to go update that
> documentation.  It's going to get out-of-sync very fast if this isn't
> done, and you either need to convince and teach each and every kernel
> contributor to follow your lead, or have a team of highly trained code
> monkeys to watch git-commits and resubmit documentation for every diff
> that touches a printk. 

This is no more and no less the same situation that we have with
the kernel-doc documented functions/data in the kernel.

I like the concept that the description is kept close to the actual
usage, the tool support and that in general looks like ordinary
kernel-doc documentation.

And if people do not dare to update the kernel-doc documentation of
a function then maybe they should not send patches in first place..

If we then really want to have the important printk's documented
is another story.

	Sam
-
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/