Package: pciutils
Version: 1:3.13.0-1+b1
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 ' $' -e '\\~$' <file>" to find obvious 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>:20: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
* 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.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 pciutils depends on:
ii libc6 2.40-7
ii libkmod2 33+20240816-2
ii libpci3 1:3.13.0-1+b1
pciutils recommends no packages.
Versions of packages pciutils suggests:
ii bzip2 1.0.8-6
ii curl 8.12.1-2
ii lynx 2.9.2-1
ii wget 1.24.5-2+b1
-- no debconf information
Input file is setpci.8
Output from "mandoc -T lint setpci.8": (shortened list)
1 input text line longer than 80 bytes: "any value". The cla...
1 input text line longer than 80 bytes: (a hex number) to th...
1 input text line longer than 80 bytes: Before each sequence...
1 input text line longer than 80 bytes: Consider only device...
1 input text line longer than 80 bytes: Each component of th...
1 input text line longer than 80 bytes: Finally, if a capabi...
1 input text line longer than 80 bytes: Select devices with ...
1 input text line longer than 80 bytes: Spell its name. Setp...
1 input text line longer than 80 bytes: The ID's are given i...
1 input text line longer than 80 bytes: There are two kinds ...
1 input text line longer than 80 bytes: This option allows o...
1 input text line longer than 80 bytes: To choose how many b...
1 input text line longer than 80 bytes: are hexadecimal numb...
1 input text line longer than 80 bytes: by its number in the...
1 input text line longer than 80 bytes: hexadecimal. E.g., ...
1 input text line longer than 80 bytes: of its own; domains ...
1 input text line longer than 80 bytes: on any bus, "0.3" se...
1 input text line longer than 80 bytes: ones in the \fImask\...
1 input text line longer than 80 bytes: specifies the upper ...
1 input text line longer than 80 bytes: they can either shar...
1 input text line longer than 80 bytes: to be verbose and di...
3 skipping paragraph macro: PP after SH
1 skipping paragraph macro: PP after SS
-.-.
Output from "test-groff -mandoc -t -ww -z setpci.8": (shortened list)
1 Use macro '.B' for one argument or split argument.
1 .BR is for at least 2 arguments, got 1
-.-.
Change two HYPHEN-MINUSES (code 0x2D) to an em-dash (\(em),
if one is intended.
" \(em " creates a too big gap in the text (in "troff").
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 "-"
(begin of an option or end of options)
then use "\-\-".
setpci.8:41:`Demo mode' -- don't write anything to the configuration registers.
setpci.8:55:.B --version
setpci.8:60:.B --help
setpci.8:63:.B --dumpregs
setpci.8:143:headers. Use `\fBsetpci --dumpregs\fP' to get the complete list.
setpci.8:149:`CAP_' or `ECAP_' in the \fB--dumpregs\fP output.
-.-.
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.
27:.B -v
32:.B -f
40:.B -D
41:`Demo mode' -- don't write anything to the configuration registers.
43:.B setpci -vD
48:.B -r
50:.B -s
55:.B --version
60:.B --help
63:.B --dumpregs
73:.B -A <method>
76:this option to override this decision. See \fB-A help\fP for a list of
79:.B -O <param>=<value>
81:This option allows one to set the value of any of the parameters. Use \fB-O
help\fP
84:.B -H1
86:(This is a shorthand for \fB-A intel-conf1\fP.)
88:.B -H2
90:(This is a shorthand for \fB-A intel-conf2\fP.)
92:.B -G
100:.B -s [[[[<domain>]:]<bus>]:][<slot>][.[<func>]]
109:.B -d [<vendor>]:[<device>][:<class>[:<prog-if>]]
115:.B -s
117:.B -d
143:headers. Use `\fBsetpci --dumpregs\fP' to get the complete list.
149:`CAP_' or `ECAP_' in the \fB--dumpregs\fP output.
-.-.
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 "\&".
Some sentences (etc.) do not begin on a new line.
Split (sometimes) lines after a punctuation mark; before a conjunction.
N.B.
The number of lines affected can be too large to be in a patch.
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]
-.-
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.
Add "\:" to split the string for the output, "\<newline>" in the source.
[List of affected lines removed.]
-.-
The name of a man page is typeset in bold and the section in roman
(see man-pages(7)).
20:.BR lspci(8)
-.-.
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
[List of affected line removed.]
-.-
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.
1:.TH setpci 8 "30 May 2024" "pciutils-3.13.0" "The PCI Utilities"
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z
":
an.tmac:<stdin>:20: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
-.-.
Generally:
Split (sometimes) lines after a punctuation mark; before a conjunction.
--- setpci.8 2025-02-27 14:53:42.647885723 +0000
+++ setpci.8.new 2025-02-27 14:54:15.494890433 +0000
@@ -1,14 +1,13 @@
-.TH setpci 8 "30 May 2024" "pciutils-3.13.0" "The PCI Utilities"
+.TH setpci 8 "30 May 2024" pciutils-3.13.0 "The PCI Utilities"
.SH NAME
setpci \- configure PCI devices
.SH SYNOPSIS
.B setpci
-.RB [ options ]
-.B devices
-.BR operations ...
+.RI [ options ]
+.I devices
+.IR operations " ..."
.SH DESCRIPTION
-.PP
.B setpci
is a utility for querying and configuring PCI devices.
@@ -17,19 +16,19 @@ All numbers are entered in hexadecimal n
Root privileges are necessary for almost all operations, excluding reads
of the standard header of the configuration space on some operating systems.
Please see
-.BR lspci(8)
+.BR lspci (8)
for details on access rights.
.SH OPTIONS
.SS General options
.TP
-.B -v
+.B \-v
Tells
.I setpci
to be verbose and display detailed information about configuration space
accesses.
.TP
-.B -f
+.B \-f
Tells
.I setpci
not to complain when there's nothing to do (when no devices are selected).
@@ -37,67 +36,65 @@ This option is intended for use in widel
where it's uncertain whether the device in question is present in the machine
or not.
.TP
-.B -D
-`Demo mode' -- don't write anything to the configuration registers.
+.B \-D
+`Demo mode' \(en don't write anything to the configuration registers.
It's useful to try
-.B setpci -vD
+.B setpci \-vD
to verify that your complex sequence of
.B setpci
operations does what you think it should do.
.TP
-.B -r
+.B \-r
Avoids bus scan if each operation selects a specific device (uses the
-.B -s
+.B \-s
selector with specific domain, bus, slot, and function). This is faster,
but if the device does not exist, it fails instead of matching an empty
set of devices.
.TP
-.B --version
+.B \-\-version
Show
.I setpci
version. This option should be used stand-alone.
.TP
-.B --help
+.B \-\-help
Show detailed help on available options. This option should be used
stand-alone.
.TP
-.B --dumpregs
+.B \-\-dumpregs
Show a list of all known PCI registers and capabilities. This option should be
used stand-alone.
.SS PCI access options
-.PP
The PCI utilities use the PCI library to talk to PCI devices (see
\fBpcilib\fP(7) for details). You can use the following options to
influence its behavior:
.TP
-.B -A <method>
+.B \-A <method>
The library supports a variety of methods to access the PCI hardware.
By default, it uses the first access method available, but you can use
-this option to override this decision. See \fB-A help\fP for a list of
+this option to override this decision. See \fB\-A help\fP for a list of
available methods and their descriptions.
.TP
-.B -O <param>=<value>
+.B \-O <param>=<value>
The behavior of the library is controlled by several named parameters.
-This option allows one to set the value of any of the parameters. Use \fB-O
help\fP
+This option allows one to set the value of any of the parameters. Use \fB\-O
help\fP
for a list of known parameters and their default values.
.TP
-.B -H1
+.B \-H1
Use direct hardware access via Intel configuration mechanism 1.
-(This is a shorthand for \fB-A intel-conf1\fP.)
+(This is a shorthand for \fB\-A intel-conf1\fP.)
.TP
-.B -H2
+.B \-H2
Use direct hardware access via Intel configuration mechanism 2.
-(This is a shorthand for \fB-A intel-conf2\fP.)
+(This is a shorthand for \fB\-A intel-conf2\fP.)
.TP
-.B -G
+.B \-G
Increase debug level of the library.
.SH DEVICE SELECTION
-.PP
Before each sequence of operations you need to select which devices you wish
that
operation to affect.
.TP
-.B -s [[[[<domain>]:]<bus>]:][<slot>][.[<func>]]
+.B \-s [[[[<domain>]:]<bus>]:][<slot>][.[<func>]]
Consider only devices in the specified domain (in case your machine has
several host bridges,
they can either share a common bus number space or each of them can address a
PCI domain
of its own; domains are numbered from 0 to ffff), bus (0 to ff), slot (0 to
1f) and function (0 to 7).
@@ -106,20 +103,19 @@ hexadecimal. E.g., "0:" means all devic
on any bus, "0.3" selects third function of device 0 on all buses and ".4"
matches only
the fourth function of each device.
.TP
-.B -d [<vendor>]:[<device>][:<class>[:<prog-if>]]
+.B \-d [<vendor>]:[<device>][:<class>[:<prog-if>]]
Select devices with specified vendor, device, class ID, and programming
interface.
The ID's are given in hexadecimal and may be omitted or given as "*", both
meaning
"any value". The class ID can contain "x" characters which stand for "any
digit".
.PP
When
-.B -s
+.B \-s
and
-.B -d
+.B \-d
are combined, only devices that match both criteria are selected. When multiple
options of the same kind are specified, the rightmost one overrides the others.
.SH OPERATIONS
-.PP
There are two kinds of operations: reads and writes. To read a register, just
specify
its name. Writes have the form
.IR name = value , value ...\&
@@ -140,13 +136,13 @@ There are several ways to identify a reg
Tell its address in hexadecimal.
.IP \(bu
Spell its name. Setpci knows the names of all registers in the standard
configuration
-headers. Use `\fBsetpci --dumpregs\fP' to get the complete list.
+headers. Use `\fBsetpci \-\-dumpregs\fP' to get the complete list.
See PCI bus specifications for the precise meaning of these registers or
consult
\fBheader.h\fP or \fB/usr/include/pci/pci.h\fP for a brief sketch.
.IP \(bu
If the register is a part of a PCI capability, you can specify the name of the
capability to get the address of its first register. See the names starting
with
-`CAP_' or `ECAP_' in the \fB--dumpregs\fP output.
+`CAP_' or `ECAP_' in the \fB\-\-dumpregs\fP output.
.IP \(bu
If the name of the capability is not known to \fBsetpci\fP, you can refer to it
by its number in the form CAP\fBid\fP or ECAP\fBid\fP, where \fBid\fP is the
numeric
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
-.-
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.
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)
-.-
