[Edu-sig] Writing books/manuals containing code
jmillr at umich.edu
Mon Sep 5 00:13:38 CEST 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:
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.
Peter Bowyer <peter at 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?
More information about the Edu-sig