Re: Documentation of kernel messages (Summary)
On Saturday 04 August 2007 3:04:33 pm Stefan Richter wrote: > Rob Landley wrote: > > Documentation is merely one resource among many, and > > to link _out_ you need HTML. > > Do you suggest HTML files in linux/Documentation? I've thought about it, but right now Documentation is text. Converting all the existing text files to html is a fairly intrusive change, and having multiple file formats in there seems even more untidy. (What next, pdf?). I'm aware there are some docbook files in there, plus an ancient graphic file, plus the bloody stains of various chicken sacrificies, but the point would be how best to clean it up... > I think we can follow > URIs and other references in plaintext files just fine. Go for it. Have fun. I'll be over here. Rob -- "One of my most productive days was throwing away 1000 lines of code." - Ken Thompson. - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Saturday 04 August 2007 3:04:33 pm Stefan Richter wrote: Rob Landley wrote: Documentation is merely one resource among many, and to link _out_ you need HTML. Do you suggest HTML files in linux/Documentation? I've thought about it, but right now Documentation is text. Converting all the existing text files to html is a fairly intrusive change, and having multiple file formats in there seems even more untidy. (What next, pdf?). I'm aware there are some docbook files in there, plus an ancient graphic file, plus the bloody stains of various chicken sacrificies, but the point would be how best to clean it up... I think we can follow URIs and other references in plaintext files just fine. Go for it. Have fun. I'll be over here. Rob -- One of my most productive days was throwing away 1000 lines of code. - Ken Thompson. - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
Rob Landley wrote: > Documentation is merely one resource among many, and > to link _out_ you need HTML. Do you suggest HTML files in linux/Documentation? I think we can follow URIs and other references in plaintext files just fine. (People who want clickable links in plaintext files can use plaintext viewers which implement this, or utilities or browser plugins which follow URLs in the clipboard.) -- Stefan Richter -=-=-=== =--- --=-- http://arcgraph.de/sr/ - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Friday 03 August 2007 10:50:38 pm Greg KH wrote: > On Fri, Aug 03, 2007 at 03:32:04PM -0400, Rob Landley wrote: > > On Friday 03 August 2007 1:11:55 pm Randy Dunlap wrote: > > > On Mon, 16 Jul 2007 15:53:06 -0400 Rob Landley wrote: > > > > On Sunday 15 July 2007 12:28:06 pm Randy Dunlap wrote: > > > > > On Sat, 14 Jul 2007 21:56:15 -0400 Rob Landley wrote: > > > > > > On Friday 13 July 2007 11:54:41 pm Randy Dunlap wrote: > > > > > > > > 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.) > > > > > > > > > > > > > > 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). > > > > > > > > > > > > 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 > > > > > > > > > > Yes. Have any of these been merged? > > > > > > > > Not that I know of. They seemed to meet with resounding > > > > indifference, so I went on to other things... > > > > > > You need to be persistent. Please re-submit this. > > > > 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. > > My "will" is only that some of these documents be translated _and_ put > in the main kernel source tree. I really have no opinion on where they > need to go within that directory. If you have a better place for them, > please let me know. A common subdirectory. I'd probably put it in "Documentation/translated" with a README at the top level of that explaining what it's for. I can push a patch to move them, but reorganizing Documentation doesn't turn it into an index that can link out resources outside itself. If reorganizing it to be less of a compost heap is a separate goal in and of itself, I can do that... Rob -- "One of my most productive days was throwing away 1000 lines of code." - Ken Thompson. - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Friday 03 August 2007 10:52:06 pm Greg KH wrote: > On Fri, Aug 03, 2007 at 03:32:04PM -0400, Rob Landley wrote: > > 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 it's a better approach. > > Better than cleaning up what we have in the kernel source tree? Yes, I just said that. > Why not work on that first, then the "automated" type stuff would be much > easier to do later, right? 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 http://www.linuxjournal.com/xstatic/magazine/archives, the Ottawa Linux Symposium papers (http://kernel.org/doc/ols), or the kernel-traffic archives http://www.kernel-traffic.org/kernel-traffic/archives.html. Some have their own indexes, such as the Linux Weekly News kernel articles http://lwn.net/Kernel/Index/ and the Linux Device Drivers book http://lwn.net/Kernel/LDD3/. Some are random bits picked out of developer blogs, found with google, reasonably coherent articles on wikipedia. Some are huge self-contained lumps on specific topics such as Mel Gorman's mm documentation or lots of the embedded stuff. So no matter what reorganization I do to Documentation, its structure (or lack thereof) is incidental to coherently indexing most of the kernel documentation that's out there. (Right now the best index is "google" but that's only useful if you know what questions to ask. But getting up-to-date versions of Documentation and the output of make htmldocs on the web lets google find it. (Last year, back when I was still working on BusyBox, I did a google trawl for ext2 documentation to replace the horrible mke2fs busybox used to have, and the first three pages of hits did _NOT_ include a copy of Documentation/filesystems/ext2.txt. Ironically, if you google for "ext2 documentation" today the sixth hit is the unfinished ext2 documentation I'd just started to write before I found Documentation/filesystems/ext2.txt.) Rob -- "One of my most productive days was throwing away 1000 lines of code." - Ken Thompson. - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Friday 03 August 2007 10:52:06 pm Greg KH wrote: On Fri, Aug 03, 2007 at 03:32:04PM -0400, Rob Landley wrote: 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 it's a better approach. Better than cleaning up what we have in the kernel source tree? Yes, I just said that. Why not work on that first, then the automated type stuff would be much easier to do later, right? 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 http://www.linuxjournal.com/xstatic/magazine/archives, the Ottawa Linux Symposium papers (http://kernel.org/doc/ols), or the kernel-traffic archives http://www.kernel-traffic.org/kernel-traffic/archives.html. Some have their own indexes, such as the Linux Weekly News kernel articles http://lwn.net/Kernel/Index/ and the Linux Device Drivers book http://lwn.net/Kernel/LDD3/. Some are random bits picked out of developer blogs, found with google, reasonably coherent articles on wikipedia. Some are huge self-contained lumps on specific topics such as Mel Gorman's mm documentation or lots of the embedded stuff. So no matter what reorganization I do to Documentation, its structure (or lack thereof) is incidental to coherently indexing most of the kernel documentation that's out there. (Right now the best index is google but that's only useful if you know what questions to ask. But getting up-to-date versions of Documentation and the output of make htmldocs on the web lets google find it. (Last year, back when I was still working on BusyBox, I did a google trawl for ext2 documentation to replace the horrible mke2fs busybox used to have, and the first three pages of hits did _NOT_ include a copy of Documentation/filesystems/ext2.txt. Ironically, if you google for ext2 documentation today the sixth hit is the unfinished ext2 documentation I'd just started to write before I found Documentation/filesystems/ext2.txt.) Rob -- One of my most productive days was throwing away 1000 lines of code. - Ken Thompson. - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Friday 03 August 2007 10:50:38 pm Greg KH wrote: On Fri, Aug 03, 2007 at 03:32:04PM -0400, Rob Landley wrote: On Friday 03 August 2007 1:11:55 pm Randy Dunlap wrote: On Mon, 16 Jul 2007 15:53:06 -0400 Rob Landley wrote: On Sunday 15 July 2007 12:28:06 pm Randy Dunlap wrote: On Sat, 14 Jul 2007 21:56:15 -0400 Rob Landley wrote: On Friday 13 July 2007 11:54:41 pm Randy Dunlap wrote: 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.) 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). 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 Yes. Have any of these been merged? Not that I know of. They seemed to meet with resounding indifference, so I went on to other things... You need to be persistent. Please re-submit this. 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. My will is only that some of these documents be translated _and_ put in the main kernel source tree. I really have no opinion on where they need to go within that directory. If you have a better place for them, please let me know. A common subdirectory. I'd probably put it in Documentation/translated with a README at the top level of that explaining what it's for. I can push a patch to move them, but reorganizing Documentation doesn't turn it into an index that can link out resources outside itself. If reorganizing it to be less of a compost heap is a separate goal in and of itself, I can do that... Rob -- One of my most productive days was throwing away 1000 lines of code. - Ken Thompson. - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
Rob Landley wrote: Documentation is merely one resource among many, and to link _out_ you need HTML. Do you suggest HTML files in linux/Documentation? I think we can follow URIs and other references in plaintext files just fine. (People who want clickable links in plaintext files can use plaintext viewers which implement this, or utilities or browser plugins which follow URLs in the clipboard.) -- Stefan Richter -=-=-=== =--- --=-- http://arcgraph.de/sr/ - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Fri, Aug 03, 2007 at 03:32:04PM -0400, Rob Landley wrote: > > 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 > it's a better approach. 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 - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Fri, Aug 03, 2007 at 03:32:04PM -0400, Rob Landley wrote: > On Friday 03 August 2007 1:11:55 pm Randy Dunlap wrote: > > On Mon, 16 Jul 2007 15:53:06 -0400 Rob Landley wrote: > > > On Sunday 15 July 2007 12:28:06 pm Randy Dunlap wrote: > > > > On Sat, 14 Jul 2007 21:56:15 -0400 Rob Landley wrote: > > > > > On Friday 13 July 2007 11:54:41 pm Randy Dunlap wrote: > > > > > > > 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.) > > > > > > > > > > > > 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). > > > > > > > > > > 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 > > > > > > > > Yes. Have any of these been merged? > > > > > > Not that I know of. They seemed to meet with resounding indifference, so > > > I went on to other things... > > > > You need to be persistent. Please re-submit this. > > 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. My "will" is only that some of these documents be translated _and_ put in the main kernel source tree. I really have no opinion on where they need to go within that directory. If you have a better place for them, please let me know. thanks, greg k-h - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Friday 03 August 2007 1:11:55 pm Randy Dunlap wrote: > On Mon, 16 Jul 2007 15:53:06 -0400 Rob Landley wrote: > > On Sunday 15 July 2007 12:28:06 pm Randy Dunlap wrote: > > > On Sat, 14 Jul 2007 21:56:15 -0400 Rob Landley wrote: > > > > On Friday 13 July 2007 11:54:41 pm Randy Dunlap wrote: > > > > > > 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.) > > > > > > > > > > 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). > > > > > > > > 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 > > > > > > Yes. Have any of these been merged? > > > > Not that I know of. They seemed to meet with resounding indifference, so > > I went on to other things... > > You need to be persistent. Please re-submit this. 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 it's a better approach. > 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). 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. - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Mon, 16 Jul 2007 15:53:06 -0400 Rob Landley wrote: > On Sunday 15 July 2007 12:28:06 pm Randy Dunlap wrote: > > On Sat, 14 Jul 2007 21:56:15 -0400 Rob Landley wrote: > > > On Friday 13 July 2007 11:54:41 pm Randy Dunlap wrote: > > > > > 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.) > > > > > > > > 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). > > > > > > 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 > > > > Yes. Have any of these been merged? > > Not that I know of. They seemed to meet with resounding indifference, so I > went on to other things... 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 *** - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Mon, 16 Jul 2007 15:53:06 -0400 Rob Landley wrote: On Sunday 15 July 2007 12:28:06 pm Randy Dunlap wrote: On Sat, 14 Jul 2007 21:56:15 -0400 Rob Landley wrote: On Friday 13 July 2007 11:54:41 pm Randy Dunlap wrote: 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.) 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). 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 Yes. Have any of these been merged? Not that I know of. They seemed to meet with resounding indifference, so I went on to other things... 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 *** - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Friday 03 August 2007 1:11:55 pm Randy Dunlap wrote: On Mon, 16 Jul 2007 15:53:06 -0400 Rob Landley wrote: On Sunday 15 July 2007 12:28:06 pm Randy Dunlap wrote: On Sat, 14 Jul 2007 21:56:15 -0400 Rob Landley wrote: On Friday 13 July 2007 11:54:41 pm Randy Dunlap wrote: 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.) 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). 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 Yes. Have any of these been merged? Not that I know of. They seemed to meet with resounding indifference, so I went on to other things... You need to be persistent. Please re-submit this. 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 it's a better approach. 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). 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. - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Fri, Aug 03, 2007 at 03:32:04PM -0400, Rob Landley wrote: On Friday 03 August 2007 1:11:55 pm Randy Dunlap wrote: On Mon, 16 Jul 2007 15:53:06 -0400 Rob Landley wrote: On Sunday 15 July 2007 12:28:06 pm Randy Dunlap wrote: On Sat, 14 Jul 2007 21:56:15 -0400 Rob Landley wrote: On Friday 13 July 2007 11:54:41 pm Randy Dunlap wrote: 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.) 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). 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 Yes. Have any of these been merged? Not that I know of. They seemed to meet with resounding indifference, so I went on to other things... You need to be persistent. Please re-submit this. 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. My will is only that some of these documents be translated _and_ put in the main kernel source tree. I really have no opinion on where they need to go within that directory. If you have a better place for them, please let me know. thanks, greg k-h - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Fri, Aug 03, 2007 at 03:32:04PM -0400, Rob Landley wrote: 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 it's a better approach. 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 - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Tue, 17 Jul 2007 12:06:56 -0400, rob wrote: > On Sunday 15 July 2007 12:46:42 pm Tsugikazu Shibata wrote: > > On Sat, 14 Jul 2007 22:12:35 -0400, rob wrote: > > > On Friday 13 July 2007 9:46:59 pm Tsugikazu Shibata wrote: > > > > > > How about adding; > > > > > > kernel-doc-nano-HOWTO.txt > > > > > > > > > > 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? > > > > > > > > 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. I thought that translation of this file may help. > > > > > > 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." > > > > 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. > > Which will be in english, so why can't the instructions on how to do it be in > english too? > > > I understand that these tools will generate English documents but > > that's OK. > > Then the instructions how to do it in english should be ok too. If they > can't > read the instructions, they won't be able to read the result. 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 the translation result would push his/her back. > > Such large volume of documents are not easy to translate > > into other languages. > > "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. > - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Monday 16 July 2007 9:17:28 pm H. Peter Anvin wrote: > Tim Bird wrote: > > 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? > > OLS uses LaTeX, not DocBook, for submissions AFAIK. 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 and breaks them up so you have reproducible local copies without blindly copying mine. It's on my todo list...) Rob -- "One of my most productive days was throwing away 1000 lines of code." - Ken Thompson. - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Monday 16 July 2007 8:31:52 pm Tim Bird wrote: > Rob Landley wrote: > > If you go to http://kernel.org/doc/ols you should find, nicely split up, > > all the OLS papers from 2002-2007. > > 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? I've asked, but OLS was in the process of happening and they were kind of swamped... > Also, it would be nice to correlate the talk names with the individual > PDFs. 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 a bit and focus on processing the existing pile... > Do you want me to solicit inside CELF for a volunteer for this? 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 into a coherent whole. Which is nontrivial.) > We'd probably produce a wiki page of links, based on your > list.txt file and the proceedings index. 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 broken-up pages (and pre-broken-up ones I found for 2004) for a while, but I went back and I re-broke up the pages with my scripts (which you'll notice I link to; I want people other than me to be able to reproduce this.) I did it because all the others I broke up have the two OLS boilerplate pages at the _end_ rather than the beginning, and I wanted to be consistent. And that list.txt page doesn't have the paragraph per article summary (which I can sometimes take from the abstract, but even when there is an abstract it's often not what I need and I read the darn paper anyway to see what interesting stuff's buried in it). I need that in order to index the articles, title isn't enough. Some articles need to get linked from more than one place. (James Bottomley's 2002 scsi paper has good "history of hotplug" material, for example.) Rob -- "One of my most productive days was throwing away 1000 lines of code." - Ken Thompson. - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Sunday 15 July 2007 12:46:42 pm Tsugikazu Shibata wrote: > On Sat, 14 Jul 2007 22:12:35 -0400, rob wrote: > > On Friday 13 July 2007 9:46:59 pm Tsugikazu Shibata wrote: > > > > > How about adding; > > > > > kernel-doc-nano-HOWTO.txt > > > > > > > > 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? > > > > > > 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. I thought that translation of this file may help. > > > > 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." > > 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. Which will be in english, so why can't the instructions on how to do it be in english too? > I understand that these tools will generate English documents but > that's OK. Then the instructions how to do it in english should be ok too. If they can't read the instructions, they won't be able to read the result. > Such large volume of documents are not easy to translate > into other languages. "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. - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Sunday 15 July 2007 12:46:42 pm Tsugikazu Shibata wrote: On Sat, 14 Jul 2007 22:12:35 -0400, rob wrote: On Friday 13 July 2007 9:46:59 pm Tsugikazu Shibata wrote: How about adding; kernel-doc-nano-HOWTO.txt 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? 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. I thought that translation of this file may help. 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. 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. Which will be in english, so why can't the instructions on how to do it be in english too? I understand that these tools will generate English documents but that's OK. Then the instructions how to do it in english should be ok too. If they can't read the instructions, they won't be able to read the result. Such large volume of documents are not easy to translate into other languages. 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. - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Monday 16 July 2007 8:31:52 pm Tim Bird wrote: Rob Landley wrote: If you go to http://kernel.org/doc/ols you should find, nicely split up, all the OLS papers from 2002-2007. 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? I've asked, but OLS was in the process of happening and they were kind of swamped... Also, it would be nice to correlate the talk names with the individual PDFs. 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 a bit and focus on processing the existing pile... Do you want me to solicit inside CELF for a volunteer for this? 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 into a coherent whole. Which is nontrivial.) We'd probably produce a wiki page of links, based on your list.txt file and the proceedings index. 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 broken-up pages (and pre-broken-up ones I found for 2004) for a while, but I went back and I re-broke up the pages with my scripts (which you'll notice I link to; I want people other than me to be able to reproduce this.) I did it because all the others I broke up have the two OLS boilerplate pages at the _end_ rather than the beginning, and I wanted to be consistent. And that list.txt page doesn't have the paragraph per article summary (which I can sometimes take from the abstract, but even when there is an abstract it's often not what I need and I read the darn paper anyway to see what interesting stuff's buried in it). I need that in order to index the articles, title isn't enough. Some articles need to get linked from more than one place. (James Bottomley's 2002 scsi paper has good history of hotplug material, for example.) Rob -- One of my most productive days was throwing away 1000 lines of code. - Ken Thompson. - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Monday 16 July 2007 9:17:28 pm H. Peter Anvin wrote: Tim Bird wrote: 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? OLS uses LaTeX, not DocBook, for submissions AFAIK. 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 and breaks them up so you have reproducible local copies without blindly copying mine. It's on my todo list...) Rob -- One of my most productive days was throwing away 1000 lines of code. - Ken Thompson. - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Tue, 17 Jul 2007 12:06:56 -0400, rob wrote: On Sunday 15 July 2007 12:46:42 pm Tsugikazu Shibata wrote: On Sat, 14 Jul 2007 22:12:35 -0400, rob wrote: On Friday 13 July 2007 9:46:59 pm Tsugikazu Shibata wrote: How about adding; kernel-doc-nano-HOWTO.txt 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? 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. I thought that translation of this file may help. 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. 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. Which will be in english, so why can't the instructions on how to do it be in english too? I understand that these tools will generate English documents but that's OK. Then the instructions how to do it in english should be ok too. If they can't read the instructions, they won't be able to read the result. 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 the translation result would push his/her back. Such large volume of documents are not easy to translate into other languages. 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. - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
Tim Bird wrote: > > 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? > OLS uses LaTeX, not DocBook, for submissions AFAIK. -hpa - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
Rob Landley wrote: > If you go to http://kernel.org/doc/ols you should find, nicely split up, all > the OLS papers from 2002-2007. 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 = - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Sunday 15 July 2007 12:28:06 pm Randy Dunlap wrote: > On Sat, 14 Jul 2007 21:56:15 -0400 Rob Landley wrote: > > On Friday 13 July 2007 11:54:41 pm Randy Dunlap wrote: > > > > 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.) > > > > > > 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). > > > > 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 > > Yes. Have any of these been merged? 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. - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Sunday 15 July 2007 12:28:06 pm Randy Dunlap wrote: On Sat, 14 Jul 2007 21:56:15 -0400 Rob Landley wrote: On Friday 13 July 2007 11:54:41 pm Randy Dunlap wrote: 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.) 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). 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 Yes. Have any of these been merged? 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. - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
Rob Landley wrote: If you go to http://kernel.org/doc/ols you should find, nicely split up, all the OLS papers from 2002-2007. 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 = - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
Tim Bird wrote: 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? OLS uses LaTeX, not DocBook, for submissions AFAIK. -hpa - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
Li Yang wrote: Yes, I do think this is a good list for translation. Greg, Do you have anything to add? 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. - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Sat, 14 Jul 2007 22:12:35 -0400, rob wrote: > On Friday 13 July 2007 9:46:59 pm Tsugikazu Shibata wrote: > > > > How about adding; > > > > kernel-doc-nano-HOWTO.txt > > > > > > 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? > > > > 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. > > I thought that translation of this file may help. > > 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." 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 into other languages. > > Rob > -- > "One of my most productive days was throwing away 1000 lines of code." > - Ken Thompson. > - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Sat, 14 Jul 2007 21:56:15 -0400 Rob Landley wrote: > On Friday 13 July 2007 11:54:41 pm Randy Dunlap wrote: > > > 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.) > > > > 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). > > 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 Yes. Have any of these been merged? --- ~Randy *** Remember to use Documentation/SubmitChecklist when testing your code *** - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Sat, 14 Jul 2007 21:56:15 -0400 Rob Landley wrote: On Friday 13 July 2007 11:54:41 pm Randy Dunlap wrote: 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.) 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). 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 Yes. Have any of these been merged? --- ~Randy *** Remember to use Documentation/SubmitChecklist when testing your code *** - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Sat, 14 Jul 2007 22:12:35 -0400, rob wrote: On Friday 13 July 2007 9:46:59 pm Tsugikazu Shibata wrote: How about adding; kernel-doc-nano-HOWTO.txt 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? 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. I thought that translation of this file may help. 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. 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 into other languages. Rob -- One of my most productive days was throwing away 1000 lines of code. - Ken Thompson. - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
Li Yang wrote: Yes, I do think this is a good list for translation. Greg, Do you have anything to add? 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. - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Friday 13 July 2007 9:46:59 pm Tsugikazu Shibata wrote: > > > How about adding; > > > kernel-doc-nano-HOWTO.txt > > > > 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? > > 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. > I thought that translation of this file may help. 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. - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Friday 13 July 2007 11:54:41 pm Randy Dunlap wrote: > > 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.) > > 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). 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. - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Friday 13 July 2007 11:54:41 pm Randy Dunlap wrote: 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.) 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). 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. - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Friday 13 July 2007 9:46:59 pm Tsugikazu Shibata wrote: How about adding; kernel-doc-nano-HOWTO.txt 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? 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. I thought that translation of this file may help. 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. - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Fri, 13 Jul 2007 14:05:49 -0400 Rob Landley wrote: > 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.) 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 *** - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Fri, 13 Jul 2007 13:12:27 -0400, rob wrote: > On Thursday 12 July 2007 10:54:46 pm Tsugikazu Shibata wrote: > > On Thu, 12 Jul 2007 13:35:54 -0400, rob wrote: > > > On Thursday 12 July 2007 9:53:54 am Li Yang-r58472 wrote: > > > > > Fielding patches and questions sounds like plenty to me...) > > > > > > > > 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 translation effort and help to make it update to date. > > > > > > 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 > > > > This file seems mostly technical. may not policy related document. > > 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. > > But I agree, it's not policy. > > > > feature-removal-schedule.txt > > > HOWTO > > > kernel-docs.txt > > > language-maintainers.txt > > > ManagementStyle > > > oops-tracing.txt > > > SecurityBugs > > > sparse.txt > > 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 directory is labeled "development" or "policy" or something else... Agree. > > > stable_api_nonsense.txt > > > stable_kernel_rules.txt > > > SubmitChecklist > > > SubmittingDrivers > > > SubmittingPatches > > > volatile-considered-harmful.txt > > > > How about adding; > > kernel-doc-nano-HOWTO.txt > > 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? 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. I thought that translation of this file may help. > 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 > have some easy way to translate them for the list... maybe. > > > These three slightly include some policy in the documents but purpose > > are mostly technical. (So, it's just comment) > > devices.txt > > kernel-parameters.txt > > unicode.txt > > Extracting the policy out into separate documents I could see, but I agree > those are primarily technical. Further comment on this is that we may need to have another 00-INDEX file, for this new directory. > > Rob > -- > "One of my most productive days was throwing away 1000 lines of code." > - Ken Thompson. > - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Fri, 13 Jul 2007 15:25:49 +0200, Stefan Richter said: > Alan Cox wrote: > > 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) > > I've got the impression that whenever I saw a "last updated:" note in a > documentation, this note was out of date. RCS and SCCS let you stick stuff like $DATE and $VERSION into the source, so it would be automagically replaced at checkin/checkout time. Not sure how well that would work across a mesh of 'git pull' and 'git push' across trees. :) pgp6YVJiuBB3m.pgp Description: PGP signature
Re: Documentation of kernel messages (Summary)
On Friday 13 July 2007 6:53:21 am Alan Cox wrote: > > 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 > > 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. - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Thursday 12 July 2007 10:54:46 pm Tsugikazu Shibata wrote: > On Thu, 12 Jul 2007 13:35:54 -0400, rob wrote: > > On Thursday 12 July 2007 9:53:54 am Li Yang-r58472 wrote: > > > > Fielding patches and questions sounds like plenty to me...) > > > > > > 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 translation effort and help to make it update to date. > > > > 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 > > This file seems mostly technical. may not policy related document. 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. But I agree, it's not policy. > > feature-removal-schedule.txt > > HOWTO > > kernel-docs.txt > > language-maintainers.txt > > ManagementStyle > > oops-tracing.txt > > SecurityBugs > > sparse.txt 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 directory is labeled "development" or "policy" or something else... > > stable_api_nonsense.txt > > stable_kernel_rules.txt > > SubmitChecklist > > SubmittingDrivers > > SubmittingPatches > > volatile-considered-harmful.txt > > How about adding; > kernel-doc-nano-HOWTO.txt 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 have some easy way to translate them for the list... > These three slightly include some policy in the documents but purpose > are mostly technical. (So, it's just comment) > devices.txt > kernel-parameters.txt > unicode.txt 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. - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Fri, Jul 13, 2007 at 08:49:00PM +0800, Li Yang wrote: > On Fri, 2007-07-13 at 11:53 +0100, Alan Cox wrote: > > > 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 > > > > 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) > > Good idea. So a "last updated" date field will be required for both the > English and translated documents. Date will be more straight forward > than using commit id, IMHO. Well, date and kernel version id, then. Otherwise they may be confusion if the translator is using 2.6.16.35 as opposed to 2.6.22-git3, etc. I would hope that the translator would always be using only the latest development branch, but I wouldn't want to always bet on that. One advantage of using git commit id is that there's no question about what the source document version was for the translation. It also makes it easier for the translator since they can just diff between the last git commit id, and HEAD, and then update their translation accordingly. - Ted - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
Alan Cox wrote: > 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) I've got the impression that whenever I saw a "last updated:" note in a documentation, this note was out of date. -- Stefan Richter -=-=-=== -=== -==-= http://arcgraph.de/sr/ - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Fri, 2007-07-13 at 11:53 +0100, Alan Cox wrote: > > 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 > > 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) Good idea. So a "last updated" date field will be required for both the English and translated documents. Date will be more straight forward than using commit id, IMHO. - Leo - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Thu, 2007-07-12 at 13:35 -0400, Rob Landley wrote: > On Thursday 12 July 2007 9:53:54 am Li Yang-r58472 wrote: > > > Fielding patches and questions sounds like plenty to me...) > > > > 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 > > translation effort and help to make it update to date. > > 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 > it would help... > > > 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 > > policy documents in native language will be very useful. > > Does the above look like a good list? There are more that need to be > written, > but that's what I saw in Documentation... Yes, I do think this is a good list for translation. Greg, Do you have anything to add? - Leo - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
> 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 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) - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
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 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) - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Fri, Jul 13, 2007 at 08:49:00PM +0800, Li Yang wrote: On Fri, 2007-07-13 at 11:53 +0100, Alan Cox wrote: 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 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) Good idea. So a last updated date field will be required for both the English and translated documents. Date will be more straight forward than using commit id, IMHO. Well, date and kernel version id, then. Otherwise they may be confusion if the translator is using 2.6.16.35 as opposed to 2.6.22-git3, etc. I would hope that the translator would always be using only the latest development branch, but I wouldn't want to always bet on that. One advantage of using git commit id is that there's no question about what the source document version was for the translation. It also makes it easier for the translator since they can just diff between the last git commit id, and HEAD, and then update their translation accordingly. - Ted - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Thu, 2007-07-12 at 13:35 -0400, Rob Landley wrote: On Thursday 12 July 2007 9:53:54 am Li Yang-r58472 wrote: Fielding patches and questions sounds like plenty to me...) 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 translation effort and help to make it update to date. 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 it would help... 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 policy documents in native language will be very useful. Does the above look like a good list? There are more that need to be written, but that's what I saw in Documentation... Yes, I do think this is a good list for translation. Greg, Do you have anything to add? - Leo - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
Alan Cox wrote: 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) I've got the impression that whenever I saw a last updated: note in a documentation, this note was out of date. -- Stefan Richter -=-=-=== -=== -==-= http://arcgraph.de/sr/ - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Fri, 2007-07-13 at 11:53 +0100, Alan Cox wrote: 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 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) Good idea. So a last updated date field will be required for both the English and translated documents. Date will be more straight forward than using commit id, IMHO. - Leo - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Thursday 12 July 2007 10:54:46 pm Tsugikazu Shibata wrote: On Thu, 12 Jul 2007 13:35:54 -0400, rob wrote: On Thursday 12 July 2007 9:53:54 am Li Yang-r58472 wrote: Fielding patches and questions sounds like plenty to me...) 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 translation effort and help to make it update to date. 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 This file seems mostly technical. may not policy related document. 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. But I agree, it's not policy. feature-removal-schedule.txt HOWTO kernel-docs.txt language-maintainers.txt ManagementStyle oops-tracing.txt SecurityBugs sparse.txt 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 directory is labeled development or policy or something else... stable_api_nonsense.txt stable_kernel_rules.txt SubmitChecklist SubmittingDrivers SubmittingPatches volatile-considered-harmful.txt How about adding; kernel-doc-nano-HOWTO.txt 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 have some easy way to translate them for the list... These three slightly include some policy in the documents but purpose are mostly technical. (So, it's just comment) devices.txt kernel-parameters.txt unicode.txt 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. - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Friday 13 July 2007 6:53:21 am Alan Cox wrote: 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 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. - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Fri, 13 Jul 2007 15:25:49 +0200, Stefan Richter said: Alan Cox wrote: 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) I've got the impression that whenever I saw a last updated: note in a documentation, this note was out of date. RCS and SCCS let you stick stuff like $DATE and $VERSION into the source, so it would be automagically replaced at checkin/checkout time. Not sure how well that would work across a mesh of 'git pull' and 'git push' across trees. :) pgp6YVJiuBB3m.pgp Description: PGP signature
Re: Documentation of kernel messages (Summary)
On Fri, 13 Jul 2007 13:12:27 -0400, rob wrote: On Thursday 12 July 2007 10:54:46 pm Tsugikazu Shibata wrote: On Thu, 12 Jul 2007 13:35:54 -0400, rob wrote: On Thursday 12 July 2007 9:53:54 am Li Yang-r58472 wrote: Fielding patches and questions sounds like plenty to me...) 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 translation effort and help to make it update to date. 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 This file seems mostly technical. may not policy related document. 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. But I agree, it's not policy. feature-removal-schedule.txt HOWTO kernel-docs.txt language-maintainers.txt ManagementStyle oops-tracing.txt SecurityBugs sparse.txt 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 directory is labeled development or policy or something else... Agree. stable_api_nonsense.txt stable_kernel_rules.txt SubmitChecklist SubmittingDrivers SubmittingPatches volatile-considered-harmful.txt How about adding; kernel-doc-nano-HOWTO.txt 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? 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. I thought that translation of this file may help. 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 have some easy way to translate them for the list... maybe. These three slightly include some policy in the documents but purpose are mostly technical. (So, it's just comment) devices.txt kernel-parameters.txt unicode.txt Extracting the policy out into separate documents I could see, but I agree those are primarily technical. Further comment on this is that we may need to have another 00-INDEX file, for this new directory. Rob -- One of my most productive days was throwing away 1000 lines of code. - Ken Thompson. - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Fri, 13 Jul 2007 14:05:49 -0400 Rob Landley wrote: 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.) 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 *** - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Thu, 12 Jul 2007 13:35:54 -0400, rob wrote: > On Thursday 12 July 2007 9:53:54 am Li Yang-r58472 wrote: > > > Fielding patches and questions sounds like plenty to me...) > > > > 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 > > translation effort and help to make it update to date. > > 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 This file seems mostly technical. may not policy related document. > 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 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 unicode.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 > it would help... > > > 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 > > policy documents in native language will be very useful. > > 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... - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Wednesday 11 July 2007 5:53:54 pm [EMAIL PROTECTED] wrote: > On Wed, 11 Jul 2007 14:13:02 EDT, Rob Landley said: > > I wouldn't discourage a translator into Klingon if they were willing to > > keep their translation up to date and/or it actually resulted in patches. > > 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. - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Thursday 12 July 2007 9:53:54 am Li Yang-r58472 wrote: > > Fielding patches and questions sounds like plenty to me...) > > 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 > translation effort and help to make it update to date. 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 it would help... > 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 > policy documents in native language will be very useful. 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." - Ken Thompson. - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Thu, 12 Jul 2007 21:53:54 +0800, LeoLi wrote: > On Thursday, July 12, 2007 2:13 AM Rob Landley wrote: > > On Wednesday 11 July 2007 10:26:30 am Li Yang wrote: > > > 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. > > > > 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 > > their translation up to date and/or it actually resulted in patches. > > > > > 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([EMAIL PROTECTED]), > there > > > will be more and more experienced kernel developer who can read and > > > update the Chinese documents after they read the translated > > > documentation and become kernel hacker. > > > > 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. :) > > The benefit of a localized maillist is that patches can be reviewed and > commented in native language for common problems (like style, API). > > > > > 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...) > > 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 > translation effort and help to make it update to date. 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 patch. > > Could you ask on said list if anyone is likely to volunteer for the > position? > > (JUST translating patches and questions, as part of pushing code > 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 > policy documents in native language will be very useful. I also think that most Japanese developers can read/write technical English at some level. > > > > Merging into the kernel is a great way to keep CODE up to date. > Don't > > > > think > > > > it's magic pixie dust for documentation. It never has been > before. > > > > > > IMHO, having contribution merged into the kernel has the MAGIC to > > > attract people to work for recognition. When more and more people > > > volunteer to work on it, the documentation will be up to date > magically. > > > > 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 > > told you so" in about five years. > > > > > > 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
RE: Documentation of kernel messages (Summary)
On Thursday, July 12, 2007 2:13 AM Rob Landley wrote: > On Wednesday 11 July 2007 10:26:30 am Li Yang wrote: > > 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. > > 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 > their translation up to date and/or it actually resulted in patches. > > > 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([EMAIL PROTECTED]), there > > will be more and more experienced kernel developer who can read and > > update the Chinese documents after they read the translated > > documentation and become kernel hacker. > > 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. :) The benefit of a localized maillist is that patches can be reviewed and commented in native language for common problems (like style, API). > > 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...) 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 translation effort and help to make it update to date. > > Could you ask on said list if anyone is likely to volunteer for the position? > (JUST translating patches and questions, as part of pushing code 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 policy documents in native language will be very useful. > > > > Merging into the kernel is a great way to keep CODE up to date. Don't > > > think > > > it's magic pixie dust for documentation. It never has been before. > > > > IMHO, having contribution merged into the kernel has the MAGIC to > > attract people to work for recognition. When more and more people > > volunteer to work on it, the documentation will be up to date magically. > > 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 > told you so" in about five years. > > > > 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 > > > documentation accompanying the patch one way; into english. > > > > 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 > > the process. > > From a language maintainer's perspective documentation patches wouldn't be any > 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
RE: Documentation of kernel messages (Summary)
On Thursday, July 12, 2007 2:13 AM Rob Landley wrote: On Wednesday 11 July 2007 10:26:30 am Li Yang wrote: 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. 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 their translation up to date and/or it actually resulted in patches. 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([EMAIL PROTECTED]), there will be more and more experienced kernel developer who can read and update the Chinese documents after they read the translated documentation and become kernel hacker. 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. :) The benefit of a localized maillist is that patches can be reviewed and commented in native language for common problems (like style, API). 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...) 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 translation effort and help to make it update to date. Could you ask on said list if anyone is likely to volunteer for the position? (JUST translating patches and questions, as part of pushing code 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 policy documents in native language will be very useful. Merging into the kernel is a great way to keep CODE up to date. Don't think it's magic pixie dust for documentation. It never has been before. IMHO, having contribution merged into the kernel has the MAGIC to attract people to work for recognition. When more and more people volunteer to work on it, the documentation will be up to date magically. 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 told you so in about five years. 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 documentation accompanying the patch one way; into english. 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 the process. From a language maintainer's perspective documentation patches wouldn't be any 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 upon in a big way...) It won't be too hard if the work is shared by a community. Like the one I'm trying
Re: Documentation of kernel messages (Summary)
On Thu, 12 Jul 2007 21:53:54 +0800, LeoLi wrote: On Thursday, July 12, 2007 2:13 AM Rob Landley wrote: On Wednesday 11 July 2007 10:26:30 am Li Yang wrote: 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. 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 their translation up to date and/or it actually resulted in patches. 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([EMAIL PROTECTED]), there will be more and more experienced kernel developer who can read and update the Chinese documents after they read the translated documentation and become kernel hacker. 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. :) The benefit of a localized maillist is that patches can be reviewed and commented in native language for common problems (like style, API). 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...) 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 translation effort and help to make it update to date. 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 patch. Could you ask on said list if anyone is likely to volunteer for the position? (JUST translating patches and questions, as part of pushing code 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 policy documents in native language will be very useful. I also think that most Japanese developers can read/write technical English at some level. Merging into the kernel is a great way to keep CODE up to date. Don't think it's magic pixie dust for documentation. It never has been before. IMHO, having contribution merged into the kernel has the MAGIC to attract people to work for recognition. When more and more people volunteer to work on it, the documentation will be up to date magically. 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 told you so in about five years. 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 documentation accompanying the patch one way; into english. Language maintainers can integrate updates to the documentation just like integrating any updates to
Re: Documentation of kernel messages (Summary)
On Thursday 12 July 2007 9:53:54 am Li Yang-r58472 wrote: Fielding patches and questions sounds like plenty to me...) 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 translation effort and help to make it update to date. 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 it would help... 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 policy documents in native language will be very useful. 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. - Ken Thompson. - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Wednesday 11 July 2007 5:53:54 pm [EMAIL PROTECTED] wrote: On Wed, 11 Jul 2007 14:13:02 EDT, Rob Landley said: I wouldn't discourage a translator into Klingon if they were willing to keep their translation up to date and/or it actually resulted in patches. 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. - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Thu, 12 Jul 2007 13:35:54 -0400, rob wrote: On Thursday 12 July 2007 9:53:54 am Li Yang-r58472 wrote: Fielding patches and questions sounds like plenty to me...) 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 translation effort and help to make it update to date. 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 This file seems mostly technical. may not policy related document. 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 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 unicode.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 it would help... 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 policy documents in native language will be very useful. 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... - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Wed, 11 Jul 2007 14:13:02 EDT, Rob Landley said: > I wouldn't discourage a translator into Klingon if they were willing to keep > their translation up to date and/or it actually resulted in patches. 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? :) pgpMS9jFLFFep.pgp Description: PGP signature
Re: Documentation of kernel messages (Summary)
On Wed, Jul 11, 2007 at 02:13:02PM -0400, Rob Landley wrote: > > IMHO, having contribution merged into the kernel has the MAGIC to > > attract people to work for recognition. When more and more people > > volunteer to work on it, the documentation will be up to date magically. > > 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 > told you so" in about five years. 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 delete the stale translation. :-) > 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 languish with everyone thinking it's someone else's responsibility. I agree; if we're going to have a language translated in Documentation/, 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 - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Wednesday 11 July 2007 10:26:30 am Li Yang wrote: > 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. 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 their translation up to date and/or it actually resulted in patches. > 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([EMAIL PROTECTED]), there > will be more and more experienced kernel developer who can read and > update the Chinese documents after they read the translated > documentation and become kernel hacker. 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? (JUST translating patches and questions, as part of pushing code upstream.) > > Merging into the kernel is a great way to keep CODE up to date. Don't > > think > > it's magic pixie dust for documentation. It never has been before. > > IMHO, having contribution merged into the kernel has the MAGIC to > attract people to work for recognition. When more and more people > volunteer to work on it, the documentation will be up to date magically. 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 told you so" in about five years. > > 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 > > documentation accompanying the patch one way; into english. > > 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 > the process. >From a language maintainer's perspective documentation patches wouldn't be any 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 upon in a big way...) > It won't be too hard if the work is shared by a community. Like the one > I'm trying to establish. 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 languish with everyone thinking it's someone else's responsibility. http://www.trumanlibrary.org/buckstop.htm > - Leo > > Advertisement time: > Chinese kernel development community http://zh-kernel.org:) Hmmm... Now I'm wondering if I should link directly to the docs pages of the chinese and japanese sites, or to the top level community pages? Rob -- "One of my most productive days was throwing away 1000 lines of code." - Ken Thompson. - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Wed, 2007-07-11 at 00:12 +0800, Rob Landley wrote: > On Monday 09 July 2007 13:18:57 Gerrit Huizenga wrote: > > On Mon, 09 Jul 2007 12:48:24 EDT, Rob Landley wrote: > > > In regard to translating kernel messages: > > > > > > On Monday 09 July 2007 01:36:31 H. Peter Anvin wrote: > > > > Kunai, Takashi wrote: > > > > > (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. > > > > > > > > There is a very strong reason for the kernel community to NOT > support > > > > this: it makes it much harder to deal with bug reports. > > > > > > Agreed. > > > > [...] > > > > > 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... > > > > 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). > > 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_. 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([EMAIL PROTECTED]), there will be more and more experienced kernel developer who can read and update the Chinese documents after they read the translated documentation and become kernel hacker. > > Merging into the kernel is a great way to keep CODE up to date. Don't > think > it's magic pixie dust for documentation. It never has been before. IMHO, having contribution merged into the kernel has the MAGIC to attract people to work for recognition. When more and more people volunteer to work on it, the documentation will be up to date magically. > > > I'm not sure that the web site hosting argument is a good one. > Arch > > maintainers and Language Maintainers have some similarities. > > 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 > documentation accompanying the patch one way; into english. 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 the process. > > > 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. > > Keeping translations up to date is not something I can do, and thus > not my > problem. > > > But, knowing
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 [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
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 [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Wed, 2007-07-11 at 00:12 +0800, Rob Landley wrote: On Monday 09 July 2007 13:18:57 Gerrit Huizenga wrote: On Mon, 09 Jul 2007 12:48:24 EDT, Rob Landley wrote: In regard to translating kernel messages: On Monday 09 July 2007 01:36:31 H. Peter Anvin wrote: Kunai, Takashi wrote: (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. There is a very strong reason for the kernel community to NOT support this: it makes it much harder to deal with bug reports. Agreed. [...] 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... 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). 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_. 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([EMAIL PROTECTED]), there will be more and more experienced kernel developer who can read and update the Chinese documents after they read the translated documentation and become kernel hacker. Merging into the kernel is a great way to keep CODE up to date. Don't think it's magic pixie dust for documentation. It never has been before. IMHO, having contribution merged into the kernel has the MAGIC to attract people to work for recognition. When more and more people volunteer to work on it, the documentation will be up to date magically. I'm not sure that the web site hosting argument is a good one. Arch maintainers and Language Maintainers have some similarities. 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 documentation accompanying the patch one way; into english. 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 the process. 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. Keeping translations up to date is not something I can do, and thus not my problem. 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
Re: Documentation of kernel messages (Summary)
On Wednesday 11 July 2007 10:26:30 am Li Yang wrote: 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. 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 their translation up to date and/or it actually resulted in patches. 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([EMAIL PROTECTED]), there will be more and more experienced kernel developer who can read and update the Chinese documents after they read the translated documentation and become kernel hacker. 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? (JUST translating patches and questions, as part of pushing code upstream.) Merging into the kernel is a great way to keep CODE up to date. Don't think it's magic pixie dust for documentation. It never has been before. IMHO, having contribution merged into the kernel has the MAGIC to attract people to work for recognition. When more and more people volunteer to work on it, the documentation will be up to date magically. 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 told you so in about five years. 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 documentation accompanying the patch one way; into english. 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 the process. From a language maintainer's perspective documentation patches wouldn't be any 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 upon in a big way...) It won't be too hard if the work is shared by a community. Like the one I'm trying to establish. 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 languish with everyone thinking it's someone else's responsibility. http://www.trumanlibrary.org/buckstop.htm - Leo Advertisement time: Chinese kernel development community http://zh-kernel.org:) Hmmm... Now I'm wondering if I should link directly to the docs pages of the chinese and japanese sites, or to the top level community pages? Rob -- One of my most productive days was throwing away 1000 lines of code. - Ken Thompson. - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Wed, Jul 11, 2007 at 02:13:02PM -0400, Rob Landley wrote: IMHO, having contribution merged into the kernel has the MAGIC to attract people to work for recognition. When more and more people volunteer to work on it, the documentation will be up to date magically. 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 told you so in about five years. 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 delete the stale translation. :-) 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 languish with everyone thinking it's someone else's responsibility. 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 - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Wed, 11 Jul 2007 14:13:02 EDT, Rob Landley said: I wouldn't discourage a translator into Klingon if they were willing to keep their translation up to date and/or it actually resulted in patches. 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? :) pgpMS9jFLFFep.pgp Description: PGP signature
Re: Documentation of kernel messages (Summary)
On Tuesday 10 July 2007 14:54:15 Adrian Bunk wrote: > On Tue, Jul 10, 2007 at 12:25:31PM -0400, Rob Landley wrote: > >... > > 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? > > You don't have to copy everything. > > And you anyway have to handle cases like e.g. most books where you are > not permitted to copy them, but might want to point people to them. 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 noticeably less likely to do with a copy. > > How > > do you update them? This is the documentation from just ONE SOURCE. > > You aren't legally permitted to update any OLS paper unless you've > gotten explicit permission by the author. I wasn't planning to. I'm pointing out that it's hard. > And you shouldn't include non-free documentation into the kernel sources. 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. Thank you for making my point. There's a LOT of this stuff out there. > > How does this help keep anything up to date? > > You can only update things you are legally and technically able to > update. For the rest, you can only ship pointers like kernel-docs.txt. 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 merging translations of documentation is ever likely to be a win. > > Rob > > cu > Adrian Rob -- "One of my most productive days was throwing away 1000 lines of code." - Ken Thompson. - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Tue, Jul 10, 2007 at 12:25:31PM -0400, Rob Landley wrote: >... > 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? You don't have to copy everything. And you anyway have to handle cases like e.g. most books where you are not permitted to copy them, but might want to point people to them. > How > do you update them? This is the documentation from just ONE SOURCE. 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. And you shouldn't include non-free documentation into the kernel sources. > 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? Not at all. > How does this help keep anything up to date? You can only update things you are legally and technically able to update. For the rest, you can only ship pointers like kernel-docs.txt. > Rob 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 - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [Lf_kernel_messages] Re: Documentation of kernel messages (Summary)
On Monday 09 July 2007 14:10:07 Theodore Tso wrote: > 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. Sounds good to me. Rob -- "One of my most productive days was throwing away 1000 lines of code." - Ken Thompson. - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Monday 09 July 2007 14:33:09 Adrian Bunk wrote: > On Mon, Jul 09, 2007 at 12:48:24PM -0400, Rob Landley wrote: > >... > > [regarding translated documentation] > > > > 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... > >... > > 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 > be trivial. 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. - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Monday 09 July 2007 13:18:57 Gerrit Huizenga wrote: > On Mon, 09 Jul 2007 12:48:24 EDT, Rob Landley wrote: > > In regard to translating kernel messages: > > > > On Monday 09 July 2007 01:36:31 H. Peter Anvin wrote: > > > Kunai, Takashi wrote: > > > > (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. > > > > > > There is a very strong reason for the kernel community to NOT support > > > this: it makes it much harder to deal with bug reports. > > > > Agreed. > > [...] > > > 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... > > 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). 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 it's magic pixie dust for documentation. It never has been before. > I'm not sure that the web site hosting argument is a good one. Arch > maintainers and Language Maintainers have some similarities. 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 documentation accompanying the patch one way; into english. > 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. Keeping translations up to date is not something I can do, and thus not my problem. > 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. 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've talked to says it's too much time commitment without any extra work piled on top of it in by armchair commentators who won't be _doing_ that work. > gerrit Rob -- "One of my most productive days was throwing away 1000 lines of code." - Ken Thompson. - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
RE: Documentation of kernel messages (Summary)
> -Original Message- > From: [EMAIL PROTECTED] > [mailto:[EMAIL PROTECTED] On Behalf Of Rob Landley > Sent: Tuesday, July 10, 2007 12:48 AM > To: H. Peter Anvin > Cc: Kunai, Takashi; [EMAIL PROTECTED]; Andrew Morton; > linux-kernel@vger.kernel.org; [EMAIL PROTECTED]; > [EMAIL PROTECTED]; [EMAIL PROTECTED]; [EMAIL PROTECTED]; [EMAIL PROTECTED]; > [EMAIL PROTECTED]; [EMAIL PROTECTED]; [EMAIL PROTECTED]; [EMAIL PROTECTED]; > [EMAIL PROTECTED]; [EMAIL PROTECTED]; [EMAIL PROTECTED]; > [EMAIL PROTECTED]; [EMAIL PROTECTED]; [EMAIL PROTECTED]; > [EMAIL PROTECTED]; [EMAIL PROTECTED]; [EMAIL PROTECTED]; > [EMAIL PROTECTED]; [EMAIL PROTECTED] > Subject: Re: Documentation of kernel messages (Summary) > > In regard to translating kernel messages: > > On Monday 09 July 2007 01:36:31 H. Peter Anvin wrote: > > Kunai, Takashi wrote: > > > (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. > > > > There is a very strong reason for the kernel community to NOT support > > this: it makes it much harder to deal with bug reports. > > 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. 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 that separate documents on separate sites. > > 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... Please add a link to http://zh-kernel.org/docs for Chinese translated kernel documentation. - Leo - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
Hi, On 7/9/07, H. Peter Anvin <[EMAIL PROTECTED]> wrote: Kunai, Takashi wrote: > (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. 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. I strongly agree with you. Please keep kernel clean. - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
Am Dienstag, 10. Juli 2007 schrieb Satyam Sharma: > 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. 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 - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
Am Dienstag, 10. Juli 2007 schrieb Satyam Sharma: 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. 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 - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
Hi, On 7/9/07, H. Peter Anvin [EMAIL PROTECTED] wrote: Kunai, Takashi wrote: (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. 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. I strongly agree with you. Please keep kernel clean. - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
RE: Documentation of kernel messages (Summary)
-Original Message- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] On Behalf Of Rob Landley Sent: Tuesday, July 10, 2007 12:48 AM To: H. Peter Anvin Cc: Kunai, Takashi; [EMAIL PROTECTED]; Andrew Morton; linux-kernel@vger.kernel.org; [EMAIL PROTECTED]; [EMAIL PROTECTED]; [EMAIL PROTECTED]; [EMAIL PROTECTED]; [EMAIL PROTECTED]; [EMAIL PROTECTED]; [EMAIL PROTECTED]; [EMAIL PROTECTED]; [EMAIL PROTECTED]; [EMAIL PROTECTED]; [EMAIL PROTECTED]; [EMAIL PROTECTED]; [EMAIL PROTECTED]; [EMAIL PROTECTED]; [EMAIL PROTECTED]; [EMAIL PROTECTED]; [EMAIL PROTECTED]; [EMAIL PROTECTED]; [EMAIL PROTECTED]; [EMAIL PROTECTED] Subject: Re: Documentation of kernel messages (Summary) In regard to translating kernel messages: On Monday 09 July 2007 01:36:31 H. Peter Anvin wrote: Kunai, Takashi wrote: (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. There is a very strong reason for the kernel community to NOT support this: it makes it much harder to deal with bug reports. 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. 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 that separate documents on separate sites. 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... Please add a link to http://zh-kernel.org/docs for Chinese translated kernel documentation. - Leo - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Monday 09 July 2007 13:18:57 Gerrit Huizenga wrote: On Mon, 09 Jul 2007 12:48:24 EDT, Rob Landley wrote: In regard to translating kernel messages: On Monday 09 July 2007 01:36:31 H. Peter Anvin wrote: Kunai, Takashi wrote: (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. There is a very strong reason for the kernel community to NOT support this: it makes it much harder to deal with bug reports. Agreed. [...] 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... 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). 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 it's magic pixie dust for documentation. It never has been before. I'm not sure that the web site hosting argument is a good one. Arch maintainers and Language Maintainers have some similarities. 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 documentation accompanying the patch one way; into english. 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. Keeping translations up to date is not something I can do, and thus not my problem. 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. 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've talked to says it's too much time commitment without any extra work piled on top of it in by armchair commentators who won't be _doing_ that work. gerrit Rob -- One of my most productive days was throwing away 1000 lines of code. - Ken Thompson. - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Monday 09 July 2007 14:33:09 Adrian Bunk wrote: On Mon, Jul 09, 2007 at 12:48:24PM -0400, Rob Landley wrote: ... [regarding translated documentation] 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... ... 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 be trivial. 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. - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [Lf_kernel_messages] Re: Documentation of kernel messages (Summary)
On Monday 09 July 2007 14:10:07 Theodore Tso wrote: 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. Sounds good to me. Rob -- One of my most productive days was throwing away 1000 lines of code. - Ken Thompson. - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Tue, Jul 10, 2007 at 12:25:31PM -0400, Rob Landley wrote: ... 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? You don't have to copy everything. And you anyway have to handle cases like e.g. most books where you are not permitted to copy them, but might want to point people to them. How do you update them? This is the documentation from just ONE SOURCE. 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. And you shouldn't include non-free documentation into the kernel sources. 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? Not at all. How does this help keep anything up to date? You can only update things you are legally and technically able to update. For the rest, you can only ship pointers like kernel-docs.txt. Rob 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 - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Tuesday 10 July 2007 14:54:15 Adrian Bunk wrote: On Tue, Jul 10, 2007 at 12:25:31PM -0400, Rob Landley wrote: ... 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? You don't have to copy everything. And you anyway have to handle cases like e.g. most books where you are not permitted to copy them, but might want to point people to them. 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 noticeably less likely to do with a copy. How do you update them? This is the documentation from just ONE SOURCE. You aren't legally permitted to update any OLS paper unless you've gotten explicit permission by the author. I wasn't planning to. I'm pointing out that it's hard. And you shouldn't include non-free documentation into the kernel sources. 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. Thank you for making my point. There's a LOT of this stuff out there. How does this help keep anything up to date? You can only update things you are legally and technically able to update. For the rest, you can only ship pointers like kernel-docs.txt. 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 merging translations of documentation is ever likely to be a win. Rob cu Adrian Rob -- One of my most productive days was throwing away 1000 lines of code. - Ken Thompson. - To unsubscribe from this list: send the line unsubscribe linux-kernel in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On 7/9/07, Oliver Neukum <[EMAIL PROTECTED]> wrote: Am Montag, 9. Juli 2007 schrieb Kunai, Takashi: > (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 We have generators for hash functions that guarantee unique results for a set of inputs. Right, perfect hash generators require the input set to be known *a priori*. They are even GPLed. As you are operating against a known target, that should work. 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 - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [Lf_kernel_messages] Re: Documentation of kernel messages (Summary)
O> 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. 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 - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: Documentation of kernel messages (Summary)
On Mon, Jul 09, 2007 at 12:48:24PM -0400, Rob Landley wrote: >... > [regarding translated documentation] > > 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... >... 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 be trivial. > Rob 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 - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Re: [Lf_kernel_messages] Re: Documentation of kernel messages (Summary)
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 - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
