-
Well, maybe by writing a book about Wax it would become mature enough. It's a long task to write a book, and in the process of trying you'll probably learn a lot about Wax and start to see what it takes to make it complete and mature. I think writing documentation along with code can be a great way to make usable libraries, and usability seems to kind of be the point of Wax. When you're writing about something, and the chapter comes out all confusing and unstructured, you can change the code instead of changing the text ;)
I like reST myself, mostly because it doesn't get in the way of writing. I think DocBook would drive me crazy, because I'd be thinking about the markup and not the text. Even a word processor can encourage that kind of typographic distraction. All the markup can wait -- the only thing that really matters is the content. ReST is close enough to plain ASCII to be non-intrusive -- and really, you can just do plain ASCII and then make it render pretty when you're editing. Editing is a good distraction when you don't know what to write. No reason to do it before then.
-
I have to agree with Ian -- I'm wrapping up the programming reference for an SDK that I was hired to create, and using reST was the best choice for me -- the reference manual comes in around 35K words. Being able to structure the document as a bunch of small text files that get .. include-d into the main doc makes writing more like software development.
I wrote a handful of vim macros to handle the reST markup stuff for me, and a few Python programs to do other massaging as I needed.
-
A great resource for inspiring technical authors is O'Reilly's Guide for New Authors (http://www.oreilly.com/oreilly/author/index.html).
O'Reilly asks their authors to provide source files in DocBook Lite format, or either Word or FrameMaker tagged based upon their templates. (Chapter 2, section 'Tools').
Personally, I'd prefer reST too. I suspect making a docutils writer for DocBook Lite format would not be very difficult.
-
As far as book ideas go:
If not Wax, how about wxPython? A wxPython book has been needed since, well, since wxPython has been created.
-
Also, if you write a book about wxPython, you could include one or more chapters about Wax. Heck, you might even include a chapter about PythonCard, and one about Boa Constructor, etc.
wxPython seems to be growing in populartiy, and there is no real book about wxPython.
-
reST to DocBook would probably need some augmentation, it is a lot more semantic and reST is more approximate/visual. But it wouldn't be hard to have something build up a correction-dictionary for that conversion, and you need only deal with it at the end...
(I've written a bunch of article-length stuff in docbook and while emacs PSGML-mode [parsing the docbook dtd so it is fully aware] is excellent, it interrupts the flow rather a lot, and I'm starting to use reST instead after a brief flirtation with "extended POD". There are some (mostly java-based) XML editors that could handle "docbk", but none of them are emacs :-) and they've had varying degrees of flakiness when I've tried them...)
-
docbook is not so bad. You just need an editor that fills the tag for you. And it gives you much more semantic value over simple ReST. plus, you get all the usual xml benefits. Oh, and OOo should be able to export Docbook, now.
BTW, what's wrong with plain latex?
About the content: I'd go with WxPython, we all want to see such a book. But please don't be too verbose about RADs. We can understand how to use them, anyway.
On a side note, I'd love to see something different from the usual reference-like text.
I just discovered the "poignant guide" to the R* language (poignant guide . net), and I feel *that* is the way documentation should be written :-)
-
I have a vague memory that Patrick O'Brien or someone involved in wxPython development has been promising a wxPython book for a while now, but I've not seen any indication of progress.
Such a book would be useful, and I'd buy a copy in a heartbeat, but might be a very small niche market. Books on GUI toolkit programming using a scripting language have not sold very well, from what I understand (though I could be wrong on that, and there's always the first time for a hit). But, that may not be an issue for you.
Something else I'd like to see is a book on best practices and on anti-patterns for large system development with Python. How, and how not, to use Python to create enterprise-level applications. We have lots of bits and pieces, but I don't think I've seen examples of all the pieces put together. Of course, that could be in part due to the lack of enterprise penetration that Python has at the system level, and in part because those that do use Python at that level don't advertise the fact. And because every Python enterprise framework except for Zope is less than a 2.0 version, often less than 1.0.
Food for thought, anyway.
-
""" If not Wax, how about wxPython? """
Contrary to what people might think, I don't know very much about wxPython. I didn't want to use it, so I wrote Wax. :-)
-
I second the nomination on writing a book about writing Python apps that scale to the enterprise. Of course, While I don't know if your experiences would lend themselves to writing such a book, I would certainly read a book on the subject.
Either way, please keep posting about progress and decisions. This is a project I've toyed with in the past and I would like to know how you go about it.
-
ReST to PDF is no problem at all. I've been using it this past year, taking DocUtil's raw XML output and running it through XSL:FO transformation and thence to PDF.
It's about the nicest low-key publishing system I've ever used. For the work I do (continually evolving content, no need for really fancy layout), it's nearly as good as the "big boy" tools (Framemaker, Ventura Publisher).
I should write a book about it... ;-)