bpo-35833: Revise IDLE doc for control codes sent to Shell. (GH-11799)

Add  a code example block.

1 files changed, 27 insertions, 8 deletions

diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst
index 56d7c9f..8290039 100644
--- a/Doc/library/idle.rst
+++ b/Doc/library/idle.rst
@@ -716,14 +716,33 @@ In contrast, some system text windows only keep the last n lines of output.
 A Windows console, for instance, keeps a user-settable 1 to 9999 lines,
 with 300 the default.
 
-Text widgets display a subset of Unicode, the Basic Multilingual Plane (BMP).
-Which characters get a proper glyph instead of a replacement box depends on
-the operating system and installed fonts.  Newline characters cause following
-text to appear on a new line, but other control characters are either
-replaced with a box or deleted.  However, ``repr()``, which is used for
-interactive echo of expression values, replaces control characters,
-some BMP codepoints, and all non-BMP characters with escape codes
-before they are output.
+A Tk Text widget, and hence IDLE's Shell, displays characters (codepoints)
+in the the BMP (Basic Multilingual Plane) subset of Unicode.
+Which characters are displayed with a proper glyph and which with a
+replacement box depends on the operating system and installed fonts.
+Tab characters cause the following text to begin after
+the next tab stop. (They occur every 8 'characters').
+Newline characters cause following text to appear on a new line.
+Other control characters are ignored or displayed as a space, box, or
+something else, depending on the operating system and font.
+(Moving the text cursor through such output with arrow keys may exhibit
+some surprising spacing behavior.)
+
+.. code-block:: none
+
+   >>> s = 'a\tb\a<\x02><\r>\bc\nd'
+   >>> len(s)
+   14
+   >>> s  # Display repr(s)
+   'a\tb\x07<\x02><\r>\x08c\nd'
+   >>> print(s, end='')  # Display s as is.
+   # Result varies by OS and font.  Try it.
+
+The ``repr`` function is used for interactive echo of expression
+values.  It returns an altered version of the input string in which
+control codes, some BMP codepoints, and all non-BMP codepoints are
+replaced with escape codes. As demonstrated above, it allows one to
+identify the characters in a string, regardless of how they are displayed.
 
 Normal and error output are generally kept separate (on separate lines)
 from code input and each other.  They each get different highlight colors.