[Edu-sig] Writing books/manuals containing code

[John Miller]

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 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?