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.
-
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]
