Re: DAVENPORT: source code in docbook

[Chris.Prael@eng.sun.com (Chris Prael)]

> From owner-davenport@berkshire.net Thu Jun 24 09:51:35 1999
> Subject: Re: DAVENPORT: source code in docbook
> From: 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. 

One of the major points here is that the text in the source file be
excluded from any compilation or building.  Having the source text
compiled/built is, IMHO, a major part of the problem.  Source text
should not be compiled or built, simply transmitted.

> 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.

Exactly!   And this is (or should be) fairly simple for programmers to
deal with (or writers, for that matter).

> 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>

Thank you for the suggestion.  I'll give this a spin and see how it
plays.
>  
> 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.

This paragraph tends to illustrate one of my original points: most
thinking has been about illustrations of code (in other words, listings) 
and not about source code.  

My purpose is to present source code, not listings.  As a result, 
annotation is quite unacceptable.  (Besides which, it is completely
redundant.  That is what we have comments for.)

> FWIW, my DSSSL stylesheets support this extension.
> 
>                                         Cheers,
>                                           norm

Cheers and, again, thanks,
chrisp