[PYTHON DOC-SIG] Documentation format
Tue, 13 Aug 1996 18:05:25 -0500
|> From: Andrew Kuchling <firstname.lastname@example.org>
|> 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
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,
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: email@example.com
administrivia to: firstname.lastname@example.org