Package: alsa-utils
Version: 1.2.14-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
grep -n -e ' $' -e '\\~$' -e ' \\f.$' -e ' \\"' <file>
to find (most) 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?
troff:<stdin>:258: warning: trailing space in the line
* 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: 13.0
APT prefers testing-security
APT policy: (500, 'testing-security'), (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.12.32-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 34.2-2
ii libasound2t64 1.2.14-1
ii libatopology2t64 1.2.14-1
ii libc6 2.41-8
ii libfftw3-single3 3.3.10-2+b1
ii libncursesw6 6.5+20250216-2
ii libsamplerate0 0.2.2-4+b2
ii libtinfo6 6.5+20250216-2
alsa-utils recommends no packages.
Versions of packages alsa-utils suggests:
pn dialog <none>
-- no debconf information
Input file is aplay.1
Output from "mandoc -T lint aplay.1": (shortened list)
9 input text line longer than 80 bytes
-.-.
Output from
test-nroff -mandoc -t -ww -z aplay.1: (shortened list)
1 line(s) with a trailing space
-.-.
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.
14:automatically split before the 2GB filesize.
-.-.
Reduce space between words.
aplay.1:187:This option has no effect if \-\-separate\-channels is
-.-.
Add a (no-break, "\ " or "\~") space between a number and a unit,
as these are not one entity.
14:automatically split before the 2GB filesize.
-.-.
Change a HYPHEN-MINUS (code 0x2D) to a minus(-dash) (\-),
if it
is in front of a name for an option,
is a symbol for standard input,
is a single character used to indicate an option,
or is in the NAME section (man-pages(7)).
N.B. - (0x2D), processed as a UTF-8 file, is changed to a hyphen
(0x2010, groff \[u2010] or \[hy]) in the output.
79:Either '-d' or '-s' option is available exclusively.
85:Either '-d' or '-s' option is available exclusively.
148:\fI-m, \-\-chmap=ch1,ch2,...\fP
-.-.
Add a "\&" (or a comma (Oxford comma)) after an abbreviation
or use English words
(man-pages(7)).
Abbreviation points should be marked as such and protected against being
interpreted as an end of sentence, if they are not, and that independent
of the current place on the line.
211:Disables recovery attempts when errors (e.g. xrun) are encountered; the
-.-.
Wrong distance (not two spaces) 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 "\&".
Some sentences (etc.) do not begin on a new line.
Split (sometimes) lines after a punctuation mark; before a conjunction.
Lines with only one (or two) space(s) between sentences could be split,
so latter sentences begin on a new line.
Use
#!/usr/bin/sh
sed -e '/^\./n' \
-e 's/\([[:alpha:]]\)\. */\1.\n/g' $1
to split lines after a sentence period.
Check result with the difference between the formatted outputs.
See also the attachment "general.bugs"
12:driver. It supports several file formats and multiple soundcards with
13:multiple devices. If recording with interleaved mode samples the file is
16:\fBaplay\fP is much the same, only it plays instead of recording. For
20:If filename is not specified, the standard output or input is used. The \fBaplay\fP utility accepts multiple filenames.
40:Quiet mode. Suppress messages (not sound :))
71:Sampling rate in Hertz. The default rate is 8000 Hertz.
92:Open the audio device in non\-blocking mode. If the device is busy the program will exit immediately.
204:Dump hw_params of the device preconfigured status to stderr. The dump
211:Disables recovery attempts when errors (e.g. xrun) are encountered; the
-.-.
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.
Add "\:" to split the string for the output, "\<newline>" in the source.
Line 20, length 119
If filename is not specified, the standard output or input is used. The \fBaplay\fP utility accepts multiple filenames.
Line 78, length 111
The default is zero, so if this option is omitted then the record/playback process will run until it is killed.
Line 84, length 112
The default is zero, so if this options is omitted then the record/playback process will run until it is killed.
Line 92, length 101
Open the audio device in non\-blocking mode. If the device is busy the program will exit immediately.
Line 93, length 91
If this option is not set the program will block until the audio device is available again.
Line 97, length 87
If no period time and no period size is given then a quarter of the buffer time is set.
Line 101, length 114
If no buffer time and no buffer size is given then the maximal allowed buffer time but not more than 500ms is set.
Line 105, length 87
If no period size and no period time is given then a quarter of the buffer size is set.
Line 109, length 114
If no buffer time and no buffer size is given then the maximal allowed buffer time but not more than 500ms is set.
Line 249, length 99
\fBarecord \-f cd \-t wav \-\-max\-file\-time 3600 \-\-use-strftime %Y/%m/%d/listen-%H-%M-%v.wav\fP
Longest line is number 20 with 119 characters
-.-.
The name of a man page is typeset in bold and the section in roman
(see man-pages(7)).
256:alsamixer(1),
257:amixer(1)
-.-.
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
aplay.1:40:Quiet mode. Suppress messages (not sound :))
aplay.1:43:File type (voc, wav, raw or au).
aplay.1:64:\-f cd (16 bit little endian, 44100, stereo) [\-f S16_LE \-c2 \-r44100]
aplay.1:65:\-f cdr (16 bit big endian, 44100, stereo) [\-f S16_BE \-c2 \-r44100]
aplay.1:66:\-f dat (16 bit little endian, 48000, stereo) [\-f S16_LE \-c2 \-r48000]
aplay.1:176:Expression for validation is: coef * (buffer_size / 2).
aplay.1:211:Disables recovery attempts when errors (e.g. xrun) are encountered; the
-.-.
Use a no-break space between a number and a (SI) unit
101:If no buffer time and no buffer size is given then the maximal allowed buffer time but not more than 500ms is set.
109:If no buffer time and no buffer size is given then the maximal allowed buffer time but not more than 500ms is set.
-.-.
Only one space character is after a possible end of sentence
(after a punctuation, that can end a sentence).
aplay.1:12:driver. It supports several file formats and multiple soundcards with
aplay.1:13:multiple devices. If recording with interleaved mode samples the file is
aplay.1:16:\fBaplay\fP is much the same, only it plays instead of recording. For
aplay.1:20:If filename is not specified, the standard output or input is used. The \fBaplay\fP utility accepts multiple filenames.
aplay.1:40:Quiet mode. Suppress messages (not sound :))
aplay.1:71:Sampling rate in Hertz. The default rate is 8000 Hertz.
aplay.1:92:Open the audio device in non\-blocking mode. If the device is busy the program will exit immediately.
aplay.1:204:Dump hw_params of the device preconfigured status to stderr. The dump
aplay.1:211:Disables recovery attempts when errors (e.g. xrun) are encountered; the
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=0 -ww -z ":
troff:<stdin>:258: warning: trailing space in the line
-.-
Generally:
Split (sometimes) lines after a punctuation mark; before a conjunction.
--- aplay.1 2025-06-20 10:46:13.551368006 +0000
+++ aplay.1.new 2025-06-20 18:27:14.304560168 +0000
@@ -11,7 +11,7 @@ soundcard driver
\fBarecord\fP is a command\-line soundfile recorder for the ALSA soundcard
driver. It supports several file formats and multiple soundcards with
multiple devices. If recording with interleaved mode samples the file is
-automatically split before the 2GB filesize.
+automatically split before the 2\~GiB filesize.
\fBaplay\fP is much the same, only it plays instead of recording. For
supported soundfile formats, the sampling rate, bit depth, and so
@@ -76,13 +76,13 @@ Valid values are 2000 through 192000 Her
Interrupt after # seconds.
A value of zero means infinity.
The default is zero, so if this option is omitted then the record/playback process will run until it is killed.
-Either '-d' or '-s' option is available exclusively.
+Either '\-d' or '\-s' option is available exclusively.
.TP
\fI\-s, \-\-samples=#\fP
Interrupt after transmission of # PCM frames.
A value of zero means infinity.
The default is zero, so if this options is omitted then the record/playback process will run until it is killed.
-Either '-d' or '-s' option is available exclusively.
+Either '\-d' or '\-s' option is available exclusively.
.TP
\fI\-M, \-\-mmap\fP
Use memory\-mapped (mmap) I/O mode for the audio stream.
@@ -98,7 +98,8 @@ If no period time and no period size is
.TP
\fI\-B, \-\-buffer\-time=#\fP
Buffer duration is # microseconds
-If no buffer time and no buffer size is given then the maximal allowed buffer time but not more than 500ms is set.
+If no buffer time and no buffer size is given
+then the maximal allowed buffer time but not more than 500\~ms is set.
.TP
\fI\-\-period\-size=#\fP
Distance between interrupts is # frames
@@ -106,7 +107,8 @@ If no period size and no period time is
.TP
\fI\-\-buffer\-size=#\fP
Buffer duration is # frames
-If no buffer time and no buffer size is given then the maximal allowed buffer time but not more than 500ms is set.
+If no buffer time and no buffer size is given then the maximal allowed
+buffer time but not more than 500\~ms is set.
.TP
\fI\-A, \-\-avail\-min=#\fP
Min available space for wakeup is # microseconds
@@ -145,7 +147,7 @@ by typing arecord.
Allow interactive operation via stdin.
Currently only pause/resume via space or enter key is implemented.
.TP
-\fI-m, \-\-chmap=ch1,ch2,...\fP
+\fI\-m, \-\-chmap=ch1,ch2,...\fP
Give the channel map to override or follow. Pass channel position
strings like \fIFL\fP, \fIFR\fP, etc.
@@ -184,7 +186,7 @@ While recording, when the output file ha
sound for this long,
close it and open a new output file. Default is the maximum
size supported by the file format: 2 GiB for WAV files.
-This option has no effect if \-\-separate\-channels is
+This option has no effect if \-\-separate\-channels is
specified.
.TP
\fI\-\-process\-id\-file <file name>\fP
@@ -208,7 +210,7 @@ For raw device hw:X this option basicall
the soundcard.
.TP
\fI\-\-fatal\-errors\fP
-Disables recovery attempts when errors (e.g. xrun) are encountered; the
+Disables recovery attempts when errors (e.g.\& xrun) are encountered; the
aplay process instead aborts immediately.
.SH SIGNALS
@@ -252,10 +254,9 @@ every hour. The files are placed in dir
and have names which include their start times and file numbers.
.SH SEE ALSO
-\fB
-alsamixer(1),
-amixer(1)
-\fP
+.BR \
+alsamixer "(1), " \
+amixer (1)
.SH BUGS
Note that .aiff files are not currently supported.
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>
To find trailing space use
grep -n -e ' $' -e ' \\f.$' -e ' \\"' <man page>
The same goes for man pages that are used as an input.
For a style guide use
mandoc -T lint
-.-
Any "autogenerator" should check its products with the above mentioned
'groff', 'mandoc', and additionally with 'nroff ...'.
It should also check its input files for too long (> 80) lines.
This is just a simple quality control measure.
The "autogenerator" may have to be corrected to get a better man page,
the source file may, and any additional file may.
Common defects:
Not removing trailing spaces (in in- and output).
The reason for these trailing spaces should be found and eliminated.
"git" has a "tool" to point out whitespace,
see for example "git-apply(1)" and git-config(1)")
Not beginning each input sentence on a new line.
Line length and patch size should thus be reduced.
The script "reportbug" uses 'quoted-printable' encoding when a line is
longer than 1024 characters in an 'ascii' file.
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 -d -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 from 'diff -d -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)
-.-
