From b5f32675fc6b5289d86f7d822f48354fbd36cf11 Mon Sep 17 00:00:00 2001
From: Alexandre Ratchov <alex@caoua.org>
Date: Fri, 12 Apr 2013 16:24:59 +0200
Subject: [PATCH] explain what "default" means in sndio.7

---
 libsndio/mio_open.3 |  7 -------
 libsndio/sio_open.3 |  8 --------
 libsndio/sndio.7    | 36 +++++++++++++++++++++++++++++++++++-
 3 files changed, 35 insertions(+), 16 deletions(-)

diff --git a/libsndio/mio_open.3 b/libsndio/mio_open.3
index f4d117b..f48befc 100644
--- a/libsndio/mio_open.3
+++ b/libsndio/mio_open.3
@@ -61,13 +61,6 @@ later it will be passed as the
 .Ar hdl
 argument of most other functions.
 The
-.Fn mio_open
-function tries to connect to the
-.Xr sndiod 1
-MIDI thru box or to use the
-.Xr midi 4
-hardware port.
-The
 .Ar name
 parameter gives the device string discussed in
 .Xr sndio 7 .
diff --git a/libsndio/sio_open.3 b/libsndio/sio_open.3
index b3f8bfe..e007c44 100644
--- a/libsndio/sio_open.3
+++ b/libsndio/sio_open.3
@@ -95,14 +95,6 @@ later it will be passed as the
 .Ar hdl
 argument of most other functions.
 The
-.Fn sio_open
-function first tries to connect to the
-.Xr sndiod 1
-audio server.
-If that fails, it then tries to use the
-.Xr audio 4
-hardware device.
-The
 .Ar name
 parameter gives the device string discussed in
 .Xr sndio 7 .
diff --git a/libsndio/sndio.7 b/libsndio/sndio.7
index fef53e7..acec61b 100644
--- a/libsndio/sndio.7
+++ b/libsndio/sndio.7
@@ -97,7 +97,7 @@ MIDI thru box created with
 MIDI port exposed by
 .Xr sndiod 1 .
 .It Pa default
-Any audio device or MIDI port.
+Default audio device or MIDI port (see below).
 .El
 .It Pa hostname
 The hostname or address where the remote
@@ -146,6 +146,40 @@ Sub-device registered with
 First MIDI thru box created with
 .Xr sndiod 1 .
 .El
+.Sh DEFAULTS
+If
+.Pa default
+is used as the audio device, the program will use the
+one specified in the
+.Ev AUDIODEVICE
+environment variable.
+If it is not set, the program first tries to connect to
+.Pa snd/0 .
+If that fails, it then tries to use
+.Pa rsnd/0 .
+This allows the
+.Xr sndiod 1
+audio server to be used by default and the bare hardware as fallback;
+programs don't have to be reconfigured when
+.Xr sndiod 1
+is started or stopped.
+.Pp
+If
+.Pa default
+is used as the MIDI port, the program will use the
+one specified in the
+.Ev MIDIDEVICE
+environment variable.
+If it is not set, the program first tries to connect to
+.Pa midithru/0 .
+If that fails, it then tries to use
+.Pa rmidi/0 .
+As long as
+.Xr sndiod 1
+is running, this allows programs to exchange MIDI data on
+machines with no MIDI hardware by default, e.g. a MIDI player
+could use a software synthesizer with no manual configuration
+required.
 .Sh AUTHENTICATION
 If a shared
 .Xr sndiod 1