Re: [Edu-sig] Writing books/manuals containing code
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@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?
participants (1)
-
John Miller