linux-kernel - Re: [PATCH 1/7] lguest: documentation pt I: Preparation

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]

Date:	Mon, 23 Jul 2007 19:21:13 -0700
From:	Randy Dunlap <rdunlap@...otime.net>
To:	Andrew Morton <akpm@...ux-foundation.org>
Cc:	Rusty Russell <rusty@...tcorp.com.au>,
	Linus Torvalds <torvalds@...ux-foundation.org>,
	lkml - Kernel Mailing List <linux-kernel@...r.kernel.org>,
	virtualization <virtualization@...ts.linux-foundation.org>,
	Rob Landley <rob@...dley.net>,
	"Randy.Dunlap" <rdunlap@...otime.net>
Subject: Re: [PATCH 1/7] lguest: documentation pt I: Preparation

On Mon, 23 Jul 2007 17:12:38 -0700 Andrew Morton wrote:

> On Sat, 21 Jul 2007 11:17:58 +1000
> Rusty Russell <rusty@...tcorp.com.au> wrote:
> 
> > The netfilter code had very good documentation: the Netfilter Hacking
> > HOWTO.  Noone ever read it.
> > 
> > So this time I'm trying something different, using a bit of
> > Knuthiness.  Start with drivers/lguest/README.
> 
> um.
> 
> I'm OK with merging patches and given lguest's newness, the timestamp on
> these patches, the fact that they don't change code generation (right?) and
> my reluctance to carry large do-nothing patches for two months, I'd be OK
> with squeaking them into 2.6.23.
> 
> But I worry that you're proposing adding what appears to be new
> Documentation-related machinery and infrastructure when there's already
> increased activity in that area from other people and we might all be
> headed in different directions and stuff.
> 
> So first I think we'd best form a kernel kommittee and mull this for a
> while (preferably months) to screw you around as much as poss, OK?  ;)
> 
> Items for consideration would be:
> 
> - if this stuff is good, shouldn't other code be using it?  If so, is
>   this new infrastructure in the correct place?

I wouldn't mind having a new doc infrastructure, but I don't see this as it.

> - if, otoh, this infrastructure is _not_ suitable for other code, well,
>   what was wrong with it?

I think that we don't want to give up html/pdf/ps output formats in
favor of just text or C source code.  If we do continue to have
multiple "rich" output formats, we need even more rich syntax rules
than we have right now.  OTOH, if we dump all of those rich output
formats, we have less tool spice that is needed.

(I'm not ignoring Andrew's question here.  I'm just applying the
7 patches/series and looking at it more.)

> - if the requirement is good, perhaps alternative implementations should
>   be explored (dunno what).

Yes, but I dunno what either.


> IOW, I'd be interested in hearing Rob and Randy's opinions on it all,
> please.

It's great that Rusty took the time to produce all of this documentation.
Few people do that today.

Were current kernel-doc tools not sufficient?  If not, why not?

---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***
-
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/