[FRPythoneers] PythonDoc review

Uche Ogbuji 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
reference.

> 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.

-- 
Uche Ogbuji
Fourthought, Inc., IT Consultants
uche.ogbuji at fourthought.com	(970)481-0805
Software-engineering, project-management, knowledge-management
http://Fourthought.com		http://OpenTechnology.org





More information about the FRPythoneers mailing list