| msg167279 - (view) |
Author: Chris Jerdonek (chris.jerdonek) *  |
Date: 2012-08-03 00:20 |
| "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. |
|
|
| msg167294 - (view) |
Author: Serhiy Storchaka (serhiy.storchaka) * |
Date: 2012-08-03 07:42 |
| See . |
|
|
| msg167298 - (view) |
Author: Chris Jerdonek (chris.jerdonek) * |
Date: 2012-08-03 08:33 |
| 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 |
|
|
| msg167376 - (view) |
Author: Chris Jerdonek (chris.jerdonek) * |
Date: 2012-08-03 23:10 |
| See also: f17a1410ebe5 |
|
|
| msg167377 - (view) |
Author: Antoine Pitrou (pitrou) * |
Date: 2012-08-03 23:12 |
| > 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. |
|
|
| msg167380 - (view) |
Author: Chris Jerdonek (chris.jerdonek) * |
Date: 2012-08-03 23:33 |
| > 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. |
|
|
| msg167390 - (view) |
Author: Antoine Pitrou (pitrou) * |
Date: 2012-08-04 00:44 |
| > 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. 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. |
|
|
| msg167393 - (view) |
Author: Chris Jerdonek (chris.jerdonek) * |
Date: 2012-08-04 02:21 |
| > 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()). |
|
|
| msg167534 - (view) |
Author: Chris Jerdonek (chris.jerdonek) * |
Date: 2012-08-06 03:44 |
| Attaching a patch for review. |
|
|
| msg167592 - (view) |
Author: Chris Jerdonek (chris.jerdonek) * |
Date: 2012-08-07 00:43 |
| Updating patch to current tip. |
|
|
| msg168162 - (view) |
Author: Chris Jerdonek (chris.jerdonek) * |
Date: 2012-08-14 01:02 |
| Updating patch to latest again. |
|
|
| msg168165 - (view) |
Author: R. David Murray (r.david.murray) * |
Date: 2012-08-14 02:02 |
| Thanks for working on this. I see nothing wrong with using 'universal newlines mode' as the term, which would simplify the markup. |
|
|
| msg168168 - (view) |
Author: Chris Jerdonek (chris.jerdonek) * |
Date: 2012-08-14 02:42 |
| 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. |
|
|
| msg168169 - (view) |
Author: Chris Jerdonek (chris.jerdonek) * |
Date: 2012-08-14 03:11 |
| 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. |
|
|
| msg168171 - (view) |
Author: Chris Jerdonek (chris.jerdonek) * |
Date: 2012-08-14 03:41 |
| Here is a new patch with David's suggested change (just for doc files though). |
|
|
| msg168187 - (view) |
Author: Chris Jerdonek (chris.jerdonek) * |
Date: 2012-08-14 10:00 |
| Updating patch to tip again. |
|
|
| msg168248 - (view) |
Author: R. David Murray (r.david.murray) * |
Date: 2012-08-15 01:01 |
| 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. |
|
|
| msg168250 - (view) |
Author: Chris Jerdonek (chris.jerdonek) * |
Date: 2012-08-15 01:09 |
| 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! |
|
|
| msg168290 - (view) |
Author: Chris Jerdonek (chris.jerdonek) * |
Date: 2012-08-15 13:02 |
| Here is the patch for 2.7. |
|
|
| msg168296 - (view) |
Author: Chris Jerdonek (chris.jerdonek) * |
Date: 2012-08-15 14:08 |
| 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. |
|
|
| msg168308 - (view) |
Author: Roundup Robot (python-dev)  |
Date: 2012-08-15 15:23 |
| 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 |
|
|
| msg168309 - (view) |
Author: R. David Murray (r.david.murray) * |
Date: 2012-08-15 15:25 |
| Thanks Chris. |
|
|
| msg168310 - (view) |
Author: Andrew Svetlov (asvetlov) * |
Date: 2012-08-15 15:30 |
| Good work. |
|
|
| msg168311 - (view) |
Author: Chris Jerdonek (chris.jerdonek) * |
Date: 2012-08-15 15:30 |
| 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 |
|
|
| msg168312 - (view) |
Author: Andrew Svetlov (asvetlov) * |
Date: 2012-08-15 15:33 |
| Yes, it is processed correctly. |
|
|
| msg168342 - (view) |
Author: Éric Araujo (eric.araujo) * |
Date: 2012-08-15 22:48 |
| Great patch! |
|
|