From a9bfbf858e6cb0e8a1b7a6abb1b863c0261cb258 Mon Sep 17 00:00:00 2001 From: Terry Jan Reedy Date: Tue, 13 Jan 2026 01:16:46 -0500 Subject: [PATCH 1/4] gh-143774 - Improve IDLE Format Paragraph doc Define 'paragraph' better and mention indent preservation, selection expansion, and length setting. --- Doc/library/idle.rst | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst index a16f46ef812400..d31fb1e9921e01 100644 --- a/Doc/library/idle.rst +++ b/Doc/library/idle.rst @@ -178,9 +178,14 @@ Format menu (Editor window only) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Format Paragraph - Reformat the current blank-line-delimited paragraph in comment block or - multiline string or selected line in a string. All lines in the - paragraph will be formatted to less than N columns, where N defaults to 72. + Rewrap the current 'paragraph'. A paragraph is a contiguous block of + equally indented non-blank comments containing the text cursor, a + similar block of non-comment lines (expected to be within a multiline + string), or a selection of a subset of either. (Partial lines in a + selection expand to complete lines.) The resulting lines have the + same indent as before but a max length of N columns (characters). + Change the default N of 72 on the Window tab of IDLE Settings. + Avoid rewrapping code lines. Indent Region Shift selected lines right by the indent width (default 4 spaces). From 3a181aa220706730e0812e09340c930032ac0671 Mon Sep 17 00:00:00 2001 From: Terry Jan Reedy Date: Tue, 13 Jan 2026 01:21:51 -0500 Subject: [PATCH 2/4] News item --- .../next/IDLE/2026-01-13-01-21-20.gh-issue-143774.rqGwX1.rst | 1 + 1 file changed, 1 insertion(+) create mode 100644 Misc/NEWS.d/next/IDLE/2026-01-13-01-21-20.gh-issue-143774.rqGwX1.rst diff --git a/Misc/NEWS.d/next/IDLE/2026-01-13-01-21-20.gh-issue-143774.rqGwX1.rst b/Misc/NEWS.d/next/IDLE/2026-01-13-01-21-20.gh-issue-143774.rqGwX1.rst new file mode 100644 index 00000000000000..dd15d1672b1b54 --- /dev/null +++ b/Misc/NEWS.d/next/IDLE/2026-01-13-01-21-20.gh-issue-143774.rqGwX1.rst @@ -0,0 +1 @@ +Better explain the operation of Format / Format Paragraph. From 89b152d8a467120b23370f16728781114c819c1e Mon Sep 17 00:00:00 2001 From: Terry Jan Reedy Date: Tue, 20 Jan 2026 01:19:34 -0500 Subject: [PATCH 3/4] Move most new text to a new subsection --- Doc/library/idle.rst | 29 +++++++++++++++++++---------- 1 file changed, 19 insertions(+), 10 deletions(-) diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst index d31fb1e9921e01..32f16b5e6fba2f 100644 --- a/Doc/library/idle.rst +++ b/Doc/library/idle.rst @@ -158,7 +158,7 @@ Go to Line Show Completions Open a scrollable list allowing selection of existing names. See - :ref:`Completions ` in the Editing and navigation section below. + :ref:`Completions ` in the Editing and Navigation section below. Expand Word Expand a prefix you have typed to match a full word in the same window; @@ -167,7 +167,7 @@ Expand Word Show Call Tip After an unclosed parenthesis for a function, open a small window with function parameter hints. See :ref:`Calltips ` in the - Editing and navigation section below. + Editing and Navigation section below. Show Surrounding Parens Highlight the surrounding parenthesis. @@ -178,14 +178,9 @@ Format menu (Editor window only) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Format Paragraph - Rewrap the current 'paragraph'. A paragraph is a contiguous block of - equally indented non-blank comments containing the text cursor, a - similar block of non-comment lines (expected to be within a multiline - string), or a selection of a subset of either. (Partial lines in a - selection expand to complete lines.) The resulting lines have the - same indent as before but a max length of N columns (characters). - Change the default N of 72 on the Window tab of IDLE Settings. - Avoid rewrapping code lines. + Rewrap the text block containing the text insert cursor. + Avoid code lines. See :ref:`Format Menu` in the + Editing and Navigation section below. Indent Region Shift selected lines right by the indent width (default 4 spaces). @@ -571,6 +566,20 @@ In an editor, import statements have no effect until one runs the file. One might want to run a file after writing import statements, after adding function definitions, or after opening an existing file. +.. _format-menu: + +Format Menu +^^^^^^^^^^^ + +Reformat Paragraph rewraps a block ('paragraph') of contiguous equally +indented non-blank comments, a similar block of text within a multiline +string, or a selected subset of either. +If needed, add a blank line to separate string from code. +Partial lines in a selection expand to complete lines. +The resulting lines have the same indent as before +but have maximum total length of N columns (characters). +Change the default N of 72 on the Window tab of IDLE Settings. + .. _code-context: Code Context From 8655aa790acd0328be509746bf59cdd968a49f05 Mon Sep 17 00:00:00 2001 From: Terry Jan Reedy Date: Tue, 20 Jan 2026 01:29:01 -0500 Subject: [PATCH 4/4] Fix duplicate reference; add help.html changes --- Doc/library/idle.rst | 8 ++++---- Lib/idlelib/help.html | 25 ++++++++++++++++++------- 2 files changed, 22 insertions(+), 11 deletions(-) diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst index 32f16b5e6fba2f..89be225b6baae4 100644 --- a/Doc/library/idle.rst +++ b/Doc/library/idle.rst @@ -179,7 +179,7 @@ Format menu (Editor window only) Format Paragraph Rewrap the text block containing the text insert cursor. - Avoid code lines. See :ref:`Format Menu` in the + Avoid code lines. See :ref:`Format block` in the Editing and Navigation section below. Indent Region @@ -566,10 +566,10 @@ In an editor, import statements have no effect until one runs the file. One might want to run a file after writing import statements, after adding function definitions, or after opening an existing file. -.. _format-menu: +.. _format-block: -Format Menu -^^^^^^^^^^^ +Format block +^^^^^^^^^^^^ Reformat Paragraph rewraps a block ('paragraph') of contiguous equally indented non-blank comments, a similar block of text within a multiline diff --git a/Lib/idlelib/help.html b/Lib/idlelib/help.html index 9eb18d8f39b7c6..eda16ac5bed118 100644 --- a/Lib/idlelib/help.html +++ b/Lib/idlelib/help.html @@ -111,14 +111,14 @@

Edit menu (Shell and Editor)Completions in the Editing and navigation section below.

+Completions in the Editing and Navigation section below.

Expand Word

Expand a prefix you have typed to match a full word in the same window; repeat to get a different expansion.

Show Call Tip

After an unclosed parenthesis for a function, open a small window with function parameter hints. See Calltips in the -Editing and navigation section below.

+Editing and Navigation section below.

Show Surrounding Parens

Highlight the surrounding parenthesis.

@@ -127,9 +127,9 @@

Edit menu (Shell and Editor)

Format menu (Editor window only)

-
Format Paragraph

Reformat the current blank-line-delimited paragraph in comment block or -multiline string or selected line in a string. All lines in the -paragraph will be formatted to less than N columns, where N defaults to 72.

+
Format Paragraph

Rewrap the text block containing the text insert cursor. +Avoid code lines. See Format block in the +Editing and Navigation section below.

Indent Region

Shift selected lines right by the indent width (default 4 spaces).

@@ -443,8 +443,19 @@

Search and Replace +

Format block

+

Reformat Paragraph rewraps a block (‘paragraph’) of contiguous equally +indented non-blank comments, a similar block of text within a multiline +string, or a selected subset of either. +If needed, add a blank line to separate string from code. +Partial lines in a selection expand to complete lines. +The resulting lines have the same indent as before +but have maximum total length of N columns (characters). +Change the default N of 72 on the Window tab of IDLE Settings.

+
-

Code Context

+

Code Context

Within an editor window containing Python code, code context can be toggled in order to show or hide a pane at the top of the window. When shown, this pane freezes the opening lines for block code, such as those beginning with @@ -791,7 +802,7 @@

Running without a subprocess

Help and Preferences

-

Help sources

+

Help sources

Help menu entry “IDLE Help” displays a formatted html version of the IDLE chapter of the Library Reference. The result, in a read-only tkinter text window, is close to what one sees in a web browser.