This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Confusing section title "New Expected Features for Python Implementations" in 3.4 What's New doc
Type: Stage: resolved
Components: Documentation Versions: Python 3.4
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, larry, ncoghlan, ned.deily, python-dev, r.david.murray
Priority: normal Keywords: patch

Created on 2014-03-15 02:04 by ned.deily, last changed 2022-04-11 14:58 by admin. This issue is now closed.

Files
File name Uploaded Description Edit
larry.remove.other.instance.of.clumsy.wording.1.diff larry, 2014-03-16 03:12 review
Messages (10)
msg213617 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2014-03-15 02:04
The 3.4 What's New document has a section entitled "New expected features for Python implementations", a title not found in previous releases.  I believe that the intention is to document features expected to be implemented by all Python implementations, including non CPython ones, when they claim to support 3.4.  However, I think the wording is likely to be misunderstood by most readers as meaning "features expected to be in the 3.4 release (including CPython)", leaving a question in their minds as to whether all of the described features are actually in the 3.4 release.  On the other hand, AFAIK, the standard documentation set has never attempted to document all of the deviations from CPython for each particular non-CPython implementation; if the wording is understood as intended, it could be construed as implying something that isn't true.  So, under either reading, the wording can be misleading.  I think it should just be removed or reworded as "New Features".

http://docs.python.org/3.4/whatsnew/3.4.html#summary-release-highlights
http://docs.python.org/3.4/whatsnew/3.4.html#new-expected-features-for-python-implementations
msg213639 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2014-03-15 05:28
The idea was to add a category for core interpreter behavioural changes
that aren't language or standard library changes. Inspiration just failed
me completely when coming up with a title for it, hence the current
monstrosity.

Something generic like "Changes to interpreter behaviour" might work.
msg213665 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-03-15 16:38
How about "Interpreter Improvements"?  The marshall format change isn't exactly a behavior change, but other implementations will need to be able to cope with it.  Or should that be moved to Library changes?
msg213669 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2014-03-15 18:05
I think "New Features" works better.
msg213700 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2014-03-16 02:11
Rereading that section (it has currently been adjusted to say "New Features"), I suggest:

- consistently using sentence case for those list headings
- tweaking that particular heading to say "Other new features:" (to contrast with the "New syntax features:" heading just above)
- losing the scare quotes from 'pip should always be "available"' (being a distro package install away counts as available in my book)
msg213701 - (view) Author: Larry Hastings (larry) * (Python committer) Date: 2014-03-16 02:51
RDM's checkin ( 21ecc3d52806 ) renamed the subheading of "Summary -- Release Highlights" from "New Expected Features for Python Implementations" to "New features".  But there's still a major heading with that title.  Surely we want to rename that one too?
msg213702 - (view) Author: Larry Hastings (larry) * (Python committer) Date: 2014-03-16 03:12
I propose to check this in.
msg213703 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2014-03-16 03:14
LGTM
msg213704 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-03-16 03:16
New changeset 3488a9fbe09e by Larry Hastings in branch 'default':
Issue #20931: Fix other confusingly-worded heading.
http://hg.python.org/cpython/rev/3488a9fbe09e
msg213705 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-03-16 03:31
New changeset 7e78e602ec73 by R David Murray in branch 'default':
whatsnew: Fix Features section title, use title/sentence case consistently.
http://hg.python.org/cpython/rev/7e78e602ec73
History
Date User Action Args
2022-04-11 14:58:00adminsetgithub: 65130
2014-03-16 03:31:25python-devsetstatus: open -> closed
resolution: fixed
messages: + msg213705

stage: resolved
2014-03-16 03:16:00python-devsetnosy: + python-dev
messages: + msg213704
2014-03-16 03:14:23ned.deilysetmessages: + msg213703
2014-03-16 03:12:27larrysetfiles: + larry.remove.other.instance.of.clumsy.wording.1.diff
keywords: + patch
messages: + msg213702
2014-03-16 02:51:43larrysetmessages: + msg213701
2014-03-16 02:11:34ncoghlansetmessages: + msg213700
2014-03-15 18:05:49ned.deilysetmessages: + msg213669
2014-03-15 16:38:54r.david.murraysetmessages: + msg213665
2014-03-15 08:14:26ned.deilysetnosy: + r.david.murray
2014-03-15 05:28:15ncoghlansetmessages: + msg213639
2014-03-15 02:04:35ned.deilycreate