[Edu-sig] Writing books/manuals containing code
delza at livingcode.org
Tue Sep 6 07:15:55 CEST 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
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  and Textpattern 
are two that I know of. There are also lightweight text markups for
more specialized purposes, such as RelaxNG's compact syntax for
defining XML dialects, and ABC 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. It is
not terribly difficult to add new directives to reST, and I wrote
a tutorial 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
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" section for more details. IBM's
developerWorks has their own XML format they require. David
Mertz has written his own simple text markup (Smart ASCII) and a
python tool 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.
"And you think you're so clever and classless and free"
— John Lennon on prototype-based programming
More information about the Edu-sig