This is the mail archive of the davenport@berkshire.net mailing list for the Davenport project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

Re: DAVENPORT: source code in docbook


/ Chris.Prael@eng.sun.com (Chris Prael) was heard to say:
| > 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>
[...]
| > 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.)

In that case, the inlinegraphic hack or any extension that you use
to make the processor slurp up the source and inject it into the
output will solve the problem for you.

In the past, I've most often encountered the problem of wanting to
incorporate source code into my documentation and add annotations
(tutorial comments, pointers to the intersting bits, etc.) while
simultaneously being absolutely certain that the sources in the
documentation were the sources used to build the application.

DocBook is about documentation, so you're absolutely right that
most of the thought has been about illustration of code rather
than incorporation of source. Flat incorporation of source code
doesn't seem to be a fundamentally useful procedure since, as you
say, you can just "read the source".

                                        Cheers,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | ...it is significant that we are
http://www.oasis-open.org/docbook/ | called the 'information society'
Member, DocBook Editorial Board    | -- not the thinking society, not
                                   | the deliberative society, not the
                                   | society of reason and
                                   | rationality.--Lloyd Morrisett


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]