Guido van Rossum wrote: > On 1/21/06, Terry Reedy <[EMAIL PROTECTED]> wrote: >> On this page, 8 of 30 entries have a 'new in' comment. For anyone with no >> interest in the past, these constitute noise. I wonder if for 3.0, the >> timer can be reset and the docs start clean again. To keep them backwards >> compatible, they would also have to be littered with 'changed in 3.0' and >> 'deleted in 3.0' entries. Better, I think, to refer people to the last 2.x >> docs and a separate 2.x/3.0 changes doc. > > (That has nothing to do with Fredrik's efforts of course -- he's just > faithfully copying the annotations from the existing docs.) > > If Python 3.0 is indeed the major incompatible release that we > currently expect it will be, I agree that "new in 3.0" and "new in > 2.x" annotations make little sense, since so much will be "new in 3.0" > (or "deleted in 3.0"). It's probably better to have a separate > document explaining the differences between 2.x and 3.0. > > For the 2.x line, however (and again post-3.0) I think the "new in X" > annotations are important -- lots of people have to deal with > different Python versions, and it's a lot easier to depend on "new in > X" notations than to manually compare two or more versions of the > docs. (Although you still need to do thorough testing -- like the rest > of the docs, these annotations can't be 100% perfect.) > > As far as noise goes, "new in X" is minor compared to all the stuff > that's documented that the average user never needs... :-)
And, of course, the "new in 2.x" could be formatted less space-consuming, perhaps to the right of the method name. Georg _______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
