Initial checkin of docs for Lib/platform.py .
Closes patch #785752 and bug #726911.
Should be backported after correctness and such has been verified by Fred.
diff --git a/Doc/lib/libplatform.tex b/Doc/lib/libplatform.tex
new file mode 100644
index 0000000..3c78eb5
--- /dev/null
+++ b/Doc/lib/libplatform.tex
@@ -0,0 +1,223 @@
+\section{\module{platform} ---
+ Access to underlying platform's identifying data.}
+
+\declaremodule{standard}{platform}
+\modulesynopsis{Retrieves as much platform identifying data as possible.}
+\moduleauthor{Marc-Andre Lemburg}{mal@egenix.com}
+\sectionauthor{Bjorn Pettersen}{bpettersen@corp.fairisaac.com}
+
+\versionadded{2.3}
+
+\begin{notice}[note]
+ Specific platforms listed alphabetically, with Linux included in the \UNIX
+ section.
+\end{notice}
+
+\subsection{Cross Platform}
+
+\begin{funcdesc}{architecture}{executable=sys.executable, bits='', linkage=''}
+ Queries the given executable (defaults to the Python interpreter
+ binary) for various architecture informations.
+
+ Returns a tuple \code{(bits, linkage)} which contain information about
+ the bit architecture and the linkage format used for the
+ executable. Both values are returned as strings.
+
+ Values that cannot be determined are returned as given by the
+ parameter presets. If bits is given as \code{''}, the
+ \cfunction{sizeof(pointer)}
+ (or \cfunction{sizeof(long)} on Python version < 1.5.2) is used as
+ indicator for the supported pointer size.
+
+ The function relies on the system's \file{file} command to do the
+ actual work. This is available on most if not all \UNIX{}
+ platforms and some non-\UNIX{} platforms and then only if the
+ executable points to the Python interpreter. Reasonable defaults
+ are used when the above needs are not met.
+\end{funcdesc}
+
+\begin{funcdesc}{machine}{}
+ Returns the machine type, e.g. \code{'i386'}.
+
+ An empty string is returned if the value cannot be determined.
+\end{funcdesc}
+
+\begin{funcdesc}{node}{}
+ Returns the computer's network name (may not be fully qualified!)
+
+ An empty string is returned if the value cannot be determined.
+\end{funcdesc}
+
+\begin{funcdesc}{platform}{aliased=0, terse=0}
+ Returns a single string identifying the underlying platform
+ with as much useful information as possible.
+
+ The output is intended to be \emph{human readable} rather than
+ machine parseable. It may look different on different
+ platforms and this is intended.
+
+ If \code{aliased} is true, the function will use aliases for
+ various platforms that report system names which differ from
+ their common names, e.g. SunOS will be reported as
+ Solaris. The \function{system_alias()} function is used to implement
+ this.
+
+ Setting terse to true causes the function to return only the
+ absolute minimum information needed to identify the platform.
+\end{funcdesc}
+
+
+\begin{funcdesc}{processor}{}
+ Returns the (real) processor name, e.g. 'amdk6'
+
+ An empty string is returned if the value cannot be
+ determined. Note that many platforms do not provide this
+ information or simply return the same value as for \function{machine()},
+ e.g. NetBSD does this.
+\end{funcdesc}
+
+\begin{funcdesc}{python_build}{}
+ Returns a tuple \code{(buildno, builddate)} stating the Python
+ build number and date as strings.
+\end{funcdesc}
+
+\begin{funcdesc}{python_compiler}{}
+ Returns a string identifying the compiler used for compiling
+ Python.
+\end{funcdesc}
+
+\begin{funcdesc}{python_version}{}
+ Returns the Python version as string \code{'major.minor.patchlevel'}
+
+ Note that unlike the Python \code{sys.version}, the returned value
+ will always include the patchlevel (it defaults to 0).
+\end{funcdesc}
+
+\begin{funcdesc}{python_version_tuple}{}
+ Returns the Python version as tuple \code{(major, minor, patchlevel)}
+ of strings.
+
+ Note that unlike the Python \code{sys.version}, the returned value
+ will always include the patchlevel (it defaults to 0).
+\end{funcdesc}
+
+\begin{funcdesc}{release}{}
+ Returns the system's release, e.g. \code{'2.2.0'} or \code{'NT'}
+
+ An empty string is returned if the value cannot be determined.
+\end{funcdesc}
+
+\begin{funcdesc}{system}{}
+ Returns the system/OS name, e.g. \code{'Linux'}, \code{'Windows'}, or \code{'Java'}.
+
+ An empty string is returned if the value cannot be determined.
+\end{funcdesc}
+
+\begin{funcdesc}{system_alias}{system, release, version}
+ Returns \code{(system, release, version)} aliased to common
+ marketing names used for some systems.
+
+ It also does some reordering of the information in some cases
+ where it would otherwise cause confusion.
+\end{funcdesc}
+
+\begin{funcdesc}{version}{}
+ Returns the system's release version, e.g. \code{'#3 on degas'}.
+
+ An empty string is returned if the value cannot be determined.
+\end{funcdesc}
+
+\begin{funcdesc}{uname}{}
+ Fairly portable uname interface. Returns a tuple
+ of strings \code{(system, node, release, version, machine, processor)}
+ identifying the underlying platform.
+
+ Note that unlike the \function{os.uname()} function this also returns
+ possible processor information as additional tuple entry.
+
+ Entries which cannot be determined are set to \code{''}.
+\end{funcdesc}
+
+\subsection{Java Platform}
+
+\begin{funcdesc}{java_ver}{release='', vendor='', vminfo=('','',''), osinfo=('','','')}
+ Version interface for JPython.
+
+ Returns a tuple \code{(release, vendor, vminfo, osinfo)} with vminfo being
+ a tuple \code{(vm_name, vm_release, vm_vendor)} and osinfo being a
+ tuple \code{(os_name, os_version, os_arch)}.
+
+ Values which cannot be determined are set to the defaults
+ given as parameters (which all default to \code{''}).
+\end{funcdesc}
+
+\subsection{Windows Platform}
+
+\begin{funcdesc}{win32_ver}{release='', version='', csd='', ptype=''}
+ Get additional version information from the Windows Registry
+ and return a tuple \code{(version, csd, ptype)} referring to version
+ number, CSD level and OS type (multi/single processor).
+
+ As a hint: ptype returns \code{'Uniprocessor Free'} on single
+ processor NT machines and \code{'Multiprocessor Free'} on multi
+ processor machines. The \emph{'Free'} refers to the OS version being
+ free of debugging code. It could also state \emph{'Checked'} which
+ means the OS version uses debugging code, i.e. code that
+ checks arguments, ranges, etc.
+
+\begin{notice}[note]
+ This function only works if Mark Hammond's \module{win32all}
+ package is installed and (obviously) only runs on Win32
+ compatible platforms.
+\end{notice}
+
+\end{funcdesc}
+
+\subsubsection{Win95/98 specific}
+
+\begin{funcdesc}{popen}{cmd, mode='r', bufsize=None}
+ Portable \function{popen()} interface.
+ Find a working popen implementation preferring \function{win32pipe.popen}.
+ On NT \function{win32pipe} should work; on Win9x
+ it hangs due to bugs in the MS C lib.
+ \seetext{MS KnowledgeBase article Q150956.}
+\end{funcdesc}
+
+
+\subsection{Mac Platform}
+
+\begin{funcdesc}{mac_ver}{release='', versioninfo=('','',''), machine=''}
+ Get MacOS version information and return it as tuple \code{(release,
+ versioninfo, machine)} with versioninfo being a tuple \code{(version,
+ dev_stage, non_release_version)}.
+
+ Entries which cannot be determined are set to \code{''}. All tuple
+ entries are strings.
+
+ Documentation for the underlying gestalt() API is available online
+ at \url{http://www.rgaros.nl/gestalt/}
+\end{funcdesc}
+
+\subsection{\UNIX{} Platforms}
+
+\begin{funcdesc}{dist}{distname='',version='',id='',supported_dists=('SuSE','debian','redhat','mandrake')}
+ Tries to determine the name of the OS distribution name
+
+ Returns a tuple \code{(distname, version, id)} which defaults to the
+ args given as parameters.
+\end{funcdesc}
+
+
+\begin{funcdesc}{libc_ver}{executable=sys.executable, lib='', version='', chunksize=2048}
+ Tries to determine the libc version against which the
+ file executable (defaults to the Python interpreter) is linked.
+
+ Returns a tuple of strings \code{(lib, version)} which default to the
+ given parameters in case the lookup fails.
+
+ Note that the function has intimate knowledge of how different
+ libc versions add symbols to the executable is probably only
+ useable for executables compiled using \emph{gcc}.
+
+ The file is read and scanned in chunks of chunksize bytes.
+\end{funcdesc}