mass changes; fix titles; add examples; correct typos; clarifications;
unified style; etc.
diff --git a/Doc/libal.tex b/Doc/libal.tex
index 51a0312..6a812dd 100644
--- a/Doc/libal.tex
+++ b/Doc/libal.tex
@@ -1,13 +1,15 @@
\section{Built-in Module \sectcode{al}}
\bimodindex{al}
-This module provides access to the audio facilities of the Indigo and
-4D/35 workstations, described in section 3A of the IRIX 4.0 man pages
-(and also available as an option in IRIX 3.3). You'll need to read
-those man pages to understand what these functions do!
-Some of the functions are not available in releases below 4.0.5.
-Again, see the manual to check whether a specific function is
-available on your platform.
+This module provides access to the audio facilities of the SGI Indy
+and Indigo workstations. See section 3A of the IRIX man pages for
+details. You'll need to read those man pages to understand what these
+functions do! Some of the functions are not available in IRIX
+releases before 4.0.5. Again, see the manual to check whether a
+specific function is available on your platform.
+
+All functions and methods defined in this module are equivalent to
+the C functions with \samp{AL} prefixed to their name.
Symbolic constants from the C header file \file{<audio.h>} are defined
in the standard module \code{AL}, see below.
@@ -20,145 +22,138 @@
(One example is specifying an excessive queue size --- there is no
documented upper limit.)
-Module \code{al} defines the following functions:
+The module defines the following functions:
\renewcommand{\indexsubitem}{(in module al)}
+
\begin{funcdesc}{openport}{name\, direction\optional{\, config}}
-Equivalent to the C function ALopenport(). The name and direction
-arguments are strings. The optional config argument is an opaque
-configuration object as returned by \code{al.newconfig()}. The return
-value is an opaque port object; methods of port objects are described
-below.
+The name and direction arguments are strings. The optional config
+argument is a configuration object as returned by
+\code{al.newconfig()}. The return value is an \dfn{port object};
+methods of port objects are described below.
\end{funcdesc}
\begin{funcdesc}{newconfig}{}
-Equivalent to the C function ALnewconfig(). The return value is a new
-opaque configuration object; methods of configuration objects are
-described below.
+The return value is a new \dfn{configuration object}; methods of
+configuration objects are described below.
\end{funcdesc}
\begin{funcdesc}{queryparams}{device}
-Equivalent to the C function ALqueryparams(). The device argument is
-an integer. The return value is a list of integers containing the
-data returned by ALqueryparams().
+The device argument is an integer. The return value is a list of
+integers containing the data returned by ALqueryparams().
\end{funcdesc}
\begin{funcdesc}{getparams}{device\, list}
-Equivalent to the C function ALgetparams(). The device argument is an
-integer. The list argument is a list such as returned by
-\code{queryparams}; it is modified in place (!).
+The device argument is an integer. The list argument is a list such
+as returned by \code{queryparams}; it is modified in place (!).
\end{funcdesc}
\begin{funcdesc}{setparams}{device\, list}
-Equivalent to the C function ALsetparams(). The device argument is an
-integer.The list argument is a list such as returned by
-\code{al.queryparams}.
+The device argument is an integer. The list argument is a list such
+as returned by \code{al.queryparams}.
\end{funcdesc}
+\subsection{Configuration Objects}
+
Configuration objects (returned by \code{al.newconfig()} have the
following methods:
\renewcommand{\indexsubitem}{(audio configuration object method)}
+
\begin{funcdesc}{getqueuesize}{}
-Return the queue size; equivalent to the C function ALgetqueuesize().
+Return the queue size.
\end{funcdesc}
\begin{funcdesc}{setqueuesize}{size}
-Set the queue size; equivalent to the C function ALsetqueuesize().
+Set the queue size.
\end{funcdesc}
\begin{funcdesc}{getwidth}{}
-Get the sample width; equivalent to the C function ALgetwidth().
+Get the sample width.
\end{funcdesc}
-\begin{funcdesc}{getwidth}{width}
-Set the sample width; equivalent to the C function ALsetwidth().
+\begin{funcdesc}{setwidth}{width}
+Set the sample width.
\end{funcdesc}
\begin{funcdesc}{getchannels}{}
-Get the channel count; equivalent to the C function ALgetchannels().
+Get the channel count.
\end{funcdesc}
\begin{funcdesc}{setchannels}{nchannels}
-Set the channel count; equivalent to the C function ALsetchannels().
+Set the channel count.
\end{funcdesc}
\begin{funcdesc}{getsampfmt}{}
-Get the sample format; equivalent to the C function ALgetsampfmt().
+Get the sample format.
\end{funcdesc}
\begin{funcdesc}{setsampfmt}{sampfmt}
-Set the sample format; equivalent to the C function ALsetsampfmt().
+Set the sample format.
\end{funcdesc}
\begin{funcdesc}{getfloatmax}{}
-Get the maximum value for floating sample formats;
-equivalent to the C function ALgetfloatmax().
+Get the maximum value for floating sample formats.
\end{funcdesc}
\begin{funcdesc}{setfloatmax}{floatmax}
-Set the maximum value for floating sample formats;
-equivalent to the C function ALsetfloatmax().
+Set the maximum value for floating sample formats.
\end{funcdesc}
+\subsection{Port Objects}
+
Port objects (returned by \code{al.openport()} have the following
methods:
\renewcommand{\indexsubitem}{(audio port object method)}
+
\begin{funcdesc}{closeport}{}
-Close the port; equivalent to the C function ALcloseport().
+Close the port.
\end{funcdesc}
\begin{funcdesc}{getfd}{}
-Return the file descriptor as an int; equivalent to the C function
-ALgetfd().
+Return the file descriptor as an int.
\end{funcdesc}
\begin{funcdesc}{getfilled}{}
-Return the number of filled samples; equivalent to the C function
-ALgetfilled().
+Return the number of filled samples.
\end{funcdesc}
\begin{funcdesc}{getfillable}{}
-Return the number of fillable samples; equivalent to the C function
-ALgetfillable().
+Return the number of fillable samples.
\end{funcdesc}
\begin{funcdesc}{readsamps}{nsamples}
-Read a number of samples from the queue, blocking if necessary;
-equivalent to the C function ALreadsamples. The data is returned as a
-string containing the raw data (e.g. 2 bytes per sample in big-endian
-byte order (high byte, low byte) if you have set the sample width to 2
-bytes.
+Read a number of samples from the queue, blocking if necessary.
+Return the data as a string containing the raw data, (e.g., 2 bytes per
+sample in big-endian byte order (high byte, low byte) if you have set
+the sample width to 2 bytes).
\end{funcdesc}
\begin{funcdesc}{writesamps}{samples}
-Write samples into the queue, blocking if necessary; equivalent to the
-C function ALwritesamples. The samples are encoded as described for
-the \code{readsamps} return value.
+Write samples into the queue, blocking if necessary. The samples are
+encoded as described for the \code{readsamps} return value.
\end{funcdesc}
\begin{funcdesc}{getfillpoint}{}
-Return the `fill point'; equivalent to the C function ALgetfillpoint().
+Return the `fill point'.
\end{funcdesc}
\begin{funcdesc}{setfillpoint}{fillpoint}
-Set the `fill point'; equivalent to the C function ALsetfillpoint().
+Set the `fill point'.
\end{funcdesc}
\begin{funcdesc}{getconfig}{}
Return a configuration object containing the current configuration of
-the port; equivalent to the C function ALgetconfig().
+the port.
\end{funcdesc}
\begin{funcdesc}{setconfig}{config}
-Set the configuration from the argument, a configuration object;
-equivalent to the C function ALsetconfig().
+Set the configuration from the argument, a configuration object.
\end{funcdesc}
\begin{funcdesc}{getstatus}{list}
-Get status information on last error
-equivalent to C function ALgetstatus().
+Get status information on last error.
\end{funcdesc}
\section{Standard Module \sectcode{AL}}