[PYTHON DOC-SIG] Documentation format

[Andrew Kuchling]

Richard Jones wrote:
> 	I'd like to add a vote here for a simple format like the docstring format 
> that can be then turned into pretty pages.  Let's try to keep it simple 
> for the people who have to write this documentation (like me).  I don't 

	I agree.  I also like a simple, nonextensible format because
it'll prevent people from inventing new constructs.  For example, when
documenting a class with keywords, there's a temptation to write
something like:

\begin{funcdesc}{Bastion}{object\, {\bf filter}=filterfunc, 
	                  {\bf name}=objectname\, {\bf bastionclass}=class}

	...which may look OK in the LaTeX output.  But will the
conversion process to Texinfo or HTML still work?  With a simple,
highly constrained language, inventing a new command would require
changing the code, which would reduce the number of commands that get
added.

> Thing.  Unfortunately the docstring format doesn't support images - which 
> are sometimes invaluable in tutorials etc.

	Well, no one intends that all Python-related material *must*
be written in this format; books and papers can be written in Frame,
LaTeX, Lout, or whatever the author likes.  I'm only thinking of the
material that should be available wherever Python is ported; that must
include the library reference, and should include the reference
manual.  Neither of those documents includes any graphics at all.  The
tutorial would be nice to have, but users don't need it close at hand.

	(The fourth item in the Doc/ subdirectory is the paper
"Interactively Testing Remote Servers Using the Python Programming
Language", which would be left in LaTeX; it doesn't need to be
translated since it's not immensely helpful in using Python.)


	Andrew Kuchling
	amk@magnet.com


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

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