Package: python3.11-minimal
Version: 3.11.9-1
Severity: minor
Tags: patch
Dear Maintainer,
here are some notes and editorial fixes for the manual.
The patch is in the attachment.
-.-
The difference between the formatted outputs can be seen with:
nroff -man <file1> > <out1>
nroff -man <file2> > <out2>
diff -u <out1> <out2>
and for groff, using
"printf '%s\n%s\n' '.kern 0' '.ss 12 0' | groff -man -Z - "
instead of "nroff -man"
Add the option "-t", if the file contains a table.
Read the output of "diff -u" with "less -R" or similar.
-.-.
If "man" (man-db) is used to check the manual for warnings,
the following must be set:
The option "-warnings=w"
The environmental variable:
export MAN_KEEP_STDERR=yes (or any non-empty value)
or
(produce only warnings):
export MANROFFOPT="-ww -z"
export MAN_KEEP_STDERR=yes (or any non-empty value)
-.-.
Output from "mandoc -T lint python3.11.1": (possibly shortened list)
mandoc: python3.11.1:1:2: WARNING: missing date, using "": TH
mandoc: python3.11.1:170:2: WARNING: line scope broken: TP breaks TP
mandoc: python3.11.1:183:85: STYLE: input text line longer than 80 bytes: Run
Python in isolat...
mandoc: python3.11.1:208:81: STYLE: input text line longer than 80 bytes: as
the current direc...
-.-.
Change two HYPHEN-MINUSES (code 0x2D) to an em-dash (\(em),
if one is intended. An en-dash is usually surrounded by a space,
while an em-dash is used without spaces.
"man" (1 byte characters in input) transforms an en-dash (\(en) to one
HYPHEN-MINUS,
and an em-dash to two HYPHEN-MINUSES without considering the space
around it.
If "--" are two single "-" (end of options) then use "\-\-".
python3.11.1:80:.B \--check-hash-based-pycs
python3.11.1:89:.B \--help
python3.11.1:92:.B \--help-env
python3.11.1:95:.B \--help-xoptions
python3.11.1:98:.B \--help-all
python3.11.1:607:\fB\--with-pydebug\fP build option.
-.-.
Mark a full stop (.) and the exclamation mark (!) with "\&",
if it does not mean an end of a sentence.
This is a preventive action,
the paragraph could be reshaped, e.g., after changes.
When typing, one does not always notice when the line wraps after the
period.
There are too many examples of input lines in manual pages,
that end with an abbreviation point.
This marking is robust, and independent of the position on the line.
It corresponds to "\ " in TeX, and to "@:" in Texinfo.
144:and comparing bytes/bytearray with str. (-bb: issue errors)
-.-.
Use the correct macro for the font change of a single argument or
split the argument into two.
265:.IB action:message:category:module:lineno
509:.IB errorhandler
511:.IB errorhandler
546:.IR malloc
556:.IR pymalloc_debug
578:.IB PYTHONTRACEMALLOC=1
594:.IR site-packages
-.-.
Change a HYPHEN-MINUS (code 0x2D) to a minus(-dash) (\-),
if it
is in front of a name for an option,
is a symbol for standard input,
is a single character used to indicate an option,
or is in the NAME section (man-pages(7)).
N.B. - (0x2D), processed as a UTF-8 file, is changed to a hyphen
(0x2010, groff \[u2010] or \[hy]) in the output.
80:.B \--check-hash-based-pycs
89:.B \--help
92:.B \--help-env
95:.B \--help-xoptions
98:.B \--help-all
144:and comparing bytes/bytearray with str. (-bb: issue errors)
251: -Wdefault # Warn once per call location
252: -Werror # Convert to exceptions
253: -Walways # Warn every time
254: -Wmodule # Warn once per calling module
255: -Wonce # Warn once per Python process
256: -Wignore # Never warn
260:.B -Wi
262:.B -Wignore .
269:.B -W ignore::DeprecationWarning
298:.B -W
301:.B -W
315: -X faulthandler: enable faulthandler
317: -X showrefcount: output the total reference count and number of used
321: -X tracemalloc: start tracing Python memory allocations using the
323: traceback of a trace. Use -X tracemalloc=NFRAME to start tracing
with a
326: -X importtime: show how long each import takes. It shows module name,
329: application. Typical usage is python3 -X importtime -c 'import
asyncio'
331: -X dev: enable CPython's "development mode", introducing additional
runtime
335: * Add default warning filter, as -W default
343: -X utf8: enable UTF-8 mode for operating system interfaces, overriding
the default
344: locale-aware mode. -X utf8=0 explicitly disables UTF-8 mode (even
when it would
347: -X pycache_prefix=PATH: enable writing .pyc files to a parallel tree
rooted at the
350: -X warn_default_encoding: enable opt-in EncodingWarning for
'encoding=None'
352: -X no_debug_ranges: disable the inclusion of the tables mapping extra
location
358: -X frozen_modules=[on|off]: whether or not frozen modules should be
used.
361: -X int_max_str_digits=number: limit the size of int<->str conversions.
403:.I '-c'.
607:\fB\--with-pydebug\fP build option.
-.-.
Wrong distance between sentences.
Separate the sentences and subordinate clauses; each begins on a new
line. See man-pages(7) ("Conventions for source file layout") and
"info groff" ("Input Conventions").
The best procedure is to always start a new sentence on a new line,
at least, if you are typing on a computer.
Remember coding: Only one command ("sentence") on each (logical) line.
E-mail: Easier to quote exactly the relevant lines.
Generally: Easier to edit the sentence.
Patches: Less unaffected text.
Search for two adjacent words is easier, when they belong to the same line,
and the same phrase.
The amount of space between sentences in the output can then be
controlled with the ".ss" request.
N.B
The number of lines affected is too large to be in the patch.
140:files on import. See also PYTHONDONTWRITEBYTECODE.
144:and comparing bytes/bytearray with str. (-bb: issue errors)
183:Run Python in isolated mode. This also implies \fB\-E\fP, \fB\-P\fP and
\fB\-s\fP. In
185:site-packages directory. All PYTHON* environment variables are ignored, too.
194:file as a script. This terminates the option list (following options
208:as the current directory, the script's directory or an empty string. See
also the
212:Do not print the version and copyright messages. These messages are
244:Warning control. Python's warning machinery by default prints warning
messages
259:them to the appropriate action name. For example,
267:Empty fields match all values; trailing empty fields may be omitted. For
284:field matches the warning category (ex: "DeprecationWarning"). This must be
a
300:for the last matching option is performed. Invalid
313:Set implementation-specific option. The following options are available:
319: interactive interpreter. This only works on debug builds
322: tracemalloc module. By default, only the most recent frame is
stored in a
323: traceback of a trace. Use -X tracemalloc=NFRAME to start tracing
with a
326: -X importtime: show how long each import takes. It shows module name,
328: nested imports). Note that its output may be broken in
multi-threaded
329: application. Typical usage is python3 -X importtime -c 'import
asyncio'
332: checks which are too expensive to be enabled by default. It will
not be
334: only emitted when an issue is detected. Effect of the developer
mode:
344: locale-aware mode. -X utf8=0 explicitly disables UTF-8 mode (even
when it would
345: otherwise activate automatically). See PYTHONUTF8 for more details
354: instruction in code objects. This is useful when smaller code
objects and pyc
452:directory or an empty string. See also the \fB\-P\fP option.
490:the \fB\-O\fP option. If set to an integer, it is equivalent to
494:the \fB\-d\fP option. If set to an integer, it is equivalent to
510:part is optional and has the same meaning as in str.encode. For stderr, the
521:the \fB\-v\fP option. If set to an integer, it is equivalent to
544:Set the Python memory allocators and/or install debug hooks. The available
557:and the debug hooks are automatically used. Otherwise, the default is
577:traceback of a trace. For example,
590:will be set to its value instead of the value got through the C runtime.
Only
599:show how long each import takes. This is exactly equivalent to setting
602:If this environment variable is set to 0, it disables the default debugger.
It
-.-.
Split lines longer than 80 characters into two or more lines.
Appropriate break points are the end of a sentence and a subordinate
clause; after punctuation marks.
python3.11.1: line 183 length 85
Run Python in isolated mode. This also implies \fB\-E\fP, \fB\-P\fP and
\fB\-s\fP. In
python3.11.1: line 208 length 81
as the current directory, the script's directory or an empty string. See also
the
-.-
Remove reverse slash (\) in front of a period (.) that is to be printed
as such, and can not come a control character in the first column of a line.
This is a sign, that the man page was transformed from another source
file with a program, whose name is NOT mentioned in a comment.
596:.IR "python setup\.py install \-\-user" .
-.-.
Protect a period (.) or an apostrophe (') with '\&' from becoming a
control character, if it could end up at the start of a line
(by splitting the line into more lines).
152:Configure how Python evaluates the up-to-dateness of hash-based .pyc files.
200:adding .opt-1 before the .pyc extension.
204:compiled (bytecode) files by adding .opt-2 before the .pyc extension.
329: application. Typical usage is python3 -X importtime -c 'import
asyncio'
347: -X pycache_prefix=PATH: enable writing .pyc files to a parallel tree
rooted at the
350: -X warn_default_encoding: enable opt-in EncodingWarning for
'encoding=None'
-.-.
Split a punctuation from a single argument, if a two-font macro is meant
403:.I '-c'.
-.-.
Change a HYPHEN-MINUS (code 0x55, 2D) to a dash
(\-, minus) if it matches "[[:alph:]]-[[:alpha:]]" in the name of an
option).
Facilitates the copy and paste of an option in UTF-8 text.
Is not needed in ordinary words like "mother-in-law", that are not
copied and pasted to a command line (which needs ASCII code)
80:.B \--check-hash-based-pycs
92:.B \--help-env
95:.B \--help-xoptions
98:.B \--help-all
151:.BI "\-\-check-hash-based-pycs " mode
152:Configure how Python evaluates the up-to-dateness of hash-based .pyc files.
607:\fB\--with-pydebug\fP build option.
-.-.
Output from "test-groff -b -mandoc -dAD=l -rF0 -rHY=0 -t -w w -z -K utf8":
an.tmac:<stdin>:171: warning: cannot nest .TP or .TQ inside .TP; supply a tag
-- System Information:
Debian Release: trixie/sid
APT prefers testing-proposed-updates
APT policy: (500, 'testing-proposed-updates'), (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.7.12-amd64 (SMP w/2 CPU threads; PREEMPT)
Locale: LANG=is_IS.iso88591, LC_CTYPE=is_IS.iso88591 (charmap=ISO-8859-1),
LANGUAGE not set
Shell: /bin/sh linked to /usr/bin/dash
Init: sysvinit (via /sbin/init)
Versions of packages python3.11-minimal depends on:
ii libc6 2.38-11
ii libexpat1 2.6.2-1
ii libpython3.11-minimal 3.11.9-1
ii zlib1g 1:1.3.dfsg+really1.3.1-1
Versions of packages python3.11-minimal recommends:
ii python3.11 3.11.9-1
Versions of packages python3.11-minimal suggests:
ii binfmt-support 2.2.2-7
-- no debconf information
--- python3.11.1 2024-05-26 03:32:27.183958008 +0000
+++ python3.11.1.new 2024-05-26 22:10:36.807236711 +0000
@@ -73,11 +73,11 @@ python \- an interpreted, interactive, o
.I option
]
[
-.B \-?
+.B \-?\&
]
.br
[
-.B \--check-hash-based-pycs
+.B \-\-check\-hash\-based\-pycs
.I default
|
.I always
@@ -86,16 +86,16 @@ python \- an interpreted, interactive, o
]
.br
[
-.B \--help
+.B \-\-help
]
[
-.B \--help-env
+.B \-\-help\-env
]
[
-.B \--help-xoptions
+.B \-\-help\-xoptions
]
[
-.B \--help-all
+.B \-\-help\-all
]
.br
[
@@ -141,7 +141,8 @@ files on import. See also PYTHONDONTWRIT
.TP
.B \-b
Issue warnings about str(bytes_instance), str(bytearray_instance)
-and comparing bytes/bytearray with str. (-bb: issue errors)
+and comparing bytes/bytearray with str.
+(\-bb: issue errors)
.TP
.BI "\-c " command
Specify the command to execute (see next section).
@@ -149,7 +150,7 @@ This terminates the option list (followi
arguments to the command).
.TP
.BI "\-\-check-hash-based-pycs " mode
-Configure how Python evaluates the up-to-dateness of hash-based .pyc files.
+Configure how Python evaluates the up-to-dateness of hash-based \&.pyc files.
.TP
.B \-d
Turn on parser debugging output (for expert only, depending on
@@ -159,7 +160,7 @@ compilation options).
Ignore environment variables like PYTHONPATH and PYTHONHOME that modify
the behavior of the interpreter.
.TP
-.B \-h ", " \-? ", "\-\-help
+.BR \-h ", " \-? ", " \-\-help
Prints the usage for the interpreter executable and exits.
.TP
.B "\-\-help\-env"
@@ -168,7 +169,6 @@ Prints help about Python-specific enviro
.B "\-\-help\-xoptions"
Prints help about implementation-specific \fB\-X\fP options and exits.
.TP
-.TP
.B "\-\-help\-all"
Prints complete usage information and exits.
.TP
@@ -180,9 +180,11 @@ useful to inspect global variables or a
raises an exception.
.TP
.B \-I
-Run Python in isolated mode. This also implies \fB\-E\fP, \fB\-P\fP and
\fB\-s\fP. In
-isolated mode sys.path contains neither the script's directory nor the user's
-site-packages directory. All PYTHON* environment variables are ignored, too.
+Run Python in isolated mode. This also implies \fB\-E\fP, \fB\-P\fP and
+\fB\-s\fP.
+In isolated mode sys.path contains neither the script's directory nor the
+user's site-packages directory.
+All PYTHON* environment variables are ignored, too.
Further restrictions may be imposed to prevent the user from injecting
malicious code.
.TP
@@ -197,15 +199,16 @@ are passed as arguments to the module).
.B \-O
Remove assert statements and any code conditional on the value of
__debug__; augment the filename for compiled (bytecode) files by
-adding .opt-1 before the .pyc extension.
+adding \&.opt-1 before the \&.pyc extension.
.TP
.B \-OO
-Do \fB-O\fP and also discard docstrings; change the filename for
-compiled (bytecode) files by adding .opt-2 before the .pyc extension.
+Do \fB\-O\fP and also discard docstrings; change the filename for
+compiled (bytecode) files by adding \&.opt-2 before the \&.pyc extension.
.TP
.B \-P
Don't automatically prepend a potentially unsafe path to \fBsys.path\fP such
-as the current directory, the script's directory or an empty string. See also
the
+as the current directory, the script's directory or an empty string.
+See also the
\fBPYTHONSAFEPATH\fP environment variable.
.TP
.B \-q
@@ -235,7 +238,7 @@ twice, print a message for each file tha
searching for a module. Also provides information on module cleanup
at exit.
.TP
-.B \-V ", " \-\-version
+.BR \-V ", " \-\-version
Prints the Python version number of the executable and exits. When given
twice, print more information about the build.
@@ -248,25 +251,25 @@ to
The simplest settings apply a particular action unconditionally to all warnings
emitted by a process (even those that are otherwise ignored by default):
- -Wdefault # Warn once per call location
- -Werror # Convert to exceptions
- -Walways # Warn every time
- -Wmodule # Warn once per calling module
- -Wonce # Warn once per Python process
- -Wignore # Never warn
+ \-Wdefault # Warn once per call location
+ \-Werror # Convert to exceptions
+ \-Walways # Warn every time
+ \-Wmodule # Warn once per calling module
+ \-Wonce # Warn once per Python process
+ \-Wignore # Never warn
The action names can be abbreviated as desired and the interpreter will resolve
them to the appropriate action name. For example,
-.B -Wi
+.B \-Wi
is the same as
-.B -Wignore .
+.B \-Wignore .
The full form of argument is:
-.IB action:message:category:module:lineno
+.I action:message:category:module:lineno
Empty fields match all values; trailing empty fields may be omitted. For
example
-.B -W ignore::DeprecationWarning
+.B \-W ignore::DeprecationWarning
ignores all DeprecationWarning warnings.
The
@@ -295,10 +298,10 @@ field matches the line number, where zer
equivalent to an omitted line number.
Multiple
-.B -W
+.B \-W
options can be given; when a warning matches more than one option, the action
for the last matching option is performed. Invalid
-.B -W
+.B \-W
options are ignored (though, a warning message is printed about invalid options
when the first warning is issued).
@@ -311,56 +314,91 @@ a regular expression on the warning mess
.TP
.BI "\-X " option
Set implementation-specific option. The following options are available:
-
- -X faulthandler: enable faulthandler
-
- -X showrefcount: 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
-
- -X tracemalloc: 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
-
- -X importtime: 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 python3 -X importtime -c 'import asyncio'
-
- -X dev: 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 -W default
- * 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
-
- -X utf8: enable UTF-8 mode for operating system interfaces, overriding the
default
- locale-aware mode. -X utf8=0 explicitly disables UTF-8 mode (even when
it would
- 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.
-
- -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).
-
- -X int_max_str_digits=number: 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.
+.
+.nr Xindent \w'Set '
+.RS \n[Xindent]u+\n[IN]u
+\#.IP \-X 2m\" 2m is minimum
+.IP \-X 3n
+faulthandler: enable faulthandler
+.
+.\".IP \-X 2m
+.IP \-X 3n
+showrefcount: 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
+.
+.IP \-X 3n
+tracemalloc: 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
+.
+.IP \-X 3n
+importtme: 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 python3 \-X importtime \-c 'import asyncio'
+.
+.IP \-X 3
+dev: 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 3n
+.IP * 2n
+Add default warning filter, as \-W default.
+Install debug hooks on memory allocators: see the PyMem_SetupDebugHooks()
+C function
+.
+.IP * 2n
+Enable the faulthandler module to dump the Python traceback on a crash
+.
+.IP * 2n
+Enable asyncio debug mode
+.
+.IP * 2
+Set the dev_mode attribute of sys.flags to True
+.
+.IP * 2
+io.IOBase destructor logs close() exceptions
+.RE
+.IP \-X 3
+utf8: enable UTF-8 mode for operating system interfaces,
+overriding the default locale-aware mode.
+.IP \-X 3
+utf8=0 explicitly disables UTF-8 mode (even when it would
+otherwise activate automatically).
+See PYTHONUTF8 for more details
+.
+.IP \-X 3
+pycache_prefix=PATH: enable writing \&.pyc files to a parallel tree
+rooted at the given directory instead of to the code tree.
+.
+.IP \-X 3
+warn_default_encoding: enable opt-in EncodingWarning for
+\&'encoding=None'
+.
+.IP \-X 3
+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.
+.
+.IP \-X 3
+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).
+.
+.IP \-X 3
+int_max_str_digits=number: 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.
+.RE
.TP
.B \-x
@@ -400,7 +438,7 @@ is an empty string; if
is used,
.I sys.argv[0]
contains the string
-.I '-c'.
+.RI ' \-c '.
Note that options interpreted by the Python interpreter itself
are not placed in
.IR sys.argv .
@@ -506,9 +544,9 @@ If this is set before running the interp
for stdin/stdout/stderr, in the syntax
.IB encodingname ":" errorhandler
The
-.IB errorhandler
+.I errorhandler
part is optional and has the same meaning as in str.encode. For stderr, the
-.IB errorhandler
+.I errorhandler
part is ignored; the handler will always be \'backslashreplace\'.
.IP PYTHONNOUSERSITE
If this is set to a non-empty string it is equivalent to specifying the
@@ -543,7 +581,7 @@ A value of 0 disables the limit. Conver
.IP PYTHONMALLOC
Set the Python memory allocators and/or install debug hooks. The available
memory allocators are
-.IR malloc
+.I malloc
and
.IR pymalloc .
The available debug hooks are
@@ -553,7 +591,7 @@ and
.IR pymalloc_debug .
.IP
When Python is compiled in debug mode, the default is
-.IR pymalloc_debug
+.I pymalloc_debug
and the debug hooks are automatically used. Otherwise, the default is
.IR pymalloc .
.IP PYTHONMALLOCSTATS
@@ -575,7 +613,7 @@ Python memory allocations using the trac
.IP
The value of the variable is the maximum number of frames stored in a
traceback of a trace. For example,
-.IB PYTHONTRACEMALLOC=1
+.I PYTHONTRACEMALLOC=1
stores only the most recent frame.
.IP PYTHONFAULTHANDLER
If this environment variable is set to a non-empty string,
@@ -590,10 +628,10 @@ If this environment variable is set,
will be set to its value instead of the value got through the C runtime. Only
works on Mac OS X.
.IP PYTHONUSERBASE
-Defines the user base directory, which is used to compute the path of the user
-.IR site-packages
+Defines the user base directory, which is used to compute the path of the
user's
+.I site-packages
directory and Distutils installation paths for
-.IR "python setup\.py install \-\-user" .
+.IR "python setup.py install \-\-user" .
.IP PYTHONPROFILEIMPORTTIME
If this environment variable is set to a non-empty string, Python will
show how long each import takes. This is exactly equivalent to setting
@@ -604,7 +642,7 @@ can be set to the callable of your debug
.SS Debug-mode variables
Setting these variables only has an effect in a debug build of Python, that is,
if Python was configured with the
-\fB\--with-pydebug\fP build option.
+\fB\-\-with\-pydebug\fP build option.
.IP PYTHONTHREADDEBUG
If this environment variable is set, Python will print threading debug info.
The feature is deprecated in Python 3.10 and will be removed in Python 3.12.
