From Fred L. Drake, Jr." <fdrake@acm.org  Tue Feb 23 20:47:00 1999
From: Fred L. Drake, Jr." <fdrake@acm.org (Fred L. Drake)
Date: Tue, 23 Feb 1999 15:47:00 -0500 (EST)
Subject: [Doc-SIG] Undocumented modules
Message-ID: <14035.5060.260018.767352@weyr.cnri.reston.va.us>

  I spent a few minutes figuring out just what isn't documented yet in 
the Python standard library.  Though 145 modules are documented,
that's only about half of it.
  I've attached a list of the undocumented modules that are
implemented as .py files; there are more that are implemented in C,
but the number there is much smaller.
  I'm open to some suggestions as to prioritizing these as far as
documenting them goes.  I'd really love to receive documentation
sections!  ;-)


  -Fred

--
Fred L. Drake, Jr.	     <fdrake@acm.org>
Corporation for National Research Initiatives
1895 Preston White Dr.	    Reston, VA  20191


AWARE
Abstract
BoxParent
Buttons
CD
CGIHTTPServer
CL
CL_old
CSplit
Canvas
Dialog
DirList
ERRNO
FCNTL
FILE
FileDialog
FixTk
FormSplit
GET
GLWS
HVSplit
Histogram
IN
IOCTL
Para
SOCKET
STROPTS
SUNAUDIODEV
SV
ScrolledText
SimpleDialog
SimpleHTTPServer
Sliders
Soundogram
Split
StripChart
TextEdit
Tkconstants
Tkdnd
Tkinter
TransParent
VUMeter
WAIT
WindowParent
WindowSched
addpack
anywin
asynchat
asyncore
audiodev
basewin
bdb
cddb
cdplayer
cmp
cmpcache
codehack
codeop
colorsys
dbhash
dircache
dircmp
dirwin
dospath
dump
filewin
find
fmt
fpformat
grep
gwin
htmlentitydefs
ihooks
knee
linecache
listwin
lockfile
macpath
macurl2path
mainloop
mhlib
mutex
newdir
ni
ntpath
nturl2path
packmail
panel
panelparser
pipes
poly
posixpath
pty
rand
readcd
reconvert
rect
regex_syntax
rlcompleter
sched
srcwin
statcache
statvfs
stdwinevents
stdwinq
sunau
sunaudio
tablewin
tb
telnetlib
textwin
threading_api
tkColorChooser
tkCommonDialog
tkFileDialog
tkFont
tkMessageBox
tkSimpleDialog
toaiff
torgb
tty
turtle
tzparse
util
wave
wdb
wdbframewin
wdbsrcwin
whatsound
zmod


From Fred L. Drake, Jr." <fdrake@acm.org  Tue Feb 23 22:43:06 1999
From: Fred L. Drake, Jr." <fdrake@acm.org (Fred L. Drake)
Date: Tue, 23 Feb 1999 17:43:06 -0500 (EST)
Subject: [Doc-SIG] Undocumented modules
In-Reply-To: <19990223155949.56264@amber.org>
References: <14035.5060.260018.767352@weyr.cnri.reston.va.us>
 <19990223155949.56264@amber.org>
Message-ID: <14035.12026.203088.609664@weyr.cnri.reston.va.us>

Christopher G. Petrilli writes:
 > Can you split these into the following categories:

  Ok, I've pushed my logic into a somewhat-real script (care to guess
what language I used? ;), and can more easily update the list.  It
also now (optionally) considers built-in modules.  My current
interpreter only showed pcre and strop as undocumented modules
(there's also an option to ignore modules listed in a file), so that's 
probably not very interesting.
  Obsolete modules (lib-old/, lib-stdwin/) are ignored, as are the
dos-8x3/ and test/ directories.  "test" still needs to be documented
since it's a package in it's own right.
  I'll attach the "categorized" version of the output below (it's
organized by subdir within Lib/, and the various plat-* directories
are collapsed to a "virtual" directory named "plat-*").  The script
will appear in Doc/tools/.


  -Fred

--
Fred L. Drake, Jr.	     <fdrake@acm.org>
Corporation for National Research Initiatives
1895 Preston White Dr.	    Reston, VA  20191


<standard>  CGIHTTPServer
            SimpleHTTPServer
            asynchat
            asyncore
            audiodev
            bdb
            cmp
            cmpcache
            codeop
            colorsys
            dbhash
            dircache
            dircmp
            dospath
            dump
            find
            fpformat
            grep
            htmlentitydefs
            ihooks
            knee
            linecache
            macpath
            macurl2path
            mhlib
            mutex
            ntpath
            nturl2path
            packmail
            pipes
            posixpath
            pty
            reconvert
            regex_syntax
            rlcompleter
            sched
            statcache
            statvfs
            sunau
            sunaudio
            telnetlib
            threading_api
            toaiff
            tty
            turtle
            tzparse
            util
            wave
            whatsound

lib-tk      Canvas
            Dialog
            FileDialog
            FixTk
            ScrolledText
            SimpleDialog
            Tkconstants
            Tkdnd
            Tkinter
            tkColorChooser
            tkCommonDialog
            tkFileDialog
            tkFont
            tkMessageBox
            tkSimpleDialog

plat-*      AWARE
            CD
            CL
            CL_old
            ERRNO
            FCNTL
            FILE
            GET
            GLWS
            IN
            IOCTL
            SOCKET
            STROPTS
            SUNAUDIODEV
            SV
            WAIT
            cddb
            cdplayer
            panel
            panelparser
            readcd
            torgb



From petrilli@amber.org  Wed Feb 24 03:50:26 1999
From: petrilli@amber.org (Christopher G. Petrilli)
Date: Tue, 23 Feb 1999 22:50:26 -0500
Subject: [Doc-SIG] Undocumented modules
In-Reply-To: <14035.12026.203088.609664@weyr.cnri.reston.va.us>; from Fred L. Drake on Tue, Feb 23, 1999 at 05:43:06PM -0500
References: <14035.5060.260018.767352@weyr.cnri.reston.va.us> <19990223155949.56264@amber.org> <14035.12026.203088.609664@weyr.cnri.reston.va.us>
Message-ID: <19990223225026.04329@amber.org>

I've kinda gone through this and figured out what probably SHOULD be
documented, what shouldn't be documented (i.e. it's not exposed to the
outside world) and what might just be totally deprecated.

<standard>  CGIHTTPServer	DOCUMENT
            SimpleHTTPServer	DOCUMENT
            asynchat		DOCUMENT (I'm writing this right now)
            asyncore		DOCUMENT (same)
            audiodev		DOCUMENT (platform specific SGI/Sun)
            bdb			DOCUMENT (though not overly exposed)
            cmp			DEPRECATE (seems to be duplicate of cmpcache)
            cmpcache		DOCUMENT
            codeop		DOCUMENT
            colorsys		DEPRECATE (very incomplete and possible
	    			inacurate, use PIL)
            dbhash		DOCUMENT
            dircache		DOCUMENT
            dircmp		DOCUMENT
            dospath		DOCUMENT (platform specific Wintel)
            dump		DEPRECATE (seems to be half-implemented)
            find		DEPRECATE (move to scripts?)
            fpformat		DOCUMENT
            grep		DEPRECATE (move to scripts?)
            htmlentitydefs	DOCUMENT
            ihooks		DOCUMENT (see comment below)
            knee		DOCUMENT (not really usable, example)
            linecache		DOCUMENT (potentially useful with
	    			fileinput)
            macpath		DOCUMENT (platform specific Mac)
            macurl2path		DOCUMENT (platform specific Mac)
            mhlib		DOCUMENT (has anyone tested this?)
            mutex		DOCUMENT
            ntpath		DOCUMENT (platform specific NT)
            nturl2path		DOCUMENT (platform specific NT)
            packmail		DEPRECATE (move to scripts?)
            pipes		DOCUMENT
            posixpath		DOCUMENT (platform specific POSIX)
            pty			DEPRECATE (VERY VERY platform specific)
            reconvert		DEPRECATE (incomplete, move to scripts?)
            regex_syntax	DEPRECATE (regex no longer preffered)
            rlcompleter		INTERNAL (don't document)
            sched		DOCUMENT
            statcache		DOCUMENT (see notes about cache things)
            statvfs		DOCUMENT (used with os.statvfs())
            sunau		DOCUMENT (platform specific Sun)
            sunaudio		DOCUMENT (platform specific Sun)
            telnetlib		DOCUMENT
            threading_api	WHAT IS THIS?! (looks like docs for
	    			threading.py)
            toaiff		DEPRECATE (move to scripts?)
            tty			DEPRECATE (move to termios?)
            turtle		DOCUMENT (Tkinter though)
            tzparse		DOCUMENT
            util		DEPRECATE (hold over from 1.4)
            wave		DEPRECATE (not sure honestly! :-)
            whatsound		DEPRECATE (same as sndhdr)

ihooks - should this be in with the new module, it seems to be of the
same class of "shoot yourself in the foot" modules :-)  Perhaps we
should have a "WARNING" label for modules that are especially dangerous
to use?

caching things - has anyone actually tested these for performance?  A
quick check on my FreeBSD 3.0 box says they're slower than not caching
because of (I assume) file system caching effeciency...  Maybe that was
a fluke, at least with statcache ;-)

lib-tk is a royal pain :-) Maybe Frederick will finish soon! :-)

plat-*      AWARE	DOCUMENT? (is this viable on new IRIX?)
            CD		INTERNAL
            CL		DEPRECATE (seems ot be deprecated)
            CL_old	DEPRECATE (same)
            ERRNO	DOCUMENT (I'd just reference the errno.h file)
            FCNTL	DOCUMENT (same here, maybe some BASICS that are
	    		common on all platforms?)
            FILE	DOCUMENT (reference external source)
            GET		DOCUMENT (woah, major platform specific IRIX)
            GLWS	DOCUMENT (more major IRIX stuff)
            IN		DOCUMENT (reference)
            IOCTL	DOCUMENT (reference)
            SOCKET	DOCUMENT (reference)
            STROPTS	INTERNAL (dear god, who uses THIS?!?!?!)
            SUNAUDIODEV DOCUEMNT (platform specific)
            SV		DOCUMENT (more major platform IRIX stuff)
            WAIT	DOCUMENT (very useful stuff here)
            cddb	DOCUMENT (note overlap with Internet CDDB)
            cdplayer	DOCUMENT (platform specific IRIX)
            panel	DOCUMENT (same)
            panelparser DOCUMENT (same)
            readcd	DOCUMENT (same)
            torgb	DEPRECATE (use PIL I think)

As you've no doubt noticed, not much I don't say to document, BUT... I'm
worried about all this HYPER specific IRIX stuff... perhaps it should
be moved into it's own seperate documentation area, or even a seperate
distribution of sorts (a'la Mac)... there's a ton of junk that just
isn't useful for 99% of the users.

Just ideas... shoot at me at will :-)

Chris
-- 
| Christopher Petrilli                      ``Television is bubble-gum for
| petrilli@amber.org                          the mind.''-Frank Lloyd Wright


From petrilli@amber.org  Wed Feb 24 03:57:09 1999
From: petrilli@amber.org (Christopher G. Petrilli)
Date: Tue, 23 Feb 1999 22:57:09 -0500
Subject: [Doc-SIG] Documenting Asyncore
Message-ID: <19990223225709.03738@amber.org>

OK, so I talked with Sam about this, and he's written some pretty good
introductory material... but here's the thing... USING asyncore and
asynchat requires a brain adjustment for most people, which seems to be
outside the realm of the reference manual, so how to deal with this?
Should I just document the class and ignore the issue of ideology?  I
know, this is a great topic for a HOWTO, and I'm meaning to reformat
Sam's introduction into one, but... that doesn't fix the library manual.

Also, I was thinking... perhaps there should be a way to note that
there's something in the source code INTENTIONALLY undocumented that
might be of trivial use to someone maybe oneday?  DOn't know... there's
some things in asyncore like that, you might be interested, but... 

Chris
-- 
| Christopher Petrilli                      ``Television is bubble-gum for
| petrilli@amber.org                          the mind.''-Frank Lloyd Wright


From Sjoerd.Mullender@cwi.nl  Wed Feb 24 07:54:26 1999
From: Sjoerd.Mullender@cwi.nl (Sjoerd Mullender)
Date: Wed, 24 Feb 1999 08:54:26 +0100
Subject: [Doc-SIG] Undocumented modules
In-Reply-To: Your message of Tue, 23 Feb 1999 22:50:26 -0500.
 <19990223225026.04329@amber.org>
References: <14035.5060.260018.767352@weyr.cnri.reston.va.us> <19990223155949.56264@amber.org> <14035.12026.203088.609664@weyr.cnri.reston.va.us>
 <19990223225026.04329@amber.org>
Message-ID: <UTC199902240754.IAA14023.sjoerd@zeus.cwi.nl>

On Tue, Feb 23 1999 "Christopher G. Petrilli" wrote:

> I've kinda gone through this and figured out what probably SHOULD be
> documented, what shouldn't be documented (i.e. it's not exposed to the
> outside world) and what might just be totally deprecated.

> plat-*      AWARE	DOCUMENT? (is this viable on new IRIX?)
>             CD		INTERNAL
>             CL		DEPRECATE (seems ot be deprecated)
>             CL_old	DEPRECATE (same)

These 4 are deprecated.  Their functionality has been taken over by
the cd and cl modules.  AWARE is a module of constants for the cl
module, but I'm not sure whether you can actually use the
functionality that these constants represent.  If I remember right, in 
some release of SGI there was support for this, but you needed a
license (which we never got).  I doubt that anybody uses AWARE, so it
can be removed, as far as I am concerned.

>             SV		DOCUMENT (more major platform IRIX stuff)

Should be incorporated in sv module.

>             cddb	DOCUMENT (note overlap with Internet CDDB)
>             cdplayer	DOCUMENT (platform specific IRIX)
>             panel	DOCUMENT (same)
>             panelparser DOCUMENT (same)
>             readcd	DOCUMENT (same)

> As you've no doubt noticed, not much I don't say to document, BUT... I'm
> worried about all this HYPER specific IRIX stuff... perhaps it should
> be moved into it's own seperate documentation area, or even a seperate
> distribution of sorts (a'la Mac)... there's a ton of junk that just
> isn't useful for 99% of the users.

Hey, but it is useful to me!  (But then I wrote some of it.)

-- Sjoerd Mullender <Sjoerd.Mullender@cwi.nl>
   <URL:http://www.cwi.nl/~sjoerd/>


From skip@mojam.com (Skip Montanaro)  Wed Feb 24 12:16:41 1999
From: skip@mojam.com (Skip Montanaro) (skip@mojam.com (Skip Montanaro))
Date: Wed, 24 Feb 1999 07:16:41 -0500 (EST)
Subject: [Doc-SIG] Undocumented modules
In-Reply-To: <14035.12026.203088.609664@weyr.cnri.reston.va.us>
References: <14035.5060.260018.767352@weyr.cnri.reston.va.us>
 <19990223155949.56264@amber.org>
 <14035.12026.203088.609664@weyr.cnri.reston.va.us>
Message-ID: <14035.60340.751903.974927@dolphin.calendar.com>

    Fred> Ok, I've pushed my logic into a somewhat-real script ...
	...
    Fred> <standard>  CGIHTTPServer
	...
    Fred>             posixpath
	...

Fred,

I think there's a logic bug.  The posixpath module is documented at

    http://www.python.org/doc/lib/module-posixpath.html

Also, some minor modules that only define manifest constants (SOCKET, ERRNO,
regex_syntax all come to mind) probably aren't worth mentioning outside the
documentation of other modules (socket, errno, regex, respectively).  ERRNO,
in particular, seems to be sucked into errno in its entirety, so probably
shouldn't be treated as a user-visible module:

    >>> id(errno.E2BIG)
    134968712
    >>> id(ERRNO.E2BIG)
    134968712

Skip


From Fred L. Drake, Jr." <fdrake@acm.org  Wed Feb 24 14:28:19 1999
From: Fred L. Drake, Jr." <fdrake@acm.org (Fred L. Drake)
Date: Wed, 24 Feb 1999 09:28:19 -0500 (EST)
Subject: [Doc-SIG] Undocumented modules
In-Reply-To: <14035.60340.751903.974927@dolphin.calendar.com>
References: <14035.5060.260018.767352@weyr.cnri.reston.va.us>
 <19990223155949.56264@amber.org>
 <14035.12026.203088.609664@weyr.cnri.reston.va.us>
 <14035.60340.751903.974927@dolphin.calendar.com>
Message-ID: <14036.3203.257788.606083@weyr.cnri.reston.va.us>

skip@mojam.com writes:
 > I think there's a logic bug.  The posixpath module is documented at
 > 
 >     http://www.python.org/doc/lib/module-posixpath.html

Skip,
  No, that's left over from the previous version of the documentation; 
I'll remove it... done.  The index of documented modules doesn't list
posixpath, and probably shouldn't; it is listed as an undocumented
implementation detail.  See:

	http://www.python.org/doc/lib/modindex.html
	http://www.python.org/doc/lib/node300.html

  (On the other hand, I just used it explicitly for something where
that made sense.  Perhaps each of the *path modules should be
documented, but only say that it's an implementation of os.path for
the specific OS; there are times when this is exactly what's needed.)

 > Also, some minor modules that only define manifest constants (SOCKET, ERRNO,
 > regex_syntax all come to mind) probably aren't worth mentioning outside the
 > documentation of other modules (socket, errno, regex, respectively).  ERRNO,
 > in particular, seems to be sucked into errno in its entirety, so probably

  ERRNO is not sucked into errno.  The identity match for small
integers is due to the small integers cache maintained internally to
Objects/intobject.c as a performance improvement.
  I'd like to see modules that consist only of constants for use with
other modules folded into those modules and removed.  If the module is 
something that the user is expected to import, it should be
documented, even if trivially:

	http://www.python.org/doc/lib/module-DEVICE.html


  -Fred

--
Fred L. Drake, Jr.	     <fdrake@acm.org>
Corporation for National Research Initiatives
1895 Preston White Dr.	    Reston, VA  20191


From skip@mojam.com (Skip Montanaro)  Wed Feb 24 14:57:13 1999
From: skip@mojam.com (Skip Montanaro) (skip@mojam.com (Skip Montanaro))
Date: Wed, 24 Feb 1999 09:57:13 -0500 (EST)
Subject: [Doc-SIG] Undocumented modules
In-Reply-To: <14036.3203.257788.606083@weyr.cnri.reston.va.us>
References: <14035.5060.260018.767352@weyr.cnri.reston.va.us>
 <19990223155949.56264@amber.org>
 <14035.12026.203088.609664@weyr.cnri.reston.va.us>
 <14035.60340.751903.974927@dolphin.calendar.com>
 <14036.3203.257788.606083@weyr.cnri.reston.va.us>
Message-ID: <14036.4585.560352.643176@dolphin.calendar.com>

>>>>> "Fred" == Fred L Drake <fdrake@cnri.reston.va.us> writes:

    Fred> skip@mojam.com writes:
    >> I think there's a logic bug.  The posixpath module is documented at
    >> 
    >> http://www.python.org/doc/lib/module-posixpath.html

    Fred> No, that's left over from the previous version of the
    Fred> documentation; I'll remove it... done.

What's wrong with the old (1.5.1?) version of the posixpath documentation?
Did it change so much between 1.5.1 and 1.5.2 that it has to be rewritten?
I must be missing something pretty basic.

    Fred> ERRNO is not sucked into errno.  The identity match for small
    Fred> integers is due to the small integers cache maintained internally to
    Fred> Objects/intobject.c as a performance improvement.

Yup, my bad.  Okay, so errno is documented, but ERRNO isn't, yet they seem
to contain much the same contents.  What's the difference?

    Fred> I'd like to see modules that consist only of constants for use
    Fred> with other modules folded into those modules and removed.  If the
    Fred> module is something that the user is expected to import, it should
    Fred> be documented, even if trivially:

Good point.  That would work for SOCKET, but the errno/ERRNO overlap still
confuses me.

Skip


From Fred L. Drake, Jr." <fdrake@acm.org  Wed Feb 24 15:18:15 1999
From: Fred L. Drake, Jr." <fdrake@acm.org (Fred L. Drake)
Date: Wed, 24 Feb 1999 10:18:15 -0500 (EST)
Subject: [Doc-SIG] Undocumented modules
In-Reply-To: <14036.4585.560352.643176@dolphin.calendar.com>
References: <14035.5060.260018.767352@weyr.cnri.reston.va.us>
 <19990223155949.56264@amber.org>
 <14035.12026.203088.609664@weyr.cnri.reston.va.us>
 <14035.60340.751903.974927@dolphin.calendar.com>
 <14036.3203.257788.606083@weyr.cnri.reston.va.us>
 <14036.4585.560352.643176@dolphin.calendar.com>
Message-ID: <14036.6199.602456.91085@weyr.cnri.reston.va.us>

skip@mojam.com writes:
 > What's wrong with the old (1.5.1?) version of the posixpath documentation?
 > Did it change so much between 1.5.1 and 1.5.2 that it has to be rewritten?
 > I must be missing something pretty basic.

  'fraid so:  It's all listed under posixpath.  ;-)  The new docs
are for os.path (it's still in the file .../libposixpath.tex).  This
makes more sense for more people, and better encourages the cross-
platform usage.

 > Yup, my bad.  Okay, so errno is documented, but ERRNO isn't, yet they seem
 > to contain much the same contents.  What's the difference?

  I presume ERRNO, SOCKET, and many other ALL_UPPERCASE_MODULES
predate the approach of incorporating constants directly in the module 
with which they're used.  Several of these files appear to be
generated by h2py, and they're located in the plat-*/ directories.
  These should probably be removed whenever possible.  I don't see any 
imports of ERRNO, FILE, GET, GLWS, IN, IOCTL, SOCKET, SV, or WAIT
anywhere in the standard library.  I *do* see AL, CD, DEVICE, FCNTL,
FL, and GL used.  CL is only used by AWARE, which Sjoerd said should be
tossed.  CD and FCNTL are not documented, but maybe should be.


  -Fred

--
Fred L. Drake, Jr.	     <fdrake@acm.org>
Corporation for National Research Initiatives
1895 Preston White Dr.	    Reston, VA  20191


From skip@mojam.com (Skip Montanaro)  Wed Feb 24 15:39:52 1999
From: skip@mojam.com (Skip Montanaro) (skip@mojam.com (Skip Montanaro))
Date: Wed, 24 Feb 1999 10:39:52 -0500 (EST)
Subject: [Doc-SIG] Undocumented modules
In-Reply-To: <14036.6199.602456.91085@weyr.cnri.reston.va.us>
References: <14035.5060.260018.767352@weyr.cnri.reston.va.us>
 <19990223155949.56264@amber.org>
 <14035.12026.203088.609664@weyr.cnri.reston.va.us>
 <14035.60340.751903.974927@dolphin.calendar.com>
 <14036.3203.257788.606083@weyr.cnri.reston.va.us>
 <14036.4585.560352.643176@dolphin.calendar.com>
 <14036.6199.602456.91085@weyr.cnri.reston.va.us>
Message-ID: <14036.7412.750632.892572@dolphin.calendar.com>

    Fred> skip@mojam.com writes:
    >> What's wrong with the old (1.5.1?) version of the posixpath documentation?
    >> Did it change so much between 1.5.1 and 1.5.2 that it has to be rewritten?
    >> I must be missing something pretty basic.

    Fred>   'fraid so:  It's all listed under posixpath.  ;-)  The new docs
    Fred> are for os.path (it's still in the file .../libposixpath.tex).  This
    Fred> makes more sense for more people, and better encourages the cross-
    Fred> platform usage.

So all that's needed is to rename the TeX file and twiddle some words?


From Fred L. Drake, Jr." <fdrake@acm.org  Wed Feb 24 15:47:18 1999
From: Fred L. Drake, Jr." <fdrake@acm.org (Fred L. Drake)
Date: Wed, 24 Feb 1999 10:47:18 -0500 (EST)
Subject: [Doc-SIG] Undocumented modules
In-Reply-To: <14036.7412.750632.892572@dolphin.calendar.com>
References: <14035.5060.260018.767352@weyr.cnri.reston.va.us>
 <19990223155949.56264@amber.org>
 <14035.12026.203088.609664@weyr.cnri.reston.va.us>
 <14035.60340.751903.974927@dolphin.calendar.com>
 <14036.3203.257788.606083@weyr.cnri.reston.va.us>
 <14036.4585.560352.643176@dolphin.calendar.com>
 <14036.6199.602456.91085@weyr.cnri.reston.va.us>
 <14036.7412.750632.892572@dolphin.calendar.com>
Message-ID: <14036.7942.474286.925503@weyr.cnri.reston.va.us>

skip@mojam.com writes:
 > So all that's needed is to rename the TeX file and twiddle some words?

  *Was* needed.  I went ahead and got it done when I fixed up the os
module documentation.


  -Fred

--
Fred L. Drake, Jr.	     <fdrake@acm.org>
Corporation for National Research Initiatives
1895 Preston White Dr.	    Reston, VA  20191


From skip@mojam.com (Skip Montanaro)  Wed Feb 24 15:56:50 1999
From: skip@mojam.com (Skip Montanaro) (skip@mojam.com (Skip Montanaro))
Date: Wed, 24 Feb 1999 10:56:50 -0500 (EST)
Subject: [Doc-SIG] Undocumented modules
In-Reply-To: <14036.7942.474286.925503@weyr.cnri.reston.va.us>
References: <14035.5060.260018.767352@weyr.cnri.reston.va.us>
 <19990223155949.56264@amber.org>
 <14035.12026.203088.609664@weyr.cnri.reston.va.us>
 <14035.60340.751903.974927@dolphin.calendar.com>
 <14036.3203.257788.606083@weyr.cnri.reston.va.us>
 <14036.4585.560352.643176@dolphin.calendar.com>
 <14036.6199.602456.91085@weyr.cnri.reston.va.us>
 <14036.7412.750632.892572@dolphin.calendar.com>
 <14036.7942.474286.925503@weyr.cnri.reston.va.us>
Message-ID: <14036.8276.449428.91848@dolphin.calendar.com>

    Fred> skip@mojam.com writes:
    >> So all that's needed is to rename the TeX file and twiddle some words?

    Fred>   *Was* needed.  I went ahead and got it done when I fixed up the os
    Fred> module documentation.

Okay, so I was able to whine loud enough to send Fred screaming to his
keyboard to fix up posixpath just to get me to shut up. :-) Fred, as your
payment, send me two general modules you think are most critical and that
still need to be documented (your choice, though some restrictions apply --
no Windows- or SGI-specific stuff).  I'll write 'em up and ship 'em back.

Skip Montanaro	| Mojam: "Uniting the World of Music" http://www.mojam.com/
skip@mojam.com  | Musi-Cal: http://www.musi-cal.com/
518-372-5583



From da@ski.org  Wed Feb 24 17:06:50 1999
From: da@ski.org (David Ascher)
Date: Wed, 24 Feb 1999 09:06:50 -0800 (Pacific Standard Time)
Subject: [Doc-SIG] Undocumented modules
In-Reply-To: <14036.8276.449428.91848@dolphin.calendar.com>
Message-ID: <Pine.WNT.4.04.9902240906380.269-100000@rigoletto.ski.org>

On Wed, 24 Feb 1999 skip@mojam.com wrote:

> Okay, so I was able to whine loud enough to send Fred screaming to his
> keyboard to fix up posixpath just to get me to shut up. :-) Fred, as your
> payment, send me two general modules you think are most critical and that
> still need to be documented (your choice, though some restrictions apply --
> no Windows- or SGI-specific stuff).  I'll write 'em up and ship 'em back.

Fred: send him Tkinter.py =)





From guido@CNRI.Reston.VA.US  Wed Feb 24 17:09:11 1999
From: guido@CNRI.Reston.VA.US (Guido van Rossum)
Date: Wed, 24 Feb 1999 12:09:11 -0500
Subject: [Doc-SIG] Documenting Asyncore
In-Reply-To: Your message of "Tue, 23 Feb 1999 22:57:09 EST."
 <19990223225709.03738@amber.org>
References: <19990223225709.03738@amber.org>
Message-ID: <199902241709.MAA05675@eric.cnri.reston.va.us>

> OK, so I talked with Sam about this, and he's written some pretty good
> introductory material... but here's the thing... USING asyncore and
> asynchat requires a brain adjustment for most people, which seems to be
> outside the realm of the reference manual, so how to deal with this?
> Should I just document the class and ignore the issue of ideology?  I
> know, this is a great topic for a HOWTO, and I'm meaning to reformat
> Sam's introduction into one, but... that doesn't fix the library manual.

I'm not sure why it wouldn't fit in the library manual.  For example
the profiler and debugger chapters have some tutorial style material
in them, and there are some others.

> Also, I was thinking... perhaps there should be a way to note that
> there's something in the source code INTENTIONALLY undocumented that
> might be of trivial use to someone maybe oneday?  DOn't know... there's
> some things in asyncore like that, you might be interested, but... 

I'm not sure what you are talking about here -- to indicate that
something is not intended to be documented a comment in the source
should be sufficient.  Documenting seems to be an oximoron ("there's
this really nify undocumented printindex() method in this class that
you're not supposed to use but could nevertheless be real handy one
day" ???).

--Guido van Rossum (home page: http://www.python.org/~guido/)


From petrilli@amber.org  Wed Feb 24 17:13:33 1999
From: petrilli@amber.org (Christopher G. Petrilli)
Date: Wed, 24 Feb 1999 12:13:33 -0500
Subject: [Doc-SIG] Documenting Asyncore
In-Reply-To: <199902241709.MAA05675@eric.cnri.reston.va.us>; from Guido van Rossum on Wed, Feb 24, 1999 at 12:09:11PM -0500
References: <19990223225709.03738@amber.org> <199902241709.MAA05675@eric.cnri.reston.va.us>
Message-ID: <19990224121333.26463@amber.org>

On Wed, Feb 24, 1999 at 12:09:11PM -0500, Guido van Rossum wrote:
> > OK, so I talked with Sam about this, and he's written some pretty good
> > introductory material... but here's the thing... USING asyncore and
> > asynchat requires a brain adjustment for most people, which seems to be
> > outside the realm of the reference manual, so how to deal with this?
> > Should I just document the class and ignore the issue of ideology?  I
> > know, this is a great topic for a HOWTO, and I'm meaning to reformat
> > Sam's introduction into one, but... that doesn't fix the library manual.
> 
> I'm not sure why it wouldn't fit in the library manual.  For example
> the profiler and debugger chapters have some tutorial style material
> in them, and there are some others.

My fear was that while the profiler/debuggers have "tutorials", the
async programming idea requires more like 10-15 pages of stuff to
really get it across to people in a sane way they can understand... it's
just too different for most people's mindset. 

Anyway, what I'm thinkin is just document it a'la a regular library with
a 1-2 paragraph introduction as to WHAT async sockets are meant to
provide, and then say 2 examples of small size which show it being used
(probably Sam's proxy example being one).  a HOWTO could then delve into
it more deeply.

> > Also, I was thinking... perhaps there should be a way to note that
> > there's something in the source code INTENTIONALLY undocumented that
> > might be of trivial use to someone maybe oneday?  DOn't know... there's
> > some things in asyncore like that, you might be interested, but... 
> 
> I'm not sure what you are talking about here -- to indicate that
> something is not intended to be documented a comment in the source
> should be sufficient.  Documenting seems to be an oximoron ("there's
> this really nify undocumented printindex() method in this class that
> you're not supposed to use but could nevertheless be real handy one
> day" ???).

Ignore that, i"m not sure what I was talking about :-)  I think I was
reffering to there being some aspects of libraries that shouldn't be
twiddled with without a deep understanding of the working code.  My
later comment about "dangerous" things might fit in better with that.
Looking back, I must have been suffering from some drug (legal) induced
stupor!

Chris
-- 
| Christopher Petrilli                      ``Television is bubble-gum for
| petrilli@amber.org                          the mind.''-Frank Lloyd Wright


From Fred L. Drake, Jr." <fdrake@acm.org  Wed Feb 24 17:18:40 1999
From: Fred L. Drake, Jr." <fdrake@acm.org (Fred L. Drake)
Date: Wed, 24 Feb 1999 12:18:40 -0500 (EST)
Subject: [Doc-SIG] Documenting Asyncore
In-Reply-To: <19990224121333.26463@amber.org>
References: <19990223225709.03738@amber.org>
 <199902241709.MAA05675@eric.cnri.reston.va.us>
 <19990224121333.26463@amber.org>
Message-ID: <14036.13424.673299.997153@weyr.cnri.reston.va.us>

On Wed, Feb 24, 1999 at 12:09:11PM -0500, Guido van Rossum wrote:
 > I'm not sure why it wouldn't fit in the library manual.  For example
 > the profiler and debugger chapters have some tutorial style material
 > in them, and there are some others.

Christopher G. Petrilli writes:
 > My fear was that while the profiler/debuggers have "tutorials", the
 > async programming idea requires more like 10-15 pages of stuff to

  I think we can spare a few pages of introductory material, and good, 
succinct examples are always welcome.  Longer, tutorial style material 
can be a separate document, and I'll be glad for the standard docs to
refer to such a beast, *if* I can have reference material in the
library manual!
  Perhaps my policy should be "If you write it, I will \input."  ;-)


  -Fred

--
Fred L. Drake, Jr.	     <fdrake@acm.org>
Corporation for National Research Initiatives
1895 Preston White Dr.	    Reston, VA  20191


From guido@CNRI.Reston.VA.US  Wed Feb 24 17:31:23 1999
From: guido@CNRI.Reston.VA.US (Guido van Rossum)
Date: Wed, 24 Feb 1999 12:31:23 -0500
Subject: [Doc-SIG] Undocumented modules
In-Reply-To: Your message of "Tue, 23 Feb 1999 22:50:26 EST."
 <19990223225026.04329@amber.org>
References: <14035.5060.260018.767352@weyr.cnri.reston.va.us> <19990223155949.56264@amber.org> <14035.12026.203088.609664@weyr.cnri.reston.va.us>
 <19990223225026.04329@amber.org>
Message-ID: <199902241731.MAA05707@eric.cnri.reston.va.us>

>             cmp		DEPRECATE (seems to be duplicate of cmpcache)
>             cmpcache		DOCUMENT

No, cmpcache uses statcache.stat() while cmp uses os.stat().  But both
are borderline -- I wrote them when writing a visual diff for stdwin 7
or 8 years ago and haven't touched or used them since...



>             codeop		DOCUMENT
>             colorsys		DEPRECATE (very incomplete and possible
> 	    			inacurate, use PIL)

Hm...  This incorporates quite a bit of arcane knowledge that was hard
to come by when we wrote it.  I'm not sure where it is incomplete or
inaccurate.

>             fpformat		DOCUMENT

Deprecate it; you can now do this using the % operator on strings.

>             linecache		DOCUMENT (potentially useful with
> 	    			fileinput)

(Also used intensely by anything printing tracebacks.)

>             mhlib		DOCUMENT (has anyone tested this?)

Yes, I use it a lot, and just today I received some patches from a
mostly happy user in the newsgroup.

>             mutex		DOCUMENT

Hmm, this is very shady and seems to predate threads!

>             pty		DEPRECATE (VERY VERY platform specific)

But also very useful when it works.  I'd like to keep it.

>             rlcompleter	INTERNAL (don't document)

Document it; it's actually useful.  One needs to know to import this
in $PYTHONSTASRTUP, and one could subclass it to use different
completion rules.

>             sched		DOCUMENT

Like mutex -- not clear how useful this is.

>             threading_api	WHAT IS THIS?! (looks like docs for
> 	    			threading.py)

Exactly.  Should be deleted now that this is in the library manual.

>             tty		DEPRECATE (move to termios?)

Document -- it's a higher-level thing that could be useful.

>             tzparse		DOCUMENT

And someone should finish it!

>             wave		DEPRECATE (not sure honestly! :-)

Document!  It reads/writes .wav sound files.

> ihooks - should this be in with the new module, it seems to be of the
> same class of "shoot yourself in the foot" modules :-)  Perhaps we
> should have a "WARNING" label for modules that are especially dangerous
> to use?

Although less so -- "new" can easily cause core dumps, ihooks can just 
screw cause tracebacks...

> caching things - has anyone actually tested these for performance?  A
> quick check on my FreeBSD 3.0 box says they're slower than not caching
> because of (I assume) file system caching effeciency...  Maybe that was
> a fluke, at least with statcache ;-)

Exactly how did you test it?  This is needed especially when using
NFS, since stat over NFS is slow and synchronous.

>             ERRNO	DOCUMENT (I'd just reference the errno.h file)

Deprecate; we now have this and more in errno.

> As you've no doubt noticed, not much I don't say to document, BUT... I'm
> worried about all this HYPER specific IRIX stuff... perhaps it should
> be moved into it's own seperate documentation area, or even a seperate
> distribution of sorts (a'la Mac)... there's a ton of junk that just
> isn't useful for 99% of the users.

Agreed.  There is already an SGI specific chapter that could easily be
lifeted out.  Some of it is also very old and of questionable utility
in modern SGI systems (even if SGI survives :-).

--Guido van Rossum (home page: http://www.python.org/~guido/)


From Fred L. Drake, Jr." <fdrake@acm.org  Wed Feb 24 17:38:06 1999
From: Fred L. Drake, Jr." <fdrake@acm.org (Fred L. Drake)
Date: Wed, 24 Feb 1999 12:38:06 -0500 (EST)
Subject: [Doc-SIG] Global Module Index
Message-ID: <14036.14590.164551.200660@weyr.cnri.reston.va.us>

  Take a look at this:

	http://www.python.org/doc/modindex.html

  This page is a combined module index, listing modules in the "lib"
and "mac" manuals at the moment.  This is probably of only limited
interest at the moment, but may be more interesting to people working
on the Mac or later if the library reference manual is further split.
  If anyone has any comments on this before it's publicized more
widely, I'd be glad to hear them.


  -Fred

--
Fred L. Drake, Jr.	     <fdrake@acm.org>
Corporation for National Research Initiatives
1895 Preston White Dr.	    Reston, VA  20191


From petrilli@amber.org  Wed Feb 24 17:42:01 1999
From: petrilli@amber.org (Christopher G. Petrilli)
Date: Wed, 24 Feb 1999 12:42:01 -0500
Subject: [Doc-SIG] Undocumented modules
In-Reply-To: <199902241731.MAA05707@eric.cnri.reston.va.us>; from Guido van Rossum on Wed, Feb 24, 1999 at 12:31:23PM -0500
References: <14035.5060.260018.767352@weyr.cnri.reston.va.us> <19990223155949.56264@amber.org> <14035.12026.203088.609664@weyr.cnri.reston.va.us> <19990223225026.04329@amber.org> <199902241731.MAA05707@eric.cnri.reston.va.us>
Message-ID: <19990224124201.51816@amber.org>

On Wed, Feb 24, 1999 at 12:31:23PM -0500, Guido van Rossum wrote:
> >             colorsys		DEPRECATE (very incomplete and possible
> > 	    			inacurate, use PIL)
> 
> Hm...  This incorporates quite a bit of arcane knowledge that was hard
> to come by when we wrote it.  I'm not sure where it is incomplete or
> inaccurate.

Um, missing color systems like CMYK (which of course are nearly
impossible to do), but also is part of the concept of imaging a'la PIL
it seems, so awefully incomplete without the ability to do
transformations in the color system (histograms, etc).

> >             mhlib		DOCUMENT (has anyone tested this?)
> 
> Yes, I use it a lot, and just today I received some patches from a
> mostly happy user in the newsgroup.

I noticed this myself, such timing :-)  

> >             mutex		DOCUMENT
> 
> Hmm, this is very shady and seems to predate threads!

It has some interesting capabilities though probably not thread-safe...
but threads don't work on every system unfortunately.

> >             sched		DOCUMENT
> 
> Like mutex -- not clear how useful this is.

Same as mutex, might be useful for non-threading systems to use, and
might also be useful to throw into an individual thread to deal with
"future events".

> >             tty		DEPRECATE (move to termios?)
> 
> Document -- it's a higher-level thing that could be useful.

But should it go into termios?

> >             tzparse		DOCUMENT
> 
> And someone should finish it!

Just what I wnated to work on, timezone parsing *gack*

> > caching things - has anyone actually tested these for performance?  A
> > quick check on my FreeBSD 3.0 box says they're slower than not caching
> > because of (I assume) file system caching effeciency...  Maybe that was
> > a fluke, at least with statcache ;-)
> 
> Exactly how did you test it?  This is needed especially when using
> NFS, since stat over NFS is slow and synchronous.

No I didn't do it over NFS, since I don't have NFS.  Maybe the
documentation should mention that it's advantages are over NFS, not on
direct file systems?  

> > As you've no doubt noticed, not much I don't say to document, BUT... I'm
> > worried about all this HYPER specific IRIX stuff... perhaps it should
> > be moved into it's own seperate documentation area, or even a seperate
> > distribution of sorts (a'la Mac)... there's a ton of junk that just
> > isn't useful for 99% of the users.
> 
> Agreed.  There is already an SGI specific chapter that could easily be
> lifeted out.  Some of it is also very old and of questionable utility
> in modern SGI systems (even if SGI survives :-).

Oh SGI will survive, probably as a Microsoft vendor unfortunately.  Sad
because IRIX was the best of the Unices in performance and amazing
feature sets (I still use the guaranteed filesystem bandwidth feature).

Chris
-- 
| Christopher Petrilli                      ``Television is bubble-gum for
| petrilli@amber.org                          the mind.''-Frank Lloyd Wright


From petrilli@amber.org  Wed Feb 24 17:49:18 1999
From: petrilli@amber.org (Christopher G. Petrilli)
Date: Wed, 24 Feb 1999 12:49:18 -0500
Subject: [Doc-SIG] Global Module Index
In-Reply-To: <14036.14590.164551.200660@weyr.cnri.reston.va.us>; from Fred L. Drake on Wed, Feb 24, 1999 at 12:38:06PM -0500
References: <14036.14590.164551.200660@weyr.cnri.reston.va.us>
Message-ID: <19990224124918.52226@amber.org>

On Wed, Feb 24, 1999 at 12:38:06PM -0500, Fred L. Drake wrote:
> 
>   Take a look at this:
> 
> 	http://www.python.org/doc/modindex.html

I wonder if it's possible to notate "platform specific" modules in
italics or something?  Just so people don't go looking for them if they
are trying to be portable.

Also, how 'bout a link to this from the main doc page, I miss that :-)

Chris
-- 
| Christopher Petrilli                      ``Television is bubble-gum for
| petrilli@amber.org                          the mind.''-Frank Lloyd Wright


From da@ski.org  Wed Feb 24 17:53:33 1999
From: da@ski.org (David Ascher)
Date: Wed, 24 Feb 1999 09:53:33 -0800 (Pacific Standard Time)
Subject: [Doc-SIG] Undocumented modules
In-Reply-To: <19990224124201.51816@amber.org>
Message-ID: <Pine.WNT.4.04.9902240951360.269-100000@rigoletto.ski.org>

On Wed, 24 Feb 1999, Christopher G. Petrilli wrote:

> On Wed, Feb 24, 1999 at 12:31:23PM -0500, Guido van Rossum wrote:
> > >             colorsys		DEPRECATE (very incomplete and possible
> > > 	    			inacurate, use PIL)
> > 
> > Hm...  This incorporates quite a bit of arcane knowledge that was hard
> > to come by when we wrote it.  I'm not sure where it is incomplete or
> > inaccurate.
> 
> Um, missing color systems like CMYK (which of course are nearly
> impossible to do), but also is part of the concept of imaging a'la PIL
> it seems, so awefully incomplete without the ability to do
> transformations in the color system (histograms, etc).

It's still useful (one may want to do colorspace manipulations just
within Tkinter, for example), it's small, and it's not that hard to
document.  Unless proven inaccurate, I vote to keep it.  If I have to
document it to keep it, I'm willing to do that.

--david



From Fred L. Drake, Jr." <fdrake@acm.org  Wed Feb 24 18:01:01 1999
From: Fred L. Drake, Jr." <fdrake@acm.org (Fred L. Drake)
Date: Wed, 24 Feb 1999 13:01:01 -0500 (EST)
Subject: [Doc-SIG] Undocumented modules
In-Reply-To: <Pine.WNT.4.04.9902240951360.269-100000@rigoletto.ski.org>
References: <19990224124201.51816@amber.org>
 <Pine.WNT.4.04.9902240951360.269-100000@rigoletto.ski.org>
Message-ID: <14036.15965.140962.710502@weyr.cnri.reston.va.us>

David Ascher writes:
 > document.  Unless proven inaccurate, I vote to keep it.  If I have to
 > document it to keep it, I'm willing to do that.

  I will remember this.  Just ask Jim Fulton!  ;-)


  -Fred

--
Fred L. Drake, Jr.	     <fdrake@acm.org>
Corporation for National Research Initiatives
1895 Preston White Dr.	    Reston, VA  20191


From Fred L. Drake, Jr." <fdrake@acm.org  Wed Feb 24 18:01:29 1999
From: Fred L. Drake, Jr." <fdrake@acm.org (Fred L. Drake)
Date: Wed, 24 Feb 1999 13:01:29 -0500 (EST)
Subject: [Doc-SIG] Global Module Index
In-Reply-To: <19990224124918.52226@amber.org>
References: <14036.14590.164551.200660@weyr.cnri.reston.va.us>
 <19990224124918.52226@amber.org>
Message-ID: <14036.15993.801795.887762@weyr.cnri.reston.va.us>

Christopher G. Petrilli writes:
 > I wonder if it's possible to notate "platform specific" modules in
 > italics or something?  Just so people don't go looking for them if they

  That would be nice.  There's nothing in the documentation now that
allows that information to be extracted; placement within a chapter is 
the only source of that information, making it essentially human-
only.
  I think explicit markup of the information would be the most
appropriate way to deal with this.  Perhaps the \declaremodule could
optionally be followed by a \platform macro that accepted a comma-
separated list of platforms (sys.platform values) as a parameter.  If
\platform isn't specified, the module would be considered portable.
  The macro probably shouldn't generate any text, but could be used to 
produce information in an auxilliary file and the index.  That
auxilliary file could be used when generating other documentation
items.

 > Also, how 'bout a link to this from the main doc page, I miss that :-)

  That's comes with the general announcement.


  -Fred

--
Fred L. Drake, Jr.	     <fdrake@acm.org>
Corporation for National Research Initiatives
1895 Preston White Dr.	    Reston, VA  20191


From petrilli@amber.org  Wed Feb 24 18:17:59 1999
From: petrilli@amber.org (Christopher G. Petrilli)
Date: Wed, 24 Feb 1999 13:17:59 -0500
Subject: [Doc-SIG] Global Module Index
In-Reply-To: <14036.15993.801795.887762@weyr.cnri.reston.va.us>; from Fred L. Drake on Wed, Feb 24, 1999 at 01:01:29PM -0500
References: <14036.14590.164551.200660@weyr.cnri.reston.va.us> <19990224124918.52226@amber.org> <14036.15993.801795.887762@weyr.cnri.reston.va.us>
Message-ID: <19990224131759.44787@amber.org>

On Wed, Feb 24, 1999 at 01:01:29PM -0500, Fred L. Drake wrote:
> 
> Christopher G. Petrilli writes:
>  > I wonder if it's possible to notate "platform specific" modules in
>  > italics or something?  Just so people don't go looking for them if they
> 
>   I think explicit markup of the information would be the most
> appropriate way to deal with this.  Perhaps the \declaremodule could
> optionally be followed by a \platform macro that accepted a comma-
> separated list of platforms (sys.platform values) as a parameter.  If
> \platform isn't specified, the module would be considered portable.

Or maybe an option component of \declaremodule?  This sounds good
though, as it would require people to explicitely document platform
specific pieces, and eventually could be used to break the manual into
pieces automatically. 

Chris
-- 
| Christopher Petrilli                      ``Television is bubble-gum for
| petrilli@amber.org                          the mind.''-Frank Lloyd Wright


From skip@mojam.com (Skip Montanaro)  Wed Feb 24 18:24:55 1999
From: skip@mojam.com (Skip Montanaro) (skip@mojam.com (Skip Montanaro))
Date: Wed, 24 Feb 1999 13:24:55 -0500 (EST)
Subject: [Doc-SIG] Global Module Index
In-Reply-To: <14036.14590.164551.200660@weyr.cnri.reston.va.us>
References: <14036.14590.164551.200660@weyr.cnri.reston.va.us>
Message-ID: <14036.16993.58806.944808@dolphin.calendar.com>

    Fred>   Take a look at this:
    Fred> 	http://www.python.org/doc/modindex.html

This is great.  Is this a "definite" for the documentation?  If so, I can
get rid of the index I've been generating for awhile and just redirect to
this one.

Chris Petrelli suggested italics for the platform-specific docs.  I think it
would be better to have "sections" for each of the different platforms
instead.  That way, the last column might look more like (underscores denote
emphasis or bolding of some kind):

    whichdb 
    whrandom 
    winsound 
    xdrlib 
    xmllib 
    zlib

    _Macintosh_

    mac 
    macconsole 
    macdnr 
    macfs 
    MacOS 
    macostools 
    macpath 
    macspeech 
    mactcp 

    _SGI_

    aifc
    AL
    al
    ...

Is that kind of division into sections possible?

Skip



From Fred L. Drake, Jr." <fdrake@acm.org  Wed Feb 24 18:30:02 1999
From: Fred L. Drake, Jr." <fdrake@acm.org (Fred L. Drake)
Date: Wed, 24 Feb 1999 13:30:02 -0500 (EST)
Subject: [Doc-SIG] Global Module Index
In-Reply-To: <19990224131759.44787@amber.org>
References: <14036.14590.164551.200660@weyr.cnri.reston.va.us>
 <19990224124918.52226@amber.org>
 <14036.15993.801795.887762@weyr.cnri.reston.va.us>
 <19990224131759.44787@amber.org>
Message-ID: <14036.17706.704771.314461@weyr.cnri.reston.va.us>

Christopher G. Petrilli writes:
 > Or maybe an option component of \declaremodule?  This sounds good

  \declaremodule currently has the form:

	\declaremodule[key]{standard|builtin|...}{modulename}

where "key" is an optional parameter that is used to specify a
reference key component when the modulename contains an underscore.
Additional paramters would have to be required, and I don't want to
penalize documentation authors for portable modules.  Probably the
easiest way to deal with it in LaTeX would be something like:

	\forplatform{myplat}{
	  \declaremodule...
	}

which is a little ugly.  I could probably work out the logistics with
the less-hostile form (no nesting):

	\declaremodule...
	  \platform{myplat}

 > though, as it would require people to explicitely document platform
 > specific pieces, and eventually could be used to break the manual into
 > pieces automatically. 

  I'd probably avoid fully automatic decomposition, but I can see
having a script that would take a file like lib.tex and produce
something similar but only with (or without) the bits for specific
platforms.  Once you have that, automation is mostly a matter of glue, 
though I'd expect it to be little used.


  -Fred

--
Fred L. Drake, Jr.	     <fdrake@acm.org>
Corporation for National Research Initiatives
1895 Preston White Dr.	    Reston, VA  20191


From Fred L. Drake, Jr." <fdrake@acm.org  Wed Feb 24 18:33:54 1999
From: Fred L. Drake, Jr." <fdrake@acm.org (Fred L. Drake)
Date: Wed, 24 Feb 1999 13:33:54 -0500 (EST)
Subject: [Doc-SIG] Global Module Index
In-Reply-To: <14036.16993.58806.944808@dolphin.calendar.com>
References: <14036.14590.164551.200660@weyr.cnri.reston.va.us>
 <14036.16993.58806.944808@dolphin.calendar.com>
Message-ID: <14036.17938.318817.849486@weyr.cnri.reston.va.us>

skip@mojam.com writes:
 > This is great.  Is this a "definite" for the documentation?  If so, I can

  In some form, probably not too different from the prototype.

 > Chris Petrelli suggested italics for the platform-specific docs.  I think it
 > would be better to have "sections" for each of the different platforms

  Nice.  If we can include explicit markup for platform dependencies
in the documentation, I don't see any reason not to have both.
They're mosly just different sort orders.


  -Fred

--
Fred L. Drake, Jr.	     <fdrake@acm.org>
Corporation for National Research Initiatives
1895 Preston White Dr.	    Reston, VA  20191


From skip@mojam.com (Skip Montanaro)  Wed Feb 24 20:45:44 1999
From: skip@mojam.com (Skip Montanaro) (skip@mojam.com (Skip Montanaro))
Date: Wed, 24 Feb 1999 15:45:44 -0500 (EST)
Subject: [Doc-SIG] Undocumented modules
In-Reply-To: <Pine.WNT.4.04.9902240906380.269-100000@rigoletto.ski.org>
References: <14036.8276.449428.91848@dolphin.calendar.com>
 <Pine.WNT.4.04.9902240906380.269-100000@rigoletto.ski.org>
Message-ID: <14036.25670.824211.889964@dolphin.calendar.com>

    David> Fred: send him Tkinter.py =)

You dog! ;-) Fred already sent me two other modules I've never used (but
will get chummy with in the near future).  I didn't get the Spanish
Inquisition, but then again, I wasn't really expecting it...

Skip


From Jack.Jansen@cwi.nl  Wed Feb 24 22:52:42 1999
From: Jack.Jansen@cwi.nl (Jack Jansen)
Date: Wed, 24 Feb 1999 23:52:42 +0100
Subject: [Doc-SIG] Undocumented modules
In-Reply-To: Message by "Christopher G. Petrilli" <petrilli@amber.org> ,
 Wed, 24 Feb 1999 12:42:01 -0500 , <19990224124201.51816@amber.org>
Message-ID: <UTC199902242252.XAA00965.jack@trawler.cwi.nl>

Recently, "Christopher G. Petrilli" <petrilli@amber.org> said:
> > >             colorsys		DEPRECATE (very incomplete and possible
> > > 	    			inacurate, use PIL)
> > 
> > Hm...  This incorporates quite a bit of arcane knowledge that was hard
> > to come by when we wrote it.  I'm not sure where it is incomplete or
> > inaccurate.
> 
> Um, missing color systems like CMYK (which of course are nearly
> impossible to do), but also is part of the concept of imaging a'la PIL
> it seems, so awefully incomplete without the ability to do
> transformations in the color system (histograms, etc).

Its main use would be in dialogs (allow users to specify colors in hls 
or whatever), and possibly to build conversion arrays, but I'm not
sure whether it is used by anyone anymore. Nope, I myself don't seem
to use it any longer...
--
Jack Jansen             | ++++ stop the execution of Mumia Abu-Jamal ++++
Jack.Jansen@cwi.nl      | ++++ if you agree copy these lines to your sig ++++
http://www.cwi.nl/~jack | see http://www.xs4all.nl/~tank/spg-l/sigaction.htm 


From fredrik@pythonware.com  Thu Feb 25 09:16:04 1999
From: fredrik@pythonware.com (Fredrik Lundh)
Date: Thu, 25 Feb 1999 10:16:04 +0100
Subject: [Doc-SIG] Undocumented modules
Message-ID: <00bc01be609f$7956a2a0$f29b12c2@pythonware.com>

various posters wrote:
>> Um, missing color systems like CMYK (which of course are nearly
>> impossible to do), but also is part of the concept of imaging a'la PIL
>> it seems, so awefully incomplete without the ability to do
>> transformations in the color system (histograms, etc).
>
>Its main use would be in dialogs (allow users to specify colors in hls 
>or whatever), and possibly to build conversion arrays, but I'm not
>sure whether it is used by anyone anymore.

PIL's not really a replacement for colorsys, since PIL doesn't
contain any code to deal with non-trivial colour spaces.

On the other hand, the code in colorsys.py is not very useful,
since it doesn't define what RGB or YUV/YIQ space it uses for
it's coefficients (looks like it's using NTSC values, which is used
by about 0% of all computer systems these days...)

I vote for a removal.

(by the way, the initial comment is really confusing; the
person who wrote that probably didn't know that "XYZ" is
the name of an existing, and very important colour space.
I almost submitted a bug report before I realized what that
comment was supposed to mean... ;-)

Cheers /F
fredrik@pythonware.com
http://www.pythonware.com



From Fred L. Drake, Jr." <fdrake@acm.org  Thu Feb 25 14:06:33 1999
From: Fred L. Drake, Jr." <fdrake@acm.org (Fred L. Drake)
Date: Thu, 25 Feb 1999 09:06:33 -0500 (EST)
Subject: [Doc-SIG] Undocumented modules
In-Reply-To: <00bc01be609f$7956a2a0$f29b12c2@pythonware.com>
References: <00bc01be609f$7956a2a0$f29b12c2@pythonware.com>
Message-ID: <14037.22761.753429.228127@weyr.cnri.reston.va.us>

Fredrik Lundh writes:
 > (by the way, the initial comment is really confusing; the
 > person who wrote that probably didn't know that "XYZ" is
 > the name of an existing, and very important colour space.
 > I almost submitted a bug report before I realized what that
 > comment was supposed to mean... ;-)

  Misleading comments are bugs.  Please describe the specific
confusion (and how to avoid it!) so this can be fixed.  I don't know
enough about color spaces to just figure it out.


  -Fred

--
Fred L. Drake, Jr.	     <fdrake@acm.org>
Corporation for National Research Initiatives
1895 Preston White Dr.	    Reston, VA  20191


From Fred L. Drake, Jr." <fdrake@acm.org  Fri Feb 26 17:04:20 1999
From: Fred L. Drake, Jr." <fdrake@acm.org (Fred L. Drake)
Date: Fri, 26 Feb 1999 12:04:20 -0500 (EST)
Subject: [Doc-SIG] Re: Links between documents?
In-Reply-To: <199902261642.LAA15123@dolphin.calendar.com>
References: <199902261642.LAA15123@dolphin.calendar.com>
Message-ID: <14038.54292.707815.756021@weyr.cnri.reston.va.us>

  Skip Montanaro wrote, in mail to python-docs, that inter-document
linking and/or a combined index would be very useful, especially since 
may people use the HTML version of the documentation.
  I agree; I've been trying to improve the level of hyperlinking in
the manuals[1], but don't have anything for inter-document linking yet.
I've looked into LaTeX approaches to this, and some things do exist.
None of them seem to be quite right, but I don't expect it to be too
difficult to create something that is close enough and has the right
level of support.
  I think the primitive should be something like \doclink{tag}{label}, 
where tag is an ID for the target document (something like api, ext,
lib, mac, etc.), and label is a name defined by \label in the other
document.  There should be something similar, like
\modlink[key]{tag}{modulename}, for use with module.  (Modules have
the nasty property that their names may include underscores, which
break all things TeXish in the Python documentation, and also numbers, 
which break my experimental platform dependence annotation; "key" is
used to provide an alternate identifier to use in constructing the
parameter to \label.)
  A combined index will be a bit easier, and has crossed my mind
before.  The scripts that process index information probably won't
need to much augmentation.  (Patches welcome.)
  Any ideas?  Suggestions?


  -Fred

[1] Note the addition of \refmodule to the set of macros; this creates 
    a hyperlink to a module section within the same document, with the 
    link text being the module name.  This is essentially a linking
    version of \module.  As I've had to do things to sections, I've
    been looking for opportunities to convert \module to \refmodule.

--
Fred L. Drake, Jr.	     <fdrake@acm.org>
Corporation for National Research Initiatives
1895 Preston White Dr.	    Reston, VA  20191


From Fred L. Drake, Jr." <fdrake@acm.org  Fri Feb 26 23:10:32 1999
From: Fred L. Drake, Jr." <fdrake@acm.org (Fred L. Drake)
Date: Fri, 26 Feb 1999 18:10:32 -0500 (EST)
Subject: [Doc-SIG] Platform dependency annotations for module docs
Message-ID: <14039.10728.875260.783563@weyr.cnri.reston.va.us>

  I have a preliminary version of platform dependency annotations for
the module documentation working.  There are a few things that still
need to be worked out, but I should be able to check in this version
on Monday (I don't have enough time to work out the checkin message
before I have to go for the day, or I'd do it now).


  -Fred

--
Fred L. Drake, Jr.	     <fdrake@acm.org>
Corporation for National Research Initiatives
1895 Preston White Dr.	    Reston, VA  20191


From Fred L. Drake, Jr." <fdrake@acm.org  Fri Feb 26 23:12:45 1999
From: Fred L. Drake, Jr." <fdrake@acm.org (Fred L. Drake)
Date: Fri, 26 Feb 1999 18:12:45 -0500 (EST)
Subject: [Doc-SIG] Looking for Mike McLay
Message-ID: <14039.10861.209737.274578@weyr.cnri.reston.va.us>

  Mike McLay (our SIG champion) doesn't seem to be answering his
email.  Does anyone here have a better way to contact him?
  Thanks.


  -Fred

--
Fred L. Drake, Jr.	     <fdrake@acm.org>
Corporation for National Research Initiatives
1895 Preston White Dr.	    Reston, VA  20191