Re: Documentation of kernel messages (Summary)

[Rob Landley <rob@landley.net>]

On Friday 03 August 2007 10:52:06 pm Greg KH wrote:
> On Fri, Aug 03, 2007 at 03:32:04PM -0400, Rob Landley wrote:
> > These days I'm trying to create an html index that links into
> > Documentation in a coherent order (with categories and everything), and
> > using automated tools to detect files that aren't linked to, or links
> > that point to a file that isn't there anymore.  This is obviously still a
> > work in progress, but I think it's a better approach.
>
> Better than cleaning up what we have in the kernel source tree?

Yes, I just said that.

> Why not work on that first, then the "automated" type stuff would be much
> easier to do later, right?

How does an automated 404 checker that identifies files nothing's linking to 
get easier if the source files are in a different order?  They could be 
alphabetical in one big directory and that would work the same.

Moving Documentation around is pointless churn that does nothing to prevent 
you from adding language directories to the top level on a whim, as if there 
were only two instead of (as I pointed out last message), several dozen.  
(While Randy Dunlap's poking me to resubmit my patch to group the 
architecture documentation into an architecture subdirectory, you're adding 
language directories to the top level instead of in their own subdirectory.)

Documentation doesn't even cross-link to the output of make htmldocs (which 
has its own structure imposed on it due to being extracted from the kernel 
sources).  The kernel tarball has _two_ documentation sources that don't 
significantly cross-reference each other, and Rusty just submitted "make 
Preparation!" for lguest that's totally unrelated to either of them (and 
starts from a README file buried in the source code).  None of this links to 
the menuconfig help entries, and the only reference in Documentation/ 
to "make help" is in Documentation/kbuild/makefiles.txt which explains that 
its purpose is to list the available architecture targets (something it does 
not, in my experience, actually do).

The idea that the kernel Documentation directory is the master repository of 
kernel documentation is an unworkable fantasy.  The Documentation directory 
cannot index for all the kernel documentation resources out on the web, 
because it's in text not html.  Documentation was created on the assumption 
that it would contain all interesting resources, as text files, but that 
doesn't match reality.  Documentation is merely one resource among many, and 
to link _out_ you need HTML.

Some of the resources out there are organized chronologically, such as the 
Linux Journal archives http://www.linuxjournal.com/xstatic/magazine/archives, 
the Ottawa Linux Symposium papers (http://kernel.org/doc/ols), or the 
kernel-traffic archives 
http://www.kernel-traffic.org/kernel-traffic/archives.html.  Some have their 
own indexes, such as the Linux Weekly News kernel articles 
http://lwn.net/Kernel/Index/ and the Linux Device Drivers book 
http://lwn.net/Kernel/LDD3/.  Some are random bits picked out of developer 
blogs, found with google, reasonably coherent articles on wikipedia.  Some 
are huge self-contained lumps on specific topics such as Mel Gorman's mm 
documentation or lots of the embedded stuff.

So no matter what reorganization I do to Documentation, its structure (or lack 
thereof) is incidental to coherently indexing most of the kernel 
documentation that's out there.  (Right now the best index is "google" but 
that's only useful if you know what questions to ask.  But getting up-to-date 
versions of Documentation and the output of make htmldocs on the web lets 
google find it.  (Last year, back when I was still working on BusyBox, I did 
a google trawl for ext2 documentation to replace the horrible mke2fs busybox 
used to have, and the first three pages of hits did _NOT_ include a copy of 
Documentation/filesystems/ext2.txt.  Ironically, if you google for "ext2 
documentation" today the sixth hit is the unfinished ext2 documentation I'd 
just started to write before I found Documentation/filesystems/ext2.txt.)

Rob
-- 
"One of my most productive days was throwing away 1000 lines of code."
  - Ken Thompson.