[Edu-sig] Writing books/manuals containing code

[Dethe Elza]

(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