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/
[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]
