Re: DOCBOOK-APPS: Including C source code in a document

[Gary Lawrence Murphy <garym at canada dot com>]

>>>>> "J" == Jorge Godoy <godoy@conectiva.com> writes:

    J> I thought this very interesting. In fact, people here at our
    J> Linux development department (you might know Rik, Acme, and
    J> other) have told me about this usage in Linux Kernel.

Oh yes, I've heard of them ;)  Sure wish I could twist the arm of
just one of them to participate in the kernelbook project ;)

    J> Could you send more information on this? I think that other
    J> people here on this list are interested in documenting some
    J> APIs or are interested on this solution for other usage
    J> possibilities.

Certainly.  First, the solution is not perfect, but it works. In the
kernel-docs, we have a template file format which violates sgml
validation (making it difficult to write documents) and in these we
include simple markers to show where and what source file is to be
processed, and whether this is an include file or a source file.

During the make, the template is scanned by docgen to parse out the
command line, run the parser and have the output merged on the fly
with the rest of the template to produce one large SGML output.

I'd love to change this process.  Ideally, I want an SGML tag in the
document which specifies the source file, and have the parser generate
into its own file which can be defined in the document as an entity.

There have been some discussions about doing this on the DSSSL list
and I have some notes contributed by readers there for ways to do this
if anyone is interested, but there is still a basic problem of needing
to maintain the list of included files in both the SGML source (as
entity defs) and in the Makefile.

Nonetheless, this system works, even if it is cludgy.  

I have been poking at the weasel program, a utility which is only
found on the gnome CVS archive and which was the basis for the
kerneldoc program.  This program is really a dead-stupid C-language
comment parser which scans the sources looking for highly structured
comment blocks much like the Javadoc program.  Files with no special
comments produce no output.  I have also downloaded doc++ but have not
had the chance to look at it.

I would be much happier with a general purpose C2db converter which
could parse prototypes and give a basic RefEntry for the function
without depending on special comment blocks.  For example, our chances
of getting Linux developers to insert the proper structure comment
blocks is approximately the same as winning the Readers Digest Lottery

There are several C-to-postscript pretty print programs, so there must
be an easy way to auto-extract RefEntry output. The key trouble seems
to be a lack of a decent GCC-compatible parser grammar; I know from my
experience in trying to run LXR and reverse-engineering programs
against the Linux sources that C in Linux goes way beyond the limits
of simple K&R based grammars; we might get a general solution for
simple C programs, but I expect I'll be out of luck in my kernel
parsing.

-- 
Gary Lawrence Murphy <garym@linux.ca>: office voice/fax: 01 519 4222723
T(C)Inc Business Innovations through Open Source http://www.teledyn.com
M:I-3 - Documenting the Linux kernel: http://kernelbook.sourceforge.net
Love Linux?  We need authors/reviewers - http://www.teledyn.com/authors