whatsnew: fix textwrap/shorten entry, and improve the related docs.

I had incorrectly added back the shorten method when I initially
made the whatsnew entry, but the shorten function docs were not
correct according to the code.  I also improved the wording in
general.

diff --git a/Doc/library/textwrap.rst b/Doc/library/textwrap.rst
index 01887292bdcf193d91b12324f1f05444a290ccb9..edf1fd6ece45fb403a4a0df8f60882cae6fe59ca 100644 (file)
--- a/Doc/library/textwrap.rst
+++ b/Doc/library/textwrap.rst
@@ -40,13 +40,14 @@ functions should be good enough; otherwise, you should use an instance of
    :func:`wrap`.
 
 
-.. function:: shorten(text, width=70, *, placeholder=" [...]")
+.. function:: shorten(text, width, **kwargs)
 
-   Collapse and truncate the given text to fit in the given width.
+   Collapse and truncate the given *text* to fit in the given *width*.
 
-   The text first has its whitespace collapsed.  If it then fits in
-   the *width*, it is returned unchanged.  Otherwise, as many words
-   as possible are joined and then the *placeholder* is appended::
+   First the whitespace in *text* is collapsed (all whitespace is replaced by
+   single spaces).  If the result fits in the *width*, it is returned.
+   Otherwise, enough words are dropped from the end so that the remaining words
+   plus the :attr:`placeholder` fit within :attr:`width`::
 
       >>> textwrap.shorten("Hello  world!", width=12)
       'Hello world!'
@@ -55,6 +56,12 @@ functions should be good enough; otherwise, you should use an instance of
       >>> textwrap.shorten("Hello world", width=10, placeholder="...")
       'Hello...'
 
+   Optional keyword arguments correspond to the instance attributes of
+   :class:`TextWrapper`, documented below.  Note that the whitespace is
+   collapsed before the text is passed to the :class:`TextWrapper` :meth:`fill`
+   function, so changing the value of :attr:`.tabsize`, :attr:`.expand_tabs`,
+   :attr:`.drop_whitespace`, and :attr:`.replace_whitespace` will have no effect.
+
    .. versionadded:: 3.4
 
 
@@ -110,8 +117,8 @@ functions should be good enough; otherwise, you should use an instance of
 :func:`wrap`, :func:`fill` and :func:`shorten` work by creating a
 :class:`TextWrapper` instance and calling a single method on it.  That
 instance is not reused, so for applications that process many text
-strings, it may be more efficient to create your own
-:class:`TextWrapper` object.
+strings using :func:`wrap` and/or :func:`fill`, it may be more efficient to
+create your own :class:`TextWrapper` object.
 
 Text is preferably wrapped on whitespaces and right after the hyphens in
 hyphenated words; only then will long words be broken if necessary, unless
@@ -252,16 +259,16 @@ hyphenated words; only then will long words be broken if necessary, unless
 
    .. attribute:: max_lines
 
-      (default: ``None``) If not ``None``, then the text be will truncated to
-      *max_lines* lines.
+      (default: ``None``) If not ``None``, then the output will contain at most
+      *max_lines* lines, with *placeholder* appearing at the end of the output.
 
       .. versionadded:: 3.4
 
 
    .. attribute:: placeholder
 
-      (default: ``' [...]'``) String that will be appended to the last line of
-      text if it will be truncated.
+      (default: ``' [...]'``) String that will appear at the end of the output
+      text if it has been truncated.
 
       .. versionadded:: 3.4
 
@@ -282,13 +289,3 @@ hyphenated words; only then will long words be broken if necessary, unless
 
       Wraps the single paragraph in *text*, and returns a single string
       containing the wrapped paragraph.
-
-
-   .. method:: shorten(text, width=70, *, placeholder=" [...]")
-
-      Collapse and truncate the given text to fit in the given width.
-      The text first has its whitespace collapsed.  If it then fits in
-      the *width*, it is returned unchanged.  Otherwise, as many words
-      as possible are joined and then the *placeholder* is appended.
-
-      .. versionadded:: 3.4

diff --git a/Doc/whatsnew/3.4.rst b/Doc/whatsnew/3.4.rst
index 997afc49d3152ccbd3306f4769be131e906bada6..16799ff70c8b6ed90f7a494087f5a0b73c6b3eba 100644 (file)
--- a/Doc/whatsnew/3.4.rst
+++ b/Doc/whatsnew/3.4.rst
@@ -1250,15 +1250,15 @@ in :issue:`13390`.)
 textwrap
 --------
 
-:mod:`textwrap` has a new function :func:`~textwrap.shorten`, implemented via a
-new :class:`~textwrap.TextWrapper` method
-:meth:`~textwrap.TextWrapper.shorten`, that provides a convenient way to create
-a string that displays just the leading porting of an input string.  It
-collapses any whitespace, truncates the result to a specified width, and a
-specified placeholder is added (by default, ``[...]``, stored in the new
-:attr:`~textwrap.TextWrapper.placeholder` attribute of the
-:class:`~textwrap.TextWrapper` object)).  (Contributed by Antoine Pitrou in
-:issue:`18585`.)
+The :class:`~textwrap.TextWrapper` class has two new attributes/constructor
+arguments: :attr:`~textwrap.TextWrapper.max_lines`, which limits the number of
+lines in the output, and :attr:`~textwrap.TextWrapper.placeholder`, which is a
+string that will appear at the end of the output if it has been truncated
+because of *max_lines*.  Building on these capabilities, a new convenience
+function :func:`~textwrap.shorten` collapses all of the whitespace in the input
+to single spaces and produces a single line of a given *width* that ends with
+the *placeholder* (by default, ``[...]``).  (Contributed by Antoine Pitrou and
+Serhiy Storchaka in :issue:`18585` and :issue:`18725`.)
 
 
 threading