add hg and python

1 files changed, 218 insertions, 0 deletions

diff --git a/sys/src/cmd/python/Doc/lib/libsunau.tex b/sys/src/cmd/python/Doc/lib/libsunau.tex
new file mode 100644
index 000000000..235bc3b08
--- /dev/null
+++ b/sys/src/cmd/python/Doc/lib/libsunau.tex
@@ -0,0 +1,218 @@
+\section{\module{sunau} ---
+         Read and write Sun AU files}
+
+\declaremodule{standard}{sunau}
+\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
+\modulesynopsis{Provide an interface to the Sun AU sound format.}
+
+The \module{sunau} module provides a convenient interface to the Sun
+AU sound format.  Note that this module is interface-compatible with
+the modules \refmodule{aifc} and \refmodule{wave}.
+
+An audio file consists of a header followed by the data.  The fields
+of the header are:
+
+\begin{tableii}{l|l}{textrm}{Field}{Contents}
+  \lineii{magic word}{The four bytes \samp{.snd}.}
+  \lineii{header size}{Size of the header, including info, in bytes.}
+  \lineii{data size}{Physical size of the data, in bytes.}
+  \lineii{encoding}{Indicates how the audio samples are encoded.}
+  \lineii{sample rate}{The sampling rate.}
+  \lineii{\# of channels}{The number of channels in the samples.}
+  \lineii{info}{\ASCII{} string giving a description of the audio
+                file (padded with null bytes).}
+\end{tableii}
+
+Apart from the info field, all header fields are 4 bytes in size.
+They are all 32-bit unsigned integers encoded in big-endian byte
+order.
+
+
+The \module{sunau} module defines the following functions:
+
+\begin{funcdesc}{open}{file, mode}
+If \var{file} is a string, open the file by that name, otherwise treat it
+as a seekable file-like object. \var{mode} can be any of
+\begin{description}
+	\item[\code{'r'}] Read only mode.
+	\item[\code{'w'}] Write only mode.
+\end{description}
+Note that it does not allow read/write files.
+
+A \var{mode} of \code{'r'} returns a \class{AU_read}
+object, while a \var{mode} of \code{'w'} or \code{'wb'} returns
+a \class{AU_write} object.
+\end{funcdesc}
+
+\begin{funcdesc}{openfp}{file, mode}
+A synonym for \function{open}, maintained for backwards compatibility.
+\end{funcdesc}
+
+The \module{sunau} module defines the following exception:
+
+\begin{excdesc}{Error}
+An error raised when something is impossible because of Sun AU specs or 
+implementation deficiency.
+\end{excdesc}
+
+The \module{sunau} module defines the following data items:
+
+\begin{datadesc}{AUDIO_FILE_MAGIC}
+An integer every valid Sun AU file begins with, stored in big-endian
+form.  This is the string \samp{.snd} interpreted as an integer.
+\end{datadesc}
+
+\begin{datadesc}{AUDIO_FILE_ENCODING_MULAW_8}
+\dataline{AUDIO_FILE_ENCODING_LINEAR_8}
+\dataline{AUDIO_FILE_ENCODING_LINEAR_16}
+\dataline{AUDIO_FILE_ENCODING_LINEAR_24}
+\dataline{AUDIO_FILE_ENCODING_LINEAR_32}
+\dataline{AUDIO_FILE_ENCODING_ALAW_8}
+Values of the encoding field from the AU header which are supported by
+this module.
+\end{datadesc}
+
+\begin{datadesc}{AUDIO_FILE_ENCODING_FLOAT}
+\dataline{AUDIO_FILE_ENCODING_DOUBLE}
+\dataline{AUDIO_FILE_ENCODING_ADPCM_G721}
+\dataline{AUDIO_FILE_ENCODING_ADPCM_G722}
+\dataline{AUDIO_FILE_ENCODING_ADPCM_G723_3}
+\dataline{AUDIO_FILE_ENCODING_ADPCM_G723_5}
+Additional known values of the encoding field from the AU header, but
+which are not supported by this module.
+\end{datadesc}
+
+
+\subsection{AU_read Objects \label{au-read-objects}}
+
+AU_read objects, as returned by \function{open()} above, have the
+following methods:
+
+\begin{methoddesc}[AU_read]{close}{}
+Close the stream, and make the instance unusable. (This is 
+called automatically on deletion.)
+\end{methoddesc}
+
+\begin{methoddesc}[AU_read]{getnchannels}{}
+Returns number of audio channels (1 for mone, 2 for stereo).
+\end{methoddesc}
+
+\begin{methoddesc}[AU_read]{getsampwidth}{}
+Returns sample width in bytes.
+\end{methoddesc}
+
+\begin{methoddesc}[AU_read]{getframerate}{}
+Returns sampling frequency.
+\end{methoddesc}
+
+\begin{methoddesc}[AU_read]{getnframes}{}
+Returns number of audio frames.
+\end{methoddesc}
+
+\begin{methoddesc}[AU_read]{getcomptype}{}
+Returns compression type.
+Supported compression types are \code{'ULAW'}, \code{'ALAW'} and \code{'NONE'}.
+\end{methoddesc}
+
+\begin{methoddesc}[AU_read]{getcompname}{}
+Human-readable version of \method{getcomptype()}. 
+The supported types have the respective names \code{'CCITT G.711
+u-law'}, \code{'CCITT G.711 A-law'} and \code{'not compressed'}.
+\end{methoddesc}
+
+\begin{methoddesc}[AU_read]{getparams}{}
+Returns a tuple \code{(\var{nchannels}, \var{sampwidth},
+\var{framerate}, \var{nframes}, \var{comptype}, \var{compname})},
+equivalent to output of the \method{get*()} methods.
+\end{methoddesc}
+
+\begin{methoddesc}[AU_read]{readframes}{n}
+Reads and returns at most \var{n} frames of audio, as a string of
+bytes.  The data will be returned in linear format.  If the original
+data is in u-LAW format, it will be converted.
+\end{methoddesc}
+
+\begin{methoddesc}[AU_read]{rewind}{}
+Rewind the file pointer to the beginning of the audio stream.
+\end{methoddesc}
+
+The following two methods define a term ``position'' which is compatible
+between them, and is otherwise implementation dependent.
+
+\begin{methoddesc}[AU_read]{setpos}{pos}
+Set the file pointer to the specified position.  Only values returned
+from \method{tell()} should be used for \var{pos}.
+\end{methoddesc}
+
+\begin{methoddesc}[AU_read]{tell}{}
+Return current file pointer position.  Note that the returned value
+has nothing to do with the actual position in the file.
+\end{methoddesc}
+
+The following two functions are defined for compatibility with the 
+\refmodule{aifc}, and don't do anything interesting.
+
+\begin{methoddesc}[AU_read]{getmarkers}{}
+Returns \code{None}.
+\end{methoddesc}
+
+\begin{methoddesc}[AU_read]{getmark}{id}
+Raise an error.
+\end{methoddesc}
+
+
+\subsection{AU_write Objects \label{au-write-objects}}
+
+AU_write objects, as returned by \function{open()} above, have the
+following methods:
+
+\begin{methoddesc}[AU_write]{setnchannels}{n}
+Set the number of channels.
+\end{methoddesc}
+
+\begin{methoddesc}[AU_write]{setsampwidth}{n}
+Set the sample width (in bytes.)
+\end{methoddesc}
+
+\begin{methoddesc}[AU_write]{setframerate}{n}
+Set the frame rate.
+\end{methoddesc}
+
+\begin{methoddesc}[AU_write]{setnframes}{n}
+Set the number of frames. This can be later changed, when and if more 
+frames are written.
+\end{methoddesc}
+
+
+\begin{methoddesc}[AU_write]{setcomptype}{type, name}
+Set the compression type and description.
+Only \code{'NONE'} and \code{'ULAW'} are supported on output.
+\end{methoddesc}
+
+\begin{methoddesc}[AU_write]{setparams}{tuple}
+The \var{tuple} should be \code{(\var{nchannels}, \var{sampwidth},
+\var{framerate}, \var{nframes}, \var{comptype}, \var{compname})}, with
+values valid for the \method{set*()} methods.  Set all parameters.
+\end{methoddesc}
+
+\begin{methoddesc}[AU_write]{tell}{}
+Return current position in the file, with the same disclaimer for
+the \method{AU_read.tell()} and \method{AU_read.setpos()} methods.
+\end{methoddesc}
+
+\begin{methoddesc}[AU_write]{writeframesraw}{data}
+Write audio frames, without correcting \var{nframes}.
+\end{methoddesc}
+
+\begin{methoddesc}[AU_write]{writeframes}{data}
+Write audio frames and make sure \var{nframes} is correct.
+\end{methoddesc}
+
+\begin{methoddesc}[AU_write]{close}{}
+Make sure \var{nframes} is correct, and close the file.
+
+This method is called upon deletion.
+\end{methoddesc}
+
+Note that it is invalid to set any parameters after calling 
+\method{writeframes()} or \method{writeframesraw()}.