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

Patch by Chris Jerdonek.

7 files changed, 56 insertions, 28 deletions

diff --git a/Doc/library/csv.rst b/Doc/library/csv.rst
index ec0dfcc..5d8368b 100644
--- 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 86e565f..de29a1a 100644
--- 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,17 @@ 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
-   works as follows:
+   .. 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 d217b0a..292fec1 100644
--- a/Doc/library/importlib.rst
+++ b/Doc/library/importlib.rst
@@ -290,12 +290,16 @@ ABC hierarchy::
         (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
-        source is available (e.g. a built-in module). Raises :exc:`ImportError`
-        if the loader cannot find the module specified.
+        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.
 
     .. method:: is_package(fullname)
 
diff --git a/Doc/library/io.rst b/Doc/library/io.rst
index f632752..3a8ddd0 100644
--- a/Doc/library/io.rst
+++ b/Doc/library/io.rst
@@ -768,16 +768,20 @@ 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'``,
-     ``'\r'``, or ``'\r\n'``, and these are translated into ``'\n'`` before
-     being returned to the caller.  If it is ``''``, universal newline 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.
+   * 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 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.
 
    * When writing output to the stream, if *newline* is ``None``, any ``'\n'``
      characters written are translated to the system default line separator,
@@ -843,10 +847,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 4a3f883..0e71910 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -1349,10 +1349,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 7557c92..ff6bb99 100644
--- a/Doc/library/subprocess.rst
+++ b/Doc/library/subprocess.rst
@@ -285,9 +285,12 @@ default values. The arguments that are most commonly needed are:
    :data:`STDOUT`, which indicates that 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'``.
@@ -508,7 +511,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 409de44..498a9cd 100644
--- a/Doc/library/zipfile.rst
+++ b/Doc/library/zipfile.rst
@@ -197,14 +197,18 @@ 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.
-   Calling  :meth:`open` on a closed ZipFile will raise a  :exc:`RuntimeError`.
+   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
+   :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::