From 8a03ff2ff4db973c9fe152561f1796e72cb71132 Mon Sep 17 00:00:00 2001 From: Terry Jan Reedy Date: Fri, 8 Feb 2019 22:51:51 -0500 Subject: [PATCH] bpo-35833: Revise IDLE doc for control codes sent to Shell. (GH-11799) Add a code example block. --- Doc/library/idle.rst | 35 +++++++++++---- Lib/idlelib/NEWS.txt | 3 ++ Lib/idlelib/help.html | 45 +++++++++++++------ .../2019-02-08-22-14-24.bpo-35833.XKFRvF.rst | 1 + 4 files changed, 62 insertions(+), 22 deletions(-) create mode 100644 Misc/NEWS.d/next/IDLE/2019-02-08-22-14-24.bpo-35833.XKFRvF.rst diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst index 56d7c9f4c2c..8290039c968 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. diff --git a/Lib/idlelib/NEWS.txt b/Lib/idlelib/NEWS.txt index 61457e93d23..60454c24c6a 100644 --- a/Lib/idlelib/NEWS.txt +++ b/Lib/idlelib/NEWS.txt @@ -3,6 +3,9 @@ Released on 2019-10-20? ====================================== +bpo-35833: Revise IDLE doc for control codes sent to Shell. +Add a code example block. + bpo-35770: IDLE macosx deletes Options => Configure IDLE. It previously deleted Window => Zoom Height by mistake. (Zoom Height is now on the Options menu). On Mac, the settings diff --git a/Lib/idlelib/help.html b/Lib/idlelib/help.html index 80c87f6ebdf..374159f807e 100644 --- a/Lib/idlelib/help.html +++ b/Lib/idlelib/help.html @@ -6,7 +6,7 @@ - IDLE — Python 3.8.0a0 documentation + IDLE — Python 3.8.0a1 documentation @@ -19,7 +19,7 @@ @@ -72,7 +72,7 @@
  • - 3.8.0a0 Documentation » + 3.8.0a1 Documentation »
  • The Python Standard Library »
    • @@ -673,14 +673,31 @@ output to Shell will eventually fill memory, resulting in a memory error. 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.)

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

    For SyntaxError tracebacks, the normal ‘^’ marking where the error was @@ -889,7 +906,7 @@ also used for testing.

  • - 3.8.0a0 Documentation » + 3.8.0a1 Documentation »
  • The Python Standard Library »
    • @@ -912,7 +929,7 @@ also used for testing.

    - © Copyright 2001-2018, Python Software Foundation. + © Copyright 2001-2019, Python Software Foundation.
    The Python Software Foundation is a non-profit corporation. @@ -920,7 +937,7 @@ also used for testing.



    - Last updated on Dec 28, 2018. + Last updated on Feb 08, 2019. Found a bug?
    diff --git a/Misc/NEWS.d/next/IDLE/2019-02-08-22-14-24.bpo-35833.XKFRvF.rst b/Misc/NEWS.d/next/IDLE/2019-02-08-22-14-24.bpo-35833.XKFRvF.rst new file mode 100644 index 00000000000..abc92e9442a --- /dev/null +++ b/Misc/NEWS.d/next/IDLE/2019-02-08-22-14-24.bpo-35833.XKFRvF.rst @@ -0,0 +1 @@ +Revise IDLE doc for control codes sent to Shell. Add a code example block.