Lots of wordsmithing and typographical improvement.

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
+Before you can write to or read from an audio device, you must call
-
+three methods in the correct order:
-To set up the device, three functions must be called in the correct
-sequence:
 \begin{enumerate}
-\item \method{setfmt()} to set the output format,
+\item \method{setfmt()} to set the output format
-\item \method{channels()} to set the number of channels, and
+\item \method{channels()} to set the number of channels
-\item \method{speed()} to set the sample rate.
+\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
+Explicitly close the audio device.  When you are done writing to or
-where deleting the object does not immediately close it since there are
+reading from an audio device, you should explicitly close it.  A closed
-other references to it.  A closed device should not be used again.
+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
+Read \var{size} bytes from the audio input and return them as a Python
-Python string.  The function blocks until enough data is available.
+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
+Write the Python string \var{data} to the audio device and return the
-number of bytes written.  If the audio device is opened in blocking
+number of bytes written.  If the audio device is in blocking mode (the
-mode, the entire string is always written.  If the device is opened in
+default), the entire string is always written (again, this is different
-nonblocking mode, some data may not be written---see
+from usual \UNIX{} device semantics).  If the device is in non-blocking
-\method{writeall()}.
+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
+Write the entire Python string \var{data} to the audio device.  If the
-device is opened in blocking mode, behaves identially to
+device is in blocking mode (the default), behaves identically to
-\method{write()}; in nonblocking mode, waits until the device becomes
+\method{write()}; in non-blocking mode, \method{writeall()} waits until the
-available before feeding it more data.  Returns \code{None}, since the
+audio device is able to accept data, writes as much data as it will
-amount of data written is always equal to the amount of data supplied.
+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
+Put the device into non-blocking mode.  Once in non-blocking mode, there
-mode there is no way to return to blocking mode.
+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
+       {a logarithmic encoding (used by Sun \code{.au} files and
-        \file{/dev/audio} and is the format used by Sun .au files.}
+        \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
+Try to set the current audio format to \var{format}---see
-\method{getfmts()} for a list.  May also be used to return the current
+\method{getfmts()} for a list.  Return the audio format that the device
-audio format---do this by passing an ``audio format'' of
+was set to, which may not be the requested format.  May also be used to
-\constant{AFMT_QUERY}. Returns the audio format that the device was set
+return the current audio format---do this by passing an ``audio format''
-to, which may not be the requested 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
+Try to set the audio sampling rate to \var{samplerate} samples per
-the rate actually set.  Most sound devices don't support arbitrary
+second.  Returns the rate actually set.  Most sound devices don't
-sample rates.  Common rates are:
+support arbitrary sampling rates.  Common rates are:
-
+\begin{tableii}{l|l}{textrm}{Rate}{Description}
-8000---default rate
+\lineii{8000}{default rate for \filenq{/dev/audio}}
-11025---speech recording
+\lineii{11025}{speech recording}
-22050
+\lineii{22050}{}
-44100---Audio CD-quality (at 16 bits/sample and 2 channels)
+\lineii{44100}{CD quality audio (at 16 bits/sample and 2 channels)}
-96000---DVD-quality
+\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