Mailman 3 May 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

documenting Python constraints on types
by Frederic Giacometti June 10, 2001

June 10, 2001

Michel Pelletier wrote: > Ignore this please, emacs key bindings should not be confused with pine > key bindings. Well, too late :))) My remarks: A) "The Problem": Michel lists much relevant items, but then he forgets to resume what the problem is (from the listed elements): The problem Michel describes in a <<documentation>> problem. B) The proposed solution: In my experience, in 80% of the cases relevant to the 'problem', the two issues are: - what is required from the objects passed as argument - what is returned by the function/methods - what are the exceptions of interest Michel's proposal just misses this. So, for completeness's sake, the should be completed with the ability to prefix argument and functions ('def ...') with one or several 'interfaces'. FYI, I'm attaching a Python documentation convention I wrote 6 months ago. It has been successfully used in 2 industrial projects; it is now used in JPE too. I guess I should update it with the retour d'experience; but this gives an idea upon what is practically feasible. The underlying reasoning is as follows: - Types are 'documented' in typed languages because they are required (e.g.: not specifying a type in Java, C++ or Eiffel give a syntax error) - Type documentation is not required in Python. Astonishingly enough, this is to be considered by 99,9% of the python programming population "Thou shallt not document argument and return types". - There is maybe an intermediate position stating "documenting types is part of the python source documentation", and for some, including this constraint in quality assurance procedures. The attached documents are derived from this; it is an attempt at defining a standardized framework for programmers for documenting the types at a 'least cost' (The threat being: If you don't respect that, you'll be sentenced to 1 year in Java :)) Frederic Giacometti Disclaimer: I am the original author of the documents, and I am authorizing whoever to do whatever with them, without my responsability being engaged in any way. > > > ;) > > -Michel > > On Tue, 29 May 2001, Michel Pelletier wrote: > > > > > Folks, > > > > I'm almost ready to distribute my PEP for wider discussion in the Python > > community; > > > > http://www.zope.org/Members/michel/InterfacesPEP/PEP.txt > > > > , > > > > > > > > _______________________________________________ > Types-SIG mailing list > Types-SIG(a)python.org > http://mail.python.org/mailman/listinfo/types-sig ## standard documentation templates ## module template """ Public: - : -- """ ##function template def (): """ Arguments: - : -- Return: - -- Effect: """ ##class template class : """ Attributes: - : -- Class Attributes: - : -- Usage: """ ##method template def ( self, ): """ Private -- Arguments: - : -- Return: - -- Effect: """

4 8

Most recent documentation update
by Fred L. Drake, Jr. May 30, 2001

May 30, 2001

One thing I forgot to mention in my announcement of the update to the development documnetation which I just posted is that I went ahead and converted all but one of the productions in the Reference Manual to the new markup. The print_stmt production, unfortunately, is given twice instead of using a single model for the statement. The formatting tools don't support that (yet), and it's not clear that they should. (No, Barry, don't go changing it...!) -Fred -- Fred L. Drake, Jr. <fdrake at acm.org> PythonLabs at Digital Creations

2 1

[development doc updates]
by fdrake＠cj42289-a.reston1.va.home.com May 30, 2001

May 30, 2001

The development version of the documentation has been updated: http://python.sourceforge.net/devel-docs/ Update for development version of Python (2.2). This update substantially re-works the prototype support for productions of a formal grammar. They look better, support forward references to symbol definitions, and allow download of an all-text version of the complete grammar (with productions ordered the same way as they are in the documentation sources). "Documeting Python" now includes documentation for the LaTeX markup used to describe productions: http://python.sourceforge.net/devel-docs/doc/grammar-displays.html

1 0

[development doc updates]
by fdrake＠cj42289-a.reston1.va.home.com May 30, 2001

May 30, 2001

The development version of the documentation has been updated: http://python.sourceforge.net/devel-docs/ Incremental update for development version of Python (2.2). Mostly small updates, but I've worked on new markup for grammar productions used in the Reference Manual. Currently, only the lexical productions in Chapter 2 of the manual have been converted to the new markup and layout. Please take a look and send comments to doc-sig(a)python.org; the first page containing these changes is at: http://python.sourceforge.net/devel-docs/ref/identifiers.html The changes needed to implement the markup have not been checked in yet, and there are some bugs in the implementation (both for HTML and PDF), but this should make the productions easier to navigate. I've tested the HTML version on Linux only with Mozilla 0.9, Opera 5.0b8, and Netscape Navigator 4.77. Navigator is definately lagging behind in CSS support! Also added Michel Pelletier's documentation for the HTMLParser module, with some small changes.

3 2

RE: [Doc-SIG] RE: Python 2.0 quick reference...
by Simon Brunning May 25, 2001

May 25, 2001

> From: Fred L. Drake, Jr. [SMTP:fdrake@acm.org] > Simon Brunning writes: > > The new version of the Python Quick Reference is at > > <http://www.brunningonline.net/simon/python/PQR.html>. It occurs to me > that > > members of this list would be best placed to advise me as to future > > directions... > > I'm not sure what you mean by "future directions" -- changes in > organization? content? Changes in *format*. Hand coded HTML is liable to get messy, especially when passed from hand to hand. The Quick Reference as it stands is a perfect example of this! I'm looking for a better format to keep the master version of the quick reference in. > I agree that moving the styling into CSS is a laudable goal, but I > don't think that means getting rid of PRE sections (assuming those are > code examples or interactive sessions). I don't have a problem with the <pre> sections used for code examples and so on. But the tag is used extensively as a way of presenting *tabular* data. 'Real' tables using the <table> tag are *much* easier to work with programmatically. > The Python docs are in LaTeX using fairly extensive custom markup. > I don't expect that would be appropriate for the QuickRef, but perhaps > if you wrote it using the "howto" document class and formatted it to > use a single HTML page. You'd also get PostScript and PDF formatting > for free that way. Information on the LaTeX markup for Python > documentation is available at: > > http://www.python.org/doc/current/doc/doc.html Doh! <Smites head> Thanks, Fred, for being too kind to tell me to RTFM. But that's what I'll do! Cheers, Simon Brunning TriSystems Ltd. sbrunning(a)trisystems.co.uk ----------------------------------------------------------------------- The information in this email is confidential and may be legally privileged. It is intended solely for the addressee. Access to this email by anyone else is unauthorised. If you are not the intended recipient, any disclosure, copying, distribution, or any action taken or omitted to be taken in reliance on it, is prohibited and may be unlawful. TriSystems Ltd. cannot accept liability for statements made which are clearly the senders own.

2 1

RE: Python 2.0 quick reference...
by Simon Brunning May 25, 2001

May 25, 2001

The new version of the Python Quick Reference is at <http://www.brunningonline.net/simon/python/PQR.html>. It occurs to me that members of this list would be best placed to advise me as to future directions... > From: Simon Brunning [SMTP:SBrunning@trisystems.co.uk] > > From: Robin Becker [SMTP:robin@jessikat.fsnet.co.uk] > > I just got the version with dark magenta change lines and rather regret > > the colour/format changes since the initial release. In particular my > > default visited link colour is darkmagenta and I think darkmagenta on > > the steelblue looks less than obvious. > > Whatever colours I pick, *someone* is going to hate them. I'm just sorry > that it's you, Robin! > > I'm not going to make any further changes to the 2.0 version, but I'm > planning to extensively revamp the whole document for the 2.1 version. At > very least, I'm going to get rid of nearly every <pre> tag, and to > externalise the formatting into a css. That would allow people download > the > document and to muck about with the format to their heart's content. > > But I'm actually thinking of going one step further, and keeping the > master > document in XML format (possibly using DocBook?) and transforming to HTML > as > required. And indeed into PDF using your own wonderful ReportLab tool. > > But I don't know *anything* about this stuff - I've just bought 'XML in a > Nutshell', so we'll see how I get on. But if anyone has any advice, don't > be > shy! Any suggestions? In what format are the master versions of the Python Documentation? Any good tools knocking around? Cheers, Simon Brunning TriSystems Ltd. sbrunning(a)trisystems.co.uk ----------------------------------------------------------------------- The information in this email is confidential and may be legally privileged. It is intended solely for the addressee. Access to this email by anyone else is unauthorised. If you are not the intended recipient, any disclosure, copying, distribution, or any action taken or omitted to be taken in reliance on it, is prohibited and may be unlawful. TriSystems Ltd. cannot accept liability for statements made which are clearly the senders own.

2 1

(no subject)
by chethan kumar May 23, 2001

May 23, 2001

2 1

[development doc updates]
by fdrake＠cj42289-a.reston1.va.home.com May 21, 2001

May 21, 2001

The development version of the documentation has been updated: http://python.sourceforge.net/devel-docs/ Incremental updates to the Python 2.2 documentation.

1 0

[development doc updates]
by fdrake＠cj42289-a.reston1.va.home.com May 10, 2001

May 10, 2001

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

1 0