small changes by Soren Larsen

Doc/lib/libaudioop.tex

@@ -1,8 +1,8 @@
 \section{Built-in module \sectcode{audioop}}
 \bimodindex{audioop}
 
-The audioop module contains some useful operations on sound fragments.
-It operates on sound fragments consisting of signed integer samples of
+The \code{audioop} module contains some useful operations on sound fragments.
+It operates on sound fragments consisting of signed integer samples
 8, 16 or 32 bits wide, stored in Python strings.  This is the same
 format as used by the \code{al} and \code{sunaudiodev} modules.  All
 scalar items are integers, unless specified otherwise.
@@ -19,7 +19,7 @@ per sample, etc.
 \end{excdesc}
 
 \begin{funcdesc}{add}{fragment1\, fragment2\, width}
-This function returns a fragment that is the addition of the two samples
+This function returns a fragment which is the addition of the two samples
 passed as parameters. \var{width} is the sample width in bytes, either
 \code{1}, \code{2} or \code{4}. Both fragments should have the same length.
 \end{funcdesc}
@@ -60,8 +60,8 @@ passed as an argument.
 \begin{funcdesc}{findfactor}{fragment\, reference}
 This routine (which only accepts 2-byte sample fragments) calculates a
 factor \var{F} such that \code{rms(add(fragment, mul(reference, -F)))}
-is minimal, i.e. it calculates the factor with which you should
-multiply \var{reference} to make it match as good as possible to
+is minimal, i.e.\ it calculates the factor with which you should
+multiply \var{reference} to make it match as well as possible to
 \var{fragment}. The fragments should be the same size.
 
 The time taken by this routine is proportional to \code{len(fragment)}. 
@@ -69,7 +69,7 @@ The time taken by this routine is proportional to \code{len(fragment)}.
 
 \begin{funcdesc}{findfit}{fragment\, reference}
 This routine (which only accepts 2-byte sample fragments) tries to
-match \var{reference} as good as possible to a portion of
+match \var{reference} as well as possible to a portion of
 \var{fragment} (which should be the longer fragment). It
 (conceptually) does this by taking slices out of \var{fragment}, using
 \code{findfactor} to compute the best match, and minimizing the
@@ -81,8 +81,8 @@ and \var{factor} the floating-point factor as per \code{findfactor}.
 
 \begin{funcdesc}{findmax}{fragment\, length}
 This routine (which only accepts 2-byte sample fragments) searches
-\var{fragment} for a slice of length \var{length} samples (not bytes!)
-with maximum energy, i.e. it returns \var{i} for which
+\var{fragment} for a slice of length \var{length} samples (not bytes!)\
+with maximum energy, i.e.\ it returns \var{i} for which
 \code{rms(fragment[i*2:(i+length)*2])} is maximal.
 
 The routine takes time proportional to \code{len(fragment)}.
@@ -140,7 +140,7 @@ This function returns the maximum peak-peak value in the sound fragment.
 \end{funcdesc}
 
 \begin{funcdesc}{mul}{fragment\, width\, factor}
-Mul returns a fragment that has all samples in the original framgent
+Return a fragment that has all samples in the original framgent
 multiplied by the floating-point value \var{factor}. Overflow is
 silently ignored.
 \end{funcdesc}
@@ -150,25 +150,6 @@ This function reverses the samples in a fragment and returns the
 modified fragment.
 \end{funcdesc}
 
-\begin{funcdesc}{tomono}{fragment\, width\, lfactor\, rfactor} 
-This function converts a stereo fragment to a mono fragment. The left
-channel is multiplied by \var{lfactor} and the right channel by
-\var{rfactor} before adding the two channels to give a mono signal.
-\end{funcdesc}
-
-\begin{funcdesc}{tostereo}{fragment\, width\, lfactor\, rfactor}
-This function generates a stereo fragment from a mono fragment. Each
-pair of samples in the stereo fragment are computed from the mono
-sample, whereby left channel samples are multiplied by \var{lfactor}
-and right channel samples by \var{rfactor}.
-\end{funcdesc}
-
-\begin{funcdesc}{mul}{fragment\, width\, factor}
-Mul returns a fragment that has all samples in the original framgent
-multiplied by the floating-point value \var{factor}. Overflow is
-silently ignored.
-\end{funcdesc}
-
 \begin{funcdesc}{rms}{fragment\, width\, factor}
 Returns the root-mean-square of the fragment, i.e.
 \iftexi
@@ -184,6 +165,19 @@ divided by the sumber of samples.
 This is a measure of the power in an audio signal.
 \end{funcdesc}
 
+\begin{funcdesc}{tomono}{fragment\, width\, lfactor\, rfactor} 
+This function converts a stereo fragment to a mono fragment. The left
+channel is multiplied by \var{lfactor} and the right channel by
+\var{rfactor} before adding the two channels to give a mono signal.
+\end{funcdesc}
+
+\begin{funcdesc}{tostereo}{fragment\, width\, lfactor\, rfactor}
+This function generates a stereo fragment from a mono fragment. Each
+pair of samples in the stereo fragment are computed from the mono
+sample, whereby left channel samples are multiplied by \var{lfactor}
+and right channel samples by \var{rfactor}.
+\end{funcdesc}
+
 \begin{funcdesc}{ulaw2lin}{fragment\, width}
 This function converts sound fragments in ULAW encoding to linearly
 encoded sound fragments. ULAW encoding always uses 8 bits samples, so
@@ -191,7 +185,7 @@ encoded sound fragments. ULAW encoding always uses 8 bits samples, so
 \end{funcdesc}
 
 Note that operations such as \code{mul} or \code{max} make no
-distinction between mono and stereo fragments, i.e. all samples are
+distinction between mono and stereo fragments, i.e.\ all samples are
 treated equal.  If this is a problem the stereo fragment should be split
 into two mono fragments first and recombined later.  Here is an example
 of how to do that:
@@ -207,10 +201,10 @@ def mul_stereo(sample, width, lfactor, rfactor):
 \end{verbatim}\ecode
 
 If you use the ADPCM coder to build network packets and you want your
-protocol to be stateless (i.e. to be able to tolerate packet loss)
+protocol to be stateless (i.e.\ to be able to tolerate packet loss)
 you should not only transmit the data but also the state. Note that
 you should send the \var{initial} state (the one you passed to
-lin2adpcm) along to the decoder, not the final state (as returned by
+\code{lin2adpcm}) along to the decoder, not the final state (as returned by
 the coder). If you want to use \code{struct} to store the state in
 binary you can code the first element (the predicted value) in 16 bits
 and the second (the delta index) in 8.