Sunday, April 05, 2009

CDK - The Documentation

In preparation for the CDK workshop later this month, I am writing up my material for my kick-off presentation of the workshop. So, I better make it good. Using LaTeX at least overcomes my laziness which always made Word documents look stupid. Even default LaTeX looks good:

Clearly, any such documentation becomes quickly outdated, in particular when source code fragments are involved. Yes, CDK 1.2 is API stable, but only for the core classes. Moreover, I hope that the documentation will survive CDK 1.4 or 2.0 or whatever the next stable version is.

Therefore, I need to source code fragments compilable. R has the magnificent Sweave, and I wanted for a long time something similar. While I do not have something that powerful yet, at least my current set up allows me have code that both compiles and embeds in the LaTeX. The system allows me to write both Java application code as BeanShell scripts. No clue yet what I will use in the workshop, maybe even both. Like Sweave, it even saves output, and I can include that in the LaTeX source too. The code fragments can either go in as a verbatim section, or as a listing, depending on what I find more appropriate.


  1. Egon, I'm curious - is this documentation to be presented in front of an audience, distributed as a booklet/pamphlet, or something else?

    One thing I like about interactive Ruby is that presenters can use it to great effect when discussing how their code works. Do you have the same thing in mind for BeanShell?

  2. The workshop will be an interactive presentation, where all participants will have a running BeanShell or maybe Eclipse (Christoph?).

    But, the documentation they will get as PDF too, and when the documentation hits 75 pages, I will put it up at or a service alike.

    The only problem I see is that BeanShell does not seem to allow newer Java goodies like the Iterable-for combination, as in:

    for (IAtom atom : molecule.atoms()) {
    // do something

  3. Yes, I guess both a BeanShell as well as Eclipse will be available.