SF #814606: merge from release23-maint branch: clarify/cleanup

mixer docs; trim \platform{}, add \versionadded{}.

1 files changed, 27 insertions, 25 deletions

diff --git a/Doc/lib/libossaudiodev.tex b/Doc/lib/libossaudiodev.tex
index ae3d16f..0515978 100644
--- a/Doc/lib/libossaudiodev.tex
+++ b/Doc/lib/libossaudiodev.tex
@@ -2,9 +2,11 @@
          Access to OSS-compatible audio devices}
 
 \declaremodule{builtin}{ossaudiodev}
-\platform{Linux, FreeBSD, maybe other Unix-like systems}
+\platform{Linux, FreeBSD}
 \modulesynopsis{Access to OSS-compatible audio devices.}
 
+\versionadded{2.3}
+
 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 and
@@ -289,7 +291,7 @@ buffer to be played without blocking.
 
 \subsection{Mixer Device Objects \label{mixer-device-objects}}
 
-File-like interface
+The mixer object provides two file-like methods:
 
 \begin{methoddesc}[mixer device]{close}{}
 This method closes the open mixer device file.  Any further attempts to
@@ -300,38 +302,38 @@ use the mixer after this file is closed will raise an IOError.
 Returns the file handle number of the open mixer device file.
 \end{methoddesc}
 
-Mixer interface
+The remaining methods are specific to audio mixing:
 
 \begin{methoddesc}[mixer device]{controls}{}
 This method returns a bitmask specifying the available mixer controls
 (``Control'' being a specific mixable ``channel'', such as
 \constant{SOUND_MIXER_PCM} or \constant{SOUND_MIXER_SYNTH}).  This
-bitmask indicates a subset of all available mixer channels---the
+bitmask indicates a subset of all available mixer controls---the
 \constant{SOUND_MIXER_*} constants defined at module level.  To determine if,
 for example, the current mixer object supports a PCM mixer, use the
 following Python code:
 
 \begin{verbatim}
 mixer=ossaudiodev.openmixer()
-if mixer.channels() & (1 << ossaudiodev.SOUND_MIXER_PCM):
-	# PCM is supported
-	<code>
+if mixer.controls() & (1 << ossaudiodev.SOUND_MIXER_PCM):
+    # PCM is supported
+    ... code ...
 \end{verbatim}
 
-For most purposes, the \constant{SOUND_MIXER_VOLUME} (Master volume) and
-\constant{SOUND_MIXER_PCM} channels should suffice---but code that uses the
-mixer should be flexible when it comes to choosing sound channels.  On
+For most purposes, the \constant{SOUND_MIXER_VOLUME} (master volume) and
+\constant{SOUND_MIXER_PCM} controls should suffice---but code that uses the
+mixer should be flexible when it comes to choosing mixer controls.  On
 the Gravis Ultrasound, for example, \constant{SOUND_MIXER_VOLUME} does not
 exist.
 \end{methoddesc}
 
 \begin{methoddesc}[mixer device]{stereocontrols}{}
-Returns a bitmask indicating stereo mixer channels.  If a bit is set,
-the corresponding channel is stereo; if it is unset, the channel is
+Returns a bitmask indicating stereo mixer controls.  If a bit is set,
+the corresponding control is stereo; if it is unset, the control is
 either monophonic or not supported by the mixer (use in combination with
-\method{channels()} to determine which).
+\method{controls()} to determine which).
 
-See the code example for the \method{channels()} function for an example
+See the code example for the \method{controls()} function for an example
 of getting data from a bitmask.
 \end{methoddesc}
 
@@ -341,30 +343,30 @@ record.  See the code example for \method{controls()} for an example of
 reading from a bitmask.
 \end{methoddesc}
 
-\begin{methoddesc}[mixer device]{get}{channel}
-Returns the volume of a given mixer channel.  The returned volume is a
+\begin{methoddesc}[mixer device]{get}{control}
+Returns the volume of a given mixer control.  The returned volume is a
 2-tuple \code{(left_volume,right_volume)}.  Volumes are specified as
-numbers from 0 (silent) to 100 (full volume).  If the channel is
-monophonic, a 2-tuple is still returned, but both channel volumes are
+numbers from 0 (silent) to 100 (full volume).  If the control is
+monophonic, a 2-tuple is still returned, but both volumes are
 the same.
 
-If an unknown channel is specified, \exception{error} is raised.
+Raises \exception{OSSAudioError} if an invalid control was is specified,
+or \exception{IOError} if an unsupported control is specified.
 \end{methoddesc}
 
-\begin{methoddesc}[mixer device]{set}{channel, (left, right)}
-Sets the volume for a given mixer channel to \code{(left,right)}.
+\begin{methoddesc}[mixer device]{set}{control, (left, right)}
+Sets the volume for a given mixer control to \code{(left,right)}.
 \code{left} and \code{right} must be ints and between 0 (silent) and 100
 (full volume).  On success, the new volume is returned as a 2-tuple.
 Note that this may not be exactly the same as the volume specified,
 because of the limited resolution of some soundcard's mixers.
 
-Raises \exception{IOError} if an invalid mixer channel was specified;
-\exception{TypeError} if the argument format was incorrect, and
-\exception{error} if the specified volumes were out-of-range.
+Raises \exception{OSSAudioError} if an invalid mixer control was
+specified, or if the specified volumes were out-of-range.
 \end{methoddesc}
 
 \begin{methoddesc}[mixer device]{get_recsrc}{}
-This method returns a bitmask indicating which channel or channels are
+This method returns a bitmask indicating which control(s) are
 currently being used as a recording source.
 \end{methoddesc}