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/
[Index of Archives]
[Kernel Newbies]
[Netfilter]
[Bugtraq]
[Photo]
[Stuff]
[Gimp]
[Yosemite News]
[MIPS Linux]
[ARM Linux]
[Linux Security]
[Linux RAID]
[Video 4 Linux]
[Linux for the blind]
[Linux Resources]
