linux-kernel - Re: Documentation:Update the INDEX of the documents

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-Id: <200902251330.49640.rob@landley.net>
Date:	Wed, 25 Feb 2009 13:30:48 -0600
From:	Rob Landley <rob@...dley.net>
To:	Theodore Tso <tytso@....edu>
Cc:	Yang Hongyang <yanghy@...fujitsu.com>, netdev@...r.kernel.org,
	"David S. Miller" <davem@...emloft.net>,
	linux-kernel@...r.kernel.org,
	Andrew Morton <akpm@...ux-foundation.org>,
	linux-doc@...r.kernel.org, mtk.manpages@...il.com,
	rdunlap@...otime.net
Subject: Re: Documentation:Update the INDEX of the documents

On Wednesday 25 February 2009 08:59:50 Theodore Tso wrote:
> On Wed, Feb 25, 2009 at 03:16:59PM +0800, Yang Hongyang wrote:
> > There are so many 00-INDEX file that are missing description of the
> > current files in the dir.  Such as 00-INDEX in
> > Documentation/x86/,Documentation/networking/,Documentation/ and so
> > on.
> >
> > It's a large amount of work for someone to go through all these
> > documents and make summaries.
> >
> > I'm willing to do some of the work but if someone else pick these
> > up(especially the authors of these new files) it will be a great
> > help.^_^
>
> Before you embark on this large amount of work, we should probably ask
> a question first --- how useful are the 00-INDEX files?  I don't find
> them particularly interesting, given that my normal way of finding
> documentation in the Documentation directory is:
>
> find . -type f | xargs grep <keyword>
>
> Or, if I have a git tree of the Linux sources handy:
>
> git grep <keyword> -- Documentation
>
> If folks do find the 00-INDEX files useful, my suggestion would be to
> make a way of automatically extracting them from the individual files
> and/or directories, and then making the 00-INDEX files to be
> automatically generated.

I have a script that automatically generates html indexes from them for 
http://kernel.org/doc/Documentation which is at least a use. :)

I'd be happy to generate those html indexes from something else, but there 
isn't an obvious reliable source of single line comments in the files 
themselves.  For a lot of 'em you can take the first nonblank line and ignore 
things like the trailing colon in unshare.txt, and maybe you could even 
automatically ignore things like the sentence fragment at the end of kref.txt.

But what do you do about the first like of IRQ-affinity.txt being 
"ChangeLog:", or hw_random.txt starting with "Introduction:"?  (And of course 
logo.gif isn't a text file.  And we haven't even gotten to the 
subdirectories...)

Rob
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@...r.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/