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

Add  a code example block.
This commit is contained in:
Terry Jan Reedy 2019-02-08 22:51:51 -05:00 committed by GitHub
parent 2dda72a2e8
commit 8a03ff2ff4
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 62 additions and 22 deletions

View File

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

View File

@ -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

View File

@ -6,7 +6,7 @@
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>IDLE &#8212; Python 3.8.0a0 documentation</title>
<title>IDLE &#8212; Python 3.8.0a1 documentation</title>
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
@ -19,7 +19,7 @@
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 3.8.0a0 documentation"
title="Search within Python 3.8.0a1 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
@ -72,7 +72,7 @@
<li>
<a href="../index.html">3.8.0a0 Documentation</a> &#187;
<a href="../index.html">3.8.0a1 Documentation</a> &#187;
</li>
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>
@ -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.</p>
<p>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, <code class="docutils literal notranslate"><span class="pre">repr()</span></code>, 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.</p>
<p>A Tk Text widget, and hence IDLEs 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.)</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>&gt;&gt;&gt; s = &#39;a\tb\a&lt;\x02&gt;&lt;\r&gt;\bc\nd&#39;
&gt;&gt;&gt; len(s)
14
&gt;&gt;&gt; s # Display repr(s)
&#39;a\tb\x07&lt;\x02&gt;&lt;\r&gt;\x08c\nd&#39;
&gt;&gt;&gt; print(s, end=&#39;&#39;) # Display s as is.
# Result varies by OS and font. Try it.
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">repr</span></code> 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.</p>
<p>Normal and error output are generally kept separate (on separate lines)
from code input and each other. They each get different highlight colors.</p>
<p>For SyntaxError tracebacks, the normal ^ marking where the error was
@ -889,7 +906,7 @@ also used for testing.</p>
<li>
<a href="../index.html">3.8.0a0 Documentation</a> &#187;
<a href="../index.html">3.8.0a1 Documentation</a> &#187;
</li>
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>
@ -912,7 +929,7 @@ also used for testing.</p>
</ul>
</div>
<div class="footer">
&copy; <a href="../copyright.html">Copyright</a> 2001-2018, Python Software Foundation.
&copy; <a href="../copyright.html">Copyright</a> 2001-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
@ -920,7 +937,7 @@ also used for testing.</p>
<br />
<br />
Last updated on Dec 28, 2018.
Last updated on Feb 08, 2019.
<a href="https://docs.python.org/3/bugs.html">Found a bug</a>?
<br />

View File

@ -0,0 +1 @@
Revise IDLE doc for control codes sent to Shell. Add a code example block.