Your message dated Tue, 15 Apr 2025 04:27:00 +0200
with message-id <[email protected]>
and subject line Re: Bug#1102892: deb-control.5: Some remarks and a patch with
editorial changes for this man page
has caused the Debian Bug report #1102892,
regarding deb-control.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 [email protected]
immediately.)
--
1102892: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1102892
Debian Bug Tracking System
Contact [email protected] with problems
--- Begin Message ---
Package: dpkg-dev
Version: 1.22.18
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
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?
an.tmac:<stdin>:116: style: use of deprecated macro: .PD
an.tmac:<stdin>:119: style: use of deprecated macro: .PD
an.tmac:<stdin>:232: style: use of deprecated macro: .PD
an.tmac:<stdin>:237: style: use of deprecated macro: .PD
troff:<stdin>:240: warning [page 3, line 11]: cannot break line; overset by 23n
* 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.21-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 dpkg-dev depends on:
ii binutils 2.44-3
ii bzip2 1.0.8-6
ii libdpkg-perl 1.22.18
ii make 4.4.1-2
ii patch 2.7.6-7
ii perl 5.40.1-2
ii tar 1.35+dfsg-3.1
ii xz-utils 5.8.1-1
Versions of packages dpkg-dev recommends:
pn build-essential <none>
ii clang-18 [c-compiler] 1:18.1.8-17
ii clang-19 [c-compiler] 1:19.1.7-3
ii fakeroot 1.37.1.1-1
ii gcc [c-compiler] 4:14.2.0-1
ii gcc-13 [c-compiler] 13.3.0-13
ii gcc-14 [c-compiler] 14.2.0-19
ii gnupg 2.2.46-6
ii gpgv 2.2.46-6
pn libalgorithm-merge-perl <none>
Versions of packages dpkg-dev suggests:
pn debian-keyring <none>
-- no debconf information
Input file is deb-control.5
Output from "mandoc -T lint deb-control.5": (shortened list)
1 empty block: RS
1 input text line longer than 80 bytes: The known priorities...
-.-.
Output from
test-nroff -mandoc -t -ww -z deb-control.5: (shortened list)
1 cannot break line; overset by 23n
-.-.
Show if Pod::Man generated this.
Who is actually creating this man page? Debian or upstream?
Is the generating software out of date?
2:.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
-.-.
Strings longer than 3/4 of a standard line length (80).
Use "\:" to split the string at the end of an output line, for example a
long URL (web address).
This is a groff extension.
240
<https://salsa.debian.org/installer\-team/debian\-installer/\-/raw/master/doc/devel/modules.txt>.
-.-.
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.
Line 137, length 89
The known priorities are \fBrequired\fR, \fBimportant\fR, \fBstandard\fR,
\fBoptional\fR,
Line 150, length 81
\&\fBdpkg\fR\|(1) or any other installation tool will not allow a
\fBProtected\fR
Line 160, length 82
\&\fBdpkg\fR\|(1) or any other installation tool will not allow an
\fBEssential\fR
Line 240, length 97
<https://salsa.debian.org/installer\-team/debian\-installer/\-/raw/master/doc/devel/modules.txt>.
Longest line is number 240 with 97 characters
-.-.
Remove unnecessary double font change (e.g., \fR\fI) in a row or (better)
use a two-fonts macro.
184:used format is \fIbts-type\fR\fB://\fR\fIbts-address\fR, like
222:.IP "\fBSource:\fR \fIsource-name\fR [\fB(\fR\fIsource-version\fR\fB)\fR]" 4
-.-.
Add a zero (0) in front of a decimal fraction that begins with a period
(.)
7:.if t .sp .5v
-.-.
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
deb-control.5:105:It may also include a Debian revision number (for non-native
packages).
deb-control.5:121:first line (after the \fBDescription\fR field).
deb-control.5:151:package to be removed (at least not without using one of the
force options).
deb-control.5:161:package to be removed (at least not without using one of the
force options).
deb-control.5:248:field aren't installed (at least not without using the force
options).
deb-control.5:284:of packages separated by vertical bar (or \(lqpipe\(rq)
symbols,
deb-control.5:294:(since dpkg 1.16.5) or \fBany\fR (since dpkg 1.16.2).
deb-control.5:341:is a list of package names, separated by commas (and optional
whitespace).
deb-control.5:376:is a list of package names, separated by commas (and optional
whitespace).
deb-control.5:380:An optional exact (equal to) version can also be given with
the same
deb-control.5:381:syntax as above (honored since dpkg 1.17.11).
deb-control.5:410:this binary packages was built with (since dpkg 1.17.2 until
1.18.18).
deb-control.5:438:\& Pre\-Depends: libc6 (>= 2.0.105)
-.-.
Only one space character is after a possible end of sentence
(after a punctuation, that can end a sentence).
deb-control.5:447:\& look at every character. The result is typically many
times faster
deb-control.5:448:\& than Unix grep or egrep. (Regular expressions containing
backreferencing
-.-.
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.
deb-control.5:66:.IX Header "SYNOPSIS"
deb-control.5:69:.IX Header "DESCRIPTION"
deb-control.5:90:.IX Header "FIELDS"
deb-control.5:389:.IX Header "EXAMPLE"
deb-control.5:412:.IX Header "BUGS"
-.-.
Use ".na" (no adjustment) instead of ".ad l" (and ".ad" to begin the
same adjustment again as before).
61:.if n .ad l
-.-.
Add lines to use the CR font for groff instead of CW.
.if t \{\
. ie \\n(.g .ft CR
. el .ft CW
.\}
11:.ft CW
-.-.
Section headings (.SH and .SS) do not need quoting their arguments.
456:.SH "SEE ALSO"
-.-.
Put a (long) web address on a new line to reduce the posibility of
splitting the address between two output lines.
Or inhibit hyphenation with "\%" in front of the name.
240:<https://salsa.debian.org/installer\-team/debian\-installer/\-/raw/master/doc/devel/modules.txt>.
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z
":
an.tmac:<stdin>:116: style: use of deprecated macro: .PD
an.tmac:<stdin>:119: style: use of deprecated macro: .PD
an.tmac:<stdin>:232: style: use of deprecated macro: .PD
an.tmac:<stdin>:237: style: use of deprecated macro: .PD
Output from "test-nroff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z
":
an.tmac:<stdin>:116: style: use of deprecated macro: .PD
an.tmac:<stdin>:119: style: use of deprecated macro: .PD
an.tmac:<stdin>:232: style: use of deprecated macro: .PD
an.tmac:<stdin>:237: style: use of deprecated macro: .PD
troff:<stdin>:240: warning [page 3, line 11]: cannot break line; overset by 23n
-.-.
Generally:
Split (sometimes) lines after a punctuation mark; before a conjunction.
--- deb-control.5 2025-04-13 01:28:59.602396612 +0000
+++ deb-control.5.new 2025-04-13 01:59:31.627618624 +0000
@@ -237,7 +237,16 @@ setting a different binary version via \
.PD
These fields are used by the debian-installer and are usually not needed.
For more details about them, see
-<https://salsa.debian.org/installer\-team/debian\-installer/\-/raw/master/doc/devel/modules.txt>.
+.br
+.ie \n(.g \{\
+<https://salsa.debian.org/\:installer\-team/\:debian\-installer/\:\-/\:raw/\:master/\:doc/\:devel/\:modules.txt>.
+.\}
+.el \{\
+.nf
+<https://salsa.debian.org/installer\-team/debian\-installer/\-/raw/master
+/doc/devel/modules.txt>.
+.fi
+.\}
.IP "\fBDepends:\fR \fIpackage-list\fR" 4
.IX Item "Depends: package-list"
List of packages that are required for this package to provide a
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
-.-
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)
-.-
--- End Message ---
--- Begin Message ---
Hi!
On Sun, 2025-04-13 at 02:08:17 +0000, Bjarni Ingi Gislason wrote:
> Package: dpkg-dev
> Version: 1.22.18
> Severity: minor
> Tags: patch
> * What was the outcome of this action?
>
[… style message …]
> troff:<stdin>:240: warning [page 3, line 11]: cannot break line; overset by
> 23n
>
> * What outcome did you expect instead?
>
> No output (no warnings).
On Sun, 2025-04-13 at 11:26:08 +0000, Bjarni Ingi Gislason wrote:
> Package: dpkg-dev
> Version: 1.22.18
> Severity: minor
> Tags: patch
> * What was the outcome of this action?
>
>
[… style message …]
> troff:<stdin>:483: warning [page 5, line 25]: cannot break line; overset by
> 23n
>
>
> * What outcome did you expect instead?
>
> No output (no warnings).
Thanks for the patches and analysis, although the dpkg man pages are
generated from POD, which the tool you are using seems to have correctly
detected. So if there is anything to fix, that should be proposed to the
podlators project. So I don't see anything to fix/change here, and I'm
thus closing these reports.
Thanks,
Guillem
--- End Message ---
