From bronger at physik.rwth-aachen.de Thu Sep 1 18:15:03 2005 From: bronger at physik.rwth-aachen.de (Torsten Bronger) Date: Thu, 01 Sep 2005 18:15:03 +0200 Subject: [Doc-SIG] No hyperref used in documentation? Message-ID: <87u0h44veg.fsf@wilson.rwth-aachen.de> 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 From fdrake at acm.org Wed Sep 7 05:10:09 2005 From: fdrake at acm.org (Fred L. Drake, Jr.) Date: Tue, 6 Sep 2005 23:10:09 -0400 Subject: [Doc-SIG] [Python-Dev] Python core documentation In-Reply-To: <20050906202602.GE4534@isnomore.net> References: <20050906202602.GE4534@isnomore.net> Message-ID: <200509062310.10132.fdrake@acm.org> 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. From chad at zetaweb.com Thu Sep 15 19:47:13 2005 From: chad at zetaweb.com (Chad Whitacre) Date: Thu, 15 Sep 2005 13:47:13 -0400 Subject: [Doc-SIG] page names other than 'nodeX'? Message-ID: 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 From chad at zetaweb.com Thu Sep 15 20:41:32 2005 From: chad at zetaweb.com (Chad Whitacre) Date: Thu, 15 Sep 2005 14:41:32 -0400 Subject: [Doc-SIG] page names other than 'nodeX'? In-Reply-To: References: Message-ID: All, I've found that node2label is called from mkhowto. I believe the issue is in my Makefile, which I've included below. If I add --numeric to MKHOWTO then the last nodeX.html is removed, but I can't see that any other files change. Thanks. chad --------------------- # Makefile to create documentation using the Python LaTeX system. PYTHON_SRC = /home/whit537/sandbox/Python-2.4.1 MKHOWTO = $(PYTHON_SRC)/Doc/tools/mkhowto \ --iconserver icons \ --split 0 \ --favicon icons/pyfav.gif \ --dir ../html \ --logging html: rm -rf ../html $(MKHOWTO) manual.tex cp -r ../icons ../html/ rm -rf ../html/icons/.svn clean: rm -f *~ *.aux *.idx *.ilg *.ind *.log *.toc *.bkm *.syn \ *.pla *.eps *.pdf *.ps *.lof *.l2h *.tex2 *.dvi From achu at klub.chip.pl Tue Sep 20 17:25:28 2005 From: achu at klub.chip.pl (=?ISO-8859-2?Q?Wojciech_=A6migaj?=) Date: Tue, 20 Sep 2005 17:25:28 +0200 Subject: [Doc-SIG] Two bugs in python.sty Message-ID: <433029E8.3060407@klub.chip.pl> 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=5470&atid=305470 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=5470&atid=305470 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 From fdrake at acm.org Tue Sep 20 18:35:53 2005 From: fdrake at acm.org (Fred L. Drake, Jr.) Date: Tue, 20 Sep 2005 12:35:53 -0400 Subject: [Doc-SIG] Two bugs in python.sty In-Reply-To: <433029E8.3060407@klub.chip.pl> References: <433029E8.3060407@klub.chip.pl> Message-ID: <200509201235.55324.fdrake@acm.org> On Tuesday 20 September 2005 11:25, Wojciech ?migaj wrote: > 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. Unfortunately, you're right. :-( I've assigned these two to myself, since I'm kinda to blame for at least one of the problems you identified and certainly for the delay in getting to documentation patches. I definately appreciate the patches; these deal with problems that are outside my TeX-knowledge. Unfortunately, the only thing I use LaTeX (or any flavor of TeX) for these days is the Python documentation, so I've not had sufficient excuse or time to keep up with how things are done. If you don't see progress on these in the next week, feel free to say nasty things about me on the list. :-) -Fred -- Fred L. Drake, Jr. From achu at klub.chip.pl Tue Sep 20 20:30:52 2005 From: achu at klub.chip.pl (=?UTF-8?B?V29qY2llY2ggxZptaWdhag==?=) Date: Tue, 20 Sep 2005 20:30:52 +0200 Subject: [Doc-SIG] Two bugs in python.sty In-Reply-To: <200509201235.55324.fdrake@acm.org> References: <433029E8.3060407@klub.chip.pl> <200509201235.55324.fdrake@acm.org> Message-ID: <4330555C.80804@klub.chip.pl> Fred L. Drake, Jr. wrote: > If you don't see progress on these in the next week, feel free to say nasty > things about me on the list. :-) Hope I won't have to :-). Thanks for your interest. I'm afraid my description of the source of the "sigline" problem wasn't very clear, so if you have any questions, ask me to reformulate it. Wojciech From janssen at parc.xerox.com Fri Sep 23 00:02:01 2005 From: janssen at parc.xerox.com (Bill Janssen) Date: Thu, 22 Sep 2005 15:02:01 PDT Subject: [Doc-SIG] Documenting the use of CPython and zipfiles? Message-ID: <05Sep22.150206pdt."58617"@synergy1.parc.xerox.com> 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 From fdrake at acm.org Wed Sep 28 07:05:50 2005 From: fdrake at acm.org (Fred L. Drake, Jr.) Date: Wed, 28 Sep 2005 01:05:50 -0400 Subject: [Doc-SIG] Python 2.4.2 documentation online Message-ID: <200509280105.50475.fdrake@acm.org> 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.