add hg and python

1 files changed, 111 insertions, 0 deletions

diff --git a/sys/src/cmd/python/Doc/lib/libchunk.tex b/sys/src/cmd/python/Doc/lib/libchunk.tex
new file mode 100644
index 000000000..8e2a4947f
--- /dev/null
+++ b/sys/src/cmd/python/Doc/lib/libchunk.tex
@@ -0,0 +1,111 @@
+\section{\module{chunk} ---
+	 Read IFF chunked data}
+
+\declaremodule{standard}{chunk}
+\modulesynopsis{Module to read IFF chunks.}
+\moduleauthor{Sjoerd Mullender}{sjoerd@acm.org}
+\sectionauthor{Sjoerd Mullender}{sjoerd@acm.org}
+
+
+
+This module provides an interface for reading files that use EA IFF 85
+chunks.\footnote{``EA IFF 85'' Standard for Interchange Format Files,
+Jerry Morrison, Electronic Arts, January 1985.}  This format is used
+in at least the Audio\index{Audio Interchange File
+Format}\index{AIFF}\index{AIFF-C} Interchange File Format
+(AIFF/AIFF-C) and the Real\index{Real Media File Format} Media File
+Format\index{RMFF} (RMFF).  The WAVE audio file format is closely
+related and can also be read using this module.
+
+A chunk has the following structure:
+
+\begin{tableiii}{c|c|l}{textrm}{Offset}{Length}{Contents}
+  \lineiii{0}{4}{Chunk ID}
+  \lineiii{4}{4}{Size of chunk in big-endian byte order, not including the 
+                 header}
+  \lineiii{8}{\var{n}}{Data bytes, where \var{n} is the size given in
+                       the preceding field}
+  \lineiii{8 + \var{n}}{0 or 1}{Pad byte needed if \var{n} is odd and
+                                chunk alignment is used}
+\end{tableiii}
+
+The ID is a 4-byte string which identifies the type of chunk.
+
+The size field (a 32-bit value, encoded using big-endian byte order)
+gives the size of the chunk data, not including the 8-byte header.
+
+Usually an IFF-type file consists of one or more chunks.  The proposed
+usage of the \class{Chunk} class defined here is to instantiate an
+instance at the start of each chunk and read from the instance until
+it reaches the end, after which a new instance can be instantiated.
+At the end of the file, creating a new instance will fail with a
+\exception{EOFError} exception.
+
+\begin{classdesc}{Chunk}{file\optional{, align, bigendian, inclheader}}
+Class which represents a chunk.  The \var{file} argument is expected
+to be a file-like object.  An instance of this class is specifically
+allowed.  The only method that is needed is \method{read()}.  If the
+methods \method{seek()} and \method{tell()} are present and don't
+raise an exception, they are also used.  If these methods are present
+and raise an exception, they are expected to not have altered the
+object.  If the optional argument \var{align} is true, chunks are
+assumed to be aligned on 2-byte boundaries.  If \var{align} is
+false, no alignment is assumed.  The default value is true.  If the
+optional argument \var{bigendian} is false, the chunk size is assumed
+to be in little-endian order.  This is needed for WAVE audio files.
+The default value is true.  If the optional argument \var{inclheader}
+is true, the size given in the chunk header includes the size of the
+header.  The default value is false.
+\end{classdesc}
+
+A \class{Chunk} object supports the following methods:
+
+\begin{methoddesc}{getname}{}
+Returns the name (ID) of the chunk.  This is the first 4 bytes of the
+chunk.
+\end{methoddesc}
+
+\begin{methoddesc}{getsize}{}
+Returns the size of the chunk.
+\end{methoddesc}
+
+\begin{methoddesc}{close}{}
+Close and skip to the end of the chunk.  This does not close the
+underlying file.
+\end{methoddesc}
+
+The remaining methods will raise \exception{IOError} if called after
+the \method{close()} method has been called.
+
+\begin{methoddesc}{isatty}{}
+Returns \code{False}.
+\end{methoddesc}
+
+\begin{methoddesc}{seek}{pos\optional{, whence}}
+Set the chunk's current position.  The \var{whence} argument is
+optional and defaults to \code{0} (absolute file positioning); other
+values are \code{1} (seek relative to the current position) and
+\code{2} (seek relative to the file's end).  There is no return value.
+If the underlying file does not allow seek, only forward seeks are
+allowed.
+\end{methoddesc}
+
+\begin{methoddesc}{tell}{}
+Return the current position into the chunk.
+\end{methoddesc}
+
+\begin{methoddesc}{read}{\optional{size}}
+Read at most \var{size} bytes from the chunk (less if the read hits
+the end of the chunk before obtaining \var{size} bytes).  If the
+\var{size} argument is negative or omitted, read all data until the
+end of the chunk.  The bytes are returned as a string object.  An
+empty string is returned when the end of the chunk is encountered
+immediately.
+\end{methoddesc}
+
+\begin{methoddesc}{skip}{}
+Skip to the end of the chunk.  All further calls to \method{read()}
+for the chunk will return \code{''}.  If you are not interested in the
+contents of the chunk, this method should be called so that the file
+points to the start of the next chunk.
+\end{methoddesc}