On Mon, 23 Jul 2007 19:21:13 -0700 Randy Dunlap wrote:
> On Mon, 23 Jul 2007 17:12:38 -0700 Andrew Morton wrote:
>
> > On Sat, 21 Jul 2007 11:17:58 +1000
> > Rusty Russell <[email protected]> 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?
A: Nope, kernel-doc won't weave the code + docs together based on a
prefix and order number (e.g., H:310).
Neat as that is, I'm concerned that it will be difficult to maintain
(the order numbers at least -- or are they just difficult to set up
the first time?).
Advantage: it does keep the source code + doc text together.
Martin (former kernel-doc maintainer) was going to come up with
some way to do this, but he abandoned it.
---
~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 [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]
