[PYTHON DOC-SIG] Documentation format

[Andrew Kuchling]

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?


	Andrew Kuchling
	amk@magnet.com

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

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