gh-76303: Improve documentation of the -x command line option (GH-155559)

serhiy-storchaka · RoryGlenn · brianschubert · web-flow · commit 4b04d5abcd84 · 2026-08-11T17:45:45.000+03:00
Expand the documentation for the -x command-line option to explain its
purpose and usage for turning Python scripts into Windows batch files,
with examples of batch file header lines.

Co-authored-by: Rory Glenn &lt;glennrory@gmail.com&gt;
Co-authored-by: Brian Schubert &lt;brianm.schubert@gmail.com&gt;
diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst
@@ -519,7 +519,25 @@ Miscellaneous options
 .. option:: -x
 
    Skip the first line of the source, allowing use of non-Unix forms of
-   ``#!cmd``.  This is intended for a DOS specific hack only.
+   ``#!cmd``.
+
+   This can be used to turn a Python script into a Windows batch file.
+   Similarly to adding a shebang line and setting the executable bit on Unix,
+   the extension of the Python script can be changed to ``.bat`` and the
+   following line can be added at the start of the script:
+
+   .. code-block:: batch
+
+      @py -x "%~f0" %* & exit /b
+
+   Or, to specify the path to the Python interpreter explicitly:
+
+   .. code-block:: batch
+
+      @"C:\Path\to\python.exe" -x "%~f0" %* & exit /b
+
+   Unlike a shebang line which is a Python comment, this line is not valid
+   Python syntax, and the :option:`-x` option is needed to skip it.
 
 
 .. option:: -X
