Rob Landley | 3 Aug 01:58 2007
Picon

http://kernel.org/doc

I've had an _insane_ couple of months (laptop died shortly before OLS, had to 
visit relatives who couldn't make the wedding, spent two weekends at Eric 
Raymond's house attacking a large todo list, and finally moving back to 
Austin), but I've finally rolled to a stop in a place I can call "home" and 
I'm trying to get lots of near-ready things finished and checked in.

The next few posts are about various documentation bits of interest having to 
do with kernel.org/doc.  Some of these have been around for a while and just 
never mentioned here, some I'm just finishing up and checking in now as I go 
down the 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-doc" in
the body of a message to majordomo <at> vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Rob Landley | 3 Aug 01:59 2007
Picon

http://kernel.org/doc.

So if you look at http://landley.net/hg/kdocs/ you'll notice a mercurial 
repository for this project, which I've had for a while but I'm trying to be 
more rigorous about checking stuff into it.

Yes, I take patches. :)

Possibly I should note this repository from the main kernel.org/doc page, but 
I really really really really need to redo that page.  (That's its own 
post...)

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-doc" in
the body of a message to majordomo <at> vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Rob Landley | 3 Aug 03:39 2007
Picon

Refreshing Documentation from the kernel tarball.

The current automation infrastructure refreshes 
http://kernel.org/doc/Documentation and http://kernel.org/doc/htmldocs from 
the linux source control repository on kernel.org.  The script to do this is 
in the mercurial archive at: http://landley.net/hg/kdoc/make/make.sh

Yes, I'm using the mercurial version of the kernel repository instead of the 
git version; it's the same data and updated live when Linus checks stuff in.  
(It would be easy enough to switch to git if there's a reason, but I prefer 
Mercurial.)  The archive update at the beginning assumes you have a kernel 
mercurial archive initialized in that directory on your machine, see the 
commented out code near the top that shows how to do that.  The paths are all 
relative to the user's home directory, that could be changed I just don't 
have a personal reason to do so.

Copying Documentation is trivial.  The "make htmldocs" stuff less so; you need 
xmlto installed.  I used to have a patch to have the kernel's makefile 
produce the "one big chunk" versions, but I decided it was far easier to just 
_do_ it than to try to make the kernel infrastructure do anything fancy.

I'm producing the "nochunks" and the "chunks" versions of the html: A URL 
ending in .html shows you the "one big file", strip that off and it's a 
directory containing the small chunk versions.  Which one you want turns out 
to be a matter of personal preference and it's easy enough to provide both.  
(I stole this idea from Douglas Gilbert over in SCSI land, see 
http://sg.torque.net/scsi/SCSI-2.4-HOWTO.html and 
http://sg.torque.net/scsi/SCSI-2.4-HOWTO for example.)

The "background process and then wait for it to finish" is because I have a 
core 2 duo laptop and I want to take advantage of the SMP, xsltproc is 
_really_slow_.  Yeah, it's an unnecessary complication but I wind up running 
(Continue reading)

Rob Landley | 3 Aug 04:41 2007
Picon

Internationalization.

This month I participated in several long threads about translating kernel 
documentation into other languages, primarily Japanese and Chinese.  (I cc'd 
some but not all of them here.)

http://kernel.org/doc now links to the websites http://www.linux.or.jp and 
http://zh-kernel.org, which are respectively japanese and chinese linux 
kernel communities that have offered to translate documentation.  (I asked if 
it made more sense to link directly to the documentation or to the top level 
communities, and was consistently told the top level.)

A big issue during the debate was that translating documentation encourages 
the creation of patches that cannot be merged into the kernel, because the 
developers of the patch don't have the English language skills necessary to 
submit their patch to linux-kernel and answer questions about it from other 
developers.  Matt Mackall proposed the position of language maintainer, 
someone to translate descriptions and questions to facilitate patch 
submissions from non-english developers.  I followed up up this and tracked 
down some candidates for the position.  A chinese language maintainer (Li 
Yang) has now accepted the position (see http://lkml.org/lkml/2007/7/12/199 
and http://lkml.org/lkml/2007/7/13/173 ) and along the way I wrote up a 
description of the position as I saw it.  (In this case, the language 
maintainer is actually a single point of contact for a mailing list of 
translators.  See the thread for details.)

Another issue is keeping translations up to date.  On the advice of Eric 
Raymond, I'm not hosting translated copies but instead linking to copies put 
on the web by the translators.  Eric has found that if he hosts translations 
of his writings, they never get updated.  If he links to translations hosted 
by the translators, they get updated.

(Continue reading)

Rob Landley | 3 Aug 04:44 2007
Picon

Lguest documentation.

Rusty Russell submitted some new kernel documentation infrastructure for 
lguest, triggered by running "make Preparation!" on the Linux kernel.  Rusty 
asked that I not add the output of this to kernel.org/doc, and I'm respecting 
the author's wishes here.

Rusty's request is at http://lkml.org/lkml/2007/7/25/524

Once the patch is merged I plan to point to the lguest README and note that 
interested parties need to run "make Preparation!" in the kernel directory 
(which I think is not currently sufficiently obvious from the README).

Rob

(Note, my definition of "merged" is "hits Linus's tree", not hits Andrew's.  
Also, it might have by now, due to my move and the week in California before 
that I'm a bit behind, but catching up.)
--

-- 
"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-doc" in
the body of a message to majordomo <at> vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Rob Landley | 3 Aug 05:07 2007
Picon

Updates to kernel-traffic.

Mark Miller (mirell <at> gmail.com) is picking up where Zack Brown left off, 
summarizing the linux kernel.  He was delayed starting the job (he graduated 
from college and then moved across town), but has made some progress despite 
this.

He spoke to Zack Brown and got a handover of the existing data files and build 
procedure (a fairly complicated system based on xml, xsl, nested makefiles, 
and requiring lots of strange tools to be installed), and spent a lot of time 
untangling it, cleaning it up, and figuring out how to make it work.

He's now reproduced most of the existing archive from the source files, and is 
starting to add new content.  His version is currently hosted at 
http://mirell.org/kernel-traffic
--

-- 
"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-doc" in
the body of a message to majordomo <at> vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Rob Landley | 3 Aug 05:24 2007
Picon

Mel Gorman's memory management book.

I spoke to Mel Gorman at Ottawa Linux Symposium, and got permisson to host 
HTML and PDF versions of his book under the Open Publication License.  He 
sent me the book in both formats, along with the license terms, and I put 
them all up at http://kernel.org/doc/gorman/

The license essentially allows redistribution but not useful modification, 
which is why I didn't receive or post copies of the source files (in latex, I 
think).  Mel would have to check with his publisher about modified copies of 
the actual book, but he's of the opinion it would be a herculean task to try 
to keep the book up to date anyway.  (Mel himself doesn't have the time or 
energy to do it.)

However, Mel is thinking of breaking it into a series of smaller articles, 
which would be easier to keep up to date.  I put him in touch with Don Marti 
of LinuxWorld, who I also spoke to at OLS and who had expressed interest in 
publishing that kind of article.  Don offers publication terms that allow the 
resulting articles to be used as open source documentation distributed with 
projects.  Don sent Mel and myself the actual terms, which I put at 
http://kernel.org/doc/gorman/freelance.tex until I figure out what I want to 
do with them.  (I'm not related to LinuxWorld and this isn't an endorsement, 
but a way to get documentation writers paid for writing documentation that 
the community can distribute is potentially useful...)

Meanwhile, the book's up.  I haven't had time to actually read it yet, let 
alone index any of its contents in with the rest of the heap.
--

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

Rob Landley | 3 Aug 05:28 2007
Picon

Re: Updates to kernel-traffic.

On Thursday 02 August 2007 10:07:31 pm Rob Landley wrote:
> Mark Miller (mirell <at> gmail.com) is picking up where Zack Brown left off,
> summarizing the linux kernel.

The missing words here are "mailing list".

Too many hours staring at a screen today, trying to catch up...

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-doc" in
the body of a message to majordomo <at> vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Rob Landley | 3 Aug 05:50 2007
Picon

Ottawa Linux Symposium papers.

Go to http://kernel.org/ols

I took the OLS proceedings volumes for each year from 2002 to 2007, mirrored 
them, and split them up into individual papers.  I am now reading and 
summarizing those papers (see http://kernel.org/doc/ols/2002), in order to 
index them by topic.  (Some papers have abstracts, but these mostly mention 
the questions that motivated the paper, not the answers provided, and are not 
sufficient for indexing the papers.)

The scripts to split each volume into individual papers are linked from 
http://kernel.org/doc/ols, and are python scripts using the pdftk package.  
(I just checked them into the mercurial repository.  At some point I need to 
reproduce the web page from the repository, plus the various scripts to 
re-download the data I'm mirroring and process it, but I'll get to that...)

Some years (2004 and 2007) are available already split up, but I re-split them 
to consistently put the OLS boilerplate pages (the title page and credits 
page) at the end of each PDF instead of the beginning.  (*shrug* six of 
one...)

I've contacted Andrew J. Hutton of OLS (ajh <at> linuxsymposium.org), who thinks he 
may be able to dig up some of the earlier proceedings in electronic format.  
So far, he hasn't had time to do this.  I've tracked down a few (such as Greg 
KH's 2001 paper on hotplug).

Tim Bird of CELF has expressed interest in finding volunteers to help 
summarize.  http://lkml.org/lkml/2007/7/16/501

There are also audio recordings from earlier years.  Haven't quite figured out 
how to approach that yet.  (Try to do transcripts, perhaps?  Voice 
(Continue reading)

Randy Dunlap | 3 Aug 07:02 2007
Picon

Re: Internationalization.

On Thu, 2 Aug 2007 22:41:50 -0400 Rob Landley wrote:

> This month I participated in several long threads about translating kernel 
> documentation into other languages, primarily Japanese and Chinese.  (I cc'd 
> some but not all of them here.)
> 
> http://kernel.org/doc now links to the websites http://www.linux.or.jp and 
> http://zh-kernel.org, which are respectively japanese and chinese linux 
> kernel communities that have offered to translate documentation.  (I asked if 
> it made more sense to link directly to the documentation or to the top level 
> communities, and was consistently told the top level.)
> 
[snip]
> 
> Another issue is keeping translations up to date.  On the advice of Eric 
> Raymond, I'm not hosting translated copies but instead linking to copies put 
> on the web by the translators.  Eric has found that if he hosts translations 
> of his writings, they never get updated.  If he links to translations hosted 
> by the translators, they get updated.
> 
> I also don't recommend checking translated documentation into the kernel 
> tarball, but that isn't my call.  I notice that Greg KH disagrees with 
> basically every issue I've ever talked to him about.  I haven't tried reverse 
> psychology on him yet to see if it's causal, but see 
> http://lwn.net/Articles/242541/ and note that I expect it to be merged.  
> *shrug*  Oh well.  (I'm not maintaining it, I can't even read it.  Not my 
> problem.)

Has been merged.  FWIW, I agree that the translations are better kept
outside the kernel tree, at various language-specific sites.
(Continue reading)


Gmane