vsbabu.org

Making of an O'Reilly book

O'Reilly Net: “The making of Effective awk Programming”.

It has some great insights into the complicated world of using DocBook. There are some effective awk scripts that help. But the part that struck me most was, how insanely complicated it is to really use DocBook. I had written 2 tutorials using SGML, and 2 other multi-chaptered documents using DocBook. The tags and other rules make it very hard to let the thoughts flow freely.

My ideal documentation tool

• Ability to edit in Leo, the outlining literate editor.
• Individual sections should be editable in Structured Text or reStructured Text.
• Output should be available in DocBook - because many stylesheets are available to convert it to other formats.
• Ability to generate a slideshow from the outline.
• Perhaps, export/import from/to Yaml. At times, I will have to edit the file in VI.

Last week, I tried to program Leo using Python. It was not that hard. Only issue I faced was that I couldn’t make it work without a Leo window being open. This might be possible, but I don’t know how to do it yet. Batch processing on Leo files without the Leo GUI being open is very important to me.

Update: You can use Leo with reStructured Text.