OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Re: [docbook] Is DocBook the right tool for this (source code examples with interspersed output and embedded links)?

Hi Stephan,
Thanks for the detailed explanation. I think you can keep this setup and just adapt the Perl script to generate DocBook XML with crossrefs and highlighting added to the code examples.

Bob Stayton
Sagehill Enterprises

On 5/30/2014 3:00 AM, Stephan Petersen wrote:

Hi Bob,

thanks for your reply.

One key question: Can the code samples in the documentation be marked up
with inline XML elements?  I ask this because DocBook's tools can import
working source code files as part of the content, and can automatically
apply highlighting like colors to certain languages.

However, the highlighting feature uses configuration files specific to
each programming language, and currently there are no config files for
fortran, pascal, or basic.  And the links to the reference pages would
not be automatically formed.

But if you are copying the code samples into DocBook XML and applying
markup, then the language support for automatic highlighting is not
needed, and you can add element markup to form the links.

I infer from your statement that "whatever documentation tool I use
doesn't need to touch this code" that the code samples are copied into
the XML, and therefore could be marked up manually to form the
highlighting and the links.

Actually "whatever documentation tool I use doesn't need to touch this
code" referred  to the source code of the thermochemistry library
itself, meaning that I don't need a tool such as doxygen that tries to
cobble the documentation found in structured comments for all the
exported functions of the library source.

What should ideally happen is that the authoring tool works as much as
possible with the original source code of the short *example programs*
which illustrate the use of the library's functions and constitute a
major part of the programmer's manual.

What happens, at least in the present version of the documentation, is
roughly this:

1) The examples that I wrote are in this form:

File cac3.in.c

/* Program cac3 */
/* Display the version number of ChemApp */

#include "cacint.h"

int main()
   LI noerr, version;

   /* Initialise ChemApp */

   /* Get version number of ChemApp*/

   printf("This program has been compiled "
	 "with ChemApp version %li\n", version);

   return 0;


The line printf("###include###\n") makes sure I have a keyword in the
output that allows the code and output subsequently to be mixed properly.

2) This code is compiled, run, and the output stored to cac3.res:

This program has been compiled with ChemApp version 642

3) A Perl script reads cac3.in.c, deletes the printf("###include###\n")
line and some other things such as svn keywords in a header block and
writes cac3.c, which is the "end user" version of the example program to
be included in the library's distribution package / installer.

4) Other Perl scripts read cac3.in.c, adds Yodl markup for syntax
highlighting and adds xrefs for each call to any of my library's
functions to the section in the manual where that function is
documented, and replaces the printf("###include###\n") line(s) with one
or more output chunks read from the cac3.res output file.

This system makes sure

- I never have to fiddle manually with any markup of an example's source

- whenever the library code changes or the code for an example, a simple
"make" is enough to recreate the docs from scratch, including the actual
up-to-date output from the examples.

- all calls to my library's functions in all of my example codes are
cross-linked with the sections where the function is documented (output
is HTML and PDF via latex).

- adding a new code example is dead simple, again, no fiddling with
markup necessary. Just sprinkle printf("###include###\n") lines where
useful and that's it.

The reason why I do it that way is the end user of my library. I firmly
believe that the end user gets the maximum out of code examples that
way: they are easily readable, because they contain the output in
chunks, right where you want to demonstrate the effects of calling a
certain function with certain parameters, it's syntax-highlighted, and
cross-referenced with the sections defining the functions. At the same
time existing code examples are easy to maintain, and new ones easy to
add, especially because example code and markup are completely separated
from each other (other than the printf("###include###\n") lines, so to
say). Again the end users benefit, because new functions can be
documented with examples extremely fast.

When I started a couple of weeks ago looking for an authoring tool that
would replace my old Yodl-based tool chain, I had no idea it would still
be as tricky to find such a tool as in the 90's :-).

But it's not like Yodl does this out of the box, I need a set of Perl
scripts to pre- and postprocess my examples, and I'm not averse at all
to do similar customizations with other authoring tools. I just hope
it's not more difficult as it is in my present setup -).

All the best,


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]