Re: GSoC proposal: NetBSD Kernel Documentation Management Toolchain

[Vladimir Kirillov <proger%wilab.org.ua@localhost>]

On 19:04 Tue 05 Apr, Vladimir Kirillov wrote:
> ... following *shortcomings*
> (mostly in result of requiring manual intervention):
> 
> - code references are not always complete and synchronized immediately
>   with manual pages
> - function signatures may be outdated
> - intro(9)-like pages may be left without attention (pages which mostly
>   contain references to other)
> - no documentation coverage control
> 
> I intend to address these shortcomings in this project by implementing
> a tool to manage kernel documentation based on the interface XML 
> specification.

Regarding latest ddb discussions, there're a couple of more use cases
regarding the documentation only:

- options DDB_VERBOSE_HELP gathers information from description strings,
  which are supplied within the struct db_command arrays.
 
ddb(4) manual page is mostly asynced with the rest. A great example
is the sys/arch/sparc64/sparc64/db_interface.c file (so many machdep
debugging information in sparc64 makes me really want to get such
machine :)

Another example would be sysctl(7) manual pages which are not coherent
with the information provided by sysctl -d.



NB:
I want to draw your attention here that I do not want to entirely
replace current mandoc manuals with XML-to-mandoc converters and
force developers to use XML to do documentation, I rather
want to patch the appropriate sections of the most documents
which require patching.

I intend to research on the topic of breaking down the kernel
subsystems and consolidation of their programming interfaces and
any other resources they are designed to provide and/or control.

This research must be beneficial for any management tasks which rise
aside actual kernel hacking:
        - providing interfaces for userspaces (there are tons
           of ways to copy configuration information from
           kernel to user and vice-versa like cdevs/ioctl/proplib/whatever,
           and writing such code takes a notable amount of time)
        - reusing kernel code for userspace (what rump and crash do)

        - documentation (trying to do here)

        - many more (suggest!)

Each kernel subsystem is a component which has it's impact on the
kernel's ecosystem with it's own tentacles.

I want to augment each kernel subsystem with it's own XML specification
whose purpose it to carry all the necessary metadata and dependencies,
because it extends way further a single kernel option and a list of files.

Of course such specifications will emphasize on the kernel modularity,
which is currently exercised by projects like rump, dtrace, zfs
within NetBSD.

The metadata contents may be variant for any subsystem:
sysctl tunables, ddb commands and so on.
The next idea would be to use this metadata to generate the code
which is more convenient to be generated automatically rather
then implemented manually (half of ddb commands are used
to print data structures, which definitely can be handled faster,
easier and more elegant).

So the first appliance where I want to exercise the XML idea is the
kernel documentation, where the research gets initial input
from the existing documentation and code (see proposal implementation
stages 1-2), and returns improved documentation on the output.
The intermediate XML specs will be the input for all the stuff above
and on my ideas page.

I hope you share my enthusiasm about this ;)