[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: Re: DOCBOOK-APPS: Including C source code in a document
>>>>> "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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Powered by eList eXpress LLC