Bug#1119952: File::Find::Rule::Extending.3pm: Some remarks and a patch with editorial changes for this man page
Bjarni Ingi Gislason
bjarniig at simnet.is
Sun Nov 2 19:25:28 GMT 2025
Package: libfile-find-rule-perl
Version: 0.35-1
Severity: minor
Tags: patch
>From "/usr/share/doc/debian/bug-reporting.txt.gz":
Don't file bugs upstream
If you file a bug in Debian, don't send a copy to the upstream software
maintainers yourself, as it is possible that the bug exists only in
Debian. If necessary, the maintainer of the package will forward the
bug upstream.
-.-
I do not send reports upstream if I have to get an account there.
The Debian maintainers have one already.
-.-
* 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=0 -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?
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=0 -ww -z ":
troff:<stdin>:70: warning: trailing space in the line
troff:<stdin>:79: warning: trailing space in the 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: forky/sid
APT prefers testing
APT policy: (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.16.12+deb14+1-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 libfile-find-rule-perl depends on:
ii libnumber-compare-perl 0.03-3
ii libtext-glob-perl 0.11-3
ii perl 5.40.1-6
libfile-find-rule-perl recommends no packages.
libfile-find-rule-perl suggests no packages.
-- no debconf information
-------------- next part --------------
Input file is File::Find::Rule::Extending.3pm
Output from "mandoc -T lint File::Find::Rule::Extending.3pm": (shortened list)
1 STYLE: input text line longer than 80 bytes:
-.-.
Output from
test-nroff -mandoc -t -ww -z File::Find::Rule::Extending.3pm: (shortened list)
2 line(s) with a trailing space
Find most trailing spaces with:
grep -n -e ' $' -e ' \\f.$' -e ' \\"' <man page>
-.-.
Show if Pod::Man generated this.
2:.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
Latest version in Debian testing:
This is perl 5, version 40, subversion 1 (v5.40.1) built for x86_64-linux-gnu-thread-multi
(with 48 registered patches, see perl -V for more detail)
-.-.
Remove space characters (whitespace) at the end of lines.
Use "git apply ... --whitespace=fix" to fix extra space issues, or use
global configuration "core.whitespace".
Number of lines affected is
2
-.-.
Split lines longer than 80 characters (fill completly
an A4 sized page line on a terminal)
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 58, length 99
.TH File::Find::Rule::Extending 3pm 2025-10-27 "perl v5.40.1" "User Contributed Perl Documentation"
Line 131, length 83
If you hadn't declared \f(CW\*(C`random\*(C'\fR with a null prototype it would have
-.-.
Add a zero (0) in front of a decimal fraction that begins with a period
(.)
7:.if t .sp .5v
-.-.
Use a character "\(->" instead of plain "->" or "\->".
76:\& my $self = shift()\->_force_object;
77:\& $self\->exec( sub { rand > 0.5 } );
106:\& my $self = shift()\->_force_object;
107:\& $self\->exec( sub { rand > 0.5 } );
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=0 -ww -z ":
troff:<stdin>:70: warning: trailing space in the line
troff:<stdin>:79: warning: trailing space in the line
-.-
Generally:
Split (sometimes) lines after a punctuation mark; before a conjunction.
-.-
-------------- next part --------------
--- File::Find::Rule::Extending.3pm 2025-11-02 19:10:55.769619664 +0000
+++ File::Find::Rule::Extending.3pm.new 2025-11-02 19:19:06.805952913 +0000
@@ -4,7 +4,7 @@
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
-.if t .sp .5v
+.if t .sp 0.5v
.if n .sp
..
.de Vb \" Begin verbatim text
@@ -67,7 +67,7 @@ File::Find::Rule::Extending \- the mini\
.Vb 2
\& package File::Find::Rule::Random;
\& use strict;
-\&
+\&
\& # take useful things from File::Find::Rule
\& use base \*(AqFile::Find::Rule\*(Aq;
\&
@@ -76,7 +76,7 @@ File::Find::Rule::Extending \- the mini\
\& my $self = shift()\->_force_object;
\& $self\->exec( sub { rand > 0.5 } );
\& }
-\&
+\&
\& 1;
.Ve
.SH DESCRIPTION
-------------- next part --------------
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
-.-
For general input conventions consult the man page "nroff(7)" (item
"Input conventions") or the Texinfo manual about the same item.
-.-
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)
-.-
More information about the pkg-perl-maintainers
mailing list