speaker-test.1: Some remarks and a patch with editorial changes for this man page

Package: alsa-utils
Version: 1.2.13-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 ' $' <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?

an.tmac:<stdin>:183: misuse, warning: .BR is for at least 2 arguments, got 1
	Use macro '.B' 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.6-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 alsa-utils depends on:
ii  kmod              33+20240816-2
ii  libasound2t64     1.2.13-1+b1
ii  libatopology2t64  1.2.13-1+b1
ii  libc6             2.40-4
ii  libfftw3-single3  3.3.10-2+b1
ii  libncursesw6      6.5-2+b1
ii  libsamplerate0    0.2.2-4+b2
ii  libtinfo6         6.5-2+b1

alsa-utils recommends no packages.

Versions of packages alsa-utils suggests:
pn  dialog  <none>

-- no debconf information
Input file is speaker-test.1

  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  speaker-test.1": (shortened list)

     10 input text line longer than 80 bytes
      2 skipping all arguments
      1 skipping paragraph macro

-.-.

Output from "test-groff -mandoc -t -ww -z speaker-test.1": (shortened list)

      1 	Use macro '.B' for one argument or split argument.
      1 .BR is for at least 2 arguments, got 1

-.-.

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.

speaker-test.1:148:Allow supplied \fIFREQ\fP to be outside the default range of 30-8000Hz. A minimum of 1Hz is still enforced.

-.-.

Change two HYPHEN-MINUSES (code 0x2D) to an em-dash (\(em),
if one is intended.
  " \(em " creates a too big gap in the text (in "troff").

An en-dash is usually surrounded by a space,
while an em-dash is used without spaces.
"man" (1 byte characters in input) transforms an en-dash (\(en) to one
HYPHEN-MINUS,
and an em-dash to two HYPHEN-MINUSES without considering the space
around it.
If "--" are two single "-"
(begin of an option or end of options)
then use "\-\-".

speaker-test.1:100:Pink noise is perceptually uniform noise -- that is, it sounds like every frequency at once.  If you can hear any tone it may indicate resonances in your speaker system or room.

-.-.

Change (or include a "FIXME" paragraph about) misused SI (metric)
numeric prefixes (or names) to the binary ones, like Ki (kibi), Mi
(mebi), Gi (gibi), or Ti (tebi), if indicated.
If the metric prefixes are correct, add the definitions or an
explanation to avoid misunderstanding.

106:Note that sampling rates less than 48KHz are outside the scope of the spec, and an attempt will be made to construct a reduced rate filter.

-.-.

Add a (no-break, "\ " or "\~") space between a number and a unit,
as these are not one entity.

106:Note that sampling rates less than 48KHz are outside the scope of the spec, and an attempt will be made to construct a reduced rate filter.

-.-.

Change - to \- if it shall be printed as a minus sign.

speaker-test.1:102:\fB\-t st2095\fP means use bandlimited pink noise at -18.5dB AES FS, generated according to SMPTE ST-2095:1-2015.

-.-.

Move a full stop (period) and a comma outside of a quoted text, if it is
at the end of the quote and does not end a quoted sentence.

105:electroacoustic response of a cinema B-chain system."

-.-.

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.

Mark a final abbreviation point as such by suffixing it with "\&".


23:\fBspeaker\-test\fP by default will test the \fIdefault\fP device. If you
26:those cards. Notice that there might be for example, one device for
50:and surround40. So, if you want to test the last device you can
51:run \fBspeaker\-test \-Dsurround40:ICH5 \-c 6\fR. The \fB\-c\fR option will
148:Allow supplied \fIFREQ\fP to be outside the default range of 30-8000Hz. A minimum of 1Hz is still enforced.

-.-.

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 21, length 89

\fBspeaker\-test\fP generates a tone that can be used to test the speakers of a computer.

Line 100, length 177

Pink noise is perceptually uniform noise -- that is, it sounds like every frequency at once.  If you can hear any tone it may indicate resonances in your speaker system or room.

Line 102, length 113

\fB\-t st2095\fP means use bandlimited pink noise at -18.5dB AES FS, generated according to SMPTE ST-2095:1-2015.

Line 103, length 147

In addition to speaker localization it may be used for system calibration, for example 85dB for thater drivers, with an extra +10dB for subwoofers.

Line 104, length 84

Per the spec, it is intended "to be used in calibrating the sound pressure level and

Line 106, length 139

Note that sampling rates less than 48KHz are outside the scope of the spec, and an attempt will be made to construct a reduced rate filter.

Line 110, length 94

\fB\-t wav\fP means to play WAV files, either pre-defined files or given via \fB\-w\fP option.

Line 119, length 91

When \fB\-s\fP option below with a valid channel is given, \fBspeaker\-test\fP will perform

Line 124, length 87

Do a single-shot speaker test for the given channel.  The channel number starts from 1.

Line 125, length 82

The channel number corresponds to left, right, rear-left, rear-right, center, LFE,

Line 128, length 92

For example, when 1 is passed, it tests the left channel only once rather than both channels

Line 148, length 107

Allow supplied \fIFREQ\fP to be outside the default range of 30-8000Hz. A minimum of 1Hz is still enforced.

Line 167, length 93

To send a nice low 75Hz tone to the Woofer and then exit without touching any other speakers:

-.-.

Use the name of units in text; use symbols in tables and
calculations.
The rule is to have a (no-break, \~) space between a number and
its units (see "www.bipm.org/en/publications/si-brochure")

102:\fB\-t st2095\fP means use bandlimited pink noise at -18.5dB AES FS, generated according to SMPTE ST-2095:1-2015.
103:In addition to speaker localization it may be used for system calibration, for example 85dB for thater drivers, with an extra +10dB for subwoofers.
106:Note that sampling rates less than 48KHz are outside the scope of the spec, and an attempt will be made to construct a reduced rate filter.
148:Allow supplied \fIFREQ\fP to be outside the default range of 30-8000Hz. A minimum of 1Hz is still enforced.
167:To send a nice low 75Hz tone to the Woofer and then exit without touching any other speakers:

-.-.

Name of a manual is set in bold, the section in roman.
See man-pages(7).

183:.BR aplay(1)

-.-.

Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
Not considered in a patch, too many lines.


speaker-test.1:172:To do a 2\-speaker test using the spdif (coax or optical) output:

-.-.

Use a no-break space between a number and a (SI) unit

148:Allow supplied \fIFREQ\fP to be outside the default range of 30-8000Hz. A minimum of 1Hz is still enforced.
167:To send a nice low 75Hz tone to the Woofer and then exit without touching any other speakers:

-.-.

Put a subordinate sentence (after a comma) on a new line.

26:those cards. Notice that there might be for example, one device for
27:analog sound, one for digital sound and one for HDMI sound.
49:in the above example, there are four devices listed: null, default, front
50:and surround40. So, if you want to test the last device you can
79:When 0 is given, use the maximal buffer size.
85:When 0 is given, the periods given by \fB\-P\fP option is used.
100:Pink noise is perceptually uniform noise -- that is, it sounds like every frequency at once.  If you can hear any tone it may indicate resonances in your speaker system or room.
102:\fB\-t st2095\fP means use bandlimited pink noise at -18.5dB AES FS, generated according to SMPTE ST-2095:1-2015.
103:In addition to speaker localization it may be used for system calibration, for example 85dB for thater drivers, with an extra +10dB for subwoofers.
104:Per the spec, it is intended "to be used in calibrating the sound pressure level and
106:Note that sampling rates less than 48KHz are outside the scope of the spec, and an attempt will be made to construct a reduced rate filter.
110:\fB\-t wav\fP means to play WAV files, either pre-defined files or given via \fB\-w\fP option.
119:When \fB\-s\fP option below with a valid channel is given, \fBspeaker\-test\fP will perform
125:The channel number corresponds to left, right, rear-left, rear-right, center, LFE,
126:side-left, side-right, and so on.
128:For example, when 1 is passed, it tests the left channel only once rather than both channels
144:required, pass the channel position strings to this option.

-.-.

Output from "test-groff  -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z ":

an.tmac:<stdin>:183: misuse, warning: .BR is for at least 2 arguments, got 1
	Use macro '.B' for one argument or split argument.