[PYTHON DOC-SIG] Documentation format

[Robin Friedrich]

|> From: Andrew Kuchling <amk@magnet.com>
|> 
|> 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

The Mac doesn't have a universal tool although Apple would like 
everyone to write in the Assistant(?) format. I use the html myself
on the Mac at home. 

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

I place the ascii version as a lower priority. For the quick reference
I do keep a file in an emacs buffer all the time but when I want the
full docs I just open the book (never far from my side). The info docs
are nice but I wouldn't miss them too much. And again that's leading
to me Unix-centric in thinking.  As a base format I think we need a 
powerful tool not a pod-like clone.

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

This was addressed at the last workshop and after some jabberwalky
we concluded that it's really not as big a drag as people think.
The final recommendation was to use doc strings with gusto and 
let the anal retentives strip them out.  

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

I believe CNRI does have Framemaker.  But again, the docs are something
Guido would love to delegate.
I vote for a powerful system, either Latex or Frame.

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

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