Re: DAVENPORT: source code in docbook

[Norman Walsh <ndw@nwalsh.com>]

/ Chris.Prael@eng.sun.com (Chris Prael) was heard to say:
[...]
| Now, before any sends me any lists of tags that will do this job, let me
| point out that docbook contains many tags that can contain ILLUSTRATIONS
| of source code.  This is dandy if one has no concerns about maintaining
| and providing accurate and current code that can be used by one's readers.  
| It is quite unacceptable if one is concerned about the quality and
| accessability of the source code in one's documentation.
[...]
| From what I have seen in the web site, it appears that this issue is a
| new one, as I see no indications of any attempt to correct the
| deficiency

I think you're right, this issue has never come up in quite this
way before.

Let me begin with an observation (which you're free to
dispute). There's no way to incorporate source code directly
into an XML document if you expect to make it part of the
compile/build cycle. I can imagine a literate programming system
that would allow it, but that would be difficult (at best) for
authors to deal with. The only practical way to make sure that
the source code in the documentation is the source code in the
product is to incorporate the source code into the documentation
by reference to the actual product sources.

The long-term answer for how to point at things is XLink and
XPointer. DocBook has a long history of using what is widely
supported and XLink and XPointer are the only things that are
going to get widely supported.

One short term answer is to abuse <inlinegraphic> as follows:

<programlisting>
<inlinegraphic format="linespecific" fileref="..\..\source\source.java">
</inlinegraphic> <!-- or <inlinegraphic.../> for XML -->
</programlisting>
 
If you need to annotate the program listing, it can be done in a
stand-off way with programlistingco and areaset. How you make
sure that the areas continue to be right as you edit the source
code is something I'm not quite sure of. Perhaps by dropping
comments in the source and using a separate tool to build the
areasets from the source.

FWIW, my DSSSL stylesheets support this extension.

                                        Cheers,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | Any idiot can face a crisis; it's
http://www.oasis-open.org/docbook/ | this day-to-day living that wears
Member, DocBook Editorial Board    | you out.--Anton Chekhov