- 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

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.
-\end{funcdesc}
+  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.
-
-\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}
+  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).
 
+  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})}.
+
+  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/}
+  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.
-
-  Returns a tuple of strings \code{(lib, version)} which default to the
-  given parameters in case the lookup fails.
+\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.
 
-  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}