Lots of small markup adjustments.

freddrake · freddrake · commit fcd845a7edba · 2003-04-09T04:06:37.000Z
diff --git a/Doc/lib/libhotshot.tex b/Doc/lib/libhotshot.tex
@@ -2,31 +2,31 @@ \section{\module{hotshot} ---
          High performance logging profiler}
 
 \declaremodule{standard}{hotshot}
+\modulesynopsis{High performance logging profiler, mostly written in C.}
 \moduleauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
 \sectionauthor{Anthony Baxter}{anthony@interlink.com.au}
 
-
 \versionadded{2.2}
 
-\modulesynopsis{High performance logging profiler, mostly written in C.}
 
-
-This module provides a nicer interface to the \code{_hotshot} C module.
+This module provides a nicer interface to the \module{_hotshot} C module.
 Hotshot is a replacement for the existing \refmodule{profile} module. As it's
-written mostly in C, it should result in a much smaller performance impact 
-than the existing profile module.
-
-\begin{classdesc}{Profile}{logfile, \optional{, lineevents=0, linetimings=1}}
-
-The profiler object. The argument \var{logfile} is the name of a log file
-to use for logged profile data. The argument \var{lineevents} specifies whether
-to generate events for every source line, or just on function call/return. It
-defaults to 0 (only log function call/return). The argument \var{linetimings}
-specifies whether to record timing information. It defaults to 1 (store timing
+written mostly in C, it should result in a much smaller performance impact
+than the existing \refmodule{profile} module.
+
+\begin{classdesc}{Profile}{logfile\optional{,
+                           lineevents\code{=0}\optional{,
+                           linetimings\code{=1}}}}
+The profiler object. The argument \var{logfile} is the name of a log
+file to use for logged profile data. The argument \var{lineevents}
+specifies whether to generate events for every source line, or just on
+function call/return. It defaults to \code{0} (only log function
+call/return). The argument \var{linetimings} specifies whether to
+record timing information. It defaults to \code{1} (store timing
 information).
-
 \end{classdesc}
 
+
 \subsection{Profile Objects \label{hotshot-objects}}
 
 Profile objects have the following methods:
@@ -38,22 +38,19 @@ \subsection{Profile Objects \label{hotshot-objects}}
 \begin{methoddesc}{close}{}
 Close the logfile and terminate the profiler.
 \end{methoddesc}
- 
-%
+
 \begin{methoddesc}{fileno}{}
 Return the file descriptor of the profiler's log file.
 \end{methoddesc}
 
 \begin{methoddesc}{run}{cmd}
-Profile an exec-compatible string in the script environment.
-
-The globals from the \module{__main__} module are used as 
+Profile an \keyword{exec}-compatible string in the script environment.
+The globals from the \refmodule[main]{__main__} module are used as
 both the globals and locals for the script.
 \end{methoddesc}
 
 \begin{methoddesc}{runcall}{func, *args, **keywords}
 Profile a single call of a callable.
-
 Additional positional and keyword arguments may be passed
 along; the result of the call is returned, and exceptions are
 allowed to propogate cleanly, while ensuring that profiling is
@@ -62,8 +59,7 @@ \subsection{Profile Objects \label{hotshot-objects}}
 
 
 \begin{methoddesc}{runctx}{cmd, globals, locals}
-Evaluate an exec-compatible string in a specific environment.
-
+Evaluate an \keyword{exec}-compatible string in a specific environment.
 The string is compiled before profiling begins.
 \end{methoddesc}
 
@@ -75,32 +71,33 @@ \subsection{Profile Objects \label{hotshot-objects}}
 Stop the profiler.
 \end{methoddesc}
 
+
 \subsection{Using hotshot data}
-\declaremodule{standard}{hotshot.stats}
 
+\declaremodule{standard}{hotshot.stats}
 \modulesynopsis{Statistical analysis for Hotshot}
 
 \versionadded{2.2}
 
-This module loads hotshot profiling data into the standard \module{pstats} 
+This module loads hotshot profiling data into the standard \module{pstats}
 Stats objects.
 
 \begin{funcdesc}{load}{filename}
-Load hotshot data from \var{filename}. Returns an instance 
+Load hotshot data from \var{filename}. Returns an instance
 of the \class{pstats.Stats} class.
 \end{funcdesc}
 
 \begin{seealso}
-  \seemodule{profile}{The profile module's \class{Stats} class }
+  \seemodule{profile}{The \module{profile} module's \class{Stats} class}
 \end{seealso}
 
+
 \subsection{Example Usage \label{hotshot-example}}
 
-Note that this example runs the python "benchmark" pystones. It can
+Note that this example runs the python ``benchmark'' pystones.  It can
 take some time to run, and will produce large output files.
 
 \begin{verbatim}
-
 >>> import hotshot, hotshot.stats, test.pystone
 >>> prof = hotshot.Profile("stones.prof")
 >>> benchtime, stones = prof.runcall(test.pystone.pystones)
@@ -120,7 +117,4 @@ \subsection{Example Usage \label{hotshot-example}}
  .
  .
  .
-
 \end{verbatim}
-
-
diff --git a/Doc/lib/libtimeit.tex b/Doc/lib/libtimeit.tex
@@ -4,36 +4,36 @@ \section{\module{timeit} ---
 \declaremodule{standard}{timeit}
 \modulesynopsis{Measure the execution time of small code snippets.}
 
+\versionadded{2.3}
 \index{Benchmarking}
 \index{Performance}
 
-\versionadded{2.3}
-
-This module provides a simple way to time small bits of Python code.  It has
-both command line as well as callable interfaces.  It avoids a number of
-common traps for measuring execution times.  See also Tim Peters'
-introduction to the Algorithms chapter in the ``Python Cookbook'', published
-by O'Reilly.
+This module provides a simple way to time small bits of Python code.
+It has both command line as well as callable interfaces.  It avoids a
+number of common traps for measuring execution times.  See also Tim
+Peters' introduction to the ``Algorithms'' chapter in the
+\citetitle{Python Cookbook}, published by O'Reilly.
 
-The module interface defines the following public class:
+The module defines the following public class:
 
-\begin{classdesc}{Timer}{\optional{stmt='pass'
-			 \optional{, setup='pass'
-			 \optional{, timer=<timer function>}}}}
+\begin{classdesc}{Timer}{\optional{stmt=\code{'pass'}
+                         \optional{, setup=\code{'pass'}
+                         \optional{, timer=<timer function>}}}}
 Class for timing execution speed of small code snippets.
 
-The constructor takes a statement to be timed, an additional statement used
-for setup, and a timer function.  Both statements default to 'pass'; the
-timer function is platform-dependent (see the module doc string).
+The constructor takes a statement to be timed, an additional statement
+used for setup, and a timer function.  Both statements default to
+\code{'pass'}; the timer function is platform-dependent (see the
+module doc string).  The statements may contain newlines, as long as
+they don't contain multi-line string literals.
 
-To measure the execution time of the first statement, use the timeit()
-method.  The repeat() method is a convenience to call timeit() multiple
-times and return a list of results.
-
-The statements may contain newlines, as long as they don't contain
-multi-line string literals.
+To measure the execution time of the first statement, use the
+\method{timeit()} method.  The \method{repeat()} method is a
+convenience to call \method{timeit()} multiple times and return a list
+of results.
+\end{classdesc}
 
-\begin{methoddesc}{print_exc}{\optional{file=None}}
+\begin{methoddesc}{print_exc}{\optional{file=\constant{None}}}
 Helper to print a traceback from the timed code.
 
 Typical use:
@@ -48,20 +48,21 @@ \section{\module{timeit} ---
 
 The advantage over the standard traceback is that source lines in the
 compiled template will be displayed.
-
-The optional file argument directs where the traceback is sent; it defaults
-to \code{sys.stderr}.
+The optional \var{file} argument directs where the traceback is sent;
+it defaults to \code{sys.stderr}.
 \end{methoddesc}
 
-\begin{methoddesc}{repeat}{\optional{repeat=3\optional{, number=1000000}}}
+\begin{methoddesc}{repeat}{\optional{repeat\code{=3}\optional{,
+                           number\code{=1000000}}}}
 Call \method{timeit()} a few times.
 
-This is a convenience function that calls the \method{timeit()} repeatedly,
-returning a list of results.  The first argument specifies how many times to
-call \function{timeit()}.  The second argument specifies the \code{number}
-argument for \function{timeit()}.
+This is a convenience function that calls the \method{timeit()}
+repeatedly, returning a list of results.  The first argument specifies
+how many times to call \method{timeit()}.  The second argument
+specifies the \var{number} argument for \function{timeit()}.
 
-Note: it's tempting to calculate mean and standard deviation from the result
+\begin{notice}
+It's tempting to calculate mean and standard deviation from the result
 vector and report these.  However, this is not very useful.  In a typical
 case, the lowest value gives a lower bound for how fast your machine can run
 the given code snippet; higher values in the result vector are typically not
@@ -70,25 +71,26 @@ \section{\module{timeit} ---
 probably the only number you should be interested in.  After that, you
 should look at the entire vector and apply common sense rather than
 statistics.
+\end{notice}
 \end{methoddesc}
 
-\begin{methoddesc}{timeit}{\optional{number=1000000}}
-Time \code{number} executions of the main statement.
-
-To be precise, this executes the setup statement once, and then returns the
-time it takes to execute the main statement a number of times, as a float
-measured in seconds.  The argument is the number of times through the loop,
-defaulting to one million.  The main statement, the setup statement and the
-timer function to be used are passed to the constructor.
+\begin{methoddesc}{timeit}{\optional{number\code{=1000000}}}
+Time \var{number} executions of the main statement.
+This executes the setup statement once, and then
+returns the time it takes to execute the main statement a number of
+times, measured in seconds as a float.  The argument is the number of
+times through the loop, defaulting to one million.  The main
+statement, the setup statement and the timer function to be used are
+passed to the constructor.
 \end{methoddesc}
-\end{classdesc}
+
 
 \subsection{Command Line Interface}
 
 When called as a program from the command line, the following form is used:
 
 \begin{verbatim}
-    python timeit.py [-n N] [-r N] [-s S] [-t] [-c] [-h] [statement ...]
+python timeit.py [-n N] [-r N] [-s S] [-t] [-c] [-h] [statement ...]
 \end{verbatim}
 
 where the following options are understood:
@@ -97,65 +99,74 @@ \subsection{Command Line Interface}
 \item[-n N/--number=N] how many times to execute 'statement'
 \item[-r N/--repeat=N] how many times to repeat the timer (default 3)
 \item[-s S/--setup=S] statement to be executed once initially (default
-'pass')
-\item[-t/--time] use time.time() (default on all platforms but Windows)
-\item[-c/--clock] use time.clock() (default on Windows)
+\code{'pass'})
+\item[-t/--time] use \function{time.time()}
+(default on all platforms but Windows)
+\item[-c/--clock] use \function{time.clock()} (default on Windows)
 \item[-v/--verbose] print raw timing results; repeat for more digits
-precision 
+precision
 \item[-h/--help] print a short usage message and exit
 \end{description}
 
-A multi-line statement may be given by specifying each line as a separate
-statement argument; indented lines are possible by enclosing an argument in
-quotes and using leading spaces.  Multiple -s options are treated similarly.
-
-If -n is not given, a suitable number of loops is calculated by trying
-successive powers of 10 until the total time is at least 0.2 seconds.
-
-The default timer function is platform dependent.  On Windows, clock() has
-microsecond granularity but time()'s granularity is 1/60th of a second; on
-Unix, clock() has 1/100th of a second granularity and time() is much more
-precise.  On either platform, the default timer functions measures wall
-clock time, not the CPU time.  This means that other processes running on
-the same computer may interfere with the timing.  The best thing to do when
-accurate timing is necessary is to repeat the timing a few times and use the
-best time.  The -r option is good for this; the default of 3 repetitions is
-probably enough in most cases.  On Unix, you can use clock() to measure CPU
-time.
-
-Note: there is a certain baseline overhead associated with executing a pass
-statement.  The code here doesn't try to hide it, but you should be aware of
-it.  The baseline overhead can be measured by invoking the program without
-arguments.
-
-The baseline overhead differs between Python versions!  Also, to fairly
-compare older Python versions to Python 2.3, you may want to use python -O
-for the older versions to avoid timing SET_LINENO instructions.
+A multi-line statement may be given by specifying each line as a
+separate statement argument; indented lines are possible by enclosing
+an argument in quotes and using leading spaces.  Multiple
+\programopt{-s} options are treated similarly.
+
+If \programopt{-n} is not given, a suitable number of loops is
+calculated by trying successive powers of 10 until the total time is
+at least 0.2 seconds.
+
+The default timer function is platform dependent.  On Windows,
+\function{time.clock()} has microsecond granularity but
+\function{time.time()}'s granularity is 1/60th of a second; on \UNIX,
+\function{time.clock()} has 1/100th of a second granularity and
+\function{time.time()} is much more precise.  On either platform, the
+default timer functions measures wall clock time, not the CPU time.
+This means that other processes running on the same computer may
+interfere with the timing.  The best thing to do when accurate timing
+is necessary is to repeat the timing a few times and use the best
+time.  The \programopt{-r} option is good for this; the default of 3
+repetitions is probably enough in most cases.  On \UNIX, you can use
+\function{time.clock()} to measure CPU time.
+
+\begin{notice}
+  There is a certain baseline overhead associated with executing a
+  pass statement.  The code here doesn't try to hide it, but you
+  should be aware of it.  The baseline overhead can be measured by
+  invoking the program without arguments.
+\end{notice}
+
+The baseline overhead differs between Python versions!  Also, to
+fairly compare older Python versions to Python 2.3, you may want to
+use Python's \programopt{-O} option for the older versions to avoid
+timing \code{SET_LINENO} instructions.
 
 \subsection{Examples}
 
-Here are two example sessions (one using the command line, one using the
-module interface) that compare the cost of using \function{hasattr()}
-vs. try/except to test for missing and present object attributes.
+Here are two example sessions (one using the command line, one using
+the module interface) that compare the cost of using
+\function{hasattr()} vs. \keyword{try}/\keyword{except} to test for
+missing and present object attributes.
 
 \begin{verbatim}
-\% timeit.py 'try:' '  str.__nonzero__' 'except AttributeError:' '  pass'
+% timeit.py 'try:' '  str.__nonzero__' 'except AttributeError:' '  pass'
 100000 loops, best of 3: 15.7 usec per loop
-\% timeit.py 'if hasattr(str, "__nonzero__"): pass'
+% timeit.py 'if hasattr(str, "__nonzero__"): pass'
 100000 loops, best of 3: 4.26 usec per loop
-\% timeit.py 'try:' '  int.__nonzero__' 'except AttributeError:' '  pass'
+% timeit.py 'try:' '  int.__nonzero__' 'except AttributeError:' '  pass'
 1000000 loops, best of 3: 1.43 usec per loop
-\% timeit.py 'if hasattr(int, "__nonzero__"): pass'
+% timeit.py 'if hasattr(int, "__nonzero__"): pass'
 100000 loops, best of 3: 2.23 usec per loop
 \end{verbatim}
 
 \begin{verbatim}
 >>> import timeit
 >>> s = """\
 ... try:
-...   str.__nonzero__
+...     str.__nonzero__
 ... except AttributeError:
-...   pass
+...     pass
 ... """
 >>> t = timeit.Timer(stmt=s)
 >>> print "%.2f usec/pass" % (1000000 * t.timeit(number=100000)/100000)
@@ -168,9 +179,9 @@ \subsection{Examples}
 4.85 usec/pass
 >>> s = """\
 ... try:
-...   int.__nonzero__
+...     int.__nonzero__
 ... except AttributeError:
-...   pass 
+...     pass
 ... """
 >>> t = timeit.Timer(stmt=s)
 >>> print "%.2f usec/pass" % (1000000 * t.timeit(number=100000)/100000)
