[PYTHON DOC-SIG] Documentation format

[Jim Fulton]

Robin Friedrich wrote:
> 
> |> 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?

Yes.

> |>      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?

> I think troff may be extranious at this point.

Hm.
 
> 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.
 
> 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 never had the enthusiasm to get TeX or any of it's variants running on
any 
platform I had access to.  I doubt I ever will.
 
Personally, I think that we should strive for generating as much
documentation 
as possible from module doc strings.  

I also think a simple doc string format should be used with clever
conversion 
tools. I've has quite satisfactory results doing this myself.

Jim

-- 
Jim Fulton         Digital Creations
jim@digicool.com   540.371.6909
## Python is my favorite language ##
##     http://www.python.org/     ##

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

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