#15543: glossary entry for and 'universal newlines', and links to it.

Patch by Chris Jerdonek.

diff --git a/Doc/glossary.rst b/Doc/glossary.rst
index bf1234db2d754e3f17862346944a0ff53768054c..7cd990528751c6490c6e76bec11405c1875571d2 100644 (file)
--- a/Doc/glossary.rst
+++ b/Doc/glossary.rst
@@ -600,6 +600,13 @@ Glossary
       object has a type.  An object's type is accessible as its
       :attr:`__class__` attribute or can be retrieved with ``type(obj)``.
 
+   universal newlines
+      A manner of interpreting text streams in which all of the following are
+      recognized as ending a line: the Unix end-of-line convention ``'\n'``,
+      the Windows convention ``'\r\n'``, and the old Macintosh convention
+      ``'\r'``.  See :pep:`278` and :pep:`3116`, as well as
+      :func:`str.splitlines` for an additional use.
+
    view
       The objects returned from :meth:`dict.keys`, :meth:`dict.values`, and
       :meth:`dict.items` are called dictionary views.  They are lazy sequences

diff --git a/Doc/library/bz2.rst b/Doc/library/bz2.rst
index d13f6e091003570816214e328ed513d130f52335..93144b6638e4126af51a44155e43dd69b1c7b04d 100644 (file)
--- a/Doc/library/bz2.rst
+++ b/Doc/library/bz2.rst
@@ -40,6 +40,9 @@ Here is a summary of the features offered by the bz2 module:
 Handling of compressed files is offered by the :class:`BZ2File` class.
 
 
+.. index::
+   single: universal newlines; bz2.BZ2File class
+
 .. class:: BZ2File(filename, mode='r', buffering=0, compresslevel=9)
 
    Open a bz2 file. Mode can be either ``'r'`` or ``'w'``, for reading (default)
@@ -48,7 +51,7 @@ Handling of compressed files is offered by the :class:`BZ2File` class.
    unbuffered, and larger numbers specify the buffer size; the default is
    ``0``. If *compresslevel* is given, it must be a number between ``1`` and
    ``9``; the default is ``9``. Add a ``'U'`` to mode to open the file for input
-   with universal newline support. Any line ending in the input file will be
+   in :term:`universal newlines` mode.  Any line ending in the input file will be
    seen as a ``'\n'`` in Python.  Also, a file so opened gains the attribute
    :attr:`newlines`; the value for this attribute is one of ``None`` (no newline
    read yet), ``'\r'``, ``'\n'``, ``'\r\n'`` or a tuple containing all the

diff --git a/Doc/library/csv.rst b/Doc/library/csv.rst
index edbe7263df5b67e2d29f45b4ced561fd2d7f5853..e84e218a37ea2099155dcc02168fe0ba0e58c440 100644 (file)
--- a/Doc/library/csv.rst
+++ b/Doc/library/csv.rst
@@ -46,6 +46,9 @@ Module Contents
 The :mod:`csv` module defines the following functions:
 
 
+.. index::
+   single: universal newlines; csv.reader function
+
 .. function:: reader(csvfile, dialect='excel', **fmtparams)
 
    Return a reader object which will iterate over lines in the given *csvfile*.
@@ -486,4 +489,5 @@ done::
 .. [1] If ``newline=''`` is not specified, newlines embedded inside quoted fields
    will not be interpreted correctly, and on platforms that use ``\r\n`` linendings
    on write an extra ``\r`` will be added.  It should always be safe to specify
-   ``newline=''``, since the csv module does its own (universal) newline handling.
+   ``newline=''``, since the csv module does its own
+   (:term:`universal <universal newlines>`) newline handling.

diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 3b94495df3d2add89133d96dc97f76cab67ef834..6b80bd9b4a963a812455c2b94438f0a57c1ac487 100644 (file)
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -819,7 +819,7 @@ are always available.  They are listed here in alphabetical order.
    ``'b'``   binary mode
    ``'t'``   text mode (default)
    ``'+'``   open a disk file for updating (reading and writing)
-   ``'U'``   universal newline mode (for backwards compatibility; should
+   ``'U'``   universal newlines mode (for backwards compatibility; should
              not be used in new code)
    ========= ===============================================================
 
@@ -874,14 +874,18 @@ are always available.  They are listed here in alphabetical order.
    used.  Any other error handling name that has been registered with
    :func:`codecs.register_error` is also valid.
 
-   *newline* controls how universal newlines works (it only applies to text
-   mode).  It can be ``None``, ``''``, ``'\n'``, ``'\r'``, and ``'\r\n'``.  It
+   .. index::
+      single: universal newlines; open() built-in function
+
+   *newline* controls how :term:`universal newlines` mode works (it only
+   applies to text mode).
+   It can be ``None``, ``''``, ``'\n'``, ``'\r'``, and ``'\r\n'``.  It
    works as follows:
 
    * When reading input from the stream, if *newline* is ``None``, universal
      newlines mode is enabled.  Lines in the input can end in ``'\n'``,
      ``'\r'``, or ``'\r\n'``, and these are translated into ``'\n'`` before
-     being returned to the caller.  If it is ``''``, universal newline mode is
+     being returned to the caller.  If it is ``''``, universal newlines mode is
      enabled, but line endings are returned to the caller untranslated.  If it
      has any of the other legal values, input lines are only terminated by the
      given string, and the line ending is returned to the caller untranslated.

diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst
index c9f742ad039097eeef3dd53a2f444b44019d68f2..158e7b443c186f45b10f84f6e04ef3dd1d9a47e9 100644 (file)
--- a/Doc/library/importlib.rst
+++ b/Doc/library/importlib.rst
@@ -189,10 +189,15 @@ are also provided to help in implementing the core ABCs.
         (e.g. built-in module).  :exc:`ImportError` is raised if loader cannot
         find the requested module.
 
+        .. index::
+           single: universal newlines; importlib.abc.InspectLoader.get_source method
+
     .. method:: get_source(fullname)
 
         An abstract method to return the source of a module. It is returned as
-        a text string with universal newlines. Returns ``None`` if no
+        a text string using :term:`universal newlines`, translating all
+        recognized line separators into ``'\n'`` characters.
+        Returns ``None`` if no
         source is available (e.g. a built-in module). Raises :exc:`ImportError`
         if the loader cannot find the module specified.
 

diff --git a/Doc/library/io.rst b/Doc/library/io.rst
index b302c641b8e34a22c85ce9878800a3bec4d50dba..8e6e601203cc7601fcf7abf3b23990bd6b46e4ed 100644 (file)
--- a/Doc/library/io.rst
+++ b/Doc/library/io.rst
@@ -757,13 +757,17 @@ Text I/O
    sequences) can be used.  Any other error handling name that has been
    registered with :func:`codecs.register_error` is also valid.
 
+   .. index::
+      single: universal newlines; io.TextIOWrapper class
+
    *newline* controls how line endings are handled.  It can be ``None``,
    ``''``, ``'\n'``, ``'\r'``, and ``'\r\n'``.  It works as follows:
 
-   * When reading input from the stream, if *newline* is ``None``, universal
-     newlines mode is enabled.  Lines in the input can end in ``'\n'``,
+   * When reading input from the stream, if *newline* is ``None``,
+     :term:`universal newlines` mode is enabled.  Lines in the input can end
+     in ``'\n'``,
      ``'\r'``, or ``'\r\n'``, and these are translated into ``'\n'`` before
-     being returned to the caller.  If it is ``''``, universal newline mode is
+     being returned to the caller.  If it is ``''``, universal newlines mode is
      enabled, but line endings are returned to the caller untranslated.  If it
      has any of the other legal values, input lines are only terminated by the
      given string, and the line ending is returned to the caller untranslated.
@@ -819,10 +823,13 @@ Text I/O
       output.close()
 
 
+.. index::
+   single: universal newlines; io.IncrementalNewlineDecoder class
+
 .. class:: IncrementalNewlineDecoder
 
-   A helper codec that decodes newlines for universal newlines mode.  It
-   inherits :class:`codecs.IncrementalDecoder`.
+   A helper codec that decodes newlines for :term:`universal newlines` mode.
+   It inherits :class:`codecs.IncrementalDecoder`.
 
 
 Performance

diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index f46787e153b7fedb0ccf44bda2af6dc69f9092cb..9688393695585530a7c6b72c2dc8dd1f1f6f3551 100644 (file)
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -1325,10 +1325,13 @@ functions based on regular expressions.
    ``'  1  2   3  '.split(None, 1)`` returns ``['1', '2   3  ']``.
 
 
+.. index::
+   single: universal newlines; str.splitlines method
+
 .. method:: str.splitlines([keepends])
 
    Return a list of the lines in the string, breaking at line boundaries.
-   This method uses the universal newlines approach to splitting lines.
+   This method uses the :term:`universal newlines` approach to splitting lines.
    Line breaks are not included in the resulting list unless *keepends* is
    given and true.
 

diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst
index b96398300ed6798075bd760f0cc7878f76463425..899bd7c26bc0328a7f6c3e9304469e4084e415af 100644 (file)
--- a/Doc/library/subprocess.rst
+++ b/Doc/library/subprocess.rst
@@ -224,9 +224,12 @@ default values. The arguments that are most commonly needed are:
    the stderr data from the child process should be captured into the same file
    handle as for stdout.
 
+   .. index::
+      single: universal newlines; subprocess module
+
    If *universal_newlines* is ``True``, the file objects *stdin*, *stdout*
-   and *stderr* will be opened as text streams with universal newlines support,
-   using the encoding returned by :func:`locale.getpreferredencoding`.
+   and *stderr* will be opened as text streams in :term:`universal newlines`
+   mode using the encoding returned by :func:`locale.getpreferredencoding`.
    For *stdin*, line ending characters ``'\n'`` in the input will be converted
    to the default line separator :data:`os.linesep`.  For *stdout* and
    *stderr*, all line endings in the output will be converted to ``'\n'``.
@@ -440,7 +443,7 @@ functions.
    .. _side-by-side assembly: http://en.wikipedia.org/wiki/Side-by-Side_Assembly
 
    If *universal_newlines* is ``True``, the file objects *stdin*, *stdout*
-   and *stderr* are opened as text files with universal newlines support, as
+   and *stderr* are opened as text streams in universal newlines mode, as
    described above in :ref:`frequently-used-arguments`.
 
    If given, *startupinfo* will be a :class:`STARTUPINFO` object, which is

diff --git a/Doc/library/zipfile.rst b/Doc/library/zipfile.rst
index bcec1344a29a492beaea89478a291ee5942f89b1..4035a14d84225e9689b8e86cce36e20c26c4e1a2 100644 (file)
--- a/Doc/library/zipfile.rst
+++ b/Doc/library/zipfile.rst
@@ -169,13 +169,17 @@ ZipFile Objects
    Return a list of archive members by name.
 
 
+.. index::
+   single: universal newlines; zipfile.ZipFile.open method
+
 .. method:: ZipFile.open(name, mode='r', pwd=None)
 
    Extract a member from the archive as a file-like object (ZipExtFile). *name* is
    the name of the file in the archive, or a :class:`ZipInfo` object. The *mode*
    parameter, if included, must be one of the following: ``'r'`` (the  default),
-   ``'U'``, or ``'rU'``. Choosing ``'U'`` or  ``'rU'`` will enable universal newline
-   support in the read-only object. *pwd* is the password used for encrypted files.
+   ``'U'``, or ``'rU'``. Choosing ``'U'`` or  ``'rU'`` will enable
+   :term:`universal newlines` support in the read-only object.
+   *pwd* is the password used for encrypted files.
    Calling  :meth:`open` on a closed ZipFile will raise a  :exc:`RuntimeError`.
 
    .. note::

diff --git a/Doc/whatsnew/2.3.rst b/Doc/whatsnew/2.3.rst
index 0cc29f608b417d5ff76de36d9be77288f0c15ada..f71422f51893a7f8efe72570a49d078eb71e4f75 100644 (file)
--- a/Doc/whatsnew/2.3.rst
+++ b/Doc/whatsnew/2.3.rst
@@ -366,6 +366,9 @@ Under MacOS, :func:`os.listdir` may now return Unicode filenames.
 .. ======================================================================
 
 
+.. index::
+   single: universal newlines; What's new
+
 PEP 278: Universal Newline Support
 ==================================
 
@@ -378,7 +381,8 @@ two-character sequence of a carriage return plus a newline.
 
 Python's file objects can now support end of line conventions other than the one
 followed by the platform on which Python is running. Opening a file with the
-mode ``'U'`` or ``'rU'`` will open a file for reading in universal newline mode.
+mode ``'U'`` or ``'rU'`` will open a file for reading in
+:term:`universal newlines` mode.
 All three line ending conventions will be translated to a ``'\n'`` in the
 strings returned by the various file methods such as :meth:`read` and
 :meth:`readline`.

diff --git a/Doc/whatsnew/2.4.rst b/Doc/whatsnew/2.4.rst
index 09ff600d395a170de2b41e2069f00fab2b2bc9d9..9d339a5a737819082f70e0318f76ad1fafc1bb76 100644 (file)
--- a/Doc/whatsnew/2.4.rst
+++ b/Doc/whatsnew/2.4.rst
@@ -411,6 +411,9 @@ error streams will be.  You can provide a file object or a file descriptor, or
 you can use the constant ``subprocess.PIPE`` to create a pipe between the
 subprocess and the parent.
 
+.. index::
+   single: universal newlines; What's new
+
 The constructor has a number of handy options:
 
 * *close_fds* requests that all file descriptors be closed before running the
@@ -424,7 +427,7 @@ The constructor has a number of handy options:
 * *preexec_fn* is a function that gets called before the child is started.
 
 * *universal_newlines* opens the child's input and output using Python's
-  universal newline feature.
+  :term:`universal newlines` feature.
 
 Once you've created the :class:`Popen` instance,  you can call its :meth:`wait`
 method to pause until the subprocess has exited, :meth:`poll` to check if it's

diff --git a/Doc/whatsnew/2.5.rst b/Doc/whatsnew/2.5.rst
index ff599c8d8a2564542d5496388ea6db4bc8475be8..afe0f5e5efb91555c257457524f05ddb22214629 100644 (file)
--- a/Doc/whatsnew/2.5.rst
+++ b/Doc/whatsnew/2.5.rst
@@ -1338,10 +1338,14 @@ complete list of changes, or look through the SVN logs for all the details.
 
   .. XXX need to provide some more detail here
 
+  .. index::
+     single: universal newlines; What's new
+
 * The :mod:`fileinput` module was made more flexible. Unicode filenames are now
   supported, and a *mode* parameter that defaults to ``"r"`` was added to the
-  :func:`input` function to allow opening files in binary or universal-newline
-  mode.  Another new parameter, *openhook*, lets you use a function other than
+  :func:`input` function to allow opening files in binary or
+  :term:`universal newlines` mode.
+  Another new parameter, *openhook*, lets you use a function other than
   :func:`open`  to open the input files.  Once you're iterating over  the set of
   files, the :class:`FileInput` object's new :meth:`fileno` returns the file
   descriptor for the currently opened file. (Contributed by Georg Brandl.)

diff --git a/Doc/whatsnew/2.6.rst b/Doc/whatsnew/2.6.rst
index 6c5d630db5249743e856a911da810a00aa5d3588..a84bc194b53a5499273f25fcb2c1ef3836219e5f 100644 (file)
--- a/Doc/whatsnew/2.6.rst
+++ b/Doc/whatsnew/2.6.rst
@@ -1071,9 +1071,12 @@ the :mod:`io` module:
   The :class:`BytesIO` class supports reading, writing, and seeking
   over an in-memory buffer.
 
+  .. index::
+     single: universal newlines; What's new
+
 * :class:`TextIOBase`: Provides functions for reading and writing
   strings (remember, strings will be Unicode in Python 3.0),
-  and supporting universal newlines.  :class:`TextIOBase` defines
+  and supporting :term:`universal newlines`.  :class:`TextIOBase` defines
   the :meth:`readline` method and supports iteration upon
   objects.