"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.

See issue15204.

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

See also: f17a1410ebe5

> 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.

> 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.

> 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.

> 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()).

Attaching a patch for review.

Updating patch to current tip.

Updating patch to latest again.

Thanks for working on this.

I see nothing wrong with using 'universal newlines mode' as the term, which would simplify the markup.

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.

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.

Here is a new patch with David's suggested change (just for doc files though).

Updating patch to tip again.

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.

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!

Here is the patch for 2.7.

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.

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

Thanks Chris.

Good work.

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

Yes, it is processed correctly.

Great patch!