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 <rusty@xxxxxxxxxxxxxxx> 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 *** _______________________________________________ Virtualization mailing list Virtualization@xxxxxxxxxxxxxxxxxxxxxxxxxx https://lists.linux-foundation.org/mailman/listinfo/virtualization
