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: Clarify some things in porting HOWTO
Type: Stage:
Components: Documentation Versions: Python 3.4
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: brett.cannon Nosy List: brett.cannon, mitya57, python-dev, rbp
Priority: normal Keywords: patch

Created on 2014-01-09 17:10 by brett.cannon, last changed 2022-04-11 14:57 by admin. This issue is now closed.

Files
File name Uploaded Description Edit
pyporting.patch rbp, 2014-01-10 13:55 review
Messages (5)
msg207756 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2014-01-09 17:10
Reported on my G+ share of the latest reworking:

"""
The only part I found confusing is when you first introduce "from _future_ import unicode_literals" --- it looks like you forgot to explain what it does. It turns out that you explain it somewhat two paragraphs below it, so maybe you can just move this down a bit?

Maybe "bytes literals" section should be called "Bytes and unicode literals" or something and move the "unicode_literals" line in there.
"""

"""
The only issue I noticed is that "Eliminate -3 Warnings" section still mentions 2to3 before it's even introduced.
"""
msg207861 - (view) Author: Rodrigo Bernardo Pimentel (rbp) (Python committer) Date: 2014-01-10 13:55
I've created a patch that addresses the first criticism (explaining unicode_literals), as well as the first mention of print_function. It also addresses a small concern regarding "map", which I've mentioned in my G+ comment:

"""
Also, a friend was confused by http://docs.python.org/dev/howto/pyporting.html#update-map-for-imbalanced-input-sequences , until I understood that he didn't know map can take several sequences. I assume a lot of less experienced Python programmers only use map with a single sequence, and might be confused as well. A sentence mentioning that might help.
"""

I see that the current version of the doc on hg already addresses the 2to3 mention.
msg207862 - (view) Author: Rodrigo Bernardo Pimentel (rbp) (Python committer) Date: 2014-01-10 13:57
BTW, there remains another concern I mentioned on G+:

"""
A note on formatting: I found some of 4th- and 5th-level headings too subtle. For instance, http://docs.python.org/dev/howto/pyporting.html#from-future-import-absolute-import got me thinking for a second if it was part of the previous paragraph or a new heading. Maybe underlining, or a bullet-like marker, or some indentation could help there.
"""

But I don't know enough of the formatting standards, so I haven't addressed this in the patch.
msg207869 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2014-01-10 15:34
There's actually no way to tweak that formatting as that is all done by Sphinx automatically.
msg208344 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-01-17 16:45
New changeset 863b8e71cfee by Brett Cannon in branch 'default':
Issue #20208: Clarify some things in the Python porting HOWTO.
http://hg.python.org/cpython/rev/863b8e71cfee
History
Date User Action Args
2022-04-11 14:57:56adminsetgithub: 64407
2014-01-17 16:45:49brett.cannonsetstatus: open -> closed
resolution: fixed
2014-01-17 16:45:10python-devsetnosy: + python-dev
messages: + msg208344
2014-01-10 15:34:43brett.cannonsetmessages: + msg207869
2014-01-10 13:57:32rbpsetmessages: + msg207862
2014-01-10 13:55:24rbpsetfiles: + pyporting.patch

nosy: + rbp
messages: + msg207861

keywords: + patch
2014-01-09 17:14:56mitya57setnosy: + mitya57
2014-01-09 17:10:37brett.cannoncreate