The 3.0a4 docs have various obsolete references to 2.x not yet removed. I found these and other items by searching for '2.' in each section Lexical Analysis: Identifiers and Keywords Please specify the legal ascii chars rather than referring back to the 2.5 doc! I would delete the second sentence and add the reference to PEP3131 to the end of the third. As it is, 'additional characters' and 'other characters' seem like possibly two different sets. Data Model: instance methods: 'changed in 2.6' delete Data Model: New Style and Classic Classes Probably this whole section should go. I hope that the last sentence is no longer true ;-) Data Model: footnote 1 (which I believe came from above): delete Simple Statements: Raise: several changes suggested. The grammar is wrong. There is only one optional expression. PEP3131 does not mention .with_traceback. It should if people are referred to it. But I would leave out the note and reference. PEP3131 is irrelevant to anyone just learning Py3 and not useful to non-expert Py2 users. Anyway, those who need it will find the reference in What's New. The .with_traceback method has no doc string. I presume it should say "Sets the __traceback__ attribute and returns self." The manual should also mention that the method returns the exception instance (self) Suggestion: "method (which returns the exception instance), like so:" (There stuff in parens is suggested addition.) I think this is worth mentioning because mutators, including setters, typically do *not* return 'self'. Compound statements: Try Given my opinion that 3.0 documents (other that What's New and other explicit transition docs) should stand on their own, I would also remove the reference to PEP3110. But at least it applies to most users. But again, I am not sure it adds very much. The What's New/Exception Stuff entry for PEP3110 could usefully add "You must now use except SomeException as identifier: instead of except Exception,identifier" in parallel to the note for 3109 above it (including the shading of code). Compound statements: With: remove last two sentences The Library Reference needs similar treatment. There are several "2." references just in Built-in Functions.
Thanks again for your work on the docs. If you would sometime prefer to receive a similar batch of comments but in a perhaps more useful form (ie, changes and comments in-line) let me know. I am thinking of any of the following: 1) doc on the Guido's new code tracker (via null patch) 2) doc embedded in an OO .odf (or Word .doc) so as to use RecordChanges feature 3) .rst (?) with changes and <embedded, to be removed, comment and questions> that you can run a diff against. Terry Georg Brandl <georg@python.org> added the comment: Thanks, this is very useful to me. I'll work through it soon. __________________________________ Tracker <report@bugs.python.org> <http://bugs.python.org/issue2762> __________________________________
Thanks very much, Terry! I've done almost all your suggestions in r62742, and added a docstring to with_traceback in r62741. For future issues, please feel free to choose either method 1 or 3 (I think 3 may be the simplest for you.)
History
Date
User
Action
Args
2022-04-11 14:56:34
admin
set
github: 47011
2008-05-05 21:45:14
georg.brandl
set
status: open -> closedresolution: acceptedmessages: +
