[PYTHON DOC-SIG] Re: Do reference/user docs exist for the Py* API?

[Michael McLay]

Skip Montanaro writes:
 > 
 > I'd like to generate one or more template documents automatically from the C
 > source or some other easily created template file that I can then make
 > available to people with an interest in completing individual sections.  I
 > don't want to get into a quagmire right off the bat, so I will initially
 > move this discussion from the main list to the doc-sig@python.org list.
 > (Don't worry, I'll move it back when I need more help... :-) Would someone
 > involved with the DOC-SIG (Michael McLay perhaps?)  give me a quick
 > brain-dump of the current state of the musings on the DOC-SIG, especially
 > about issues of documentation format, input source, etc?  

Robin's answer covered what's been discussed lately on the WWW pages.
I am a bit concerned about standardizing on Framemaker.  I've watch my
organization "standardize" on two commercial products for
wordprocessing.  There are definite pitfalls in picking a vendor.
An immediate problem is that Framemaker isn't universally available
this choice will limit who can participate in the documentation project.

I just read about another possible option.  YODL is described as:

  nsect(What's YODL?)

    YODL (Yet Oneother Document Language) is a package that consists of
    programs, some shell scripts, and auxiliary "lib" files for which hold
    macro files. The whole purpose of the package is to provide a
    simple-to-use and extensible document language, that can be used to
    convert documents in the YODL format to a variety of other formats. In
    this purpose, YODL somewhat resembles generic markup languages, e.g. SGML
    footnote(Standard Generalized Markup Language) but:

The paragraph is in YODL notation.  I'm not advocating it.  I just
thought it might be of interest.

How about writing the documentation in Python?  That should be
flexible enough.  It also shouldn't take too much to add a minimal GUI
front end so you don't have to write lots of special notation
characters.  If the objects were massaged properly the html2ps.py
filter could be used to output the documents to a postscript printer.

Michael

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

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