mixer(8): Improve mute and recsrc controls

The input options of "dev.mute" (+, -, ^) and "dev.recsrc" (+, -, ^, =)
are quite cryptic. Allow the input to also be an actual description of
what these options do.

+ -> add (recsrc)
- -> remove (recsrc)
^ -> toggle (recsrc, mute)
= -> set (recsrc)
0 -> off (mute)
1 -> on (mute)

Also, deprecate the use of the symbol options in the EXAMPLES section of
the man page, by using the new descriptive options.

In the future, we might want to get rid of the symbol options
altogether, but preserve backwards compatibility for now.

Sponsored by: The FreeBSD Foundation
MFC after: 2 weeks
Reviewed by: dev_submerge.ch, imp
Differential Revision: https://reviews.freebsd.org/D43796

mixer.8: Fix wrong sentence

246e0457d93071ffd901c78e3ee7badc5f51bd4c ("mixer.8: Add terse example
for increasing volume") mentions that the example changes the volume of
the "first mixer found", while the example shows how the change the
volume of the current mixer's "vol" device. Re-phrease sentence to
reflect the actual behavior of the command.

Also, improve the example by using the % operator, instead of hardcoding
0.05.

Sponsored by: The FreeBSD Foundation
MFC after: 2 weeks
Reviewed by: dev_submerge.ch, markj
Differential Revision: https://reviews.freebsd.org/D43795

mixer(8): Allow full PCM device names as input for the -d option

The -d option is a wrapper around hw.snd.default_unit. Currently
mixer(8) expects the option argument to be just the unit's number (e.g
pcm0 -> 0). To avoid confusion, allow full device names of the form
"pcmN" as well.

While here, improve the -d option's description in the man page.

Sponsored by: The FreeBSD Foundation
MFC after: 2 weeks
Reviewed by: dev_submerge.ch, imp
Differential Revision: https://reviews.freebsd.org/D43794

mixer.8: Add terse example for increasing volume

Reviewed by: jhb
Pull Request: https://github.com/freebsd/freebsd-src/pull/1044

Remove $FreeBSD$: two-line nroff pattern

Remove /^\.\\"\n\.\\"\s*\$FreeBSD\$$\n/

mixer: remove volume backwards compat, add % interpretation

The current situation is fairly confusing, where an integer is interpreted
as a percent until you slap a decimal on it and magically it becomes an
absolute value.

Let's have a flag day in 14.0 and remove this shim entirely. Setting with
percent can still be useful, so allow a trailing '%' to indicate as such.
As a side effect, we tighten down the format allowed in the volume a little
bit by ensuring there's no trailing garbage after the value once it's
separated into left and right components.

Reviewed by: christos, hselasky, pauamma_gundo.com (manpages)
Relnotes: yes
Differential Revision: https://reviews.freebsd.org/D35101

mixer.8: Document shorthand syntax for volume setting.

Submitted by: christos@
Differential Revision: https://reviews.freebsd.org/D34614
Sponsored by: NVIDIA Networking

mixer.4 and mixer.8: Fix mandoc -Tlint errors.

Submitted by: christos@
Differential Revision: https://reviews.freebsd.org/D34603
Sponsored by: NVIDIA Networking

mixer .8: Clean up the manual page

- Use correct macros (e.g., Pa for paths, Ar for arguments, Cm for
command modifiers).
- Pet igor and mandoc -Tlint (e.g., start sentences after a newline).
- Use Ta instead of a tab character in tables.
- Stylize all table headers with Sy consistency.
- Add a missing "vol" variant to the synopsis of "dev.volume".
- Sort dev.recsrc command modifiers consistency.
- Use "Bd -literal" for code blocks in the examples. "Bl -tag" is not
the right macro for that.

Fixes: 903873ce1560 Implement and use new mixer(3) library for FreeBSD.

mixer: make .Dt tags uppercase

The document title should be uppercase in man pages.

Reviewed by: imp, gbe
MFC after: 5 days
Differential Revision: https://reviews.freebsd.org/D33027

mixer.8: Document -h

mixer(3) and mixer(8): Update manual pages.

- Use correct e-mail address.
- Set FreeBSD 14.0 as introduction for the updated mixer(8) utility.

Submitted by: christos@
Differential Revision: https://reviews.freebsd.org/D31636
Sponsored by: NVIDIA Networking

Implement and use new mixer(3) library for FreeBSD.

Wiki article: https://wiki.freebsd.org/SummerOfCode2021Projects/SoundMixerImprovements
This project was part of Google Summer of Code 2021.

Submitted by: christos@
Differential Revision: https://reviews.freebsd.org/D31636
Sponsored by: NVIDIA Networking

use .Mt to mark up email addresses consistently (part2)

PR: 191174
Submitted by: Franco Fichtner <franco@lastsummer.de>

add Xref to sound(4)...

MFC after: 1 week

A new jail(8) with a configuration file, to replace the work currently done
by /etc/rc.d/jail.

mdoc: drop redundant .Pp and .LP calls

They have no effect when coming in pairs, or before .Bl/.Bd

mdoc: consistently spell our email addresses <foo@FreeBSD.org>

Reviewed by: ru

Create the altix project branch. The altix project will add support
for the SGI Altix 350 to FreeBSD/ia64. The hardware used for porting
is a two-module system, consisting of a base compute module and a
CPU expansion module. SGI's NUMAFlex architecture can be an excellent
platform to test CPU affinity and NUMA-aware features in FreeBSD.

- Import the HEAD csup code which is the basis for the cvsmode work.

Update list of possible mixer devices. These devices were added to
soundcard.h more than ten years ago.

o Add "line" device to a list of mixer(8) devices.

PR: docs/112520
Submitted by: Pietro Cerutti
MFC after: 1 week

Markup fixes.

Approved by: re (blanket)

Add the -S flag which produces the -s output without
mixing field separators.

Mechanically kill hard sentence breaks.

Removed trailing whitespace.

Document changes to default output.

Assorted mdoc(7) fixes.

Approved by: re (blanket)

Implement relative mixer adjustment.

PR: 46679 (similar functionality)

The .Nm utility

Remove whitespace at EOL.

Change the behaviour of mixer slightly such that not explicitly specifying
a mixer device will set/get the master volume levels

PR: 25156
Submitted by: Tony Finch <dot@dotat.at>
Reviewed by: cg, nik

mdoc(7) police: split punctuation characters + misc fixes.

mdoc(7) police: do not split author names in the AUTHORS section.

Several cleanups:
- use getopt(3) to parse command line arguments instead of home-made incomplete
parser;
- be more verbose when error in command line encountered (i.e. incorrect
playing/recording device, incorrect recsrc syntax).

I've always wanted to be able to dump out the current values of
the mixer in a format suitable for saving and handing off to
mixer(1) at some future date to restore the settings.
Add a -s flag to do this.

Remove single-space hard sentence breaks. These degrade the quality
of the typeset output, tend to make diffs harder to read and provide
bad examples for new-comers to mdoc.

Remove xrefs to obosolete cdplay(1)

PR: docs/17079
Submitted by: Udo Erdelhoff <ue@nathan.ruhr.de>

Terminate .Bl with .El

Spelling fix.

PR: bin/14588
Submitted by: Christian Weisgerber <naddy@mips.rhein-neckar.de>

$Id$ -> $FreeBSD$

Add $Id$, to make it simpler for members of the translation teams to
track.

The Id line is normally at the bottom of the main comment block in the
man page, separated from the rest of the manpage by an empty comment,
like so;

.\" $Id$
.\"

If the immediately preceding comment is a @(#) format ID marker than the
the $Id$ will line up underneath it with no intervening blank lines.
Otherwise, an additional blank line is inserted.

Approved by: bde

.Sh AUTHOR -> .Sh AUTHORS. Use .An/.Aq.

Use err(3).

major modifications to the mixer. currently it doesn't report errors
that it encounters (such as invalid device), but does print usage upon
this error...

but otherwise allows complex commands such as:
mixer -f /dev/mixer4 synth line 50 -rec mic +rec line =rec cd ^rec mix

Add a man page for mixer(8).