[Edu-sig] Writing books/manuals containing code

[Dethe Elza]

On 1-Sep-05, at 7:28 PM, Kirby Urner wrote:

> Hi Peter --
>
> I do question the choice of Word, given its platform specificity (not
> talking about operating system:  you need a heavy duty word  
> processor to
> open it -- even OpenOffice is a chore).  To me, a course manual for
> programmers should be in a medium they'll appreciate in future.   
> Probably
> HTML, although the XML you mention (DocBook) is good.  I use <oXygen/>
> sometimes.  From one XML master document, you may output HTML, PDF or
> several other un/friendly formats.  I do think the day is passed  
> when the
> teacher could win popularity points for doing man pages -- and anyway,
> they're not really meant as a vehicle for course materials.

And sometimes even XML is too heavy--in which case you can use  
reStructured Text[1] (or reST, part of the Python Docutils project).  
Using reST is kind of like wiki markup, but it can be transformed  
into DocBook, reST XML, XHTML, PDF, etc.  Much more readable and  
editor-friendly than XML.  If you are on OS X there is even a reST- 
specific editor[2] which transforms to XHTML as you go, for WYSIWYG- 
ish goodness.

[1] http://docutils.sourceforge.net/docs/index.html
[2] http://python.net/~gherman/ReSTedit.html

--Dethe

"Well I've wrestled with reality for thirty-five years now, doctor,  
and I'm
happy to state I've finally won out over it." -- Elwood P. Dowd, Harvey