[Edu-sig] Writing books/manuals containing code

[Dethe Elza]

(Sending this to the list because it might be useful to others as well)

On 6-Sep-05, at 7:37 AM, Peter Bowyer wrote:

> Hello Dethe,
>
> Thanks for your excellent information (which I see you've now sent  
> to the list as well).  I'm nearly convinced by reST now, it's a  
> really nice way to write and I know I can 'bail out' into Docbook/ 
> LaTeX at any stage using the converters.  There's some bits of reST  
> that feel odd (*italics* and **bold**, vs _italics_ and *bold*) but  
> that's because I've been using Textile before.  The more I use reST  
> the smarter it feels.

You're welcome.  I think the *italics* and **bold** come from old  
email conventions (of which there were many %-) and from the fact  
that HTML <em>phasis then maps to one asterisk, while <strong>  
emphasis maps to two.  And that leaves the underline for other  
purposes--it has many roles in reST.

> At 05:10 04/09/2005, you wrote:
>
>> Finally, to answer your question, you can extend reST in several
>> ways.
>> [...]
>> What kind of customizations do you need?
>>
>
> Well I was thinking along the lines of suppose I want a section to  
> be collapsing/expanding in the HTML output (using Javascript), but  
> as a fixed box in the PDF.  Some sections I want to tag as advanced  
> material (which will be shown online with a blue background in  
> collapsing boxes, and may be missed out of the printed version),  
> others as important or asides (red and green backgrounds  
> respectively).  I am guessing this will have to go into the  
> structure of the document.
>
> Another may be a converter to the tbook format, but probably not -  
> I'll go direct to LaTeX and HTML.

For making a section in HTML collapse and expand, you can do that  
pretty easily with CSS classes, simply by switching the class name  
(one class for expanded, one for collapsed).  Bob Ippolito's MochaKit 
[1] gives some nice Javascript tools for manipulating class names  
(since a given element may have more than one class) as well as many  
other useful Javascript methods (making JS mare like Python in some  
important ways).  Depending on what elements you want to expand/ 
collapse, you may be able to walk the DOM in the onload event and add  
the appropriate classes, or you may want to tweak the output of the  
HTML writer in docutils itself.  In any case, attaching the  
javascript should be fairly trivial.  Docutils already has a variety  
of Admonitions (Attention, Caution, Danger, Error, Hint, Important,  
Note, Tip, Warning) and you can make up your own Admonitions, so that  
might be the way to create the boxes you want.  Admonitions can be  
styled differently in different outputs (blue, collapsing in HTML,  
discarded in PDF, for instance).  The implementation (for HTML) puts  
the admonition of your choice as the class name.

>> 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.
>
> The Pragmatic Programmers summarise their original system at http:// 
> blogs.pragprog.com/cgi-bin/pragdave.cgi/Tech/Random/DocPrep.rdoc,  
> which seems pretty similar.  I like their way of tagging blocks of  
> code with surrounding comments and inserting those chunks into the  
> document - something which shouldn't be hard to implement with a  
> preprocessor.

Docutils is intended to be able to extract documentation from the  
docstrings of Python code, but I'm not sure if that Reader is fully  
implemented yet.  Alternatively, you can include external code into a  
reST document using directives.

> Whichever route I take is going to have to end up with LaTeX for  
> the final output to render the equations.  Have you used reST's  
> equation handling?

Not really.  And I found it's table, while nice to read in text  
format, painful to create.  I ended up writing a simple script to  
massage an even simpler format into reST tables in that case.

> Thinking ahead to when I write the final report: what is  
> bibliography handling like in reST?  I've come across http:// 
> www.pricklysoft.org/software/bibstuff.html which can link reST to  
> bibtex, is this as good as it gets?

Not sure, this is something you should probably ask on the docutils  
mailing list[2].  They're quite friendly.

> The other thing I'm looking for as I write a sample document in  
> reST: is there some way to mark up text so that HTML's <abbr> or  
> <acronym> tags are used?  I'm thinking maybe in conjunction with a  
> glossary (definition list) but from the documentation I cannot see  
> how this could be linked in.

I don't see anything like this in a cursory look of the site and a  
quick google, but it's something so useful that it has almost  
certainly been discussed on the mailing list at some point.  I did  
discover while looking that automatic numbering of lists has finally  
been implemented (in the svn version, not yet in the released  
version) and that they have a table format which may be like what I  
implemented with an external script awhile back (I haven't really  
been keeping up with docutils for the past year or so).  Again, a  
quick question on the mailing list may get you what you need.   
Development appears to still be quite active, so if there is not a  
way to specify <abbr> there could be one soon.

> I think the one question I do have about reST is how sophisticated  
> are its converters?  As far as I can tell, the Docbook one is under  
> development while the LaTeX converter is pretty much complete?

They vary widely.  Once they are reasonably complete they migrate to  
the docutils core.  While still rough works in progress they tend to  
live in the sandbox.

> Thanks so much for your help,
> Peter

My pleasure.  Best wishes with the writing.

--Dethe

[1] http://www.mochikit.com/doc/html/MochiKit/index.html
[2] http://sourceforge.net/mailarchive/forum.php?forum_id=11444


A good engineer is a person who makes a design that works with as few  
original ideas as possible. --Freeman Dyson