Mailman 3 September 2005 - Edu-sig

quantum instance?
by Arthur Sept. 11, 2005

Sept. 11, 2005

Trying to handle the sudden change of state of an instance of an object - a "quantum instance" c starts as a Circle instance. Say, in the course of the manipulation of c its radius approaches towards infinity, and upon the radius becoming > than some Max, I want c to suddenly think of itself as a Line instance rather than as a Circle instance. doable? hints? Art

3 2

Python Quiz
by Kirby Urner Sept. 7, 2005

Sept. 7, 2005

class Shell: def __init__(ghost): pass def __repr__(ghost): return 'What famous Japanese cartoon?' OK that was easy. So how about: class Shell (object): def __init__(ghost): pass def __repr__(ghost): return 'What famous Japanimation?' Hint: think "new-style class." Kirby

4 4

Link to RUR-PLE added
by Kirby Urner Sept. 7, 2005

Sept. 7, 2005

Finally got a couple updates to: http://www.python.org/sigs/edu-sig/ i.e. André's RUR-PLE and Ipython. Not an easy process, as pydotorg is undergoing changes and some of the web based instructions on how to update pages is obsolete. Under the current (changing) setup, A.M. Kuchling had to do the final push to the old server, as I the old ssh-based update method is no longer accessible to me. Soon, making changes will be easy again. I believe I've got the svn process down. Kirby

1 0

Re: [Edu-sig] Writing books/manuals containing code
by Dethe Elza Sept. 6, 2005

Sept. 6, 2005

(Sending this to the list because it might be useful to others as well) On 6-Sep-05, at 7:37 AM, Peter Bowyer wrote: > Hello Dethe, > > Thanks for your excellent information (which I see you've now sent > to the list as well). I'm nearly convinced by reST now, it's a > really nice way to write and I know I can 'bail out' into Docbook/ > LaTeX at any stage using the converters. There's some bits of reST > that feel odd (*italics* and **bold**, vs _italics_ and *bold*) but > that's because I've been using Textile before. The more I use reST > the smarter it feels. You're welcome. I think the *italics* and **bold** come from old email conventions (of which there were many %-) and from the fact that HTML <em>phasis then maps to one asterisk, while <strong> emphasis maps to two. And that leaves the underline for other purposes--it has many roles in reST. > At 05:10 04/09/2005, you wrote: > >> Finally, to answer your question, you can extend reST in several >> ways. >> [...] >> What kind of customizations do you need? >> > > Well I was thinking along the lines of suppose I want a section to > be collapsing/expanding in the HTML output (using Javascript), but > as a fixed box in the PDF. Some sections I want to tag as advanced > material (which will be shown online with a blue background in > collapsing boxes, and may be missed out of the printed version), > others as important or asides (red and green backgrounds > respectively). I am guessing this will have to go into the > structure of the document. > > Another may be a converter to the tbook format, but probably not - > I'll go direct to LaTeX and HTML. For making a section in HTML collapse and expand, you can do that pretty easily with CSS classes, simply by switching the class name (one class for expanded, one for collapsed). Bob Ippolito's MochaKit [1] gives some nice Javascript tools for manipulating class names (since a given element may have more than one class) as well as many other useful Javascript methods (making JS mare like Python in some important ways). Depending on what elements you want to expand/ collapse, you may be able to walk the DOM in the onload event and add the appropriate classes, or you may want to tweak the output of the HTML writer in docutils itself. In any case, attaching the javascript should be fairly trivial. Docutils already has a variety of Admonitions (Attention, Caution, Danger, Error, Hint, Important, Note, Tip, Warning) and you can make up your own Admonitions, so that might be the way to create the boxes you want. Admonitions can be styled differently in different outputs (blue, collapsing in HTML, discarded in PDF, for instance). The implementation (for HTML) puts the admonition of your choice as the class name. >> Judging by the colophons of O'Reilly books over the years, they use a >> lot of different sytems for writing their books, depending on what >> the author is comfortable with, as far as I can tell. > > The Pragmatic Programmers summarise their original system at http:// > blogs.pragprog.com/cgi-bin/pragdave.cgi/Tech/Random/DocPrep.rdoc, > which seems pretty similar. I like their way of tagging blocks of > code with surrounding comments and inserting those chunks into the > document - something which shouldn't be hard to implement with a > preprocessor. Docutils is intended to be able to extract documentation from the docstrings of Python code, but I'm not sure if that Reader is fully implemented yet. Alternatively, you can include external code into a reST document using directives. > Whichever route I take is going to have to end up with LaTeX for > the final output to render the equations. Have you used reST's > equation handling? Not really. And I found it's table, while nice to read in text format, painful to create. I ended up writing a simple script to massage an even simpler format into reST tables in that case. > Thinking ahead to when I write the final report: what is > bibliography handling like in reST? I've come across http:// > www.pricklysoft.org/software/bibstuff.html which can link reST to > bibtex, is this as good as it gets? Not sure, this is something you should probably ask on the docutils mailing list[2]. They're quite friendly. > The other thing I'm looking for as I write a sample document in > reST: is there some way to mark up text so that HTML's <abbr> or > <acronym> tags are used? I'm thinking maybe in conjunction with a > glossary (definition list) but from the documentation I cannot see > how this could be linked in. I don't see anything like this in a cursory look of the site and a quick google, but it's something so useful that it has almost certainly been discussed on the mailing list at some point. I did discover while looking that automatic numbering of lists has finally been implemented (in the svn version, not yet in the released version) and that they have a table format which may be like what I implemented with an external script awhile back (I haven't really been keeping up with docutils for the past year or so). Again, a quick question on the mailing list may get you what you need. Development appears to still be quite active, so if there is not a way to specify <abbr> there could be one soon. > I think the one question I do have about reST is how sophisticated > are its converters? As far as I can tell, the Docbook one is under > development while the LaTeX converter is pretty much complete? They vary widely. Once they are reasonably complete they migrate to the docutils core. While still rough works in progress they tend to live in the sandbox. > Thanks so much for your help, > Peter My pleasure. Best wishes with the writing. --Dethe [1] http://www.mochikit.com/doc/html/MochiKit/index.html [2] http://sourceforge.net/mailarchive/forum.php?forum_id=11444 A good engineer is a person who makes a design that works with as few original ideas as possible. --Freeman Dyson

1 0

Re: [Edu-sig] Writing books/manuals containing code
by Dethe Elza Sept. 6, 2005

Sept. 6, 2005

(sorry, forgot to reply to list with this earlier) On 3-Sep-05, at 11:32 AM, Peter Bowyer wrote: > 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? > There are a couple of other "lightweight markup" formats around. Two are more data focussed: JSON (Javascript object notation, which also works fine in Python, Perl, Java, etc.) and YAML (YAML Ain't Markup Language, which is kind of JSON++). Others are simpler markups than reST used mainly for weblog posting: Markdown [3] and Textpattern [4] are two that I know of. There are also lightweight text markups for more specialized purposes, such as RelaxNG's compact syntax[5] for defining XML dialects, and ABC[6] for music notation (and there is a project in the docutils sandbox for adding ABC to reST). Finally, to answer your question, you can extend reST in several ways. One of the simplest may be to use interpreted roles[7]. It is not terribly difficult to add new directives to reST[8], and I wrote a tutorial[9] for doing it. You can easily customize the stylesheet (s) used by reST if you are converting reST to (X)HTML. If you need to convert reST to a format that it doesn't already have a writer for, you can create a new writer, and there are examples to work from for writing PDF, XHTML, XHTML snippets, slides, LaTeX, and other formats. What kind of customizations do you need? > 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? > Judging by the colophons of O'Reilly books over the years, they use a lot of different sytems for writing their books, depending on what the author is comfortable with, as far as I can tell. You can see their "Writing for O'Reilly"[10] section for more details. IBM's developerWorks has their own XML format[11] they require. David Mertz has written his own simple text markup (Smart ASCII) and a python tool[12] for converting it to developerWorks markup. Some publishers prefer plain (unmarked-up) text, many request (or require) Word documents. It depends a lot on the market, the publisher, etc. [1] http://www.crockford.com/JSON/index.html [2] http://www.yaml.org/ [3] http://daringfireball.net/projects/markdown/ [4] http://textpattern.com/weblog/11/textpattern-4-stable-released [5] http://www.xml.com/pub/a/2002/06/19/rng-compact.html [6] http://staffweb.cms.gre.ac.uk/~c.walshaw/abc/ [7] http://docutils.sourceforge.net/docs/ref/rst/roles.html [8] http://docutils.sourceforge.net/docs/ref/rst/directives.html [9] http://docutils.sourceforge.net/docs/howto/rst-directives.html [10] http://www.oreilly.com/oreilly/author/intro.html [11] http://www-128.ibm.com/developerworks/library-combined/i-dwauthors/ [12] http://www-128.ibm.com/developerworks/xml/library/x-tipt2dw.html HTH --Dethe "And you think you're so clever and classless and free" — John Lennon on prototype-based programming

1 0

Writing books/manuals containing code
by Peter Bowyer Sept. 6, 2005

Sept. 6, 2005

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

7 9

Re: [Edu-sig] Writing books/manuals containing code
by Alexander Schliep Sept. 5, 2005

Sept. 5, 2005

Hi everyone, LaTeX is (rightfully so, IMHO) the standard for scientific publishing, in particular for books if there is any math context. To automate the production of PDFs with up-to-date code examples, sample outputs and figures (that is sometimes more difficult) you can use make. Appropriate rules create output such that myscript.py produces myscript.out whenever myscript.py is changed. Both code and output can be incorporated and pretty-printed using the listings package; the only bummer is that you have to reference line numbers. It would be nice if you could reference particular pieces more easily; Knuth's original programming tools seemed not that much more helpful for the lots of theory and small sample programs and their output type publications. I use pyexpect to capture the output of an interactive session given some commands a user would type in a file. I just stumbled over http://starship.python.net/crew/bhoel/PyLaTeX-0.2/README.html which is another way to have Python code in LaTeX. Best, Alexander -- Alexander Schliep schliep(a)molgen.mpg.de

1 0

Re: [Edu-sig] Writing books/manuals containing code
by John Miller Sept. 4, 2005

Sept. 4, 2005

Just recently the editor of About This Particular Mac, Michael Tsai, wrote about this topic (although for a magazine rather than a book) from an historical perspective. The gist is that now he is using ReST: http://www.atpm.com/11.07/publishersletter.shtml """ The core of our new publishing system is Docutils, a text processing system designed for use with the Python programming language. I now format ATPM articles in reStructuredText format, a plaintext markup language that’s similar to Setext and Markdown. Docutils includes a parser, which reads reStructuredText files into an internal representation. Then, a writer translates the internal representation into an output format such as HTML. The beauty of the Docutils system is that both sides of this process are extensible. reStructuredText doesn’t have support for the blue ATPM article headers, but I was able to teach it about them by extending the parser. Similarly, Docutils doesn’t have writers that generate ATPM- style HTML or PDFs, but it lets you plug in writers of your own. As a programmer, it was simple for me to make these and other extensions, and Docutils’ good design meant that I didn’t have to re-invent the wheel to do so. """ John Miller Peter Bowyer <peter(a)mapledesign.co.uk> wrote: > 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?

1 0

Re: [Edu-sig] Writing books/manuals containing code
by Lee Harr Sept. 3, 2005

Sept. 3, 2005

>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? You might want to look at Bruce Eckel's Thinking in Python. http://www.mindview.net/Books/TIPython I remember that being able to test all of the code examples was an important consideration in the system he set up for the book. _________________________________________________________________ Express yourself instantly with MSN Messenger! Download today it's FREE! http://messenger.msn.click-url.com/go/onm00200471ave/direct/01/

1 0