lkml.org 
[lkml]   [2007]   [Jul]   [13]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
SubjectRe: Documentation of kernel messages (Summary)
From
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 majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/

\
 
 \ /
  Last update: 2007-07-14 03:59    [W:0.120 / U:0.236 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site