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    [from the cache]
©2003-2011 Jasper Spaans. Advertise on this site