diff options
Diffstat (limited to 'Doc')
36 files changed, 1534 insertions, 1468 deletions
diff --git a/Doc/lib/libaifc.tex b/Doc/lib/libaifc.tex index 8bb88a1..f86b1d8 100644 --- a/Doc/lib/libaifc.tex +++ b/Doc/lib/libaifc.tex @@ -1,4 +1,4 @@ -\section{Standard Module \sectcode{aifc}} +\section{Standard Module \module{aifc}} \label{module-aifc} \stmodindex{aifc} @@ -6,6 +6,9 @@ This module provides support for reading and writing AIFF and AIFF-C files. AIFF is Audio Interchange File Format, a format for storing digital audio samples in a file. AIFF-C is a newer version of the format that includes the ability to compress the audio data. +\index{Audio Interchange File Format} +\index{AIFF} +\index{AIFF-C} Audio files have a number of parameters that describe the audio data. The sampling rate or frame rate is the number of times per second the @@ -21,9 +24,8 @@ bits), uses two channels (stereo) and has a frame rate of 44,100 frames/second. This gives a frame size of 4 bytes (2*2), and a second's worth occupies 2*2*44100 bytes, i.e.\ 176,400 bytes. -Module \code{aifc} defines the following function: +Module \module{aifc} defines the following function: -\setindexsubitem{(in module aifc)} \begin{funcdesc}{open}{file, mode} Open an AIFF or AIFF-C file and return an object instance with methods that are described below. The argument file is either a @@ -32,159 +34,161 @@ string naming a file or a file object. The mode is either the string when the file must be opened for writing. When used for writing, the file object should be seekable, unless you know ahead of time how many samples you are going to write in total and use -\code{writeframesraw()} and \code{setnframes()}. +\method{writeframesraw()} and \method{setnframes()}. \end{funcdesc} -Objects returned by \code{aifc.open()} when a file is opened for +Objects returned by \function{open()} when a file is opened for reading have the following methods: -\setindexsubitem{(aifc object method)} -\begin{funcdesc}{getnchannels}{} +\begin{methoddesc}[aifc]{getnchannels}{} Return the number of audio channels (1 for mono, 2 for stereo). -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{getsampwidth}{} +\begin{methoddesc}[aifc]{getsampwidth}{} Return the size in bytes of individual samples. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{getframerate}{} +\begin{methoddesc}[aifc]{getframerate}{} Return the sampling rate (number of audio frames per second). -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{getnframes}{} +\begin{methoddesc}[aifc]{getnframes}{} Return the number of audio frames in the file. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{getcomptype}{} +\begin{methoddesc}[aifc]{getcomptype}{} Return a four-character string describing the type of compression used in the audio file. For AIFF files, the returned value is \code{'NONE'}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{getcompname}{} +\begin{methoddesc}[aifc]{getcompname}{} Return a human-readable description of the type of compression used in the audio file. For AIFF files, the returned value is \code{'not compressed'}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{getparams}{} +\begin{methoddesc}[aifc]{getparams}{} Return a tuple consisting of all of the above values in the above order. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{getmarkers}{} +\begin{methoddesc}[aifc]{getmarkers}{} Return a list of markers in the audio file. A marker consists of a tuple of three elements. The first is the mark ID (an integer), the second is the mark position in frames from the beginning of the data (an integer), the third is the name of the mark (a string). -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{getmark}{id} -Return the tuple as described in \code{getmarkers} for the mark with -the given id. -\end{funcdesc} +\begin{methoddesc}[aifc]{getmark}{id} +Return the tuple as described in \method{getmarkers()} for the mark +with the given \var{id}. +\end{methoddesc} -\begin{funcdesc}{readframes}{nframes} +\begin{methoddesc}[aifc]{readframes}{nframes} Read and return the next \var{nframes} frames from the audio file. The returned data is a string containing for each frame the uncompressed samples of all channels. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{rewind}{} -Rewind the read pointer. The next \code{readframes} will start from +\begin{methoddesc}[aifc]{rewind}{} +Rewind the read pointer. The next \method{readframes()} will start from the beginning. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{setpos}{pos} +\begin{methoddesc}[aifc]{setpos}{pos} Seek to the specified frame number. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{tell}{} +\begin{methoddesc}[aifc]{tell}{} Return the current frame number. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{close}{} +\begin{methoddesc}[aifc]{close}{} Close the AIFF file. After calling this method, the object can no longer be used. -\end{funcdesc} +\end{methoddesc} -Objects returned by \code{aifc.open()} when a file is opened for -writing have all the above methods, except for \code{readframes} and -\code{setpos}. In addition the following methods exist. The -\code{get} methods can only be called after the corresponding -\code{set} methods have been called. Before the first -\code{writeframes()} or \code{writeframesraw()}, all parameters except -for the number of frames must be filled in. +Objects returned by \function{open()} when a file is opened for +writing have all the above methods, except for \method{readframes()} and +\method{setpos()}. In addition the following methods exist. The +\method{get*()} methods can only be called after the corresponding +\method{set*()} methods have been called. Before the first +\method{writeframes()} or \method{writeframesraw()}, all parameters +except for the number of frames must be filled in. -\begin{funcdesc}{aiff}{} +\begin{methoddesc}[aifc]{aiff}{} Create an AIFF file. The default is that an AIFF-C file is created, unless the name of the file ends in \code{'.aiff'} in which case the default is an AIFF file. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{aifc}{} +\begin{methoddesc}[aifc]{aifc}{} Create an AIFF-C file. The default is that an AIFF-C file is created, unless the name of the file ends in \code{'.aiff'} in which case the default is an AIFF file. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{setnchannels}{nchannels} +\begin{methoddesc}[aifc]{setnchannels}{nchannels} Specify the number of channels in the audio file. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{setsampwidth}{width} +\begin{methoddesc}[aifc]{setsampwidth}{width} Specify the size in bytes of audio samples. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{setframerate}{rate} +\begin{methoddesc}[aifc]{setframerate}{rate} Specify the sampling frequency in frames per second. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{setnframes}{nframes} +\begin{methoddesc}[aifc]{setnframes}{nframes} Specify the number of frames that are to be written to the audio file. If this parameter is not set, or not set correctly, the file needs to support seeking. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{setcomptype}{type, name} +\begin{methoddesc}[aifc]{setcomptype}{type, name} Specify the compression type. If not specified, the audio data will not be compressed. In AIFF files, compression is not possible. The name parameter should be a human-readable description of the compression type, the type parameter should be a four-character string. Currently the following compression types are supported: NONE, ULAW, ALAW, G722. -\end{funcdesc} +\index{u-LAW} +\index{A-LAW} +\index{G.722} +\end{methoddesc} -\begin{funcdesc}{setparams}{nchannels, sampwidth, framerate, comptype, compname} +\begin{methoddesc}[aifc]{setparams}{nchannels, sampwidth, framerate, comptype, compname} Set all the above parameters at once. The argument is a tuple consisting of the various parameters. This means that it is possible -to use the result of a \code{getparams()} call as argument to -\code{setparams()}. -\end{funcdesc} +to use the result of a \method{getparams()} call as argument to +\method{setparams()}. +\end{methoddesc} -\begin{funcdesc}{setmark}{id, pos, name} +\begin{methoddesc}[aifc]{setmark}{id, pos, name} Add a mark with the given id (larger than 0), and the given name at the given position. This method can be called at any time before -\code{close()}. -\end{funcdesc} +\method{close()}. +\end{methoddesc} -\begin{funcdesc}{tell}{} +\begin{methoddesc}[aifc]{tell}{} Return the current write position in the output file. Useful in -combination with \code{setmark()}. -\end{funcdesc} +combination with \method{setmark()}. +\end{methoddesc} -\begin{funcdesc}{writeframes}{data} +\begin{methoddesc}[aifc]{writeframes}{data} Write data to the output file. This method can only be called after the audio file parameters have been set. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{writeframesraw}{data} -Like \code{writeframes()}, except that the header of the audio file is -not updated. -\end{funcdesc} +\begin{methoddesc}[aifc]{writeframesraw}{data} +Like \method{writeframes()}, except that the header of the audio file +is not updated. +\end{methoddesc} -\begin{funcdesc}{close}{} +\begin{methoddesc}[aifc]{close}{} Close the AIFF file. The header of the file is updated to reflect the actual size of the audio data. After calling this method, the object can no longer be used. -\end{funcdesc} +\end{methoddesc} diff --git a/Doc/lib/libal.tex b/Doc/lib/libal.tex index 1126f83..fb31ffa 100644 --- a/Doc/lib/libal.tex +++ b/Doc/lib/libal.tex @@ -1,4 +1,4 @@ -\section{Built-in Module \sectcode{al}} +\section{Built-in Module \module{al}} \label{module-al} \bimodindex{al} @@ -10,10 +10,11 @@ releases before 4.0.5. Again, see the manual to check whether a specific function is available on your platform. All functions and methods defined in this module are equivalent to -the C functions with \samp{AL} prefixed to their name. +the \C{} functions with \samp{AL} prefixed to their name. -Symbolic constants from the C header file \file{<audio.h>} are defined -in the standard module \code{AL}, see below. +Symbolic constants from the \C{} header file \code{<audio.h>} are +defined in the standard module \module{AL}\refstmodindex{AL}, see +below. \strong{Warning:} the current version of the audio library may dump core when bad argument values are passed rather than returning an error @@ -25,145 +26,146 @@ documented upper limit.) The module defines the following functions: -\setindexsubitem{(in module al)} \begin{funcdesc}{openport}{name, direction\optional{, config}} -The name and direction arguments are strings. The optional config -argument is a configuration object as returned by -\code{al.newconfig()}. The return value is an \dfn{port object}; -methods of port objects are described below. +The name and direction arguments are strings. The optional +\var{config} argument is a configuration object as returned by +\function{newconfig()}. The return value is an \dfn{audio port +object}; methods of audio port objects are described below. \end{funcdesc} \begin{funcdesc}{newconfig}{} -The return value is a new \dfn{configuration object}; methods of -configuration objects are described below. +The return value is a new \dfn{audio configuration object}; methods of +audio configuration objects are described below. \end{funcdesc} \begin{funcdesc}{queryparams}{device} The device argument is an integer. The return value is a list of -integers containing the data returned by ALqueryparams(). +integers containing the data returned by \cfunction{ALqueryparams()}. \end{funcdesc} \begin{funcdesc}{getparams}{device, list} -The device argument is an integer. The list argument is a list such -as returned by \code{queryparams}; it is modified in place (!). +The \var{device} argument is an integer. The list argument is a list +such as returned by \function{queryparams()}; it is modified in place +(!). \end{funcdesc} \begin{funcdesc}{setparams}{device, list} -The device argument is an integer. The list argument is a list such -as returned by \code{al.queryparams}. +The \var{device} argument is an integer. The \var{list} argument is a +list such as returned by \function{queryparams()}. \end{funcdesc} + \subsection{Configuration Objects} +\label{al-config-objects} -Configuration objects (returned by \code{al.newconfig()} have the +Configuration objects (returned by \function{newconfig()} have the following methods: -\setindexsubitem{(audio configuration object method)} - -\begin{funcdesc}{getqueuesize}{} +\begin{methoddesc}[audio configuration]{getqueuesize}{} Return the queue size. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{setqueuesize}{size} +\begin{methoddesc}[audio configuration]{setqueuesize}{size} Set the queue size. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{getwidth}{} +\begin{methoddesc}[audio configuration]{getwidth}{} Get the sample width. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{setwidth}{width} +\begin{methoddesc}[audio configuration]{setwidth}{width} Set the sample width. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{getchannels}{} +\begin{methoddesc}[audio configuration]{getchannels}{} Get the channel count. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{setchannels}{nchannels} +\begin{methoddesc}[audio configuration]{setchannels}{nchannels} Set the channel count. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{getsampfmt}{} +\begin{methoddesc}[audio configuration]{getsampfmt}{} Get the sample format. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{setsampfmt}{sampfmt} +\begin{methoddesc}[audio configuration]{setsampfmt}{sampfmt} Set the sample format. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{getfloatmax}{} +\begin{methoddesc}[audio configuration]{getfloatmax}{} Get the maximum value for floating sample formats. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{setfloatmax}{floatmax} +\begin{methoddesc}[audio configuration]{setfloatmax}{floatmax} Set the maximum value for floating sample formats. -\end{funcdesc} +\end{methoddesc} + \subsection{Port Objects} +\label{al-port-objects} -Port objects (returned by \code{al.openport()} have the following +Port objects, as returned by \function{openport()}, have the following methods: -\setindexsubitem{(audio port object method)} - -\begin{funcdesc}{closeport}{} +\begin{methoddesc}[audio port]{closeport}{} Close the port. -\end{funcdesc} +\end{methoddesc}[audio port] -\begin{funcdesc}{getfd}{} +\begin{methoddesc}[audio port]{getfd}{} Return the file descriptor as an int. -\end{funcdesc} +\end{methoddesc}[audio port] -\begin{funcdesc}{getfilled}{} +\begin{methoddesc}[audio port]{getfilled}{} Return the number of filled samples. -\end{funcdesc} +\end{methoddesc}[audio port] -\begin{funcdesc}{getfillable}{} +\begin{methoddesc}[audio port]{getfillable}{} Return the number of fillable samples. -\end{funcdesc} +\end{methoddesc}[audio port] -\begin{funcdesc}{readsamps}{nsamples} +\begin{methoddesc}[audio port]{readsamps}{nsamples} Read a number of samples from the queue, blocking if necessary. Return the data as a string containing the raw data, (e.g., 2 bytes per sample in big-endian byte order (high byte, low byte) if you have set the sample width to 2 bytes). -\end{funcdesc} +\end{methoddesc}[audio port] -\begin{funcdesc}{writesamps}{samples} +\begin{methoddesc}[audio port]{writesamps}{samples} Write samples into the queue, blocking if necessary. The samples are -encoded as described for the \code{readsamps} return value. -\end{funcdesc} +encoded as described for the \method{readsamps()} return value. +\end{methoddesc}[audio port] -\begin{funcdesc}{getfillpoint}{} +\begin{methoddesc}[audio port]{getfillpoint}{} Return the `fill point'. -\end{funcdesc} +\end{methoddesc}[audio port] -\begin{funcdesc}{setfillpoint}{fillpoint} +\begin{methoddesc}[audio port]{setfillpoint}{fillpoint} Set the `fill point'. -\end{funcdesc} +\end{methoddesc}[audio port] -\begin{funcdesc}{getconfig}{} +\begin{methoddesc}[audio port]{getconfig}{} Return a configuration object containing the current configuration of the port. -\end{funcdesc} +\end{methoddesc}[audio port] -\begin{funcdesc}{setconfig}{config} +\begin{methoddesc}[audio port]{setconfig}{config} Set the configuration from the argument, a configuration object. -\end{funcdesc} +\end{methoddesc}[audio port] -\begin{funcdesc}{getstatus}{list} +\begin{methoddesc}[audio port]{getstatus}{list} Get status information on last error. -\end{funcdesc} +\end{methoddesc}[audio port] + -\section{Standard Module \sectcode{AL}} +\section{Standard Module \module{AL}} \nodename{AL (uppercase)} \stmodindex{AL} This module defines symbolic constants needed to use the built-in -module \code{al} (see above); they are equivalent to those defined in -the C header file \file{<audio.h>} except that the name prefix +module \module{al} (see above); they are equivalent to those defined +in the \C{} header file \code{<audio.h>} except that the name prefix \samp{AL_} is omitted. Read the module source for a complete list of the defined names. Suggested use: diff --git a/Doc/lib/libaudioop.tex b/Doc/lib/libaudioop.tex index 887cac9..774a92e 100644 --- a/Doc/lib/libaudioop.tex +++ b/Doc/lib/libaudioop.tex @@ -1,19 +1,25 @@ -\section{Built-in Module \sectcode{audioop}} +\section{Built-in Module \module{audioop}} \label{module-audioop} \bimodindex{audioop} -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. +The \module{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 \module{al} and \module{sunaudiodev} +modules. All scalar items are integers, unless specified otherwise. + +% This para is mostly here to provide an excuse for the index entries... +This module provides support for u-LAW and Intel/DVI ADPCM encodings. +\index{Intel/DVI ADPCM} +\index{ADPCM, Intel/DVI} +\index{u-LAW} 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. +otherwise the sample size (in bytes) is always a parameter of the +operation. The module defines the following variables and functions: -\setindexsubitem{(in module audioop)} \begin{excdesc}{error} This exception is raised on all errors, such as unknown number of bytes per sample, etc. @@ -28,14 +34,14 @@ length. \begin{funcdesc}{adpcm2lin}{adpcmfragment, width, state} Decode an Intel/DVI ADPCM coded fragment to a linear fragment. See -the description of \code{lin2adpcm} for details on ADPCM coding. +the description of \function{lin2adpcm()} for details on ADPCM coding. Return a tuple \code{(\var{sample}, \var{newstate})} where the sample has the width specified in \var{width}. \end{funcdesc} \begin{funcdesc}{adpcm32lin}{adpcmfragment, width, state} -Decode an alternative 3-bit ADPCM code. See \code{lin2adpcm3} for -details. +Decode an alternative 3-bit ADPCM code. See \function{lin2adpcm3()} +for details. \end{funcdesc} \begin{funcdesc}{avg}{fragment, width} @@ -60,26 +66,25 @@ argument. \begin{funcdesc}{findfactor}{fragment, reference} Return a factor \var{F} such that -\code{rms(add(fragment, mul(reference, -F)))} is minimal, i.e., -return the factor with which you should multiply \var{reference} to -make it match as well as possible to \var{fragment}. The fragments -should both contain 2-byte samples. +\code{rms(add(\var{fragment}, mul(\var{reference}, -\var{F})))} is +minimal, i.e., return the factor with which you should multiply +\var{reference} to make it match as well as possible to +\var{fragment}. The fragments should both contain 2-byte samples. -The time taken by this routine is proportional to \code{len(fragment)}. +The time taken by this routine is proportional to +\code{len(\var{fragment})}. \end{funcdesc} \begin{funcdesc}{findfit}{fragment, reference} -This routine (which only accepts 2-byte sample fragments) - Try to match \var{reference} as well as possible to a portion of \var{fragment} (which should be the longer fragment). This is (conceptually) done by taking slices out of \var{fragment}, using -\code{findfactor} to compute the best match, and minimizing the +\function{findfactor()} to compute the best match, and minimizing the result. The fragments should both contain 2-byte samples. Return a tuple \code{(\var{offset}, \var{factor})} where \var{offset} is the (integer) offset into \var{fragment} where the optimal match started and \var{factor} is the (floating-point) factor as per -\code{findfactor}. +\function{findfactor()}. \end{funcdesc} \begin{funcdesc}{findmax}{fragment, length} @@ -88,7 +93,7 @@ bytes!)\ with maximum energy, i.e., return \var{i} for which \code{rms(fragment[i*2:(i+length)*2])} is maximal. The fragments should both contain 2-byte samples. -The routine takes time proportional to \code{len(fragment)}. +The routine takes time proportional to \code{len(\var{fragment})}. \end{funcdesc} \begin{funcdesc}{getsample}{fragment, width, index} @@ -106,11 +111,12 @@ between one sample and the next, divided by a (varying) step. The Intel/DVI ADPCM algorithm has been selected for use by the IMA, so it may well become a standard. -\code{State} is a tuple containing the state of the coder. The coder +\var{state} is a tuple containing the state of the coder. The coder returns a tuple \code{(\var{adpcmfrag}, \var{newstate})}, and the -\var{newstate} should be passed to the next call of lin2adpcm. In the -initial call \code{None} can be passed as the state. \var{adpcmfrag} -is the ADPCM coded fragment packed 2 4-bit values per byte. +\var{newstate} should be passed to the next call of +\function{lin2adpcm()}. In the initial call, \code{None} can be +passed as the state. \var{adpcmfrag} is the ADPCM coded fragment +packed 2 4-bit values per byte. \end{funcdesc} \begin{funcdesc}{lin2adpcm3}{fragment, width, state} @@ -121,8 +127,8 @@ discouraged. \end{funcdesc} \begin{funcdesc}{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 +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. \end{funcdesc} @@ -147,15 +153,18 @@ multiplied by the floating-point value \var{factor}. Overflow is silently ignored. \end{funcdesc} -\begin{funcdesc}{ratecv}{fragment, width, nchannels, inrate, outrate, state\optional{, weightA, weightB}} +\begin{funcdesc}{ratecv}{fragment, width, nchannels, inrate, outrate, + state\optional{, weightA\optional{, weightB}}} Convert the frame rate of the input fragment. -\code{State} is a tuple containing the state of the converter. The +\var{state} is a tuple containing the state of the converter. The converter returns a tupl \code{(\var{newfragment}, \var{newstate})}, -and \var{newstate} should be passed to the next call of ratecv. +and \var{newstate} should be passed to the next call of +\function{ratecv()}. -The \code{weightA} and \code{weightB} arguments are parameters for a -simple digital filter and default to 1 and 0 respectively. +The \var{weightA} and \var{weightB} arguments are parameters for a +simple digital filter and default to \code{1} and \code{0} +respectively. \end{funcdesc} \begin{funcdesc}{reverse}{fragment, width} @@ -164,9 +173,12 @@ Reverse the samples in a fragment and returns the modified fragment. \begin{funcdesc}{rms}{fragment, width} Return the root-mean-square of the fragment, i.e. +%begin{latexonly} \iftexi +%end{latexonly} the square root of the quotient of the sum of all squared sample value, divided by the sumber of samples. +%begin{latexonly} \else % in eqn: sqrt { sum S sub i sup 2 over n } \begin{displaymath} @@ -174,6 +186,7 @@ divided by the sumber of samples. \sqrt{\frac{\sum{{S_{i}}^{2}}}{n}} \end{displaymath} \fi +%end{latexonly} This is a measure of the power in an audio signal. \end{funcdesc} @@ -191,16 +204,17 @@ samples by \var{rfactor}. \end{funcdesc} \begin{funcdesc}{ulaw2lin}{fragment, width} -Convert sound fragments in ULAW encoding to linearly encoded sound -fragments. ULAW encoding always uses 8 bits samples, so \var{width} +Convert sound fragments in u-LAW encoding to linearly encoded sound +fragments. u-LAW encoding always uses 8 bits samples, so \var{width} refers only to the sample width of the output fragment here. \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 -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: +Note that operations such as \function{mul()} or \function{max()} make +no 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: + \begin{verbatim} def mul_stereo(sample, width, lfactor, rfactor): lsample = audioop.tomono(sample, width, 1, 0) @@ -211,26 +225,27 @@ def mul_stereo(sample, width, lfactor, rfactor): rsample = audioop.tostereo(rsample, width, 0, 1) return audioop.add(lsample, rsample, width) \end{verbatim} -% + 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) 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 -\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. +\function{lin2adpcm()}) along to the decoder, not the final state (as +returned by the coder). If you want to use \function{struct.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. The ADPCM coders have never been tried against other ADPCM coders, only against themselves. It could well be that I misinterpreted the standards in which case they will not be interoperable with the respective standards. -The \code{find...} routines might look a bit funny at first sight. +The \function{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: + \begin{verbatim} def echocancel(outputdata, inputdata): pos = audioop.findmax(outputdata, 800) # one tenth second diff --git a/Doc/lib/libbasehttp.tex b/Doc/lib/libbasehttp.tex index 2a4a7d0..7ee55df 100644 --- a/Doc/lib/libbasehttp.tex +++ b/Doc/lib/libbasehttp.tex @@ -1,4 +1,4 @@ -\section{Standard Module \sectcode{BaseHTTPServer}} +\section{Standard Module \module{BaseHTTPServer}} \label{module-BaseHTTPServer} \stmodindex{BaseHTTPServer} @@ -23,18 +23,21 @@ run the server looks like this: \begin{verbatim} def run(server_class=BaseHTTPServer.HTTPServer, handler_class=BaseHTTPServer.BaseHTTPRequestHandler): - server_address = ('', 8000) - httpd = server_class(server_address, handler_class) - httpd.serve_forever() + server_address = ('', 8000) + httpd = server_class(server_address, handler_class) + httpd.serve_forever() \end{verbatim} -The \class{HTTPServer} class builds on the \class{TCPServer} class by +\begin{classdesc}{HTTPServer}{server_address, RequestHandlerClass} +This class builds on the \class{TCPServer} class by storing the server address as instance variables named \member{server_name} and \member{server_port}. The server is accessible by the handler, typically through the handler's \member{server} instance variable. +\end{classdesc} -The module's second class, \class{BaseHTTPRequestHandler}, is used +\begin{classdesc}{BaseHTTPRequestHandler}{request, client_address, server} +This class is used to handle the HTTP requests that arrive at the server. By itself, it cannot respond to any actual HTTP requests; it must be subclassed to handle each request method (e.g. GET or POST). @@ -43,69 +46,69 @@ variables, and methods for use by subclasses. The handler will parse the request and the headers, then call a method specific to the request type. The method name is constructed -from the request. For example, for the request \samp{SPAM}, the +from the request. For example, for the request method \samp{SPAM}, the \method{do_SPAM()} method will be called with no arguments. All of -the relevant information is stored into instance variables of the -handler. +the relevant information is stored in instance variables of the +handler. Subclasses should not need to override or extend the +\method{__init__()} method. +\end{classdesc} -\setindexsubitem{(BaseHTTPRequestHandler attribute)} \class{BaseHTTPRequestHandler} has the following instance variables: -\begin{datadesc}{client_address} +\begin{memberdesc}{client_address} Contains a tuple of the form \code{(\var{host}, \var{port})} referring to the client's address. -\end{datadesc} +\end{memberdesc} -\begin{datadesc}{command} +\begin{memberdesc}{command} Contains the command (request type). For example, \code{'GET'}. -\end{datadesc} +\end{memberdesc} -\begin{datadesc}{path} +\begin{memberdesc}{path} Contains the request path. -\end{datadesc} +\end{memberdesc} -\begin{datadesc}{request_version} +\begin{memberdesc}{request_version} Contains the version string from the request. For example, \code{'HTTP/1.0'}. -\end{datadesc} +\end{memberdesc} -\begin{datadesc}{headers} +\begin{memberdesc}{headers} Holds an instance of the class specified by the \member{MessageClass} class variable. This instance parses and manages the headers in the HTTP request. -\end{datadesc} +\end{memberdesc} -\begin{datadesc}{rfile} +\begin{memberdesc}{rfile} Contains an input stream, positioned at the start of the optional input data. -\end{datadesc} +\end{memberdesc} -\begin{datadesc}{wfile} +\begin{memberdesc}{wfile} Contains the output stream for writing a response back to the client. Proper adherance to the HTTP protocol must be used when writing to this stream. -\end{datadesc} +\end{memberdesc} -\setindexsubitem{(BaseHTTPRequestHandler attribute)} -\code{BaseHTTPRequestHandler} has the following class variables: +\class{BaseHTTPRequestHandler} has the following class variables: -\begin{datadesc}{server_version} +\begin{memberdesc}{server_version} Specifies the server software version. You may want to override this. The format is multiple whitespace-separated strings, where each string is of the form name[/version]. For example, \code{'BaseHTTP/0.2'}. -\end{datadesc} +\end{memberdesc} -\begin{datadesc}{sys_version} +\begin{memberdesc}{sys_version} Contains the Python system version, in a form usable by the \member{version_string} method and the \member{server_version} class variable. For example, \code{'Python/1.4'}. -\end{datadesc} +\end{memberdesc} -\begin{datadesc}{error_message_format} +\begin{memberdesc}{error_message_format} Specifies a format string for building an error response to the client. It uses parenthesized, keyed format specifiers, so the format operand must be a dictionary. The \var{code} key should @@ -115,103 +118,102 @@ message of what occurred, and \var{explain} should be an explanation of the error code number. Default \var{message} and \var{explain} values can found in the \var{responses} class variable. -\end{datadesc} +\end{memberdesc} -\begin{datadesc}{protocol_version} +\begin{memberdesc}{protocol_version} This specifies the HTTP protocol version used in responses. Typically, this should not be overridden. Defaults to \code{'HTTP/1.0'}. -\end{datadesc} +\end{memberdesc} -\begin{datadesc}{MessageClass} +\begin{memberdesc}{MessageClass} Specifies a \class{rfc822.Message}-like class to parse HTTP headers. Typically, this is not overridden, and it defaults to \class{mimetools.Message}. \withsubitem{(in module mimetools)}{\ttindex{Message}} -\end{datadesc} +\end{memberdesc} -\begin{datadesc}{responses} +\begin{memberdesc}{responses} This variable contains a mapping of error code integers to two-element tuples containing a short and long message. For example, \code{\{\var{code}: (\var{shortmessage}, \var{longmessage})\}}. The \var{shortmessage} is usually used as the \var{message} key in an error response, and \var{longmessage} as the \var{explain} key (see the \member{error_message_format} class variable). -\end{datadesc} +\end{memberdesc} -\setindexsubitem{(BaseHTTPRequestHandler method)} A \class{BaseHTTPRequestHandler} instance has the following methods: -\begin{funcdesc}{handle}{} +\begin{methoddesc}{handle}{} Overrides the superclass' \method{handle()} method to provide the specific handler behavior. This method will parse and dispatch -the request to the appropriate \code{do_*()} method. -\end{funcdesc} +the request to the appropriate \method{do_*()} method. +\end{methoddesc} -\begin{funcdesc}{send_error}{code\optional{, message}} +\begin{methoddesc}{send_error}{code\optional{, message}} Sends and logs a complete error reply to the client. The numeric \var{code} specifies the HTTP error code, with \var{message} as optional, more specific text. A complete set of headers is sent, followed by text composed using the \member{error_message_format} class variable. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{send_response}{code\optional{, message}} +\begin{methoddesc}{send_response}{code\optional{, message}} Sends a response header and logs the accepted request. The HTTP response line is sent, followed by \emph{Server} and \emph{Date} headers. The values for these two headers are picked up from the \method{version_string()} and \method{date_time_string()} methods, respectively. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{send_header}{keyword, value} +\begin{methoddesc}{send_header}{keyword, value} Writes a specific MIME header to the output stream. \var{keyword} should specify the header keyword, with \var{value} specifying its value. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{end_headers}{} +\begin{methoddesc}{end_headers}{} Sends a blank line, indicating the end of the MIME headers in the response. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{log_request}{\optional{code\optional{, size}}} +\begin{methoddesc}{log_request}{\optional{code\optional{, size}}} Logs an accepted (successful) request. \var{code} should specify the numeric HTTP code associated with the response. If a size of the response is available, then it should be passed as the \var{size} parameter. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{log_error}{...} +\begin{methoddesc}{log_error}{...} Logs an error when a request cannot be fulfilled. By default, it passes the message to \method{log_message()}, so it takes the same arguments (\var{format} and additional values). -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{log_message}{format, ...} +\begin{methoddesc}{log_message}{format, ...} Logs an arbitrary message to \code{sys.stderr}. This is typically overridden to create custom error logging mechanisms. The \var{format} argument is a standard printf-style format string, where the additional arguments to \method{log_message()} are applied as inputs to the formatting. The client address and current date and time are prefixed to every message logged. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{version_string}{} +\begin{methoddesc}{version_string}{} Returns the server software's version string. This is a combination of the \member{server_version} and \member{sys_version} class variables. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{date_time_string}{} +\begin{methoddesc}{date_time_string}{} Returns the current date and time, formatted for a message header. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{log_data_time_string}{} +\begin{methoddesc}{log_data_time_string}{} Returns the current date and time, formatted for logging. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{address_string}{} +\begin{methoddesc}{address_string}{} Returns the client address, formatted for logging. A name lookup is performed on the client's IP address. -\end{funcdesc} +\end{methoddesc} diff --git a/Doc/lib/libbinhex.tex b/Doc/lib/libbinhex.tex index 560b401..6a7d3c6 100644 --- a/Doc/lib/libbinhex.tex +++ b/Doc/lib/libbinhex.tex @@ -1,15 +1,13 @@ -\section{Standard Module \sectcode{binhex}} +\section{Standard Module \module{binhex}} \label{module-binhex} \stmodindex{binhex} This module encodes and decodes files in binhex4 format, a format -allowing representation of Macintosh files in ASCII. On the macintosh, +allowing representation of Macintosh files in \ASCII{}. On the Macintosh, both forks of a file and the finder information are encoded (or decoded), on other platforms only the data fork is handled. -The \code{binhex} module defines the following functions: - -\setindexsubitem{(in module binhex)} +The \module{binhex} module defines the following functions: \begin{funcdesc}{binhex}{input, output} Convert a binary file with filename \var{input} to binhex file @@ -31,7 +29,8 @@ There is an alternative, more powerful interface to the coder and decoder, see the source for details. If you code or decode textfiles on non-Macintosh platforms they will -still use the macintosh newline convention (carriage-return as end of +still use the Macintosh newline convention (carriage-return as end of line). -As of this writing, \var{hexbin} appears to not work in all cases. +As of this writing, \function{hexbin()} appears to not work in all +cases. diff --git a/Doc/lib/libcd.tex b/Doc/lib/libcd.tex index e2571cc..fc32da5 100644 --- a/Doc/lib/libcd.tex +++ b/Doc/lib/libcd.tex @@ -1,4 +1,4 @@ -\section{Built-in Module \sectcode{cd}} +\section{Built-in Module \module{cd}} \label{module-cd} \bimodindex{cd} @@ -113,32 +113,34 @@ that can be set by the \method{addcallback()} method of CD parser objects (see below). \end{datadesc} + +\subsection{Player Objects} +\label{player-objects} + Player objects (returned by \function{open()}) have the following methods: -\setindexsubitem{(CD player method)} - -\begin{funcdesc}{allowremoval}{} +\begin{methoddesc}[CD player]{allowremoval}{} Unlocks the eject button on the CD-ROM drive permitting the user to eject the caddy if desired. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{bestreadsize}{} +\begin{methoddesc}[CD player]{bestreadsize}{} Returns the best value to use for the \var{num_frames} parameter of the \method{readda()} method. Best is defined as the value that permits a continuous flow of data from the CD-ROM drive. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{close}{} +\begin{methoddesc}[CD player]{close}{} Frees the resources associated with the player object. After calling \method{close()}, the methods of the object should no longer be used. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{eject}{} +\begin{methoddesc}[CD player]{eject}{} Ejects the caddy from the CD-ROM drive. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{getstatus}{} +\begin{methoddesc}[CD player]{getstatus}{} Returns information pertaining to the current state of the CD-ROM drive. The returned information is a tuple with the following values: \var{state}, \var{track}, \var{rtime}, \var{atime}, \var{ttime}, @@ -150,24 +152,24 @@ the meaning of the values, see the man page \manpage{CDgetstatus}{3dm}. The value of \var{state} is one of the following: \constant{ERROR}, \constant{NODISC}, \constant{READY}, \constant{PLAYING}, \constant{PAUSED}, \constant{STILL}, or \constant{CDROM}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{gettrackinfo}{track} +\begin{methoddesc}[CD player]{gettrackinfo}{track} Returns information about the specified track. The returned information is a tuple consisting of two elements, the start time of the track and the duration of the track. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{msftoblock}{min, sec, frame} +\begin{methoddesc}[CD player]{msftoblock}{min, sec, frame} Converts a minutes, seconds, frames triple representing a time in absolute time code into the corresponding logical block number for the given CD-ROM drive. You should use \function{msftoframe()} rather than \method{msftoblock()} for comparing times. The logical block number differs from the frame number by an offset required by certain CD-ROM drives. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{play}{start, play} +\begin{methoddesc}[CD player]{play}{start, play} Starts playback of an audio CD in the CD-ROM drive at the specified track. The audio output appears on the CD-ROM drive's headphone and audio jacks (if fitted). Play stops at the end of the disc. @@ -175,71 +177,73 @@ audio jacks (if fitted). Play stops at the end of the disc. CD; if \var{play} is 0, the CD will be set to an initial paused state. The method \method{togglepause()} can then be used to commence play. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{playabs}{minutes, seconds, frames, play} +\begin{methoddesc}[CD player]{playabs}{minutes, seconds, frames, play} Like \method{play()}, except that the start is given in minutes, seconds, and frames instead of a track number. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{playtrack}{start, play} +\begin{methoddesc}[CD player]{playtrack}{start, play} Like \method{play()}, except that playing stops at the end of the track. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{playtrackabs}{track, minutes, seconds, frames, play} +\begin{methoddesc}[CD player]{playtrackabs}{track, minutes, seconds, frames, play} Like \method{play()}, except that playing begins at the spcified absolute time and ends at the end of the specified track. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{preventremoval}{} +\begin{methoddesc}[CD player]{preventremoval}{} Locks the eject button on the CD-ROM drive thus preventing the user from arbitrarily ejecting the caddy. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{readda}{num_frames} +\begin{methoddesc}[CD player]{readda}{num_frames} Reads the specified number of frames from an audio CD mounted in the CD-ROM drive. The return value is a string representing the audio frames. This string can be passed unaltered to the \method{parseframe()} method of the parser object. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{seek}{minutes, seconds, frames} +\begin{methoddesc}[CD player]{seek}{minutes, seconds, frames} Sets the pointer that indicates the starting point of the next read of digital audio data from a CD-ROM. The pointer is set to an absolute time code location specified in \var{minutes}, \var{seconds}, and \var{frames}. The return value is the logical block number to which the pointer has been set. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{seekblock}{block} +\begin{methoddesc}[CD player]{seekblock}{block} Sets the pointer that indicates the starting point of the next read of digital audio data from a CD-ROM. The pointer is set to the specified logical block number. The return value is the logical block number to which the pointer has been set. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{seektrack}{track} +\begin{methoddesc}[CD player]{seektrack}{track} Sets the pointer that indicates the starting point of the next read of digital audio data from a CD-ROM. The pointer is set to the specified track. The return value is the logical block number to which the pointer has been set. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{stop}{} +\begin{methoddesc}[CD player]{stop}{} Stops the current playing operation. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{togglepause}{} +\begin{methoddesc}[CD player]{togglepause}{} Pauses the CD if it is playing, and makes it play if it is paused. -\end{funcdesc} +\end{methoddesc} + + +\subsection{Parser Objects} +\label{cd-parser-objects} Parser objects (returned by \function{createparser()}) have the following methods: -\setindexsubitem{(CD parser method)} - -\begin{funcdesc}{addcallback}{type, func, arg} +\begin{methoddesc}[CD parser]{addcallback}{type, func, arg} Adds a callback for the parser. The parser has callbacks for eight different types of data in the digital audio data stream. Constants for these types are defined at the \module{cd} module level (see above). @@ -268,15 +272,15 @@ owner code, \\ \lineii{control}{Integer giving the control bits from the CD subcode data} \end{tableii} -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{deleteparser}{} +\begin{methoddesc}[CD parser]{deleteparser}{} Deletes the parser and frees the memory it was using. The object should not be used after this call. This call is done automatically when the last reference to the object is removed. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{parseframe}{frame} +\begin{methoddesc}[CD parser]{parseframe}{frame} Parses one or more frames of digital audio data from a CD such as returned by \method{readda()}. It determines which subcodes are present in the data. If these subcodes have changed since the last @@ -284,14 +288,14 @@ frame, then \method{parseframe()} executes a callback of the appropriate type passing to it the subcode data found in the frame. Unlike the \C{} function, more than one frame of digital audio data can be passed to this method. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{removecallback}{type} +\begin{methoddesc}[CD parser]{removecallback}{type} Removes the callback for the given \var{type}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{resetparser}{} +\begin{methoddesc}[CD parser]{resetparser}{} Resets the fields of the parser used for tracking subcodes to an initial state. \method{resetparser()} should be called after the disc has been changed. -\end{funcdesc} +\end{methoddesc} diff --git a/Doc/lib/libfl.tex b/Doc/lib/libfl.tex index 4716e7b..a0e0076 100644 --- a/Doc/lib/libfl.tex +++ b/Doc/lib/libfl.tex @@ -1,4 +1,4 @@ -\section{Built-in Module \sectcode{fl}} +\section{Built-in Module \module{fl}} \label{module-fl} \bimodindex{fl} @@ -37,7 +37,7 @@ FORMS with pure GL windows. function \cfunction{foreground()} and to the FORMS routine \cfunction{fl_init()}. -\subsection{Functions Defined in Module \sectcode{fl}} +\subsection{Functions Defined in Module \module{fl}} \nodename{FL Functions} Module \module{fl} defines the following functions. For more @@ -83,7 +83,8 @@ Show a dialog box with a three-line message and YES and NO buttons. It returns \code{1} if the user pressed YES, \code{0} if NO. \end{funcdesc} -\begin{funcdesc}{show_choice}{str1, str2, str3, but1\optional{, but2, but3}} +\begin{funcdesc}{show_choice}{str1, str2, str3, but1\optional{, + but2\optional{, but3}}} Show a dialog box with a three-line message and up to three buttons. It returns the number of the button clicked by the user (\code{1}, \code{2} or \code{3}). @@ -136,116 +137,117 @@ See the description in the FORMS documentation of \end{funcdesc} \subsection{Form Objects} +\label{form-objects} -Form objects (returned by \function{fl.make_form()} above) have the +Form objects (returned by \function{make_form()} above) have the following methods. Each method corresponds to a \C{} function whose name is prefixed with \samp{fl_}; and whose first argument is a form pointer; please refer to the official FORMS documentation for descriptions. -All the \code{add_*()} functions return a Python object -representing the FORMS object. Methods of FORMS objects are described -below. Most kinds of FORMS object also have some methods specific to -that kind; these methods are listed here. +All the \method{add_*()} methods return a Python object representing +the FORMS object. Methods of FORMS objects are described below. Most +kinds of FORMS object also have some methods specific to that kind; +these methods are listed here. \begin{flushleft} -\setindexsubitem{(form method)} -\begin{funcdesc}{show_form}{placement, bordertype, name} + +\begin{methoddesc}[form]{show_form}{placement, bordertype, name} Show the form. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{hide_form}{} +\begin{methoddesc}[form]{hide_form}{} Hide the form. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{redraw_form}{} +\begin{methoddesc}[form]{redraw_form}{} Redraw the form. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{set_form_position}{x, y} +\begin{methoddesc}[form]{set_form_position}{x, y} Set the form's position. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{freeze_form}{} +\begin{methoddesc}[form]{freeze_form}{} Freeze the form. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{unfreeze_form}{} +\begin{methoddesc}[form]{unfreeze_form}{} Unfreeze the form. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{activate_form}{} +\begin{methoddesc}[form]{activate_form}{} Activate the form. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{deactivate_form}{} +\begin{methoddesc}[form]{deactivate_form}{} Deactivate the form. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{bgn_group}{} +\begin{methoddesc}[form]{bgn_group}{} Begin a new group of objects; return a group object. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{end_group}{} +\begin{methoddesc}[form]{end_group}{} End the current group of objects. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{find_first}{} +\begin{methoddesc}[form]{find_first}{} Find the first object in the form. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{find_last}{} +\begin{methoddesc}[form]{find_last}{} Find the last object in the form. -\end{funcdesc} +\end{methoddesc} %--- -\begin{funcdesc}{add_box}{type, x, y, w, h, name} +\begin{methoddesc}[form]{add_box}{type, x, y, w, h, name} Add a box object to the form. No extra methods. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{add_text}{type, x, y, w, h, name} +\begin{methoddesc}[form]{add_text}{type, x, y, w, h, name} Add a text object to the form. No extra methods. -\end{funcdesc} +\end{methoddesc} -%\begin{funcdesc}{add_bitmap}{type, x, y, w, h, name} +%\begin{methoddesc}[form]{add_bitmap}{type, x, y, w, h, name} %Add a bitmap object to the form. -%\end{funcdesc} +%\end{methoddesc} -\begin{funcdesc}{add_clock}{type, x, y, w, h, name} +\begin{methoddesc}[form]{add_clock}{type, x, y, w, h, name} Add a clock object to the form. \\ Method: \method{get_clock()}. -\end{funcdesc} +\end{methoddesc} %--- -\begin{funcdesc}{add_button}{type, x, y, w, h, name} +\begin{methoddesc}[form]{add_button}{type, x, y, w, h, name} Add a button object to the form. \\ Methods: \method{get_button()}, \method{set_button()}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{add_lightbutton}{type, x, y, w, h, name} +\begin{methoddesc}[form]{add_lightbutton}{type, x, y, w, h, name} Add a lightbutton object to the form. \\ Methods: \method{get_button()}, \method{set_button()}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{add_roundbutton}{type, x, y, w, h, name} +\begin{methoddesc}[form]{add_roundbutton}{type, x, y, w, h, name} Add a roundbutton object to the form. \\ Methods: \method{get_button()}, \method{set_button()}. -\end{funcdesc} +\end{methoddesc} %--- -\begin{funcdesc}{add_slider}{type, x, y, w, h, name} +\begin{methoddesc}[form]{add_slider}{type, x, y, w, h, name} Add a slider object to the form. \\ Methods: \method{set_slider_value()}, @@ -256,9 +258,9 @@ Methods: \method{set_slider_size()}, \method{set_slider_precision()}, \method{set_slider_step()}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{add_valslider}{type, x, y, w, h, name} +\begin{methoddesc}[form]{add_valslider}{type, x, y, w, h, name} Add a valslider object to the form. \\ Methods: \method{set_slider_value()}, @@ -269,18 +271,18 @@ Methods: \method{set_slider_size()}, \method{set_slider_precision()}, \method{set_slider_step()}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{add_dial}{type, x, y, w, h, name} +\begin{methoddesc}[form]{add_dial}{type, x, y, w, h, name} Add a dial object to the form. \\ Methods: \method{set_dial_value()}, \method{get_dial_value()}, \method{set_dial_bounds()}, \method{get_dial_bounds()}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{add_positioner}{type, x, y, w, h, name} +\begin{methoddesc}[form]{add_positioner}{type, x, y, w, h, name} Add a positioner object to the form. \\ Methods: \method{set_positioner_xvalue()}, @@ -291,9 +293,9 @@ Methods: \method{get_positioner_yvalue()}, \method{get_positioner_xbounds()}, \method{get_positioner_ybounds()}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{add_counter}{type, x, y, w, h, name} +\begin{methoddesc}[form]{add_counter}{type, x, y, w, h, name} Add a counter object to the form. \\ Methods: \method{set_counter_value()}, @@ -302,30 +304,30 @@ Methods: \method{set_counter_step()}, \method{set_counter_precision()}, \method{set_counter_return()}. -\end{funcdesc} +\end{methoddesc} %--- -\begin{funcdesc}{add_input}{type, x, y, w, h, name} +\begin{methoddesc}[form]{add_input}{type, x, y, w, h, name} Add a input object to the form. \\ Methods: \method{set_input()}, \method{get_input()}, \method{set_input_color()}, \method{set_input_return()}. -\end{funcdesc} +\end{methoddesc} %--- -\begin{funcdesc}{add_menu}{type, x, y, w, h, name} +\begin{methoddesc}[form]{add_menu}{type, x, y, w, h, name} Add a menu object to the form. \\ Methods: \method{set_menu()}, \method{get_menu()}, \method{addto_menu()}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{add_choice}{type, x, y, w, h, name} +\begin{methoddesc}[form]{add_choice}{type, x, y, w, h, name} Add a choice object to the form. \\ Methods: \method{set_choice()}, @@ -337,9 +339,9 @@ Methods: \method{get_choice_text()}, \method{set_choice_fontsize()}, \method{set_choice_fontstyle()}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{add_browser}{type, x, y, w, h, name} +\begin{methoddesc}[form]{add_browser}{type, x, y, w, h, name} Add a browser object to the form. \\ Methods: \method{set_browser_topline()}, @@ -360,16 +362,16 @@ Methods: \method{set_browser_fontsize()}, \method{set_browser_fontstyle()}, \method{set_browser_specialkey()}. -\end{funcdesc} +\end{methoddesc} %--- -\begin{funcdesc}{add_timer}{type, x, y, w, h, name} +\begin{methoddesc}[form]{add_timer}{type, x, y, w, h, name} Add a timer object to the form. \\ Methods: \method{set_timer()}, \method{get_timer()}. -\end{funcdesc} +\end{methoddesc} \end{flushleft} Form objects have the following data attributes; see the FORMS @@ -388,49 +390,49 @@ documentation: \end{tableiii} \subsection{FORMS Objects} +\label{forms-objects} Besides methods specific to particular kinds of FORMS objects, all FORMS objects also have the following methods: -\setindexsubitem{(FORMS method)} -\begin{funcdesc}{set_call_back}{function, argument} +\begin{methoddesc}[FORMS object]{set_call_back}{function, argument} Set the object's callback function and argument. When the object needs interaction, the callback function will be called with two arguments: the object, and the callback argument. (FORMS objects without a callback function are returned by \function{fl.do_forms()} or \function{fl.check_forms()} when they need interaction.) Call this method without arguments to remove the callback function. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{delete_object}{} +\begin{methoddesc}[FORMS object]{delete_object}{} Delete the object. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{show_object}{} +\begin{methoddesc}[FORMS object]{show_object}{} Show the object. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{hide_object}{} +\begin{methoddesc}[FORMS object]{hide_object}{} Hide the object. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{redraw_object}{} +\begin{methoddesc}[FORMS object]{redraw_object}{} Redraw the object. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{freeze_object}{} +\begin{methoddesc}[FORMS object]{freeze_object}{} Freeze the object. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{unfreeze_object}{} +\begin{methoddesc}[FORMS object]{unfreeze_object}{} Unfreeze the object. -\end{funcdesc} +\end{methoddesc} -%\begin{funcdesc}{handle_object}{} XXX -%\end{funcdesc} +%\begin{methoddesc}[FORMS object]{handle_object}{} XXX +%\end{methoddesc} -%\begin{funcdesc}{handle_object_direct}{} XXX -%\end{funcdesc} +%\begin{methoddesc}[FORMS object]{handle_object_direct}{} XXX +%\end{methoddesc} FORMS objects have these data attributes; see the FORMS documentation: @@ -460,7 +462,7 @@ FORMS objects have these data attributes; see the FORMS documentation: \lineiii{automatic}{int (read-only)}{(see FORMS docs)} \end{tableiii} -\section{Standard Module \sectcode{FL}} +\section{Standard Module \module{FL}} \label{module-FLuppercase} \stmodindex{FL} @@ -475,7 +477,7 @@ import fl from FL import * \end{verbatim} -\section{Standard Module \sectcode{flp}} +\section{Standard Module \module{flp}} \label{module-flp} \stmodindex{flp} diff --git a/Doc/lib/libftplib.tex b/Doc/lib/libftplib.tex index cda8b66..7f0aeda 100644 --- a/Doc/lib/libftplib.tex +++ b/Doc/lib/libftplib.tex @@ -1,4 +1,4 @@ -\section{Standard Module \sectcode{ftplib}} +\section{Standard Module \module{ftplib}} \label{module-ftplib} \stmodindex{ftplib} \indexii{FTP}{protocol} @@ -30,7 +30,8 @@ dr-xr-srwt 105 ftp-usr pdmaint 1536 Mar 21 14:32 .. The module defines the following items: -\begin{classdesc}{FTP}{\optional{host\optional{, user\optional{, passwd\optional{, acct}}}}} +\begin{classdesc}{FTP}{\optional{host\optional{, user\optional{, + passwd\optional{, acct}}}}} Return a new instance of the \code{FTP} class. When \var{host} is given, the method call \code{connect(\var{host})} is made. When \var{user} is given, additionally the method call @@ -63,37 +64,37 @@ Exception raised when a reply is received from the server that does not begin with a digit in the range 1--5. \end{excdesc} + \subsection{FTP Objects} +\label{ftp-objects} \class{FTP} instances have the following methods: -\setindexsubitem{(FTP method)} - -\begin{funcdesc}{set_debuglevel}{level} +\begin{methoddesc}{set_debuglevel}{level} Set the instance's debugging level. This controls the amount of debugging output printed. The default, \code{0}, produces no debugging output. A value of \code{1} produces a moderate amount of debugging output, generally a single line per request. A value of \code{2} or higher produces the maximum amount of debugging output, logging each line sent and received on the control connection. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{connect}{host\optional{, port}} +\begin{methoddesc}{connect}{host\optional{, port}} Connect to the given host and port. The default port number is \code{21}, as specified by the FTP protocol specification. It is rarely needed to specify a different port number. This function should be called only once for each instance; it should not be called at all if a host was given when the instance was created. All other methods can only be used after a connection has been made. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{getwelcome}{} +\begin{methoddesc}{getwelcome}{} Return the welcome message sent by the server in reply to the initial connection. (This message sometimes contains disclaimers or help information that may be relevant to the user.) -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{login}{\optional{user\optional{, passwd\optional{, acct}}}} +\begin{methoddesc}{login}{\optional{user\optional{, passwd\optional{, acct}}}} Log in as the given \var{user}. The \var{passwd} and \var{acct} parameters are optional and default to the empty string. If no \var{user} is specified, it defaults to \code{'anonymous'}. If @@ -106,25 +107,25 @@ once for each instance, after a connection has been established; it should not be called at all if a host and user were given when the instance was created. Most FTP commands are only allowed after the client has logged in. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{abort}{} +\begin{methoddesc}{abort}{} Abort a file transfer that is in progress. Using this does not always work, but it's worth a try. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{sendcmd}{command} +\begin{methoddesc}{sendcmd}{command} Send a simple command string to the server and return the response string. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{voidcmd}{command} +\begin{methoddesc}{voidcmd}{command} Send a simple command string to the server and handle the response. Return nothing if a response code in the range 200--299 is received. Raise an exception otherwise. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{retrbinary}{command, callback\optional{, maxblocksize}} +\begin{methoddesc}{retrbinary}{command, callback\optional{, maxblocksize}} Retrieve a file in binary transfer mode. \var{command} should be an appropriate \samp{RETR} command, i.e.\ \code{'RETR \var{filename}'}. The \var{callback} function is called for each block of data received, @@ -133,73 +134,73 @@ The optional \var{maxblocksize} argument specifies the maximum chunk size to read on the low-level socket object created to do the actual transfer (which will also be the largest size of the data blocks passed to \var{callback}). A reasonable default is chosen. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{retrlines}{command\optional{, callback}} +\begin{methoddesc}{retrlines}{command\optional{, callback}} Retrieve a file or directory listing in \ASCII{} transfer mode. \var{command} should be an appropriate \samp{RETR} command (see \method{retrbinary()} or a \samp{LIST} command (usually just the string \code{'LIST'}). The \var{callback} function is called for each line, with the trailing CRLF stripped. The default \var{callback} prints the line to \code{sys.stdout}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{storbinary}{command, file, blocksize} +\begin{methoddesc}{storbinary}{command, file, blocksize} Store a file in binary transfer mode. \var{command} should be an appropriate \samp{STOR} command, i.e.\ \code{"STOR \var{filename}"}. \var{file} is an open file object which is read until \EOF{} using its \method{read()} method in blocks of size \var{blocksize} to provide the data to be stored. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{storlines}{command, file} +\begin{methoddesc}{storlines}{command, file} Store a file in \ASCII{} transfer mode. \var{command} should be an appropriate \samp{STOR} command (see \method{storbinary()}). Lines are read until \EOF{} from the open file object \var{file} using its \method{readline()} method to privide the data to be stored. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{nlst}{argument\optional{, \ldots}} +\begin{methoddesc}{nlst}{argument\optional{, \ldots}} Return a list of files as returned by the \samp{NLST} command. The optional \var{argument} is a directory to list (default is the current server directory). Multiple arguments can be used to pass non-standard options to the \samp{NLST} command. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{dir}{argument\optional{, \ldots}} +\begin{methoddesc}{dir}{argument\optional{, \ldots}} Return a directory listing as returned by the \samp{LIST} command, as a list of lines. The optional \var{argument} is a directory to list (default is the current server directory). Multiple arguments can be used to pass non-standard options to the \samp{LIST} command. If the last argument is a function, it is used as a \var{callback} function as for \method{retrlines()}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{rename}{fromname, toname} +\begin{methoddesc}{rename}{fromname, toname} Rename file \var{fromname} on the server to \var{toname}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{cwd}{pathname} +\begin{methoddesc}{cwd}{pathname} Set the current directory on the server. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{mkd}{pathname} +\begin{methoddesc}{mkd}{pathname} Create a new directory on the server. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{pwd}{} +\begin{methoddesc}{pwd}{} Return the pathname of the current directory on the server. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{quit}{} +\begin{methoddesc}{quit}{} Send a \samp{QUIT} command to the server and close the connection. This is the ``polite'' way to close a connection, but it may raise an exception of the server reponds with an error to the \samp{QUIT} command. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{close}{} +\begin{methoddesc}{close}{} Close the connection unilaterally. This should not be applied to an already closed connection (e.g.\ after a successful call to \method{quit()}. -\end{funcdesc} +\end{methoddesc} diff --git a/Doc/lib/libhttplib.tex b/Doc/lib/libhttplib.tex index d578ae2..55ec9b98 100644 --- a/Doc/lib/libhttplib.tex +++ b/Doc/lib/libhttplib.tex @@ -1,4 +1,4 @@ -\section{Standard Module \sectcode{httplib}} +\section{Standard Module \module{httplib}} \label{module-httplib} \stmodindex{httplib} \indexii{HTTP}{protocol} @@ -9,7 +9,10 @@ HTTP protocol. It is normally not used directly --- the module \module{urllib}\refstmodindex{urllib} uses it to handle URLs that use HTTP. -The module defines one class, \class{HTTP}. An \class{HTTP} instance +The module defines one class, \class{HTTP}: + +\begin{classdesc}{HTTP}{\optional{host\optional{, port}}} +An \class{HTTP} instance represents one transaction with an HTTP server. It should be instantiated passing it a host and optional port number. If no port number is passed, the port is extracted from the host string if it has @@ -45,50 +48,50 @@ step 4 makes no calls). file object that it returns. \end{enumerate} +\end{classdesc} \subsection{HTTP Objects} \class{HTTP} instances have the following methods: -\setindexsubitem{(HTTP method)} -\begin{funcdesc}{set_debuglevel}{level} +\begin{methoddesc}{set_debuglevel}{level} Set the debugging level (the amount of debugging output printed). The default debug level is \code{0}, meaning no debugging output is printed. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{connect}{host\optional{, port}} +\begin{methoddesc}{connect}{host\optional{, port}} Connect to the server given by \var{host} and \var{port}. See the intro for the default port. This should be called directly only if the instance was instantiated without passing a host. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{send}{data} +\begin{methoddesc}{send}{data} Send data to the server. This should be used directly only after the \method{endheaders()} method has been called and before \method{getreply()} has been called. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{putrequest}{request, selector} +\begin{methoddesc}{putrequest}{request, selector} This should be the first call after the connection to the server has been made. It sends a line to the server consisting of the \var{request} string, the \var{selector} string, and the HTTP version (\code{HTTP/1.0}). -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{putheader}{header, argument\optional{, ...}} +\begin{methoddesc}{putheader}{header, argument\optional{, ...}} Send an \rfc{822} style header to the server. It sends a line to the server consisting of the header, a colon and a space, and the first argument. If more arguments are given, continuation lines are sent, each consisting of a tab and an argument. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{endheaders}{} +\begin{methoddesc}{endheaders}{} Send a blank line to the server, signalling the end of the headers. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{getreply}{} +\begin{methoddesc}{getreply}{} Complete the request by shutting down the sending end of the socket, read the reply from the server, and return a triple \code{(\var{replycode}, \var{message}, \var{headers})}. Here, @@ -98,13 +101,13 @@ message string corresponding to the reply code; and \var{headers} is an instance of the class \class{mimetools.Message} containing the headers received from the server. See the description of the \module{mimetools}\refstmodindex{mimetools} module. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{getfile}{} +\begin{methoddesc}{getfile}{} Return a file object from which the data returned by the server can be read, using the \method{read()}, \method{readline()} or \method{readlines()} methods. -\end{funcdesc} +\end{methoddesc} \subsection{Example} \nodename{HTTP Example} @@ -123,5 +126,4 @@ Here is an example session: >>> f = h.getfile() >>> data = f.read() # Get the raw HTML >>> f.close() ->>> \end{verbatim} diff --git a/Doc/lib/libimageop.tex b/Doc/lib/libimageop.tex index 4a93487..c21be48 100644 --- a/Doc/lib/libimageop.tex +++ b/Doc/lib/libimageop.tex @@ -1,16 +1,14 @@ -\section{Built-in Module \sectcode{imageop}} +\section{Built-in Module \module{imageop}} \label{module-imageop} \bimodindex{imageop} -The \code{imageop} module contains some useful operations on images. -It operates on images consisting of 8 or 32 bit pixels -stored in Python strings. This is the same format as used -by \code{gl.lrectwrite} and the \code{imgfile} module. +The \module{imageop} module contains some useful operations on images. +It operates on images consisting of 8 or 32 bit pixels stored in +Python strings. This is the same format as used by +\function{gl.lrectwrite()} and the \module{imgfile} module. The module defines the following variables and functions: -\setindexsubitem{(in module imageop)} - \begin{excdesc}{error} This exception is raised on all errors, such as unknown number of bits per pixel, etc. @@ -21,11 +19,11 @@ per pixel, etc. Return the selected part of \var{image}, which should by \var{width} by \var{height} in size and consist of pixels of \var{psize} bytes. \var{x0}, \var{y0}, \var{x1} and \var{y1} are like -the \code{lrectread} parameters, i.e.\ the boundary is included in the -new image. The new boundaries need not be inside the picture. Pixels -that fall outside the old image will have their value set to zero. If -\var{x0} is bigger than \var{x1} the new image is mirrored. The same -holds for the y coordinates. +the \function{gl.lrectread()} parameters, i.e.\ the boundary is +included in the new image. The new boundaries need not be inside the +picture. Pixels that fall outside the old image will have their value +set to zero. If \var{x0} is bigger than \var{x1} the new image is +mirrored. The same holds for the y coordinates. \end{funcdesc} \begin{funcdesc}{scale}{image, psize, width, height, newwidth, newheight} @@ -46,7 +44,7 @@ interlacing, hence the name. \begin{funcdesc}{grey2mono}{image, width, height, threshold} Convert a 8-bit deep greyscale image to a 1-bit deep image by tresholding all the pixels. The resulting image is tightly packed and -is probably only useful as an argument to \code{mono2grey}. +is probably only useful as an argument to \function{mono2grey()}. \end{funcdesc} \begin{funcdesc}{dither2mono}{image, width, height} @@ -74,8 +72,8 @@ dithering. \begin{funcdesc}{dither2grey2}{image, width, height} Convert an 8-bit greyscale image to a 2-bit greyscale image with -dithering. As for \code{dither2mono}, the dithering algorithm is -currently very simple. +dithering. As for \function{dither2mono()}, the dithering algorithm +is currently very simple. \end{funcdesc} \begin{funcdesc}{grey42grey}{image, width, height} diff --git a/Doc/lib/libjpeg.tex b/Doc/lib/libjpeg.tex index 745fe32..201a142 100644 --- a/Doc/lib/libjpeg.tex +++ b/Doc/lib/libjpeg.tex @@ -1,10 +1,12 @@ -\section{Built-in Module \sectcode{jpeg}} +\section{Built-in Module \module{jpeg}} \label{module-jpeg} \bimodindex{jpeg} The module \module{jpeg} provides access to the jpeg compressor and -decompressor written by the Independent JPEG Group. JPEG is a (draft?) -standard for compressing pictures. For details on jpeg or the +decompressor written by the Independent JPEG Group% +\index{Independent JPEG Group}% +. JPEG is a (draft?) +standard for compressing pictures. For details on JPEG or the Independent JPEG Group software refer to the JPEG standard or the documentation provided with the software. @@ -18,19 +20,19 @@ in case of errors. \begin{funcdesc}{compress}{data, w, h, b} Treat data as a pixmap of width \var{w} and height \var{h}, with \var{b} bytes per pixel. The data is in SGI GL order, so the first -pixel is in the lower-left corner. This means that \code{gl.lrectread} +pixel is in the lower-left corner. This means that \function{gl.lrectread()} return data can immediately be passed to \function{compress()}. Currently only 1 byte and 4 byte pixels are allowed, the former being treated as greyscale and the latter as RGB color. \function{compress()} returns a string that contains the compressed -picture, in JFIF format. +picture, in JFIF\index{JFIF} format. \end{funcdesc} \begin{funcdesc}{decompress}{data} -Data is a string containing a picture in JFIF format. It returns a -tuple \code{(\var{data}, \var{width}, \var{height}, +Data is a string containing a picture in JFIF\index{JFIF} format. It +returns a tuple \code{(\var{data}, \var{width}, \var{height}, \var{bytesperpixel})}. Again, the data is suitable to pass to -\code{gl.lrectwrite}. +\function{gl.lrectwrite()}. \end{funcdesc} \begin{funcdesc}{setoption}{name, value} diff --git a/Doc/lib/libmimetools.tex b/Doc/lib/libmimetools.tex index 0d4e40f..54d1fe0 100644 --- a/Doc/lib/libmimetools.tex +++ b/Doc/lib/libmimetools.tex @@ -1,8 +1,7 @@ -\section{Standard Module \sectcode{mimetools}} +\section{Standard Module \module{mimetools}} \label{module-mimetools} \stmodindex{mimetools} -\setindexsubitem{(in module mimetools)} This module defines a subclass of the \class{rfc822.Message} class and a number of utility functions that are useful for the manipulation for @@ -53,9 +52,7 @@ open file \var{output}. The block size is currently fixed at 8192. The \class{Message} class defines the following methods in addition to the \class{rfc822.Message} methods: -\setindexsubitem{(mimetool.Message method)} - -\begin{funcdesc}{getplist}{} +\begin{methoddesc}{getplist}{} Return the parameter list of the \code{content-type} header. This is a list if strings. For parameters of the form \samp{\var{key}=\var{value}}, \var{key} is converted to lower case but @@ -63,36 +60,36 @@ a list if strings. For parameters of the form \samp{Content-type: text/html; spam=1; Spam=2; Spam} then \method{getplist()} will return the Python list \code{['spam=1', 'spam=2', 'Spam']}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{getparam}{name} +\begin{methoddesc}{getparam}{name} Return the \var{value} of the first parameter (as returned by \method{getplist()} of the form \samp{\var{name}=\var{value}} for the given \var{name}. If \var{value} is surrounded by quotes of the form `\code{<}...\code{>}' or `\code{"}...\code{"}', these are removed. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{getencoding}{} +\begin{methoddesc}{getencoding}{} Return the encoding specified in the \code{content-transfer-encoding} message header. If no such header exists, return \code{'7bit'}. The encoding is converted to lower case. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{gettype}{} +\begin{methoddesc}{gettype}{} Return the message type (of the form \samp{\var{type}/\var{subtype}}) as specified in the \code{content-type} header. If no such header exists, return \code{'text/plain'}. The type is converted to lower case. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{getmaintype}{} +\begin{methoddesc}{getmaintype}{} Return the main type as specified in the \code{content-type} header. If no such header exists, return \code{'text'}. The main type is converted to lower case. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{getsubtype}{} +\begin{methoddesc}{getsubtype}{} Return the subtype as specified in the \code{content-type} header. If no such header exists, return \code{'plain'}. The subtype is converted to lower case. -\end{funcdesc} +\end{methoddesc} diff --git a/Doc/lib/libmpz.tex b/Doc/lib/libmpz.tex index 1c4b19f..707a3a8 100644 --- a/Doc/lib/libmpz.tex +++ b/Doc/lib/libmpz.tex @@ -1,38 +1,48 @@ -\section{Built-in Module \sectcode{mpz}} +\section{Built-in Module \module{mpz}} \label{module-mpz} \bimodindex{mpz} This is an optional module. It is only available when Python is configured to include it, which requires that the GNU MP software is installed. +\index{MP, GNU library} +\index{arbitrary precision integers} +\index{integer!arbitrary precision} This module implements the interface to part of the GNU MP library, which defines arbitrary precision integer and rational number arithmetic routines. Only the interfaces to the \emph{integer} -(\samp{mpz_{\rm \ldots}}) routines are provided. If not stated +(\function{mpz_*()}) routines are provided. If not stated otherwise, the description in the GNU MP documentation can be applied. In general, \dfn{mpz}-numbers can be used just like other standard Python numbers, e.g.\ you can use the built-in operators like \code{+}, \code{*}, etc., as well as the standard built-in functions like -\code{abs}, \code{int}, \ldots, \code{divmod}, \code{pow}. -\strong{Please note:} the \emph{bitwise-xor} operation has been implemented as -a bunch of \emph{and}s, \emph{invert}s and \emph{or}s, because the library -lacks an \code{mpz_xor} function, and I didn't need one. +\function{abs()}, \function{int()}, \ldots, \function{divmod()}, +\function{pow()}. \strong{Please note:} the \emph{bitwise-xor} +operation has been implemented as a bunch of \emph{and}s, +\emph{invert}s and \emph{or}s, because the library lacks an +\cfunction{mpz_xor()} function, and I didn't need one. -You create an mpz-number by calling the function called \code{mpz} (see +You create an mpz-number by calling the function \function{mpz()} (see below for an exact description). An mpz-number is printed like this: \code{mpz(\var{value})}. -\setindexsubitem{(in module mpz)} + \begin{funcdesc}{mpz}{value} Create a new mpz-number. \var{value} can be an integer, a long, another mpz-number, or even a string. If it is a string, it is interpreted as an array of radix-256 digits, least significant digit - first, resulting in a positive number. See also the \code{binary} + first, resulting in a positive number. See also the \method{binary()} method, described below. \end{funcdesc} +\begin{datadesc}{MPZType} + The type of the objects returned by \function{mpz()} and most other + functions in this module. +\end{datadesc} + + A number of \emph{extra} functions are defined in this module. Non mpz-arguments are converted to mpz-values first, and the functions return mpz-numbers. @@ -40,7 +50,7 @@ return mpz-numbers. \begin{funcdesc}{powm}{base, exponent, modulus} Return \code{pow(\var{base}, \var{exponent}) \%{} \var{modulus}}. If \code{\var{exponent} == 0}, return \code{mpz(1)}. In contrast to the - \C-library function, this version can handle negative exponents. + \C{} library function, this version can handle negative exponents. \end{funcdesc} \begin{funcdesc}{gcd}{op1, op2} @@ -62,18 +72,18 @@ return mpz-numbers. \end{funcdesc} \begin{funcdesc}{divm}{numerator, denominator, modulus} - Returns a number \var{q}. such that - \code{\var{q} * \var{denominator} \%{} \var{modulus} == \var{numerator}}. - One could also implement this function in Python, using \code{gcdext}. + Returns a number \var{q} such that + \code{\var{q} * \var{denominator} \%{} \var{modulus} == + \var{numerator}}. One could also implement this function in Python, + using \function{gcdext()}. \end{funcdesc} An mpz-number has one method: -\setindexsubitem{(mpz method)} -\begin{funcdesc}{binary}{} +\begin{methoddesc}[mpz]{binary}{} Convert this mpz-number to a binary string, where the number has been stored as an array of radix-256 digits, least significant digit first. The mpz-number must have a value greater than or equal to zero, - otherwise a \code{ValueError}-exception will be raised. -\end{funcdesc} + otherwise \exception{ValueError} will be raised. +\end{methoddesc} diff --git a/Doc/lib/libnntplib.tex b/Doc/lib/libnntplib.tex index 75c84d3..ba1d788 100644 --- a/Doc/lib/libnntplib.tex +++ b/Doc/lib/libnntplib.tex @@ -1,11 +1,10 @@ -\section{Standard Module \sectcode{nntplib}} +\section{Standard Module \module{nntplib}} \label{module-nntplib} \stmodindex{nntplib} \indexii{NNTP}{protocol} -\setindexsubitem{(in module nntplib)} -This module defines the class \code{NNTP} which implements the client +This module defines the class \class{NNTP} which implements the client side of the NNTP protocol. It can be used to implement a news reader or poster, or automated news processors. For more information on NNTP (Network News Transfer Protocol), see Internet \rfc{977}. @@ -34,7 +33,6 @@ Group comp.lang.python has 59 articles, range 3742 to 3803 3803 Re: \POSIX{} wait and SIGCHLD >>> s.quit() '205 news.cwi.nl closing connection. Goodbye.' ->>> \end{verbatim} To post an article from a file (this assumes that the article has @@ -47,16 +45,15 @@ valid headers): '240 Article posted successfully.' >>> s.quit() '205 news.cwi.nl closing connection. Goodbye.' ->>> \end{verbatim} % The module itself defines the following items: -\begin{funcdesc}{NNTP}{host\optional{, port}} -Return a new instance of the \code{NNTP} class, representing a +\begin{classdesc}{NNTP}{host\optional{, port}} +Return a new instance of the \class{NNTP} class, representing a connection to the NNTP server running on host \var{host}, listening at port \var{port}. The default \var{port} is 119. -\end{funcdesc} +\end{classdesc} \begin{excdesc}{error_reply} Exception raised when an unexpected reply is received from the server. @@ -75,7 +72,9 @@ Exception raised when a reply is received from the server that does not begin with a digit in the range 1--5. \end{excdesc} + \subsection{NNTP Objects} +\label{nntp-objects} NNTP instances have the following methods. The \var{response} that is returned as the first item in the return tuple of almost all methods @@ -83,40 +82,40 @@ is the server's response: a string beginning with a three-digit code. If the server's response indicates an error, the method raises one of the above exceptions. -\setindexsubitem{(NNTP object method)} -\begin{funcdesc}{getwelcome}{} +\begin{methoddesc}{getwelcome}{} Return the welcome message sent by the server in reply to the initial connection. (This message sometimes contains disclaimers or help information that may be relevant to the user.) -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{set_debuglevel}{level} +\begin{methoddesc}{set_debuglevel}{level} Set the instance's debugging level. This controls the amount of -debugging output printed. The default, 0, produces no debugging -output. A value of 1 produces a moderate amount of debugging output, -generally a single line per request or response. A value of 2 or -higher produces the maximum amount of debugging output, logging each -line sent and received on the connection (including message text). -\end{funcdesc} - -\begin{funcdesc}{newgroups}{date, time} +debugging output printed. The default, \code{0}, produces no debugging +output. A value of \code{1} produces a moderate amount of debugging +output, generally a single line per request or response. A value of +\code{2} or higher produces the maximum amount of debugging output, +logging each line sent and received on the connection (including +message text). +\end{methoddesc} + +\begin{methoddesc}{newgroups}{date, time} Send a \samp{NEWGROUPS} command. The \var{date} argument should be a string of the form \code{"\var{yy}\var{mm}\var{dd}"} indicating the date, and \var{time} should be a string of the form \code{"\var{hh}\var{mm}\var{ss}"} indicating the time. Return a pair \code{(\var{response}, \var{groups})} where \var{groups} is a list of group names that are new since the given date and time. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{newnews}{group, date, time} +\begin{methoddesc}{newnews}{group, date, time} Send a \samp{NEWNEWS} command. Here, \var{group} is a group name or -\code{"*"}, and \var{date} and \var{time} have the same meaning as for -\code{newgroups()}. Return a pair \code{(\var{response}, +\code{'*'}, and \var{date} and \var{time} have the same meaning as for +\method{newgroups()}. Return a pair \code{(\var{response}, \var{articles})} where \var{articles} is a list of article ids. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{list}{} +\begin{methoddesc}{list}{} Send a \samp{LIST} command. Return a pair \code{(\var{response}, \var{list})} where \var{list} is a list of tuples. Each tuple has the form \code{(\var{group}, \var{last}, \var{first}, \var{flag})}, where @@ -124,106 +123,107 @@ form \code{(\var{group}, \var{last}, \var{first}, \var{flag})}, where and first article numbers (as strings), and \var{flag} is \code{'y'} if posting is allowed, \code{'n'} if not, and \code{'m'} if the newsgroup is moderated. (Note the ordering: \var{last}, \var{first}.) -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{group}{name} +\begin{methoddesc}{group}{name} Send a \samp{GROUP} command, where \var{name} is the group name. -Return a tuple \code{(\var{response}, \var{count}, \var{first}, -\var{last}, \var{name})} where \var{count} is the (estimated) number -of articles in the group, \var{first} is the first article number in -the group, \var{last} is the last article number in the group, and -\var{name} is the group name. The numbers are returned as strings. -\end{funcdesc} - -\begin{funcdesc}{help}{} +Return a tuple \code{(}\var{response}\code{,} \var{count}\code{,} +\var{first}\code{,} \var{last}\code{,} \var{name}\code{)} where +\var{count} is the (estimated) number of articles in the group, +\var{first} is the first article number in the group, \var{last} is +the last article number in the group, and \var{name} is the group +name. The numbers are returned as strings. +\end{methoddesc} + +\begin{methoddesc}{help}{} Send a \samp{HELP} command. Return a pair \code{(\var{response}, \var{list})} where \var{list} is a list of help strings. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{stat}{id} +\begin{methoddesc}{stat}{id} Send a \samp{STAT} command, where \var{id} is the message id (enclosed -in \samp{<} and \samp{>}) or an article number (as a string). +in \character{<} and \character{>}) or an article number (as a string). Return a triple \code{(\var{response}, \var{number}, \var{id})} where \var{number} is the article number (as a string) and \var{id} is the -article id (enclosed in \samp{<} and \samp{>}). -\end{funcdesc} +article id (enclosed in \character{<} and \character{>}). +\end{methoddesc} -\begin{funcdesc}{next}{} -Send a \samp{NEXT} command. Return as for \code{stat()}. -\end{funcdesc} +\begin{methoddesc}{next}{} +Send a \samp{NEXT} command. Return as for \method{stat()}. +\end{methoddesc} -\begin{funcdesc}{last}{} -Send a \samp{LAST} command. Return as for \code{stat()}. -\end{funcdesc} +\begin{methoddesc}{last}{} +Send a \samp{LAST} command. Return as for \method{stat()}. +\end{methoddesc} -\begin{funcdesc}{head}{id} +\begin{methoddesc}{head}{id} Send a \samp{HEAD} command, where \var{id} has the same meaning as for -\code{stat()}. Return a pair \code{(\var{response}, \var{list})} +\method{stat()}. Return a pair \code{(\var{response}, \var{list})} where \var{list} is a list of the article's headers (an uninterpreted list of lines, without trailing newlines). -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{body}{id} +\begin{methoddesc}{body}{id} Send a \samp{BODY} command, where \var{id} has the same meaning as for -\code{stat()}. Return a pair \code{(\var{response}, \var{list})} +\method{stat()}. Return a pair \code{(\var{response}, \var{list})} where \var{list} is a list of the article's body text (an uninterpreted list of lines, without trailing newlines). -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{article}{id} +\begin{methoddesc}{article}{id} Send a \samp{ARTICLE} command, where \var{id} has the same meaning as -for \code{stat()}. Return a pair \code{(\var{response}, \var{list})} +for \method{stat()}. Return a pair \code{(\var{response}, \var{list})} where \var{list} is a list of the article's header and body text (an uninterpreted list of lines, without trailing newlines). -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{slave}{} +\begin{methoddesc}{slave}{} Send a \samp{SLAVE} command. Return the server's \var{response}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{xhdr}{header, string} +\begin{methoddesc}{xhdr}{header, string} Send an \samp{XHDR} command. This command is not defined in the RFC but is a common extension. The \var{header} argument is a header -keyword, e.g. \code{"subject"}. The \var{string} argument should have +keyword, e.g. \code{'subject'}. The \var{string} argument should have the form \code{"\var{first}-\var{last}"} where \var{first} and \var{last} are the first and last article numbers to search. Return a pair \code{(\var{response}, \var{list})}, where \var{list} is a list of pairs \code{(\var{id}, \var{text})}, where \var{id} is an article id (as a string) and \var{text} is the text of the requested header for that article. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{post}{file} +\begin{methoddesc}{post}{file} Post an article using the \samp{POST} command. The \var{file} argument is an open file object which is read until EOF using its -\code{readline()} method. It should be a well-formed news article, -including the required headers. The \code{post()} method +\method{readline()} method. It should be a well-formed news article, +including the required headers. The \method{post()} method automatically escapes lines beginning with \samp{.}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{ihave}{id, file} +\begin{methoddesc}{ihave}{id, file} Send an \samp{IHAVE} command. If the response is not an error, treat -\var{file} exactly as for the \code{post()} method. -\end{funcdesc} +\var{file} exactly as for the \method{post()} method. +\end{methoddesc} -\begin{funcdesc}{date}{} +\begin{methoddesc}{date}{} Return a triple \code{(\var{response}, \var{date}, \var{time})}, containing the current date and time in a form suitable for the -\code{newnews} and \code{newgroups} methods. +\method{newnews()} and \method{newgroups()} methods. This is an optional NNTP extension, and may not be supported by all servers. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{xgtitle}{name} -Process an XGTITLE command, returning a pair \code{(\var{response}, +\begin{methoddesc}{xgtitle}{name} +Process an \samp{XGTITLE} command, returning a pair \code{(\var{response}, \var{list})}, where \var{list} is a list of tuples containing \code{(\var{name}, \var{title})}. % XXX huh? Should that be name, description? This is an optional NNTP extension, and may not be supported by all servers. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{xover}{start, end} +\begin{methoddesc}{xover}{start, end} Return a pair \code{(\var{resp}, \var{list})}. \var{list} is a list of tuples, one for each article in the range delimited by the \var{start} and \var{end} article numbers. Each tuple is of the form @@ -232,15 +232,15 @@ and \var{end} article numbers. Each tuple is of the form \var{references}\code{,} \var{size}\code{,} \var{lines}\code{)}. This is an optional NNTP extension, and may not be supported by all servers. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{xpath}{id} +\begin{methoddesc}{xpath}{id} Return a pair \code{(\var{resp}, \var{path})}, where \var{path} is the directory path to the article with message ID \var{id}. This is an optional NNTP extension, and may not be supported by all servers. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{quit}{} +\begin{methoddesc}{quit}{} Send a \samp{QUIT} command and close the connection. Once this method has been called, no other methods of the NNTP object should be called. -\end{funcdesc} +\end{methoddesc} diff --git a/Doc/lib/librgbimg.tex b/Doc/lib/librgbimg.tex index 873a75f..73e4aae 100644 --- a/Doc/lib/librgbimg.tex +++ b/Doc/lib/librgbimg.tex @@ -5,7 +5,7 @@ The \module{rgbimg} module allows Python programs to access SGI imglib image files (also known as \file{.rgb} files). The module is far from complete, but is provided anyway since the functionality that there is -is enough in some cases. Currently, colormap files are not supported. +enough in some cases. Currently, colormap files are not supported. The module defines the following variables and functions: @@ -24,7 +24,7 @@ are currently supported. This function reads and decodes the image on the specified file, and returns it as a Python string. The string has 4 byte RGBA pixels. The bottom left pixel is the first in -the string. This format is suitable to pass to \code{gl.lrectwrite}, +the string. This format is suitable to pass to \function{gl.lrectwrite()}, for instance. \end{funcdesc} @@ -34,7 +34,7 @@ file \var{file}. \var{x} and \var{y} give the size of the image. \var{z} is 1 if the saved image should be 1 byte greyscale, 3 if the saved image should be 3 byte RGB data, or 4 if the saved images should be 4 byte RGBA data. The input data always contains 4 bytes per pixel. -These are the formats returned by \code{gl.lrectread}. +These are the formats returned by \function{gl.lrectread()}. \end{funcdesc} \begin{funcdesc}{ttob}{flag} diff --git a/Doc/lib/librotor.tex b/Doc/lib/librotor.tex index e467d4e..63dc56e 100644 --- a/Doc/lib/librotor.tex +++ b/Doc/lib/librotor.tex @@ -1,9 +1,10 @@ -\section{Built-in Module \sectcode{rotor}} +\section{Built-in Module \module{rotor}} \label{module-rotor} \bimodindex{rotor} This module implements a rotor-based encryption algorithm, contributed by -Lance Ellinghouse. The design is derived from the Enigma device, a machine +Lance Ellinghouse\index{Ellinghouse, Lance}. The design is derived +from the Enigma device\indexii{Enigma}{device}, a machine used during World War II to encipher messages. A rotor is simply a permutation. For example, if the character `A' is the origin of the rotor, then a given rotor might map `A' to `L', `B' to `Z', `C' to `G', and so on. @@ -19,12 +20,10 @@ recursively. In other words, after enciphering one character, we advance the rotors in the same fashion as a car's odometer. Decoding works in the same way, except we reverse the permutations and apply them in the opposite order. -\index{Ellinghouse, Lance} \indexii{Enigma}{cipher} The available functions in this module are: -\setindexsubitem{(in module rotor)} \begin{funcdesc}{newrotor}{key\optional{, numrotors}} Return a rotor object. \var{key} is a string containing the encryption key for the object; it can contain arbitrary binary data. The key will be used @@ -35,32 +34,31 @@ if it is omitted, a default value of 6 will be used. Rotor objects have the following methods: -\setindexsubitem{(rotor method)} -\begin{funcdesc}{setkey}{key} +\begin{methoddesc}[rotor]{setkey}{key} Sets the rotor's key to \var{key}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{encrypt}{plaintext} +\begin{methoddesc}[rotor]{encrypt}{plaintext} Reset the rotor object to its initial state and encrypt \var{plaintext}, returning a string containing the ciphertext. The ciphertext is always the same length as the original plaintext. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{encryptmore}{plaintext} +\begin{methoddesc}[rotor]{encryptmore}{plaintext} Encrypt \var{plaintext} without resetting the rotor object, and return a string containing the ciphertext. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{decrypt}{ciphertext} +\begin{methoddesc}[rotor]{decrypt}{ciphertext} Reset the rotor object to its initial state and decrypt \var{ciphertext}, returning a string containing the ciphertext. The plaintext string will always be the same length as the ciphertext. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{decryptmore}{ciphertext} +\begin{methoddesc}[rotor]{decryptmore}{ciphertext} Decrypt \var{ciphertext} without resetting the rotor object, and return a string containing the ciphertext. -\end{funcdesc} +\end{methoddesc} An example usage: \begin{verbatim} @@ -80,17 +78,18 @@ An example usage: 'l(\315' >>> del rt \end{verbatim} -% -The module's code is not an exact simulation of the original Enigma device; -it implements the rotor encryption scheme differently from the original. The -most important difference is that in the original Enigma, there were only 5 -or 6 different rotors in existence, and they were applied twice to each -character; the cipher key was the order in which they were placed in the -machine. The Python rotor module uses the supplied key to initialize a -random number generator; the rotor permutations and their initial positions -are then randomly generated. The original device only enciphered the -letters of the alphabet, while this module can handle any 8-bit binary data; -it also produces binary output. This module can also operate with an + +The module's code is not an exact simulation of the original Enigma +device; it implements the rotor encryption scheme differently from the +original. The most important difference is that in the original +Enigma, there were only 5 or 6 different rotors in existence, and they +were applied twice to each character; the cipher key was the order in +which they were placed in the machine. The Python \module{rotor} +module uses the supplied key to initialize a random number generator; +the rotor permutations and their initial positions are then randomly +generated. The original device only enciphered the letters of the +alphabet, while this module can handle any 8-bit binary data; it also +produces binary output. This module can also operate with an arbitrary number of rotors. The original Enigma cipher was broken in 1944. % XXX: Is this right? @@ -102,5 +101,4 @@ for discouraging casual snooping through your files, it will probably be just fine, and may be somewhat safer than using the \UNIX{} \program{crypt} command. \index{NSA} -\index{National Security Agency}\index{crypt(1)} -% XXX How were Unix commands represented in the docs? +\index{National Security Agency} diff --git a/Doc/lib/libsunaudio.tex b/Doc/lib/libsunaudio.tex index bafd7c5..c43d611 100644 --- a/Doc/lib/libsunaudio.tex +++ b/Doc/lib/libsunaudio.tex @@ -1,15 +1,14 @@ -\section{Built-in Module \sectcode{sunaudiodev}} +\section{Built-in Module \module{sunaudiodev}} \label{module-sunaudiodev} \bimodindex{sunaudiodev} This module allows you to access the sun audio interface. The sun audio hardware is capable of recording and playing back audio data -in U-LAW format with a sample rate of 8K per second. A full -description can be gotten with \samp{man audio}. +in u-LAW\index{u-LAW} format with a sample rate of 8K per second. A +full description can be found in the \manpage{audio}{7I} manual page. The module defines the following variables and functions: -\setindexsubitem{(in module sunaudiodev)} \begin{excdesc}{error} This exception is raised on all errors. The argument is a string describing what went wrong. @@ -22,87 +21,87 @@ is one of \code{'r'} for record-only access, \code{'w'} for play-only access, \code{'rw'} for both and \code{'control'} for access to the control device. Since only one process is allowed to have the recorder or player open at the same time it is a good idea to open the device -only for the activity needed. See the audio manpage for details. +only for the activity needed. See \manpage{audio}{7I} for details. \end{funcdesc} + \subsection{Audio Device Objects} +\label{audio-device-objects} -The audio device objects are returned by \code{open} define the +The audio device objects are returned by \function{open()} define the following methods (except \code{control} objects which only provide -getinfo, setinfo and drain): - -\setindexsubitem{(audio device method)} +\method{getinfo()}, \method{setinfo()} and \method{drain()}): -\begin{funcdesc}{close}{} +\begin{methoddesc}[audio device]{close}{} This method explicitly closes the device. It is useful in situations where deleting the object does not immediately close it since there are other references to it. A closed device should not be used again. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{drain}{} +\begin{methoddesc}[audio device]{drain}{} This method waits until all pending output is processed and then returns. Calling this method is often not necessary: destroying the object will automatically close the audio device and this will do an implicit drain. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{flush}{} +\begin{methoddesc}[audio device]{flush}{} This method discards all pending output. It can be used avoid the slow response to a user's stop request (due to buffering of up to one second of sound). -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{getinfo}{} +\begin{methoddesc}[audio device]{getinfo}{} This method retrieves status information like input and output volume, etc. and returns it in the form of an audio status object. This object has no methods but it contains a number of attributes describing the current device status. The names and meanings of the attributes are described in -\file{/usr/include/sun/audioio.h} and in the audio man page. Member names -are slightly different from their C counterparts: a status object is -only a single structure. Members of the \code{play} substructure have -\samp{o_} prepended to their name and members of the \code{record} -structure have \samp{i_}. So, the C member \code{play.sample_rate} is -accessed as \code{o_sample_rate}, \code{record.gain} as \code{i_gain} -and \code{monitor_gain} plainly as \code{monitor_gain}. -\end{funcdesc} - -\begin{funcdesc}{ibufcount}{} +\file{/usr/include/sun/audioio.h} and in the \manpage{audio}{7I} +manual page. Member names +are slightly different from their \C{} counterparts: a status object is +only a single structure. Members of the \cdata{play} substructure have +\samp{o_} prepended to their name and members of the \cdata{record} +structure have \samp{i_}. So, the \C{} member \cdata{play.sample_rate} is +accessed as \member{o_sample_rate}, \cdata{record.gain} as \member{i_gain} +and \cdata{monitor_gain} plainly as \member{monitor_gain}. +\end{methoddesc} + +\begin{methoddesc}[audio device]{ibufcount}{} This method returns the number of samples that are buffered on the -recording side, i.e. -the program will not block on a \function{read()} call of so many samples. -\end{funcdesc} +recording side, i.e.\ the program will not block on a +\function{read()} call of so many samples. +\end{methoddesc} -\begin{funcdesc}{obufcount}{} +\begin{methoddesc}[audio device]{obufcount}{} This method returns the number of samples buffered on the playback side. Unfortunately, this number cannot be used to determine a number of samples that can be written without blocking since the kernel output queue length seems to be variable. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{read}{size} +\begin{methoddesc}[audio device]{read}{size} This method reads \var{size} samples from the audio input and returns them as a Python string. The function blocks until enough data is available. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{setinfo}{status} +\begin{methoddesc}[audio device]{setinfo}{status} This method sets the audio device status parameters. The \var{status} parameter is an device status object as returned by \function{getinfo()} and possibly modified by the program. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{write}{samples} +\begin{methoddesc}[audio device]{write}{samples} Write is passed a Python string containing audio samples to be played. If there is enough buffer space free it will immediately return, otherwise it will block. -\end{funcdesc} +\end{methoddesc} -There is a companion module, \module{SUNAUDIODEV}, which defines useful +There is a companion module, +\module{SUNAUDIODEV}\refstmodindex{SUNAUDIODEV}, which defines useful symbolic constants like \constant{MIN_GAIN}, \constant{MAX_GAIN}, -\constant{SPEAKER}, etc. The names of -the constants are the same names as used in the \C{} include file -\code{<sun/audioio.h>}, with the leading string \samp{AUDIO_} -stripped. -\refstmodindex{SUNAUDIODEV} +\constant{SPEAKER}, etc. The names of the constants are the same names +as used in the \C{} include file \code{<sun/audioio.h>}, with the +leading string \samp{AUDIO_} stripped. Useability of the control device is limited at the moment, since there is no way to use the ``wait for something to happen'' feature the diff --git a/Doc/lib/libxmllib.tex b/Doc/lib/libxmllib.tex index efc7f00..4306aca 100644 --- a/Doc/lib/libxmllib.tex +++ b/Doc/lib/libxmllib.tex @@ -1,4 +1,4 @@ -\section{Standard Module \sectcode{xmllib}} +\section{Standard Module \module{xmllib}} % Author: Sjoerd Mullender \label{module-xmllib} \stmodindex{xmllib} @@ -13,59 +13,57 @@ The \class{XMLParser} class must be instantiated without arguments. This class provides the following interface methods: -\setindexsubitem{(XMLParser method)} - -\begin{funcdesc}{reset}{} +\begin{methoddesc}{reset}{} Reset the instance. Loses all unprocessed data. This is called implicitly at the instantiation time. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{setnomoretags}{} +\begin{methoddesc}{setnomoretags}{} Stop processing tags. Treat all following input as literal input (CDATA). -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{setliteral}{} +\begin{methoddesc}{setliteral}{} Enter literal mode (CDATA mode). -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{feed}{data} +\begin{methoddesc}{feed}{data} Feed some text to the parser. It is processed insofar as it consists of complete elements; incomplete data is buffered until more data is fed or \method{close()} is called. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{close}{} +\begin{methoddesc}{close}{} Force processing of all buffered data as if it were followed by an end-of-file mark. This method may be redefined by a derived class to define additional processing at the end of the input, but the redefined version should always call \method{close()}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{translate_references}{data} +\begin{methoddesc}{translate_references}{data} Translate all entity and character references in \var{data} and returns the translated string. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{handle_xml}{encoding, standalone} -This method is called when the \code{<?xml ...?>} tag is processed. +\begin{methoddesc}{handle_xml}{encoding, standalone} +This method is called when the \samp{<?xml ...?>} tag is processed. The arguments are the values of the encoding and standalone attributes in the tag. Both encoding and standalone are optional. The values passed to \method{handle_xml()} default to \code{None} and the string \code{'no'} respectively. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{handle_doctype}{tag, data} -This method is called when the \code{<!DOCTYPE...>} tag is processed. +\begin{methoddesc}{handle_doctype}{tag, data} +This method is called when the \samp{<!DOCTYPE...>} tag is processed. The arguments are the name of the root element and the uninterpreted contents of the tag, starting after the white space after the name of the root element. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{handle_starttag}{tag, method, attributes} +\begin{methoddesc}{handle_starttag}{tag, method, attributes} This method is called to handle start tags for which a -\code{start_\var{tag}()} method has been defined. The \var{tag} -argument is the name of the tag, and the \method{method} argument is the +\method{start_\var{tag}()} method has been defined. The \var{tag} +argument is the name of the tag, and the \var{method} argument is the bound method which should be used to support semantic interpretation of the start tag. The \var{attributes} argument is a dictionary of attributes, the key being the \var{name} and the value being the @@ -76,29 +74,29 @@ been interpreted. For instance, for the tag \code{handle_starttag('A', self.start_A, \{'HREF': 'http://www.cwi.nl/'\})}. The base implementation simply calls \var{method} with \var{attributes} as the only argument. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{handle_endtag}{tag, method} +\begin{methoddesc}{handle_endtag}{tag, method} This method is called to handle endtags for which an -\code{end_\var{tag}()} method has been defined. The \var{tag} +\method{end_\var{tag}()} method has been defined. The \var{tag} argument is the name of the tag, and the \var{method} argument is the bound method which should be used to support semantic interpretation of the end tag. If no -\code{end_\var{tag}()} method is defined for the closing element, this +\method{end_\var{tag}()} method is defined for the closing element, this handler is not called. The base implementation simply calls \var{method}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{handle_data}{data} +\begin{methoddesc}{handle_data}{data} This method is called to process arbitrary data. It is intended to be overridden by a derived class; the base class implementation does nothing. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{handle_charref}{ref} +\begin{methoddesc}{handle_charref}{ref} This method is called to process a character reference of the form \samp{\&\#\var{ref};}. \var{ref} can either be a decimal number, -or a hexadecimal number when preceded by \code{x}. +or a hexadecimal number when preceded by an \character{x}. In the base implementation, \var{ref} must be a number in the range 0-255. It translates the character to \ASCII{} and calls the method \method{handle_data()} with the character as argument. If @@ -106,9 +104,9 @@ method \method{handle_data()} with the character as argument. If \code{unknown_charref(\var{ref})} is called to handle the error. A subclass must override this method to provide support for character references outside of the \ASCII{} range. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{handle_entityref}{ref} +\begin{methoddesc}{handle_entityref}{ref} This method is called to process a general entity reference of the form \samp{\&\var{ref};} where \var{ref} is an general entity reference. It looks for \var{ref} in the instance (or class) @@ -119,48 +117,48 @@ with the translation; otherwise, it calls the method \code{unknown_entityref(\var{ref})}. The default \member{entitydefs} defines translations for \code{\&}, \code{\&apos}, \code{\>}, \code{\<}, and \code{\"}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{handle_comment}{comment} +\begin{methoddesc}{handle_comment}{comment} This method is called when a comment is encountered. The \var{comment} argument is a string containing the text between the \samp{<!--} and \samp{-->} delimiters, but not the delimiters themselves. For example, the comment \samp{<!--text-->} will cause this method to be called with the argument \code{'text'}. The default method does nothing. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{handle_cdata}{data} +\begin{methoddesc}{handle_cdata}{data} This method is called when a CDATA element is encountered. The \var{data} argument is a string containing the text between the \samp{<![CDATA[} and \samp{]]>} delimiters, but not the delimiters themselves. For example, the entity \samp{<![CDATA[text]]>} will cause this method to be called with the argument \code{'text'}. The default method does nothing, and is intended to be overridden. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{handle_proc}{name, data} +\begin{methoddesc}{handle_proc}{name, data} This method is called when a processing instruction (PI) is encountered. The \var{name} is the PI target, and the \var{data} argument is a string containing the text between the PI target and the closing delimiter, but not the delimiter itself. For example, the instruction \samp{<?XML text?>} will cause this method to be called with the arguments \code{'XML'} and \code{'text'}. The default method -does nothing. Note that if a document starts with \code{<?xml +does nothing. Note that if a document starts with \samp{<?xml ...?>}, \method{handle_xml()} is called to handle it. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{handle_special}{data} +\begin{methoddesc}{handle_special}{data} This method is called when a declaration is encountered. The \var{data} argument is a string containing the text between the \samp{<!} and \samp{>} delimiters, but not the delimiters themselves. For example, the entity \samp{<!ENTITY text>} will cause this method to be called with the argument \code{'ENTITY text'}. The -default method does nothing. Note that \code{<!DOCTYPE ...>} is +default method does nothing. Note that \samp{<!DOCTYPE ...>} is handled separately if it is located at the start of the document. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{syntax_error}{message} +\begin{methoddesc}{syntax_error}{message} This method is called when a syntax error is encountered. The \var{message} is a description of what was wrong. The default method raises a \exception{RuntimeError} exception. If this method is @@ -168,31 +166,31 @@ overridden, it is permissable for it to return. This method is only called when the error can be recovered from. Unrecoverable errors raise a \exception{RuntimeError} without first calling \method{syntax_error()}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{unknown_starttag}{tag, attributes} +\begin{methoddesc}{unknown_starttag}{tag, attributes} This method is called to process an unknown start tag. It is intended to be overridden by a derived class; the base class implementation does nothing. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{unknown_endtag}{tag} +\begin{methoddesc}{unknown_endtag}{tag} This method is called to process an unknown end tag. It is intended to be overridden by a derived class; the base class implementation does nothing. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{unknown_charref}{ref} +\begin{methoddesc}{unknown_charref}{ref} This method is called to process unresolvable numeric character references. It is intended to be overridden by a derived class; the base class implementation does nothing. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{unknown_entityref}{ref} +\begin{methoddesc}{unknown_entityref}{ref} This method is called to process an unknown entity reference. It is intended to be overridden by a derived class; the base class implementation does nothing. -\end{funcdesc} +\end{methoddesc} Apart from overriding or extending the methods listed above, derived classes may also define methods and variables of the following form to @@ -200,19 +198,19 @@ define processing of specific tags. Tag names in the input stream are case dependent; the \var{tag} occurring in method names must be in the correct case: -\begin{funcdescni}{start_\var{tag}}{attributes} +\begin{methoddescni}{start_\var{tag}}{attributes} This method is called to process an opening tag \var{tag}. The \var{attributes} argument has the same meaning as described for \method{handle_starttag()} above. In fact, the base implementation of \method{handle_starttag()} calls this method. -\end{funcdescni} +\end{methoddescni} -\begin{funcdescni}{end_\var{tag}}{} +\begin{methoddescni}{end_\var{tag}}{} This method is called to process a closing tag \var{tag}. -\end{funcdescni} +\end{methoddescni} -\begin{datadescni}{\var{tag}_attributes} -If a class or instance variable \code{\var{tag}_attributes} exists, it +\begin{memberdescni}{\var{tag}_attributes} +If a class or instance variable \member{\var{tag}_attributes} exists, it should be a list or a dictionary. If a list, the elements of the list are the valid attributes for the element \var{tag}; if a dictionary, the keys are the valid attributes for the element \var{tag}, and the @@ -222,4 +220,4 @@ In addition to the attributes that were present in the tag, the attribute dictionary that is passed to \method{handle_starttag()} and \method{unknown_starttag()} contains values for all attributes that have a default value. -\end{datadescni} +\end{memberdescni} diff --git a/Doc/libaifc.tex b/Doc/libaifc.tex index 8bb88a1..f86b1d8 100644 --- a/Doc/libaifc.tex +++ b/Doc/libaifc.tex @@ -1,4 +1,4 @@ -\section{Standard Module \sectcode{aifc}} +\section{Standard Module \module{aifc}} \label{module-aifc} \stmodindex{aifc} @@ -6,6 +6,9 @@ This module provides support for reading and writing AIFF and AIFF-C files. AIFF is Audio Interchange File Format, a format for storing digital audio samples in a file. AIFF-C is a newer version of the format that includes the ability to compress the audio data. +\index{Audio Interchange File Format} +\index{AIFF} +\index{AIFF-C} Audio files have a number of parameters that describe the audio data. The sampling rate or frame rate is the number of times per second the @@ -21,9 +24,8 @@ bits), uses two channels (stereo) and has a frame rate of 44,100 frames/second. This gives a frame size of 4 bytes (2*2), and a second's worth occupies 2*2*44100 bytes, i.e.\ 176,400 bytes. -Module \code{aifc} defines the following function: +Module \module{aifc} defines the following function: -\setindexsubitem{(in module aifc)} \begin{funcdesc}{open}{file, mode} Open an AIFF or AIFF-C file and return an object instance with methods that are described below. The argument file is either a @@ -32,159 +34,161 @@ string naming a file or a file object. The mode is either the string when the file must be opened for writing. When used for writing, the file object should be seekable, unless you know ahead of time how many samples you are going to write in total and use -\code{writeframesraw()} and \code{setnframes()}. +\method{writeframesraw()} and \method{setnframes()}. \end{funcdesc} -Objects returned by \code{aifc.open()} when a file is opened for +Objects returned by \function{open()} when a file is opened for reading have the following methods: -\setindexsubitem{(aifc object method)} -\begin{funcdesc}{getnchannels}{} +\begin{methoddesc}[aifc]{getnchannels}{} Return the number of audio channels (1 for mono, 2 for stereo). -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{getsampwidth}{} +\begin{methoddesc}[aifc]{getsampwidth}{} Return the size in bytes of individual samples. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{getframerate}{} +\begin{methoddesc}[aifc]{getframerate}{} Return the sampling rate (number of audio frames per second). -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{getnframes}{} +\begin{methoddesc}[aifc]{getnframes}{} Return the number of audio frames in the file. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{getcomptype}{} +\begin{methoddesc}[aifc]{getcomptype}{} Return a four-character string describing the type of compression used in the audio file. For AIFF files, the returned value is \code{'NONE'}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{getcompname}{} +\begin{methoddesc}[aifc]{getcompname}{} Return a human-readable description of the type of compression used in the audio file. For AIFF files, the returned value is \code{'not compressed'}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{getparams}{} +\begin{methoddesc}[aifc]{getparams}{} Return a tuple consisting of all of the above values in the above order. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{getmarkers}{} +\begin{methoddesc}[aifc]{getmarkers}{} Return a list of markers in the audio file. A marker consists of a tuple of three elements. The first is the mark ID (an integer), the second is the mark position in frames from the beginning of the data (an integer), the third is the name of the mark (a string). -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{getmark}{id} -Return the tuple as described in \code{getmarkers} for the mark with -the given id. -\end{funcdesc} +\begin{methoddesc}[aifc]{getmark}{id} +Return the tuple as described in \method{getmarkers()} for the mark +with the given \var{id}. +\end{methoddesc} -\begin{funcdesc}{readframes}{nframes} +\begin{methoddesc}[aifc]{readframes}{nframes} Read and return the next \var{nframes} frames from the audio file. The returned data is a string containing for each frame the uncompressed samples of all channels. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{rewind}{} -Rewind the read pointer. The next \code{readframes} will start from +\begin{methoddesc}[aifc]{rewind}{} +Rewind the read pointer. The next \method{readframes()} will start from the beginning. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{setpos}{pos} +\begin{methoddesc}[aifc]{setpos}{pos} Seek to the specified frame number. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{tell}{} +\begin{methoddesc}[aifc]{tell}{} Return the current frame number. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{close}{} +\begin{methoddesc}[aifc]{close}{} Close the AIFF file. After calling this method, the object can no longer be used. -\end{funcdesc} +\end{methoddesc} -Objects returned by \code{aifc.open()} when a file is opened for -writing have all the above methods, except for \code{readframes} and -\code{setpos}. In addition the following methods exist. The -\code{get} methods can only be called after the corresponding -\code{set} methods have been called. Before the first -\code{writeframes()} or \code{writeframesraw()}, all parameters except -for the number of frames must be filled in. +Objects returned by \function{open()} when a file is opened for +writing have all the above methods, except for \method{readframes()} and +\method{setpos()}. In addition the following methods exist. The +\method{get*()} methods can only be called after the corresponding +\method{set*()} methods have been called. Before the first +\method{writeframes()} or \method{writeframesraw()}, all parameters +except for the number of frames must be filled in. -\begin{funcdesc}{aiff}{} +\begin{methoddesc}[aifc]{aiff}{} Create an AIFF file. The default is that an AIFF-C file is created, unless the name of the file ends in \code{'.aiff'} in which case the default is an AIFF file. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{aifc}{} +\begin{methoddesc}[aifc]{aifc}{} Create an AIFF-C file. The default is that an AIFF-C file is created, unless the name of the file ends in \code{'.aiff'} in which case the default is an AIFF file. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{setnchannels}{nchannels} +\begin{methoddesc}[aifc]{setnchannels}{nchannels} Specify the number of channels in the audio file. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{setsampwidth}{width} +\begin{methoddesc}[aifc]{setsampwidth}{width} Specify the size in bytes of audio samples. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{setframerate}{rate} +\begin{methoddesc}[aifc]{setframerate}{rate} Specify the sampling frequency in frames per second. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{setnframes}{nframes} +\begin{methoddesc}[aifc]{setnframes}{nframes} Specify the number of frames that are to be written to the audio file. If this parameter is not set, or not set correctly, the file needs to support seeking. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{setcomptype}{type, name} +\begin{methoddesc}[aifc]{setcomptype}{type, name} Specify the compression type. If not specified, the audio data will not be compressed. In AIFF files, compression is not possible. The name parameter should be a human-readable description of the compression type, the type parameter should be a four-character string. Currently the following compression types are supported: NONE, ULAW, ALAW, G722. -\end{funcdesc} +\index{u-LAW} +\index{A-LAW} +\index{G.722} +\end{methoddesc} -\begin{funcdesc}{setparams}{nchannels, sampwidth, framerate, comptype, compname} +\begin{methoddesc}[aifc]{setparams}{nchannels, sampwidth, framerate, comptype, compname} Set all the above parameters at once. The argument is a tuple consisting of the various parameters. This means that it is possible -to use the result of a \code{getparams()} call as argument to -\code{setparams()}. -\end{funcdesc} +to use the result of a \method{getparams()} call as argument to +\method{setparams()}. +\end{methoddesc} -\begin{funcdesc}{setmark}{id, pos, name} +\begin{methoddesc}[aifc]{setmark}{id, pos, name} Add a mark with the given id (larger than 0), and the given name at the given position. This method can be called at any time before -\code{close()}. -\end{funcdesc} +\method{close()}. +\end{methoddesc} -\begin{funcdesc}{tell}{} +\begin{methoddesc}[aifc]{tell}{} Return the current write position in the output file. Useful in -combination with \code{setmark()}. -\end{funcdesc} +combination with \method{setmark()}. +\end{methoddesc} -\begin{funcdesc}{writeframes}{data} +\begin{methoddesc}[aifc]{writeframes}{data} Write data to the output file. This method can only be called after the audio file parameters have been set. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{writeframesraw}{data} -Like \code{writeframes()}, except that the header of the audio file is -not updated. -\end{funcdesc} +\begin{methoddesc}[aifc]{writeframesraw}{data} +Like \method{writeframes()}, except that the header of the audio file +is not updated. +\end{methoddesc} -\begin{funcdesc}{close}{} +\begin{methoddesc}[aifc]{close}{} Close the AIFF file. The header of the file is updated to reflect the actual size of the audio data. After calling this method, the object can no longer be used. -\end{funcdesc} +\end{methoddesc} diff --git a/Doc/libal.tex b/Doc/libal.tex index 1126f83..fb31ffa 100644 --- a/Doc/libal.tex +++ b/Doc/libal.tex @@ -1,4 +1,4 @@ -\section{Built-in Module \sectcode{al}} +\section{Built-in Module \module{al}} \label{module-al} \bimodindex{al} @@ -10,10 +10,11 @@ releases before 4.0.5. Again, see the manual to check whether a specific function is available on your platform. All functions and methods defined in this module are equivalent to -the C functions with \samp{AL} prefixed to their name. +the \C{} functions with \samp{AL} prefixed to their name. -Symbolic constants from the C header file \file{<audio.h>} are defined -in the standard module \code{AL}, see below. +Symbolic constants from the \C{} header file \code{<audio.h>} are +defined in the standard module \module{AL}\refstmodindex{AL}, see +below. \strong{Warning:} the current version of the audio library may dump core when bad argument values are passed rather than returning an error @@ -25,145 +26,146 @@ documented upper limit.) The module defines the following functions: -\setindexsubitem{(in module al)} \begin{funcdesc}{openport}{name, direction\optional{, config}} -The name and direction arguments are strings. The optional config -argument is a configuration object as returned by -\code{al.newconfig()}. The return value is an \dfn{port object}; -methods of port objects are described below. +The name and direction arguments are strings. The optional +\var{config} argument is a configuration object as returned by +\function{newconfig()}. The return value is an \dfn{audio port +object}; methods of audio port objects are described below. \end{funcdesc} \begin{funcdesc}{newconfig}{} -The return value is a new \dfn{configuration object}; methods of -configuration objects are described below. +The return value is a new \dfn{audio configuration object}; methods of +audio configuration objects are described below. \end{funcdesc} \begin{funcdesc}{queryparams}{device} The device argument is an integer. The return value is a list of -integers containing the data returned by ALqueryparams(). +integers containing the data returned by \cfunction{ALqueryparams()}. \end{funcdesc} \begin{funcdesc}{getparams}{device, list} -The device argument is an integer. The list argument is a list such -as returned by \code{queryparams}; it is modified in place (!). +The \var{device} argument is an integer. The list argument is a list +such as returned by \function{queryparams()}; it is modified in place +(!). \end{funcdesc} \begin{funcdesc}{setparams}{device, list} -The device argument is an integer. The list argument is a list such -as returned by \code{al.queryparams}. +The \var{device} argument is an integer. The \var{list} argument is a +list such as returned by \function{queryparams()}. \end{funcdesc} + \subsection{Configuration Objects} +\label{al-config-objects} -Configuration objects (returned by \code{al.newconfig()} have the +Configuration objects (returned by \function{newconfig()} have the following methods: -\setindexsubitem{(audio configuration object method)} - -\begin{funcdesc}{getqueuesize}{} +\begin{methoddesc}[audio configuration]{getqueuesize}{} Return the queue size. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{setqueuesize}{size} +\begin{methoddesc}[audio configuration]{setqueuesize}{size} Set the queue size. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{getwidth}{} +\begin{methoddesc}[audio configuration]{getwidth}{} Get the sample width. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{setwidth}{width} +\begin{methoddesc}[audio configuration]{setwidth}{width} Set the sample width. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{getchannels}{} +\begin{methoddesc}[audio configuration]{getchannels}{} Get the channel count. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{setchannels}{nchannels} +\begin{methoddesc}[audio configuration]{setchannels}{nchannels} Set the channel count. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{getsampfmt}{} +\begin{methoddesc}[audio configuration]{getsampfmt}{} Get the sample format. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{setsampfmt}{sampfmt} +\begin{methoddesc}[audio configuration]{setsampfmt}{sampfmt} Set the sample format. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{getfloatmax}{} +\begin{methoddesc}[audio configuration]{getfloatmax}{} Get the maximum value for floating sample formats. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{setfloatmax}{floatmax} +\begin{methoddesc}[audio configuration]{setfloatmax}{floatmax} Set the maximum value for floating sample formats. -\end{funcdesc} +\end{methoddesc} + \subsection{Port Objects} +\label{al-port-objects} -Port objects (returned by \code{al.openport()} have the following +Port objects, as returned by \function{openport()}, have the following methods: -\setindexsubitem{(audio port object method)} - -\begin{funcdesc}{closeport}{} +\begin{methoddesc}[audio port]{closeport}{} Close the port. -\end{funcdesc} +\end{methoddesc}[audio port] -\begin{funcdesc}{getfd}{} +\begin{methoddesc}[audio port]{getfd}{} Return the file descriptor as an int. -\end{funcdesc} +\end{methoddesc}[audio port] -\begin{funcdesc}{getfilled}{} +\begin{methoddesc}[audio port]{getfilled}{} Return the number of filled samples. -\end{funcdesc} +\end{methoddesc}[audio port] -\begin{funcdesc}{getfillable}{} +\begin{methoddesc}[audio port]{getfillable}{} Return the number of fillable samples. -\end{funcdesc} +\end{methoddesc}[audio port] -\begin{funcdesc}{readsamps}{nsamples} +\begin{methoddesc}[audio port]{readsamps}{nsamples} Read a number of samples from the queue, blocking if necessary. Return the data as a string containing the raw data, (e.g., 2 bytes per sample in big-endian byte order (high byte, low byte) if you have set the sample width to 2 bytes). -\end{funcdesc} +\end{methoddesc}[audio port] -\begin{funcdesc}{writesamps}{samples} +\begin{methoddesc}[audio port]{writesamps}{samples} Write samples into the queue, blocking if necessary. The samples are -encoded as described for the \code{readsamps} return value. -\end{funcdesc} +encoded as described for the \method{readsamps()} return value. +\end{methoddesc}[audio port] -\begin{funcdesc}{getfillpoint}{} +\begin{methoddesc}[audio port]{getfillpoint}{} Return the `fill point'. -\end{funcdesc} +\end{methoddesc}[audio port] -\begin{funcdesc}{setfillpoint}{fillpoint} +\begin{methoddesc}[audio port]{setfillpoint}{fillpoint} Set the `fill point'. -\end{funcdesc} +\end{methoddesc}[audio port] -\begin{funcdesc}{getconfig}{} +\begin{methoddesc}[audio port]{getconfig}{} Return a configuration object containing the current configuration of the port. -\end{funcdesc} +\end{methoddesc}[audio port] -\begin{funcdesc}{setconfig}{config} +\begin{methoddesc}[audio port]{setconfig}{config} Set the configuration from the argument, a configuration object. -\end{funcdesc} +\end{methoddesc}[audio port] -\begin{funcdesc}{getstatus}{list} +\begin{methoddesc}[audio port]{getstatus}{list} Get status information on last error. -\end{funcdesc} +\end{methoddesc}[audio port] + -\section{Standard Module \sectcode{AL}} +\section{Standard Module \module{AL}} \nodename{AL (uppercase)} \stmodindex{AL} This module defines symbolic constants needed to use the built-in -module \code{al} (see above); they are equivalent to those defined in -the C header file \file{<audio.h>} except that the name prefix +module \module{al} (see above); they are equivalent to those defined +in the \C{} header file \code{<audio.h>} except that the name prefix \samp{AL_} is omitted. Read the module source for a complete list of the defined names. Suggested use: diff --git a/Doc/libaudioop.tex b/Doc/libaudioop.tex index 887cac9..774a92e 100644 --- a/Doc/libaudioop.tex +++ b/Doc/libaudioop.tex @@ -1,19 +1,25 @@ -\section{Built-in Module \sectcode{audioop}} +\section{Built-in Module \module{audioop}} \label{module-audioop} \bimodindex{audioop} -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. +The \module{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 \module{al} and \module{sunaudiodev} +modules. All scalar items are integers, unless specified otherwise. + +% This para is mostly here to provide an excuse for the index entries... +This module provides support for u-LAW and Intel/DVI ADPCM encodings. +\index{Intel/DVI ADPCM} +\index{ADPCM, Intel/DVI} +\index{u-LAW} 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. +otherwise the sample size (in bytes) is always a parameter of the +operation. The module defines the following variables and functions: -\setindexsubitem{(in module audioop)} \begin{excdesc}{error} This exception is raised on all errors, such as unknown number of bytes per sample, etc. @@ -28,14 +34,14 @@ length. \begin{funcdesc}{adpcm2lin}{adpcmfragment, width, state} Decode an Intel/DVI ADPCM coded fragment to a linear fragment. See -the description of \code{lin2adpcm} for details on ADPCM coding. +the description of \function{lin2adpcm()} for details on ADPCM coding. Return a tuple \code{(\var{sample}, \var{newstate})} where the sample has the width specified in \var{width}. \end{funcdesc} \begin{funcdesc}{adpcm32lin}{adpcmfragment, width, state} -Decode an alternative 3-bit ADPCM code. See \code{lin2adpcm3} for -details. +Decode an alternative 3-bit ADPCM code. See \function{lin2adpcm3()} +for details. \end{funcdesc} \begin{funcdesc}{avg}{fragment, width} @@ -60,26 +66,25 @@ argument. \begin{funcdesc}{findfactor}{fragment, reference} Return a factor \var{F} such that -\code{rms(add(fragment, mul(reference, -F)))} is minimal, i.e., -return the factor with which you should multiply \var{reference} to -make it match as well as possible to \var{fragment}. The fragments -should both contain 2-byte samples. +\code{rms(add(\var{fragment}, mul(\var{reference}, -\var{F})))} is +minimal, i.e., return the factor with which you should multiply +\var{reference} to make it match as well as possible to +\var{fragment}. The fragments should both contain 2-byte samples. -The time taken by this routine is proportional to \code{len(fragment)}. +The time taken by this routine is proportional to +\code{len(\var{fragment})}. \end{funcdesc} \begin{funcdesc}{findfit}{fragment, reference} -This routine (which only accepts 2-byte sample fragments) - Try to match \var{reference} as well as possible to a portion of \var{fragment} (which should be the longer fragment). This is (conceptually) done by taking slices out of \var{fragment}, using -\code{findfactor} to compute the best match, and minimizing the +\function{findfactor()} to compute the best match, and minimizing the result. The fragments should both contain 2-byte samples. Return a tuple \code{(\var{offset}, \var{factor})} where \var{offset} is the (integer) offset into \var{fragment} where the optimal match started and \var{factor} is the (floating-point) factor as per -\code{findfactor}. +\function{findfactor()}. \end{funcdesc} \begin{funcdesc}{findmax}{fragment, length} @@ -88,7 +93,7 @@ bytes!)\ with maximum energy, i.e., return \var{i} for which \code{rms(fragment[i*2:(i+length)*2])} is maximal. The fragments should both contain 2-byte samples. -The routine takes time proportional to \code{len(fragment)}. +The routine takes time proportional to \code{len(\var{fragment})}. \end{funcdesc} \begin{funcdesc}{getsample}{fragment, width, index} @@ -106,11 +111,12 @@ between one sample and the next, divided by a (varying) step. The Intel/DVI ADPCM algorithm has been selected for use by the IMA, so it may well become a standard. -\code{State} is a tuple containing the state of the coder. The coder +\var{state} is a tuple containing the state of the coder. The coder returns a tuple \code{(\var{adpcmfrag}, \var{newstate})}, and the -\var{newstate} should be passed to the next call of lin2adpcm. In the -initial call \code{None} can be passed as the state. \var{adpcmfrag} -is the ADPCM coded fragment packed 2 4-bit values per byte. +\var{newstate} should be passed to the next call of +\function{lin2adpcm()}. In the initial call, \code{None} can be +passed as the state. \var{adpcmfrag} is the ADPCM coded fragment +packed 2 4-bit values per byte. \end{funcdesc} \begin{funcdesc}{lin2adpcm3}{fragment, width, state} @@ -121,8 +127,8 @@ discouraged. \end{funcdesc} \begin{funcdesc}{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 +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. \end{funcdesc} @@ -147,15 +153,18 @@ multiplied by the floating-point value \var{factor}. Overflow is silently ignored. \end{funcdesc} -\begin{funcdesc}{ratecv}{fragment, width, nchannels, inrate, outrate, state\optional{, weightA, weightB}} +\begin{funcdesc}{ratecv}{fragment, width, nchannels, inrate, outrate, + state\optional{, weightA\optional{, weightB}}} Convert the frame rate of the input fragment. -\code{State} is a tuple containing the state of the converter. The +\var{state} is a tuple containing the state of the converter. The converter returns a tupl \code{(\var{newfragment}, \var{newstate})}, -and \var{newstate} should be passed to the next call of ratecv. +and \var{newstate} should be passed to the next call of +\function{ratecv()}. -The \code{weightA} and \code{weightB} arguments are parameters for a -simple digital filter and default to 1 and 0 respectively. +The \var{weightA} and \var{weightB} arguments are parameters for a +simple digital filter and default to \code{1} and \code{0} +respectively. \end{funcdesc} \begin{funcdesc}{reverse}{fragment, width} @@ -164,9 +173,12 @@ Reverse the samples in a fragment and returns the modified fragment. \begin{funcdesc}{rms}{fragment, width} Return the root-mean-square of the fragment, i.e. +%begin{latexonly} \iftexi +%end{latexonly} the square root of the quotient of the sum of all squared sample value, divided by the sumber of samples. +%begin{latexonly} \else % in eqn: sqrt { sum S sub i sup 2 over n } \begin{displaymath} @@ -174,6 +186,7 @@ divided by the sumber of samples. \sqrt{\frac{\sum{{S_{i}}^{2}}}{n}} \end{displaymath} \fi +%end{latexonly} This is a measure of the power in an audio signal. \end{funcdesc} @@ -191,16 +204,17 @@ samples by \var{rfactor}. \end{funcdesc} \begin{funcdesc}{ulaw2lin}{fragment, width} -Convert sound fragments in ULAW encoding to linearly encoded sound -fragments. ULAW encoding always uses 8 bits samples, so \var{width} +Convert sound fragments in u-LAW encoding to linearly encoded sound +fragments. u-LAW encoding always uses 8 bits samples, so \var{width} refers only to the sample width of the output fragment here. \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 -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: +Note that operations such as \function{mul()} or \function{max()} make +no 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: + \begin{verbatim} def mul_stereo(sample, width, lfactor, rfactor): lsample = audioop.tomono(sample, width, 1, 0) @@ -211,26 +225,27 @@ def mul_stereo(sample, width, lfactor, rfactor): rsample = audioop.tostereo(rsample, width, 0, 1) return audioop.add(lsample, rsample, width) \end{verbatim} -% + 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) 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 -\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. +\function{lin2adpcm()}) along to the decoder, not the final state (as +returned by the coder). If you want to use \function{struct.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. The ADPCM coders have never been tried against other ADPCM coders, only against themselves. It could well be that I misinterpreted the standards in which case they will not be interoperable with the respective standards. -The \code{find...} routines might look a bit funny at first sight. +The \function{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: + \begin{verbatim} def echocancel(outputdata, inputdata): pos = audioop.findmax(outputdata, 800) # one tenth second diff --git a/Doc/libbasehttp.tex b/Doc/libbasehttp.tex index 2a4a7d0..7ee55df 100644 --- a/Doc/libbasehttp.tex +++ b/Doc/libbasehttp.tex @@ -1,4 +1,4 @@ -\section{Standard Module \sectcode{BaseHTTPServer}} +\section{Standard Module \module{BaseHTTPServer}} \label{module-BaseHTTPServer} \stmodindex{BaseHTTPServer} @@ -23,18 +23,21 @@ run the server looks like this: \begin{verbatim} def run(server_class=BaseHTTPServer.HTTPServer, handler_class=BaseHTTPServer.BaseHTTPRequestHandler): - server_address = ('', 8000) - httpd = server_class(server_address, handler_class) - httpd.serve_forever() + server_address = ('', 8000) + httpd = server_class(server_address, handler_class) + httpd.serve_forever() \end{verbatim} -The \class{HTTPServer} class builds on the \class{TCPServer} class by +\begin{classdesc}{HTTPServer}{server_address, RequestHandlerClass} +This class builds on the \class{TCPServer} class by storing the server address as instance variables named \member{server_name} and \member{server_port}. The server is accessible by the handler, typically through the handler's \member{server} instance variable. +\end{classdesc} -The module's second class, \class{BaseHTTPRequestHandler}, is used +\begin{classdesc}{BaseHTTPRequestHandler}{request, client_address, server} +This class is used to handle the HTTP requests that arrive at the server. By itself, it cannot respond to any actual HTTP requests; it must be subclassed to handle each request method (e.g. GET or POST). @@ -43,69 +46,69 @@ variables, and methods for use by subclasses. The handler will parse the request and the headers, then call a method specific to the request type. The method name is constructed -from the request. For example, for the request \samp{SPAM}, the +from the request. For example, for the request method \samp{SPAM}, the \method{do_SPAM()} method will be called with no arguments. All of -the relevant information is stored into instance variables of the -handler. +the relevant information is stored in instance variables of the +handler. Subclasses should not need to override or extend the +\method{__init__()} method. +\end{classdesc} -\setindexsubitem{(BaseHTTPRequestHandler attribute)} \class{BaseHTTPRequestHandler} has the following instance variables: -\begin{datadesc}{client_address} +\begin{memberdesc}{client_address} Contains a tuple of the form \code{(\var{host}, \var{port})} referring to the client's address. -\end{datadesc} +\end{memberdesc} -\begin{datadesc}{command} +\begin{memberdesc}{command} Contains the command (request type). For example, \code{'GET'}. -\end{datadesc} +\end{memberdesc} -\begin{datadesc}{path} +\begin{memberdesc}{path} Contains the request path. -\end{datadesc} +\end{memberdesc} -\begin{datadesc}{request_version} +\begin{memberdesc}{request_version} Contains the version string from the request. For example, \code{'HTTP/1.0'}. -\end{datadesc} +\end{memberdesc} -\begin{datadesc}{headers} +\begin{memberdesc}{headers} Holds an instance of the class specified by the \member{MessageClass} class variable. This instance parses and manages the headers in the HTTP request. -\end{datadesc} +\end{memberdesc} -\begin{datadesc}{rfile} +\begin{memberdesc}{rfile} Contains an input stream, positioned at the start of the optional input data. -\end{datadesc} +\end{memberdesc} -\begin{datadesc}{wfile} +\begin{memberdesc}{wfile} Contains the output stream for writing a response back to the client. Proper adherance to the HTTP protocol must be used when writing to this stream. -\end{datadesc} +\end{memberdesc} -\setindexsubitem{(BaseHTTPRequestHandler attribute)} -\code{BaseHTTPRequestHandler} has the following class variables: +\class{BaseHTTPRequestHandler} has the following class variables: -\begin{datadesc}{server_version} +\begin{memberdesc}{server_version} Specifies the server software version. You may want to override this. The format is multiple whitespace-separated strings, where each string is of the form name[/version]. For example, \code{'BaseHTTP/0.2'}. -\end{datadesc} +\end{memberdesc} -\begin{datadesc}{sys_version} +\begin{memberdesc}{sys_version} Contains the Python system version, in a form usable by the \member{version_string} method and the \member{server_version} class variable. For example, \code{'Python/1.4'}. -\end{datadesc} +\end{memberdesc} -\begin{datadesc}{error_message_format} +\begin{memberdesc}{error_message_format} Specifies a format string for building an error response to the client. It uses parenthesized, keyed format specifiers, so the format operand must be a dictionary. The \var{code} key should @@ -115,103 +118,102 @@ message of what occurred, and \var{explain} should be an explanation of the error code number. Default \var{message} and \var{explain} values can found in the \var{responses} class variable. -\end{datadesc} +\end{memberdesc} -\begin{datadesc}{protocol_version} +\begin{memberdesc}{protocol_version} This specifies the HTTP protocol version used in responses. Typically, this should not be overridden. Defaults to \code{'HTTP/1.0'}. -\end{datadesc} +\end{memberdesc} -\begin{datadesc}{MessageClass} +\begin{memberdesc}{MessageClass} Specifies a \class{rfc822.Message}-like class to parse HTTP headers. Typically, this is not overridden, and it defaults to \class{mimetools.Message}. \withsubitem{(in module mimetools)}{\ttindex{Message}} -\end{datadesc} +\end{memberdesc} -\begin{datadesc}{responses} +\begin{memberdesc}{responses} This variable contains a mapping of error code integers to two-element tuples containing a short and long message. For example, \code{\{\var{code}: (\var{shortmessage}, \var{longmessage})\}}. The \var{shortmessage} is usually used as the \var{message} key in an error response, and \var{longmessage} as the \var{explain} key (see the \member{error_message_format} class variable). -\end{datadesc} +\end{memberdesc} -\setindexsubitem{(BaseHTTPRequestHandler method)} A \class{BaseHTTPRequestHandler} instance has the following methods: -\begin{funcdesc}{handle}{} +\begin{methoddesc}{handle}{} Overrides the superclass' \method{handle()} method to provide the specific handler behavior. This method will parse and dispatch -the request to the appropriate \code{do_*()} method. -\end{funcdesc} +the request to the appropriate \method{do_*()} method. +\end{methoddesc} -\begin{funcdesc}{send_error}{code\optional{, message}} +\begin{methoddesc}{send_error}{code\optional{, message}} Sends and logs a complete error reply to the client. The numeric \var{code} specifies the HTTP error code, with \var{message} as optional, more specific text. A complete set of headers is sent, followed by text composed using the \member{error_message_format} class variable. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{send_response}{code\optional{, message}} +\begin{methoddesc}{send_response}{code\optional{, message}} Sends a response header and logs the accepted request. The HTTP response line is sent, followed by \emph{Server} and \emph{Date} headers. The values for these two headers are picked up from the \method{version_string()} and \method{date_time_string()} methods, respectively. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{send_header}{keyword, value} +\begin{methoddesc}{send_header}{keyword, value} Writes a specific MIME header to the output stream. \var{keyword} should specify the header keyword, with \var{value} specifying its value. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{end_headers}{} +\begin{methoddesc}{end_headers}{} Sends a blank line, indicating the end of the MIME headers in the response. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{log_request}{\optional{code\optional{, size}}} +\begin{methoddesc}{log_request}{\optional{code\optional{, size}}} Logs an accepted (successful) request. \var{code} should specify the numeric HTTP code associated with the response. If a size of the response is available, then it should be passed as the \var{size} parameter. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{log_error}{...} +\begin{methoddesc}{log_error}{...} Logs an error when a request cannot be fulfilled. By default, it passes the message to \method{log_message()}, so it takes the same arguments (\var{format} and additional values). -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{log_message}{format, ...} +\begin{methoddesc}{log_message}{format, ...} Logs an arbitrary message to \code{sys.stderr}. This is typically overridden to create custom error logging mechanisms. The \var{format} argument is a standard printf-style format string, where the additional arguments to \method{log_message()} are applied as inputs to the formatting. The client address and current date and time are prefixed to every message logged. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{version_string}{} +\begin{methoddesc}{version_string}{} Returns the server software's version string. This is a combination of the \member{server_version} and \member{sys_version} class variables. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{date_time_string}{} +\begin{methoddesc}{date_time_string}{} Returns the current date and time, formatted for a message header. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{log_data_time_string}{} +\begin{methoddesc}{log_data_time_string}{} Returns the current date and time, formatted for logging. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{address_string}{} +\begin{methoddesc}{address_string}{} Returns the client address, formatted for logging. A name lookup is performed on the client's IP address. -\end{funcdesc} +\end{methoddesc} diff --git a/Doc/libbinhex.tex b/Doc/libbinhex.tex index 560b401..6a7d3c6 100644 --- a/Doc/libbinhex.tex +++ b/Doc/libbinhex.tex @@ -1,15 +1,13 @@ -\section{Standard Module \sectcode{binhex}} +\section{Standard Module \module{binhex}} \label{module-binhex} \stmodindex{binhex} This module encodes and decodes files in binhex4 format, a format -allowing representation of Macintosh files in ASCII. On the macintosh, +allowing representation of Macintosh files in \ASCII{}. On the Macintosh, both forks of a file and the finder information are encoded (or decoded), on other platforms only the data fork is handled. -The \code{binhex} module defines the following functions: - -\setindexsubitem{(in module binhex)} +The \module{binhex} module defines the following functions: \begin{funcdesc}{binhex}{input, output} Convert a binary file with filename \var{input} to binhex file @@ -31,7 +29,8 @@ There is an alternative, more powerful interface to the coder and decoder, see the source for details. If you code or decode textfiles on non-Macintosh platforms they will -still use the macintosh newline convention (carriage-return as end of +still use the Macintosh newline convention (carriage-return as end of line). -As of this writing, \var{hexbin} appears to not work in all cases. +As of this writing, \function{hexbin()} appears to not work in all +cases. diff --git a/Doc/libcd.tex b/Doc/libcd.tex index e2571cc..fc32da5 100644 --- a/Doc/libcd.tex +++ b/Doc/libcd.tex @@ -1,4 +1,4 @@ -\section{Built-in Module \sectcode{cd}} +\section{Built-in Module \module{cd}} \label{module-cd} \bimodindex{cd} @@ -113,32 +113,34 @@ that can be set by the \method{addcallback()} method of CD parser objects (see below). \end{datadesc} + +\subsection{Player Objects} +\label{player-objects} + Player objects (returned by \function{open()}) have the following methods: -\setindexsubitem{(CD player method)} - -\begin{funcdesc}{allowremoval}{} +\begin{methoddesc}[CD player]{allowremoval}{} Unlocks the eject button on the CD-ROM drive permitting the user to eject the caddy if desired. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{bestreadsize}{} +\begin{methoddesc}[CD player]{bestreadsize}{} Returns the best value to use for the \var{num_frames} parameter of the \method{readda()} method. Best is defined as the value that permits a continuous flow of data from the CD-ROM drive. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{close}{} +\begin{methoddesc}[CD player]{close}{} Frees the resources associated with the player object. After calling \method{close()}, the methods of the object should no longer be used. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{eject}{} +\begin{methoddesc}[CD player]{eject}{} Ejects the caddy from the CD-ROM drive. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{getstatus}{} +\begin{methoddesc}[CD player]{getstatus}{} Returns information pertaining to the current state of the CD-ROM drive. The returned information is a tuple with the following values: \var{state}, \var{track}, \var{rtime}, \var{atime}, \var{ttime}, @@ -150,24 +152,24 @@ the meaning of the values, see the man page \manpage{CDgetstatus}{3dm}. The value of \var{state} is one of the following: \constant{ERROR}, \constant{NODISC}, \constant{READY}, \constant{PLAYING}, \constant{PAUSED}, \constant{STILL}, or \constant{CDROM}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{gettrackinfo}{track} +\begin{methoddesc}[CD player]{gettrackinfo}{track} Returns information about the specified track. The returned information is a tuple consisting of two elements, the start time of the track and the duration of the track. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{msftoblock}{min, sec, frame} +\begin{methoddesc}[CD player]{msftoblock}{min, sec, frame} Converts a minutes, seconds, frames triple representing a time in absolute time code into the corresponding logical block number for the given CD-ROM drive. You should use \function{msftoframe()} rather than \method{msftoblock()} for comparing times. The logical block number differs from the frame number by an offset required by certain CD-ROM drives. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{play}{start, play} +\begin{methoddesc}[CD player]{play}{start, play} Starts playback of an audio CD in the CD-ROM drive at the specified track. The audio output appears on the CD-ROM drive's headphone and audio jacks (if fitted). Play stops at the end of the disc. @@ -175,71 +177,73 @@ audio jacks (if fitted). Play stops at the end of the disc. CD; if \var{play} is 0, the CD will be set to an initial paused state. The method \method{togglepause()} can then be used to commence play. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{playabs}{minutes, seconds, frames, play} +\begin{methoddesc}[CD player]{playabs}{minutes, seconds, frames, play} Like \method{play()}, except that the start is given in minutes, seconds, and frames instead of a track number. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{playtrack}{start, play} +\begin{methoddesc}[CD player]{playtrack}{start, play} Like \method{play()}, except that playing stops at the end of the track. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{playtrackabs}{track, minutes, seconds, frames, play} +\begin{methoddesc}[CD player]{playtrackabs}{track, minutes, seconds, frames, play} Like \method{play()}, except that playing begins at the spcified absolute time and ends at the end of the specified track. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{preventremoval}{} +\begin{methoddesc}[CD player]{preventremoval}{} Locks the eject button on the CD-ROM drive thus preventing the user from arbitrarily ejecting the caddy. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{readda}{num_frames} +\begin{methoddesc}[CD player]{readda}{num_frames} Reads the specified number of frames from an audio CD mounted in the CD-ROM drive. The return value is a string representing the audio frames. This string can be passed unaltered to the \method{parseframe()} method of the parser object. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{seek}{minutes, seconds, frames} +\begin{methoddesc}[CD player]{seek}{minutes, seconds, frames} Sets the pointer that indicates the starting point of the next read of digital audio data from a CD-ROM. The pointer is set to an absolute time code location specified in \var{minutes}, \var{seconds}, and \var{frames}. The return value is the logical block number to which the pointer has been set. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{seekblock}{block} +\begin{methoddesc}[CD player]{seekblock}{block} Sets the pointer that indicates the starting point of the next read of digital audio data from a CD-ROM. The pointer is set to the specified logical block number. The return value is the logical block number to which the pointer has been set. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{seektrack}{track} +\begin{methoddesc}[CD player]{seektrack}{track} Sets the pointer that indicates the starting point of the next read of digital audio data from a CD-ROM. The pointer is set to the specified track. The return value is the logical block number to which the pointer has been set. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{stop}{} +\begin{methoddesc}[CD player]{stop}{} Stops the current playing operation. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{togglepause}{} +\begin{methoddesc}[CD player]{togglepause}{} Pauses the CD if it is playing, and makes it play if it is paused. -\end{funcdesc} +\end{methoddesc} + + +\subsection{Parser Objects} +\label{cd-parser-objects} Parser objects (returned by \function{createparser()}) have the following methods: -\setindexsubitem{(CD parser method)} - -\begin{funcdesc}{addcallback}{type, func, arg} +\begin{methoddesc}[CD parser]{addcallback}{type, func, arg} Adds a callback for the parser. The parser has callbacks for eight different types of data in the digital audio data stream. Constants for these types are defined at the \module{cd} module level (see above). @@ -268,15 +272,15 @@ owner code, \\ \lineii{control}{Integer giving the control bits from the CD subcode data} \end{tableii} -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{deleteparser}{} +\begin{methoddesc}[CD parser]{deleteparser}{} Deletes the parser and frees the memory it was using. The object should not be used after this call. This call is done automatically when the last reference to the object is removed. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{parseframe}{frame} +\begin{methoddesc}[CD parser]{parseframe}{frame} Parses one or more frames of digital audio data from a CD such as returned by \method{readda()}. It determines which subcodes are present in the data. If these subcodes have changed since the last @@ -284,14 +288,14 @@ frame, then \method{parseframe()} executes a callback of the appropriate type passing to it the subcode data found in the frame. Unlike the \C{} function, more than one frame of digital audio data can be passed to this method. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{removecallback}{type} +\begin{methoddesc}[CD parser]{removecallback}{type} Removes the callback for the given \var{type}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{resetparser}{} +\begin{methoddesc}[CD parser]{resetparser}{} Resets the fields of the parser used for tracking subcodes to an initial state. \method{resetparser()} should be called after the disc has been changed. -\end{funcdesc} +\end{methoddesc} diff --git a/Doc/libfl.tex b/Doc/libfl.tex index 4716e7b..a0e0076 100644 --- a/Doc/libfl.tex +++ b/Doc/libfl.tex @@ -1,4 +1,4 @@ -\section{Built-in Module \sectcode{fl}} +\section{Built-in Module \module{fl}} \label{module-fl} \bimodindex{fl} @@ -37,7 +37,7 @@ FORMS with pure GL windows. function \cfunction{foreground()} and to the FORMS routine \cfunction{fl_init()}. -\subsection{Functions Defined in Module \sectcode{fl}} +\subsection{Functions Defined in Module \module{fl}} \nodename{FL Functions} Module \module{fl} defines the following functions. For more @@ -83,7 +83,8 @@ Show a dialog box with a three-line message and YES and NO buttons. It returns \code{1} if the user pressed YES, \code{0} if NO. \end{funcdesc} -\begin{funcdesc}{show_choice}{str1, str2, str3, but1\optional{, but2, but3}} +\begin{funcdesc}{show_choice}{str1, str2, str3, but1\optional{, + but2\optional{, but3}}} Show a dialog box with a three-line message and up to three buttons. It returns the number of the button clicked by the user (\code{1}, \code{2} or \code{3}). @@ -136,116 +137,117 @@ See the description in the FORMS documentation of \end{funcdesc} \subsection{Form Objects} +\label{form-objects} -Form objects (returned by \function{fl.make_form()} above) have the +Form objects (returned by \function{make_form()} above) have the following methods. Each method corresponds to a \C{} function whose name is prefixed with \samp{fl_}; and whose first argument is a form pointer; please refer to the official FORMS documentation for descriptions. -All the \code{add_*()} functions return a Python object -representing the FORMS object. Methods of FORMS objects are described -below. Most kinds of FORMS object also have some methods specific to -that kind; these methods are listed here. +All the \method{add_*()} methods return a Python object representing +the FORMS object. Methods of FORMS objects are described below. Most +kinds of FORMS object also have some methods specific to that kind; +these methods are listed here. \begin{flushleft} -\setindexsubitem{(form method)} -\begin{funcdesc}{show_form}{placement, bordertype, name} + +\begin{methoddesc}[form]{show_form}{placement, bordertype, name} Show the form. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{hide_form}{} +\begin{methoddesc}[form]{hide_form}{} Hide the form. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{redraw_form}{} +\begin{methoddesc}[form]{redraw_form}{} Redraw the form. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{set_form_position}{x, y} +\begin{methoddesc}[form]{set_form_position}{x, y} Set the form's position. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{freeze_form}{} +\begin{methoddesc}[form]{freeze_form}{} Freeze the form. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{unfreeze_form}{} +\begin{methoddesc}[form]{unfreeze_form}{} Unfreeze the form. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{activate_form}{} +\begin{methoddesc}[form]{activate_form}{} Activate the form. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{deactivate_form}{} +\begin{methoddesc}[form]{deactivate_form}{} Deactivate the form. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{bgn_group}{} +\begin{methoddesc}[form]{bgn_group}{} Begin a new group of objects; return a group object. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{end_group}{} +\begin{methoddesc}[form]{end_group}{} End the current group of objects. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{find_first}{} +\begin{methoddesc}[form]{find_first}{} Find the first object in the form. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{find_last}{} +\begin{methoddesc}[form]{find_last}{} Find the last object in the form. -\end{funcdesc} +\end{methoddesc} %--- -\begin{funcdesc}{add_box}{type, x, y, w, h, name} +\begin{methoddesc}[form]{add_box}{type, x, y, w, h, name} Add a box object to the form. No extra methods. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{add_text}{type, x, y, w, h, name} +\begin{methoddesc}[form]{add_text}{type, x, y, w, h, name} Add a text object to the form. No extra methods. -\end{funcdesc} +\end{methoddesc} -%\begin{funcdesc}{add_bitmap}{type, x, y, w, h, name} +%\begin{methoddesc}[form]{add_bitmap}{type, x, y, w, h, name} %Add a bitmap object to the form. -%\end{funcdesc} +%\end{methoddesc} -\begin{funcdesc}{add_clock}{type, x, y, w, h, name} +\begin{methoddesc}[form]{add_clock}{type, x, y, w, h, name} Add a clock object to the form. \\ Method: \method{get_clock()}. -\end{funcdesc} +\end{methoddesc} %--- -\begin{funcdesc}{add_button}{type, x, y, w, h, name} +\begin{methoddesc}[form]{add_button}{type, x, y, w, h, name} Add a button object to the form. \\ Methods: \method{get_button()}, \method{set_button()}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{add_lightbutton}{type, x, y, w, h, name} +\begin{methoddesc}[form]{add_lightbutton}{type, x, y, w, h, name} Add a lightbutton object to the form. \\ Methods: \method{get_button()}, \method{set_button()}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{add_roundbutton}{type, x, y, w, h, name} +\begin{methoddesc}[form]{add_roundbutton}{type, x, y, w, h, name} Add a roundbutton object to the form. \\ Methods: \method{get_button()}, \method{set_button()}. -\end{funcdesc} +\end{methoddesc} %--- -\begin{funcdesc}{add_slider}{type, x, y, w, h, name} +\begin{methoddesc}[form]{add_slider}{type, x, y, w, h, name} Add a slider object to the form. \\ Methods: \method{set_slider_value()}, @@ -256,9 +258,9 @@ Methods: \method{set_slider_size()}, \method{set_slider_precision()}, \method{set_slider_step()}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{add_valslider}{type, x, y, w, h, name} +\begin{methoddesc}[form]{add_valslider}{type, x, y, w, h, name} Add a valslider object to the form. \\ Methods: \method{set_slider_value()}, @@ -269,18 +271,18 @@ Methods: \method{set_slider_size()}, \method{set_slider_precision()}, \method{set_slider_step()}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{add_dial}{type, x, y, w, h, name} +\begin{methoddesc}[form]{add_dial}{type, x, y, w, h, name} Add a dial object to the form. \\ Methods: \method{set_dial_value()}, \method{get_dial_value()}, \method{set_dial_bounds()}, \method{get_dial_bounds()}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{add_positioner}{type, x, y, w, h, name} +\begin{methoddesc}[form]{add_positioner}{type, x, y, w, h, name} Add a positioner object to the form. \\ Methods: \method{set_positioner_xvalue()}, @@ -291,9 +293,9 @@ Methods: \method{get_positioner_yvalue()}, \method{get_positioner_xbounds()}, \method{get_positioner_ybounds()}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{add_counter}{type, x, y, w, h, name} +\begin{methoddesc}[form]{add_counter}{type, x, y, w, h, name} Add a counter object to the form. \\ Methods: \method{set_counter_value()}, @@ -302,30 +304,30 @@ Methods: \method{set_counter_step()}, \method{set_counter_precision()}, \method{set_counter_return()}. -\end{funcdesc} +\end{methoddesc} %--- -\begin{funcdesc}{add_input}{type, x, y, w, h, name} +\begin{methoddesc}[form]{add_input}{type, x, y, w, h, name} Add a input object to the form. \\ Methods: \method{set_input()}, \method{get_input()}, \method{set_input_color()}, \method{set_input_return()}. -\end{funcdesc} +\end{methoddesc} %--- -\begin{funcdesc}{add_menu}{type, x, y, w, h, name} +\begin{methoddesc}[form]{add_menu}{type, x, y, w, h, name} Add a menu object to the form. \\ Methods: \method{set_menu()}, \method{get_menu()}, \method{addto_menu()}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{add_choice}{type, x, y, w, h, name} +\begin{methoddesc}[form]{add_choice}{type, x, y, w, h, name} Add a choice object to the form. \\ Methods: \method{set_choice()}, @@ -337,9 +339,9 @@ Methods: \method{get_choice_text()}, \method{set_choice_fontsize()}, \method{set_choice_fontstyle()}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{add_browser}{type, x, y, w, h, name} +\begin{methoddesc}[form]{add_browser}{type, x, y, w, h, name} Add a browser object to the form. \\ Methods: \method{set_browser_topline()}, @@ -360,16 +362,16 @@ Methods: \method{set_browser_fontsize()}, \method{set_browser_fontstyle()}, \method{set_browser_specialkey()}. -\end{funcdesc} +\end{methoddesc} %--- -\begin{funcdesc}{add_timer}{type, x, y, w, h, name} +\begin{methoddesc}[form]{add_timer}{type, x, y, w, h, name} Add a timer object to the form. \\ Methods: \method{set_timer()}, \method{get_timer()}. -\end{funcdesc} +\end{methoddesc} \end{flushleft} Form objects have the following data attributes; see the FORMS @@ -388,49 +390,49 @@ documentation: \end{tableiii} \subsection{FORMS Objects} +\label{forms-objects} Besides methods specific to particular kinds of FORMS objects, all FORMS objects also have the following methods: -\setindexsubitem{(FORMS method)} -\begin{funcdesc}{set_call_back}{function, argument} +\begin{methoddesc}[FORMS object]{set_call_back}{function, argument} Set the object's callback function and argument. When the object needs interaction, the callback function will be called with two arguments: the object, and the callback argument. (FORMS objects without a callback function are returned by \function{fl.do_forms()} or \function{fl.check_forms()} when they need interaction.) Call this method without arguments to remove the callback function. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{delete_object}{} +\begin{methoddesc}[FORMS object]{delete_object}{} Delete the object. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{show_object}{} +\begin{methoddesc}[FORMS object]{show_object}{} Show the object. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{hide_object}{} +\begin{methoddesc}[FORMS object]{hide_object}{} Hide the object. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{redraw_object}{} +\begin{methoddesc}[FORMS object]{redraw_object}{} Redraw the object. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{freeze_object}{} +\begin{methoddesc}[FORMS object]{freeze_object}{} Freeze the object. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{unfreeze_object}{} +\begin{methoddesc}[FORMS object]{unfreeze_object}{} Unfreeze the object. -\end{funcdesc} +\end{methoddesc} -%\begin{funcdesc}{handle_object}{} XXX -%\end{funcdesc} +%\begin{methoddesc}[FORMS object]{handle_object}{} XXX +%\end{methoddesc} -%\begin{funcdesc}{handle_object_direct}{} XXX -%\end{funcdesc} +%\begin{methoddesc}[FORMS object]{handle_object_direct}{} XXX +%\end{methoddesc} FORMS objects have these data attributes; see the FORMS documentation: @@ -460,7 +462,7 @@ FORMS objects have these data attributes; see the FORMS documentation: \lineiii{automatic}{int (read-only)}{(see FORMS docs)} \end{tableiii} -\section{Standard Module \sectcode{FL}} +\section{Standard Module \module{FL}} \label{module-FLuppercase} \stmodindex{FL} @@ -475,7 +477,7 @@ import fl from FL import * \end{verbatim} -\section{Standard Module \sectcode{flp}} +\section{Standard Module \module{flp}} \label{module-flp} \stmodindex{flp} diff --git a/Doc/libftplib.tex b/Doc/libftplib.tex index cda8b66..7f0aeda 100644 --- a/Doc/libftplib.tex +++ b/Doc/libftplib.tex @@ -1,4 +1,4 @@ -\section{Standard Module \sectcode{ftplib}} +\section{Standard Module \module{ftplib}} \label{module-ftplib} \stmodindex{ftplib} \indexii{FTP}{protocol} @@ -30,7 +30,8 @@ dr-xr-srwt 105 ftp-usr pdmaint 1536 Mar 21 14:32 .. The module defines the following items: -\begin{classdesc}{FTP}{\optional{host\optional{, user\optional{, passwd\optional{, acct}}}}} +\begin{classdesc}{FTP}{\optional{host\optional{, user\optional{, + passwd\optional{, acct}}}}} Return a new instance of the \code{FTP} class. When \var{host} is given, the method call \code{connect(\var{host})} is made. When \var{user} is given, additionally the method call @@ -63,37 +64,37 @@ Exception raised when a reply is received from the server that does not begin with a digit in the range 1--5. \end{excdesc} + \subsection{FTP Objects} +\label{ftp-objects} \class{FTP} instances have the following methods: -\setindexsubitem{(FTP method)} - -\begin{funcdesc}{set_debuglevel}{level} +\begin{methoddesc}{set_debuglevel}{level} Set the instance's debugging level. This controls the amount of debugging output printed. The default, \code{0}, produces no debugging output. A value of \code{1} produces a moderate amount of debugging output, generally a single line per request. A value of \code{2} or higher produces the maximum amount of debugging output, logging each line sent and received on the control connection. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{connect}{host\optional{, port}} +\begin{methoddesc}{connect}{host\optional{, port}} Connect to the given host and port. The default port number is \code{21}, as specified by the FTP protocol specification. It is rarely needed to specify a different port number. This function should be called only once for each instance; it should not be called at all if a host was given when the instance was created. All other methods can only be used after a connection has been made. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{getwelcome}{} +\begin{methoddesc}{getwelcome}{} Return the welcome message sent by the server in reply to the initial connection. (This message sometimes contains disclaimers or help information that may be relevant to the user.) -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{login}{\optional{user\optional{, passwd\optional{, acct}}}} +\begin{methoddesc}{login}{\optional{user\optional{, passwd\optional{, acct}}}} Log in as the given \var{user}. The \var{passwd} and \var{acct} parameters are optional and default to the empty string. If no \var{user} is specified, it defaults to \code{'anonymous'}. If @@ -106,25 +107,25 @@ once for each instance, after a connection has been established; it should not be called at all if a host and user were given when the instance was created. Most FTP commands are only allowed after the client has logged in. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{abort}{} +\begin{methoddesc}{abort}{} Abort a file transfer that is in progress. Using this does not always work, but it's worth a try. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{sendcmd}{command} +\begin{methoddesc}{sendcmd}{command} Send a simple command string to the server and return the response string. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{voidcmd}{command} +\begin{methoddesc}{voidcmd}{command} Send a simple command string to the server and handle the response. Return nothing if a response code in the range 200--299 is received. Raise an exception otherwise. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{retrbinary}{command, callback\optional{, maxblocksize}} +\begin{methoddesc}{retrbinary}{command, callback\optional{, maxblocksize}} Retrieve a file in binary transfer mode. \var{command} should be an appropriate \samp{RETR} command, i.e.\ \code{'RETR \var{filename}'}. The \var{callback} function is called for each block of data received, @@ -133,73 +134,73 @@ The optional \var{maxblocksize} argument specifies the maximum chunk size to read on the low-level socket object created to do the actual transfer (which will also be the largest size of the data blocks passed to \var{callback}). A reasonable default is chosen. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{retrlines}{command\optional{, callback}} +\begin{methoddesc}{retrlines}{command\optional{, callback}} Retrieve a file or directory listing in \ASCII{} transfer mode. \var{command} should be an appropriate \samp{RETR} command (see \method{retrbinary()} or a \samp{LIST} command (usually just the string \code{'LIST'}). The \var{callback} function is called for each line, with the trailing CRLF stripped. The default \var{callback} prints the line to \code{sys.stdout}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{storbinary}{command, file, blocksize} +\begin{methoddesc}{storbinary}{command, file, blocksize} Store a file in binary transfer mode. \var{command} should be an appropriate \samp{STOR} command, i.e.\ \code{"STOR \var{filename}"}. \var{file} is an open file object which is read until \EOF{} using its \method{read()} method in blocks of size \var{blocksize} to provide the data to be stored. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{storlines}{command, file} +\begin{methoddesc}{storlines}{command, file} Store a file in \ASCII{} transfer mode. \var{command} should be an appropriate \samp{STOR} command (see \method{storbinary()}). Lines are read until \EOF{} from the open file object \var{file} using its \method{readline()} method to privide the data to be stored. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{nlst}{argument\optional{, \ldots}} +\begin{methoddesc}{nlst}{argument\optional{, \ldots}} Return a list of files as returned by the \samp{NLST} command. The optional \var{argument} is a directory to list (default is the current server directory). Multiple arguments can be used to pass non-standard options to the \samp{NLST} command. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{dir}{argument\optional{, \ldots}} +\begin{methoddesc}{dir}{argument\optional{, \ldots}} Return a directory listing as returned by the \samp{LIST} command, as a list of lines. The optional \var{argument} is a directory to list (default is the current server directory). Multiple arguments can be used to pass non-standard options to the \samp{LIST} command. If the last argument is a function, it is used as a \var{callback} function as for \method{retrlines()}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{rename}{fromname, toname} +\begin{methoddesc}{rename}{fromname, toname} Rename file \var{fromname} on the server to \var{toname}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{cwd}{pathname} +\begin{methoddesc}{cwd}{pathname} Set the current directory on the server. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{mkd}{pathname} +\begin{methoddesc}{mkd}{pathname} Create a new directory on the server. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{pwd}{} +\begin{methoddesc}{pwd}{} Return the pathname of the current directory on the server. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{quit}{} +\begin{methoddesc}{quit}{} Send a \samp{QUIT} command to the server and close the connection. This is the ``polite'' way to close a connection, but it may raise an exception of the server reponds with an error to the \samp{QUIT} command. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{close}{} +\begin{methoddesc}{close}{} Close the connection unilaterally. This should not be applied to an already closed connection (e.g.\ after a successful call to \method{quit()}. -\end{funcdesc} +\end{methoddesc} diff --git a/Doc/libhttplib.tex b/Doc/libhttplib.tex index d578ae2..55ec9b98 100644 --- a/Doc/libhttplib.tex +++ b/Doc/libhttplib.tex @@ -1,4 +1,4 @@ -\section{Standard Module \sectcode{httplib}} +\section{Standard Module \module{httplib}} \label{module-httplib} \stmodindex{httplib} \indexii{HTTP}{protocol} @@ -9,7 +9,10 @@ HTTP protocol. It is normally not used directly --- the module \module{urllib}\refstmodindex{urllib} uses it to handle URLs that use HTTP. -The module defines one class, \class{HTTP}. An \class{HTTP} instance +The module defines one class, \class{HTTP}: + +\begin{classdesc}{HTTP}{\optional{host\optional{, port}}} +An \class{HTTP} instance represents one transaction with an HTTP server. It should be instantiated passing it a host and optional port number. If no port number is passed, the port is extracted from the host string if it has @@ -45,50 +48,50 @@ step 4 makes no calls). file object that it returns. \end{enumerate} +\end{classdesc} \subsection{HTTP Objects} \class{HTTP} instances have the following methods: -\setindexsubitem{(HTTP method)} -\begin{funcdesc}{set_debuglevel}{level} +\begin{methoddesc}{set_debuglevel}{level} Set the debugging level (the amount of debugging output printed). The default debug level is \code{0}, meaning no debugging output is printed. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{connect}{host\optional{, port}} +\begin{methoddesc}{connect}{host\optional{, port}} Connect to the server given by \var{host} and \var{port}. See the intro for the default port. This should be called directly only if the instance was instantiated without passing a host. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{send}{data} +\begin{methoddesc}{send}{data} Send data to the server. This should be used directly only after the \method{endheaders()} method has been called and before \method{getreply()} has been called. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{putrequest}{request, selector} +\begin{methoddesc}{putrequest}{request, selector} This should be the first call after the connection to the server has been made. It sends a line to the server consisting of the \var{request} string, the \var{selector} string, and the HTTP version (\code{HTTP/1.0}). -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{putheader}{header, argument\optional{, ...}} +\begin{methoddesc}{putheader}{header, argument\optional{, ...}} Send an \rfc{822} style header to the server. It sends a line to the server consisting of the header, a colon and a space, and the first argument. If more arguments are given, continuation lines are sent, each consisting of a tab and an argument. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{endheaders}{} +\begin{methoddesc}{endheaders}{} Send a blank line to the server, signalling the end of the headers. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{getreply}{} +\begin{methoddesc}{getreply}{} Complete the request by shutting down the sending end of the socket, read the reply from the server, and return a triple \code{(\var{replycode}, \var{message}, \var{headers})}. Here, @@ -98,13 +101,13 @@ message string corresponding to the reply code; and \var{headers} is an instance of the class \class{mimetools.Message} containing the headers received from the server. See the description of the \module{mimetools}\refstmodindex{mimetools} module. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{getfile}{} +\begin{methoddesc}{getfile}{} Return a file object from which the data returned by the server can be read, using the \method{read()}, \method{readline()} or \method{readlines()} methods. -\end{funcdesc} +\end{methoddesc} \subsection{Example} \nodename{HTTP Example} @@ -123,5 +126,4 @@ Here is an example session: >>> f = h.getfile() >>> data = f.read() # Get the raw HTML >>> f.close() ->>> \end{verbatim} diff --git a/Doc/libimageop.tex b/Doc/libimageop.tex index 4a93487..c21be48 100644 --- a/Doc/libimageop.tex +++ b/Doc/libimageop.tex @@ -1,16 +1,14 @@ -\section{Built-in Module \sectcode{imageop}} +\section{Built-in Module \module{imageop}} \label{module-imageop} \bimodindex{imageop} -The \code{imageop} module contains some useful operations on images. -It operates on images consisting of 8 or 32 bit pixels -stored in Python strings. This is the same format as used -by \code{gl.lrectwrite} and the \code{imgfile} module. +The \module{imageop} module contains some useful operations on images. +It operates on images consisting of 8 or 32 bit pixels stored in +Python strings. This is the same format as used by +\function{gl.lrectwrite()} and the \module{imgfile} module. The module defines the following variables and functions: -\setindexsubitem{(in module imageop)} - \begin{excdesc}{error} This exception is raised on all errors, such as unknown number of bits per pixel, etc. @@ -21,11 +19,11 @@ per pixel, etc. Return the selected part of \var{image}, which should by \var{width} by \var{height} in size and consist of pixels of \var{psize} bytes. \var{x0}, \var{y0}, \var{x1} and \var{y1} are like -the \code{lrectread} parameters, i.e.\ the boundary is included in the -new image. The new boundaries need not be inside the picture. Pixels -that fall outside the old image will have their value set to zero. If -\var{x0} is bigger than \var{x1} the new image is mirrored. The same -holds for the y coordinates. +the \function{gl.lrectread()} parameters, i.e.\ the boundary is +included in the new image. The new boundaries need not be inside the +picture. Pixels that fall outside the old image will have their value +set to zero. If \var{x0} is bigger than \var{x1} the new image is +mirrored. The same holds for the y coordinates. \end{funcdesc} \begin{funcdesc}{scale}{image, psize, width, height, newwidth, newheight} @@ -46,7 +44,7 @@ interlacing, hence the name. \begin{funcdesc}{grey2mono}{image, width, height, threshold} Convert a 8-bit deep greyscale image to a 1-bit deep image by tresholding all the pixels. The resulting image is tightly packed and -is probably only useful as an argument to \code{mono2grey}. +is probably only useful as an argument to \function{mono2grey()}. \end{funcdesc} \begin{funcdesc}{dither2mono}{image, width, height} @@ -74,8 +72,8 @@ dithering. \begin{funcdesc}{dither2grey2}{image, width, height} Convert an 8-bit greyscale image to a 2-bit greyscale image with -dithering. As for \code{dither2mono}, the dithering algorithm is -currently very simple. +dithering. As for \function{dither2mono()}, the dithering algorithm +is currently very simple. \end{funcdesc} \begin{funcdesc}{grey42grey}{image, width, height} diff --git a/Doc/libjpeg.tex b/Doc/libjpeg.tex index 745fe32..201a142 100644 --- a/Doc/libjpeg.tex +++ b/Doc/libjpeg.tex @@ -1,10 +1,12 @@ -\section{Built-in Module \sectcode{jpeg}} +\section{Built-in Module \module{jpeg}} \label{module-jpeg} \bimodindex{jpeg} The module \module{jpeg} provides access to the jpeg compressor and -decompressor written by the Independent JPEG Group. JPEG is a (draft?) -standard for compressing pictures. For details on jpeg or the +decompressor written by the Independent JPEG Group% +\index{Independent JPEG Group}% +. JPEG is a (draft?) +standard for compressing pictures. For details on JPEG or the Independent JPEG Group software refer to the JPEG standard or the documentation provided with the software. @@ -18,19 +20,19 @@ in case of errors. \begin{funcdesc}{compress}{data, w, h, b} Treat data as a pixmap of width \var{w} and height \var{h}, with \var{b} bytes per pixel. The data is in SGI GL order, so the first -pixel is in the lower-left corner. This means that \code{gl.lrectread} +pixel is in the lower-left corner. This means that \function{gl.lrectread()} return data can immediately be passed to \function{compress()}. Currently only 1 byte and 4 byte pixels are allowed, the former being treated as greyscale and the latter as RGB color. \function{compress()} returns a string that contains the compressed -picture, in JFIF format. +picture, in JFIF\index{JFIF} format. \end{funcdesc} \begin{funcdesc}{decompress}{data} -Data is a string containing a picture in JFIF format. It returns a -tuple \code{(\var{data}, \var{width}, \var{height}, +Data is a string containing a picture in JFIF\index{JFIF} format. It +returns a tuple \code{(\var{data}, \var{width}, \var{height}, \var{bytesperpixel})}. Again, the data is suitable to pass to -\code{gl.lrectwrite}. +\function{gl.lrectwrite()}. \end{funcdesc} \begin{funcdesc}{setoption}{name, value} diff --git a/Doc/libmimetools.tex b/Doc/libmimetools.tex index 0d4e40f..54d1fe0 100644 --- a/Doc/libmimetools.tex +++ b/Doc/libmimetools.tex @@ -1,8 +1,7 @@ -\section{Standard Module \sectcode{mimetools}} +\section{Standard Module \module{mimetools}} \label{module-mimetools} \stmodindex{mimetools} -\setindexsubitem{(in module mimetools)} This module defines a subclass of the \class{rfc822.Message} class and a number of utility functions that are useful for the manipulation for @@ -53,9 +52,7 @@ open file \var{output}. The block size is currently fixed at 8192. The \class{Message} class defines the following methods in addition to the \class{rfc822.Message} methods: -\setindexsubitem{(mimetool.Message method)} - -\begin{funcdesc}{getplist}{} +\begin{methoddesc}{getplist}{} Return the parameter list of the \code{content-type} header. This is a list if strings. For parameters of the form \samp{\var{key}=\var{value}}, \var{key} is converted to lower case but @@ -63,36 +60,36 @@ a list if strings. For parameters of the form \samp{Content-type: text/html; spam=1; Spam=2; Spam} then \method{getplist()} will return the Python list \code{['spam=1', 'spam=2', 'Spam']}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{getparam}{name} +\begin{methoddesc}{getparam}{name} Return the \var{value} of the first parameter (as returned by \method{getplist()} of the form \samp{\var{name}=\var{value}} for the given \var{name}. If \var{value} is surrounded by quotes of the form `\code{<}...\code{>}' or `\code{"}...\code{"}', these are removed. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{getencoding}{} +\begin{methoddesc}{getencoding}{} Return the encoding specified in the \code{content-transfer-encoding} message header. If no such header exists, return \code{'7bit'}. The encoding is converted to lower case. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{gettype}{} +\begin{methoddesc}{gettype}{} Return the message type (of the form \samp{\var{type}/\var{subtype}}) as specified in the \code{content-type} header. If no such header exists, return \code{'text/plain'}. The type is converted to lower case. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{getmaintype}{} +\begin{methoddesc}{getmaintype}{} Return the main type as specified in the \code{content-type} header. If no such header exists, return \code{'text'}. The main type is converted to lower case. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{getsubtype}{} +\begin{methoddesc}{getsubtype}{} Return the subtype as specified in the \code{content-type} header. If no such header exists, return \code{'plain'}. The subtype is converted to lower case. -\end{funcdesc} +\end{methoddesc} diff --git a/Doc/libmpz.tex b/Doc/libmpz.tex index 1c4b19f..707a3a8 100644 --- a/Doc/libmpz.tex +++ b/Doc/libmpz.tex @@ -1,38 +1,48 @@ -\section{Built-in Module \sectcode{mpz}} +\section{Built-in Module \module{mpz}} \label{module-mpz} \bimodindex{mpz} This is an optional module. It is only available when Python is configured to include it, which requires that the GNU MP software is installed. +\index{MP, GNU library} +\index{arbitrary precision integers} +\index{integer!arbitrary precision} This module implements the interface to part of the GNU MP library, which defines arbitrary precision integer and rational number arithmetic routines. Only the interfaces to the \emph{integer} -(\samp{mpz_{\rm \ldots}}) routines are provided. If not stated +(\function{mpz_*()}) routines are provided. If not stated otherwise, the description in the GNU MP documentation can be applied. In general, \dfn{mpz}-numbers can be used just like other standard Python numbers, e.g.\ you can use the built-in operators like \code{+}, \code{*}, etc., as well as the standard built-in functions like -\code{abs}, \code{int}, \ldots, \code{divmod}, \code{pow}. -\strong{Please note:} the \emph{bitwise-xor} operation has been implemented as -a bunch of \emph{and}s, \emph{invert}s and \emph{or}s, because the library -lacks an \code{mpz_xor} function, and I didn't need one. +\function{abs()}, \function{int()}, \ldots, \function{divmod()}, +\function{pow()}. \strong{Please note:} the \emph{bitwise-xor} +operation has been implemented as a bunch of \emph{and}s, +\emph{invert}s and \emph{or}s, because the library lacks an +\cfunction{mpz_xor()} function, and I didn't need one. -You create an mpz-number by calling the function called \code{mpz} (see +You create an mpz-number by calling the function \function{mpz()} (see below for an exact description). An mpz-number is printed like this: \code{mpz(\var{value})}. -\setindexsubitem{(in module mpz)} + \begin{funcdesc}{mpz}{value} Create a new mpz-number. \var{value} can be an integer, a long, another mpz-number, or even a string. If it is a string, it is interpreted as an array of radix-256 digits, least significant digit - first, resulting in a positive number. See also the \code{binary} + first, resulting in a positive number. See also the \method{binary()} method, described below. \end{funcdesc} +\begin{datadesc}{MPZType} + The type of the objects returned by \function{mpz()} and most other + functions in this module. +\end{datadesc} + + A number of \emph{extra} functions are defined in this module. Non mpz-arguments are converted to mpz-values first, and the functions return mpz-numbers. @@ -40,7 +50,7 @@ return mpz-numbers. \begin{funcdesc}{powm}{base, exponent, modulus} Return \code{pow(\var{base}, \var{exponent}) \%{} \var{modulus}}. If \code{\var{exponent} == 0}, return \code{mpz(1)}. In contrast to the - \C-library function, this version can handle negative exponents. + \C{} library function, this version can handle negative exponents. \end{funcdesc} \begin{funcdesc}{gcd}{op1, op2} @@ -62,18 +72,18 @@ return mpz-numbers. \end{funcdesc} \begin{funcdesc}{divm}{numerator, denominator, modulus} - Returns a number \var{q}. such that - \code{\var{q} * \var{denominator} \%{} \var{modulus} == \var{numerator}}. - One could also implement this function in Python, using \code{gcdext}. + Returns a number \var{q} such that + \code{\var{q} * \var{denominator} \%{} \var{modulus} == + \var{numerator}}. One could also implement this function in Python, + using \function{gcdext()}. \end{funcdesc} An mpz-number has one method: -\setindexsubitem{(mpz method)} -\begin{funcdesc}{binary}{} +\begin{methoddesc}[mpz]{binary}{} Convert this mpz-number to a binary string, where the number has been stored as an array of radix-256 digits, least significant digit first. The mpz-number must have a value greater than or equal to zero, - otherwise a \code{ValueError}-exception will be raised. -\end{funcdesc} + otherwise \exception{ValueError} will be raised. +\end{methoddesc} diff --git a/Doc/libnntplib.tex b/Doc/libnntplib.tex index 75c84d3..ba1d788 100644 --- a/Doc/libnntplib.tex +++ b/Doc/libnntplib.tex @@ -1,11 +1,10 @@ -\section{Standard Module \sectcode{nntplib}} +\section{Standard Module \module{nntplib}} \label{module-nntplib} \stmodindex{nntplib} \indexii{NNTP}{protocol} -\setindexsubitem{(in module nntplib)} -This module defines the class \code{NNTP} which implements the client +This module defines the class \class{NNTP} which implements the client side of the NNTP protocol. It can be used to implement a news reader or poster, or automated news processors. For more information on NNTP (Network News Transfer Protocol), see Internet \rfc{977}. @@ -34,7 +33,6 @@ Group comp.lang.python has 59 articles, range 3742 to 3803 3803 Re: \POSIX{} wait and SIGCHLD >>> s.quit() '205 news.cwi.nl closing connection. Goodbye.' ->>> \end{verbatim} To post an article from a file (this assumes that the article has @@ -47,16 +45,15 @@ valid headers): '240 Article posted successfully.' >>> s.quit() '205 news.cwi.nl closing connection. Goodbye.' ->>> \end{verbatim} % The module itself defines the following items: -\begin{funcdesc}{NNTP}{host\optional{, port}} -Return a new instance of the \code{NNTP} class, representing a +\begin{classdesc}{NNTP}{host\optional{, port}} +Return a new instance of the \class{NNTP} class, representing a connection to the NNTP server running on host \var{host}, listening at port \var{port}. The default \var{port} is 119. -\end{funcdesc} +\end{classdesc} \begin{excdesc}{error_reply} Exception raised when an unexpected reply is received from the server. @@ -75,7 +72,9 @@ Exception raised when a reply is received from the server that does not begin with a digit in the range 1--5. \end{excdesc} + \subsection{NNTP Objects} +\label{nntp-objects} NNTP instances have the following methods. The \var{response} that is returned as the first item in the return tuple of almost all methods @@ -83,40 +82,40 @@ is the server's response: a string beginning with a three-digit code. If the server's response indicates an error, the method raises one of the above exceptions. -\setindexsubitem{(NNTP object method)} -\begin{funcdesc}{getwelcome}{} +\begin{methoddesc}{getwelcome}{} Return the welcome message sent by the server in reply to the initial connection. (This message sometimes contains disclaimers or help information that may be relevant to the user.) -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{set_debuglevel}{level} +\begin{methoddesc}{set_debuglevel}{level} Set the instance's debugging level. This controls the amount of -debugging output printed. The default, 0, produces no debugging -output. A value of 1 produces a moderate amount of debugging output, -generally a single line per request or response. A value of 2 or -higher produces the maximum amount of debugging output, logging each -line sent and received on the connection (including message text). -\end{funcdesc} - -\begin{funcdesc}{newgroups}{date, time} +debugging output printed. The default, \code{0}, produces no debugging +output. A value of \code{1} produces a moderate amount of debugging +output, generally a single line per request or response. A value of +\code{2} or higher produces the maximum amount of debugging output, +logging each line sent and received on the connection (including +message text). +\end{methoddesc} + +\begin{methoddesc}{newgroups}{date, time} Send a \samp{NEWGROUPS} command. The \var{date} argument should be a string of the form \code{"\var{yy}\var{mm}\var{dd}"} indicating the date, and \var{time} should be a string of the form \code{"\var{hh}\var{mm}\var{ss}"} indicating the time. Return a pair \code{(\var{response}, \var{groups})} where \var{groups} is a list of group names that are new since the given date and time. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{newnews}{group, date, time} +\begin{methoddesc}{newnews}{group, date, time} Send a \samp{NEWNEWS} command. Here, \var{group} is a group name or -\code{"*"}, and \var{date} and \var{time} have the same meaning as for -\code{newgroups()}. Return a pair \code{(\var{response}, +\code{'*'}, and \var{date} and \var{time} have the same meaning as for +\method{newgroups()}. Return a pair \code{(\var{response}, \var{articles})} where \var{articles} is a list of article ids. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{list}{} +\begin{methoddesc}{list}{} Send a \samp{LIST} command. Return a pair \code{(\var{response}, \var{list})} where \var{list} is a list of tuples. Each tuple has the form \code{(\var{group}, \var{last}, \var{first}, \var{flag})}, where @@ -124,106 +123,107 @@ form \code{(\var{group}, \var{last}, \var{first}, \var{flag})}, where and first article numbers (as strings), and \var{flag} is \code{'y'} if posting is allowed, \code{'n'} if not, and \code{'m'} if the newsgroup is moderated. (Note the ordering: \var{last}, \var{first}.) -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{group}{name} +\begin{methoddesc}{group}{name} Send a \samp{GROUP} command, where \var{name} is the group name. -Return a tuple \code{(\var{response}, \var{count}, \var{first}, -\var{last}, \var{name})} where \var{count} is the (estimated) number -of articles in the group, \var{first} is the first article number in -the group, \var{last} is the last article number in the group, and -\var{name} is the group name. The numbers are returned as strings. -\end{funcdesc} - -\begin{funcdesc}{help}{} +Return a tuple \code{(}\var{response}\code{,} \var{count}\code{,} +\var{first}\code{,} \var{last}\code{,} \var{name}\code{)} where +\var{count} is the (estimated) number of articles in the group, +\var{first} is the first article number in the group, \var{last} is +the last article number in the group, and \var{name} is the group +name. The numbers are returned as strings. +\end{methoddesc} + +\begin{methoddesc}{help}{} Send a \samp{HELP} command. Return a pair \code{(\var{response}, \var{list})} where \var{list} is a list of help strings. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{stat}{id} +\begin{methoddesc}{stat}{id} Send a \samp{STAT} command, where \var{id} is the message id (enclosed -in \samp{<} and \samp{>}) or an article number (as a string). +in \character{<} and \character{>}) or an article number (as a string). Return a triple \code{(\var{response}, \var{number}, \var{id})} where \var{number} is the article number (as a string) and \var{id} is the -article id (enclosed in \samp{<} and \samp{>}). -\end{funcdesc} +article id (enclosed in \character{<} and \character{>}). +\end{methoddesc} -\begin{funcdesc}{next}{} -Send a \samp{NEXT} command. Return as for \code{stat()}. -\end{funcdesc} +\begin{methoddesc}{next}{} +Send a \samp{NEXT} command. Return as for \method{stat()}. +\end{methoddesc} -\begin{funcdesc}{last}{} -Send a \samp{LAST} command. Return as for \code{stat()}. -\end{funcdesc} +\begin{methoddesc}{last}{} +Send a \samp{LAST} command. Return as for \method{stat()}. +\end{methoddesc} -\begin{funcdesc}{head}{id} +\begin{methoddesc}{head}{id} Send a \samp{HEAD} command, where \var{id} has the same meaning as for -\code{stat()}. Return a pair \code{(\var{response}, \var{list})} +\method{stat()}. Return a pair \code{(\var{response}, \var{list})} where \var{list} is a list of the article's headers (an uninterpreted list of lines, without trailing newlines). -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{body}{id} +\begin{methoddesc}{body}{id} Send a \samp{BODY} command, where \var{id} has the same meaning as for -\code{stat()}. Return a pair \code{(\var{response}, \var{list})} +\method{stat()}. Return a pair \code{(\var{response}, \var{list})} where \var{list} is a list of the article's body text (an uninterpreted list of lines, without trailing newlines). -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{article}{id} +\begin{methoddesc}{article}{id} Send a \samp{ARTICLE} command, where \var{id} has the same meaning as -for \code{stat()}. Return a pair \code{(\var{response}, \var{list})} +for \method{stat()}. Return a pair \code{(\var{response}, \var{list})} where \var{list} is a list of the article's header and body text (an uninterpreted list of lines, without trailing newlines). -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{slave}{} +\begin{methoddesc}{slave}{} Send a \samp{SLAVE} command. Return the server's \var{response}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{xhdr}{header, string} +\begin{methoddesc}{xhdr}{header, string} Send an \samp{XHDR} command. This command is not defined in the RFC but is a common extension. The \var{header} argument is a header -keyword, e.g. \code{"subject"}. The \var{string} argument should have +keyword, e.g. \code{'subject'}. The \var{string} argument should have the form \code{"\var{first}-\var{last}"} where \var{first} and \var{last} are the first and last article numbers to search. Return a pair \code{(\var{response}, \var{list})}, where \var{list} is a list of pairs \code{(\var{id}, \var{text})}, where \var{id} is an article id (as a string) and \var{text} is the text of the requested header for that article. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{post}{file} +\begin{methoddesc}{post}{file} Post an article using the \samp{POST} command. The \var{file} argument is an open file object which is read until EOF using its -\code{readline()} method. It should be a well-formed news article, -including the required headers. The \code{post()} method +\method{readline()} method. It should be a well-formed news article, +including the required headers. The \method{post()} method automatically escapes lines beginning with \samp{.}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{ihave}{id, file} +\begin{methoddesc}{ihave}{id, file} Send an \samp{IHAVE} command. If the response is not an error, treat -\var{file} exactly as for the \code{post()} method. -\end{funcdesc} +\var{file} exactly as for the \method{post()} method. +\end{methoddesc} -\begin{funcdesc}{date}{} +\begin{methoddesc}{date}{} Return a triple \code{(\var{response}, \var{date}, \var{time})}, containing the current date and time in a form suitable for the -\code{newnews} and \code{newgroups} methods. +\method{newnews()} and \method{newgroups()} methods. This is an optional NNTP extension, and may not be supported by all servers. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{xgtitle}{name} -Process an XGTITLE command, returning a pair \code{(\var{response}, +\begin{methoddesc}{xgtitle}{name} +Process an \samp{XGTITLE} command, returning a pair \code{(\var{response}, \var{list})}, where \var{list} is a list of tuples containing \code{(\var{name}, \var{title})}. % XXX huh? Should that be name, description? This is an optional NNTP extension, and may not be supported by all servers. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{xover}{start, end} +\begin{methoddesc}{xover}{start, end} Return a pair \code{(\var{resp}, \var{list})}. \var{list} is a list of tuples, one for each article in the range delimited by the \var{start} and \var{end} article numbers. Each tuple is of the form @@ -232,15 +232,15 @@ and \var{end} article numbers. Each tuple is of the form \var{references}\code{,} \var{size}\code{,} \var{lines}\code{)}. This is an optional NNTP extension, and may not be supported by all servers. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{xpath}{id} +\begin{methoddesc}{xpath}{id} Return a pair \code{(\var{resp}, \var{path})}, where \var{path} is the directory path to the article with message ID \var{id}. This is an optional NNTP extension, and may not be supported by all servers. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{quit}{} +\begin{methoddesc}{quit}{} Send a \samp{QUIT} command and close the connection. Once this method has been called, no other methods of the NNTP object should be called. -\end{funcdesc} +\end{methoddesc} diff --git a/Doc/librgbimg.tex b/Doc/librgbimg.tex index 873a75f..73e4aae 100644 --- a/Doc/librgbimg.tex +++ b/Doc/librgbimg.tex @@ -5,7 +5,7 @@ The \module{rgbimg} module allows Python programs to access SGI imglib image files (also known as \file{.rgb} files). The module is far from complete, but is provided anyway since the functionality that there is -is enough in some cases. Currently, colormap files are not supported. +enough in some cases. Currently, colormap files are not supported. The module defines the following variables and functions: @@ -24,7 +24,7 @@ are currently supported. This function reads and decodes the image on the specified file, and returns it as a Python string. The string has 4 byte RGBA pixels. The bottom left pixel is the first in -the string. This format is suitable to pass to \code{gl.lrectwrite}, +the string. This format is suitable to pass to \function{gl.lrectwrite()}, for instance. \end{funcdesc} @@ -34,7 +34,7 @@ file \var{file}. \var{x} and \var{y} give the size of the image. \var{z} is 1 if the saved image should be 1 byte greyscale, 3 if the saved image should be 3 byte RGB data, or 4 if the saved images should be 4 byte RGBA data. The input data always contains 4 bytes per pixel. -These are the formats returned by \code{gl.lrectread}. +These are the formats returned by \function{gl.lrectread()}. \end{funcdesc} \begin{funcdesc}{ttob}{flag} diff --git a/Doc/librotor.tex b/Doc/librotor.tex index e467d4e..63dc56e 100644 --- a/Doc/librotor.tex +++ b/Doc/librotor.tex @@ -1,9 +1,10 @@ -\section{Built-in Module \sectcode{rotor}} +\section{Built-in Module \module{rotor}} \label{module-rotor} \bimodindex{rotor} This module implements a rotor-based encryption algorithm, contributed by -Lance Ellinghouse. The design is derived from the Enigma device, a machine +Lance Ellinghouse\index{Ellinghouse, Lance}. The design is derived +from the Enigma device\indexii{Enigma}{device}, a machine used during World War II to encipher messages. A rotor is simply a permutation. For example, if the character `A' is the origin of the rotor, then a given rotor might map `A' to `L', `B' to `Z', `C' to `G', and so on. @@ -19,12 +20,10 @@ recursively. In other words, after enciphering one character, we advance the rotors in the same fashion as a car's odometer. Decoding works in the same way, except we reverse the permutations and apply them in the opposite order. -\index{Ellinghouse, Lance} \indexii{Enigma}{cipher} The available functions in this module are: -\setindexsubitem{(in module rotor)} \begin{funcdesc}{newrotor}{key\optional{, numrotors}} Return a rotor object. \var{key} is a string containing the encryption key for the object; it can contain arbitrary binary data. The key will be used @@ -35,32 +34,31 @@ if it is omitted, a default value of 6 will be used. Rotor objects have the following methods: -\setindexsubitem{(rotor method)} -\begin{funcdesc}{setkey}{key} +\begin{methoddesc}[rotor]{setkey}{key} Sets the rotor's key to \var{key}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{encrypt}{plaintext} +\begin{methoddesc}[rotor]{encrypt}{plaintext} Reset the rotor object to its initial state and encrypt \var{plaintext}, returning a string containing the ciphertext. The ciphertext is always the same length as the original plaintext. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{encryptmore}{plaintext} +\begin{methoddesc}[rotor]{encryptmore}{plaintext} Encrypt \var{plaintext} without resetting the rotor object, and return a string containing the ciphertext. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{decrypt}{ciphertext} +\begin{methoddesc}[rotor]{decrypt}{ciphertext} Reset the rotor object to its initial state and decrypt \var{ciphertext}, returning a string containing the ciphertext. The plaintext string will always be the same length as the ciphertext. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{decryptmore}{ciphertext} +\begin{methoddesc}[rotor]{decryptmore}{ciphertext} Decrypt \var{ciphertext} without resetting the rotor object, and return a string containing the ciphertext. -\end{funcdesc} +\end{methoddesc} An example usage: \begin{verbatim} @@ -80,17 +78,18 @@ An example usage: 'l(\315' >>> del rt \end{verbatim} -% -The module's code is not an exact simulation of the original Enigma device; -it implements the rotor encryption scheme differently from the original. The -most important difference is that in the original Enigma, there were only 5 -or 6 different rotors in existence, and they were applied twice to each -character; the cipher key was the order in which they were placed in the -machine. The Python rotor module uses the supplied key to initialize a -random number generator; the rotor permutations and their initial positions -are then randomly generated. The original device only enciphered the -letters of the alphabet, while this module can handle any 8-bit binary data; -it also produces binary output. This module can also operate with an + +The module's code is not an exact simulation of the original Enigma +device; it implements the rotor encryption scheme differently from the +original. The most important difference is that in the original +Enigma, there were only 5 or 6 different rotors in existence, and they +were applied twice to each character; the cipher key was the order in +which they were placed in the machine. The Python \module{rotor} +module uses the supplied key to initialize a random number generator; +the rotor permutations and their initial positions are then randomly +generated. The original device only enciphered the letters of the +alphabet, while this module can handle any 8-bit binary data; it also +produces binary output. This module can also operate with an arbitrary number of rotors. The original Enigma cipher was broken in 1944. % XXX: Is this right? @@ -102,5 +101,4 @@ for discouraging casual snooping through your files, it will probably be just fine, and may be somewhat safer than using the \UNIX{} \program{crypt} command. \index{NSA} -\index{National Security Agency}\index{crypt(1)} -% XXX How were Unix commands represented in the docs? +\index{National Security Agency} diff --git a/Doc/libsunaudio.tex b/Doc/libsunaudio.tex index bafd7c5..c43d611 100644 --- a/Doc/libsunaudio.tex +++ b/Doc/libsunaudio.tex @@ -1,15 +1,14 @@ -\section{Built-in Module \sectcode{sunaudiodev}} +\section{Built-in Module \module{sunaudiodev}} \label{module-sunaudiodev} \bimodindex{sunaudiodev} This module allows you to access the sun audio interface. The sun audio hardware is capable of recording and playing back audio data -in U-LAW format with a sample rate of 8K per second. A full -description can be gotten with \samp{man audio}. +in u-LAW\index{u-LAW} format with a sample rate of 8K per second. A +full description can be found in the \manpage{audio}{7I} manual page. The module defines the following variables and functions: -\setindexsubitem{(in module sunaudiodev)} \begin{excdesc}{error} This exception is raised on all errors. The argument is a string describing what went wrong. @@ -22,87 +21,87 @@ is one of \code{'r'} for record-only access, \code{'w'} for play-only access, \code{'rw'} for both and \code{'control'} for access to the control device. Since only one process is allowed to have the recorder or player open at the same time it is a good idea to open the device -only for the activity needed. See the audio manpage for details. +only for the activity needed. See \manpage{audio}{7I} for details. \end{funcdesc} + \subsection{Audio Device Objects} +\label{audio-device-objects} -The audio device objects are returned by \code{open} define the +The audio device objects are returned by \function{open()} define the following methods (except \code{control} objects which only provide -getinfo, setinfo and drain): - -\setindexsubitem{(audio device method)} +\method{getinfo()}, \method{setinfo()} and \method{drain()}): -\begin{funcdesc}{close}{} +\begin{methoddesc}[audio device]{close}{} This method explicitly closes the device. It is useful in situations where deleting the object does not immediately close it since there are other references to it. A closed device should not be used again. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{drain}{} +\begin{methoddesc}[audio device]{drain}{} This method waits until all pending output is processed and then returns. Calling this method is often not necessary: destroying the object will automatically close the audio device and this will do an implicit drain. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{flush}{} +\begin{methoddesc}[audio device]{flush}{} This method discards all pending output. It can be used avoid the slow response to a user's stop request (due to buffering of up to one second of sound). -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{getinfo}{} +\begin{methoddesc}[audio device]{getinfo}{} This method retrieves status information like input and output volume, etc. and returns it in the form of an audio status object. This object has no methods but it contains a number of attributes describing the current device status. The names and meanings of the attributes are described in -\file{/usr/include/sun/audioio.h} and in the audio man page. Member names -are slightly different from their C counterparts: a status object is -only a single structure. Members of the \code{play} substructure have -\samp{o_} prepended to their name and members of the \code{record} -structure have \samp{i_}. So, the C member \code{play.sample_rate} is -accessed as \code{o_sample_rate}, \code{record.gain} as \code{i_gain} -and \code{monitor_gain} plainly as \code{monitor_gain}. -\end{funcdesc} - -\begin{funcdesc}{ibufcount}{} +\file{/usr/include/sun/audioio.h} and in the \manpage{audio}{7I} +manual page. Member names +are slightly different from their \C{} counterparts: a status object is +only a single structure. Members of the \cdata{play} substructure have +\samp{o_} prepended to their name and members of the \cdata{record} +structure have \samp{i_}. So, the \C{} member \cdata{play.sample_rate} is +accessed as \member{o_sample_rate}, \cdata{record.gain} as \member{i_gain} +and \cdata{monitor_gain} plainly as \member{monitor_gain}. +\end{methoddesc} + +\begin{methoddesc}[audio device]{ibufcount}{} This method returns the number of samples that are buffered on the -recording side, i.e. -the program will not block on a \function{read()} call of so many samples. -\end{funcdesc} +recording side, i.e.\ the program will not block on a +\function{read()} call of so many samples. +\end{methoddesc} -\begin{funcdesc}{obufcount}{} +\begin{methoddesc}[audio device]{obufcount}{} This method returns the number of samples buffered on the playback side. Unfortunately, this number cannot be used to determine a number of samples that can be written without blocking since the kernel output queue length seems to be variable. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{read}{size} +\begin{methoddesc}[audio device]{read}{size} This method reads \var{size} samples from the audio input and returns them as a Python string. The function blocks until enough data is available. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{setinfo}{status} +\begin{methoddesc}[audio device]{setinfo}{status} This method sets the audio device status parameters. The \var{status} parameter is an device status object as returned by \function{getinfo()} and possibly modified by the program. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{write}{samples} +\begin{methoddesc}[audio device]{write}{samples} Write is passed a Python string containing audio samples to be played. If there is enough buffer space free it will immediately return, otherwise it will block. -\end{funcdesc} +\end{methoddesc} -There is a companion module, \module{SUNAUDIODEV}, which defines useful +There is a companion module, +\module{SUNAUDIODEV}\refstmodindex{SUNAUDIODEV}, which defines useful symbolic constants like \constant{MIN_GAIN}, \constant{MAX_GAIN}, -\constant{SPEAKER}, etc. The names of -the constants are the same names as used in the \C{} include file -\code{<sun/audioio.h>}, with the leading string \samp{AUDIO_} -stripped. -\refstmodindex{SUNAUDIODEV} +\constant{SPEAKER}, etc. The names of the constants are the same names +as used in the \C{} include file \code{<sun/audioio.h>}, with the +leading string \samp{AUDIO_} stripped. Useability of the control device is limited at the moment, since there is no way to use the ``wait for something to happen'' feature the diff --git a/Doc/libxmllib.tex b/Doc/libxmllib.tex index efc7f00..4306aca 100644 --- a/Doc/libxmllib.tex +++ b/Doc/libxmllib.tex @@ -1,4 +1,4 @@ -\section{Standard Module \sectcode{xmllib}} +\section{Standard Module \module{xmllib}} % Author: Sjoerd Mullender \label{module-xmllib} \stmodindex{xmllib} @@ -13,59 +13,57 @@ The \class{XMLParser} class must be instantiated without arguments. This class provides the following interface methods: -\setindexsubitem{(XMLParser method)} - -\begin{funcdesc}{reset}{} +\begin{methoddesc}{reset}{} Reset the instance. Loses all unprocessed data. This is called implicitly at the instantiation time. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{setnomoretags}{} +\begin{methoddesc}{setnomoretags}{} Stop processing tags. Treat all following input as literal input (CDATA). -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{setliteral}{} +\begin{methoddesc}{setliteral}{} Enter literal mode (CDATA mode). -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{feed}{data} +\begin{methoddesc}{feed}{data} Feed some text to the parser. It is processed insofar as it consists of complete elements; incomplete data is buffered until more data is fed or \method{close()} is called. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{close}{} +\begin{methoddesc}{close}{} Force processing of all buffered data as if it were followed by an end-of-file mark. This method may be redefined by a derived class to define additional processing at the end of the input, but the redefined version should always call \method{close()}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{translate_references}{data} +\begin{methoddesc}{translate_references}{data} Translate all entity and character references in \var{data} and returns the translated string. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{handle_xml}{encoding, standalone} -This method is called when the \code{<?xml ...?>} tag is processed. +\begin{methoddesc}{handle_xml}{encoding, standalone} +This method is called when the \samp{<?xml ...?>} tag is processed. The arguments are the values of the encoding and standalone attributes in the tag. Both encoding and standalone are optional. The values passed to \method{handle_xml()} default to \code{None} and the string \code{'no'} respectively. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{handle_doctype}{tag, data} -This method is called when the \code{<!DOCTYPE...>} tag is processed. +\begin{methoddesc}{handle_doctype}{tag, data} +This method is called when the \samp{<!DOCTYPE...>} tag is processed. The arguments are the name of the root element and the uninterpreted contents of the tag, starting after the white space after the name of the root element. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{handle_starttag}{tag, method, attributes} +\begin{methoddesc}{handle_starttag}{tag, method, attributes} This method is called to handle start tags for which a -\code{start_\var{tag}()} method has been defined. The \var{tag} -argument is the name of the tag, and the \method{method} argument is the +\method{start_\var{tag}()} method has been defined. The \var{tag} +argument is the name of the tag, and the \var{method} argument is the bound method which should be used to support semantic interpretation of the start tag. The \var{attributes} argument is a dictionary of attributes, the key being the \var{name} and the value being the @@ -76,29 +74,29 @@ been interpreted. For instance, for the tag \code{handle_starttag('A', self.start_A, \{'HREF': 'http://www.cwi.nl/'\})}. The base implementation simply calls \var{method} with \var{attributes} as the only argument. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{handle_endtag}{tag, method} +\begin{methoddesc}{handle_endtag}{tag, method} This method is called to handle endtags for which an -\code{end_\var{tag}()} method has been defined. The \var{tag} +\method{end_\var{tag}()} method has been defined. The \var{tag} argument is the name of the tag, and the \var{method} argument is the bound method which should be used to support semantic interpretation of the end tag. If no -\code{end_\var{tag}()} method is defined for the closing element, this +\method{end_\var{tag}()} method is defined for the closing element, this handler is not called. The base implementation simply calls \var{method}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{handle_data}{data} +\begin{methoddesc}{handle_data}{data} This method is called to process arbitrary data. It is intended to be overridden by a derived class; the base class implementation does nothing. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{handle_charref}{ref} +\begin{methoddesc}{handle_charref}{ref} This method is called to process a character reference of the form \samp{\&\#\var{ref};}. \var{ref} can either be a decimal number, -or a hexadecimal number when preceded by \code{x}. +or a hexadecimal number when preceded by an \character{x}. In the base implementation, \var{ref} must be a number in the range 0-255. It translates the character to \ASCII{} and calls the method \method{handle_data()} with the character as argument. If @@ -106,9 +104,9 @@ method \method{handle_data()} with the character as argument. If \code{unknown_charref(\var{ref})} is called to handle the error. A subclass must override this method to provide support for character references outside of the \ASCII{} range. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{handle_entityref}{ref} +\begin{methoddesc}{handle_entityref}{ref} This method is called to process a general entity reference of the form \samp{\&\var{ref};} where \var{ref} is an general entity reference. It looks for \var{ref} in the instance (or class) @@ -119,48 +117,48 @@ with the translation; otherwise, it calls the method \code{unknown_entityref(\var{ref})}. The default \member{entitydefs} defines translations for \code{\&}, \code{\&apos}, \code{\>}, \code{\<}, and \code{\"}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{handle_comment}{comment} +\begin{methoddesc}{handle_comment}{comment} This method is called when a comment is encountered. The \var{comment} argument is a string containing the text between the \samp{<!--} and \samp{-->} delimiters, but not the delimiters themselves. For example, the comment \samp{<!--text-->} will cause this method to be called with the argument \code{'text'}. The default method does nothing. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{handle_cdata}{data} +\begin{methoddesc}{handle_cdata}{data} This method is called when a CDATA element is encountered. The \var{data} argument is a string containing the text between the \samp{<![CDATA[} and \samp{]]>} delimiters, but not the delimiters themselves. For example, the entity \samp{<![CDATA[text]]>} will cause this method to be called with the argument \code{'text'}. The default method does nothing, and is intended to be overridden. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{handle_proc}{name, data} +\begin{methoddesc}{handle_proc}{name, data} This method is called when a processing instruction (PI) is encountered. The \var{name} is the PI target, and the \var{data} argument is a string containing the text between the PI target and the closing delimiter, but not the delimiter itself. For example, the instruction \samp{<?XML text?>} will cause this method to be called with the arguments \code{'XML'} and \code{'text'}. The default method -does nothing. Note that if a document starts with \code{<?xml +does nothing. Note that if a document starts with \samp{<?xml ...?>}, \method{handle_xml()} is called to handle it. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{handle_special}{data} +\begin{methoddesc}{handle_special}{data} This method is called when a declaration is encountered. The \var{data} argument is a string containing the text between the \samp{<!} and \samp{>} delimiters, but not the delimiters themselves. For example, the entity \samp{<!ENTITY text>} will cause this method to be called with the argument \code{'ENTITY text'}. The -default method does nothing. Note that \code{<!DOCTYPE ...>} is +default method does nothing. Note that \samp{<!DOCTYPE ...>} is handled separately if it is located at the start of the document. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{syntax_error}{message} +\begin{methoddesc}{syntax_error}{message} This method is called when a syntax error is encountered. The \var{message} is a description of what was wrong. The default method raises a \exception{RuntimeError} exception. If this method is @@ -168,31 +166,31 @@ overridden, it is permissable for it to return. This method is only called when the error can be recovered from. Unrecoverable errors raise a \exception{RuntimeError} without first calling \method{syntax_error()}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{unknown_starttag}{tag, attributes} +\begin{methoddesc}{unknown_starttag}{tag, attributes} This method is called to process an unknown start tag. It is intended to be overridden by a derived class; the base class implementation does nothing. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{unknown_endtag}{tag} +\begin{methoddesc}{unknown_endtag}{tag} This method is called to process an unknown end tag. It is intended to be overridden by a derived class; the base class implementation does nothing. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{unknown_charref}{ref} +\begin{methoddesc}{unknown_charref}{ref} This method is called to process unresolvable numeric character references. It is intended to be overridden by a derived class; the base class implementation does nothing. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{unknown_entityref}{ref} +\begin{methoddesc}{unknown_entityref}{ref} This method is called to process an unknown entity reference. It is intended to be overridden by a derived class; the base class implementation does nothing. -\end{funcdesc} +\end{methoddesc} Apart from overriding or extending the methods listed above, derived classes may also define methods and variables of the following form to @@ -200,19 +198,19 @@ define processing of specific tags. Tag names in the input stream are case dependent; the \var{tag} occurring in method names must be in the correct case: -\begin{funcdescni}{start_\var{tag}}{attributes} +\begin{methoddescni}{start_\var{tag}}{attributes} This method is called to process an opening tag \var{tag}. The \var{attributes} argument has the same meaning as described for \method{handle_starttag()} above. In fact, the base implementation of \method{handle_starttag()} calls this method. -\end{funcdescni} +\end{methoddescni} -\begin{funcdescni}{end_\var{tag}}{} +\begin{methoddescni}{end_\var{tag}}{} This method is called to process a closing tag \var{tag}. -\end{funcdescni} +\end{methoddescni} -\begin{datadescni}{\var{tag}_attributes} -If a class or instance variable \code{\var{tag}_attributes} exists, it +\begin{memberdescni}{\var{tag}_attributes} +If a class or instance variable \member{\var{tag}_attributes} exists, it should be a list or a dictionary. If a list, the elements of the list are the valid attributes for the element \var{tag}; if a dictionary, the keys are the valid attributes for the element \var{tag}, and the @@ -222,4 +220,4 @@ In addition to the attributes that were present in the tag, the attribute dictionary that is passed to \method{handle_starttag()} and \method{unknown_starttag()} contains values for all attributes that have a default value. -\end{datadescni} +\end{memberdescni} |