Package: codespell
Version: 2.4.1-1
Severity: minor
Tags: patch
Dear Maintainer,
>From "/usr/share/doc/debian/bug-reporting.txt.gz":
Don't file bugs upstream
If you file a bug in Debian, don't send a copy to the upstream software
maintainers yourself, as it is possible that the bug exists only in
Debian. If necessary, the maintainer of the package will forward the
bug upstream.
-.-
I do not send reports upstream if I have to get an account there.
The Debian maintainers have one already.
If I get a negative (or no) response from upstream, I send henceforth
bugs to Debian.
-.-
* What led up to the situation?
Checking for defects with a new version
test-[g|n]roff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=0 -ww -z < "man page"
[Use
grep -n -e ' $' -e '\\~$' -e ' \\f.$' -e ' \\"' <file>
to find (most) trailing spaces.]
["test-groff" is a script in the repository for "groff"; is not shipped]
(local copy and "troff" slightly changed by me).
[The fate of "test-nroff" was decided in groff bug #55941.]
* What was the outcome of this action?
Mangled paragraphs.
* What outcome did you expect instead?
Better order of paragraphs.
-.-
General remarks and further material, if a diff-file exist, are in the
attachments.
-- System Information:
Debian Release: forky/sid
APT prefers testing
APT policy: (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.17.13+deb14-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 codespell depends on:
ii python3 3.13.7-1+b1
ii python3-chardet 5.2.0+dfsg-2
codespell recommends no packages.
codespell suggests no packages.
-- no debconf information
Input file is codespell.1
Output from "mandoc -T lint codespell.1": (shortened list)
2 STYLE: input text line longer than 80 bytes:
1 WARNING: skipping paragraph macro: PP after SH
-.-.
Input file is codespell.1
Show if help2man generated this.
1:.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.49.3.
Latest version in Debian testing: GNU help2man 1.49.3
-.-.
Add a "\&" (or a comma (Oxford comma)) after an abbreviation
or use English words
(man-pages(7)).
Abbreviation points should be marked as such and protected against being
interpreted as an end of sentence, if they are not, and that independent
of the current place on the line.
152:e.g. use 3 for levels 1+2, 7 for 1+2+4, 23 for
-.-.
Wrong distance (not two spaces) between sentences in the input file.
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.
Mark a final abbreviation point as such by suffixing it with "\&".
Some sentences (etc.) do not begin on a new line.
Split (sometimes) lines after a punctuation mark; before a conjunction.
Lines with only one (or two) space(s) between sentences could be split,
so latter sentences begin on a new line.
Use
#!/usr/bin/sh
sed -e '/^\./n' \
-e 's/\([[:alpha:]]\)\. */\1.\n/g' $1
to split lines after a sentence period.
Check result with the difference between the formatted outputs.
See also the attachment "general.bugs"
[List of affected lines removed.]
6:\fBcodespell\fR [OPTIONS] [file1 file2 ... fileN]
46:contain spelling corrections. If this flag is not
52:include (when "\-D \-" or no "\-D" is passed). Current
73:ignore by treating as whitespace. When writing regular
74:expressions, consider ensuring there are boundary nonword chars, e.g.,
"\ebmatch\eb". Defaults to
79:may span multi\-line regions. The regex is run with
80:re.DOTALL. For example to allow skipping of regions of
83:*\en.*# codespell:ignore\-end *\en'. Defaults to
88:ignored by codespell. Files must contain 1 word per
89:line. Words are case sensitive based on how they are
94:codespell. Words are case sensitive based on how they
99:codespell in URIs and emails only. Words are case
101:dictionary file. If set to "*", all misspelling in
105:regular expression that is used to find words. By
108:words. This option cannot be specified together with
113:emails. A default expression is provided.
122:comma\-separated list of files to skip. It accepts
123:globs as well. E.g.: if you want codespell to skip
128:ignore whole lines that match those in the commaseparated list of files
EXCLUDE. The lines in these
152:e.g. use 3 for levels 1+2, 7 for 1+2+4, 23 for
153:1+2+4+16, etc. The default mask is 34.
156:use chardet to detect the encoding of each file. This
-.-.
Split lines longer than 80 characters (fill completely
an A4 sized page line on a terminal)
into two or more lines.
Appropriate break points are the end of a sentence and a subordinate
clause; after punctuation marks.
Add "\:" to split the string for the output, "\<newline>" in the source.
Line 74, length 97
expressions, consider ensuring there are boundary nonword chars, e.g.,
"\ebmatch\eb". Defaults to
Line 128, length 99
ignore whole lines that match those in the commaseparated list of files
EXCLUDE. The lines in these
Longest line is number 128 with 99 characters
-.-.
Use \(en (en-dash) for a dash at the beginning (end) of a line,
or between space characters,
not a minus (\-) or a hyphen (-), except in the NAME section.
codespell.1:54:\- 'clear' for unambiguous errors
codespell.1:55:\- 'rare' for rare (but valid) words that are likely to
codespell.1:58:\- 'informal' for making informal words more formal
codespell.1:59:\- 'usage' for replacing phrasing with recommended
codespell.1:62:\- 'code' for words from code and/or mathematics that
codespell.1:67:\- 'names' for valid proper names that might be typos
codespell.1:68:\- 'en\-GB_to_en\-US' for corrections from en\-GB to en\-US
codespell.1:133:\- 0: no interactivity.
codespell.1:134:\- 1: ask for confirmation.
codespell.1:135:\- 2: ask user to choose one fix when more than one is
codespell.1:138:\- 3: both 1 and 2
codespell.1:142:\- 0: print all messages.
codespell.1:143:\- 1: disable warnings about wrong encoding.
codespell.1:144:\- 2: disable warnings about binary files.
codespell.1:145:\- 4: omit warnings about automatic fixes that were
codespell.1:148:\- 8: don't print anything for non\-automatic fixes.
codespell.1:149:\- 16: don't print the list of fixed files.
codespell.1:150:\- 32: don't print configuration files.
-.-.
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
codespell.1:52:include (when "\-D \-" or no "\-D" is passed). Current
codespell.1:55:\- 'rare' for rare (but valid) words that are likely to
-.-.
Remove quotes when there is a printable
but no space character between them
and the quotes are not for emphasis (markup),
for example as an argument to a macro.
codespell.1:2:.TH CODESPELL "1" "February 2025" "codespell 2.4.1" "User
Commands"
codespell.1:27:.SS "options:"
-.-.
Use "\-" instead of "-" in web addresses.
189:https://github.com/codespell-project/codespell
-.-.
Add "\&" after an ellipsis, when it does not end a sentence.
6:\fBcodespell\fR [OPTIONS] [file1 file2 ... fileN]
22:[files ...]
-.-.
Additionally:
Remove '.PP' after a '.SH', as it has no effect.
Use '.IP' (indented paragraph) for items that start with \-<n> (<n> is a
number)
-.-
Generally:
Split (sometimes) lines after a punctuation mark; before a conjunction.
--- codespell.1 2026-01-29 03:18:24.533470445 +0000
+++ codespell.1.new 2026-01-29 03:59:34.191420133 +0000
@@ -3,9 +3,8 @@
.SH NAME
codespell \- detect spelling mistakes in source code
.SH SYNOPSIS
-\fBcodespell\fR [OPTIONS] [file1 file2 ... fileN]
+\fBcodespell\fR [OPTIONS] [file1 file2 \&...\& fileN]
.SH DESCRIPTION
-.PP
codespell is designed to find and fix common misspellings in text files.
It is designed primarily for checking misspelled words in source code,
but it can be used with other files as well.
@@ -51,21 +50,24 @@ used.
comma\-separated list of builtin dictionaries to
include (when "\-D \-" or no "\-D" is passed). Current
options are:
+.IP
\- 'clear' for unambiguous errors
+.IP
\- 'rare' for rare (but valid) words that are likely to
-.TP
be errors
+.IP
\- 'informal' for making informal words more formal
+.IP
\- 'usage' for replacing phrasing with recommended
-.TP
terms
+.IP
\- 'code' for words from code and/or mathematics that
-.TP
are likely to be typos in other contexts (such as
uint)
-.TP
+.IP
\- 'names' for valid proper names that might be typos
-\- 'en\-GB_to_en\-US' for corrections from en\-GB to en\-US
+.IP
+\- 'en\-GB_to_en\-US' for corrections from en\-GB to en\-US.
The default is 'clear,rare'.
.TP
\fB\-\-ignore\-regex\fR IGNORE_REGEX
@@ -130,8 +132,11 @@ files should match the to\-be\-excluded
.TP
\fB\-i\fR, \fB\-\-interactive\fR MODE
set interactive mode when writing changes:
+.IP
\- 0: no interactivity.
+.IP
\- 1: ask for confirmation.
+.IP
\- 2: ask user to choose one fix when more than one is
.TP
available.
@@ -139,17 +144,23 @@ available.
.TP
\fB\-q\fR, \fB\-\-quiet\-level\fR LEVEL
bitmask that allows suppressing messages:
+.IP
\- 0: print all messages.
+.IP
\- 1: disable warnings about wrong encoding.
+.IP
\- 2: disable warnings about binary files.
+.IP
\- 4: omit warnings about automatic fixes that were
-.TP
disabled in the dictionary.
+.IP
\- 8: don't print anything for non\-automatic fixes.
+.IP
\- 16: don't print the list of fixed files.
+.IP
\- 32: don't print configuration files.
As usual with bitmasks, these levels can be combined;
-e.g. use 3 for levels 1+2, 7 for 1+2+4, 23 for
+e.g., use 3 for levels 1+2, 7 for 1+2+4, 23 for
1+2+4+16, etc. The default mask is 34.
.TP
\fB\-e\fR, \fB\-\-hard\-encoding\-detection\fR
Any program (person), that produces man pages, should check the output
for defects by using (both groff and nroff)
[gn]roff -mandoc -t -ww -b -z -K utf8 <man page>
To find trailing space use
grep -n -e ' $' -e ' \\f.$' -e ' \\"' <man page>
The same goes for man pages that are used as an input.
-.-
For a style guide use
mandoc -T lint
-.-
For general input conventions consult the man page "nroff(7)" (item
"Input conventions") or the Texinfo manual about the same item.
-.-
Any "autogenerator" should check its products with the above mentioned
'groff', 'mandoc', and additionally with 'nroff ...'.
It should also check its input files for too long (> 80) lines.
This is just a simple quality control measure.
The "autogenerator" may have to be corrected to get a better man page,
the source file may, and any additional file may.
-.-
Common defects:
Not removing trailing spaces (in in- and output).
The reason for these trailing spaces should be found and eliminated.
"git" has a "tool" to point out whitespace,
see for example "git-apply(1)" and git-config(1)")
-.-
Not beginning each input sentence on a new line.
Line length and patch size should thus be reduced when that has been fixed.
The script "reportbug" uses 'quoted-printable' encoding when a line is
longer than 1024 characters in an 'ascii' file.
See man-pages(7), item "semantic newline".
-.-
The difference between the formatted output of the original
and patched file can be seen with:
nroff -mandoc <file1> > <out1>
nroff -mandoc <file2> > <out2>
diff -d -u <out1> <out2>
and for groff, using
\"printf '%s\n%s\n' '.kern 0' '.ss 12 0' | groff -mandoc -Z - \"
instead of 'nroff -mandoc'
Add the option '-t', if the file contains a table.
Read the output from 'diff -d -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 -b -z"
export MAN_KEEP_STDERR=yes (or any non-empty value)
-.-
