From 60adb362df847702ae6f5b48533446fa06911500 Mon Sep 17 00:00:00 2001
From: Fred Drake <fdrake@acm.org>
Date: Tue, 5 Jan 1999 23:09:12 +0000
Subject: [PATCH] Document the sndhdr module.

Document that the whatsound module is obsolete.
---
 Doc/lib/lib.tex       |  1 +
 Doc/lib/libsndhdr.tex | 52 +++++++++++++++++++++++++++++++++++++++++++
 Doc/lib/libundoc.tex  |  9 +++-----
 3 files changed, 56 insertions(+), 6 deletions(-)
 create mode 100644 Doc/lib/libsndhdr.tex

diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex
index 7c94d6a28ea..39d0ffb066d 100644
--- a/Doc/lib/lib.tex
+++ b/Doc/lib/lib.tex
@@ -208,6 +208,7 @@ add new extensions to Python and how to embed it in other applications.
 \input{libjpeg}
 \input{librgbimg}
 \input{libimghdr}
+\input{libsndhdr}
 
 \input{libcrypto}		% Cryptographic Services
 \input{libmd5}
diff --git a/Doc/lib/libsndhdr.tex b/Doc/lib/libsndhdr.tex
new file mode 100644
index 00000000000..7d834401d81
--- /dev/null
+++ b/Doc/lib/libsndhdr.tex
@@ -0,0 +1,52 @@
+\section{\module{sndhdr} ---
+         Determine type of sound file.}
+
+\declaremodule{standard}{sndhdr}
+\modulesynopsis{Determine type of a sound file.}
+\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
+% Based on comments in the module source file.
+
+
+The \module{sndhdr} provides utility functions which attempt to
+determine the type of sound data which is in a file.  When these
+functions are able to determine what type of sound data is stored in a
+file, they return a tuple \code{(\var{type}, \var{sampling_rate},
+\var{channels}, \var{frames}, \var{bits_per_sample})}.  The value for
+\var{type} indicates the data type and will be one of the strings
+\code{'aifc'}, \code{'aiff'}, \code{'au'}, \code{'hcom'},
+\code{'sndr'}, \code{'sndt'}, \code{'voc'}, \code{'wav'},
+\code{'8svx'}, \code{'sb'}, \code{'ub'}, or \code{'ul'}.  The
+\var{sampling_rate} will be either the actual value or \code{0} if
+unknown or difficult to decode.  Similarly, \var{channels} will be
+either the number of channels or \code{0} if it cannot be determined
+or if the value is difficult to decode.  The value for \var{frames}
+will be either the number of frames or \code{-1}.  The last item in
+the tuple, \var{bits_per_sample}, will either be the sample size in
+bits or \code{'A'} for A-LAW\index{A-LAW} or \code{'U'} for
+u-LAW\index{u-LAW}.
+
+
+\begin{funcdesc}{what}{filename}
+  Determines the type of sound data stored in the file \var{filename}
+  using \function{whathdr()}.  If not successful, \function{whatraw()} 
+  is used.  If neither attempt succeeds, returns \code{None},
+  otherwise it returns a tuple as described above.
+\end{funcdesc}
+
+
+\begin{funcdesc}{whathdr}{filename}
+  Determines the type of sound data stored in a file based on the file 
+  header.  The name of the file is given by \var{filename}.  This
+  function returns a tuple as described above on success, or
+  \code{None}.
+\end{funcdesc}
+
+
+\begin{funcdesc}{whatraw}{filename}
+  Determines the type of raw sound data stored in a file without a
+  header.  The name of the file is given by \var{filename}.  This
+  function returns a tuple as described above on success, or
+  \code{None}.
+
+  This requires the \program{whatsound} program to work.
+\end{funcdesc}
diff --git a/Doc/lib/libundoc.tex b/Doc/lib/libundoc.tex
index 22684d8cf4f..5d1b3cae29d 100644
--- a/Doc/lib/libundoc.tex
+++ b/Doc/lib/libundoc.tex
@@ -143,14 +143,8 @@ sizes (used by pdb)
 \item[toaiff.py]
 --- Convert "arbitrary" sound files to AIFF files
 
-\item[sndhdr.py]
---- recognizing sound files
-
 \item[wave.py]
 --- parse WAVE files
-
-\item[whatsound.py]
---- recognizing sound files
 \end{description}
 
 
@@ -232,6 +226,9 @@ func.func_name, co.co_firstlineno).
 --- Measure time intervals to high resolution (use
 \function{time.clock()} instead).  (This is an extension module.)
 
+\item[whatsound.py]
+--- recognizing sound files
+
 \item[zmod.py]
 --- Compute properties of mathematical "fields"
 \end{description}