Re: [Lf_kernel_messages] Re: Documentation of kernel messages (Summary)

[Theodore Tso <tytso@mit.edu>]

On Mon, Jun 25, 2007 at 11:44:45AM -0400, Rob Landley wrote:
> Personally?  No to the second question, which renders the first "do it 
> yourself outside of the tree".
> 
> Just a guess, and I don't speak for anyone else here, but I think most of us 
> are waiting to see how long it takes you to lose interest.

Actually, at a brainstorming session at the recent Linux Foundation
collaboration summit, there were a number of kernel developers,
including James Bottomley, Greg K-H, Cristoph Hellwig (I think), and
others, who were actually generally symapthetic to the idea, if done
right.

The idea that was tossed about was essentially printk hashes (hashed
on message plus filename, with optional reporting of filename+line
number), with the messaging catalog being maintained externally.  Yes,
that will be a major pain for whoever wants to do the translation ---
but it puts the onus on the people who would be getting the value for
this to do the work.

The other idea that was tossed about was that for subsystems that are
using structured reporting (i.e., dev_printk, and sdev_printk in the
SCSI subsystem --- guess who suggested that :-), that there is an
opportunity to push a lot more information out to userspace for people
who want to use this facility to more easily determine when something
has bad happened to a particular disk device, for example.  This goes
a little a beyond the original stated desire for translation support,
but it was another idea to explore.

> I find "document messages" to be a horrible idea conceptually, because I think 
> the messages should _be_ documentation.  If the message is unclear it should 
> be clarified.  "There's too much garbage on the floor, we should laminate it 
> so we can't smell it anymore."  Er, no...

There are two separable desires being addressed here.  The first is
"cute" messages such as "lp0: on fire".  Yes, maybe those should be
fixed, but sometimes kernel developers *like* cute messages.  (Sniff,
I'm pretty sure there used to be a "eaten by a grue" printk, but it
doesn't seem to be there any more.  :-) Fixing these is largely a
political problem: "of course printer on fire makes sense".

The second desire is where people want entire paragraphs discsusing
possible causes of the messages and recommended responses to be
carried out by the data center's 3rd shift operations guy (aka "tape
monkey").  That's not something you *ever* want to put in the kernel,
and who ever compiles such a long document will probably sell it for
$$$ as significant value add.  Which is fine, because it is going to
cost a lot of $$$ to keep it up to date.  :-)

> > printk hashes:
> > - Additional preprocessor step needed
> 
> Only for you guys.  Those of us building our own kernels and NOT translating 
> them or producing "the big book of explanations of kernel messages for IBM 
> customers who don't understand them" shouldn't have to run this preprocessor 
> step.

Yep, I suspect it will only be used by distro kernels.  I probably
wouldn't turn it on myself.  :-)

> > - Hard to keep printks and descriptions up-to-date. If using hashes,
> >   each typo fix in a printk breaks the link to your documentation.
> > - Since the developer knows the meaning of a printk best, he probably
> >   would be the right person to write the description.
> 
> Imposing additional requirements on developers isn't going to work unless you 
> reject patches from developers who don't follow your procedures and submit 
> the appropriately filled-out forms with each patch for processing by the 
> central bureaucracy.

Yep, it's going to be up to the translators to keep the message
catalogs up to date.  The gettext folks have figured out ways of doing
fuzzy string matches, and so if you keep the external database of
filename, line #, string, hash, and translation(s), when you go to new
version of the kernel, it's not that hard to make the fuzzy
translations work.

	       	       	    	     - Ted