Package: linux-base
Version: 4.11
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>:427: misuse, warning: .IR is for at least 2 arguments, got 1
Use macro '.I' 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 linux-base depends on:
ii debconf [debconf-2.0] 1.5.89
linux-base recommends no packages.
linux-base suggests no packages.
-- debconf information excluded
Input file is kernel-img.conf.5
Output from "mandoc -T lint kernel-img.conf.5": (shortened list)
-.-.
Output from "test-groff -mandoc -t -ww -z kernel-img.conf.5": (shortened list)
1 Use macro '.I' for one argument or split argument.
1 .IR 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 "\-\-".
kernel-img.conf.5:112:path can be a relative path if the script lives in a safe
path -- that
kernel-img.conf.5:130:this script should issue no diagnostic messages to stdout
-- while the
kernel-img.conf.5:155:a safe path -- that is, if it lives in /bin, /sbin,
/usr/bin, or
kernel-img.conf.5:168:diagnostic messages to stdout -- while the postinst does
call
kernel-img.conf.5:189:a relative path if the script lives in a safe path --
that is, if it
kernel-img.conf.5:219:relative path if the script lives in a safe path -- that
is, if it
kernel-img.conf.5:232:script should issue no diagnostic messages to stdout --
while the
kernel-img.conf.5:256:The path can be a relative path if the script lives in a
safe path --
kernel-img.conf.5:285:path if the script lives in a safe path -- that is, if it
lives in
-.-.
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.
N.B.
The number of lines affected can be too large to be in a patch.
53:pair. Boolean values may be specified as
111:Set this variable to a script to be executed during installation. The
114:absolute path instead. Before calling this script, the environment
128:of the kernel image itself. Errors in the script shall cause the
129:postinst to fail. Since debconf is in use before the script is called,
154:been performed. The path can be a relative path if the script lives in
156:/usr/sbin, or must be an absolute path instead. In packages
160:package. This script shall be called with two arguments, the first
165:of the kernel image itself. Errors in the script shall produce a
166:warning message, but shall be otherwise ignored. Since debconf is in
188:unpacked, and can be used to put in additional checks. The path can be
191:path instead. In packages created by kernel\-package, the
195:package. This script shall be called with two arguments, the first
218:are removed (so any added files may be removed) . The path can be a
221:path instead. In packages created by kernel\-package, the
225:package. This script shall be called with two arguments, the
230:of the kernel image itself. Errors in the script shall cause the prerm
231:to fail. Since debconf is in use before the script is called, this
253:the post inst of a docs, headers or a source package. Using this hook
258:be an absolute path instead. The environment variable
267:of the package being installed. Errors in the script shall cause the
284:the post inst of a headers package only. The path can be a relative
287:instead. In packages created by kernel\-package, the environment
291:package. This script shall be called with two arguments, the first
296:of the package being installed. Errors in the script shall cause the
314:installed. Use at your own risk.
328:running version. If the modules list is changed, the modules
331:changed in the meanwhile. It is a good idea to reboot, and this is a
332:note to remind you. If you know what you are doing, you can set this
333:variable to no. This variable is set by default.
344:This option manipulates the build link created by recent kernels. If
347:created to point to them. The default is to relink the build link
359:This option manipulates the build link created by recent kernels. If
362:not. The default is unset, we don't create potentially dangling
374:This option manipulates the source link created by recent kernels. If
375:the link is a dangling link it is deleted at install time. The default
410:postinst script. This facilitates automated installs, though it may
411:mask a problem with the kernel image. A diagnostic is still
412:issued. This is unset by default.
-.-.
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
kernel-img.conf.5:119:argument (or the default value, linux), and in packages
created
kernel-img.conf.5:218:are removed (so any added files may be removed) . The
path can be a
kernel-img.conf.5:264:of the package being installed (could be kernel source or
headers),
-.-.
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.
25:.TH KERNEL\-IMG.CONF 5 "24 March 2019" "Debian" "Debian GNU/Linux manual"
32:.SH "DESCRIPTION"
-.-.
Section headings (.SH and .SS) do not need quoting.
32:.SH "DESCRIPTION"
430:.SH "SEE ALSO"
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z
":
an.tmac:<stdin>:427: misuse, warning: .IR is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument.
--- kernel-img.conf.5 2025-02-11 03:13:56.618631915 +0000
+++ kernel-img.conf.5.new 2025-02-11 03:39:14.040810872 +0000
@@ -22,14 +22,14 @@
.\" Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
.\" USA.
.\"
-.TH KERNEL\-IMG.CONF 5 "24 March 2019" "Debian" "Debian GNU/Linux manual"
+.TH KERNEL\-IMG.CONF 5 "24 March 2019" Debian "Debian GNU/Linux manual"
.\" NAME should be all caps, SECTION should be 1-8, maybe w/ subsection
.\" other parms are allowed: see man(7), man(1)
.SH NAME
kernel\-img.conf \- configuration file for Linux kernel packages
.SH SYNOPSIS
.I /etc/kernel\-img.conf
-.SH "DESCRIPTION"
+.SH DESCRIPTION
The file
.I /etc/kernel\-img.conf
is used by the kernel package installation and removal process to
@@ -109,14 +109,16 @@ kernel\-package ignored since v12.001;
.B postinst_hook
.BR DEPRECATED :
Set this variable to a script to be executed during installation. The
-path can be a relative path if the script lives in a safe path -- that
+path can be a relative path if the script lives in a safe path \(en that
is, if it lives in /bin, /sbin, /usr/bin, or /usr/sbin, or must be an
absolute path instead. Before calling this script, the environment
variable
.B STEM
shall be set to the value of the
.I \-\-stem
-argument (or the default value, linux), and in packages created
+argument
+(or the default value, linux),
+and in packages created
by kernel\-package
.B KERNEL_PACKAGE_VERSION
shall be set to the version of the kernel\-package that created the
@@ -127,7 +129,7 @@ of the kernel image, and the second argu
.I location
of the kernel image itself. Errors in the script shall cause the
postinst to fail. Since debconf is in use before the script is called,
-this script should issue no diagnostic messages to stdout -- while the
+this script should issue no diagnostic messages to stdout \(en while the
postinst does call
.BR db_stop ,
debconf does not restore stdout, so messages to stdout disappear.
@@ -152,7 +154,7 @@ kernel\-package deprecated
Set this variable to a script to be executed in the postrm (that is,
after the image has been removed) after all the remove actions have
been performed. The path can be a relative path if the script lives in
-a safe path -- that is, if it lives in /bin, /sbin, /usr/bin, or
+a safe path \(en that is, if it lives in /bin, /sbin, /usr/bin, or
/usr/sbin, or must be an absolute path instead. In packages
created by kernel\-package, the environment variable
.B KERNEL_PACKAGE_VERSION
@@ -165,7 +167,7 @@ of the kernel image, and the second argu
of the kernel image itself. Errors in the script shall produce a
warning message, but shall be otherwise ignored. Since debconf is in
use before the script is called, this script should issue no
-diagnostic messages to stdout -- while the postinst does call
+diagnostic messages to stdout \(en while the postinst does call
.BR db_stop ,
debconf does not restore stdout, so messages to stdout disappear.
This script is run
@@ -186,7 +188,7 @@ kernel\-package deprecated
.BR DEPRECATED :
Set this variable to a script to be executed before the package is
unpacked, and can be used to put in additional checks. The path can be
-a relative path if the script lives in a safe path -- that is, if it
+a relative path if the script lives in a safe path \(en that is, if it
lives in /bin, /sbin, /usr/bin, or /usr/sbin, or must be an absolute
path instead. In packages created by kernel\-package, the
environment variable
@@ -215,8 +217,10 @@ kernel\-package deprecated
.B prerm_hook
.BR DEPRECATED :
Set this variable to a script to be executed before the package files
-are removed (so any added files may be removed) . The path can be a
-relative path if the script lives in a safe path -- that is, if it
+are removed
+(so any added files may be removed).
+The path can be a
+relative path if the script lives in a safe path \(en that is, if it
lives in /bin, /sbin, /usr/bin, or /usr/sbin, or must be an absolute
path instead. In packages created by kernel\-package, the
environment variable
@@ -229,7 +233,7 @@ of the kernel image, and the second argu
.I location
of the kernel image itself. Errors in the script shall cause the prerm
to fail. Since debconf is in use before the script is called, this
-script should issue no diagnostic messages to stdout -- while the
+script should issue no diagnostic messages to stdout \(en while the
postinst does call
.BR db_stop ,
debconf does not restore stdout, so messages to stdout disappear.
@@ -261,7 +265,8 @@ shall be set to the version of the kerne
package. This script shall be called with two arguments, the first
being the
.I name
-of the package being installed (could be kernel source or headers),
+of the package being installed
+(could be kernel source or headers),
and the second argument being the
.I version
of the package being installed. Errors in the script shall cause the
@@ -282,7 +287,7 @@ kernel\-package deprecated
.BR DEPRECATED :
Unlike the other hook variables, this is meant for a script run during
the post inst of a headers package only. The path can be a relative
-path if the script lives in a safe path -- that is, if it lives in
+path if the script lives in a safe path \(en that is, if it lives in
/bin, /sbin, /usr/bin, or /usr/sbin, or must be an absolute path
instead. In packages created by kernel\-package, the environment
variable
@@ -424,10 +429,10 @@ kernel\-package supported
The file described here is
.IR /etc/kernel\-img.conf .
\fBkernel\-common\fR includes example scripts suitable for dropping into
-.IR /etc/kernel/*.d
+.I /etc/kernel/*.d
installed in
.IR /usr/share/doc/kernel-common/examples .
-.SH "SEE ALSO"
+.SH SEE ALSO
.BR linux\-update\-symlinks (8),
.BR make\-kpkg (1),
.BR kernel\-pkg.conf (5)
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.
Not beginning each input sentence on a new line.
Line length 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)
-.-
