Re: DRY way to insert source code into an article?

Daniel Wellman wrote:
> 
> 
> Hi all,
> 
> I'm starting to write articles about programming and I'd like to
> include source code snippets into my article. My strategy was to get
> the source code examples working, then annotate sections of code which
> should be imported into the body of the article. The goal here was to
> avoid copy-paste problems of putting incorrect or stale source code
> examples into the document.
> 
> How do other pragmatists approach this problem?
> 
> In my case, the source code will be Java, and I'm open to picking a
> tool for the prose part of the article -- ultimately the final output
> format will be whatever the publisher can accept (I'm working on
> finding out that part). Do people write the article in some plain
> text format (TeX? DocBook?) or some open document format (ODT?) and
> then use a template-generation strategy to generate final document?
> 
> Thanks for your advice,
> Dan

Well, first of all, what you're talking about is sometimes called 
"literate programming." The best-integrated literate programming 
environment I've found is in the LyX document processor, especially with 
the R programming language.

With LyX/R, it is possible to edit a document which contains text, code 
to produce graphics that is invisible, code that is visible, etc. You 
can then push a button and view your document as a PDF. When you're 
happy with the document, you can save it off in any of the formats LyX 
supports: PDF, Rich Text, HTML and Open Document are the four I use most 
of the time, but anything that has a converter can be integrated.

If you don't have or don't want to learn R, there are some other ways to 
do literate programming in LyX, which involve the "noweb" literate 
programming package. The "core scripting language" of LyX is Python, so 
if you can and are willing to hack Python you can extend what's built 
in, but you should be able to do something in Java.

You haven't said what environment you're in, but LyX is open source and 
will run on at least Windows, Linux and Macintosh. I use Gentoo Linux, 
and I've loaded just about everything I can around LyX. The LyX/R 
interface doesn't work on Windows, but it can be hacked in Cygwin on a 
Windows system.

Send me an email off-list if you want help getting LyX set up or 
pointers to the right parts of the documentation.