[PYTHON DOC-SIG] Re: Do reference/user docs exist for the Py* API?

[Skip Montanaro]

Robin wrote:

   I have argued that we should switch over to FrameMaker as the baseline
   tool.

I'm sure FrameMaker is a terrific piece of software.  I even used it
occasionally in my days at GE. However, I simply can't afford to purchase it
(or anything else) at this point.

Generally speaking, I can't see how it benefits a free piece of software to
have its documentation developed using a proprietary word processor, even
something as ubiquitous as Microsoft Word (which I also can't afford at the
moment).  Others who might be cajoled into working on the documentation
might well be put off -- as am I -- at the thought of having to spend money
to support free software.

To Michael McLay's point, I'm also not too interested in writing a bunch of
Python code just to document existing C code.  (Maybe I misunderstood
something.)  Writing is writing.  Programming is programming.  Many (all?)
of the functions and data to be documented are not going to be visible to
tools like gendoc, so doc strings (if that's what you had in mind) won't cut
it.  Nor am I interested in learning a new text processing system just for
this project.  My day-to-day exposure to various text processors tends to be
rather minimal, so I'd rather stick with something I know, however vaguely.

My first choice would be LaTeX or texinfo.  I believe all the existing
Python documentation is written in LaTeX.  It's freely available on a wide
variety of platforms.  If people decide later on to move to something else
altogether, then the effort of converting existing documentation to a new
text processing system will be minimized by having only one source format to
convert.

The only other obvious alternative I see is HTML.  It's big disadvantage is
that it's a moving target.  LaTeX is much more stable, and you can use tools
like latex2html (or latex2frame, or ...) to generate other formats like
HTML.

Skip Montanaro     |   Musi-Cal: http://concerts.calendar.com/
skip@calendar.com  |   Conference Calendar: http://conferences.calendar.com/
(518)372-5583      |   Python: http://www.python.org/

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================