(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