lkml.org 
[lkml]   [1998]   [Oct]   [22]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    /
    Date
    From
    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:

    ftp://egcs.cygnus.com/pub/egcs/infrastructure/autogen.tar.gz

    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:

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

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

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

    (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 majordomo@vger.rutgers.edu
    Please read the FAQ at http://www.tux.org/lkml/

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