Message-Id: <200707032058.26512.rob@landley.net>
Date:	Tue, 3 Jul 2007 20:58:25 -0400
From:	Rob Landley <rob@...dley.net>
To:	Andrew Morton <akpm@...ux-foundation.org>
Cc:	Jesper Juhl <jesper.juhl@...il.com>,
	Linux Kernel Mailing List <linux-kernel@...r.kernel.org>,
	Randy Dunlap <randy.dunlap@...cle.com>, trivial@...nel.org
Subject: Re: [PATCH][Documentation][resend] Add missing files and dirs to 00-INDEX in Documentation/

On Tuesday 03 July 2007 15:58:52 Andrew Morton wrote:
> On Sun, 1 Jul 2007 01:05:59 +0200
>
> Jesper Juhl <jesper.juhl@...il.com> wrote:
> > This patch adds descriptions for a number of missing files and
> > directories to the Documentation/00-INDEX file.
> > People really should learn to keep this file up-to-date when adding or
> > moving documentation...
>
> Or just delete it.  Does anyone use it?
>
> That's Rob's problem, I guess.

Documentation/* is a gigantic mess, currently organized based on where random 
passers-by put things down last.  I posted a couple of patches to do minor 
cleanups to it last month, but since then I've put that on the back burner, 
because Documentation/* can't do what I need.

I spent the first month of the documentation fellowship trying to find all the 
kernel documentation I could, and figure out how to organize it.  It would be 
easy to pile up a big heap (that's sort of what http://kernel.org/docs has 
now, and that's less than half of what I've tracked down), but the hard part 
is _organizing_ it.  I can't figure out what _isn't_ documented until I have 
a handle on what _is_ documented.  (And then I can worry about documentation 
being stale, incomplete, or simply wrong...)

I was looking at the Documentation directory in the kernel as the primary 
source of documentation and the core around which the rest could be 
organized: but it isn't.  Out on the internet there are 8 gazillion other 
sources of documentation for the Linux kernel: OLS papers, the LWN kernel 
article index, wikis, developer blogs, specifications, online books, things 
on sourceforge...  most of that is NEVER getting indexed into Documentation/* 
because it's HTML or PDF under various different non-gpl licenses, and the 
Documentation directory contains text files.

The fact that Documentation is text means it can't easily link out to 
resources that live on the web.  The index I need to organize all this stuff 
with must be HTML because huge chunks of it simply aren't local.  The kernel 
generates HTML documentation via "make htmldocs", but that can't even 
coherently link to everything in the Documentation directory today, let alone 
the whole web, because it's generated by grepping through the kernel sources 
and that imposes a strong structure on it that makes it bad for indexing 
things outside itself.  It can be linked _into_ by an external index, but it 
can't easily BE an index composed primarily of external references.  That's 
not what it's for.  So that's out too.

I intend to integrate the existing 00-index into the new index (the bare 
skeleton of which just went up at http://kernel.org/doc earlier today, 
although expect it to change a lot as links and sub-pages get added and I 
generally go "what was I THINKING?").  And I'll be adding in all the stuff 
that ISN'T in 00-index, too.  I need to set up a link checker to detect 404 
and also detect files that aren't linked from anywhere in my local set of 
directories...

I have a mercurial archive at http://landley.net/hg/kdocs which I'll accept 
patches into (it's deeply unimpressive at the moment, I'm working on it), and 
I'd like said patches cc:'d to linux-doc@...r.kernel.org which I'm trying to 
resurrect.  I also might shuffle all the stuff I'm mirroring (like 
http://kernel.org/doc/ols) into its own mirror/* subdirectory for easier 
mirroring if other people want a local copy of this stuff, I'm still trying 
to figure out the best way to organize all this.  (I'd prefer not to confuse 
google by having multiple live mirrors out on the web, but hey: it's a free 
country.)  

Keep in mind my previous laptop died a month ago, and my new one arrived the 
monday before OLS, at which my todo list got much longer.  I'm still catching 
up.  Organizing is the hard part.  Just _writing_ documentation is 
comparatively easy...

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@...r.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/

Powered by blists - more mailing lists