[Edu-sig] Writing books/manuals containing code

[Hans Fangohr]

Hi Peter,

> 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.
>
> 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?
>
> I'm using Microsoft Word 2000, which is also making referencing code
> hard.  I am open to suggestions of other programs, although I'd
> prefer not to have to learn and write Docbook/LaTeX by hand.
>
> Finally, is there a way to syntax highlight python code before
> putting it into MS Word?

I'll have to agree with some of the previous emails that Word (whatever 
version) is a questionable choice. I also think you should look into 
LaTeX: it is just another programming language where the source code is 
'compiled' into graphical output (usually so called dvi-files) which is 
easily converted into postscript or pdf. You can also create html from 
latex using latex2html (although this sometimes needs manual fine tuning). 
Note also that latex is very similar to html in that you have tags 
defining how things should look like (I write this in case you know html). 
Finally, even if you use Word in the end, knowing latex will show you how 
to typeset well.

To answer some of your questions: I often use LaTeX for lecture notes etc 
and use the 'listings' extension to include source code 
(http://www.ctan.org/tex-archive/macros/latex/contrib/listings/). It 
supports syntax highlighting of more than 20 languages, including 
Python (although I don't think it does different colours such as IDLE but 
just highlights keywords in a style of your choice). It allows you to read 
a piece of source code from a file into your document; this is great to 
make sure you don't get your main document out-of-date when you change the 
code. You can also ask it number the lines for you (so you can discuss the 
code more easily). You can also ask it to only print lines 10 to 20 or so 
which might help you in what you are asking for above.

In particular, if you need equations, it is unlikely you can get around 
LaTeX. Most people (certainly on this list, I think) will agree that 
equations written in LaTeX look best.

I hope this is useful,

Hans