Package: smartmontools
Version: 7.4-2
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>':37
troff:<stdin>:37: warning: trailing space in the line
troff: backtrace: file '<stdin>':38
troff:<stdin>:38: warning: trailing space in the line
troff: backtrace: '<stdin>':16: macro 'Vb'
troff: backtrace: file '<stdin>':315
troff:<stdin>:315: warning: font name 'CW' is deprecated
* 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.7-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 smartmontools depends on:
ii debianutils 5.21
ii libc6 2.40-3
ii libcap-ng0 0.8.5-3+b1
ii libgcc-s1 14.2.0-8
ii libselinux1 3.7-3+b1
ii libstdc++6 14.2.0-8
ii libsystemd0 256.7-3
ii sysvinit-utils 3.11-1
smartmontools recommends no packages.
Versions of packages smartmontools suggests:
ii curl 8.11.0-1
ii gpg 2.2.45-2
pn gsmartcontrol <none>
ii lynx 2.9.2-1
pn mailx | mailutils <none>
pn smart-notifier <none>
ii wget 1.24.5-2+b1
-- no debconf information
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 "test-groff -mandoc -t -ww -b -z smartctl.8": (shortened list)
1 font name 'CW' is deprecated
2 trailing space in the line
-.-.
Change '-' (\-) to '\(en' (en-dash) for a numeric range.
GNU gnulib has recently (2023-06-18) updated its
"build_aux/update-copyright" to recognize "\(en" in man pages.
smartctl.8:2:Copyright (C) 2002-10 Bruce Allen
smartctl.8:3:Copyright (C) 2004-23 Christian Franke
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.
1596:scan was unable to read (i.e. a defect). Entries, if any, show the
defective
2366:approach is running a tool like smartmontools inside the RAID 1 box (e.g.
2380:pending alerts after that page is fetched (i.e. read from
2383:command; so another initiator (e.g. a HBA on another machine) will still
2398:that behave normally (i.e. they don't change any state information in
-.-.
Wrong distance between sentences in the input file.
Separate the sentences and subordinate clauses; each begins on a new
line. See man-pages(7) ("Conventions for source file layout") and
"info groff" ("Input Conventions").
The best procedure is to always start a new sentence on a new line,
at least, if you are typing on a computer.
Remember coding: Only one command ("sentence") on each (logical) line.
E-mail: Easier to quote exactly the relevant lines.
Generally: Easier to edit the sentence.
Patches: Less unaffected text.
Search for two adjacent words is easier, when they belong to the same line,
and the same phrase.
The amount of space between sentences in the output can then be
controlled with the ".ss" request.
37:[This man page is generated for the Linux version of smartmontools. \"#
523:127 inclusive) denotes which disk on the controller is monitored. This
interface
612:and /dev/twe? do not exist, or exist with the incorrect major or minor
1596:scan was unable to read (i.e. a defect). Entries, if any, show the
defective
1598:scan found the defect. Note these pending defects may appear in advance of
any
1604:page. This includes one or more temperatures and may include relative
1605:humidities. Lifetime maximums and minimums are also reported.
1626:prints values and descriptions of the (SSC) Tape Alert log page. See
2067: /* ... */
2372:INCITS 516\-2013). SSC stands for "SCSI Streaming Commands". Draft
2377:to report abnormal conditions. Unlike most other log pages the TapeAlert
2380:pending alerts after that page is fetched (i.e. read from
2381:the tape drive). To be more precise, the TapeAlert log page is cleared
2384:have pending alerts reported. [This clearing action can be controlled by
2390:page when the \-\-health option is given. This clearing of pending alerts
2391:has created problems for other tape\-specific tools. This version of
2398:that behave normally (i.e. they don't change any state information in
-.-.
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 91, length 82
.\"# Long forms are also available: please use \*(Aq\-h\*(Aq to see some
examples.
Line 103, length 85
.\"# devices and \fB"/dev/da[0\-9]+"\fP or \fB"/dev/pass[0\-9]+"\fP for SCSI
devices.
Line 104, length 83
.\"# For SATA devices on AHCI bus use \fB"/dev/ada[0\-9]+"\fP format. For HP
Smart
Line 142, length 82
.\"# to run the \*(Aqtw_cli\*(Aq tool and parse the output. This provides
limited
Line 153, length 81
.\"# The AMD RAID driver may return incomplete information about port
assignment.
Line 160, length 82
.\"#
\fB[HKLM\\SYSTEM\\CurrentControlSet\\Services\\rcraid\\Parameters\\Device]\fP
Line 176, length 83
.\"# Alternatively use the forms \fB"/dev/nvmes[0\-9][n[1\-9]]"\fP for NVMe
devices
Line 191, length 83
.\"# Use the form \fB"/dev/hd[a\-z]"\fP for ATA/SATA devices using DANIS506
driver.
Line 193, length 84
.\"# Use the form \fB"/dev/ahci[a\-z]"\fP for ATA/SATA devices using OS2AHCI
driver.
Line 521, length 87
\- [FreeBSD and Linux only] the device consists of one or more SCSI/SAS disks
connected
Line 695, length 81
\fBsmartctl \-a \-d cciss,0 /dev/sg2\fP (hpsa or hpahcisr drivers under
Linux)
Line 1056, length 82
\*(Aq\-g aam \-g apm \-g lookahead \-g security \-g wcache \-g rcache \-g
dsn\*(Aq
Line 1345, length 84
\fBICRC\fP: \fBI\fPnterface \fBC\fPyclic \fBR\fPedundancy \fBC\fPode (CRC)
error
Line 2474, length 92
.B smartctl \-t select,10\-100 \-t select,30\-300 \-t afterselect,on \-t
pending,45 /dev/sda
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z ":
troff: backtrace: file '<stdin>':37
troff:<stdin>:37: warning: trailing space in the line
troff: backtrace: file '<stdin>':38
troff:<stdin>:38: warning: trailing space in the line
troff: backtrace: '<stdin>':16: macro 'Vb'
troff: backtrace: file '<stdin>':315
troff:<stdin>:315: warning: font name 'CW' is deprecated
