Fixed tons of small markup problems.

freddrake · freddrake · commit bf5a6d2eb466 · 1999-03-12T19:57:38.000Z
diff --git a/Doc/lib/libthreading.tex b/Doc/lib/libthreading.tex
@@ -1,8 +1,8 @@
 \section{\module{threading} ---
-         Higher-level threading interfaces.}
-\declaremodule{standard}{threading}
+         Higher-level threading interface}
 
-\modulesynopsis{Higher-level threading interfaces.}
+\declaremodule{standard}{threading}
+\modulesynopsis{Higher-level threading interface.}
 
 
 This module constructs higher-level threading interfaces on top of the 
@@ -85,7 +85,8 @@ \section{\module{threading} ---
 
 All of the methods described below are executed atomically.
 
-\subsection{Lock Objects}
+
+\subsection{Lock Objects \label{lock-objects}}
 
 A primitive lock is a synchronization primitive that is not owned
 by a particular thread when locked.  In Python, it is currently
@@ -109,7 +110,7 @@ \subsection{Lock Objects}
 
 All methods are executed atomically.
 
-\begin{methoddesc}{acquire}{blocking=1}
+\begin{methoddesc}{acquire}{\optional{blocking\code{ = 1}}}
 Acquire a lock, blocking or non-blocking.
 
 When invoked without arguments, block until the lock is
@@ -137,7 +138,8 @@ \subsection{Lock Objects}
 There is no return value.
 \end{methoddesc}
 
-\subsection{RLock Objects}
+
+\subsection{RLock Objects \label{rlock-objects}}
 
 A reentrant lock is a synchronization primitive that may be
 acquired multiple times by the same thread.  Internally, it uses
@@ -153,7 +155,7 @@ \subsection{RLock Objects}
 outermost pair) resets the lock to unlocked and allows another
 thread blocked in \method{acquire()} to proceed.
 
-\begin{methoddesc}{acquire}{blocking=1}
+\begin{methoddesc}{acquire}{\optional{blocking\code{ = 1}}}
 Acquire a lock, blocking or non-blocking.
 
 When invoked without arguments: if this thread already owns
@@ -189,7 +191,8 @@ \subsection{RLock Objects}
 There is no return value.
 \end{methoddesc}
 
-\subsection{Condition Objects}
+
+\subsection{Condition Objects \label{condition-objects}}
 
 A condition variable is always associated with some kind of lock;
 this can be passed in or one will be created by default.  (Passing
@@ -248,11 +251,11 @@ \subsection{Condition Objects}
 adding one item to the buffer only needs to wake up one consumer
 thread.
 
-\begin{classdesc}{Condition}{lock=None}
-If the \var{lock} argument is given and not \code{None}, it must be a \class{Lock}
-or \class{RLock} object, and it is used as the underlying lock.
-Otherwise, a new \class{RLock} object is created and used as the
-underlying lock.
+\begin{classdesc}{Condition}{\optional{lock}}
+If the \var{lock} argument is given and not \code{None}, it must be a
+\class{Lock} or \class{RLock} object, and it is used as the underlying
+lock.  Otherwise, a new \class{RLock} object is created and used as
+the underlying lock.
 \end{classdesc}
 
 \begin{methoddesc}{acquire}{*args}
@@ -267,7 +270,7 @@ \subsection{Condition Objects}
 lock; there is no return value.
 \end{methoddesc}
 
-\begin{methoddesc}{wait}{timeout=None}
+\begin{methoddesc}{wait}{\optional{timeout}}
 Wait until notified or until a timeout occurs.
 This must only be called when the calling thread has acquired the
 lock.
@@ -278,17 +281,17 @@ \subsection{Condition Objects}
 timeout occurs.  Once awakened or timed out, it re-acquires the lock
 and returns.
 
-When the timeout argument is present and not \code{None}, it should be a
-floating point number specifying a timeout for the operation in
-seconds (or fractions thereof).
+When the \var{timeout} argument is present and not \code{None}, it
+should be a floating point number specifying a timeout for the
+operation in seconds (or fractions thereof).
 
-When the underlying lock is an \class{RLock}, it is not released using its
-\method{release()} method, since this may not actually unlock the lock
-when it was acquired multiple times recursively.  Instead, an
-internal interface of the \class{RLock} class is used, which really unlocks it
-even when it has been recursively acquired several times.  Another
-internal interface is then used to restore the recursion level when
-the lock is reacquired.
+When the underlying lock is an \class{RLock}, it is not released using
+its \method{release()} method, since this may not actually unlock the
+lock when it was acquired multiple times recursively.  Instead, an
+internal interface of the \class{RLock} class is used, which really
+unlocks it even when it has been recursively acquired several times.
+Another internal interface is then used to restore the recursion level
+when the lock is reacquired.
 \end{methoddesc}
 
 \begin{methoddesc}{notify}{}
@@ -314,25 +317,26 @@ \subsection{Condition Objects}
 \method{notify()}, but wakes up all waiting threads instead of one.
 \end{methoddesc}
 
-\subsection{Semaphore Objects}
+
+\subsection{Semaphore Objects \label{semaphore-objects}}
 
 This is one of the oldest synchronization primitives in the history of
 computer science, invented by the early Dutch computer scientist
-Edsger W. Dijkstra (he used \method{P()} and \method{V()} instead of \method{acquire()}
-and \method{release()}).
+Edsger W. Dijkstra (he used \method{P()} and \method{V()} instead of
+\method{acquire()} and \method{release()}).
 
 A semaphore manages an internal counter which is decremented by each
 \method{acquire()} call and incremented by each \method{release()}
 call.  The counter can never go below zero; when \method{acquire()}
 finds that it is zero, it blocks, waiting until some other thread
 calls \method{release()}.
 
-\begin{classdesc}{Semaphore}{value=1}
+\begin{classdesc}{Semaphore}{\optional{value}}
 The optional argument gives the initial value for the internal
-counter; it defaults to 1.
+counter; it defaults to \code{1}.
 \end{classdesc}
 
-\begin{methoddesc}{acquire}{blocking=1}
+\begin{methoddesc}{acquire}{\optional{blocking}}
 Acquire a semaphore.
 
 When invoked without arguments: if the internal counter is larger than
@@ -345,13 +349,13 @@ \subsection{Semaphore Objects}
 threads are awakened should not be relied on.  There is no return
 value in this case.
 
-When invoked with the \var{blocking} argument set to true, do the same
-thing as when called without arguments, and return true.
+When invoked with \var{blocking} set to true, do the same thing as
+when called without arguments, and return true.
 
-When invoked with the \var{blocking} argument set to false, do not
-block.  If a call without an argument would block, return false
-immediately; otherwise, do the same thing as when called without
-arguments, and return true.
+When invoked with \var{blocking} set to false, do not block.  If a
+call without an argument would block, return false immediately;
+otherwise, do the same thing as when called without arguments, and
+return true.
 \end{methoddesc}
 
 \begin{methoddesc}{release}{}
@@ -361,7 +365,8 @@ \subsection{Semaphore Objects}
 than zero again, wake up that thread.
 \end{methoddesc}
 
-\subsection{Event Objects}
+
+\subsection{Event Objects \label{event-objects}}
 
 This is one of the simplest mechanisms for communication between
 threads: one thread signals an event and one or more other thread
@@ -393,7 +398,7 @@ \subsection{Event Objects}
 called to set the internal flag to true again.
 \end{methoddesc}
 
-\begin{methoddesc}{wait}{timeout=None}
+\begin{methoddesc}{wait}{\optional{timeout}}
 Block until the internal flag is true.
 If the internal flag is true on entry, return immediately.  Otherwise,
 block until another thread calls \method{set()} to set the flag to
@@ -404,41 +409,42 @@ \subsection{Event Objects}
 seconds (or fractions thereof).
 \end{methoddesc}
 
-\subsection{Thread Objects}
+
+\subsection{Thread Objects \label{thread-objects}}
 
 This class represents an activity that is run in a separate thread
 of control.  There are two ways to specify the activity: by
 passing a callable object to the constructor, or by overriding the
 \method{run()} method in a subclass.  No other methods (except for the
 constructor) should be overridden in a subclass.  In other words, 
-\emph{only}  override the \method{__init__()} and \method{run()} methods of this class.
-
+\emph{only}  override the \method{__init__()} and \method{run()}
+methods of this class.
 
 Once a thread object is created, its activity must be started by
-calling the thread's \method{start()} method.  This invokes the \method{run()}
-method in a separate thread of control.
+calling the thread's \method{start()} method.  This invokes the
+\method{run()} method in a separate thread of control.
 
 Once the thread's activity is started, the thread is considered
 'alive' and 'active' (these concepts are almost, but not quite
 exactly, the same; their definition is intentionally somewhat
-vague).  It stops being alive and active when its \method{run()} method
-terminates -- either normally, or by raising an unhandled
+vague).  It stops being alive and active when its \method{run()}
+method terminates -- either normally, or by raising an unhandled
 exception.  The \method{isAlive()} method tests whether the thread is
 alive.
 
-Other threads can call a thread's \method{join()} method.  This blocks the
-calling thread until the thread whose \method{join()} method is called
-is terminated.
+Other threads can call a thread's \method{join()} method.  This blocks
+the calling thread until the thread whose \method{join()} method is
+called is terminated.
 
 A thread has a name.  The name can be passed to the constructor,
-set with the \method{setName()} method, and retrieved with the \method{getName()}
-method.
+set with the \method{setName()} method, and retrieved with the
+\method{getName()} method.
 
 A thread can be flagged as a ``daemon thread''.  The significance
 of this flag is that the entire Python program exits when only
 daemon threads are left.  The initial value is inherited from the
-creating thread.  The flag can be set with the \method{setDaemon()} method
-and retrieved with the \method{getDaemon()} method.
+creating thread.  The flag can be set with the \method{setDaemon()}
+method and retrieved with the \method{getDaemon()} method.
 
 There is a ``main thread'' object; this corresponds to the
 initial thread of control in the Python program.  It is not a
@@ -449,38 +455,37 @@ \subsection{Thread Objects}
 threads''.  These are threads of control started outside the
 threading module, e.g. directly from C code.  Dummy thread objects
 have limited functionality; they are always considered alive,
-active, and daemonic, and cannot be \method{join()}ed.  They are never
+active, and daemonic, and cannot be \method{join()}ed.  They are never 
 deleted, since it is impossible to detect the termination of alien
 threads.
 
 
 \begin{classdesc}{Thread}{group=None, target=None, name=None,
- args=(), kwargs={}}
+                          args=(), kwargs=\{\}}
 This constructor should always be called with keyword
 arguments.  Arguments are:
 
-group
-Should be None; reserved for future extension when a
-ThreadGroup class is implemented.
+\var{group}
+Should be \code{None}; reserved for future extension when a
+\class{ThreadGroup} class is implemented.
 
-target
+\var{target}
 Callable object to be invoked by the \method{run()} method.
-Defaults to None, meaning nothing is called.
+Defaults to \code{None}, meaning nothing is called.
 
-name
-The thread name.  By default, a unique name is constructed
-of the form ``Thread-N'' where N is a small decimal
-number.
+\var{name}
+The thread name.  By default, a unique name is constructed of the form
+``Thread-\var{N}'' where \var{N} is a small decimal number.
 
-args
-Argument tuple for the target invocation.  Defaults to ().
+\var{args}
+Argument tuple for the target invocation.  Defaults to \code{()}.
 
-kwargs
+\var{kwargs}
 Keyword argument dictionary for the target invocation.
-Defaults to {}.
+Defaults to \code{\{\}}.
 
 If the subclass overrides the constructor, it must make sure
-to invoke the base class constructor (Thread.__init__())
+to invoke the base class constructor (\code{Thread.__init__()})
 before doing anything else to the thread.
 \end{classdesc}
 
@@ -507,7 +512,7 @@ \subsection{Thread Objects}
 \end{methoddesc}
 
 
-\begin{methoddesc}{join}{timeout=None}
+\begin{methoddesc}{join}{\optional{timeout}}
 Wait until the thread terminates.
 This blocks the calling thread until the thread whose \method{join()}
 method is called terminates -- either normally or through an
