Add a big comment about cross-platform issues (especially OpenBSD).

This should be turned into a footnote by someone who actually
understands OSS and its relationship to Linux, FreeBSD, OpenBSD, NetBSD,
etc.

1 files changed, 33 insertions, 7 deletions

diff --git a/Doc/lib/libossaudiodev.tex b/Doc/lib/libossaudiodev.tex
index 414ec67..d9b4fe5 100644
--- a/Doc/lib/libossaudiodev.tex
+++ b/Doc/lib/libossaudiodev.tex
@@ -2,20 +2,46 @@
          Access to OSS-compatible audio devices}
 
 \declaremodule{builtin}{ossaudiodev}
-\platform{Linux, FreeBSD}
+\platform{Linux, FreeBSD, possibly other \UNIX-like systems}
 \modulesynopsis{Access to OSS-compatible audio devices.}
 
-% XXX OSS is standard for Linux and FreeBSD -- what about NetBSD?
-% OpenBSD?  others?
 This module allows you to access the OSS (Open Sound System) audio
 interface.  OSS is available for a wide range of open-source and
-commercial Unices, and is the standard audio interface for Linux (up to
-kernel 2.4) and FreeBSD.
+commercial Unices, and is the standard audio interface for Linux and
+recent versions of FreeBSD.
+
+% Things will get more complicated for future Linux versions, since
+% ALSA is in the standard kernel as of 2.5.x.  Presumably if you
+% use ALSA, you'll have to make sure its OSS compatibility layer
+% is active to use ossaudiodev, but you're gonna need it for the vast
+% majority of Linux audio apps anyways.  
+%
+% Sounds like things are also complicated for other BSDs.  In response
+% to my python-dev query, Thomas Wouters said:
+%
+% > Likewise, googling shows OpenBSD also uses OSS/Free -- the commercial
+% > OSS installation manual tells you to remove references to OSS/Free from the
+% > kernel :)
+%
+% but Aleksander Piotrowsk actually has an OpenBSD box, and he quotes
+% from its <soundcard.h>:
+% >  * WARNING!  WARNING!
+% >  * This is an OSS (Linux) audio emulator.
+% >  * Use the Native NetBSD API for developing new code, and this
+% >  * only for compiling Linux programs.
+%
+% There's also an ossaudio manpage on OpenBSD that explains things
+% further.  Presumably NetBSD and OpenBSD have a different standard
+% audio interface.  That's the great thing about standards, there are so
+% many to choose from ... ;-)  
+%
+% This probably all warrants a footnote or two, but I don't understand
+% things well enough right now to write it!   --GPW
 
 \begin{seealso}
 \seetitle[http://www.opensound.com/pguide/oss.pdf]
-         {Open Sound System Programmer's Guide}
-         {the official documentation for the OSS C API}
+         {Open Sound System Programmer's Guide} {the official
+         documentation for the OSS C API}
 \seetext{The module defines a large number of constants supplied by
          the OSS device driver; see \file{<sys/soundcard.h>} on either
          Linux or FreeBSD for a listing .}