[lkml]   [1998]   [Oct]   [22]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
Messages in this thread
    SubjectThe Kernel Documentation Dilemma
    I have thought about the problem for a number of years.
    After having taken several approaches, I have found that
    a distributed-centralized approach works best for me.
    I write a central document that talks about the overall
    picture and then I drag in the minutia from wherever the
    minutia get implemented. I have an example of this in:

    The main document is 26K and the compiled .texi file is 117K.
    It depends upon an included extraction program `getdefs'
    to extract information from stylized comments and passes it
    along to the autogen program. That program then takes those data
    and instantiates the templatized main document.

    Why do I think this is interesting? Because I *also* take
    those same definition data and, using different templates,
    I construct various tables needed to make autogen operate.
    I *also* use these data to construct program option tables
    so that library routines handle envrionment variables, rc files,
    usage text, option processing, *storing* of rc files,
    and so on and so on.

    The comment syntax is fairly innocuous:

    /*=group_name member_name
    * attribute_1: value
    * attr2:
    * attr2: this copy of attr-2 has a value
    * descrip: Something about member-name
    * doc:
    * Here I write a bunch of documentation
    * about the member_name member of the group group_name.

    From this, you can produce documentation:

    This is a long description of the group-name area of the kernel.
    Included in this area are several functions:

    `for each member-of-group_name ; do`
    * grp ${member_name}:: ${descrip}
    @end menu

    `for each member-of-group_name ; do`
    @cindex grp ${member_name}
    @node grp ${member_name}
    @section ${descrip}

    This function is implemented in ${filename} near line ${fileline}.

    (This syntax is not the real syntax. It is, perhaps, pseudo-code :)
    Check out the real doc. `getdefs' is a section under the `Add-Ons' chapter.)

    Bruce Korb
    Korb at DataDesign dot com

    To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
    the body of a message to
    Please read the FAQ at

     \ /
      Last update: 2005-03-22 13:45    [W:0.071 / U:0.636 seconds]
    ©2003-2017 Jasper Spaans. hosted at Digital OceanAdvertise on this site