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

      1 skipping paragraph macro

-.-.

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

      1 trailing space in the line

-.-.

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

mandoc: alsabat.1:163:2: WARNING: skipping paragraph macro: br after SH

-.-.

Change - to \- if it shall be printed as a minus sign.

alsabat.1:166:If no peak be detected, returns -1001;
alsabat.1:168:If only DC be detected, returns -1002;
alsabat.1:170:If peak frequency does not match with the target frequency, returns -1003.

-.-.

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.

37:of alsabat, with configure option "--enable-alsabat-backend-tiny".
134:"--standalone".

-.-.

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.

11:human interaction. ALSABAT can be used to test audio quality, stress test
14:ALSABAT's design is relatively simple. ALSABAT plays an audio stream and
15:captures the same stream in either a digital or analog loop back. It then
21:target and runs as a server on a separate tester machine. The client/server
30:jacks to create a loopback. If only headphone and mic jacks (or combo jack)
68:The number of channels. The default is one channel.
72:Sampling rate in Hertz. The default rate is 44100 Hertz.
79:1. Decimal integer, means number of frames;
81:2. Floating point with suffix 's', means number of seconds.
90:value and standard deviation of frequency vectors. After that, we define
123:Playback, capture and analysis internal to ALSABAT only. This is intended
139:There are many kinds of audio latency metrics. One useful metric is the
143:Noise detection threshold in SNR (dB). 26dB indicates 5% noise in amplitude.
178:Currently only support RIFF WAV format with PCM data. Please report any bugs to

-.-.

Use the name of units in text; use symbols in tables and
calculations.
The rule is to have a (no-break, \~) space between a number and
its units (see "www.bipm.org/en/publications/si-brochure")

143:Noise detection threshold in SNR (dB). 26dB indicates 5% noise in amplitude.

-.-.

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

174:aplay(1)

-.-.

Change a HYPHEN-MINUS (code 0x55, 2D) to a dash
(\-, minus) if it matches "[[:alph:]]-[[:alpha:]]" in the name of an
option).
Facilitates the copy and paste of
a) an option in UTF-8 text
b) web addresses (URL).

Is not needed in ordinary words like "mother-in-law", that are not
copied and pasted to a command line (which needs ASCII code)

37:of alsabat, with configure option "--enable-alsabat-backend-tiny".

-.-.

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

troff: backtrace: file '<stdin>':175
troff:<stdin>:175: warning: trailing space in the line

-.-

Additionally:

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