Package: python3-pygments
Version: 2.18.0+dfsg-1
Severity: minor
Tags: patch
* 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=10 -ww -z < "man
page"
[Use "groff -e ' $' <file>" to find 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?
an.tmac:<stdin>:1: style: .TH missing fourth argument; consider package/project
name and version (e.g., "groff 1.23.0")
an.tmac:<stdin>:8: misuse, warning: .RI is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument.
an.tmac:<stdin>:9: misuse, warning: .RI is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument.
an.tmac:<stdin>:12: misuse, warning: .RI is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument.
an.tmac:<stdin>:15: misuse, warning: .RI is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument.
an.tmac:<stdin>:18: misuse, warning: .RI is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument.
an.tmac:<stdin>:21: misuse, warning: .RI is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument.
an.tmac:<stdin>:24: misuse, warning: .RI is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument.
an.tmac:<stdin>:27: misuse, warning: .RI is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument.
an.tmac:<stdin>:35: style: 2 leading space(s) on input line
an.tmac:<stdin>:36: style: 2 leading space(s) on input line
an.tmac:<stdin>:37: style: 2 leading space(s) on input line
an.tmac:<stdin>:38: style: 2 leading space(s) on input line
an.tmac:<stdin>:39: style: 2 leading space(s) on input line
an.tmac:<stdin>:40: style: 2 leading space(s) on input line
* What outcome did you expect instead?
No output (no warnings).
-.-
General remarks and further material, if a diff-file exist, are in the
attachments.
-- System Information:
Debian Release: trixie/sid
APT prefers testing
APT policy: (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.12.6-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-pygments depends on:
ii python3 3.12.8-1
ii python3-pkg-resources 75.6.0-1
python3-pygments recommends no packages.
Versions of packages python3-pygments suggests:
pn python-pygments-doc <none>
pn ttf-bitstream-vera <none>
-- no debconf information
Input file is pygmentize.1
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>
The same goes for man pages that are used as an input.
For a style guide use
mandoc -T lint
-.-
So any 'generator' should check its products with the above mentioned
'groff', 'mandoc', and additionally with 'nroff ...'.
This is just a simple quality control measure.
The 'generator' may have to be corrected to get a better man page,
the source file may, and any additional file may.
Common defects:
Input text line longer than 80 bytes.
Not removing trailing spaces (in in- and output).
The reason for these trailing spaces should be found and eliminated.
Not beginning each input sentence on a new line.
Lines should thus be shorter.
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 -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 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 -b -z"
export MAN_KEEP_STDERR=yes (or any non-empty value)
-.-.
Output from "mandoc -T lint pygmentize.1": (shortened list)
4 input text line longer than 80 bytes
-.-.
Output from "test-groff -mandoc -t -ww -z pygmentize.1": (shortened list)
8 Use macro '.I' for one argument or split argument.
8 .RI is for at least 2 arguments, got 1
-.-.
Use the correct macro for the font change of a single argument or
split the argument into two.
21:.RI -C
-.-.
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.
8:.RI [-l\ \fI<lexer>\fP\ |\ -g]\ [-F\ \fI<filter>\fP[:\fI<options>\fP]]\ [-f\
\fI<formatter>\fP]
9:.RI [-O\ \fI<options>\fP]\ [-P\ \fI<option=value>\fP]\ [-o\
\fI<outfile>\fP]\ [\fI<infile>\fP]
12:.RI -S\ \fI<style>\fP\ -f\ \fI<formatter>\fP\ [-a\ \fI<arg>\fP]\ [-O\
\fI<options>\fP]\ [-P\ \fI<option=value>\fP]
15:.RI -L\ [\fI<which>\fP\ ...]
18:.RI -N\ \fI<filename>\fP
21:.RI -C
24:.RI -H\ \fI<type>\fP\ \fI<name>\fP
27:.RI -h\ |\ -V
57:-O after a colon (note: there must not be spaces around the colon).
70:options, e.g. "-O bg=light,python=cool". Which options are valid for which
75:This option adds lexer and formatter options like the -O option, but
76:you can only give one option per -P. That way, the option value may contain
77:commas and equals signs, which it can't with -O.
95:Like \fI-N\fP, but guess a lexer based on content read from standard input.
-.-.
Add a comma (or \&) after "e.g." and "i.e.", or use English words
(man-pages(7)).
Abbreviation points should be protected against being interpreted as
an end of sentence, if they are not, and that independent of the
current place on the line.
70:options, e.g. "-O bg=light,python=cool". Which options are valid for which
87:to list (e.g. "styles"), or omit it to list everything.
-.-.
Wrong distance 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 "\&".
40: * ... and it highlights even Brainfuck!
43:write the result to \fI<outfile>\fP. If no \fI<infile>\fP is given, stdin is
used.
48:Set the lexer name. If not given, the lexer is guessed from the extension of
the
56:Add a filter to the token stream. You can give options in the same way as for
61:Set the formatter name. If not given, it will be guessed from the extension
of
62:the output file name. If no output file is given, the terminal formatter
will be
66:Set output file. If not given, stdout is used.
70:options, e.g. "-O bg=light,python=cool". Which options are valid for which
76:you can only give one option per -P. That way, the option value may contain
86:List lexers, formatters, styles or filters. Set \fI<which>\fP to the thing
you want
87:to list (e.g. "styles"), or omit it to list everything.
-.-.
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.
Line 8, length 96
.RI [-l\ \fI<lexer>\fP\ |\ -g]\ [-F\ \fI<filter>\fP[:\fI<options>\fP]]\ [-f\
\fI<formatter>\fP]
Line 9, length 95
.RI [-O\ \fI<options>\fP]\ [-P\ \fI<option=value>\fP]\ [-o\ \fI<outfile>\fP]\
[\fI<infile>\fP]
Line 12, length 114
.RI -S\ \fI<style>\fP\ -f\ \fI<formatter>\fP\ [-a\ \fI<arg>\fP]\ [-O\
\fI<options>\fP]\ [-P\ \fI<option=value>\fP]
Line 43, length 82
write the result to \fI<outfile>\fP. If no \fI<infile>\fP is given, stdin is
used.
Line 80, length 88
Print out style definitions for style \fI<style>\fP and for formatter
\fI<formatter>\fP.
Line 86, length 83
List lexers, formatters, styles or filters. Set \fI<which>\fP to the thing you
want
Line 98, length 95
Print detailed help for the object \fI<name>\fP of type \fI<type>\fP, where
\fI<type>\fP is one
-.-.
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
pygmentize.1:49:input file name (this obviously doesn't work if the input is
stdin).
pygmentize.1:53:if this fails (this option works for highlighting standard
input).
pygmentize.1:57:-O after a colon (note: there must not be spaces around the
colon).
pygmentize.1:87:to list (e.g. "styles"), or omit it to list everything.
-.-.
Put a subordinate sentence (after a comma) on a new line.
31:of software such as forum systems, wikis or other applications that need to
43:write the result to \fI<outfile>\fP. If no \fI<infile>\fP is given, stdin is
used.
48:Set the lexer name. If not given, the lexer is guessed from the extension of
the
52:Attempt to guess the lexer from the file contents, or pass through as plain
text
61:Set the formatter name. If not given, it will be guessed from the extension
of
62:the output file name. If no output file is given, the terminal formatter
will be
66:Set output file. If not given, stdout is used.
69:With this option, you can give the lexer and formatter a comma-separated
list of
70:options, e.g. "-O bg=light,python=cool". Which options are valid for which
75:This option adds lexer and formatter options like the -O option, but
76:you can only give one option per -P. That way, the option value may contain
77:commas and equals signs, which it can't with -O.
87:to list (e.g. "styles"), or omit it to list everything.
91:take input or highlight anything. If no specific lexer can be found, "text"
95:Like \fI-N\fP, but guess a lexer based on content read from standard input.
98:Print detailed help for the object \fI<name>\fP of type \fI<type>\fP, where
\fI<type>\fP is one
99:of "lexer", "formatter" or "filter".
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z
":
an.tmac:<stdin>:1: style: .TH missing fourth argument; consider package/project
name and version (e.g., "groff 1.23.0")
an.tmac:<stdin>:8: misuse, warning: .RI is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument.
an.tmac:<stdin>:9: misuse, warning: .RI is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument.
an.tmac:<stdin>:12: misuse, warning: .RI is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument.
an.tmac:<stdin>:15: misuse, warning: .RI is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument.
an.tmac:<stdin>:18: misuse, warning: .RI is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument.
an.tmac:<stdin>:21: misuse, warning: .RI is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument.
an.tmac:<stdin>:24: misuse, warning: .RI is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument.
an.tmac:<stdin>:27: misuse, warning: .RI is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument.
an.tmac:<stdin>:35: style: 2 leading space(s) on input line
an.tmac:<stdin>:36: style: 2 leading space(s) on input line
an.tmac:<stdin>:37: style: 2 leading space(s) on input line
an.tmac:<stdin>:38: style: 2 leading space(s) on input line
an.tmac:<stdin>:39: style: 2 leading space(s) on input line
an.tmac:<stdin>:40: style: 2 leading space(s) on input line
-.-.
Additionally (general):
Abbreviations get a '\&' added after their final full stop (.) to mark them
as such and not as an end of a sentence.
--- pygmentize.1 2025-01-05 01:02:35.100878982 +0000
+++ pygmentize.1.new 2025-01-05 01:27:10.773235611 +0000
@@ -5,31 +5,35 @@ pygmentize \- highlights the input file
.SH SYNOPSIS
.B \fBpygmentize\fP
-.RI [-l\ \fI<lexer>\fP\ |\ -g]\ [-F\ \fI<filter>\fP[:\fI<options>\fP]]\ [-f\
\fI<formatter>\fP]
-.RI [-O\ \fI<options>\fP]\ [-P\ \fI<option=value>\fP]\ [-o\ \fI<outfile>\fP]\
[\fI<infile>\fP]
+[\-l\ \fI<lexer>\fP\ |\ \-g]\ [\-F\ \fI<filter>\fP[:\fI<options>\fP]]\ \
+[\-f\ \fI<formatter>\fP]
+[\-O\ \fI<options>\fP]\ [\-P\ \fI<option=value>\fP]\ [\-o\ \
+\fI<outfile>\fP]\ [\fI<infile>\fP]
.br
.B \fBpygmentize\fP
-.RI -S\ \fI<style>\fP\ -f\ \fI<formatter>\fP\ [-a\ \fI<arg>\fP]\ [-O\
\fI<options>\fP]\ [-P\ \fI<option=value>\fP]
+\-S\ \fI<style>\fP\ \-f\ \fI<formatter>\fP\ [\-a\ \fI<arg>\fP]\ [\-O\ \
+\fI<options>\fP]\ [\-P\ \fI<option=value>\fP]
.br
.B \fBpygmentize\fP
-.RI -L\ [\fI<which>\fP\ ...]
+\-L\ [\fI<which>\fP\ ...]
.br
.B \fBpygmentize\fP
-.RI -N\ \fI<filename>\fP
+\-N\ \fI<filename>\fP
.br
.B \fBpygmentize\fP
-.RI -C
+\-C
.br
.B \fBpygmentize\fP
-.RI -H\ \fI<type>\fP\ \fI<name>\fP
+\-H\ \fI<type>\fP\ \fI<name>\fP
.br
.B \fBpygmentize\fP
-.RI -h\ |\ -V
+\-h\ |\ \-V
.SH DESCRIPTION
Pygments is a generic syntax highlighter for general use in all kinds
-of software such as forum systems, wikis or other applications that need to
-prettify source code.
+of software such as forum systems,
+wikis or other applications
+that need to prettify source code.
.PP
Its highlights are:
* a wide range of common languages and markup formats is supported
@@ -37,66 +41,87 @@ Its highlights are:
* support for new languages and formats are added easily
* a number of output formats, presently HTML, LaTeX and ANSI sequences
* it is usable as a command-line tool and as a library
- * ... and it highlights even Brainfuck!
+ * ...\& and it highlights even Brainfuck!
.PP
\fBpygmentize\fP is a command that uses Pygments to highlight the input file
and
-write the result to \fI<outfile>\fP. If no \fI<infile>\fP is given, stdin is
used.
+write the result to \fI<outfile>\fP.
+If no \fI<infile>\fP is given,
+stdin is used.
.SH OPTIONS
A summary of options is included below.
.TP
.B \-l \fI<lexer>\fP
-Set the lexer name. If not given, the lexer is guessed from the extension of
the
-input file name (this obviously doesn't work if the input is stdin).
+Set the lexer name.
+If not given,
+the lexer is guessed from the extension of the input file name
+(this obviously doesn't work if the input is stdin).
.TP
.B \-g
-Attempt to guess the lexer from the file contents, or pass through as plain
text
-if this fails (this option works for highlighting standard input).
+Attempt to guess the lexer from the file contents,
+or pass through as plain text
+if this fails
+(this option works for highlighting standard input).
.TP
.B \-F \fI<filter>\fP[:\fI<options>\fP]
-Add a filter to the token stream. You can give options in the same way as for
--O after a colon (note: there must not be spaces around the colon).
+Add a filter to the token stream.
+You can give options in the same way as for \-O after a colon
+(note: there must not be spaces around the colon).
This option can be given multiple times.
.TP
.B \-f \fI<formatter>\fP
-Set the formatter name. If not given, it will be guessed from the extension of
-the output file name. If no output file is given, the terminal formatter will
be
-used by default.
+Set the formatter name.
+If not given,
+it will be guessed from the extension of the output file name.
+If no output file is given,
+the terminal formatter will be used by default.
.TP
.B \-o \fI<outfile>\fP
-Set output file. If not given, stdout is used.
+Set output file.
+If not given, stdout is used.
.TP
.B \-O \fI<options>\fP
-With this option, you can give the lexer and formatter a comma-separated list
of
-options, e.g. "-O bg=light,python=cool". Which options are valid for which
-lexers and formatters can be found in the documentation.
+With this option,
+you can give the lexer
+and formatter a comma-separated list of options,
+e.g., "\-O bg=light,python=cool".
+Which options are valid for which lexers
+and formatters can be found in the documentation.
This option can be given multiple times.
.TP
.B \-P \fI<option=value>\fP
-This option adds lexer and formatter options like the -O option, but
-you can only give one option per -P. That way, the option value may contain
-commas and equals signs, which it can't with -O.
+This option adds lexer and formatter options like the \-O option,
+but you can only give one option per \-P.
+That way,
+the option value may contain commas and equals signs,
+which it can't with \-O.
.TP
.B \-S \fI<style>\fP
-Print out style definitions for style \fI<style>\fP and for formatter
\fI<formatter>\fP.
+Print out style definitions for style \fI<style>\fP
+and for formatter \fI<formatter>\fP.
The meaning of the argument given by
.B \-a \fI<arg>\fP
is formatter dependent and can be found in the documentation.
.TP
.B \-L [\fI<which>\fP ...]
-List lexers, formatters, styles or filters. Set \fI<which>\fP to the thing you
want
-to list (e.g. "styles"), or omit it to list everything.
+List lexers, formatters, styles or filters.
+Set \fI<which>\fP to the thing you want to list
+(e.g., "styles"),
+or omit it to list everything.
.TP
.B \-N \fI<filename>\fP
-Guess and print out a lexer name based solely on the given filename. Does not
-take input or highlight anything. If no specific lexer can be found, "text"
-is printed.
+Guess and print out a lexer name based solely on the given filename.
+Does not take input or highlight anything.
+If no specific lexer can be found,
+"text" is printed.
.TP
.B \-C
-Like \fI-N\fP, but guess a lexer based on content read from standard input.
+Like \fI\-N\fP,
+but guess a lexer based on content read from standard input.
.TP
.B \-H \fI<type>\fP \fI<name>\fP
-Print detailed help for the object \fI<name>\fP of type \fI<type>\fP, where
\fI<type>\fP is one
-of "lexer", "formatter" or "filter".
+Print detailed help for the object \fI<name>\fP of type \fI<type>\fP,
+where \fI<type>\fP is one of "lexer",
+"formatter" or "filter".
.TP
.B \-h
Show help screen.
