mirror/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2026-01-26 12:55:08 +00:00
Code Issues Packages Projects Releases Wiki Activity

gh-143774 - Improve IDLE Format Paragraph doc (#143775)

Browse Source 
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.)
This commit is contained in:
Terry Jan Reedy 2026-01-20 04:07:29 -05:00 committed by GitHub
parent 71cbffde61
commit fa3abf5a51
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 38 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
Doc/library/idle.rst
View File

@ -158,7 +158,7 @@ Go to Line
Show Completions
Open a scrollable list allowing selection of existing names. See
:ref:`Completions <completions>` in the Editing and navigation section below.
:ref:`Completions <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 <calltips>` in the
Editing and navigation section below.
Editing and Navigation section below.
Show Surrounding Parens
Highlight the surrounding parenthesis.
@ -178,9 +178,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<format-block>` in the
Editing and Navigation section below.
Indent Region
Shift selected lines right by the indent width (default 4 spaces).
@ -566,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-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

25
Lib/idlelib/help.html generated
View File

@ -111,14 +111,14 @@ line visible. A request past the end of the file goes to the end.
Clear any selection and update the line and column status.</p>
</dd>
<dt>Show Completions</dt><dd><p>Open a scrollable list allowing selection of existing names. See
<a class="reference internal" href="#completions"><span class="std std-ref">Completions</span></a> in the Editing and navigation section below.</p>
<a class="reference internal" href="#completions"><span class="std std-ref">Completions</span></a> in the Editing and Navigation section below.</p>
</dd>
<dt>Expand Word</dt><dd><p>Expand a prefix you have typed to match a full word in the same window;
repeat to get a different expansion.</p>
</dd>
<dt>Show Call Tip</dt><dd><p>After an unclosed parenthesis for a function, open a small window with
function parameter hints. See <a class="reference internal" href="#calltips"><span class="std std-ref">Calltips</span></a> in the
Editing and navigation section below.</p>
Editing and Navigation section below.</p>
</dd>
<dt>Show Surrounding Parens</dt><dd><p>Highlight the surrounding parenthesis.</p>
</dd>
@ -127,9 +127,9 @@ Editing and navigation section below.</p>
<section id="format-menu-editor-window-only">
<span id="format-menu"></span><h3>Format menu (Editor window only)<a class="headerlink" href="#format-menu-editor-window-only" title="Link to this heading"></a></h3>
<dl class="simple">
<dt>Format Paragraph</dt><dd><p>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.</p>
<dt>Format Paragraph</dt><dd><p>Rewrap the text block containing the text insert cursor.
Avoid code lines. See <a class="reference internal" href="#format-block"><span class="std std-ref">Format block</span></a> in the
Editing and Navigation section below.</p>
</dd>
<dt>Indent Region</dt><dd><p>Shift selected lines right by the indent width (default 4 spaces).</p>
</dd>
@ -443,8 +443,19 @@ will display a calltip.</p>
One might want to run a file after writing import statements, after
adding function definitions, or after opening an existing file.</p>
</section>
<section id="format-block">
<span id="id4"></span><h3>Format block<a class="headerlink" href="#format-block" title="Link to this heading"></a></h3>
<p>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.</p>
</section>
<section id="code-context">
<span id="id4"></span><h3>Code Context<a class="headerlink" href="#code-context" title="Link to this heading"></a></h3>
<span id="id5"></span><h3>Code Context<a class="headerlink" href="#code-context" title="Link to this heading"></a></h3>
<p>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 @@ with the default subprocess if at all possible.</p>
<section id="help-and-preferences">
<h2>Help and Preferences<a class="headerlink" href="#help-and-preferences" title="Link to this heading"></a></h2>
<section id="help-sources">
<span id="id5"></span><h3>Help sources<a class="headerlink" href="#help-sources" title="Link to this heading"></a></h3>
<span id="id6"></span><h3>Help sources<a class="headerlink" href="#help-sources" title="Link to this heading"></a></h3>
<p>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.

1
Misc/NEWS.d/next/IDLE/2026-01-13-01-21-20.gh-issue-143774.rqGwX1.rst Normal file
View File

@ -0,0 +1 @@
Better explain the operation of Format / Format Paragraph.