New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Tutorial documentation contains undefined reference to #! #73567
Comments
After moving a certain chunk of the 'interpreter.rst' contents to 'appendix.rst' in bpo-16827 the reference to #! in the section '2.2.3. Source Code Encoding' is currently confusing for new readers. Attached patches reword the sentence to remove that reference for 3.4+ and 2.7. |
Mariatta, could you check this patch and tell us your recommendation about whether it should be applied, modified, or rejected? |
Hi, Raymond. Is Mariatta responsible for reviewing Documentation submissions? If so, should I nosy Mariatta in any future documentation issues? |
You wrote: "It is also possible to specify a different encoding for source files. In order to do this, you can use a special comment line that defines the source file encoding::". I think that is not true, because the line have to be the first line, or right below a comment (just one, as in the case of the shebang). For instance, in this case Python apply the declared coding: $ cat foo.py
# The first line is a comment
# -*- coding: ascii -*-
print('è') # Encoded in UTF-8
$ python foo.py
...
SyntaxError: encoding problem: ascii In this case it does not: $ cat foo.py
# The first line is a comment
# and also the sencond line
# -*- coding: ascii -*-
print('è') # Encoded in UTF-8
$ python foo.py
è But I think you are right that the current doc is confusing. Maybe yon can write something like this: "It is also possible to specify a different encoding for source files. In order to do this, put one special comment line to define the source file encoding: # -- coding: encoding -- This coding comment has to be the first line of the file, or the second line in case the first one is the #! line." |
Indeed, this does create an issue. The last sentence in the documentation actually specifies where the encoding comment can be but doesn't strictly specify it can be on the second line if and only if preceded by I'm thinking the last sentence should contain the additional change, that is, change it from :
to:
linking to (https://docs.python.org/3/tutorial/appendix.html#executable-python-scripts) accordingly. Let's see what Mariatta says about these proposals. Thanks for noticing. |
No, she is a new core developer and this is a good issue for her to do the initial review and post any thoughts on the subject. We've all got to start somewhere.
You did everything just right. Just marking this as a doc patch is sufficient. |
There are certain rules about the encoding declaration line. I've prepared a patch that addresses this. Please review, and let me know if you have additional feedback. Thanks :) |
Suggestions:
|
Thanks for the feedback, Raymond. I adjusted my patch. |
The patch LGTM. I think there is just one type (see review). By the way, looking at the PEP-0263, the sentence "To define a source code encoding, a magic comment must be placed into the source files either as first or second line in the file" actually is not true. Also because I did not see any point in the PEP that clarifies that the fist line has to be a comment. Maybe it could be deduced by the examples (all using the shebang), but maybe not, and the user could think this is a valid declaration: print('très jolie')
# -*- coding: ascii -*- If you think is worth to clarify, I open an issue with a patch for the PEP-0263. |
Added a comment too. Other than that and the comment by Marco it looks fine to me too. |
Thanks all for the feedback. I updated the patch. Marco, IMO it's not necessary to update the PEP. |
It looks like everyone is happy and the patch is ready for Mariatta to apply. The procedure is: Then return to this issue, verify the bot has posted the commit. Write a comment thanking the OP and reviewers. Then mark the status as "closed" and resolution as "fixed". |
I would only post this to 2.7, 3.6 and 3.7. Also, no Misc/NEWS entry is needed. |
New changeset 3d712292f2fa by Mariatta Wijaya in branch '3.6': |
New changeset 483d9133fd7e by Mariatta Wijaya in branch '3.6': New changeset 762a93935afd by Mariatta Wijaya in branch 'default': |
New changeset df356d3c916e by Mariatta Wijaya in branch '2.7': |
Thanks, Jim, Marco, and Raymond :) |
New changeset abfa17511f7ce8f1a6394f28f82ffb9a916fcf03 by Mariatta Wijaya in branch 'master': New changeset 848eeb1debc94a82660bf5af4e3d554b02b81c2e by Mariatta Wijaya in branch 'master': New changeset 35519d021ece942efc4a710ea3e94bcc5c06b130 by Mariatta Wijaya in branch 'master': |
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
bugs.python.org fields:
The text was updated successfully, but these errors were encountered: