Input file is aplay.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  aplay.1 ": (shortened list)

      9 input text line longer than 80 bytes
     16 whitespace at end of input line

-.-.

Output from "test-groff -mandoc -t -ww -b -z aplay.1 ": (shortened list)

     16 trailing space in the line

-.-.

Output from "mandoc -T lint  aplay.1 ":

mandoc: aplay.1:3:67: STYLE: whitespace at end of input line
mandoc: aplay.1:20:119: STYLE: input text line longer than 80 bytes: If filename is not s...
mandoc: aplay.1:78:111: STYLE: input text line longer than 80 bytes: The default is zero,...
mandoc: aplay.1:84:112: STYLE: input text line longer than 80 bytes: The default is zero,...
mandoc: aplay.1:87:31: STYLE: whitespace at end of input line
mandoc: aplay.1:91:33: STYLE: whitespace at end of input line
mandoc: aplay.1:92:101: STYLE: input text line longer than 80 bytes: Open the audio devic...
mandoc: aplay.1:93:91: STYLE: input text line longer than 80 bytes: If this option is no...
mandoc: aplay.1:95:34: STYLE: whitespace at end of input line
mandoc: aplay.1:97:87: STYLE: input text line longer than 80 bytes: If no period time an...
mandoc: aplay.1:99:34: STYLE: whitespace at end of input line
mandoc: aplay.1:101:114: STYLE: input text line longer than 80 bytes: If no buffer time an...
mandoc: aplay.1:103:29: STYLE: whitespace at end of input line
mandoc: aplay.1:105:87: STYLE: input text line longer than 80 bytes: If no period size an...
mandoc: aplay.1:107:29: STYLE: whitespace at end of input line
mandoc: aplay.1:109:114: STYLE: input text line longer than 80 bytes: If no buffer time an...
mandoc: aplay.1:111:34: STYLE: whitespace at end of input line
mandoc: aplay.1:114:34: STYLE: whitespace at end of input line
mandoc: aplay.1:115:48: STYLE: whitespace at end of input line
mandoc: aplay.1:118:34: STYLE: whitespace at end of input line
mandoc: aplay.1:121:33: STYLE: whitespace at end of input line
mandoc: aplay.1:131:34: STYLE: whitespace at end of input line
mandoc: aplay.1:215:66: STYLE: whitespace at end of input line
mandoc: aplay.1:225:43: STYLE: whitespace at end of input line
mandoc: aplay.1:260:10: STYLE: whitespace at end of input line

-.-.

Remove space characters at the end of lines.

Use "git apply ... --whitespace=fix" to fix extra space issues, or use
global configuration "core.whitespace".

3:arecord, aplay \- command\-line sound recorder and player for ALSA 
87:\fI\-M, \-\-mmap\fP            
91:\fI\-N, \-\-nonblock\fP          
95:\fI\-F, \-\-period\-time=#\fP     
99:\fI\-B, \-\-buffer\-time=#\fP     
103:\fI\-\-period\-size=#\fP     
107:\fI\-\-buffer\-size=#\fP     
111:\fI\-A, \-\-avail\-min=#\fP       
114:\fI\-R, \-\-start\-delay=#\fP     
115:Delay for automatic PCM start is # microseconds 
118:\fI\-T, \-\-stop\-delay=#\fP      
121:\fI\-v, \-\-verbose\fP           
131:\fI\-I, \-\-separate\-channels\fP 
215:When recording, SIGINT, SIGTERM and SIGABRT will close the output 
225:22050\-Hz, mono, 8\-bit, Mu\-Law .au file. 
260:.SH BUGS 

-.-.

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 comma (or \&) after "e.g." and "i.e.", or use English words
(man-pages(7)).
Abbreviation points should be 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 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.


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.


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


-.-.

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

257:amixer(1)

-.-.

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.

-.-.

Use a hyphen between a number and the unit (name) "bit",
see "man-pages(7)", item "Terms to avoid".

64:\-f cd (16 bit little endian, 44100, stereo) [\-f S16_LE \-c2 \-r44100]
65:\-f cdr (16 bit big endian, 44100, stereo) [\-f S16_BE \-c2 \-r44100]
66:\-f dat (16 bit little endian, 48000, stereo) [\-f S16_LE \-c2 \-r48000]

-.-.

Two or more space charaters between printable characters.

When the distance is between sentences,
start the beginning of the second one on a separate line
("semantic newline").

123:This option is accumulative.  The VU meter is displayed when this
132:One file for each channel.  This option disables max\-file\-time
133:and use\-strftime, and ignores SIGUSR1.  The stereo VU meter is
137:Playback.  This is the default if the program is invoked
141:Record.  This is the default if the program is invoked
149:Give the channel map to override or follow.  Pass channel position
185:close it and open a new output file.  Default is the maximum
187:This option has no effect if  \-\-separate\-channels is
196:the strftime facility whenever the output file is opened.  The
198:the month, %H hour, %M minute and %S second.  In addition, %v is
199:the file number, starting at 1.  When this option is specified,
216:file and exit.  SIGUSR1 will close the output file, open a new one,
217:and continue recording.  However, SIGUSR1 does not work with
244:per second, 8 bits per sample.  Start a new file every
245:30 seconds.  File names are mon\-nn.wav, where nn increases
246:from 01.  The file after mon\-99.wav is mon\-100.wav.
250:Record in stereo from the default audio source.  Create a new file
251:every hour.  The files are placed in directories based on their start dates

-.-.

Output from "test-groff  -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z ":

troff: backtrace: file '<stdin>':3
troff:<stdin>:3: warning: trailing space in the line
troff: backtrace: file '<stdin>':87
troff:<stdin>:87: warning: trailing space in the line
troff: backtrace: file '<stdin>':91
troff:<stdin>:91: warning: trailing space in the line
troff: backtrace: file '<stdin>':95
troff:<stdin>:95: warning: trailing space in the line
troff: backtrace: file '<stdin>':99
troff:<stdin>:99: warning: trailing space in the line
troff: backtrace: file '<stdin>':103
troff:<stdin>:103: warning: trailing space in the line
troff: backtrace: file '<stdin>':107
troff:<stdin>:107: warning: trailing space in the line
troff: backtrace: file '<stdin>':111
troff:<stdin>:111: warning: trailing space in the line
troff: backtrace: file '<stdin>':114
troff:<stdin>:114: warning: trailing space in the line
troff: backtrace: file '<stdin>':115
troff:<stdin>:115: warning: trailing space in the line
troff: backtrace: file '<stdin>':118
troff:<stdin>:118: warning: trailing space in the line
troff: backtrace: file '<stdin>':121
troff:<stdin>:121: warning: trailing space in the line
troff: backtrace: file '<stdin>':131
troff:<stdin>:131: warning: trailing space in the line
troff: backtrace: file '<stdin>':215
troff:<stdin>:215: warning: trailing space in the line
troff: backtrace: file '<stdin>':225
troff:<stdin>:225: warning: trailing space in the line
troff: backtrace: file '<stdin>':258
troff:<stdin>:258: warning: trailing space in the line