Subject: alsamixer.1: some remarks and editorial changes for this man page

From: Bjarni Ingi Gislason <[email-masked]>
Date: Wed, 12 Jun 2024 00:17:09 +0000

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

Dear Maintainer,

   * What led up to the situation?

     Checking for defects with

[test-]groff -mandoc -t -K utf8 -ww -b -z < "man page"

  [test-groff is a script in the repository for "groff"]

   * What was the outcome of this action?

troff: backtrace: file '<stdin>':79
troff:<stdin>:79: warning: trailing space in the line
troff: backtrace: file '<stdin>':86
troff:<stdin>:86: warning: trailing space in the line
troff: backtrace: file '<stdin>':142
troff:<stdin>:142: warning: trailing space in the line
troff: backtrace: file '<stdin>':296
troff:<stdin>:296: warning: trailing space in the line
troff: backtrace: file '<stdin>':392
troff:<stdin>:392: warning: trailing space in the line

   * What outcome did you expect instead?

     No output (warnings).

-.-

  Remarks and a patch are in the attachments.

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

Kernel: Linux 6.7.12-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              32+20240327-1
ii  libasound2t64     1.2.11-1+b1
ii  libatopology2t64  1.2.11-1+b1
ii  libc6             2.38-12
ii  libfftw3-single3  3.3.10-1+b2
ii  libncursesw6      6.5-2
ii  libsamplerate0    0.2.2-4+b1
ii  libtinfo6         6.5-2

alsa-utils recommends no packages.

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

-- no debconf information
--- alsamixer.1	2024-06-11 14:20:35.165362104 +0000
+++ alsamixer.1.new	2024-06-11 22:05:25.914012508 +0000
@@ -7,7 +7,8 @@ alsamixer \- soundcard mixer for ALSA so
 
 .SH DESCRIPTION
 \fBalsamixer\fP is an ncurses mixer program for use with the ALSA
-soundcard drivers. It supports multiple soundcards with multiple devices.
+soundcard drivers.
+It supports multiple soundcards with multiple devices.
 
 .SH OPTIONS
 
@@ -17,8 +18,8 @@ Help: show available flags.
 
 .TP
 \fI\-c, \-\-card\fP <card number or identification>
-Select the soundcard to use, if you have more than one. Cards are
-numbered from 0 (the default).
+Select the soundcard to use, if you have more than one.
+Cards are numbered from 0 (the default).
 
 .TP
 \fI\-D, \-\-device\fP <device identification>
@@ -26,10 +27,11 @@ Select the mixer device to control.
 
 .TP
 \fI\-V, \-\-view\fP <mode>
-Select the starting view mode, either \fIplayback\fP, \fIcapture\fP or \fIall\fP.
+Select the starting view mode, either \fIplayback\fP, \fIcapture\fP or
+\fIall\fP.
 
 .TP
-\fI\-B, \-\-black-background\fP
+\fI\-B, \-\-black\-background\fP
 Use the black background color.
 
 .TP
@@ -73,17 +75,19 @@ item via up/down keys.
 \fBalsamixer\fP has three view modes: playback, capture and all.
 In the playback view, only the controls related with playback are shown.
 Similarly, only the controls for capture (recording) are shown in the capture
-view.  The all view mode shows all controls.  The current view mode is displayed
-in the top-left position together with the mixer name, etc.
+view.  The all view mode shows all controls.
+The current view mode is displayed in the top-left position together with
+the mixer name, etc.
 
-The default view mode is the playback view.  You can change it via 
-\fI-V\fP option.
+The default view mode is the playback view.  You can change it via
+\fI\-V\fP option.
 
 Each view mode can be switched via keyboard commands, too.
 See the next section.
 
 .SH KEYBOARD COMMANDS
-\fBalsamixer\fP recognizes the following keyboard commands to control the soundcard. 
+\fBalsamixer\fP recognizes the following keyboard commands to control the
+soundcard.
 Commands shown here in upper case can also be given in lower case.
 To be reminded of these keystrokes, hit the \fIh\fP key.
 
@@ -91,13 +95,14 @@ To be reminded of these keystrokes, hit
 General Controls
 
 The \fILeft\fP and \fIright arrow\fP keys are used to select the
-channel (or device, depending on your preferred terminology). You can
-also use \fIn\fP ("next") and \fIp\fP ("previous").
+channel (or device, depending on your preferred terminology).
+You can also use \fIn\fP ("next") and \fIp\fP ("previous").
 
 The \fIUp\fP and \fIDown Arrows\fP control the volume for the
-currently selected device. You can also use \fI+\fP or \fI\-\fP for the
-same purpose. Both the left and right signals are affected. For
-independent left and right control, see below.
+currently selected device.
+You can also use \fI+\fP or \fI\-\fP for the same purpose.
+Both the left and right signals are affected.
+For independent left and right control, see below.
  
 The \fIB\fP or \fI=\fP key adjusts the balance of volumes on left and
 right channels.
@@ -107,9 +112,10 @@ If the hardware supports it, you can
 mute left and right independently by using \fI,\fP (or \fI<\fP) and
 \fI.\fP (or \fI>\fP) respectively.
 
-\fISPACE\fP enables recording for the current channel. If any other
-channels have recording enabled, they will have their recording function
-disabled first. This only works for valid input channels, of course.
+\fISPACE\fP enables recording for the current channel.
+If any other channels have recording enabled,
+they will have their recording function disabled first.
+This only works for valid input channels, of course.
 
 \fIL\fP re-draws the screen.
 
@@ -137,9 +143,9 @@ Quick Volume Changes
 You can also control left & right levels for the current channel
 independently, as follows:
 
-[\fIQ\fP | \fIW\fP | \fIE\fP ]  -- turn UP [ left | both | right ]
+[\fIQ\fP | \fIW\fP | \fIE\fP ] \(en turn UP [ left | both | right ]
 
-[\fIZ\fP | \fIX\fP | \fIC\fP ] -- turn DOWN [ left | both | right ]   
+[\fIZ\fP | \fIX\fP | \fIC\fP ] \(en turn DOWN [ left | both | right ]
 
 If the currently selected mixer channel is not a stereo channel, then
 all UP keys will work like \fIW\fP, and all DOWN keys will work like \fIX\fP.
@@ -163,9 +169,10 @@ since it's regarded as a prefix key.
 
 .SH VOLUME MAPPING
 In \fBalsamixer\fP, the volume is mapped to a value that is more natural
-for a human ear.  The mapping is designed so that the position in the
-interval is proportional to the volume as a human ear would perceive
-it, i.e. the position is the cubic root of the linear sample
+for a human ear.
+The mapping is designed so that the position in the interval is proportional
+to the volume as a human ear would perceive it,
+i.e., the position is the cubic root of the linear sample
 multiplication factor.  For controls with a small range (24 dB or
 less), the mapping is linear in the dB values so that each step has
 the same size visually.
@@ -189,9 +196,11 @@ Comments start with '#'.
 .TP
 \fBcolor\fP \fIelement\fP \fIforeground\fP \fIbackground\fP [\fIattribute...\fP]
 
-Valid values for \fIforeground\fP and \fIbackground\fP are: red, green, yellow, blue, magenta, cyan, white, black, none / default.
+Valid values for \fIforeground\fP and \fIbackground\fP are:
+red, green, yellow, blue, magenta, cyan, white, black, none / default.
 
-Valid values for \fIattribute\fP are: bold, normal, reverse, underline, dim, italic, blink.
+Valid values for \fIattribute\fP are:
+bold, normal, reverse, underline, dim, italic, blink.
 
 See section \fBTHEME ELEMENTS\fP for a list of \fIelements\fP.
 
@@ -204,7 +213,9 @@ Set the mouse wheel step to \fI<N>\fP
 
 \fBmouse_wheel_focuses_control\fP \fI0|1\fP
 
-If enabled (\fI1\fP), mixer controls can be changed by hovering over them and scrolling the mouse wheel.
+If enabled (\fI1\fP),
+mixer controls can be changed by hovering over them
+and scrolling the mouse wheel.
 
 \fBbackground\fP \fIcolor\fP
 
@@ -214,12 +225,22 @@ Set the default background color
 \fBbind\fP \fIkey_definition\fP \fIcommand\fP
 
 A \fIkey_definition\fP may be:
-   - a single character
-   - a combination with control: C-a
-   - a combination with alt: M-a
-   - a special keyname: Enter, Escape, PageUp, PageDown, Left, Down, Right, Up, Home, End, Backspace, F1 .. F12
-
+.RS 7m
+.PD 0
+.IP \(en 2m
+a single character
+.IP \(en 2m
+a combination with control: C-a
+.IP \(en 2m
+a combination with alt: M-a
+.IP \(en 2m
+a special keyname: Enter, Escape, PageUp, PageDown, Left, Down, Right,
+Up, Home, End, Backspace, F1 \&..\& F12
+.PD 0
+.IP "" 0m
 See section \fBCOMMANDS\fP for a list of \fIcommands\fP.
+.RE
+.PD
 
 .SS COMMANDS
 
@@ -293,7 +314,7 @@ Change volume of current control to \fI<
 
 .TP
 \fImixer_control_up_<N>\fP[\fI_left\fP|\fI_right\fP]
-Increase volume of current control by \fI<N>\fP percent. 
+Increase volume of current control by \fI<N>\fP percent.
 
 .TP
 \fImixer_control_down_<N>\fP[\fI_left\fP|\fI_right\fP]
@@ -385,11 +406,10 @@ Show system information
 \fImenu_selected\fP Color used for selected entry in menu
 
 .SH SEE ALSO
-\fB
-amixer(1),
-aplay(1),
-arecord(1)
-\fP
+
+.BR amixer (1),
+.BR aplay (1),
+.BR arecord (1)
 
 .SH AUTHOR
 .B alsamixer