Bug#1087000: discover-pkginstall.8: Some remarks and editorial changes for this man page
Package: discover
Version: 2.1.2-10.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"
[Use "groff -e ' $' <file>" to find 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?
troff: backtrace: file '<stdin>':3
troff:<stdin>:3: warning: trailing space in the line
troff: backtrace: file '<stdin>':6
troff:<stdin>:6: warning: trailing space in the line
troff: backtrace: file '<stdin>':9
troff:<stdin>:9: warning: trailing space in the line
troff: backtrace: file '<stdin>':10
troff:<stdin>:10: warning: trailing space in the line
troff: backtrace: file '<stdin>':11
troff:<stdin>:11: warning: trailing space in the line
troff: backtrace: file '<stdin>':12
troff:<stdin>:12: warning: trailing space in the line
troff: backtrace: file '<stdin>':13
troff:<stdin>:13: warning: trailing space in the line
troff: backtrace: file '<stdin>':14
troff:<stdin>:14: warning: trailing space in the line
troff: backtrace: file '<stdin>':17
troff:<stdin>:17: warning: trailing space in the line
troff: backtrace: file '<stdin>':19
troff:<stdin>:19: warning: trailing space in the line
troff: backtrace: file '<stdin>':20
troff:<stdin>:20: warning: trailing space in the line
troff: backtrace: file '<stdin>':21
troff:<stdin>:21: warning: trailing space in the line
troff: backtrace: file '<stdin>':23
troff:<stdin>:23: warning: trailing space in the line
troff: backtrace: file '<stdin>':26
troff:<stdin>:26: 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.5-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 discover depends on:
ii debconf [debconf-2.0] 1.5.87
ii libc6 2.40-3
ii libdiscover2 2.1.2-10.1
discover recommends no packages.
Versions of packages discover suggests:
ii lsb-base 11.6
ii sysvinit-utils [lsb-base] 3.11-1
-- 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 output of the original and patched file
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)
-.-.
Output from "mandoc -T lint discover-pkginstall.8": (possibly shortened list)
mandoc: discover-pkginstall.8:1:2: WARNING: missing date, using "": TH
mandoc: discover-pkginstall.8:1:31: STYLE: whitespace at end of input line
mandoc: discover-pkginstall.8:2:12: STYLE: whitespace at end of input line
mandoc: discover-pkginstall.8:3:83: STYLE: input text line longer than 80 bytes: discover-pkginstall ...
mandoc: discover-pkginstall.8:3:83: STYLE: whitespace at end of input line
mandoc: discover-pkginstall.8:4:16: STYLE: whitespace at end of input line
mandoc: discover-pkginstall.8:5:2: WARNING: skipping paragraph macro: PP after SH
mandoc: discover-pkginstall.8:5:4: STYLE: whitespace at end of input line
mandoc: discover-pkginstall.8:6:47: STYLE: whitespace at end of input line
mandoc: discover-pkginstall.8:7:19: STYLE: whitespace at end of input line
mandoc: discover-pkginstall.8:8:2: WARNING: skipping paragraph macro: PP after SH
mandoc: discover-pkginstall.8:8:4: STYLE: whitespace at end of input line
mandoc: discover-pkginstall.8:9:49: STYLE: whitespace at end of input line
mandoc: discover-pkginstall.8:10:65: STYLE: whitespace at end of input line
mandoc: discover-pkginstall.8:11:61: STYLE: whitespace at end of input line
mandoc: discover-pkginstall.8:12:64: STYLE: whitespace at end of input line
mandoc: discover-pkginstall.8:13:64: STYLE: whitespace at end of input line
mandoc: discover-pkginstall.8:14:30: STYLE: whitespace at end of input line
mandoc: discover-pkginstall.8:15:15: STYLE: whitespace at end of input line
mandoc: discover-pkginstall.8:16:19: STYLE: whitespace at end of input line
mandoc: discover-pkginstall.8:17:32: STYLE: whitespace at end of input line
mandoc: discover-pkginstall.8:18:19: STYLE: whitespace at end of input line
mandoc: discover-pkginstall.8:19:25: STYLE: whitespace at end of input line
mandoc: discover-pkginstall.8:20:51: STYLE: whitespace at end of input line
mandoc: discover-pkginstall.8:21:6: STYLE: whitespace at end of input line
mandoc: discover-pkginstall.8:22:19: STYLE: whitespace at end of input line
mandoc: discover-pkginstall.8:23:12: STYLE: whitespace at end of input line
mandoc: discover-pkginstall.8:24:16: STYLE: whitespace at end of input line
mandoc: discover-pkginstall.8:25:2: WARNING: skipping paragraph macro: PP after SH
mandoc: discover-pkginstall.8:25:4: STYLE: whitespace at end of input line
mandoc: discover-pkginstall.8:26:46: STYLE: whitespace at end of input line
mandoc: discover-pkginstall.8:27:64: STYLE: whitespace at end of input line
-.-.
Remove space characters at the end of lines.
Use "git apply ... --whitespace=fix" to fix extra space issues, or use
global configuration "core.whitespace".
3:discover-pkginstall \(em intsall packages for available hardware using discover(1)
5:.PP
6:\fBdiscover-pkginstall\fR [\-l] [\-n] [\-v]
8:.PP
9:\fBdiscover-pkginstall\fR install packages based
10:on detected hardware. It will use the discover-data database to
11:map for hardware to debian packages, install the packages by
12:default. Packages using module-assistant will be automatically
13:built and the result installed if module-assistant is installed
14:or pulled in as a dependency.
16:.IP "\fB-l\fP" 10
17:Only list the detected packages
18:.IP "\fB-n\fP" 10
19:Echo the \fBaptitude
and
20:module-assistant\fR invocations instead of running
21:them.
22:.IP "\fB-v\fP" 10
23:Be verbose.
25:.PP
26:aptitude(8), discover(1), module-assistant(8)
27:.\" created by instant / docbook-to-man, Sun 13 Jan 2008, 09:40
-.-.
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.
16:.IP "\fB-l\fP" 10
18:.IP "\fB-n\fP" 10
22:.IP "\fB-v\fP" 10
-.-.
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.
Line 3, length 83
discover-pkginstall \(em intsall packages for available hardware using discover(1)
-.-.
Show if docman-to-man created this
27:.\" created by instant / docbook-to-man, Sun 13 Jan 2008, 09:40
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z ":
troff: backtrace: file '<stdin>':3
troff:<stdin>:3: warning: trailing space in the line
troff: backtrace: file '<stdin>':6
troff:<stdin>:6: warning: trailing space in the line
troff: backtrace: file '<stdin>':9
troff:<stdin>:9: warning: trailing space in the line
troff: backtrace: file '<stdin>':10
troff:<stdin>:10: warning: trailing space in the line
troff: backtrace: file '<stdin>':11
troff:<stdin>:11: warning: trailing space in the line
troff: backtrace: file '<stdin>':12
troff:<stdin>:12: warning: trailing space in the line
troff: backtrace: file '<stdin>':13
troff:<stdin>:13: warning: trailing space in the line
troff: backtrace: file '<stdin>':14
troff:<stdin>:14: warning: trailing space in the line
troff: backtrace: file '<stdin>':17
troff:<stdin>:17: warning: trailing space in the line
troff: backtrace: file '<stdin>':19
troff:<stdin>:19: warning: trailing space in the line
troff: backtrace: file '<stdin>':20
troff:<stdin>:20: warning: trailing space in the line
troff: backtrace: file '<stdin>':21
troff:<stdin>:21: warning: trailing space in the line
troff: backtrace: file '<stdin>':23
troff:<stdin>:23: warning: trailing space in the line
troff: backtrace: file '<stdin>':26
troff:<stdin>:26: warning: trailing space in the line
-.-
Additionally (general):
Spelling:
intsall -> install
pkgintsall -> pkginstall
install -> installs
-.-
Name of a manual is set in bold, the section in roman.
See man-pages(7).
24:aptitude(8), discover(1), module-assistant(8)
--- discover-pkginstall.8 2024-11-07 22:06:18.141106461 +0000
+++ discover-pkginstall.8.new 2024-11-07 22:27:46.184187878 +0000
@@ -1,27 +1,25 @@
-.TH "discover-pkgintsall" "8"
-.SH "NAME"
-discover-pkginstall \(em intsall packages for available hardware using discover(1)
-.SH "SYNOPSIS"
-.PP
-\fBdiscover-pkginstall\fR [\-l] [\-n] [\-v]
-.SH "Description"
-.PP
-\fBdiscover-pkginstall\fR install packages based
-on detected hardware. It will use the discover-data database to
-map for hardware to debian packages, install the packages by
-default. Packages using module-assistant will be automatically
-built and the result installed if module-assistant is installed
-or pulled in as a dependency.
-.SH "Options"
-.IP "\fB-l\fP" 10
-Only list the detected packages
-.IP "\fB-n\fP" 10
-Echo the \fBaptitude and
-module-assistant\fR invocations instead of running
-them.
-.IP "\fB-v\fP" 10
-Be verbose.
-.SH "See Also"
-.PP
-aptitude(8), discover(1), module-assistant(8)
-.\" created by instant / docbook-to-man, Sun 13 Jan 2008, 09:40
+.TH "discover-pkginstall" "8"
+.SH "NAME"
+discover-pkginstall \(em install packages for available hardware using \
+discover(1)
+.SH "SYNOPSIS"
+\fBdiscover-pkginstall\fR [\-l] [\-n] [\-v]
+.SH "Description"
+\fBdiscover-pkginstall\fR installs packages based
+on detected hardware. It will use the discover-data database to
+map for hardware to debian packages, install the packages by
+default. Packages using module-assistant will be automatically
+built and the result installed if module-assistant is installed
+or pulled in as a dependency.
+.SH "Options"
+.IP "\fB\-l\fP" 10
+Only list the detected packages
+.IP "\fB\-n\fP" 10
+Echo the \fBaptitude and
+module-assistant\fR invocations instead of running
+them.
+.IP "\fB\-v\fP" 10
+Be verbose.
+.SH "See Also"
+.BR aptitude "(8), " discover "(1), " module-assistant (8)
+.\" created by instant / docbook-to-man, Sun 13 Jan 2008, 09:40
Reply to: