[PYTHON DOC-SIG] Documentation format

[Robin Friedrich]

|> From jim.fulton@digicool.com Tue Aug 13 16:48 CDT 1996
|> Date: Tue, 13 Aug 1996 17:45:52 -0400
|> From: Jim Fulton <jim.fulton@digicool.com>
|> 
|> Robin Friedrich wrote:
|> > 
|> > |> From: Andrew Kuchling <amk@magnet.com>
|> > |>
...
|> > |>      I'd imagine automatic generation of an index and table of
|> > |> contents is mandatory, particularly for the reference guide and
|> > |> library reference.
|> > |>
|> > |>      Any thoughts on this?
|> > |>
|> > 
|> > Good thread Andy. I might add PDF and FrameMaker and WinHelp formats
|> > to the list.
|> 
|> As input or output?

Output. Except in the possible case of Framemaker.
|> 
|> > I think troff may be extranious at this point.
|> 
|> Hm.

By this I was refering to the lessening importance of man pages in a
world not dominated by Unix. Latex also has some packages for
generation or man-like pages as well.

|>  
|> > As far as the native base docs, Frame is a valid candidate.
|> > 
|> > Pros: WYSIWYG, so it's easier to maintain.
|> >       Output in PostScript free; output in HTML free or nearly so;
|> >       output in PDF inexpensive.  Output in RTF(as a way to WinHelp)
|> >       Support for hyperlinks native. Support for Graphics and nice
|> >       tables.  Support for equations.  Indexing and TOC support.
|> >       Framemaker is very common (more so than TeX) Large extension
|> >       writers more likely to use it (NumPy, PIL, etc) and fold it into
|> >       the Doc tree.  Portable; available on most platforms.  Converter
|> >       available for LaTeX -> Frame.  see
|> >       http://www.ius.cs.cmu.edu/IUS/sin_www/help/Document/latex2fm.html
|> 
|> I like Frame alot, but it is pricey.

And many many folks have already bitten that bullet. (although I would say
$500 is only pricey for individuals not companies, and that's who would 
need it.) It would be used by the PSA stuckee in charge of maintaining
the Docs.  Guido would like to get this whole deal off his back. 
End users look at paper or html or winhelp.

BTW I downloaded the above la2mml tool and compiled it and ran it 
against all the 1.4b2 .tex files and it did generate the complete doc
set (with many caveats).  MML (maker markup language) is rather limited
in scope as it has no support for character tags. Thus all the \code
latex markups etc, is left in the text. That would have to be cleaned 
up with a little processor.  The indexes likewise would have to be
manually dealt with to get the docs back up to snuff in the Frame5 format.
This conversion mess would have to be done only once though so I don't
worry too much about it. I estimate two weeks for a FrameMaker-Python-Latex-
MML-MIF expert ;-).

Otherwise the bulk of the text came over fine.

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

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