Debian Bug report logs - #1038855
speaker-test.1: Some remarks and editing fixes for the manual

Reply or subscribe to this bug.

Display info messages

Message #5 received at [email protected] (full text, mbox, reply):

From: Bjarni Ingi Gislason <[email protected]>

To: Debian Bug Tracking System <[email protected]>

Subject: speaker-test.1: Some remarks and editing fixes for the manual

Date: Wed, 21 Jun 2023 23:28:52 +0000

Package: alsa-utils
Version: 1.2.9-1
Severity: minor
Tags: patch

Dear Maintainer,

here are some notes and fixes for the manual.

Input file is speaker-test.1

Output from "mandoc -T lint speaker-test.1":

mandoc: speaker-test.1:30:2: ERROR: skipping all arguments: PP \fBaplay\fR's ...
mandoc: speaker-test.1:31:1: WARNING: skipping paragraph macro: sp after PP
mandoc: speaker-test.1:48:2: ERROR: skipping all arguments: PP Each ...
mandoc: speaker-test.1:100:177: STYLE: input text line longer than 80 bytes: Pink noise is percep...
mandoc: speaker-test.1:113:91: STYLE: input text line longer than 80 bytes: When \fB\-s\fP optio...
mandoc: speaker-test.1:118:87: STYLE: input text line longer than 80 bytes: Do a single-shot spe...
mandoc: speaker-test.1:119:82: STYLE: input text line longer than 80 bytes: The channel number c...
mandoc: speaker-test.1:122:92: STYLE: input text line longer than 80 bytes: For example, when 1 ...
mandoc: speaker-test.1:142:107: STYLE: input text line longer than 80 bytes: Allow supplied \fIFR...
mandoc: speaker-test.1:161:93: STYLE: input text line longer than 80 bytes: To send a nice low 7...

#######

Change '-' (\-) to '\(en' (en-dash) for a numeric range.

speaker-test.1:142: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 0x055, 2D) to an em-dash (\(em), if one
is intended.  An en-dash is usually surrounded by a space, while an em-dash
is used without spaces. "man" (1 byte characters) 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 "-" (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.

#####

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.

  The amount of space between sentences in the output can then be
controlled with the ".ss" request.

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
142:Allow supplied \fIFREQ\fP to be outside the default range of 30-8000Hz. A minimum of 1Hz is still enforced.

#####

Split lines longer than 100 characters into two or more lines.
Appropriate break points are the end of a sentence and a subordinate
clause; after punctuation marks.

speaker-test.1: 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.

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


#####

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

177:.BR aplay(1)

#####

--- speaker-test.1	2023-06-21 22:53:24.000000000 +0000
+++ speaker-test.1.new	2023-06-21 23:12:51.000000000 +0000
@@ -20,14 +20,17 @@ speaker\-test \- command\-line speaker t
 .SH DESCRIPTION
 \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
+\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.
+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
@@ -47,14 +50,12 @@ surround40:CARD=ICH5,DEV=0
 
 .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
+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
 
 .TP
@@ -97,29 +98,38 @@ stream of \fIRATE\fP Hz
 \fB\-t\fP | \fB\-\-test\fP \fBpink\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.
+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 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.
 
 .TP
 \fB\-l\fP | \fB\-\-nloops\fP \fICOUNT\fP
 
-Specifies the number of loops.  Zero means to run infinitely.
+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.
-The channel number corresponds to left, right, rear-left, rear-right, center, LFE,
+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
+For example,
+when 1 is passed,
+it tests the left channel only once rather than both channels
 with looping.
 
 .TP
@@ -139,7 +149,8 @@ required, pass the channel position stri
 
 .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
 
@@ -158,7 +169,8 @@ 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
@@ -174,7 +186,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.


-- System Information:
Debian Release: trixie/sid
  APT prefers testing
  APT policy: (500, 'testing')
Architecture: amd64 (x86_64)

Kernel: Linux 6.1.27-1 (SMP w/2 CPU threads; PREEMPT)
Kernel taint flags: TAINT_WARN
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              30+20230519-1
ii  libasound2        1.2.9-1
ii  libatopology2     1.2.9-1
ii  libc6             2.36-9
ii  libfftw3-single3  3.3.10-1
ii  libncursesw6      6.4-4
ii  libsamplerate0    0.2.2-3
ii  libtinfo6         6.4-4

alsa-utils recommends no packages.

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

-- no debconf information

Send a report that this bug log contains spam.