[Edu-sig] Writing books/manuals containing code

[Nicola Larosa]

> I have just started writing a course manual to introduce students to 
> programming.  There are going to be lots of code examples, and I was 
> wondering: is there a way to insert the code into the document from 
> external files, so I can test all the files and make sure the code 
> works, even if I edit it?  In Microsoft Word I can embed a file as an 
> object, but the file's contents does not show in the document.

You want Leo ( http://leo.sourceforge.net/ ). It is a versatile outliner
that lets one compose documents including references to external files,
that are automatically tracked. It's a very powerful "literate programming"
tool (also known as "executable documentation").


> My example programs are then broken down and I go through it 
> line-by-line.  Again, is there any way to insert these single lines 
> of code without copying and pasting from the main block?

This is harder, and arguably less useful, since your comment text will have
to be revised anyway, when you change those lines.


> I'm using Microsoft Word 2000, which is also making referencing code 
> hard.  I am open to suggestions of other programs, alhtough I'd 
> prefer not to have to learn and write Docbook/LaTeX by hand.

No Word, no Docbook, no LaTex (but output in those formats, if you need it).

You want Docutils ( http://docutils.sourceforge.net/ ), with ReStructured
Text markup, much simpler than those alternative. It is well integrated
within Leo via plugins.


> Finally, is there a way to syntax highlight python code before 
> putting it into MS Word?

There are a number of Python syntax highlighting libraries out there, it
depends on the output format needed. I would avoid Word, if at all
possible, and if you value your peace of mind. :-)


-- 
Nicola Larosa - nico at tekNico.net

My god carries a hammer. Your god died nailed to a tree. Any questions?
 -- maxpublic on Slashdot, July 2005