Including the result of an external program

[Gary Lawrence Murphy <garym@xxxxxxxxxx>]

I hope I'm not wearing out my welcome with these incessant questions ;)

Further to the earlier post on including stdin into a document, I have
a wish-list item that seems so common and general a task, someone must
have worked out a solution: I'd like to pass parameters to an external
program from within an SGML tag and replace that tag with the output
results.

In the Linux Kernel, we have a new Documentation/DocBook project which
includes a small parser to extract comments from C source code and
generate a raw DocBook <RefEntry> element; it is similar in effect to
javadoc or perldoc and we hope to encourage developers to use this to
create automatic API docs for the Linux kernel.

Right now, it is awkward and I'd like to streamline it.  Tim Waugh
created the C source parser and a utility which takes an SGML file,
hunts for patterns like

    <sect1><title>The Directory Cache</title>
    !Efs/dcache.c
    !Iinclude/linux/dcache.h
    </sect1>

which is transformed into pure SGML with the output of the C parser in
place of those odd tags.  I think this introduces an extra layer of
complexity which may discourage authors from using the system; I would
much rather code the above as something more SGML-ish, maybe

    <sect1><title>The Directory Cache</title>
    <refEntry role="module">fs/dcache.c</refEntry>
    <refEntry role="header">include/linux/dcache.h</refEntry>
    </sect1>

Now, of course, that won't work because refEntry requires more
structure; I looked at olink, but it makes a _link_ to the other
material and we want it inline.  

Is there an elegant way to do this? Can I define entities at the top
of the file which, instead of filenames, are exec calls, and then
just plunk those entities in where they fit?

My goal is to have source documents that pass onsgmls.

I looked at a customizing layer for the DTD, but this may not be
feasible when we want DocBook-novice contributors to create content;
we could distribute a DTD file which defines a new tag or changes the
behaviour of refEntry, but having an odd DTD may cause too much
confusion (I'm open to debate on this).  

This seems a general problem; is there a general solution?  An example
in the DocBook book shows an external search program, but this is
meant as a secondary page of a web site and not as something to insert
inline SGML source.  Index-generator or bibliographic programs are
also similar, but a makefile could easily call an external program
because the target filename is static and declared in the makefile and
the output is amiable to being in its own file; in our case, we could
still generate external files, but the target C language file is only
known in the main SGML source code.

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


 DSSSList info and archive:  http://www.mulberrytech.com/dsssl/dssslist