[PYTHON DOC-SIG] Documentation format

[Robin Friedrich]

|> From: Andrew Kuchling <amk@magnet.com>
|> 
|> One of the goals of the Doc-SIG is to decide on a format for written
|> documentation, such as the tutorial and library reference.  Currently
|> LaTeX is used for everything, and it's converted to Texinfo and HTML.
|> 
|> However, there are now more things that need to be documented, such as
|> the presence and name of keyword arguments, and default argument
|> values.  We could add LaTeX macros to handle them, but it might be a
|> good time to think about the format of Python's documentation, and to
|> consider the usefulness of changing it (both the input format, and the
|> typographical presentation of the output).  Therefore, I'm raising the
|> topic for discussion here.
|> 
|> Some possible topics: How should keywords and default values be
|> presented while keeping the library manual readable?  What other
|> formatting features would be useful?  Should we stick with LaTeX, or
|> would some other format be easier to work with?  What are the
|> advantages and disadvantages of the various possibilities?
|> 
|> Quoting from the Doc-SIG Web page: 
|> + The format options:
|>                o Write in one format, and generate multiple output formats.
|>                     # Linuxdoc
|>                     # Bill Janssen suggested something else
|>                o What output formats are needed
|>                     # Postscript
|>                     # HTML
|>                     # info
|>                     # troff (-man option)
|>                     # native Grail .pyc files ??
|> <End of quotation>
|> 
|> 	I'll list the possible input formats I can think of, without
|> commenting on their usefulness or applicability:
|> 
|> 	* LaTeX 
|> PostScript output for free; converted to Texinfo, provides HTML, Info.
|> 
|> 	* Texinfo
|> PostScript, HTML, Info output for free.
|> 
|> 	* Texinfo variants (such as ILU's TIM, or an otherwise
|> modified texinfo) 
|> PostScript, HTML, Info could be produced, but changes to texinfo.tex,
|> makeinfo, texi2html would be required to get that output.
|> 
|> 	* HTML 
|> How can one convert HTML to PostScript or Info?  
|> 
|> 	* Some other SGML-based solution (like Linuxdoc-SGML)
|> In theory, any output we like (TeX, troff, HTML) could be generated,
|> but a fair amount of coding would be required to get that output.  
|> 
|> 	* troff  
|> I don't know troff very well; presumably one can get PS output, but is
|> there a troff-to-HTML converter?
|> 
|> 	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. I think troff may be extranious at this point.

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

Cons: convertion to info not available. 

Having said this LaTeX2e would be the best choice if we are keeping it
in a ASCII readable format which can be parsed. It continues to
provide many useful output formats.

OTOH, I just installed TeX and was impressed by how much a pain in the
buttocks it was to get running.  I see the use of LaTeX in the future
dwindling (although LaTeX3 may save it).  Either way, TeX is a black
art and we're not going to get many people to help with the doc
maintenance as long as it's encoded that way. 

I'm going to download the latex2fm tool above and try my hand at 
converting the 1.4b2 docs.  (just for grins)

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

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