Lots of wordsmithing and typographical improvement.

1 files changed, 71 insertions, 58 deletions

diff --git a/Doc/lib/libossaudiodev.tex b/Doc/lib/libossaudiodev.tex
index d9b4fe5..d42c946 100644
--- a/Doc/lib/libossaudiodev.tex
+++ b/Doc/lib/libossaudiodev.tex
@@ -43,7 +43,7 @@ recent versions of FreeBSD.
          {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
+         the OSS device driver; see \code{<sys/soundcard.h>} on either
          Linux or FreeBSD for a listing .}
 \end{seealso}
 
@@ -67,13 +67,6 @@ differences between conventional Unix read/write semantics and those of
 OSS audio devices).  It also supports a number of audio-specific
 methods; see below for the complete list of methods.
 
-Note the unusual calling syntax: the \emph{first} argument is optional,
-and the second is required.  This is a historical artifact for
-compatibility with the older \module{linuxaudiodev} module which
-\module{ossaudiodev} supersedes.  % XXX it might also be motivated
-% by my unfounded-but-still-possibly-true belief that the default
-% audio device varies unpredictably across operating systems.  -GW
-
 \var{device} is the audio device filename to use.  If it is not
 specified, this module first looks in the environment variable
 \envvar{AUDIODEV} for a device to use.  If not found, it falls back to
@@ -85,6 +78,13 @@ Since many soundcards only allow one process to have the recorder or
 player open at a time it is a good idea to open the device only for the
 activity needed.  Further, some soundcards are half-duplex: they can be
 opened for reading or writing, but not both at once.
+
+Note the unusual calling syntax: the \emph{first} argument is optional,
+and the second is required.  This is a historical artifact for
+compatibility with the older \module{linuxaudiodev} module which
+\module{ossaudiodev} supersedes.  % XXX it might also be motivated
+% by my unfounded-but-still-possibly-true belief that the default
+% audio device varies unpredictably across operating systems.  -GW
 \end{funcdesc}
 
 \begin{funcdesc}{openmixer}{\optional{device}}
@@ -98,74 +98,81 @@ not specified, this module first looks in the environment variable
 
 \subsection{Audio Device Objects \label{ossaudio-device-objects}}
 
-Setting up the device
-
-To set up the device, three functions must be called in the correct
-sequence:
+Before you can write to or read from an audio device, you must call
+three methods in the correct order:
 \begin{enumerate}
-\item \method{setfmt()} to set the output format,
-\item \method{channels()} to set the number of channels, and
-\item \method{speed()} to set the sample rate.
+\item \method{setfmt()} to set the output format
+\item \method{channels()} to set the number of channels
+\item \method{speed()} to set the sample rate
 \end{enumerate}
+Alternately, you can use the \method{setparameters()} method to set all
+three audio parameters at once.  This is more convenient, but may not be
+as flexible in all cases.
 
 The audio device objects are returned by \function{open()} define the
 following methods:
 
 \begin{methoddesc}[audio device]{close}{}
-This method explicitly closes the device.  It is useful in situations
-where deleting the object does not immediately close it since there are
-other references to it.  A closed device should not be used again.
+Explicitly close the audio device.  When you are done writing to or
+reading from an audio device, you should explicitly close it.  A closed
+device cannot be used again.
 \end{methoddesc}
 
 \begin{methoddesc}[audio device]{fileno}{}
-Returns the file descriptor associated with the device.
+Return the file descriptor associated with the device.
 \end{methoddesc}
 
 \begin{methoddesc}[audio device]{read}{size}
-Reads \var{size} samples from the audio input and returns them as a
-Python string.  The function blocks until enough data is available.
+Read \var{size} bytes from the audio input and return them as a Python
+string.  Unlike most \UNIX{} device drivers, OSS audio devices in
+blocking mode (the default) will block \function{read()} until the
+entire requested amount of data is available.
 \end{methoddesc}
 
 \begin{methoddesc}[audio device]{write}{data}
-Writes Python string \var{data} to the audio device and returns the
-number of bytes written.  If the audio device is opened in blocking
-mode, the entire string is always written.  If the device is opened in
-nonblocking mode, some data may not be written---see
-\method{writeall()}.
+Write the Python string \var{data} to the audio device and return the
+number of bytes written.  If the audio device is in blocking mode (the
+default), the entire string is always written (again, this is different
+from usual \UNIX{} device semantics).  If the device is in non-blocking
+mode, some data may not be written---see \method{writeall()}.
 \end{methoddesc}
 
 \begin{methoddesc}[audio device]{writeall}{data}
-Writes the entire Python string \var{data} to the audio device.  If the
-device is opened in blocking mode, behaves identially to
-\method{write()}; in nonblocking mode, waits until the device becomes
-available before feeding it more data.  Returns \code{None}, since the
-amount of data written is always equal to the amount of data supplied.
+Write the entire Python string \var{data} to the audio device.  If the
+device is in blocking mode (the default), behaves identically to
+\method{write()}; in non-blocking mode, \method{writeall()} waits until the
+audio device is able to accept data, writes as much data as it will
+accept, and repeats until \var{data} has been completely written.  Has
+no return value, since the amount of data written is always equal to the
+amount of data supplied.
 \end{methoddesc}
 
-Simple IOCTLs:
+The following methods each map to exactly one
+\function{ioctl()} system call.  If the underlying \function{ioctl()}
+fails, they all raise \exception{IOError}.
 
 \begin{methoddesc}[audio device]{nonblock}{}
-Attempts to put the device into nonblocking mode.  Once in nonblocking
-mode there is no way to return to blocking mode.
+Put the device into non-blocking mode.  Once in non-blocking mode, there
+is no way to return it to blocking mode.
 
-Raises \exception{IOError} if the IOCTL failed.
+Corresponds to the \code{SNDCTL_DSP_NONBLOCK} ioctl.
 \end{methoddesc}
 
 \begin{methoddesc}[audio device]{getfmts}{}
-Returns a bitmask of the audio output formats supported by the
+Return a bitmask of the audio output formats supported by the
 soundcard.  On a typical Linux system, these formats are:
 
 \begin{tableii}{l|l}{constant}{Format}{Description}
 \lineii{AFMT_MU_LAW}
-       {a logarithmic encoding.  This is the default format on
-        \file{/dev/audio} and is the format used by Sun .au files.}
+       {a logarithmic encoding (used by Sun \code{.au} files and
+        \filenq{/dev/audio})}
 \lineii{AFMT_A_LAW}
        {a logarithmic encoding}
 \lineii{AFMT_IMA_ADPCM}
        {a 4:1 compressed format defined by the Interactive Multimedia
-        Association.} 
+        Association} 
 \lineii{AFMT_U8}
-       {Unsigned, 8-bit audio.}
+       {Unsigned, 8-bit audio}
 \lineii{AFMT_S16_LE}
        {Unsigned, 16-bit audio, little-endian byte order (as used by
         Intel processors)}
@@ -173,7 +180,7 @@ soundcard.  On a typical Linux system, these formats are:
        {Unsigned, 16-bit audio, big-endian byte order (as used by 68k,
         PowerPC, Sparc)}
 \lineii{AFMT_S8}
-       {Signed, 8 bit audio.}
+       {Signed, 8 bit audio}
 \lineii{AFMT_U16_LE}
        {Signed, 16-bit little-endian audio}
 \lineii{AFMT_U16_BE}
@@ -182,14 +189,19 @@ soundcard.  On a typical Linux system, these formats are:
 Most systems support only a subset of these formats.  Many devices only
 support \constant{AFMT_U8}; the most common format used today is
 \constant{AFMT_S16_LE}.
+
+Corresponds to the \code{SNDCTL_DSP_GETFMTS} ioctl.
 \end{methoddesc}
 
 \begin{methoddesc}[audio device]{setfmt}{format}
-Used to set the current audio format to \var{format}---see
-\method{getfmts()} for a list.  May also be used to return the current
-audio format---do this by passing an ``audio format'' of
-\constant{AFMT_QUERY}. Returns the audio format that the device was set
-to, which may not be the requested format.
+Try to set the current audio format to \var{format}---see
+\method{getfmts()} for a list.  Return the audio format that the device
+was set to, which may not be the requested format.  May also be used to
+return the current audio format---do this by passing an ``audio format''
+of
+\constant{AFMT_QUERY}.  
+
+Corresponds to the \code{SNDCTL_DSP_SETFMT} ioctl.
 \end{methoddesc}
 
 \begin{methoddesc}[audio device]{channels}{num_channels}
@@ -200,31 +212,32 @@ Returns the number of channels the device was set to.
 \end{methoddesc}
 
 \begin{methoddesc}[audio device]{speed}{samplerate}
-Sets the samplerate to \var{samplerate} samples per second and returns
-the rate actually set.  Most sound devices don't support arbitrary
-sample rates.  Common rates are:
-
-8000---default rate
-11025---speech recording
-22050
-44100---Audio CD-quality (at 16 bits/sample and 2 channels)
-96000---DVD-quality
+Try to set the audio sampling rate to \var{samplerate} samples per
+second.  Returns the rate actually set.  Most sound devices don't
+support arbitrary sampling rates.  Common rates are:
+\begin{tableii}{l|l}{textrm}{Rate}{Description}
+\lineii{8000}{default rate for \filenq{/dev/audio}}
+\lineii{11025}{speech recording}
+\lineii{22050}{}
+\lineii{44100}{CD quality audio (at 16 bits/sample and 2 channels)}
+\lineii{96000}{DVD quality audio (at 24 bits/sample)}
+\end{tableii}
 \end{methoddesc}
 
-\begin{methoddesc}[audio device]{sync}
+\begin{methoddesc}[audio device]{sync}{}
 Waits until the sound device has played every byte in its buffer and
 returns.  This also occurs when the sound device is closed.  The OSS
 documentation recommends simply closing and re-opening the device rather
 than using \method{sync()}.
 \end{methoddesc}
 
-\begin{methoddesc}[audio device]{reset}
+\begin{methoddesc}[audio device]{reset}{}
 Immediately stops and playing or recording and returns the device to a
 state where it can accept commands.  The OSS documentation recommends
 closing and re-opening the device after calling \method{reset()}.
 \end{methoddesc}
 
-\begin{methoddesc}[audio device]{post}
+\begin{methoddesc}[audio device]{post}{}
 To be used like a lightweight \method{sync()}, the \method{post()}
 IOCTL informs the audio device that there is a likely to be a pause in
 the audio output---i.e., after playing a spot sound effect, before