[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.030 / U:0.332 seconds]
©2003-2018 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site