--- rest25/library/audioop.rst	2008-12-19 16:58:08.000000000 +0900
+++ rest262/library/audioop.rst	2009-04-05 05:02:09.000000000 +0900
@@ -11,25 +11,25 @@
 bits wide, stored in Python strings.  This is the same format as used by the
 :mod:`al` and :mod:`sunaudiodev` modules.  All scalar items are integers, unless
 specified otherwise.
 
 .. index::
    single: Intel/DVI ADPCM
    single: ADPCM, Intel/DVI
    single: a-LAW
    single: u-LAW
 
 This module provides support for a-LAW, u-LAW and Intel/DVI ADPCM encodings.
 
-.. % This para is mostly here to provide an excuse for the index entries...
+.. This para is mostly here to provide an excuse for the index entries...
 
 A few of the more complicated operations only take 16-bit samples, otherwise the
 sample size (in bytes) is always a parameter of the operation.
 
 The module defines the following variables and functions:
 
 
 .. exception:: error
 
    This exception is raised on all errors, such as unknown number of bytes per
    sample, etc.
 
@@ -132,24 +132,36 @@
    Convert samples in the audio fragment to a-LAW encoding and return this as a
    Python string.  a-LAW is an audio encoding format whereby you get a dynamic
    range of about 13 bits using only 8 bit samples.  It is used by the Sun audio
    hardware, among others.
 
    .. versionadded:: 2.5
 
 
 .. function:: lin2lin(fragment, width, newwidth)
 
    Convert samples between 1-, 2- and 4-byte formats.
 
+   .. note::
+
+      In some audio formats, such as .WAV files, 16 and 32 bit samples are
+      signed, but 8 bit samples are unsigned.  So when converting to 8 bit wide
+      samples for these formats, you need to also add 128 to the result::
+
+         new_frames = audioop.lin2lin(frames, old_width, 1)
+         new_frames = audioop.bias(new_frames, 1, 128)
+
+      The same, in reverse, has to be applied when converting from 8 to 16 or 32
+      bit width samples.
+
 
 .. function:: lin2ulaw(fragment, width)
 
    Convert samples in the audio fragment to u-LAW encoding and return this as a
    Python string.  u-LAW is an audio encoding format whereby you get a dynamic
    range of about 14 bits using only 8 bit samples.  It is used by the Sun audio
    hardware, among others.
 
 
 .. function:: minmax(fragment, width)
 
    Return a tuple consisting of the minimum and maximum values of all samples in
@@ -182,29 +194,25 @@
 
    The *weightA* and *weightB* arguments are parameters for a simple digital filter
    and default to ``1`` and ``0`` respectively.
 
 
 .. function:: reverse(fragment, width)
 
    Reverse the samples in a fragment and returns the modified fragment.
 
 
 .. function:: rms(fragment, width)
 
-   Return the root-mean-square of the fragment, i.e.  ::
-
-      XXX: translate this math
-      \catcode`_=8
-      \sqrt{\frac{\sum{{S_{i}}^{2}}}{n}}
+   Return the root-mean-square of the fragment, i.e. ``sqrt(sum(S_i^2)/n)``.
 
    This is a measure of the power in an audio signal.
 
 
 .. function:: tomono(fragment, width, lfactor, rfactor)
 
    Convert a stereo fragment to a mono fragment.  The left channel is multiplied by
    *lfactor* and the right channel by *rfactor* before adding the two channels to
    give a mono signal.
 
 
 .. function:: tostereo(fragment, width, lfactor, rfactor)
@@ -248,19 +256,19 @@
 
 The :func:`find\*` routines might look a bit funny at first sight. They are
 primarily meant to do echo cancellation.  A reasonably fast way to do this is to
 pick the most energetic piece of the output sample, locate that in the input
 sample and subtract the whole output sample from the input sample::
 
    def echocancel(outputdata, inputdata):
        pos = audioop.findmax(outputdata, 800)    # one tenth second
        out_test = outputdata[pos*2:]
        in_test = inputdata[pos*2:]
        ipos, factor = audioop.findfit(in_test, out_test)
        # Optional (for better cancellation):
-       # factor = audioop.findfactor(in_test[ipos*2:ipos*2+len(out_test)], 
+       # factor = audioop.findfactor(in_test[ipos*2:ipos*2+len(out_test)],
        #              out_test)
        prefill = '\0'*(pos+ipos)*2
        postfill = '\0'*(len(inputdata)-len(prefill)-len(outputdata))
        outputdata = prefill + audioop.mul(outputdata,2,-factor) + postfill
        return audioop.add(inputdata, outputdata, 2)
 
