- make this section format
- start cleaning up the markup for consistency
- comment out the reference to a MS KnowledgeBase article that doesn't
seem to be present at msdn.microsoft.com; hopefully someone can
point out an alternate source for the relevant information
diff --git a/Doc/lib/libplatform.tex b/Doc/lib/libplatform.tex
index 3c78eb5..029c632 100644
--- a/Doc/lib/libplatform.tex
+++ b/Doc/lib/libplatform.tex
@@ -8,9 +8,9 @@
\versionadded{2.3}
-\begin{notice}[note]
- Specific platforms listed alphabetically, with Linux included in the \UNIX
- section.
+\begin{notice}
+ Specific platforms listed alphabetically, with Linux included in the
+ \UNIX{} section.
\end{notice}
\subsection{Cross Platform}
@@ -38,52 +38,46 @@
\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!)
-
+ 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.
+ 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 \var{aliased} is true, the function will use aliases for various
+ platforms that report system names which differ from their common
+ names, for example SunOS will be reported as Solaris. The
+ \function{system_alias()} function is used to implement this.
+
+ Setting \var{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'
+ Returns the (real) processor name, e.g. \code{'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.
+ 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()}. NetBSD does this.
\end{funcdesc}
\begin{funcdesc}{python_build}{}
- Returns a tuple \code{(buildno, builddate)} stating the Python
- build number and date as strings.
+ Returns a tuple \code{(\var{buildno}, \var{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.
+ Returns a string identifying the compiler used for compiling Python.
\end{funcdesc}
\begin{funcdesc}{python_version}{}
@@ -94,43 +88,41 @@
\end{funcdesc}
\begin{funcdesc}{python_version_tuple}{}
- Returns the Python version as tuple \code{(major, minor, patchlevel)}
- of strings.
+ Returns the Python version as tuple \code{(\var{major}, \var{minor},
+ \var{patchlevel})} of strings.
Note that unlike the Python \code{sys.version}, the returned value
- will always include the patchlevel (it defaults to 0).
+ will always include the patchlevel (it defaults to \code{'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'}.
-
+ 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.
+ Returns \code{(\var{system}, \var{release}, \var{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'}.
-
+ 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.
+ Fairly portable uname interface. Returns a tuple of strings
+ \code{(\var{system}, \var{node}, \var{release}, \var{version},
+ \var{machine}, \var{processor})} identifying the underlying
+ platform.
Note that unlike the \function{os.uname()} function this also returns
possible processor information as additional tuple entry.
@@ -138,86 +130,92 @@
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{''}).
+\begin{funcdesc}{java_ver}{release='', vendor='', vminfo=('','',''),
+ osinfo=('','','')}
+ Version interface for JPython.
+
+ Returns a tuple \code{(\var{release}, \var{vendor}, \var{vminfo},
+ \var{osinfo})} with \var{vminfo} being a tuple \code{(\var{vm_name},
+ \var{vm_release}, \var{vm_vendor})} and \var{osinfo} being a tuple
+ \code{(\var{os_name}, \var{os_version}, \var{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.
+ Get additional version information from the Windows Registry
+ and return a tuple \code{(\var{version}, \var{csd}, \var{ptype})}
+ referring to version number, CSD level and OS type (multi/single
+ processor).
-\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}
+ As a hint: \var{ptype} is \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.}
+ Portable \function{popen()} interface. Find a working popen
+ implementation preferring \function{win32pipe.popen()}. On Windows
+ NT, \function{win32pipe.popen()} should work; on Windows 9x it hangs
+ due to bugs in the MS C library.
+ % This KnowledgeBase article appears to be missing...
+ %See also \ulink{MS KnowledgeBase article Q150956}{}.
\end{funcdesc}
-\subsection{Mac Platform}
+\subsection{Mac OS 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.
+ Get Mac OS version information and return it as tuple
+ \code{(\var{release}, \var{versioninfo}, \var{machine})} with
+ \var{versioninfo} being a tuple \code{(\var{version},
+ \var{dev_stage}, \var{non_release_version})}.
- Documentation for the underlying gestalt() API is available online
- at \url{http://www.rgaros.nl/gestalt/}
+ Entries which cannot be determined are set to \code{''}. All tuple
+ entries are strings.
+
+ Documentation for the underlying \cfunction{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.
+\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{(\var{distname}, \var{version}, \var{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.
+\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{(\var{lib}, \var{version})} which default
+ to the given parameters in case the lookup fails.
- 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
+ Note that this function has intimate knowledge of how different
libc versions add symbols to the executable is probably only
- useable for executables compiled using \emph{gcc}.
+ useable for executables compiled using \program{gcc}.
- The file is read and scanned in chunks of chunksize bytes.
+ The file is read and scanned in chunks of \var{chunksize} bytes.
\end{funcdesc}