Package: man-db
Version: 2.13.0-1
Severity: minor
Tags: patch
* What led up to the situation?
Checking for defects with
[test-][g|n]roff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z < "man page"
["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?
troff: backtrace: file '<stdin>':870
troff:<stdin>:870: warning: trailing space in the line
Output from "test-nroff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z ":
troff: backtrace: file '<stdin>':870
troff:<stdin>:870: 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: trixie/sid
APT prefers testing
APT policy: (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.11.2-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 man-db depends on:
ii bsdextrautils 2.40.2-9
ii bsdmainutils 12.1.8
ii debconf [debconf-2.0] 1.5.87
ii groff-base 1.23.0-5
ii libc6 2.40-3
ii libgdbm6t64 1.24-2
ii libpipeline1 1.5.8-1
ii libseccomp2 2.5.5-1+b1
ii zlib1g 1:1.3.dfsg+really1.3.1-1
man-db recommends no packages.
Versions of packages man-db suggests:
pn apparmor <none>
ii firefox-esr [www-browser] 128.3.1esr-2
ii groff 1.23.0-5
ii less 643-1
ii lynx [www-browser] 2.9.2-1
ii w3m [www-browser] 0.5.3+git20230121-2+b3
-- Configuration Files:
/etc/manpath.config changed [not included]
-- debconf information excluded
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
-.-
So any 'generator' should check its products with the above mentioned
'groff', 'mandoc', and additionally with 'nroff ...'.
This is just a simple quality control measure.
The 'generator' may have to be corrected to get a better man page,
the source file may, and any additional file may.
Common defects:
Input text line longer than 80 bytes.
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.
Lines should thus be shorter.
See man-pages(7), item 'semantic newline'.
-.-
The difference between the formatted outputs can be seen with:
nroff -mandoc <file1> > <out1>
nroff -mandoc <file2> > <out2>
diff -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 of 'diff -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)
-.-.
Use the correct macro for the font change of a single argument or
split the argument into two.
994:.BR X75
-.-.
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.
1097:.B MANROFFOPT=-P-i
1313:https://gitlab.com/man-db/man-db/-/issues
1315:https://savannah.nongnu.org/bugs/?group=man-db
-.-.
Change a HYPHEN-MINUS (code 0x55, 2D) to a dash
(\-, minus) if it matches "[[:alph:]]-[[:alpha:]]" in the name of an
option).
Facilitates the copy and paste of
a) an option in UTF-8 text
b) web addresses (URL).
Is not needed in ordinary words like "mother-in-law", that are not
copied and pasted to a command line (which needs ASCII code)
1097:.B MANROFFOPT=-P-i
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z ":
troff: backtrace: file '<stdin>':870
troff:<stdin>:870: warning: trailing space in the line
-.-
Additions:
Table headers, that are wider than any data in the corresponding column, do
not
need to be centered, so a left adjustment is sufficient.
-.-
203:\fBman '\fIman\fR(\fI7\fR)'
The later quote character (') should be typed in bold.
-.-
Additionally (general):
Abbreviations get a '\&' added after their final full stop (.) to mark them as
such and not as an end of a sentence.
--- man.1 2024-10-19 22:08:03.982204804 +0000
+++ man.1.new 2024-10-20 00:50:07.685078177 +0000
@@ -200,7 +200,7 @@ from section
(This is an alternative spelling of
"\fBman\fR \fI7 man\fR".)
.TP
-\fBman '\fIman\fR(\fI7\fR)'
+\fBman '\fIman\fR(\fI7\fR)\fB'\fR
Display the manual page for macro package
.I man
from section
@@ -866,7 +866,8 @@ device.
. ds softhyphen \(hy
.TS
tab (@);
-l c c c.
+l l l l
+l c c c .
Description@Octal@latin1@ascii
_
continuation hyphen@255@\*[softhyphen]@-
@@ -991,7 +992,7 @@ Examples (as of groff 1.23.0) include
.BR pdf ,
.BR ps ,
.BR utf8 ,
-.BR X75
+.B X75
and
.BR X100 .
.TP
@@ -1094,7 +1095,7 @@ it adds the contents of
to the formatter's command line.
For example,
-.B MANROFFOPT=-P-i
+.B MANROFFOPT=\-P\-i
tells the formatter to use italic text (which is only supported by some
terminals) rather than underlined text.
.TP
@@ -1310,6 +1311,6 @@ help of all the community.
31st March 2001 \(en present day: Colin Watson <cjwat...@debian.org> is now
developing and maintaining man-db.
.SH BUGS
-https://gitlab.com/man-db/man-db/-/issues
+https://gitlab.com/man-db/man-db/\-/issues
.br
-https://savannah.nongnu.org/bugs/?group=man-db
+https://savannah.nongnu.org/bugs/?group=man\-db
