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.
--- speaker-test.1 2025-01-10 23:55:38.162393206 +0000
+++ speaker-test.1.new 2025-01-11 21:26:59.088889888 +0000
@@ -15,19 +15,25 @@
.SH NAME
speaker\-test \- command\-line speaker test tone generator for ALSA
.SH SYNOPSIS
-.B speaker\-test [\-options]
+.BR speaker\-test\ [ \fIoptions\fR ]
.SH DESCRIPTION
-\fBspeaker\-test\fP generates a tone that can be used to test the speakers of a computer.
+\fBspeaker\-test\fP generates a tone that can be used to test the speakers
+of a computer.
-\fBspeaker\-test\fP by default will test the \fIdefault\fP device. If you
-want to test another sound device you will have first to get a list of
-all of the sound cards in your system and the devices associated with
-those cards. Notice that there might be for example, one device for
-analog sound, one for digital sound and one for HDMI sound.
-To get the list of available cards and devices you can run \fBaplay \-L\fR.
+\fBspeaker\-test\fP by default will test the \fIdefault\fP device.
+If you want to test another sound device
+you will have first to get a list of all of the sound cards in your system
+and the devices associated with those cards.
+Notice that there might be for example,
+one device for analog sound,
+one for digital sound
+and one for HDMI sound.
+To get the list of available cards
+and devices you can run \fBaplay \-L\fR.
-.P \fBaplay\fR's output will be similar to this one:
+.P
+\fBaplay\fR's output will be similar to this one:
.nf
$ aplay \-L
@@ -45,15 +51,15 @@ surround40:CARD=ICH5,DEV=0
(...)
.fi
-.P Each of the devices is listed in the beginning of the definition so,
-in the above example, there are four devices listed: null, default, front
-and surround40. So, if you want to test the last device you can
-run \fBspeaker\-test \-Dsurround40:ICH5 \-c 6\fR. The \fB\-c\fR option will
-indicate that the six audio channels in the device have to be tested.
-
-
-
-
+.P
+Each of the devices is listed in the beginning of the definition so,
+in the above example,
+there are four devices listed:
+null, default, front and surround40.
+So, if you want to test the last device
+you can run \fBspeaker\-test \-Dsurround40:ICH5 \-c 6\fR.
+The \fB\-c\fR option will indicate
+that the six audio channels in the device have to be tested.
.SH OPTIONS
@@ -76,13 +82,15 @@ Print usage help
.TP
\fB\-b\fP | \fB\-\-buffer\fP \fITIME\fP
Use buffer size of \fITIME\fP microseconds.
-When 0 is given, use the maximal buffer size.
+When 0 is given,
+use the maximal buffer size.
The default value is 0.
.TP
\fB\-p\fP | \fB\-\-period\fP \fITIME\fP
Use period size of \fITIME\fP microseconds.
-When 0 is given, the periods given by \fB\-P\fP option is used.
+When 0 is given,
+the periods given by \fB\-P\fP option is used.
The default value is 0.
.TP
@@ -97,17 +105,27 @@ stream of \fIRATE\fP Hz
\fB\-t\fP | \fB\-\-test\fP \fBpink\fP|\fBst2095\fP|\fBsine\fP|\fBwav\fP
\fB\-t pink\fP means use pink noise (default).
-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.
-
-\fB\-t st2095\fP means use bandlimited pink noise at -18.5dB AES FS, generated according to SMPTE ST-2095:1-2015.
-In addition to speaker localization it may be used for system calibration, for example 85dB for thater drivers, with an extra +10dB for subwoofers.
-Per the spec, it is intended "to be used in calibrating the sound pressure level and
-electroacoustic response of a cinema B-chain system."
-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.
+Pink noise is perceptually uniform noise \(en 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.
+
+\fB\-t st2095\fP means use bandlimited pink noise at \-18.5\~dB AES FS,
+generated according to SMPTE ST-2095:1-2015.
+In addition to speaker localization it may be used for system calibration,
+for example 85\~dB for thater drivers,
+with an extra +10\~dB for subwoofers.
+Per the spec,
+it is intended
+"to be used in calibrating the sound pressure level
+and electroacoustic response of a cinema B-chain system".
+Note that sampling rates less than 48\~kHz are outside the scope of the spec,
+and an attempt will be made to construct a reduced rate filter.
\fB\-t sine\fP means to use sine wave.
-\fB\-t wav\fP means to play WAV files, either pre-defined files or given via \fB\-w\fP option.
+\fB\-t wav\fP means to play WAV files,
+either pre-defined files or given via \fB\-w\fP option.
You can pass the number from 1 to 3 as a backward compatibility.
@@ -116,17 +134,20 @@ You can pass the number from 1 to 3 as a
Specifies the number of loops. Zero means to run infinitely.
-When \fB\-s\fP option below with a valid channel is given, \fBspeaker\-test\fP will perform
-always a single-shot without looping.
+When \fB\-s\fP option below with a valid channel is given,
+\fBspeaker\-test\fP will perform always a single-shot without looping.
.TP
\fB\-s\fP | \fB\-\-speaker\fP \fICHANNEL\fP
-Do a single-shot speaker test for the given channel. The channel number starts from 1.
+Do a single-shot speaker test for the given channel.
+The channel number starts from 1.
The channel number corresponds to left, right, rear-left, rear-right, center, LFE,
side-left, side-right, and so on.
-For example, when 1 is passed, it tests the left channel only once rather than both channels
-with looping.
+For example,
+when 1 is passed,
+it tests the left channel only once
+rather than both channels with looping.
.TP
\fB\-w\fP | \fB\-\-wavfile\fP \fIFILE\fP
@@ -140,13 +161,15 @@ The default path is \fI/usr/share/sounds
.TP
\fB\-m\fP | \fB\-\-chmap\fP \fIMAP\fP
Pass the channel map to override.
-If the playback in a specific channel order or channel positions is
-required, pass the channel position strings to this option.
+If the playback in a specific channel order
+or channel positions
+is required,
+pass the channel position strings to this option.
.TP
\fB\-X\fP | \fB\-\-force-frequency\fP
-Allow supplied \fIFREQ\fP to be outside the default range of 30-8000Hz. A minimum of 1Hz is still enforced.
-
+Allow supplied \fIFREQ\fP to be outside the default range of 30\(en8000\~Hz.
+A minimum of 1\~Hz is still enforced.
.SH USAGE EXAMPLES
Produce stereo sound from one stereo jack:
@@ -164,12 +187,15 @@ Produce 5.1 speaker sound from three ste
speaker\-test \-Dplug:surround51 \-c6
.EE
-To send a nice low 75Hz tone to the Woofer and then exit without touching any other speakers:
+To send a nice low 75\~Hz tone to the Woofer
+and then exit without touching any other speakers:
.EX
speaker\-test \-Dplug:surround51 \-c6 \-s1 \-f75
.EE
-To do a 2\-speaker test using the spdif (coax or optical) output:
+To do a 2\-speaker test using the spdif
+(coax or optical)
+output:
.EX
speaker\-test \-Dplug:spdif \-c2
.EE
@@ -180,7 +206,7 @@ Play in the order of front\-right and fr
.EE
.SH SEE ALSO
-.BR aplay(1)
+.BR aplay (1)
.SH AUTHOR
The speaker\-test program was written by James Courtier-Dutton.
