[Edu-sig] Writing books/manuals containing code

Kirby Urner urnerk at qwest.net
Fri Sep 2 04:28:29 CEST 2005

Hi Peter --

I do question the choice of Word, given its platform specificity (not
talking about operating system:  you need a heavy duty word processor to
open it -- even OpenOffice is a chore).  To me, a course manual for
programmers should be in a medium they'll appreciate in future.  Probably
HTML, although the XML you mention (DocBook) is good.  I use <oXygen/>
sometimes.  From one XML master document, you may output HTML, PDF or
several other un/friendly formats.  I do think the day is passed when the
teacher could win popularity points for doing man pages -- and anyway,
they're not really meant as a vehicle for course materials.

There's a cgi utility that I use, some of it by Guido's brother, which
colorizes Python using HTML tags.  You can run it locally to automatically
colorize your code.  Then, if you're using HTML or XML as your base (you
could use Word to get the HTML, but I don't find its WYSIWYG solution
attractive -- too busy on the HTML side) you can just paste in the cgi
scripts output.

To see the script in action, and to get a link to its home (bottom of the
rendered output), check some page of mine with a link to colorized source
code, e.g. http://www.4dsolutions.net/ocn/hypertoons.html 


PS: speaking of hypertoons, there's some silliness in rbf.py (one of the
dependencies) that I've needed to fix, but nothing that affects
functionality -- just some kinda dumb code.

> -----Original Message-----
> From: edu-sig-bounces at python.org [mailto:edu-sig-bounces at python.org] On
> Behalf Of Peter Bowyer
> Sent: Wednesday, August 31, 2005 2:53 AM
> To: edu-sig at python.org
> Subject: [Edu-sig] Writing books/manuals containing code
> Hi,
> 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, alhtough 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?
> Thanks,
> Peter
> --
> Maple Design - quality web design and programming
> http://www.mapledesign.co.uk
> _______________________________________________
> Edu-sig mailing list
> Edu-sig at python.org
> http://mail.python.org/mailman/listinfo/edu-sig

More information about the Edu-sig mailing list