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@tekNico.net My god carries a hammer. Your god died nailed to a tree. Any questions? -- maxpublic on Slashdot, July 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 Kirby 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@python.org [mailto:edu-sig-bounces@python.org] On Behalf Of Peter Bowyer Sent: Wednesday, August 31, 2005 2:53 AM To: edu-sig@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@python.org http://mail.python.org/mailman/listinfo/edu-sig

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