[PYTHON DOC-SIG] Documentation format

[Andrew Kuchling]

Robin Friedrich wrote:
> > Good thread Andy. I might add PDF and FrameMaker and WinHelp formats
> > to the list.

	Good point, particularly WinHelp; we shouldn't be Unix-centric
here, and the 95/NT ports deserve support.  (What does the Mac use for
help?  That should be supported, too.)  However, I think we also need
some sort of basic ASCII-readable format (consider the recent poster
to python-list who didn't have FTP or Web access); presumably that's
why troff was listed in the original charter, and why Info's supported
now.

Jim Fulton wrote:
> Personally, I think that we should strive for generating as much
> documentation as possible from module doc strings.  

	True, but would this really help with things like the tutorial
and the reference manual?  While it's not absolutely required that
everything be done in the same format, variety probably is a bad thing
in this case, or we might wind up with, say only the library
ref. available in WinHelp, but not the other documents.

	Another thought: If we turn module-level docstrings into
lengthy blocks of text intended for paper and HTML documents, .pyc
files will get larger and slower to read, and the temptation to
optimize them by stripping out the docstrings will increase.  But if
everyone strips out docstrings by default, they're no longer available
from inside the interpreter, which damages their usefulness.  

> I also think a simple doc string format should be used with clever
> conversion tools. I've has quite satisfactory results doing this
> myself.

	Good suggestion.  Would it be feasible to write straight
documents in a docstring format?  For example, could I take the
tutorial, turn it into one huge docstring, run it through a conversion
tool and get reasonable output?  I guess this approach is similar to
Perl's pod format, which is a simple application-specific ASCII format
which is converted to HTML, troff, or whatever.  
	
	My original posting tried to be neutral, so I might as well
say now that my personal preference leans toward either Texinfo or a
simple made-up format like pod or docstring.  Either one is less
powerful than full-blown LaTeX, which means it's easier to parse.
However, Texinfo's typography is really bad, so it would have to be
modified to change the margins and fonts.

	(Frame's non-free status doesn't worry me much, though I'd
never have access to it.  The Frame source would be available on
python.org, and the distribution would ship with various output files
like PS, HTML, or WinHelp.  Better make sure Guido has access to it,
though.)


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