Repository: python/cpython
Pull request: gh-93217: fix some issues in man page and --help

Problem statement:
Minor issues in python --help and man page
**Bug report**

The man page has a markup issue and is missing documentation for a couple -X options.
The output of --help has some lines that are too wide, or don’t follow the order of the man page.

These problems are taken out of GH-90300 so that there can be separate PRs and approval for their fixes.

Hints from issue discussion:

Commit message: keep long option at the end of help text

Patch to review:
diff --git a/Misc/python.man b/Misc/python.man
index 69dab58a9aac26..c6628fe75f40ff 100644
--- a/Misc/python.man
+++ b/Misc/python.man
@@ -69,10 +69,10 @@ python \- an interpreted, interactive, object-oriented programming language
 .B \-x
 ]
 [
-[
 .B \-X
 .I option
 ]
+[
 .B \-?
 ]
 .br
@@ -310,7 +310,8 @@ Set implementation specific option. The following options are available:
         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 -W default
-           * Install debug hooks on memory allocators: see the PyMem_SetupDebugHooks() C function
+           * 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
@@ -321,7 +322,19 @@ Set implementation specific option. The following options are available:
         otherwise activate automatically). See PYTHONUTF8 for more details
 
     -X pycache_prefix=PATH: enable writing .pyc files to a parallel tree rooted at the
-         given directory instead of to the code tree.
+        given directory instead of to the code tree.
+
+    -X warn_default_encoding: enable opt-in EncodingWarning for 'encoding=None'
+
+    -X no_debug_ranges: 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.
+
+    -X frozen_modules=[on|off]: whether or not frozen modules should be used
+       The default is "on" (or "off" if you are running a local build).
+
 .TP
 .B \-x
 Skip the first line of the source.  This is intended for a DOS
diff --git a/Python/initconfig.c b/Python/initconfig.c
index a623973f953734..0011c31a56fd12 100644
--- a/Python/initconfig.c
+++ b/Python/initconfig.c
@@ -38,7 +38,7 @@ Options and arguments (and corresponding environment variables):\n\
 -d     : turn on parser debugging output (for experts only, only works on\n\
          debug builds); also PYTHONDEBUG=x\n\
 -E     : ignore PYTHON* environment variables (such as PYTHONPATH)\n\
--h     : print this help message and exit (also --help)\n\
+-h     : print this help message and exit (also --help or -?)\n\
 ";
 static const char usage_2[] = "\
 -i     : inspect interactively after running script; forces a prompt even\n\
@@ -65,7 +65,6 @@ static const char usage_3[] = "\
          also PYTHONWARNINGS=arg\n\
 -x     : skip first line of source, allowing use of non-Unix forms of #!cmd\n\
 -X opt : set implementation-specific option. The following options are available:\n\
-\n\
          -X faulthandler: enable faulthandler\n\
          -X showrefcount: output the total reference count and number of used\n\
              memory blocks when the program finishes or after each statement in the\n\
@@ -82,7 +81,8 @@ static const char usage_3[] = "\
              checks which are too expensive to be enabled by default. Effect of the\n\
              developer mode:\n\
                 * Add default warning filter, as -W default\n\
-                * Install debug hooks on memory allocators: see the PyMem_SetupDebugHooks() C function\n\
+                * Install debug hooks on memory allocators: see the PyMem_SetupDebugHooks()\n\
+                  C function\n\
                 * Enable the faulthandler module to dump the Python traceback on a crash\n\
                 * Enable asyncio debug mode\n\
                 * Set the dev_mode attribute of sys.flags to True\n\
@@ -100,9 +100,8 @@ static const char usage_3[] = "\
             when the interpreter displays tracebacks.\n\
          -X frozen_modules=[on|off]: whether or not frozen modules should be used.\n\
             The default is \"on\" (or \"off\" if you are running a local build).\n\
-\n\
 --check-hash-based-pycs always|default|never:\n\
-    control how Python invalidates hash-based .pyc files\n\
+         control how Python invalidates hash-based .pyc files\n\
 ";
 static const char usage_4[] = "\
 file   : program read from script file\n\
@@ -141,7 +140,7 @@ static const char usage_6[] =
 "PYTHONNODEBUGRANGES: If this variable is set, it disables the inclusion of the \n"
 "   tables mapping extra location information (end line, start column offset \n"
 "   and end column offset) to every instruction in code objects. This is useful \n"
-"   when smaller cothe de objects and pyc files are desired as well as suppressing the \n"
+"   when smaller code objects and pyc files are desired as well as suppressing the \n"
 "   extra visual location indicators when the interpreter displays tracebacks.\n";
 
 #if defined(MS_WINDOWS)


Code review comments:
diff_hunk: @@ -38,7 +38,7 @@ Options and arguments (and corresponding environment variables):\n\
 -d     : turn on parser debugging output (for experts only, only works on\n\
          debug builds); also PYTHONDEBUG=x\n\
 -E     : ignore PYTHON* environment variables (such as PYTHONPATH)\n\
--h     : print this help message and exit (also --help)\n\
+-h     : print this help message and exit (also --help or -?)\n\
path: Python/initconfig.c
text: @author:
```suggestion
-h     : print this help message and exit (also -? or --help)\n\
```