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 [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 > 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 ([EMAIL PROTECTED]) Work - 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/
