Added chapter on Windows modules, including msvcrt and winsound.

Doc/lib/lib.tex

@@ -234,6 +234,10 @@ add new extensions to Python and how to embed it in other applications.
 \input{libsun}			% SUNOS ONLY
 \input{libsunaudio}
 
+\input{windows}			% MS Windows ONLY
+\input{libmsvcrt}
+\input{libwinsound}
+
 \input{libundoc}
 
 %

Doc/lib/libmsvcrt.tex

@@ -0,0 +1,84 @@
+\section{\module{msvcrt} --
+         Useful routines from the MS VC++ runtime}
+
+\declaremodule{builtin}{msvcrt}
+\modulesynopsis{Miscellaneous useful routines from the MS VC++ runtime.}
+\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
+
+
+These functions provide access to some useful capabilities on Windows
+platforms.  Some higher-level modules use these functions to build the 
+Windows implementations of their services.  For example, the
+\refmodule{getpass} module uses this in the implementation of the
+\function{getpass()} function.
+
+Further documentation on these functions can be found in the Platform
+API documentation.
+
+
+\subsection{File Operations \label{msvcrt-files}}
+
+\begin{funcdesc}{locking}{fd, mode, nbytes}
+  Lock part of a file based on a file descriptor from the C runtime.
+  Raises \exception{IOError} on failure.
+\end{funcdesc}
+
+\begin{funcdesc}{setmode}{fd, flags}
+  Set the line-end translation mode for the file descriptor \var{fd}.
+  To set it to text mode, \var{flags} should be \constant{_O_TEXT};
+  for binary, it should be \constant{_O_BINARY}.
+\end{funcdesc}
+
+\begin{funcdesc}{open_osfhandle}{handle, flags}
+  Create a C runtime file descriptor from the file handle
+  \var{handle}.  The \var{flags} parameter should be a bit-wise OR of
+  \constant{_O_APPEND}, \constant{_O_RDONLY}, and \constant{_O_TEXT}.
+  The returned file descriptor may be used as a parameter to
+  \function{os.fdopen()} to create a file object.
+\end{funcdesc}
+
+\begin{funcdesc}{get_osfhandle}{fd}
+  Return the file handle for the file descriptor \var{fd}.  Raises
+  \exception{IOError} if \var{fd} is not recognized.
+\end{funcdesc}
+
+
+\subsection{Console I/O \label{msvcrt-console}}
+
+\begin{funcdesc}{kbhit}{}
+  Return true if a keypress is waiting to be read.
+\end{funcdesc}
+
+\begin{funcdesc}{getch}{}
+  Read a keypress and return the resulting character.  Nothing is
+  echoed to the console.  This call will block if a keypress is not
+  already available, but will not wait for \kbd{Enter} to be pressed.
+  If the pressed key was a special function key, this will return
+  \code{'\e000'} or \code{'\e xe0'}; the next call will return the
+  keycode.  The \kbd{Control-C} keypress cannot be read with this
+  function.
+\end{funcdesc}
+
+\begin{funcdesc}{getche}{}
+  Similar to \function{getch()}, but the keypress will be echoed if it 
+  represents a printable character.
+\end{funcdesc}
+
+\begin{funcdesc}{putch}{char}
+  Print the character \var{char} to the console without buffering.
+\end{funcdesc}
+
+\begin{funcdesc}{ungetch}{char}
+  Cause the character \var{char} to be ``pushed back'' into the
+  console buffer; it will be the next character read by
+  \function{getch()} or \function{getche()}.
+\end{funcdesc}
+
+
+\subsection{Other Functions \label{msvcrt-other}}
+
+\begin{funcdesc}{heapmin}{}
+  Force the \cfunction{malloc()} heap to clean itself up and return
+  unused blocks to the operating system.  This only works on Windows
+  NT.  On failure, this raises \exception{IOError}.
+\end{funcdesc}

Doc/lib/libundoc.tex

@@ -274,16 +274,3 @@ The following are SGI specific:
 --- Interface to the ``simple video'' board on SGI Indigo
 (obsolete hardware).
 \end{description}
-
-The following are Windows specific:
-
-\begin{description}
-\item[msvcrtmodule.c]
-(in directory \file{PC/}) --- define a number of Windows
-specific goodies like \function{khbit()}, \function{getch()} and
-\function{setmode()}.  (Windows 95 and NT only.)
-
-\item[winsound.c]
---- Define \function{play()} and \function{stop()} operations for
-controlling audio playback on Windows.
-\end{description}

Doc/lib/libwinsound.tex

@@ -0,0 +1,66 @@
+\section{\module{winsound} ---
+         Sound-playing interface for Windows}
+
+\declaremodule{builtin}{winsound}
+\modulesynopsis{Access to the sound-playing machinery for Windows.}
+\moduleauthor{Toby Dickenson}{htrd90@zepler.org}
+\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
+
+
+The \module{winsound} module provides access to the basic
+sound-playing machinery provided by Windows platforms.  It includes a
+single function and several constants.
+
+
+\begin{funcdesc}{PlaySound}{sound, flags}
+  Call the underlying \cfunction{PlaySound()} function from the
+  Platform API.  The \var{sound} parameter may be a filename, audio
+  data as a string, or \code{None}.  Its interpretation depends on the
+  value of \var{flags}, which can be a bit-wise ORed combination of
+  the constants described below.  If the system indicates an error,
+  \exception{RuntimeError} is raised.
+\end{funcdesc}
+
+
+\begin{datadesc}{SND_FILENAME}
+  The \var{sound} parameter is the name of a WAV file.
+\end{datadesc}
+
+\begin{datadesc}{SND_ALIAS}
+  The \var{sound} parameter should be interpreted as a control panel
+  sound association name.
+\end{datadesc}
+
+\begin{datadesc}{SND_LOOP}
+  Play the sound repeatedly.  The \constant{SND_ASYNC} flag must also
+  be used to avoid blocking.
+\end{datadesc}
+
+\begin{datadesc}{SND_MEMORY}
+  The \var{sound} parameter to \function{PlaySound()} is a memory
+  image of a WAV file.
+
+  \strong{Note:}  This module does not support playing from a memory
+  image asynchonously, so a combination of this flag and
+  \constant{SND_ASYNC} will raise a \exception{RuntimeError}.
+\end{datadesc}
+
+\begin{datadesc}{SND_PURGE}
+  Stop playing all instances of the specified sound.
+\end{datadesc}
+
+\begin{datadesc}{SND_ASYNC}
+  Return immediately, allowing sounds to play asynchronously.
+\end{datadesc}
+
+\begin{datadesc}{SND_NODEFAULT}
+  If the specified sound cannot be found, do not play a default beep.
+\end{datadesc}
+
+\begin{datadesc}{SND_NOSTOP}
+  Do not interrupt sounds currently playing.
+\end{datadesc}
+
+\begin{datadesc}{SND_NOWAIT}
+  Return immediately if the sound driver is busy.
+\end{datadesc}

Doc/lib/windows.tex

@@ -0,0 +1,8 @@
+\chapter{MS Windows Specific Modules}
+
+
+This chapter describes modules that are only available on MS Windows
+platforms.
+
+
+\localmoduletable