From 88510a4d9e30d9589bde6ea4294bca8f24b65421 Mon Sep 17 00:00:00 2001 From: Terry Jan Reedy Date: Tue, 20 Jan 2026 04:07:29 -0500 Subject: [PATCH] gh-143774 - Improve IDLE Format Paragraph doc (GH-143775) Add a reminder to not rewrap code line to the Menu => Format => Reformat Paragraph entry. In Editing and Nagivagion, add a new 'Format block' subsection that defines 'paragraph' to better match what is dependably handled as more or less expected. In particular, specify equal indents and that the resulting indent equals original indent. Also mention that selections are expanded to complete lines and how to modify max length. (Also fix a couple case errors in cross references.) (cherry picked from commit fa3abf5a51d42b2d62e1bc89e9465b398a567e94) Co-authored-by: Terry Jan Reedy --- Doc/library/idle.rst | 24 ++++++++++++++---- Lib/idlelib/help.html | 25 +++++++++++++------ ...-01-13-01-21-20.gh-issue-143774.rqGwX1.rst | 1 + 3 files changed, 38 insertions(+), 12 deletions(-) create mode 100644 Misc/NEWS.d/next/IDLE/2026-01-13-01-21-20.gh-issue-143774.rqGwX1.rst diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst index 8249eeb15ccea9..417c0ef6cabaa6 100644 --- a/Doc/library/idle.rst +++ b/Doc/library/idle.rst @@ -159,7 +159,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; @@ -168,7 +168,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. @@ -179,9 +179,9 @@ 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 text block containing the text insert cursor. + Avoid code lines. See :ref:`Format block` in the + Editing and Navigation section below. Indent Region Shift selected lines right by the indent width (default 4 spaces). @@ -567,6 +567,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-block: + +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 diff --git a/Lib/idlelib/help.html b/Lib/idlelib/help.html index 822ee99479c9dd..3394cc34b09550 100644 --- a/Lib/idlelib/help.html +++ b/Lib/idlelib/help.html @@ -108,14 +108,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.

@@ -124,9 +124,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).

@@ -440,8 +440,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 @@ -788,7 +799,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. 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.