[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Bug#1095744: marked as done (kernel-img.conf.5: Some remarks and a patch with editorial changes for this man page)

Your message dated Sun, 25 May 2025 19:34:34 +0000
with message-id <E1uJH7C-005Mau-Jy@fasolo.debian.org>
and subject line Bug#1095744: fixed in linux-base 4.12
has caused the Debian Bug report #1095744,
regarding kernel-img.conf.5: Some remarks and a patch with editorial changes for this man page
to be marked as done.

This means that you claim that the problem has been dealt with.
If this is not the case it is now your responsibility to reopen the
Bug report if necessary, and/or fix the problem forthwith.

(NB: If you are a system administrator and have no idea what this
message is talking about, this may indicate a serious mail system
misconfiguration somewhere. Please contact owner@bugs.debian.org
immediately.)


-- 
1095744: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1095744
Debian Bug Tracking System
Contact owner@bugs.debian.org with problems
--- Begin Message --- 
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)

-.-

--- End Message ---
--- Begin Message --- 
Source: linux-base
Source-Version: 4.12
Done: Ben Hutchings <benh@debian.org>

We believe that the bug you reported is fixed in the latest version of
linux-base, which is due to be installed in the Debian FTP archive.

A summary of the changes between this version and the previous one is
attached.

Thank you for reporting the bug, which will now be closed.  If you
have further comments please address them to 1095744@bugs.debian.org,
and the maintainer will reopen the bug report if appropriate.

Debian distribution maintenance software
pp.
Ben Hutchings <benh@debian.org> (supplier of updated linux-base package)

(This message was generated automatically at their request; if you
believe that there is a problem with it please contact the archive
administrators by mailing ftpmaster@ftp-master.debian.org)


-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

Format: 1.8
Date: Sun, 25 May 2025 21:16:36 +0200
Source: linux-base
Architecture: source
Version: 4.12
Distribution: unstable
Urgency: medium
Maintainer: Debian Kernel Team <debian-kernel@lists.debian.org>
Changed-By: Ben Hutchings <benh@debian.org>
Closes: 1076510 1095744 1099472 1100702
Changes:
 linux-base (4.12) unstable; urgency=medium
 .
   * d/changelog: Word-wrap previous entry to under 80 characters
   * d/copyright: Replace old FSF addresses with current GNU license URL
   * Add linux-run-hooks command for use by package maintainer scripts
   * man: Fix some minor formatting issues, thanks to Bjarni Ingi Gislason
     (Closes: #1095744, #1100702)
   * kernel-img.conf(5): Remove documentation of kernel-package
     (Closes: #1099472)
   * kernel-img.conf(5): Simplify description of support status
   * linux-sysctl-defaults: Increase vm.max_map_count to 1048576
     (Closes: #1076510)
Checksums-Sha1:
 7c92a4e45f4d38cf8c36cad1713855060ec9b785 1746 linux-base_4.12.dsc
 a79ea1b8ca18f093d6997abdcae682c8a7011ee3 29444 linux-base_4.12.tar.xz
 ecd9e751b055b83f5efab6ab53f5d402b310eb04 7764 linux-base_4.12_source.buildinfo
Checksums-Sha256:
 df6e43a704cc6b67f47a0d1b843739d9199853da9e40be54a732eea0fcca6a3d 1746 linux-base_4.12.dsc
 23fd8ce524a68cebbc300119a956ad50614f705cec910c39fd1b58b0a27e0131 29444 linux-base_4.12.tar.xz
 2d939498b5244c5204e1443bda07a0105f37867a44829d3e8d149144ab0939c9 7764 linux-base_4.12_source.buildinfo
Files:
 91888629ccf3568ae96b3d8a62ec1cac 1746 kernel optional linux-base_4.12.dsc
 28526cd9db660957576693ab8e5ce56a 29444 kernel optional linux-base_4.12.tar.xz
 d73b5df024549bab9f0886fcf47f005b 7764 kernel optional linux-base_4.12_source.buildinfo

-----BEGIN PGP SIGNATURE-----

iQIzBAEBCgAdFiEErCspvTSmr92z9o8157/I7JWGEQkFAmgzbh8ACgkQ57/I7JWG
EQkDyBAA1OPkUcDPm0/1RlAMZ2Ox3VkLuJNGb4CCBoRUYeRCQeZIRWIog/rvXSGl
wuRThT10Ak/x1He2LqTmYkTVbGQOrNrqaZlYCl362NUEz33Td9BL13bI7MPilvT6
R/024zJAeMbRtUADkIyAQf4lgcNfUqIxU7yn3OxtOlFB0KGJP0uen3AC5D66A26M
COYpVea4P8rnsP5JAzeNgFyVRadq6WmKjj8/nKrgYc+n+oh7A+4l5k6Y3y3cUR18
3x+TNZT3ealn9Gbw6JtMqtW43hB45AkCzzxDncX+NK6DLOYu2elFrOlPto9gjomM
Fck3AH6SpxYQ1+fRSjoZi4jt2Mw5NXYmqy0hogpzR9WzTcM/a90GsfLVs4ilKFij
1CFLtGEA4RhmBSieeDNcYqzjv6WTsB8OYs2yVZh/h590UNo8iPFNRX+xuypYnx8E
JjVjsRHa7UZTaVIw66Xajq1jQfFNdh2G945FrigJCUtbME358R+5SCboBkbU+hIc
18koCQl9806cRs46EM65nsD1NoWLGuibg93W1elMWixF6IVDHlgNiR0kzaU72x8V
IEhACqlJGfYmoPRXaCUMrVgwIdQnwr0yafImDxq22nHr79ljs6gDFXqVtjXh7ykc
Zy6fPhDwLY1wyzj+C02O/Ou9VUP2jyIEQmAubP9HZsMO0Z4/qaQ=
=HCYC
-----END PGP SIGNATURE-----

Attachment: pgpYrfsWyAULk.pgp
Description: PGP signature


--- End Message ---
Reply to: