Greetings,
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.
In general we think, that also for Linux it is a good thing to have

documentation for the most important kernel/driver messages. Even

kernel hackers not always are aware of the meaning of kernel messages

for components, which they don't know in detail. Most of the messages

are self explaining but sometimes you get something like "Clocksource

tsc unstable (delta = 7304132729 ns)" and you wonder if your system is

going to explode.
Unfortunately currently there is no general infrastructure in the Linux

kernel for the documentation of messages. I worked on a proposal, how

that could be implemented in an easy way using the already existing

kernel-doc infrastructure and using printk. The proposal is as follows
1. We use message identifiers in order to map messages to message

descriptions. A message identifier consists out of a component name and

within that component unique message number.
2. Messages and message descriptions are maintained together in the

kernel sources in order to keep them up to date. Messages catalog are

generated automatically for exactly one kernel level.
3. A special tool checks, if messages are not documented or if there

are message descriptions without corresponding messages.
4. We use the already existing kernel-doc tool to generate an online

message catalog or e.g. a pdf for offline documentation.
Current prototype implementation:

================================= 
The structure of a kernel message is: <component>.<msg number>: <msg>
* component: Name of the kernel or driver ...
[ message continues ]

I think my general response to something like this, if it goes

in, would be to stop emitting useful kernel log messages

in the code I write because having to document it too on top

of that is just too much extra work to be worthwhile.

-

Nobody will force you to document your messages. As I said, there is no

need to document self-explaining printks.
Michael
-

Your proposal is similar to one I made to some Japanese developers

earlier this year.  I was more modest, proposing that we
- add an enhanced printk
	xxprintk(msgid, KERN_ERR "some text %d\n", some_number);
- An externally managed database will provide translations, diagnostics,

  remedial actions, etc, keyed off the msgid string
- Format and management of the msgid hasn't been clearly identified yet

  as far as I know.  But all we really need is that each ID be unique,

  kernel-wide.  We develop a simple tool which can check the whole tree

  for duplicated msgids.
- From a practical day-to-day POV what this means is that a person

  from the kernel-messages team will prepare a patch for your driver

  which adds the msgids and you the driver author should take care not

  to break the tagging.
  This is deliberately designed to be minimum-impact upon general

  developers.  We want a system in place where driver/fs/etc developers

  can concentrate on what they do, and kernel-message developers can

  as independently as possibe take care of what _they_ do.
- A project has started up and there is a mailing list (cc'ed here) and

  meetings are happening at the LF collaboration summit this week.
  Please see https://lists.linux-foundation.org/mailman/listinfo/lf_kernel_messages

  and don't miss the next conference call ;)
  (argh.  The lf_kernel_messages archives are subscriber-only and it could be that

-

Hi all,
Any idea, how to proceed with this topic? Do you think that any of the

suggested solutions for documentation / translation of kernel messages

will have a chance to be included in the kernel?
I tried to summarize the outcome of this discussion...
There are two main issues:
* Translate messages

* Document messages
For both, we have to give messages identifiers in order to match them

to the corresponding documentation / translation. Three possible

solutions have been suggested:
1. Use message numbers maintained by driver owners

2. Automatically create hashes for printks

3. Use printk format string as message identifier
Regarding the question where to put documentation and translations we

have two options:
* In the kernel tree

* Somewhere outside the kernel tree
Another issue of the discussion was the usage of the component name for

printks.
Useful comments:

================

Andrew Morton:

Suggested an alternative approach using a new printk function with

message ID parameter. Documentation / Translation should be done

outside the kernel.
Gerrit Huizenga:

Suggested an alternative approach using hashes as message IDs.
Greg Kroah-Hartman:

He pointed out, that we need a solution which integrates dev_xxx()

macros.
Randy Dunlop:

He doesn't want to have message documentation included in the

kernel-doc tool. We should create new tool for kernel messages.
Pavel Machek:

Suggested to use gettext for message documentation / translation.
Useful links:

=============

There already exists a mailing list for the kernel messages topic:

https://lists.linux-foundation.org/mailman/listinfo/lf_kernel_messages
There was an LWN article summarizing some aspects of the discussion:

http://lwn.net/Articles/238948/
Pros and Cons of the different Message ID methods:

==================================================

Message numbers maintained by driver owners:

+ Unique IDs

+ Can be kept stable between different kernel versions

+ Efficient way of matching pri...
[ message continues ]

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 
I'm somewhat sympathetic to translation (although I tend to think of it as a

distro's job, and still wonder why IBM is pushing this directly rather than

trying to bounce it off Red Hat or somebody).  But you could put a sed filter

around dmesg to give you swahili output entirely in userspace.  Have you

shown the simple approach to be insufficient yet?
Is "document messages" the same problem as "translate messages", or are these

two different problems conflated together?
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 
#2 has the advantage that you can do it without buy-in from the community, and

without touching the code.  (Of course it doesn't necessarily help you if the

printk string is "%s:%s".)
But I'm still convinced you could tackle over 90% of the problem from 
Will at best only ever be done for some drivers, not all.  But that's probably 
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 
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.
Signed-off-by works because A) Linus enforces it, B) The overhead's very low,

C) attribution is already highly good thing within our community values, D)

it annoys SCO.
The javadoc function comments in the source don't have complete coverage and

probably never will (although ...
[ message continues ]

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,
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
Yep, I suspect it will only be used by distro kernels.  I probably...
[ message continues ]

Sounds good to me.
Rob

--

"One of my most productive days was throwing away 1000 lines of code."

  - Ken Thompson.

-

The tools can extract the strings if marked _() which is easy work to do

and you usually only want to hit a subset of strings anyway [the ones

that occur usually].
Having implemented an encheferizer in a much older kernel its worth it

even for the humour value of a valspeak kernel (plus some people will

never be happy until it says things like
SYS-E-FOO: Incorrect operating system in use

-

If that is the opinion of the majority here, fine. If there is no hard

rule on how to define printk macros, one option for us would be to

define some new s390 specific printk macros for our device drivers.

Similar to hundreds of other driver specific printk macros in the
Michael
-

Hi Micheal,
This is a late response to your summary below.
First of all, there is a lot of interest in this issue among Japanese

vendor community. Recently, I have built a Japanese mailing list to

discuss this issue. I'm posting this comment resulting from such discussion.
(1) Your kernel development proposal will be greatly supported by

Japanese vendor community. At the same time, it needs support from the

kernel communities, as well.

(2) As for message ID's, you proposed 3 ways; (a)adding message numbers,

(b)printk hashes and (c)Format strings. (a) seems difficult to get

supports from kernel developers and (c) lacks uniqueness of each

message. Though (b) also lacks uniqueness, adding component id and/or

file name (files name could be hashed, as well), it could achieve some

practical level of uniqueness. To avoid ugly message format, it could be

possible to introduce a system parameter to suppress this hash ids.

Thus, our preference is (b).

(3) As for a documentation file, outside of kernel source tree would be

fine.

(4) When this kernel message scheme become feasible, it will be needed

to talk about the standardized contents of each description

(meanings/actions/etc).
Takashi Kunai

--

Kunai, Takashi

The Linux Foundation Japan (New since '07/2/5)

Shibuya Mark City West 22nd Floor

1-12-1 Dogenzaka,Shibuya-ku,Tokyo,Japan

zip150-0043 tel+81-3-4360-5493
-

We have generators for hash functions that guarantee unique results

for a set of inputs. They are even GPLed. As you are operating against

a known target, that should work.
	Regards

		Oliver

-

Right, perfect hash generators require the input set to be known
But, I'm not sure they'd be operating against a known target -- I don't

really know what exactly would be hashed, but if it's kernel printk()

messages (the format string, obviously), then please remember that

new messages would get added all the time, and unless we're also

willing to change the hash function every time a printk() gets added

to the kernel (whew!) it's going to be a problem -- especially because

we don't really want to generate new hash functions for every kernel

version / or for every kernel build, because we'd obviously like the

same error message to hash to the same value across versions.
If we really care about uniqueness, the only solution I see is to use

a strong/cryptographic hash function (say SHA-1, which would never

change in the future) that generates the hashes for all the printk()

messages that are getting compiled-in at build-time ... but it would be

slow, of course.
Satyam

-

I suggest exactly that you build a new hash function for every build.

Nothing but your translating demon need ever see it. We build a new

System.map every time and it doesn't hurt.
	Regards

		Oliver
-

There is a very strong reason for the kernel community to NOT support

this: it makes it much harder to deal with bug reports.
Like it or not, English is a lingua franca[1] of the technology

industry.  When I deal with the rest of the kernel community, I use

English, instead of my native language (Swedish).
For things that are targetted toward end users, that's a different

matter, of course, but kernel messages are inherently directed toward

developers and technically sophisticated users.
	-hpa
-

Hi,

I strongly agree with you.
Please keep kernel clean.

-

In regard to translating kernel messages:
Agreed.
There's a proposal in play for translations of documentation, and to

recruit "language maintainers" (which is an idea I see that Matt Mackall came

up with before I did).
A language maintainer is somebody who can accept a patch in language X,

translate its description to post on the appropriate english-only list with a

cc: to the appropriate maintainer(s), and translate questions and reviews

back and forth for the original author until the patch can be merged.  (This

means that documentation translations don't result in a stream of unmergeable

patches.)
As for the documentation translations themselves, I note that Eric Raymond

dissuaded me from actually hosting translations of kernel documentation on

http://kernel.org/doc due to his experience with translations of his own

writings.  If he hosts the translations on his website, they never get

updated again.  But if he makes the contributor host them on their own

website, then they sometimes get updated.
For my part, I can't _tell_ when a given translation is out of date because I

can't read it, and I certainly can't update it.  So I agree with Eric and I'm

linking to sites hosting kernel documentation in other languages rather than

hosting them myself.  I've got a good link to a Japanese site, need to ping

the contributors of the chinese documentation and see if they have a site for

it...
I await hearing back from Satoru Ueda who might have a lead on a potential

Japanese maintainer, probably after some event in Japan (a "Jamboree") in a

week or two...
Rob

--

"One of my most productive days was throwing away 1000 lines of code."

  - Ken Thompson.

-

If the documents are already maintained together on one site, it won't

be very hard to synchronize with kernel.org.  Eric is right for the case
Please add a link to http://zh-kernel.org/docs for Chinese translated

kernel documentation.
- Leo

-

Include the last git commit on this file in the translated document?
This would also make it easier for a translator to update a document

because a diff on the original document since the last translation would 
cu

Adrian
-- 
       "Is there not promise of rain?" Ling Tan asked suddenly out

        of the darkness. There had been need of rain for many days.

       "Only a promise," Lao Er said.

                                       Pearl S. Buck - Dragon Seed
-

Ok, back up.
Let's look at _english_ documentation.
If you go to http://kernel.org/doc/ols you should find, nicely split up, all

the OLS papers from 2002-2007.  By my count, there are 337 of them, totaling

61.8 megabytes when they're split up like that.  Being PDFs, they don't

compress all that well.
Which subset of these should be copied into the Documentation directory?  How

do you update them?  This is the documentation from just ONE SOURCE.
And PDF isn't close to the worst of it: Linuxconf.au has lots of video, as

does google video.  (I don't even have _english_ transcripts for those

videos, which would be nice.)  Do you want to merge all of this into the

kernel tarball as well?
How does this help keep anything up to date?
Rob

--

"One of my most productive days was throwing away 1000 lines of code."

  - Ken Thompson.

-

Oooh!  That's nice!  I didn't notice the "nicely split up" part earlier.

Any chance we can get the original docbook inputs that OLS uses

for paper submissions?  Have you asked Andrew or Craig about this?
Also, it would be nice to correlate the talk names with the individual

PDFs.  Do you want me to solicit inside CELF for a volunteer for this?

We'd probably produce a wiki page of links, based on your

list.txt file and the proceedings index.

 -- Tim
=============================

Tim Bird

Architecture Group Chair, CE Linux Forum

Senior Staff Engineer, Sony Corporation of America

=============================
-

I've asked, but OLS was in the process of happening and they were kind of 
I'm working on that: http://kernel.org/doc/ols/2002
I keep getting distracted by new material coming in.  Need to shut it out for 
Yes please.  I'm happy to have volunteers help out with any of this, if I can

figure out how to sanely partition it.
I'm not just collating names with papers, I'm also reading the paper and

trying to come up with a one page summary.  If you look at

http://kernel.org/doc you'll see a (now stale) version of an index skeleton.

I'd like to link to all these papers from one big index.  And also link the

Documentation files into the same index.  And http://lwn.net/Kernel/Index/

and Linux Journal's archives and...
That's the hard part.  Indexing it.  Piling up a big heap is easy.
You'll notice that Documentation has its own 00-index file, which doesn't even

refer to the make htmldocs output.  The lwn kernel material has an excellent

index.  The Linux Journal articles have a chronological archive.  Every

volume of OLS papers starts with a brief index.
And the problem is, every time somebody notices the problem they start a _new_

index that doesn't use any of the others.  (And they keep wanting to do it as

a wiki, which dooms the project.  In my experience wikis aren't stable and

only locally versioned.  They're not designed to be snapshotted as a coherent

whole, which is the _point_ of an index.  If you deep-link into a wiki you

get 404 errors after a while.  They're a good tool for the "piling up

information" part, but a bad tool for editorial jobs like organizing and

indexing existing information.  Wikis are designed to be decentralized, so

the left hand doesn't have to know what the right hand is doing, but

editorial functions is all about collating, coordinating, and correlating 
I have a list.txt file?  (Rummages.)  Oh, that's actually extracted from Red

Hat's 2007 OLS web page (see the link at top, "mirrored from here".)
I was using Red hat's b...
[ message continues ]

OLS uses LaTeX, not DocBook, for submissions AFAIK.
	-hpa

-

Yeah, but their retention of the original latex has been...  Iffy.  And their

indexing was a bit rushed.  http://www.linuxsymposium.org/proceedings.php

goes up to 2005.  If you go to

http://www.linuxsymposium.org/2006/proceedings.php you'll see a mirror of the

other page with 2006 added (why not update the top level one?  No idea.)

Then 2007 is off on a Red Hat site (mis-numbered) and not even hosted on

linuxsymposium.org.
If you look at http://kernel.org/doc/ols/2006/slides/ you'll notice I mirrored

all the presentation slides (not the same as the papers).  Two of them had

already gone down before I got there, but I managed to get a fresh copy of

Steven Hill's uClibc NPTL slides when I bumped into him at OLS.  (My mirror

has it, the original site it links to is 404.)  I still haven't tracked down

Kristen Accardi's slides, and that's one that was theoretically mirrored on

the OLS website itself, yet the link is 404...
I'm not complaining, by the way: busy people get the data out and then move

on, it's up to people like me to go back and clean it up if you want any kind

of data retention.  (And THEN you have to periodically figure out what's

still relevant and what's only of historical interest.  Wheee...)
Right now, I'd be happy to just get the PDFs of 2001 and earlier.  There's a

apparently one year they only have on paper, and one of the others is on a CD

that Andrew thinks he knows where it is, but hadn't had time to dig up when

last I poked him...
If latex shows up, I'm all for it.  But for now, I'm happy with the PDFs.

(Hey Tim, you want something for a volunteer to do?  Index the 2006 papers,

then match up the 2006 slides with the corresponding papers.  I can go

through and add in summaries afterwards...  And note that the index.html

should have _relative_ links, not absolute ones, because I want anyone to be

able to tarball up the whole site and locally mirror it.  I need to do a big

script that fetches the external things like the ols papers ...
[ message continues ]

You don't have to copy everything.
And you anyway have to handle cases like e.g. most books where you are 
You aren't legally permitted to update any OLS paper unless you've

gotten explicit permission by the author. And when he gives legal

permission, he can as well give you the LaTeX source. I'd expect legal

and technical update possibilities to usually be related this way.
You can only update things you are legally and technically able to 
cu

Adrian
-- 
       "Is there not promise of rain?" Ling Tan asked suddenly out

        of the darkness. There had been need of rain for many days.

       "Only a promise," Lao Er said.

                                       Pearl S. Buck - Dragon Seed
-

This is exactly what I'm saying.  I don't want to copy the translated

documentation, I want to point people to it.  Out on the web.  Where it's

maintained by the people who translated it, which history says they're 
A) http://www.linuxsymposium.org/2007/cfp.php under "Publication Rights":
  Further, as stated in the official templates, and on the Credits page from

  the Proceedings of this year and prior years: "Authors retain copyright to

  all submitted papers, but have granted unlimited redistribution rights to

  all as a condition of submission."
So it's free as in speech but not beer.
B) I'm using these as examples of things to NOT merge into the kernel sources.  
As an english speaker, I am not technically able to update non-english

documentation.  Since the only common language required of linux kernel

developers has ever been English, only the english documentation makes sense

to merge into the kernel tarball.  Merging anything else guarantees that the

vast majority of the contributors will never be able to review or update it,

so merging it into the kernel tarball does not result in extra review or

maintenance.
Extrapolating the review benefits of C code that breaks the build for

everybody if you do it wrong to chinese documentation you can't even

_read_...  Apples and oranges, it's a false comparison.  I don't see how 
Rob

--

"One of my most productive days was throwing away 1000 lines of code."

  - Ken Thompson.

-

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.
I'm not sure that the web site hosting argument is a good one.  Arch

maintainers and Language Maintainers have some similarities.  Also, being

able to clearly mark which version of a document was last translated

would help a bit with the fact that most of us aren't proficient in all

of the world's languages.  But, knowing who the translation maintainer is,

and when the translation was last updated allows both the original doc

maintainer and the translation document maintainer to see when a document

likely needs to be updated.  And that is probably good enough.
gerrit

-

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).
Now add in the non-english nature of the new Documentation/stale

subdirectories you're proposing.  Almost nobody in the existing kernel

community can even _read_ this documentation, let alone update it.  People

who update Documentation/* _can't_ update the translations, and that will

_never_change_.
Merging into the kernel is a great way to keep CODE up to date.  Don't think 
Ah, but It's not a language maintainer's job to update documentation.  It's

their job to ACCEPT PATCHES.  Translate patches, translate questions back and

forth.  This has NOTHING to do with documentation unless they're converting 
Keeping translations up to date is not something I can do, and thus not my 
Thank you.  You've just scared away all potential language maintainers by

making them think we want them to translate all the world's existing

documentation.  Do you know how long it takes just to read through the

existing Documentation directory?  (Have you done it?)
When I'm talking about language maintainers I am NOT looking for them to

translate existing documentation or keep Documentation/* up to date for some

other langauge.  That's a more than full-time job.  I've been looking around

for weeks for someone to just accept Japanese patches, and everybody I'...
[ message continues ]

There are quite a lot kernel developers for each of the popular

language, AFAIK.  For non-popular languages, there shouldn't be

translation available in the first place.  It was really a surprise when

I post my Chinese translation on the LKML so many Chinese speakers have

commented on the translation and encouraged the translation work.  They

are not visible as they usually don't talk too much.  :) So I set up the

Chinese kernel development maillist(linux-kernel@zh-kernel.org), there

will be more and more experienced kernel developer who can read and

update the Chinese documents after they read the translated
IMHO, having contribution merged into the kernel has the MAGIC to

attract people to work for recognition.  When more and more people
Language maintainers can integrate updates to the documentation just

like integrating any updates to the code.  Working on the documentation

is ,IMHO, a perfect task for novice kernel hacker to get familiar with
It won't be too hard if the work is shared by a community.  Like the one

I'm trying to establish.
- Leo
Advertisement time:

Chinese kernel development community http://zh-kernel.org    :)
-

I don't distinguish between "popular" and "non-popular" languages.  If

somebody's willing to do the translation work, it's popular.  If nobody's

willing to do the work, then even a language 1/3 of the planet's population

speaks isn't "popular" for kernel development.
I wouldn't discourage a translator into Klingon if they were willing to keep 
The chinese mailing list is highly cool, and my first instinct was to note it

on kernel.org/doc, but it would be better if the chinese website I already

link to notes it instead.  (That way I don't have to worry about how to

spam-guard your email address. :)
This also highlights the need for language maintainers to help the patches go

upstream to the english list.  (If we can avoid armchair commentators

saddling them with the task of translating the entire Documentation directory

and keeping such a translation up to date, we might actually get one too.

Fielding patches and questions sounds like plenty to me...)
Could you ask on said list if anyone is likely to volunteer for the position?  
Obvious counter-arguments include the floppy driver, the floppy tape driver,

the tty layer, and most of the existing english Documentation directory...
I'll happily stay out of the way of people who actually want to merge

translations of documentation into the kernel.  I reserve the right to say "I

different than any other patches.  Translate the description and questions

going back and forth.  The patch itself doesn't get translated when it's C

and applies to scripts/kconfig/, why would it when it's UTF-8 and applies to

Documentation/?
Of course this brings up the question "what kind of function and variable

names do chinese people pick?"  (I honestly don't know, but I note that

attempts to use names that don't fit in 7-bit ascii would probably be frowned 
A list works fine as a point of contact.  I note that in general, maintainers

are individuals (who delegate like mad, of course), because otherwise agenda

items languis...
[ message continues ]

The benefit of a localized maillist is that patches can be reviewed and
I do think the documentation translation is very necessary even when

there is a language maintainer, especially for the policy documents as

HOWTO, codestyle , and etc.  The contributors should go through these

policies and check their code for compliance before going to the

language maintainer for help, or there will be too much for the language

maintainer to translate.  The language maintainer doesn't need to

translate all the documents himself, but he can help to coordinate the

upstream.)
If we do need a contact person, I can do it.  However I don't think

there will be much translation work to do here.  As I stated before,

most Chinese programmers are more or less capable of read/write

technical English.  The difficult part is to let them know the benefit

of merging code in kernel and teach them how to do it.  That's why the

responsibility.
The documents and maillist are also linked in the front page.  It's

better to link the top level page.
- Leo

-

It would help if all the policy documents got grouped into a single

Documentation/development directory so we could separate "policy documents in

each language would be nice" from "that document about the amiga zorro bus

really needs to be kept up-to-date in Navajo and that should be in the kernel

tarball please".
Lemme see, which ones are we talking about?  The candidates are:

  applying-patches.txt

  BUG-HUNTING

  Changes

  CodingStyle

  debugging-modules.txt

  feature-removal-schedule.txt

  HOWTO

  kernel-docs.txt

  language-maintainers.txt

  ManagementStyle

  oops-tracing.txt

  SecurityBugs

  sparse.txt

  stable_api_nonsense.txt

  stable_kernel_rules.txt

  SubmitChecklist

  SubmittingDrivers

  SubmittingPatches

  volatile-considered-harmful.txt
That's everything I noticed in the top level directory that's a good candidate

to be grouped into a "development" subdirectory.  Did I miss anything?
I note that Changes is a bit stale in places (16 bit assembly?),

feature-removal-schedule.txt changes often but is good to know,

kernel-docs.txt might be useless to translate considering it's mostly links

to english documentation, language-maintainers.txt is assuming my patch from

earlier today gets accepted...
I can submit a patch grouping all that stuff together into a subdirectory if 
Does the above look like a good list?  There are more that need to be written,

but that's what I saw in Documentation...
Rob
P.S.  Dear kmail/postfix developers: having a transient DNS lookup failure on

one address in a long cc: list is _NOT_ a reason to have the message stay in

the kmail outbox.  It should go into the postfix send queue and be retried

from there.  Right now, if I tell it to resend, how do I know who it has and

hasn't been successfully distributed to on the first attempt?  I've gotten

dinged for trimming the cc: list before, but now I'm about to send out

duplicates.  Wheee...

--

"One of my most productive days was throwing away 1000 lines of code...
[ message continues ]

Yes, I do think this is a good list for translation.
Greg,

Do you have anything to add?
- Leo
-

There are a few documents not in the kernel tree that you

may want to translate too, if your goal is to increase the

number of kernel developers:
http://kernelnewbies.org/KernelGlossary
http://kernelnewbies.org/FAQ
http://kernelnewbies.org/UpstreamMerge
--

Politics is the struggle between those who want to make their country

the best in the world, and those who believe it already is.  Each group

calls the other unpatriotic.

-

How about adding;

kernel-doc-nano-HOWTO.txt
These three slightly include some policy in the documents but purpose

are mostly technical. (So, it's just comment)

devices.txt

kernel-parameters.txt

-

Yeah, I guess so.  My mental filter was actually more like "how to do linux

development", and it seemed both short and easy to translate, and also

generally relevant to the majority of developers no matter what subsystem

they're working on.
That one's not policy either, but it is general non-subsystem-specific

development.  Probably "applying-patches.txt" above goes in the same bucket.
Whether or not to include that bucket in the new directory depends on whether 
The problem is, the generated htmdocs are in english.  This file is about how

to generate (and author) English documentation that won't be translated.

What's the point of translating the instructions if the result won't be

translated?
On the other hand, if the authors of patches _do_ put javadoc comments into

the source code, the language maintainer should be aware of them and should 
Extracting the policy out into separate documents I could see, but I agree

those are primarily technical.
Rob

--

"One of my most productive days was throwing away 1000 lines of code."

  - Ken Thompson.

-

People (who even in non-native) would better to know and read it such

htmldocs because there are good and important documents even in English.
Further comment on this is that we may need to have another 00-INDEX

-

The english version of htmldocs is generated from the source code.    If

translating remotely current versions of htmldocs into other languages was

feasible, then the english version wouldn't need to be in the source code in

the first place.
Translating a document _about_ htmldocs boils down to "Dear non-english

speaker: here's something you can't read, nor can you update it either except

though your language maintainer."
Rob

--

"One of my most productive days was throwing away 1000 lines of code."

  - Ken Thompson.

-

No, kernel-doc-nano-HOWTO includes explanation of tools to extract the

document, format of extractable document in source files and so on.

I thought this file would help non-native people, how to extract or add

in-kernel extractable documents.

I understand that these tools will generate English documents but

that's OK. Such large volume of documents are not easy to translate

-

Which will be in english, so why can't the instructions on how to do it be in 
Then the instructions how to do it in english should be ok too.  If they can't 
"Here's how to get a result that will be useless to you."
Why?  What's the point?  I'm not seeing it.
Rob

--

"One of my most productive days was throwing away 1000 lines of code."

  - Ken Thompson.

-

It seems my explanation was not enough.

We (like me, usually not using English) can read English but it takes

more time than you (and any natives). So, reading large document takes

huge amount of time. In case of htmldocs, it is actually large and

developer may give up before start.

I thought that if some part (like how to do it) are translated into

his/her familiar language, he/she may not give it up.

Yes, it may not be.
Another viewpoint is that if he/she need to modify some interface and

it may need to change some part of extractable document, this file

includes, "How to add extractable documentation to your source files".

It will be some help as well.

Yes, He/she should write English and it may take long time but hopefully

-

I would like to comment from Japanese situation.

I do also think the documentation translation is necessary even if

there are language maintainer are not there. HOWTO like very

fundamental documents will great help for early stage of developers.

The contributors/early stage of developer will be able to follow

coding style and so on if the documents are easy to read.
So, maintain this kind of document in local language are necessary

even if there are no language maintainer.
I believe the language maintainer should mostly take care about the
I also think that most Japanese developers can read/write technical

-

Proposed patch adding Li Yang to MAINTAINERS, and Documentation

describing what a language maintainer is.
Signed-off-by: Rob Landley <rob@landley.net>
--
Woot!  See attached patch and sign-off-by if you want the job. :)
The bit about "the maintainer forwards, not the list" is a suggestion to

prevent duplicates.  It doesn't mean you can't delegate, just that if it's

open season on the list translating stuff _and_ forwarding it, then

linux-kernel will get dupes.  (Plus other maintainers are more likely

to pay attention to somebody they've heard from before.)
Greg KH had entire an OLS presentation about how the developer ->

maintainer -> subsystem -> anderew+linus forwarding is more

an ideal than a reality, but at least it gives us a frame of reference

to diverge from:

http://lwn.net/Articles/240402/
diff -r edfd2d6f670d MAINTAINERS

--- a/MAINTAINERS	Tue Jul 10 17:51:13 2007 -0700

+++ b/MAINTAINERS	Thu Jul 12 11:51:19 2007 -0400

@@ -2146,6 +2146,13 @@ W:	http://auxdisplay.googlepages.com/

 W:	http://auxdisplay.googlepages.com/

 S:	Maintained
+LANGUAGE (CHINESE)

+P:	Li Yang

+M:	LeoLi@freescale.com

+L:	linux-kernel@zh-kernel.org

+W:	http://zh-kernel.org

+S:	Maintained

+

 LAPB module

 L:	linux-x25@vger.kernel.org

 S:	Orphan

--- /dev/null	2007-04-23 11:59:00.000000000 -0400

+++ linux-2.6/Documentation/language-maintainers.txt	2007-07-12 11:49:20.000000000 -0400

@@ -0,0 +1,20 @@

+The langauges in which the Linux kernel is developed are C and English.

+(Note that Linus Torvalds' native language is Swedish, yet he chose

+to hold technical discussions in English.)

+

+The job of a language maintainer is to provide a point of contact for

+non-english speaking developers who wish to merge their patches into the

+Linux kernel.  Each language needs a specific language maintainer, who

+accepts non-english patch submissions on behalf of the Linux kernel.

+

+A language maintainer accepts patches to the Linux kernel, written in C, from

+authors who do not al...
[ message continues ]

In addiction to this responsibility, I would like to add two more which,

in my opinion, are more important.  And these are what I'm trying to

do.  :)

First, promoting contribution to Linux kernel in local language.
-

Cool.  It's good to do that, but not the problem I'm worried about solving.
I was trying to describe the minimum requirements for being a language

maintainer, I.E. what non-english users need in order to be able to merge

their patches.  Because without someone to contribute patches to (I.E a

language maintainer), documentation in non-english languages promotes the

creation of patches that can't be merged.  That's the problem I'm trying to

solve.
To me, finding language maintainers is the flip side of the coin of

translating documentation.
Rob
--

"One of my most productive days was throwing away 1000 lines of code."

  - Ken Thompson.

-

I think you worried too much about this problem.  :)  Let me explain

the situation here in China more clearly.  Actually, English is

mandatory in most schools and universities.  Only very few people

learn other language as a second language.  Therefore software

developers who are almost educated should have the basic English

skill.  However, that doesn't mean that they can read English or

communicate with native English speaker very easily.  Consider your

second language learn in school for analogy.  Read in English will be

much slower and more likely to cause misunderstanding.  This will

reduce the likelihood greatly of English documentation being read.  If

we are promoting contribution to the Linux community, we should

maximum the possibility that these key documents being read.

Translation will serve this purpose very well.
So the possibility is very little that a translator is needed between

the Linux maintainer and a Chinese developer.  Although sometimes help

is needed when there is misunderstanding.
After a brief talk with the Japanese translator, I think the case is

similar for Japanese too.
Therefore, in my opinion, language maintainer should be more a helper

and promoter rather than a gatekeeper.  I will give a proposed process

later about how this helper mechanism works.
- Leo

-

Yes, In Japan, situation is mostly the same.

We are trying to increase number of Linux community developer with

Linux Foundation Japan or CELF people in Japan.

In our discussion, the problem is not only Language.
In case of some developer, once he step forward (he try to send patch

or comment on LKML), he got some comment and he can work with

community even if it's slow (because of he was non-native).

So, I thought if some key document are available in Japanese like
-

Here is the helper process I propose to help more people to participate.

  Suggestions and comments are welcomed.
1) Developer who can't speak English or has a problem going through the

submission process sends patches to the Language maintainer and cc the

local mail list provided.

2) Language maintainer and experienced Linux developer on the local mail

list can review the patch and give comments in native language.

3) When the language maintainer thinks the patch is good in general, he

will pass the patch onto corresponding subsystem maintainer and mail

list for further review, cc the author and local list.

4) The author communicates directly with the community.

5) If the author has a problem understanding the comments or expressing

himself in English, he can ask for help in native language on the local

list.  The language maintainer and the developers on the list are

responsible to help out.

6) When the developer gets familiar with the submission process and can

go through it with no problem, he can then submit patch directly without

the helper process and probably join the mail list to help other new

developer.
- Leo

-

You know your area better than I do.  If you think that will work, I certainly 
Rob

--

"One of my most productive days was throwing away 1000 lines of code."

  - Ken Thompson.

-

I think you're absolutely right about that.  The stuff that will help

most of have translated is (kernel)newbie type documentation, the stuff

one wants when being introduced to the community.
	-hpa

-

Actually, I disagree.  English *is* the second language learned in

school for most European developers (except, obviously, the ones from
What we have found in Europe, is that that it has limited value, and

that the closer to the core you are, the less value it is, because at

that stage you should be communicating more with other developers.

Putting yourself behind a wall of translation is unfortunately a

detriment in that way.
	-hpa

-

There is somewhat of a difference though: English and both our native

languages are very much related. English, Dutch (my native language) and

Swedish (yours) are all Germanic languages -- English and Dutch both West

Germanic and Swedish only slightly farther removed as North Germanic. Word

for word translations not _too_ infrequently actually make okay or at least

understandable Dutch...
Other than Germanic, the Slavic (Polish, Czech, Russian, ...) and Latin

(Italian, Spanish, French, ...) language families are two other direct

Indo-European descendants that are fairly well represented in the kernel

community but I believe it's a largely unsurprising observation that members

of both these families have a somewhat harder time adopting English. And

Chinese is not even Indo-European...
However -- in Europe I notice culture might be even more important than

school _or_ language family is and as such I believe the above argument

isn't all that important anyway. English is the second language we learn in

school here in the Netherlands but it's much more popular than say German, a

language even closer to Dutch, due to us having heard English basically from

the time we're old enough to hear music and watch TV. Most _Dutch_ bands

sing in English and the ones that don't are for a part targetting the

elderly and/or mentally handicapped...
German is close enough to Dutch (and English itself) to rule out most

differences related to native language, but in Germany a significantly

smaller percentage of people speaks English well enough to be comfortable

with it than in the Netherlands simply due to them producing more of their

own culture. It's a larger language zone to market to and they dub the

remaining English-language content on TV. Over here in the Netherlands we

sub-title.
France is another good example. While a bit farther removed from English

family-wise, English has had lots of influences from French as well and in

any case, learning English shouldn't be...
[ message continues ]

Then this could be the main reason for the disagreement we have on

this topic.  Many people here don't grasp English very well even after

the English classes.
- Leo

-

Not all those from the British Isles. A first language an English as

school language is not that uncommon for segments of the population, and

in Wales schooling may also be such that English is learned as a first

foreign language.
That aside, please remember that Europe as a whole is a small place on the

bigger world stage. The total volume of potential developers in the huge

and rapidly modernising nations like India and China is vast, and there

are large highly skilled technical nations that don't teach English to

everyone technical by default.
Key documents in other languages is a big help, especially those about

values, culture and standards because they are things that are not easy

to understand if your use of English is technically oriented.
Alan

-

No doubt.  My point was merely that the closer to the core of

development, the less translated documents help as the emphasis on

interaction *has* to increase.
In that sense, a translation of "Linux Kernel Internals" and the other

books written on the Linux kernel is more useful.  That doesn't mean, of

course, that there isn't documentation distributed with the kernel that

is intended for users and therefore more useful in translation.

However, I do feel that trying to keep up-to-date translations of design

documentation is at least to some degree a fool's errand, which ends up

having people rely on incomplete and outdated documentation, and cut

them off from the overall community.
	-hpa

-

Several groups of people are translating the "important bits"

(a different selection for each culture) of the kernelnewbies

documentation to different languages already:
http://kernelnewbies.org/RegionalNewbies
I can easily set up additional wikis for anybody who wants

to set up such a kernel documentation site in their language.
--

Politics is the struggle between those who want to make their country

the best in the world, and those who believe it already is.  Each group

calls the other unpatriotic.

-

Poor person... I'm not sure this can work for non-trivial patches.
							Pavel

--

(english) http://www.livejournal.com/~pavelmachek

(cesky, pictures) http://atrey.karlin.mff.cuni.cz/~pavel/picture/horses/blog.html

-

We'll see.  Personally, I'm more worried about how people who don't speak

english are supposed to choose function and variable names.  But translating

_just_ the patch is not the end of it, and I wanted to make that clear.
I suppose a translator can always push back and ask for a _concise_ review,

for the sake of translation.  But let's not invent problems before they 
Rob

--

"One of my most productive days was throwing away 1000 lines of code."

  - Ken Thompson.

-

Choose \Choose\, v. t. [imp. {Chose}; p. p. {Chosen}, {Chose}

     (Obs.); p. pr. & vb. n. {Choosing}.] [OE. chesen, cheosen,

     AS. ce['o]san; akin to OS. kiosan, D. kiezen, G. kiesen,

     Icel. kj[=o]sa, Goth. kiusan, L. gustare to taste, Gr. ?,

     Skr. jush to enjoy. [root]46. Cf. {Choice}, 2d {Gust}.]
Gr{oetje,eeting}s,
						Geert
--

Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org
In personal conversations with technical people, I call myself a hacker. But

when I'm talking to journalists I just say "programmer" or something like that.

							    -- Linus Torvalds

-

^^^^^^^^^

           ^^^^^^^^^^^
Gr{oetje,eeting}s,
						Geert
--

Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org
In personal conversations with technical people, I call myself a hacker. But

when I'm talking to journalists I just say "programmer" or something like that.

							    -- Linus Torvalds

-

The guys at the Klingon Language Institute are going to have a fit - what's

the Klingon word for 'freezer' as used in our suspend code? :)

Considering that Klingon didn't have "to be" before Star Trek 6 needed hamlet,

I suspect they'll manage somehow.
Rob

--

"One of my most productive days was throwing away 1000 lines of code."

  - Ken Thompson.

-

One thing that would be a VERY good idea is to make sure that each

translated document is tagged with when it was last translated, and

against which kernel version (using either a GIT commit id or a

2.6.x.y revision, I don't care), and who is responsible for keeping

that particular document translated.  That way, it becomes a lot

easier to recognize when something is stale, and if has gotten stale,

we can just delete it.
If someone keeping some files translated into Klingon up to date for 3

months, and then disappears, we can just delete it, and it's no big

deal.  You can even say "I told you so" when you submit the patch to
I agree; if we're going to have a language translated in

Documentation/<lang>, there ought to be one or two overall language

maintainer, plus a maintainer for each file that is being translated,

who is responsible for updating the translated file when the base

English Documentation file is updated.
					- Ted

-

The English versions need a last updated too, that way we would know when

they are past their best before date (as most of them are)

-

You can get this out of git annotate.  (Or in my case, hg annotate from

http://kernel.org/hg/linux-2.6 .)
Cleaning up Documentation is on my todo list, but for this month I'm trying to

integrate the existing Documentation files with things like the OLS papers,

linux journal articles, lwn.net kernel articles, man-pages, and so on into

one big index.  (Indexing it requires reading large chunks of it.  My brain

hurts.)
If there's interest, I can push some patches to clean up Documentation by

moving files into subdirectories, but Documentation's not well-suited to link

out to the web.  (You need html for that, and it's text.)
Rob

--

"One of my most productive days was throwing away 1000 lines of code."

  - Ken Thompson.

-

I think that you should start moving Documentation/ files around

and adding subdirectories -- if you are pretty sure of where they

should go (i.e., they won't likely be moved again later on).
---

~Randy

*** Remember to use Documentation/SubmitChecklist when testing your code ***

-

You mean like these?

http://www.uwsg.iu.edu/hypermail/linux/kernel/0705.3/2925.html

http://www.uwsg.iu.edu/hypermail/linux/kernel/0705.3/2924.html
Rob

--

"One of my most productive days was throwing away 1000 lines of code."

  - Ken Thompson.

-

Yes.  Have any of these been merged?
---

~Randy

*** Remember to use Documentation/SubmitChecklist when testing your code ***

-

Not that I know of.  They seemed to meet with resounding indifference, so I

went on to other things...
Rob

--

"One of my most productive days was throwing away 1000 lines of code."

  - Ken Thompson.

-

You need to be persistent.  Please re-submit this.
and since it's just file & dir moves and done via git, it should go to

Linus.  However, he may not want it right now since the primary

merge window for 2.6.23 has closed (although he has been merging

some other doc updates recently).
---

~Randy

*** Remember to use Documentation/SubmitChecklist when testing your code ***

-

Greg KH thinks it's a good idea to add language directories to the top level

of Documentation, and there are slightly more than two of those:

http://www.translatorscafe.com/cafe/Help.asp?HelpID=59
Since you think it's worth doing, I'll resubmit the work I've already done

here, but I no longer think trying to shovel Documentation into some

semblance of order against the will of people like Greg is a good use of

time.
These days I'm trying to create an html index that links into Documentation in

a coherent order (with categories and everything), and using automated tools

to detect files that aren't linked to, or links that point to a file that

isn't there anymore.  This is obviously still a work in progress, but I think 
If moving text files from one location to another in the Documentation

directory breaks the build or causes bugs in the kernel, we have bigger

problems. :)
Rob

--

"One of my most productive days was throwing away 1000 lines of code."

  - Ken Thompson.

-

Better than cleaning up what we have in the kernel source tree?  Why not

work on that first, then the "automated" type stuff would be much easier

to do later, right?
thanks,
greg k-h

-

How does an automated 404 checker that identifies files nothing's linking to

get easier if the source files are in a different order?  They could be

alphabetical in one big directory and that would work the same.
Moving Documentation around is pointless churn that does nothing to prevent

you from adding language directories to the top level on a whim, as if there

were only two instead of (as I pointed out last message), several dozen.

(While Randy Dunlap's poking me to resubmit my patch to group the

architecture documentation into an architecture subdirectory, you're adding

language directories to the top level instead of in their own subdirectory.)
Documentation doesn't even cross-link to the output of make htmldocs (which

has its own structure imposed on it due to being extracted from the kernel

sources).  The kernel tarball has _two_ documentation sources that don't

significantly cross-reference each other, and Rusty just submitted "make

Preparation!" for lguest that's totally unrelated to either of them (and

starts from a README file buried in the source code).  None of this links to

the menuconfig help entries, and the only reference in Documentation/

to "make help" is in Documentation/kbuild/makefiles.txt which explains that

its purpose is to list the available architecture targets (something it does

not, in my experience, actually do).
The idea that the kernel Documentation directory is the master repository of

kernel documentation is an unworkable fantasy.  The Documentation directory

cannot index for all the kernel documentation resources out on the web,

because it's in text not html.  Documentation was created on the assumption

that it would contain all interesting resources, as text files, but that

doesn't match reality.  Documentation is merely one resource among many, and

to link _out_ you need HTML.
Some of the resources out there are organized chronologically, such as the

Linux Journal archives [ message continues ]