Mailman 3 February 1999 - Doc-SIG

Looking for Mike McLay
by Fred L. Drake Feb. 26, 1999

Feb. 26, 1999

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(a)acm.org> Corporation for National Research Initiatives 1895 Preston White Dr. Reston, VA 20191

1 0

Platform dependency annotations for module docs
by Fred L. Drake Feb. 26, 1999

Feb. 26, 1999

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(a)acm.org> Corporation for National Research Initiatives 1895 Preston White Dr. Reston, VA 20191

1 0

Re: Links between documents?
by Fred L. Drake Feb. 26, 1999

Feb. 26, 1999

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(a)acm.org> Corporation for National Research Initiatives 1895 Preston White Dr. Reston, VA 20191

1 0

Re: [Doc-SIG] Undocumented modules
by Fredrik Lundh Feb. 25, 1999

Feb. 25, 1999

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(a)pythonware.com http://www.pythonware.com

2 1

Re: [Doc-SIG] Undocumented modules
by Jack Jansen Feb. 24, 1999

Feb. 24, 1999

Recently, "Christopher G. Petrilli" <petrilli(a)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(a)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

1 0

Re: [Doc-SIG] Undocumented modules
by Fred L. Drake Feb. 24, 1999

Feb. 24, 1999

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(a)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

6 15

Global Module Index
by Fred L. Drake Feb. 24, 1999

Feb. 24, 1999

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(a)acm.org> Corporation for National Research Initiatives 1895 Preston White Dr. Reston, VA 20191

3 6

Documenting Asyncore
by Christopher G. Petrilli Feb. 24, 1999

Feb. 24, 1999

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(a)amber.org the mind.''-Frank Lloyd Wright

3 3

Undocumented modules
by Fred L. Drake Feb. 23, 1999

Feb. 23, 1999

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(a)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

1 0