headers
Elyse M. Grasso | 6 Jul 2007 00:09
Favicon

Re: [PATCH][Documentation][resend] Add missing files and dirs to 00-INDEX in Documentation/

On Thursday 05 July 2007, you wrote:
> On Thursday 05 July 2007 13:12:35 Elyse M. Grasso wrote:
> > Is there something I could do to help? It's been years since I programmed
> > C, but I'm a former librarian, current configuration management tools
> > consultant. I write good standards-compliant HTML and XHTML, and Perl is 
my
> > life these days.
> >
> > Point me at something where I won't be duplicating effort and I'll take a
> > look at it.
> 
> Sure.
> 
> Could you start by subscribing to linux-doc?  (Info at 
> http://vger.kernel.org/vger-lists.html)  We can discuss it at length over 
> there.
> 
> Thanks,
> 
> Rob
> -- 
> "One of my most productive days was throwing away 1000 lines of code."
>   - Ken Thompson.
> 
OK I've joined. I hope this was the right one, the group description says:

 Old linux documentation forum (?)

--

-- 
Elyse Grasso
(Continue reading)

Permalink | Reply | 2 comments |
headers
Randy Dunlap | 6 Jul 2007 02:11

Re: [PATCH][Documentation][resend] Add missing files and dirs to 00-INDEX in Documentation/

On Thu, 5 Jul 2007 16:09:15 -0600 Elyse M. Grasso wrote:

> On Thursday 05 July 2007, you wrote:
> > On Thursday 05 July 2007 13:12:35 Elyse M. Grasso wrote:
> > > Is there something I could do to help? It's been years since I programmed
> > > C, but I'm a former librarian, current configuration management tools
> > > consultant. I write good standards-compliant HTML and XHTML, and Perl is 
> my
> > > life these days.
> > >
> > > Point me at something where I won't be duplicating effort and I'll take a
> > > look at it.
> > 
> > Sure.
> > 
> > Could you start by subscribing to linux-doc?  (Info at 
> > http://vger.kernel.org/vger-lists.html)  We can discuss it at length over 
> > there.
> > 
> > Thanks,
> > 
> > Rob
> > -- 
> > 
> OK I've joined. I hope this was the right one, the group description says:
> 
>  Old linux documentation forum (?)

Yes, this is it.  Maybe we can get that phrase fixed...
(Continue reading)

Permalink | Reply | 1 comment |
headers
Rob Landley | 6 Jul 2007 17:07

The documentation todo heap.

Elyse M. Grasso said:
> Is there something I could do to help? It's been years since I programmed
> C, but I'm a former librarian, current configuration management tools
> consultant. I write good standards-compliant HTML and XHTML, and Perl is my
> life these days.
>
> Point me at something where I won't be duplicating effort and I'll take a
> look at it.
> --
> Elyse Grasso

Ok, here's what I've got at the top of my todo heap.

My first priority is a massive indexing job.  I have a half-dozen sources of 
information either mirrored or linked from "http://kernel.org/doc" already, 
and before I add more I'd like to integrate the ones I've got into one big 
index, sorted by topic.

I appended the skeleton of a possible index to the page, and I'd like to start 
by shuffling in articles from Documentation, the lwn.net kernel page, and the 
broken-up OLS papers I've mirrored on the site.  These are probably the three 
highest quality sources of documentation with a reasonable granularity to the 
information.  (The man pages are very good too, but the man page maintainer 
expressed interest in maintaining his own html versions online, and I'd like 
to give that time to settle before linking to a location that might move.)

Today I'm going through OLS papers from 2002.  I'm reading them all and 
writing one paragraph summaries, which I can then use to slot them into the 
index on a second pass.
(Continue reading)

Permalink | Reply | 0 comments |
headers
Rob Landley | 6 Jul 2007 17:32

Re: [PATCH][Documentation][resend] Add missing files and dirs to 00-INDEX in Documentation/

On Thursday 05 July 2007 20:11:36 Randy Dunlap wrote:
> On Thu, 5 Jul 2007 16:09:15 -0600 Elyse M. Grasso wrote:
> > On Thursday 05 July 2007, you wrote:
> > > On Thursday 05 July 2007 13:12:35 Elyse M. Grasso wrote:
> > > > Is there something I could do to help? It's been years since I
> > > > programmed C, but I'm a former librarian, current configuration
> > > > management tools consultant. I write good standards-compliant HTML
> > > > and XHTML, and Perl is
> >
> > my
> >
> > > > life these days.
> > > >
> > > > Point me at something where I won't be duplicating effort and I'll
> > > > take a look at it.
> > >
> > > Sure.
> > >
> > > Could you start by subscribing to linux-doc?  (Info at
> > > http://vger.kernel.org/vger-lists.html)  We can discuss it at length
> > > over there.
> > >
> > > Thanks,
> > >
> > > Rob
> > > --
> >
> > OK I've joined. I hope this was the right one, the group description
> > says:
> >
(Continue reading)

Permalink | Reply | 0 comments |
headers
Rob Landley | 9 Jul 2007 18:48

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.
(Continue reading)

Permalink | Reply | 126 comments |
headers
Gerrit Huizenga | 9 Jul 2007 19:18
Picon
Favicon

Re: Documentation of kernel messages (Summary)


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
(Continue reading)

Permalink | Reply | 106 comments |
headers
Adrian Bunk | 9 Jul 2007 20:33
Picon

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
(Continue reading)

Permalink | Reply | 14 comments |
headers
Li Yang-r58472 | 10 Jul 2007 09:59
Favicon

RE: Documentation of kernel messages (Summary)

> -----Original Message-----
> From: linux-kernel-owner <at> vger.kernel.org
> [mailto:linux-kernel-owner <at> vger.kernel.org] On Behalf Of Rob Landley
> Sent: Tuesday, July 10, 2007 12:48 AM
> To: H. Peter Anvin
> Cc: Kunai, Takashi; holzheu <at> linux.vnet.ibm.com; Andrew Morton;
> linux-kernel <at> vger.kernel.org; lf_kernel_messages <at> linux-foundation.org;
> mtk-manpages <at> gmx.net; jack <at> suse.cz; randy.dunlap <at> oracle.com;
gregkh <at> suse.de;
> pavel <at> ucw.cz; tim.bird <at> am.sony.com; gh <at> us.ibm.com;
arjan <at> infradead.org;
> sam <at> ravnborg.org; jengelh <at> computergmbh.de; joe <at> perches.com;
> auke-jan.h.kok <at> intel.com; hansendc <at> us.ibm.com; davem <at> davemloft.net;
> Valdis.Kletnieks <at> vt.edu; kenistoj <at> us.ibm.com; schwidefsky <at> de.ibm.com;
> heiko.carstens <at> de.ibm.com; linux-doc <at> vger.kernel.org
> 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.
>
(Continue reading)

Permalink | Reply | 0 comments |
headers
Rob Landley | 10 Jul 2007 18:12

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...
(Continue reading)

Permalink | Reply | 104 comments |
headers
Rob Landley | 10 Jul 2007 18:25

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.
(Continue reading)

Permalink | Reply | 12 comments |

Gmane