[FRPythoneers] PythonDoc review
uche.ogbuji at fourthought.com
Wed Mar 29 15:55:08 MST 2000
Evelyn Mitchell wrote:
> On Tue, Mar 28, 2000 at 11:25:04PM -0700, Sean Reifschneider wrote:
> > On Mon, Mar 27, 2000 at 10:10:37AM -0700, Uche Ogbuji wrote:
> > >any time soon. In the meantime fourthought has moved to Docbook for
> > >on-line docs and is considering a Javadoc (with a few good ideas from
> > >Structured Text) approach for in-line docs.
> DocBook may be a little heavy weight for documentation included
> in source files. The book by Normal Walsh is available
> online at http://www.oreilly.com/catalog/docbook/index.html
Docbook is a _lot_ heavyweight for in-line docs (excuse the grammar),
and that's why I said we intend to use JavaDoc for that purpose.
DocBook is strictly for on-line (meaning Intra and Internet) docs.
I'd like to point out that the O'Reilly book is not the best, IMHO for
beginners. I'd look at the SGML-Tools HOWTO and other less abstruse
sources first to get the feet wet. It is, however, an excellent
> I used it when I was working on SGML-Tools, and it had a few
> things I liked, and a few I didn't. It does seem to be the
> best tool available right now.
I've been using DocBook on and off for about a year now. If I had to
judge it empirically, I would say it really sucks (I prefer TEI and the
general idiom of TeX), but it's the best such system out there for
modern tools, so I'm happy with it.
> The support for XML in Python is really good, and I'd push for
> that sort of tool, if possible.
I should note that Digital Creations has also discovered Docbook and
will be using it quite a bit, apparently in similar ways to our usage at
Fourthought, Inc., IT Consultants
uche.ogbuji at fourthought.com (970)481-0805
Software-engineering, project-management, knowledge-management
More information about the FRPythoneers