lkml.org 
[lkml]   [2007]   [Jul]   [23]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    /
    Date
    From
    SubjectRe: [PATCH 1/7] lguest: documentation pt I: Preparation
    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@rustcorp.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?

    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 majordomo@vger.kernel.org
    More majordomo info at http://vger.kernel.org/majordomo-info.html
    Please read the FAQ at http://www.tux.org/lkml/

    \
     
     \ /
      Last update: 2007-07-24 05:05    [W:0.034 / U:209.436 seconds]
    ©2003-2016 Jasper Spaans. hosted at Digital OceanAdvertise on this site