Dear Maintainer,

here are some notes and editorial fixes for the man page.

Patch is in the attachment.

-.-.

The difference between the formatted outputs can be seen with:

  nroff -man <file1> > <out1>
  nroff -man <file2> > <out2>
  diff -u <out1> <out2>

and for groff, using

"groff -man -Z" instead of "nroff -man"

  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, 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 -z"

export MAN_KEEP_STDERR=yes (or any non-empty value)

-.-.

Output from "mandoc -T lint smartd.conf.5":

mandoc: smartd.conf.5:250:2: WARNING: line scope broken: SH breaks TP
mandoc: smartd.conf.5:600:81: STYLE: input text line longer than 80 bytes: It may also be used ...
mandoc: smartd.conf.5:1080:84: STYLE: input text line longer than 80 bytes: If \*(Aq@ALL\*(Aq is...

-.-.

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.

smartd.conf.5:2:Copyright (C) 2002-10 Bruce Allen
smartd.conf.5:3:Copyright (C) 2004-21 Christian Franke
smartd.conf.5:122:# Start short self\-tests daily between 1\-2, 2\-3, and
smartd.conf.5:123:# 3\-4 am.
smartd.conf.5:142:# Start short self\-tests daily between 1\-2, 2\-3, and
smartd.conf.5:143:# 3\-4 am.
smartd.conf.5:152:# 1 am and 2\-3 am
smartd.conf.5:173:# Start short self\-tests daily between 1\-2, 2\-3, and
smartd.conf.5:174:# 3\-4 am.
smartd.conf.5:192:# between midnight and 1 am and 2\-3 am.
smartd.conf.5:225:# Start short self\-tests daily between 1\-2, 2\-3, and
smartd.conf.5:226:# 3\-4 am.
smartd.conf.5:964:  smartctl \-t select,0\-99999999 /dev/sda
smartd.conf.5:969:\fB \-s n/../../[1\-5]/12\fP

-.-.

Wrong distance between sentences.

  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.

Seach for two words are 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.

167:# uses the cciss driver. Start long tests on Sunday nights and short
248:then the corresponding block device (/dev/sd?) must be listed,
371:then the corresponding SCSI (/dev/sd?) or character device (/dev/twe?,
372:/dev/twa?, /dev/twl? or /dev/tws?) must be listed, along with the
379:then the corresponding device (SCSI /dev/sg? on Linux or /dev/arcmsr0 on

-.-.

Protect a period (.) or a apostrophe (') with '\&' from becoming a
control character, if it could end up at the start of a line
(by splitting the line into more lines).

115:# flagged with the '\-d sat' option.  This situation
648:\fBsmartd\fP checks it.  This is the default behavior if the '\-n'
786:Appending ',ns' (no standby) to this directive is not implemented \"#
801:Appending ',ns' (no standby) to this directive is not implemented \"#
934:0, ... hours, use:
938:To enable staggered tests with delays 0, 1, 2, ..., 9, 10, 0, ... hours,

-.-.

Split a punctuation from a single argument, if a two-font macro is meant

64:.B /etc/smartd.conf.

-.-.

Use \(en for a dash (en-dash) between space characters and at the
beginning of a line, not a minus (\-) or a hyphen (-), except in the
NAME section.

smartd.conf.5:394:\- attempt to guess the device type from the device name or from
[... and more]
smartd.conf.5:1644:\- show the presets that are available for all drives and then exit.

-.-.

[ "test-groff" is a developmental version of "groff" ]

Input file is ./smartd.conf.5

Output from "test-groff -b -mandoc -dAD=l -rF0 -rHY=0 -t -w w -z ":

troff: backtrace: file '<stdin>':33
troff:<stdin>:33: warning: trailing space in the line
troff: backtrace: file '<stdin>':34
troff:<stdin>:34: warning: trailing space in the line
troff: backtrace: file '<stdin>':786
troff:<stdin>:786: warning: trailing space in the line
troff: backtrace: file '<stdin>':787
troff:<stdin>:787: warning: trailing space in the line
troff: backtrace: file '<stdin>':801
troff:<stdin>:801: warning: trailing space in the line
troff: backtrace: file '<stdin>':802
troff:<stdin>:802: warning: trailing space in the line

-.-.

Dear Bjarni,

thanks very much for the corrections/patches to the man pages.

I reviewed the diff and it looks good.  Something I was wondering: why
are you inserting the zero width characters '\&' in various places?  I
thought that there were only needed to avoid an input sequence being
misinterpreted as a control character.  But in many places where you
have inserted it, I did not realize that this was a possibility.

Cheers,
  Bruce

Dear Bjarni,

thanks very much for the corrections/patches to the man pages.

I reviewed the diff and it looks good.  Something I was wondering: why
are you inserting the zero width characters '\&' in various places?  I
thought that there were only needed to avoid an input sequence being
misinterpreted as a control character.  But in many places where you
have inserted it, I did not realize that this was a possibility.

Cheers,
  Bruce

  '\&' is, with the current layout of the source text, unnecessary,
but the position of the words can later change.
  So using '\&' is just a measure in advance.

  My explanation was:

Protect a period (.) or a apostrophe (') with '\&' from becoming a
control character, if it could end up at the start of a line
(by splitting the line into more lines).

  Can you suggest a better explanation?

  Maybe I should add after the sentence in parentheses:

"by reflowing, reorganising, reformatting the source text."

Extreme case: each word in a textual line is put in a separate line.

Thanks for the suggestions. Possibly too late for upcoming smartmontools
7.4, but will be addressed later.

In general, non-trivial syntax changes require tests with several
formatting tools including those used on Free/Net/OpenBSD. Changes shall
also work with older tool versions still used by LTS distributions.

Using \(en may make sense and is already used elsewhere in the man page
source files. This is IMO a minor issue. The visible difference with
"groff -man -Tpdf" is small.

The \& are not needed because we always format these files manually and
review plaintext and pdf formatted versions afterwards.

Please note that the patch itself could not be used because it only
fixes the generated Debian specific version of this page. This file
hides the info specific to other platforms in comments. See the long
MAN_FILTER macro in Makefile.am for the details.
The patch only addresses a single file. Such general changes should be
done for all four *.[58].in files from the sourcecode with a single commit.

Regards,
Christian

This makes sense -- thanks for the clarification!

Hi Bjarni,

this bug

and minor mandoc / groff warnings are now fixed upstream:

https://www.smartmontools.org/changeset/5506
https://www.smartmontools.org/changeset/5520

The remaining suggestions will be addressed after smartmontools 7.4 release.

BTW, tests with groff show that, unlike '\-', the '\(en' does not look
"nice" for numerical ranges because it is vertically aligned for
lowercase letters. This is the case with the default serif font T(imes)
and also the with sans-serif font H(elvetica).

Note that using '\(en' in the above text has no visible effect because
this section is always rendered with monospaced (.ft CW) font.

Where should .ss be used? I didn't find any example in your patch on
other man pages.

  "minus (in text) has different meaning than an "en-dash", consult a
style guide.

  It is not about how something is rendered, but about meaning (in the
source).

  This request is not used in man page sources.

  The request can only come from outside of the man page,
it is only for personal use, if the user wants to change the default
value.

  I only know of this possibility:
# example with one space between sentences

echo '.ss 12 0' | nroff -man -- - <man file>