Re: Documentation of kernel messages (Summary)

[Rob Landley <rob@landley.net>]

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.