[issue15543] central documentation for 'universal newlines'
New submission from Chris Jerdonek: "Universal newlines" of PEP 278 does not seem to have a central, linkable description within the documentation. In particular, there does not seem to be a glossary entry or any index entries for it. The main documentation seems to be in the middle of the documentation for the open() built-in function: http://docs.python.org/dev/library/functions.html?highlight=open#open But this does not feature prominently when searching for universal newlines in the "Quick Search". This would allow us, for example, to reference and link to an explanation of universal newlines in the documentation for str.splitlines(): http://docs.python.org/dev/library/stdtypes.html#str.splitlines I would be happy to provide a patch. ---------- assignee: docs@python components: Documentation keywords: easy messages: 167279 nosy: cjerdonek, docs@python priority: normal severity: normal status: open title: central documentation for 'universal newlines' versions: Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
Serhiy Storchaka added the comment: See issue15204. ---------- nosy: +storchaka _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
Chris Jerdonek added the comment: Since universal newline mode is discouraged and getting deprecated in the built-in open() function, the "central" place for describing universal newlines should probably not be the documentation for the open() method. I am leaning towards a glossary entry. The io.TextIOWrapper class is another candidate: http://docs.python.org/dev/library/io.html#io.TextIOWrapper ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
Chris Jerdonek added the comment: See also: f17a1410ebe5 ---------- nosy: +pitrou _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
Antoine Pitrou added the comment:
Since universal newline mode is discouraged and getting deprecated in the built-in open() function
There may (or may not :-)) be a misunderstanding. Universal newlines are not discouraged; it's the legacy "U" flag which is deprecated. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
Chris Jerdonek added the comment:
There may (or may not :-)) be a misunderstanding. Universal newlines are not discouraged; it's the legacy "U" flag which is deprecated.
Already understood. :) (I said "in the built-in open() function" above and meant "mode" as in "flag".) I nosied you only because you copy and pasted information about universal newlines that might benefit from a glossary entry or some such about universal newlines. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
Antoine Pitrou added the comment:
Yes, it might benefit from a glossary entry. On the other hand, the details of the *newline* argument should probably remain in the API descriptions themselves. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
Chris Jerdonek added the comment:
On the other hand, the details of the *newline* argument should probably remain in the API descriptions themselves.
Correct. It would be a high-level entry for "universal newlines" -- independent of any API and suitable for linking to wherever universal newlines are mentioned (e.g. in the documentation of str.splitlines()). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
Chris Jerdonek added the comment: Attaching a patch for review. ---------- keywords: +patch stage: -> patch review Added file: http://bugs.python.org/file26706/issue-15543-1.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
Chris Jerdonek added the comment: Updating patch to current tip. ---------- Added file: http://bugs.python.org/file26714/issue-15543-2.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
Chris Jerdonek added the comment: Updating patch to latest again. ---------- nosy: +asvetlov Added file: http://bugs.python.org/file26792/issue-15543-3.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
R. David Murray added the comment: Thanks for working on this. I see nothing wrong with using 'universal newlines mode' as the term, which would simplify the markup. ---------- nosy: +r.david.murray _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
Chris Jerdonek added the comment: Sure, you're welcome. And sounds good, I'll change it. The singular was the prevailing form, but you're right that there is no reason we can't change it. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
Chris Jerdonek added the comment: Is it worth standardizing on "universal newlines mode" in the code as well (docstrings, etc)? There are about ten occurrences of "universal newline mode" that would need to be changed. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
Chris Jerdonek added the comment: Here is a new patch with David's suggested change (just for doc files though). ---------- Added file: http://bugs.python.org/file26796/issue-15543-4.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
Chris Jerdonek added the comment: Updating patch to tip again. ---------- Added file: http://bugs.python.org/file26799/issue-15543-5.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
R. David Murray added the comment: Yeah, we might as well be consistent, though it's not a big deal either way. I'd prefer that as a separate patch. Any interest in backporting this to 2.7? Being so close to final release on 3.2 I think we can skip 3.2, unless you feel like doing it. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
Chris Jerdonek added the comment: Sure, I'd be happy to do both 2.7 and 3.2. I can upload the patch for the default branch as a delta to apply after the 3.2 change has been forward-ported from 3.2 to default. Thanks for taking an interest in this! ---------- versions: +Python 2.7, Python 3.2 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
Chris Jerdonek added the comment: Here is the patch for 2.7. ---------- Added file: http://bugs.python.org/file26822/issue-15543-6-py27.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
Changes by Chris Jerdonek <chris.jerdonek@gmail.com>: Added file: http://bugs.python.org/file26826/issue-15543-6-py32.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
Chris Jerdonek added the comment: And here are the 3.2 patch and the 3.3 "delta" after forward-porting. Note that to forward-port the 3.2 patch to the default 3.3 branch, you can simply drop the changes to the file Doc/library/bz2.rst. I think that is the only conflict. ---------- Added file: http://bugs.python.org/file26827/issue-15543-6-py33-delta.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
Roundup Robot added the comment: New changeset 273df9789796 by R David Murray in branch '3.2': #15543: glossary entry for and 'universal newlines', and links to it. http://hg.python.org/cpython/rev/273df9789796 New changeset e67042b6ad02 by R David Murray in branch '3.2': #15543: reflow paragraphs. http://hg.python.org/cpython/rev/e67042b6ad02 New changeset 04a0255de9b8 by R David Murray in branch 'default': Merge #15543: glossary entry for and 'universal newlines', and links to it. http://hg.python.org/cpython/rev/04a0255de9b8 New changeset 37df50bc4ea0 by R David Murray in branch 'default': #15543: additional link in subprocess docs. http://hg.python.org/cpython/rev/37df50bc4ea0 New changeset a2efe5eeb876 by R David Murray in branch 'default': #15543: reflow paragraph. http://hg.python.org/cpython/rev/a2efe5eeb876 New changeset 8795cd3b4c8c by R David Murray in branch '2.7': #15543: glossary entry for and 'universal newlines', and links to it. http://hg.python.org/cpython/rev/8795cd3b4c8c New changeset 35d8a638b0e2 by R David Murray in branch '2.7': #15543: reflow paragraphs. http://hg.python.org/cpython/rev/35d8a638b0e2 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
R. David Murray added the comment: Thanks Chris. ---------- resolution: -> fixed stage: patch review -> committed/rejected status: open -> closed type: -> enhancement _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
Andrew Svetlov added the comment: Good work. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
Chris Jerdonek added the comment: Thanks, David! Also, can/did you check that reflows like these still link to the glossary correctly? + :func:`input` function to allow opening files in binary or :term:`universal + newlines` mode. Another new parameter, *openhook*, lets you use a function I tried to avoid breaking role markups like these to be safe ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
Andrew Svetlov added the comment: Yes, it is processed correctly. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
Éric Araujo added the comment: Great patch! ---------- nosy: +eric.araujo _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
Serhiy Storchaka added the comment: See issue15204. ---------- nosy: +storchaka _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
Chris Jerdonek added the comment: Since universal newline mode is discouraged and getting deprecated in the built-in open() function, the "central" place for describing universal newlines should probably not be the documentation for the open() method. I am leaning towards a glossary entry. The io.TextIOWrapper class is another candidate: http://docs.python.org/dev/library/io.html#io.TextIOWrapper ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
Chris Jerdonek added the comment: See also: f17a1410ebe5 ---------- nosy: +pitrou _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
Antoine Pitrou added the comment:
Since universal newline mode is discouraged and getting deprecated in the built-in open() function
There may (or may not :-)) be a misunderstanding. Universal newlines are not discouraged; it's the legacy "U" flag which is deprecated. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
Chris Jerdonek added the comment:
There may (or may not :-)) be a misunderstanding. Universal newlines are not discouraged; it's the legacy "U" flag which is deprecated.
Already understood. :) (I said "in the built-in open() function" above and meant "mode" as in "flag".) I nosied you only because you copy and pasted information about universal newlines that might benefit from a glossary entry or some such about universal newlines. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
Antoine Pitrou added the comment:
Yes, it might benefit from a glossary entry. On the other hand, the details of the *newline* argument should probably remain in the API descriptions themselves. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
Chris Jerdonek added the comment:
On the other hand, the details of the *newline* argument should probably remain in the API descriptions themselves.
Correct. It would be a high-level entry for "universal newlines" -- independent of any API and suitable for linking to wherever universal newlines are mentioned (e.g. in the documentation of str.splitlines()). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
Chris Jerdonek added the comment: Attaching a patch for review. ---------- keywords: +patch stage: -> patch review Added file: http://bugs.python.org/file26706/issue-15543-1.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
Chris Jerdonek added the comment: Updating patch to current tip. ---------- Added file: http://bugs.python.org/file26714/issue-15543-2.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
Chris Jerdonek added the comment: Updating patch to latest again. ---------- nosy: +asvetlov Added file: http://bugs.python.org/file26792/issue-15543-3.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
R. David Murray added the comment: Thanks for working on this. I see nothing wrong with using 'universal newlines mode' as the term, which would simplify the markup. ---------- nosy: +r.david.murray _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
Chris Jerdonek added the comment: Sure, you're welcome. And sounds good, I'll change it. The singular was the prevailing form, but you're right that there is no reason we can't change it. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
Chris Jerdonek added the comment: Is it worth standardizing on "universal newlines mode" in the code as well (docstrings, etc)? There are about ten occurrences of "universal newline mode" that would need to be changed. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
Chris Jerdonek added the comment: Here is a new patch with David's suggested change (just for doc files though). ---------- Added file: http://bugs.python.org/file26796/issue-15543-4.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
Chris Jerdonek added the comment: Updating patch to tip again. ---------- Added file: http://bugs.python.org/file26799/issue-15543-5.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
R. David Murray added the comment: Yeah, we might as well be consistent, though it's not a big deal either way. I'd prefer that as a separate patch. Any interest in backporting this to 2.7? Being so close to final release on 3.2 I think we can skip 3.2, unless you feel like doing it. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
Chris Jerdonek added the comment: Sure, I'd be happy to do both 2.7 and 3.2. I can upload the patch for the default branch as a delta to apply after the 3.2 change has been forward-ported from 3.2 to default. Thanks for taking an interest in this! ---------- versions: +Python 2.7, Python 3.2 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
Chris Jerdonek added the comment: Here is the patch for 2.7. ---------- Added file: http://bugs.python.org/file26822/issue-15543-6-py27.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
Changes by Chris Jerdonek <chris.jerdonek@gmail.com>: Added file: http://bugs.python.org/file26826/issue-15543-6-py32.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
Chris Jerdonek added the comment: And here are the 3.2 patch and the 3.3 "delta" after forward-porting. Note that to forward-port the 3.2 patch to the default 3.3 branch, you can simply drop the changes to the file Doc/library/bz2.rst. I think that is the only conflict. ---------- Added file: http://bugs.python.org/file26827/issue-15543-6-py33-delta.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
Roundup Robot added the comment: New changeset 273df9789796 by R David Murray in branch '3.2': #15543: glossary entry for and 'universal newlines', and links to it. http://hg.python.org/cpython/rev/273df9789796 New changeset e67042b6ad02 by R David Murray in branch '3.2': #15543: reflow paragraphs. http://hg.python.org/cpython/rev/e67042b6ad02 New changeset 04a0255de9b8 by R David Murray in branch 'default': Merge #15543: glossary entry for and 'universal newlines', and links to it. http://hg.python.org/cpython/rev/04a0255de9b8 New changeset 37df50bc4ea0 by R David Murray in branch 'default': #15543: additional link in subprocess docs. http://hg.python.org/cpython/rev/37df50bc4ea0 New changeset a2efe5eeb876 by R David Murray in branch 'default': #15543: reflow paragraph. http://hg.python.org/cpython/rev/a2efe5eeb876 New changeset 8795cd3b4c8c by R David Murray in branch '2.7': #15543: glossary entry for and 'universal newlines', and links to it. http://hg.python.org/cpython/rev/8795cd3b4c8c New changeset 35d8a638b0e2 by R David Murray in branch '2.7': #15543: reflow paragraphs. http://hg.python.org/cpython/rev/35d8a638b0e2 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
R. David Murray added the comment: Thanks Chris. ---------- resolution: -> fixed stage: patch review -> committed/rejected status: open -> closed type: -> enhancement _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
Andrew Svetlov added the comment: Good work. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
Chris Jerdonek added the comment: Thanks, David! Also, can/did you check that reflows like these still link to the glossary correctly? + :func:`input` function to allow opening files in binary or :term:`universal + newlines` mode. Another new parameter, *openhook*, lets you use a function I tried to avoid breaking role markups like these to be safe ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
Andrew Svetlov added the comment: Yes, it is processed correctly. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
Éric Araujo added the comment: Great patch! ---------- nosy: +eric.araujo _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15543> _______________________________________
participants (7)
-
Andrew Svetlov -
Antoine Pitrou
-
Chris Jerdonek
-
R. David Murray
-
Roundup Robot
-
Serhiy Storchaka
-
Éric Araujo