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

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

>>>>> "M" == Michael Wiedmann <michael.wiedmann@detewe.de> writes:

    M> Jorge Godoy wrote: ...
    >> This solution would require me to actually put the source in
    >> the document. Isn't there any solution that allow me to get the
    >> C file as an entity? This would be much more interesting since
    >> I'd always have

The solution we use with the Linux kernel-docs (in the 2.4 kernel
sources) is to use a pre-processing stage and a program based on the
gnome weasel software for translating C sources into DocBook
RefEntries ... the process is not perfect, and it requires a specific
function-header-comment convention, but it lets us produce current API
docs directly from the sources.

Using weasel, you could, for example, create your C API RefEntry files
and then define entities for these to insert where needed.

Of course, this is only really useful for API documentation; if you
wanted to illustrate algorithms with large stretches of source files,
then the best you could do is to write a wrapper script to create

<programlisting>
<![CDATA[
(include source file)
]]>
</programlisting>

this could be managed through a makefile.

-- 
Gary Lawrence Murphy <garym@teledyn.com> TeleDynamics Communications Inc
Business Innovations Through Open Source Systems: http://www.teledyn.com
"Computers are useless.  They can only give you answers."(Pablo Picasso)