Package: man-db
Version: 2.13.0-1
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>:45: 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 man-db depends on:
ii bsdextrautils 2.40.4-3
ii bsdmainutils 12.1.8
ii debconf [debconf-2.0] 1.5.89
ii groff-base 1.23.0-7
ii libc6 2.40-6
ii libgdbm6t64 1.24-2
ii libpipeline1 1.5.8-1
ii libseccomp2 2.5.5-2
ii zlib1g 1:1.3.dfsg+really1.3.1-1+b1
man-db recommends no packages.
Versions of packages man-db suggests:
pn apparmor <none>
ii firefox-esr [www-browser] 128.7.0esr-1
ii groff 1.23.0-7
ii less 643-1
ii lynx [www-browser] 2.9.2-1
ii w3m [www-browser] 0.5.3+git20230121-2.1
-- Configuration Files:
/etc/manpath.config changed [not included]
-- debconf information excluded
Input file is manpath.5
Output from "mandoc -T lint manpath.5": (shortened list)
-.-.
Output from "test-groff -mandoc -t -ww -z manpath.5": (shortened list)
1 Use macro '.I' for one argument or split argument.
1 .IR is for at least 2 arguments, got 1
-.-.
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 URLs (web address)
72 .IR /usr/share/man/newOS:/usr/share/man:/usr/local/man/newOS:/usr/local/man .
-.-.
Add a comma (or \&) after "e.g." and "i.e.", or use English words
(man-pages(7)).
Abbreviation points should be protected against being interpreted as
an end of sentence, if they are not, and that independent of the
current place on the line.
208:(e.g. "1 1mh 8 ...").
-.-.
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
manpath.5:203:If a particular extension is not in this list (say, 1mh) it will
be
manpath.5:217:cat pages will not be created (if missing) or displayed.
manpath.5:223:cat pages will not be created (if missing) or displayed.
-.-.
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.
13:.TH MANPATH 5 "2024-08-29" "2.13.0" "/etc/manpath.config"
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z
":
an.tmac:<stdin>:45: misuse, warning: .IR is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument.
--- manpath.5 2025-02-13 10:22:01.696592511 +0000
+++ manpath.5.new 2025-02-13 10:30:06.568965749 +0000
@@ -10,7 +10,7 @@
.\" Sat Oct 29 13:09:31 GMT 1994 Wilf. ([email protected])
.\"
.pc
-.TH MANPATH 5 "2024-08-29" "2.13.0" "/etc/manpath.config"
+.TH MANPATH 5 2024-08-29 2.13.0 /etc/manpath.config
.SH NAME
manpath \- format of the /etc/manpath.config file
.SH DESCRIPTION
@@ -42,7 +42,7 @@ then it adds all of
.IR path_element/man ,
.IR path_element/../share/man ,
and
-.IR path_element/share/man
+.I path_element/share/man
that exist as directories to the search path.
It then adds any
@@ -69,7 +69,7 @@ and
is set to
.IR newOS:man ,
then the final search path will be
-.IR /usr/share/man/newOS:/usr/share/man:/usr/local/man/newOS:/usr/local/man .
+.IR
/usr/share/man/newOS:\:/usr/share/man:\:/usr/local/man/newOS:\:/usr/local/man .
The
.RB $ MANPATH
@@ -200,12 +200,13 @@ If multiple
.B SECTION
directives are given, their section lists will be concatenated.
.PP
-If a particular extension is not in this list (say, 1mh) it will be
-displayed with the rest of the section it belongs to.
+If a particular extension is not in this list
+(say, 1mh)
+it will be displayed with the rest of the section it belongs to.
The effect of this is that you only need to explicitly list extensions if
you want to force a particular order.
Sections with extensions should usually be adjacent to their main section
-(e.g. "1 1mh 8 ...").
+(e.g., "1 1mh 8 ...").
.PP
.B SECTIONS
is accepted as an alternative name for this directive.
@@ -214,13 +215,17 @@ is accepted as an alternative name for t
.BI MINCATWIDTH \ width
If the terminal width is less than
.IR width ,
-cat pages will not be created (if missing) or displayed.
+cat pages will not be created
+(if missing)
+or displayed.
The default is 80.
.TP
.BI MAXCATWIDTH \ width
If the terminal width is greater than
.IR width ,
-cat pages will not be created (if missing) or displayed.
+cat pages will not be created
+(if missing)
+or displayed.
The default is 80.
.TP
.BI CATWIDTH \ width
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)
-.-
