Subject: Bug#1099198: alsaucm.1: Some remarks and a patch with editorial changes for this man page

From: Bjarni Ingi Gislason <[email-masked]>
Date: Sat, 1 Mar 2025 15:36:33 +0000

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 ' $' -e '\\~$' <file>" to find obvious 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>:30: style: .TH missing fourth argument; consider package/project name and version (e.g., "groff 1.23.0")

   * 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.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              33+20240816-2
ii  libasound2t64     1.2.13-1+b1
ii  libatopology2t64  1.2.13-1+b1
ii  libc6             2.40-7
ii  libfftw3-single3  3.3.10-2+b1
ii  libncursesw6      6.5+20250216-1
ii  libsamplerate0    0.2.2-4+b2
ii  libtinfo6         6.5+20250216-1

alsa-utils recommends no packages.

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

-- no debconf information
--- alsaucm.1	2025-03-01 14:55:25.265148045 +0000
+++ alsaucm.1.new	2025-03-01 15:26:40.241393658 +0000
@@ -31,13 +31,14 @@ level margin: \\n[rst2man-indent\\n[rst2
 .SH NAME
 alsaucm \- ALSA Use Case Manager
 .SH SYNOPSIS
-.sp
-\fIalsaucm\fP <options> [command]
+.B alsaucm
+.IR <options> " [" command ]
 .SH DESCRIPTION
-.sp
-alsaucm (ALSA Use Case Manager) is a program to use the ALSA Use Case
-Interface <http://www.alsa-project.org/alsa-doc/alsa-lib/group__ucm.html>
- from the command line.
+alsaucm
+(ALSA Use Case Manager)
+is a program to use the ALSA Use Case
+Interface <http://www.alsa-project.org/\:alsa-doc/\:alsa-lib/\:group__ucm.html>
+from the command line.
 .sp
 On complex sound cards, setting up audio routes is not trivial and mixer
 settings can conflict one another preventing the audio card to work at all.
@@ -54,13 +55,14 @@ ALSA kcontrols to change the hardware di
 match the requested device use case.
 .sp
 The use case manager kcontrol configurations are stored in easy to modify text
-files. An audio use case can be defined by a \fBverb\fP and \fBdevice\fP parameter.
+files.
+An audio use case can be defined by a \fBverb\fP and \fBdevice\fP parameter.
 .sp
-The verb describes the use case action i.e. a phone call, listening to music,
-recording a conversation etc. The device describes the physical audio capture
-and playback hardware i.e. headphones, phone handset, bluetooth headset, etc.
+The verb describes the use case action i.e.\& a phone call, listening to music,
+recording a conversation etc.
+The device describes the physical audio capture
+and playback hardware i.e.\& headphones, phone handset, bluetooth headset, etc.
 .SH OPTIONS
-.sp
 Available options:
 .INDENT 0.0
 .INDENT 3.5
@@ -76,7 +78,8 @@ open card NAME
 interactive mode
 .TP
 .B \fB\-b\fP, \fB\-\-batch\fP \fIFILE\fP
-batch mode (use \fB\(aq\-\(aq\fP for the stdin input)
+batch mode
+(use \fB\(aq\-\(aq\fP for the stdin input)
 .TP
 .B \fB\-n\fP, \fB\-\-no\-open\fP
 do not open first card found
@@ -92,7 +95,7 @@ Available commands:
 .B \fBopen\fP \fINAME\fP
 open card NAME.
 .sp
-valid names are sound card names as listed in \fB/usr/share/alsa/ucm\fP\&.
+valid names are sound card names as listed in \fB/usr/share/alsa/ucm\fP.
 .TP
 .B \fBreset\fP
 reset sound card to default state.
@@ -109,11 +112,14 @@ list command, for items returning two en
 the value of the \fIIDENTIFIER\fP argument can be:
 .INDENT 7.0
 .IP \(bu 2
-\fB_verbs\fP \- get verb list (in pair verb+comment)
+\fB_verbs\fP \- get verb list \
+(in pair verb+comment)
 .IP \(bu 2
-\fB_devices[/{verb}]\fP \- get list of supported devices (in pair device+comment)
+\fB_devices[/{verb}]\fP \- get list of supported devices \
+(in pair device+comment)
 .IP \(bu 2
-\fB_modifiers[/{verb}]\fP \- get list of supported modifiers (in pair modifier+comment)
+\fB_modifiers[/{verb}]\fP \- get list of supported modifiers \
+(in pair modifier+comment)
 .UNINDENT
 .sp
 The forms without the trailing \fB/{verb}\fP are valid only after a specific
@@ -134,7 +140,8 @@ it can be:
 .IP \(bu 2
 \fB_supporteddevs/{modifier}|{device}[/{verb}]\fP \- list of supported devices
 .IP \(bu 2
-\fB_conflictingdevs/{modifier}|{device}[/{verb}]\fP \- list of conflicting devices
+\fB_conflictingdevs/{modifier}|{device}[/{verb}]\fP \- list of
+conflicting devices
 .UNINDENT
 .TP
 .B \fBget\fP \fIIDENTIFIER\fP
@@ -145,9 +152,9 @@ the value of the \fIIDENTIFIER\fP argume
 .IP \(bu 2
 \fB_verb\fP \- return current verb
 .IP \(bu 2
-\fB[=]{NAME}[/[{modifier}|{/device}][/{verb}]]\fP (For valid NAMEs look at the
-ALSA Use Case Interface <http://www.alsa-project.org/alsa-doc/alsa-lib/group__ucm.html>
-)
+\fB[=]{NAME}[/[{modifier}|{/device}][/{verb}]]\fP \
+(For valid NAMEs look at the ALSA Use Case Interface
+<http://www.alsa-project.org/\:alsa-doc/\:alsa-lib/\:group__ucm.html>)
 .UNINDENT
 .TP
 .B \fBgeti\fP \fIIDENTIFIER\fP
@@ -173,7 +180,7 @@ The value of the \fIIDENTIFIER\fP argume
 .IP \(bu 2
 \fB_disdev\fP \- disable the device specified by \fIVALUE\fP
 .IP \(bu 2
-\fB_swdev/{old_device}\fP \- switche device:
+\fB_swdev/{old_device}\fP \- switch device:
 .INDENT 2.0
 .IP \(bu 2
 disable \fIold_device\fP and then enable the device specified by
@@ -208,12 +215,12 @@ quit
 .UNINDENT
 .UNINDENT
 .SH FILES
-.sp
-The master use case files for each supported sound card are in \fB/usr/share/alsa/ucm\fP\&.
+The master use case files for each supported sound card are in
+\fB/usr/share/alsa/ucm\fP.
 .sp
 For example, the master use case file for the \fIPandaboard\fP card is in
 \fB/usr/share/alsa/ucm/PandaBoard/PandaBoard.conf\fP, this file lists all the
-supported use cases, e.g.
+supported use cases, e.g.\&
 .INDENT 0.0
 .INDENT 3.5
 .sp
@@ -231,12 +238,11 @@ Each use case defines a _verb, which is
 the \fBFile\fP directive, like above.
 .sp
 The \fBHiFi\fP verb above is described in
-\fB/usr/share/alsa/ucm/PandaBoard/hifi\fP\&.
+\fB/usr/share/alsa/ucm/PandaBoard/hifi\fP.
 .sp
 For more details on the syntax of UCM files, see the alsa\-lib source code:
- <http://git.alsa\-project.org/?p=alsa\-lib.git;a=blob;f=src/ucm/parser.c> 
+<http://git.alsa\-project.org/\:?p=alsa\-lib.git;a=blob;f=src/\:ucm/\:parser.c>
 .SH EXAMPLES OF USE
-.sp
 Some commands, like for instance \fBlist _devices\fP,
 can only work after setting a \fB_verb\fP in the \fBsame execution\fP, for
 instance this sequence doesn\(aqt work:
@@ -282,10 +288,10 @@ EOM
 .SH SEE ALSO
 .INDENT 0.0
 .IP \(bu 2
-Use Case Interface:  <http://www.alsa\-project.org/alsa\-doc/alsa\-lib/group__ucm.html> 
+Use Case Interface: \
+<http://www.alsa\-project.org/\:alsa\-doc/\:alsa\-lib/\:group__ucm.html>
 .UNINDENT
 .SH BUGS
-.sp
 None known.
 .SH AUTHOR
 Antonio Ospite <[email-masked]>