explain what "default" means in sndio.7 rather than {sio,mio}_open.3,

with tweaks from jmc

3 files changed, 41 insertions, 22 deletions

diff --git a/lib/libsndio/mio_open.3 b/lib/libsndio/mio_open.3
index 8e0747f357f..cd889f2dca3 100644
--- a/lib/libsndio/mio_open.3
+++ b/lib/libsndio/mio_open.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: mio_open.3,v 1.10 2012/09/15 08:58:08 stsp Exp $
+.\" $OpenBSD: mio_open.3,v 1.11 2013/04/06 11:38:41 ratchov Exp $
 .\"
 .\" Copyright (c) 2007 Alexandre Ratchov <alex@caoua.org>
 .\"
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: September 15 2012 $
+.Dd $Mdocdate: April 6 2013 $
 .Dt MIO_OPEN 3
 .Os
 .Sh NAME
@@ -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/lib/libsndio/sio_open.3 b/lib/libsndio/sio_open.3
index 712a92d8dae..2f90927cdb6 100644
--- a/lib/libsndio/sio_open.3
+++ b/lib/libsndio/sio_open.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: sio_open.3,v 1.33 2012/05/23 19:25:11 ratchov Exp $
+.\" $OpenBSD: sio_open.3,v 1.34 2013/04/06 11:38:41 ratchov Exp $
 .\"
 .\" Copyright (c) 2007 Alexandre Ratchov <alex@caoua.org>
 .\"
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: May 23 2012 $
+.Dd $Mdocdate: April 6 2013 $
 .Dt SIO_OPEN 3
 .Os
 .Sh NAME
@@ -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/lib/libsndio/sndio.7 b/lib/libsndio/sndio.7
index 1065fd6ecac..49c3396c55a 100644
--- a/lib/libsndio/sndio.7
+++ b/lib/libsndio/sndio.7
@@ -1,4 +1,4 @@
-.\" $OpenBSD: sndio.7,v 1.12 2012/12/22 10:10:04 jmc Exp $
+.\" $OpenBSD: sndio.7,v 1.13 2013/04/06 11:38:41 ratchov Exp $
 .\"
 .\" Copyright (c) 2007 Alexandre Ratchov <alex@caoua.org>
 .\"
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: December 22 2012 $
+.Dd $Mdocdate: April 6 2013 $
 .Dt SNDIO 7
 .Os
 .Sh NAME
@@ -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