Writing books/manuals containing code

classic Classic list List threaded Threaded
15 messages Options
Reply | Threaded
Open this post in threaded view
|

Writing books/manuals containing code

Peter Bowyer
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
[hidden email]
http://mail.python.org/mailman/listinfo/edu-sig
Reply | Threaded
Open this post in threaded view
|

Re: Writing books/manuals containing code

Nicola Larosa
> 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 - [hidden email]

My god carries a hammer. Your god died nailed to a tree. Any questions?
 -- maxpublic on Slashdot, July 2005

_______________________________________________
Edu-sig mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/edu-sig
Reply | Threaded
Open this post in threaded view
|

Re: Writing books/manuals containing code

Peter Bowyer
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 

_______________________________________________
Edu-sig mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/edu-sig
Reply | Threaded
Open this post in threaded view
|

Re: Writing books/manuals containing code

Nicola Larosa
>> 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 - [hidden email]

My god carries a hammer. Your god died nailed to a tree. Any questions?
 -- maxpublic on Slashdot, July 2005

_______________________________________________
Edu-sig mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/edu-sig
Reply | Threaded
Open this post in threaded view
|

Re: Writing books/manuals containing code

Kirby Urner
In reply to this post by Peter Bowyer
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: [hidden email] [mailto:[hidden email]] On
> Behalf Of Peter Bowyer
> Sent: Wednesday, August 31, 2005 2:53 AM
> To: [hidden email]
> 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
> [hidden email]
> http://mail.python.org/mailman/listinfo/edu-sig


_______________________________________________
Edu-sig mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/edu-sig
Reply | Threaded
Open this post in threaded view
|

Re: Writing books/manuals containing code

Dethe Elza
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

_______________________________________________
Edu-sig mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/edu-sig
Reply | Threaded
Open this post in threaded view
|

Re: Writing books/manuals containing code

Arthur-27


> -----Original Message-----
> From: [hidden email] [mailto:[hidden email]] 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


_______________________________________________
Edu-sig mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/edu-sig
Reply | Threaded
Open this post in threaded view
|

Re: Writing books/manuals containing code

Jaime E. Villate
In reply to this post by Nicola Larosa
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
_______________________________________________
Edu-sig mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/edu-sig
Reply | Threaded
Open this post in threaded view
|

Re: Writing books/manuals containing code

Lee Harr-3
In reply to this post by Peter Bowyer
>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/

_______________________________________________
Edu-sig mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/edu-sig
Reply | Threaded
Open this post in threaded view
|

Re: Writing books/manuals containing code

Peter Bowyer
In reply to this post by Dethe Elza
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 

_______________________________________________
Edu-sig mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/edu-sig
Reply | Threaded
Open this post in threaded view
|

Re: Writing books/manuals containing code

John Miller-3
In reply to this post by Peter Bowyer
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 <[hidden email]> 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?
_______________________________________________
Edu-sig mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/edu-sig
Reply | Threaded
Open this post in threaded view
|

Re: Writing books/manuals containing code

Alexander Schliep
In reply to this post by Peter Bowyer

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                                    [hidden email]
_______________________________________________
Edu-sig mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/edu-sig
Reply | Threaded
Open this post in threaded view
|

Re: Writing books/manuals containing code

Hans Fangohr
In reply to this post by Peter Bowyer
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

_______________________________________________
Edu-sig mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/edu-sig
Reply | Threaded
Open this post in threaded view
|

Re: Writing books/manuals containing code

Dethe Elza
In reply to this post by Peter Bowyer
(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



_______________________________________________
Edu-sig mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/edu-sig
Reply | Threaded
Open this post in threaded view
|

Re: Writing books/manuals containing code

Dethe Elza
In reply to this post by Peter Bowyer
(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

_______________________________________________
Edu-sig mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/edu-sig