Date:	Thu, 5 Jul 2007 11:12:35 -0600
From:	"Elyse M. Grasso" <emgrasso@...a-raptors.com>
To:	Rob Landley <rob@...dley.net>
Cc:	Andrew Morton <akpm@...ux-foundation.org>,
	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, Rob Landley wrote:

> 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
>
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

http://www.data-raptors.com    Computers and Technology
http://www.astraltrading.com   Divination and Science Fiction
http://www.data-raptors.com/global-cgi-bin/cgiwrap/emgrasso/blosxom.cgi WebLog
http://www.releaseteam.com  (egrasso@...easeteam.com) Work
-
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