gh-145649: Fix man page text wrapping for -X option (#145656)

Replace hardcoded space indentation with proper troff macros
(.TP, .RS/.RE, .IP) for -X sub-options so text wraps correctly
at any terminal width.

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

diff --git a/Misc/NEWS.d/next/Documentation/2026-03-09-00-00-00.gh-issue-145649.8BcbAB.rst b/Misc/NEWS.d/next/Documentation/2026-03-09-00-00-00.gh-issue-145649.8BcbAB.rst
new file mode 100644 (file)
index 0000000..33061f7
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2026-03-09-00-00-00.gh-issue-145649.8BcbAB.rst
@@ -0,0 +1,2 @@
+Fix text wrapping and formatting of ``-X`` option descriptions in the
+:manpage:`python(1)` man page by using proper roff markup.

diff --git a/Misc/python.man b/Misc/python.man
index 612e2bbf56800eb375ada2ee11dd725d7f04bd56..a65fb98a697b5031b02cc0779770b6885f3ed334 100644 (file)
--- a/Misc/python.man
+++ b/Misc/python.man
@@ -320,82 +320,105 @@ a regular expression on the warning message.
 .TP
 .BI "\-X " option
 Set implementation-specific option. The following options are available:
-
-    \fB\-X cpu_count=\fIN\fR: override the return value of \fIos.cpu_count()\fR;
-       \fB\-X cpu_count=default\fR cancels overriding; also \fBPYTHON_CPU_COUNT\fI
-
-    \fB\-X dev\fR: enable CPython's "development mode", introducing additional
-        runtime checks which are too expensive to be enabled by default. It
-        will not be more verbose than the default if the code is correct: new
-        warnings are only emitted when an issue is detected. Effect of the
-        developer mode:
-           * Add default warning filter, as \fB\-W default\fR
-           * Install debug hooks on memory allocators: see the
-             PyMem_SetupDebugHooks() C function
-           * Enable the faulthandler module to dump the Python traceback on a
-             crash
-           * Enable asyncio debug mode
-           * Set the dev_mode attribute of sys.flags to True
-           * io.IOBase destructor logs close() exceptions
-
-    \fB\-X importtime\fR: show how long each import takes. It shows module name,
-        cumulative time (including nested imports) and self time (excluding
-        nested imports). Note that its output may be broken in multi-threaded
-        application. Typical usage is
-        \fBpython3 \-X importtime \-c 'import asyncio'\fR
-
-        \fB\-X importtime=2\fR enables additional output that indicates when an
-        imported module has already been loaded.  In such cases, the string
-        \fBcached\fR will be printed in both time columns.
-
-    \fB\-X faulthandler\fR: enable faulthandler
-
-    \fB\-X frozen_modules=\fR[\fBon\fR|\fBoff\fR]: whether or not frozen modules
-       should be used.
-       The default is "on" (or "off" if you are running a local build).
-
-    \fB\-X gil=\fR[\fB0\fR|\fB1\fR]: enable (1) or disable (0) the GIL; also
-       \fBPYTHON_GIL\fR
-       Only available in builds configured with \fB\-\-disable\-gil\fR.
-
-    \fB\-X int_max_str_digits=\fInumber\fR: limit the size of int<->str conversions.
-       This helps avoid denial of service attacks when parsing untrusted data.
-       The default is sys.int_info.default_max_str_digits.  0 disables.
-
-    \fB\-X no_debug_ranges\fR: disable the inclusion of the tables mapping extra
-       location information (end line, start column offset and end column
-       offset) to every instruction in code objects. This is useful when
-       smaller code objects and pyc files are desired as well as suppressing
-       the extra visual location indicators when the interpreter displays
-       tracebacks.
-
-    \fB\-X perf\fR: support the Linux "perf" profiler; also \fBPYTHONPERFSUPPORT=1\fR
-
-    \fB\-X perf_jit\fR: support the Linux "perf" profiler with DWARF support;
-       also \fBPYTHON_PERF_JIT_SUPPORT=1\fR
-
-    \fB\-X presite=\fIMOD\fR: import this module before site; also \fBPYTHON_PRESITE\fR
-       This only works on debug builds.
-
-    \fB\-X pycache_prefix=\fIPATH\fR: enable writing .pyc files to a parallel
-       tree rooted at the given directory instead of to the code tree.
-
-    \fB\-X showrefcount\fR: output the total reference count and number of used
-        memory blocks when the program finishes or after each statement in the
-        interactive interpreter. This only works on debug builds
-
-    \fB\-X tracemalloc\fR: start tracing Python memory allocations using the
-        tracemalloc module. By default, only the most recent frame is stored in a
-        traceback of a trace. Use \-X tracemalloc=NFRAME to start tracing with a
-        traceback limit of NFRAME frames
-
-    \fB\-X utf8\fR: enable UTF-8 mode for operating system interfaces,
-        overriding the default locale-aware mode. \fB\-X utf8=0\fR explicitly
-        disables UTF-8 mode (even when it would otherwise activate
-        automatically). See \fBPYTHONUTF8\fR for more details
-
-    \fB\-X warn_default_encoding\fR: enable opt-in EncodingWarning for 'encoding=None'
-
+.RS
+.TP
+\fB\-X cpu_count=\fIN\fR
+Override the return value of \fIos.cpu_count()\fR.
+\fB\-X cpu_count=default\fR cancels overriding.
+See also \fBPYTHON_CPU_COUNT\fR.
+.TP
+\fB\-X dev\fR
+Enable CPython's "development mode", introducing additional
+runtime checks which are too expensive to be enabled by default. It
+will not be more verbose than the default if the code is correct: new
+warnings are only emitted when an issue is detected. Effect of the
+developer mode:
+.RS
+.IP \(bu 2
+Add default warning filter, as \fB\-W default\fR.
+.IP \(bu 2
+Install debug hooks on memory allocators: see the
+PyMem_SetupDebugHooks() C function.
+.IP \(bu 2
+Enable the faulthandler module to dump the Python traceback on a crash.
+.IP \(bu 2
+Enable asyncio debug mode.
+.IP \(bu 2
+Set the dev_mode attribute of sys.flags to True.
+.IP \(bu 2
+io.IOBase destructor logs close() exceptions.
+.RE
+.TP
+\fB\-X importtime\fR
+Show how long each import takes. It shows module name,
+cumulative time (including nested imports) and self time (excluding
+nested imports). Note that its output may be broken in multi-threaded
+application. Typical usage is
+\fBpython3 \-X importtime \-c 'import asyncio'\fR.
+.IP
+\fB\-X importtime=2\fR enables additional output that indicates when an
+imported module has already been loaded. In such cases, the string
+\fBcached\fR will be printed in both time columns.
+.TP
+\fB\-X faulthandler\fR
+Enable faulthandler.
+.TP
+\fB\-X frozen_modules=\fR[\fBon\fR|\fBoff\fR]
+Whether or not frozen modules should be used.
+The default is "on" (or "off" if you are running a local build).
+.TP
+\fB\-X gil=\fR[\fB0\fR|\fB1\fR]
+Enable (1) or disable (0) the GIL. See also \fBPYTHON_GIL\fR.
+Only available in builds configured with \fB\-\-disable\-gil\fR.
+.TP
+\fB\-X int_max_str_digits=\fInumber\fR
+Limit the size of int<->str conversions.
+This helps avoid denial of service attacks when parsing untrusted data.
+The default is sys.int_info.default_max_str_digits. 0 disables.
+.TP
+\fB\-X no_debug_ranges\fR
+Disable the inclusion of the tables mapping extra
+location information (end line, start column offset and end column
+offset) to every instruction in code objects. This is useful when
+smaller code objects and pyc files are desired as well as suppressing
+the extra visual location indicators when the interpreter displays
+tracebacks.
+.TP
+\fB\-X perf\fR
+Support the Linux "perf" profiler. See also \fBPYTHONPERFSUPPORT=1\fR.
+.TP
+\fB\-X perf_jit\fR
+Support the Linux "perf" profiler with DWARF support.
+See also \fBPYTHON_PERF_JIT_SUPPORT=1\fR.
+.TP
+\fB\-X presite=\fIMOD\fR
+Import this module before site. See also \fBPYTHON_PRESITE\fR.
+This only works on debug builds.
+.TP
+\fB\-X pycache_prefix=\fIPATH\fR
+Enable writing .pyc files to a parallel
+tree rooted at the given directory instead of to the code tree.
+.TP
+\fB\-X showrefcount\fR
+Output the total reference count and number of used
+memory blocks when the program finishes or after each statement in the
+interactive interpreter. This only works on debug builds.
+.TP
+\fB\-X tracemalloc\fR
+Start tracing Python memory allocations using the
+tracemalloc module. By default, only the most recent frame is stored in a
+traceback of a trace. Use \fB\-X tracemalloc=\fINFRAME\fR to start tracing with a
+traceback limit of NFRAME frames.
+.TP
+\fB\-X utf8\fR
+Enable UTF-8 mode for operating system interfaces,
+overriding the default locale-aware mode. \fB\-X utf8=0\fR explicitly
+disables UTF-8 mode (even when it would otherwise activate
+automatically). See \fBPYTHONUTF8\fR for more details.
+.TP
+\fB\-X warn_default_encoding\fR
+Enable opt-in EncodingWarning for 'encoding=None'.
+.RE
 .TP
 .B \-x
 Skip the first line of the source.  This is intended for a DOS