[PYTHON DOC-SIG] Documentation format

[Richard Jones]

Andrew Kuchling wrote:
> Jim Fulton wrote:
> > 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.  

	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 
have access to Frame, and probably never will.  I do have access to LaTeX 
(and I'm not afraid to use it), but I think we'd be making a mistake 
keeping on going down that path - TeX _is_ a pain to install.

	The docstring format has another thing going for it -- apart from being a 
simple format to write documents in -- in that it is immediately readable 
by all users.  If a user doesn't have access to a PS, HTML, Frame, DVI, 
etc viewer, then they can still view the documentation.  This is a Good 
Thing.  Unfortunately the docstring format doesn't support images - which 
are sometimes invaluable in tutorials etc.


		Richard



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

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