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
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
At 11:43 31/08/2005, Nicola Larosa wrote:
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").
Do you have any .leo files doing this that you can share, or links to documentation? I've been reading Leo's site and googling, and still don't understand enough to make the program work.
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.
That sounds good. Peter -- Maple Design - quality web design and programming http://www.mapledesign.co.uk
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").
Do you have any .leo files doing this that you can share, or links to documentation?
There's lots of examples and docs on the site, maybe even too many. :-) It surely takes some study at the beginning. I'd say, start from the tutorials, and just take your time.
I've been reading Leo's site and googling, and still don't understand enough to make the program work.
Instead of just reading, try running the program, and studying its examples from within. -- Nicola Larosa - nico@tekNico.net My god carries a hammer. Your god died nailed to a tree. Any questions? -- maxpublic on Slashdot, July 2005
On Wed, Aug 31, 2005 at 12:43:03PM +0200, Nicola Larosa wrote:
You want Docutils ( http://docutils.sourceforge.net/ ), with ReStructured Text markup, much simpler than those alternative.
You might also want to try my python script: http://villate.org/wikiup/ Look at the example: http://villate.org/wikiup/examples/example.html and the result: http://villate.org/wikiup/examples/example1.html In the near future it will produce Latex and Docbook output, which is something that I have already implemented in its predecessor, before I switched into Python: http://villate.org/parsewiki/ (debian> apt-get install parsewiki) Cheers, Jaime
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
On 1-Sep-05, at 7:28 PM, Kirby Urner wrote:
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.
And sometimes even XML is too heavy--in which case you can use reStructured Text[1] (or reST, part of the Python Docutils project). Using reST is kind of like wiki markup, but it can be transformed into DocBook, reST XML, XHTML, PDF, etc. Much more readable and editor-friendly than XML. If you are on OS X there is even a reST- specific editor[2] which transforms to XHTML as you go, for WYSIWYG- ish goodness. [1] http://docutils.sourceforge.net/docs/index.html [2] http://python.net/~gherman/ReSTedit.html --Dethe "Well I've wrestled with reality for thirty-five years now, doctor, and I'm happy to state I've finally won out over it." -- Elwood P. Dowd, Harvey
-----Original Message----- From: edu-sig-bounces@python.org [mailto:edu-sig-bounces@python.org] On Behalf Of Dethe Elza
And sometimes even XML is too heavy--in which case you can use reStructured Text[1] (or reST, part of the Python Docutils project). Using reST is kind of like wiki markup, but it can be transformed into DocBook, reST XML, XHTML, PDF, etc. Much more readable and editor-friendly than XML.
Again, just offering my own experience - I found learning to work with reST well worth the investment. It's a strange beast in a way - you write pretty naturally, but as if you were using a very primitive text editor with few "modern" capabilities - and by so doing you are connected, as mentioned above, with the state of the art capabilities of XHTML ,XML, PDF, etc.
If you are on OS X there is even a reST- specific editor[2] which transforms to XHTML as you go, for WYSIWYG- ish goodness.
Frustrating that it's OS X specific, as I don't have easy access to it. Would be anguish to give it a whirl. Art
At 04:38 02/09/2005, Dethe Elza wrote:
If you are on OS X there is even a reST- specific editor[2] which transforms to XHTML as you go, for WYSIWYG- ish goodness.
A bit of searching found one for all platforms available: DocFactory - http://docutils.sourceforge.net/sandbox/gschwant/docfactory/doc/ I'm not convinced about reST from the examples I've seen, but I will certainly play with it. I think it's one of those things you have to *get* before it makes sense (and Leo even more so). It seems counter-intuitive to drop back to plain text with syntax. One question I do have about it, is can you extend the syntax with your own modifiers etc? Does anyone know how publishers such as O'Reilly have their books written? When I read the Pragmatic Programmer's guide to Ruby I noted at the front they say the code results in their book are actual output - the code is executed every time the book was generated. Is anyone familiar with the systems for doing this? For the number of books and manuals being written I've found very little in the way of guides on different set-ups people use. Peter -- Maple Design - quality web design and programming http://www.mapledesign.co.uk
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
participants (7)
-
Arthur -
Dethe Elza -
Hans Fangohr -
Jaime E. Villate -
Kirby Urner -
Nicola Larosa -
Peter Bowyer