[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 bobs@sagehill.net 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 */ tqini(&noerr); /* Get version number of ChemApp*/ tqvers(&version,&noerr); printf("This program has been compiled " "with ChemApp version %li\n", version); printf("###include###\n"); 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 ###include### 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 code - 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, Stephan
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]