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

On 13/04/2008, Daniel Wellman <wellman-pD6z9c7pN/[email protected]> wrote:
>  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.

I've done that by adding magic comments to the code.  It worked well
until I wanted to show the difference between different versions of
the same code.  At that point it became too much of a development
effort and I went back to copy-and-paste.

>  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?

I use Docbook, have defined my own XML format for some of my
documentation projects, and am also looking into DITA for reference
manuals and the like.

Although you can edit XML with a plain text editor, I find it quite
difficult to concentrate on the text among all the markup.  There are
a few WYSIWYM editors for Docbook and other XML formats.  My favourite
is XMLMind XML Editor (XXE), available from http://www.xmlmind.com.
You can download a free personal edition and the professional edition
is (in my opinion) well worth the money.

--Nat