Mailman 3 September 2005 - Doc-SIG

Python 2.4.2 documentation online
by Fred L. Drake, Jr. Sept. 28, 2005

Sept. 28, 2005

The Python 2.4.2 documentation is now online in the main documentation area (as opposed to just the /dev/ area) for both www.python.org and docs.python.org. The 2.4 and 2.4.1 documentation areas have been updated to link to the 2.4.2 documentation as the preferred documentation for all 2.4.x releases. -Fred -- Fred L. Drake, Jr. <fdrake at acm.org>

1 0

Documenting the use of CPython and zipfiles?
by Bill Janssen Sept. 22, 2005

Sept. 22, 2005

I went looking for documentation on how to use Python's version of jar files today. It's very well hidden in the 2.3.5 documentation on my MacOS X 10.4.2 system. I finally found documentation of "zipimport" in the 2.4 documentation (still fairly hidden). But along the way, I wondered several times why there was no document about "Using Python", or even just the CPython man page (I was thinking of Java's "-jar" command-line flag), in the standard documentation set you see when you visit the documentation on the Web site. I guess you'd want something like: 1. Invoking CPython 2. Notes about CPython on Windows 3. Notes about CPython on MacOS X 4. Notes about CPython on Linux ... Bill

1 0

Two bugs in python.sty
by Wojciech Śmigaj Sept. 20, 2005

Sept. 20, 2005

Hello, Recently I've uploaded two patches dealing with some typographical problems of the Python LaTeX package (python.sty) to the Sourceforge tracker of the Python project. Up to now I haven't received any feedback, and I see it's kind of "normal" for patches submitted there to be left unnoticed ;-), so perhaps I'll better mention them here, too. The first patch does away with excessive space surrounding text typeset within verbatim environments; its Tracker page is http://sourceforge.net/tracker/index.php?func=detail&aid=1293788&group_id=5… The second ensures that headings of classdesc, methoddesc and similar environments are separated from the following text with proper amount of space: currently, it is not the case with multiline headings. The patch's URL is http://sourceforge.net/tracker/index.php?func=detail&aid=1293790&group_id=5… I believe these problems (esp. the former) are fairly visible to an average reader of Python documentation, and their correction would definitely improve its looks. So perhaps someone from the Doc team could review the patches :-). Thanks! Wojciech Smigaj

2 2

page names other than 'nodeX'?
by Chad Whitacre Sept. 15, 2005

Sept. 15, 2005

Hey all, I am learning the Python LaTeX system, and I am a bit stuck on how to generate pages with names other than 'nodeX.' I see the node2label perl script in the src/Doc/tools directory, and I've bashed about in the Makefile but been unable to figure out how to use that script. I will keep bashing but I thought I would check here for any gotchas or pointers. I'd also love to put sections in their own folders if anyone has any tips on that as well. Thanks! chad

1 1

Re: [Doc-SIG] [Python-Dev] Python core documentation
by Fred L. Drake, Jr. Sept. 7, 2005

Sept. 7, 2005

On Tuesday 06 September 2005 16:26, Rodrigo Bernardo Pimentel wrote: > I sent this to Fred Drake a few weeks ago but got no response. I > assume he's busy, or maybe my message never reached him. I hope some of > you will have opinions on this (BTW, please Cc: me on any replies, as I am > not on python-dev). Again, I'm sorry I haven't had time to reply until now, but reminders/re-posts like this are certainly a welcome reminder! > (Original message below) > > I was sharing some ideas with Gustavo Niemeyer (who's also > receiving a copy of this message) and he told me you'd be the right person > to talk to [he was also the one who recommended that I resent it to > python-dev]. I'll suggest that the Documentation SIG is a better place to discuss this for some reasons, and I've CC'd that list as well. > I'm relatively new to Python, my first project with it started at > the beginning of 2004. And, from the start, its documentation bugged me a > little. Now I'm completely hooked and am a full-time Python programmer, > but I still see the same quirks in documentation. > > I don't mean to say there's lack of it, but I think it needs some > work, it seems quite incomplete. I see some of these characteristics in > the tutorial and module documentation, but I'm refering mostly to internal > documentation. It appears that by "internal" you're referring to the docstrings available from the runtime. I generally only think of those as hints or reminders, and not complete documentation (other minds disagree). For the non-docstring documentation, the same kinds of issues occur, though not always for the same features. I'd categorize the issues you point out into two groups: A) Omissions. You're right; there's a lot of places we haven't been as thorough as we should be. These certainly should be corrected by adding the missing information. B) Vague contracts. There are many places where documentation is omitted because the contracts of the documented feature aren't clearly specified by the code. This may happen for many reasons, but how each should be handled has to be determined on a case-by-case basis. In many cases, it's intentional that edge cases aren't well specified, simply because the treatment hasn't been discussed and decided. This case can usually be resolved by bringing up specific cases; once there's some discussion, useful documentation can be written because the documentation writers learn what the intent was (or the developers have to decide what the contract should be). Historically, I think we've seen a lot of (B) simply because there's an expectation of users will read the source to determine what the feature will do in any given case. As we see more implementations appear, and as the size and range of Python's audience grow, this becomes a less reasonable approach. This is especially the case for features implemented in C, since users are increasingly unlikely to have the C sources handy due to the use of pre-compiled packages on all platforms. [...lots of specific examples elided...] > As I told Niemeyer, I considered sending documentation patches, > but I think a standard should be defined first, and then volunteers > (myself included) could sweep over the core language and conform > documentation to it. I'm willing to work on it and help however I can, but > I wanted to discuss it first (that's why I came to Niemeyer). It would be good to have more specific guidelines for documentation. We've generally avoided trying to specify what exceptions can be raised by various functions or methods, and describe only specific cases that are guaranteed as part of the API. Treatment of edge cases is often left as an accident as well, though not as frequently. As the documentation increasingly becomes the way that programmers learn about the details of the library, we need to think about whether this is the right approach. In addition to this, we should settle the question of completeness of docstrings and document it. Anything missing that should be included according to that decision should then be added. Also, the level of detail regarding edge cases and exceptions that we're willing to make contract should be discussed, and documentation brought up to snuff. This is more likely an issue that will require case-by-case treatment. -Fred -- Fred L. Drake, Jr. <fdrake at acm.org>

1 0

No hyperref used in documentation?
by Torsten Bronger Sept. 1, 2005

Sept. 1, 2005

Hallöchen! I use \ProvidesClass{howto} [1998/02/25 Document class (Python HOWTO)] for creating documentation for my little Python project. However, all links in the TOC lead to nothing. pdfTeX says multiple times: ! pdfTeX warning (dest): name{page005} has been referenced but does not exist, replaced by a fixed one Apparently hyperref.sty is not used at all. Is there a reason for that? And, of course, how can I activate the links in my TOC? Thank you! Tschö, Torsten. -- Torsten Bronger, aquisgrana, europa vetus ICQ 264-296-646

1 0