Mailman 3 October 2000 - 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

Too many files!
by Fred L. Drake, Jr. Oct. 19, 2000

Oct. 19, 2000

The Python 2.0 documentation was released as 18(!) different files. There are three different formatted versions (HTML, PDF, PostScript), with two paper sizes for each of the later, and a documentation source package. For each of these variants, three different archive formats are provided. At some point, I'd like to provide HTML Help as well. This has been provided by a volunteer in the past, and may be again (otherwise I get to do it). That's another file (making 19). Does anyone mind if I remove any of these from future releases? Which ones? The .tar.bz2 files are the best compressed, and there are reports that tools are available to handle these on Windows. Would anyone object if I removed the .tgz and .zip archives? -Fred -- Fred L. Drake, Jr. <fdrake at acm.org> PythonLabs Team Member

5 5

Re: [Doc-SIG] DocBook introduction?
by Daniel Yoo Oct. 13, 2000

Oct. 13, 2000

On Thu, 12 Oct 2000, Mike Miller wrote: > > >Hmm... is there a gentle introduction to DocBook? The Definitive Guide > >looks like rough going, although I'm sure I'll figure things out with > >time. > > Did you get any responses? I'm using DocBook some now but it's pretty > shakey. 'The Definitive Guide' is rough, and I'd like to supplement my > knowledge from some better sources. Actually, I did receive a few responses. The Gnome project has quite a few good links to DocBook stuff: http://developer.gnome.org/projects/gdp/handbook/gdp-handbook/

1 0

Re: [XML-SIG] documentation
by Fred L. Drake, Jr. Oct. 11, 2000

Oct. 11, 2000

[CC'd to the Doc-SIG as well.] Martin v. Loewis writes: > I'm currently working on the major body of the SAX interfaces, mostly > by extracting the doc strings into TeX. Great, since I was planning to work on them this week! I'll merge some of your xml.dom documentation with some that Paul sent directly to me, and get that in later this week. (Hopefully by Wed.) I've told Paul that I'd really like to have everything that will be in the final release in by Thursday, and will have a doc freeze on Friday. -Fred -- Fred L. Drake, Jr. <fdrake at beopen.com> BeOpen PythonLabs Team Member

2 2

DocBook introduction?
by Daniel Yoo Oct. 11, 2000

Oct. 11, 2000

A while ago, I made a random comment about wanting to write a "Best Hits of tutor(a)python.org" page. Now that I think about it, that sounds like a fun and useful project. I can't have too much fun, so I'd like to use this as an excuse to learn DocBook. Hmm... is there a gentle introduction to DocBook? The Definitive Guide looks like rough going, although I'm sure I'll figure things out with time. If you have any suggestions on this "Best Hits", I'd be glad to hear them. Thanks!

1 0

Nit in "urllib" library documentation
by Ka-Ping Yee Oct. 10, 2000

Oct. 10, 2000

See http://www.python.org/doc/1.5.2p2/lib/module-urllib.html The last chunk of the section on "urlopen" appears to be repeated twice: The urlopen() function works transparently with proxies... For example (the "%" is the command prompt): ... In a Macintosh environment, urlopen() will retrieve proxy information from Internet Config. The urlopen() function works transparently with proxies... For example (the "%" is the command prompt): ... In a Macintosh environment, urlopen() will retrieve proxy information from Internet Config. -- ?!ng

2 1

library reference contents
by Ka-Ping Yee Oct. 10, 2000

Oct. 10, 2000

The contents page of the Library Reference has a few warts: - A few section headers (e.g. operator, pprint, repr) end in periods that probably ought to be deleted. (Complete list: 3.5, 3.23, 3.24, 3.27, 3.32, 4.2, 4.3, 4.5, 5.10, 6.13, 6.15, 7.1, 7.6, 11.11, 11.12, 11.13, 12.13, 12.14, 14.9, 14.10, 15.4.) - Description of 3.28 "new" doesn't make much sense: "runtime implementation object creation" (probably you want to replace "implementation" with "instance") - Description of 4.3 "regex" should probably say "old" or "deprecated". - Description of 6.12 "curses" has a spelling mistake: "Terminal independant (sic) console handling". - Description of 7.14 "rlcompleter" probably ought to say "Completion function for GNU readline". - Descriptions of 11.14 "SimpleHTTPServer" and 11.15 "CGIHTTPServer" seem strange: "A Do-Something Request Handler". Suggest "11.14 SimpleHTTPServer -- A simple HTTP request handler" and "11.16 CGIHTTPServer -- A CGI-capable HTTP request handler". Hope this helps. -- ?!ng "I'm not trying not to answer the question; i'm just not answering it." -- Lenore Snell

2 1

Re: [Doc-SIG] Re: [XML-SIG] documentation
by Mike Miller Oct. 9, 2000

Oct. 9, 2000

>Martin v. Loewis writes: > > I'm currently working on the major body of the SAX interfaces, mostly > > by extracting the doc strings into TeX. > > Great, since I was planning to work on them this week! I'll merge >some of your xml.dom documentation with some that Paul sent directly >to me, and get that in later this week. (Hopefully by Wed.) > I've told Paul that I'd really like to have everything that will be >in the final release in by Thursday, and will have a doc freeze on >Friday. Stupid question time. This isn't an automated process via pythondoc or happydoc? - Mike

1 0

Fench Translation of Python Documentation
by Benoit Lacherez Oct. 4, 2000

Oct. 4, 2000

Hello, I'm happy to announce that the website of the project for a French translation of Python Documentation is online on http://pythonfr.free.fr/ Bye -- Benoit Lacherez Libourne - France Projet de traduction de la documentation de Python: http://pythonfr.free.fr/

1 0