[PYTHON DOC-SIG] Documentation format
Tue, 13 Aug 1996 23:58:45 GMT
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.
DOC-SIG - SIG for the Python Documentation Project
send messages to: firstname.lastname@example.org
administrivia to: email@example.com