On Tuesday 03 July 2007 15:58:52 Andrew Morton wrote: > On Sun, 1 Jul 2007 01:05:59 +0200 > > Jesper Juhl <[EMAIL PROTECTED]> 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 [EMAIL PROTECTED] 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 [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
