Mailman 3 February 2001 - Doc-SIG

Error in pyexpat docs
by uche.ogbuji＠fourthought.com July 9, 2002

July 9, 2002

An excerpt from the Python 2.0 docs for pyexpat: """ ParseFile (file) Parse XML data reading from the object file. file only needs to provide the read(nbytes) method, returning the empty string when there's no more data. [snip] The following attributes contain values relating to the most recent error encountered by an xmlparser object, and will only have correct values once a call to Parse() or ParseFile() has raised a xml.parsers.expat.error exception. ErrorByteIndex Byte index at which an error occurred. [etc.] """ The wrong, "xml.parsers.expat" is the first indicator that there might be a problem, yet I took the docs at their word and wrapped the call to ParseFile in a blanket try/except, only to find that no exception of any sort is ever raised by ParseFile. It turns out that ParseFile actually returns 0 on error, returning 1 otherwise. The first matter is that the code and the docs need to be reconciled. However, I would _much_ rather prefer that things were as in the docs. I think ParseFile should raise an exception rather than return an error flag. Interestingly enough, this is the same argument I had with a colleague just last week. -- Uche Ogbuji Principal Consultant uche.ogbuji(a)fourthought.com +1 303 583 9900 x 101 Fourthought, Inc. http://Fourthought.com 4735 East Walnut St, Ste. C, Boulder, CO 80301-2537, USA Software-engineering, knowledge-management, XML, CORBA, Linux, Python

3 2

A draft for a "defining new types" chapter for ext.tex
by Michael Hudson March 5, 2001

March 5, 2001

After various people noticing that there is no documentation at all for defining new types for python in the standard docs I set to work: http://www-jcsu.jesus.cam.ac.uk/~mwh21/hacks/ext/defining-new-types.html It's not even nearly finished; I would like to add sections on supporting GC, coercion, rich comparisons &c (partly because documenting such things would force me to learn about them!). But I would like to see what people think. It strikes me that (a) to define a new type really you need to understand how Python is implemented. So perhaps I should write a Python-Internals-HOWTO first. (b) The Extending and Embedding Manual could really do with being entirely rewritten. (c) It's hard to think of a sensible order to write such a thing in without lots of circular dependencies (of the form you need to read chapter I to understand chapter II, but to understand chapter I you need to have read chapter III which requires understanding chapter II...). Anybody got some spare-time-in-a-tin? Cheers, M.

3 9

Doc build question
by Dan Milgram March 1, 2001

March 1, 2001

I'm having some difficulty simply building the html docs, and was hoping someone could help me out as I am not familiar with LaTeX. All the docs build ok, with the exception of the modindex.html files (they simply contain the header and footer info but no actual index entries). I am using the following relevant packages on a RedHat box: latex2html99.2beta8 ActivePerl5.6 tetex-1.0.6-11 Anyone else encountered this, or is there a particular environment variable that I need to have set before the build? Any help would be greatly appreciated. Dan Milgram

2 1

[development doc updates]
by Fred L. Drake Feb. 19, 2001

Feb. 19, 2001

The development version of the documentation has been updated: http://python.sourceforge.net/devel-docs/

1 0

[development doc updates]
by Fred L. Drake Feb. 14, 2001

Feb. 14, 2001

The development version of the documentation has been updated: http://python.sourceforge.net/devel-docs/

1 0

Pre-alpha release of docutils
by Tony J Ibbs (Tibs) Feb. 13, 2001

Feb. 13, 2001

Well, I took Tuesday off as holiday to work on docutils, on the grounds that my since-the-new-year work rate of about an hour a week on it was getting, well, nowhere, and thus I can now announce: The very first very pre-alpha release 0.0.1 of docutils The current status of the code is documented at: http://www.tibsnjoan.co.uk/docutils/status.html http://www.tibsnjoan.demon.co.uk/docutils/status.html http://homepage.ntlworld.com/tibsnjoan/docutils/status.html (technically, those first two should be the same place, but I know there's been trouble with that first URL in the past). That page also includes information on downloading the code (well, the current snapshot of my "working" directory). Note that the "Structured Text for Python docstrings" page is now moved to be in the same directory - so if you care, please adjust your bookmarks appropriately (it's referenced from the "status" page). What does it do? Well, it will read a Python file and output its docstrings as not-terribly-good HTML, and it will also read a StructuredText file and output that as similar quality HTML. There's a detailed checklist of exactly which bits of ST it supports in the "status" document, but it does enough to be potentially useful (although it's not very fast). The reason I'm still calling it "pre-alpha" is that I want to do a significant code rewrite of the main innards - but on the other hand, if I waited until that was finished, I probably wouldn't be releasing anything until at least a month away. As normal, all comments are welcomed. But I already know that the docstrings are often wrong... Tibs Postcript: Damn, checking the output of stpy.py when run on Colourise.py, I see there's a major bug in (at least some) list items - it's dropping all but the first line (see, for instance, the Module documentation). It's probably something very stupid, and I don't have time to look at it right now, so I might as well announce this stuff anyway, and I'll try to look at it this evening. Ho hum. -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "Bounce with the bunny. Strut with the duck. Spin with the chickens now - CLUCK CLUCK CLUCK!" BARNYARD DANCE! by Sandra Boynton My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)

1 2

Python 2.1 alpha 2 docs released
by Fred L. Drake, Jr. Feb. 2, 2001

Feb. 2, 2001

The documentation for the Python 2.1 alpha 2 release is now available. View it online at: http://python.sourceforge.net/devel-docs/ (This version will be updated as the documentation evolves, so will be updated beyond what's in the downloadable packages.) Downloadable packages in many formats are also available at: ftp://ftp.python.org/pub/python/doc/2.1a2/ Please avoid printing this documentation -- it's for the alpha, and could waste entire forests! Thanks to everyone who has helped improve the documentation! As always, suggestions and bug reports are welcome. For more instructions on how to file bug reports and where to send suggestions for improvement, see: http://python.sourceforge.net/devel-docs/about.html -Fred -- Fred L. Drake, Jr. <fdrake at acm.org> PythonLabs at Digital Creations

1 0

Doc tree frozen for 2.1a2
by Fred L. Drake, Jr. Feb. 2, 2001

Feb. 2, 2001

The Doc/ tree in the Python CVS is frozen until Python 2.1a2 has been released. No further changes should be made in that part of the tree. -Fred -- Fred L. Drake, Jr. <fdrake at acm.org> PythonLabs at Digital Creations

1 0