Richard Wolff's changes:

pdb.doc		Updated to reflect better the various changes.

Lib/pdb.doc

@@ -1,5 +1,5 @@
-The Python Debugger
+The Python Debugger Pdb
-===================
+=======================
 
 To use the debugger in its simplest form:
 
@@ -24,8 +24,8 @@ that 'help' can be typed as 'h' or 'help' (but not as 'he' or 'hel',
 nor as 'H' or 'Help' or 'HELP').  Optional arguments are enclosed in
 square brackets.
 
-A blank line repeats the previous command literally.  (Except for
+A blank line repeats the previous command literally, except for
-'list', where it lists the next 11 lines.)
+'list', where it lists the next 11 lines.
 
 Commands that the debugger doesn't recognize are assumed to be Python
 statements and are executed in the context of the program being
@@ -35,9 +35,24 @@ debugged; it is even possible to change variables.  When an exception
 occurs in such a statement, the exception name is printed but the
 debugger's state is not changed.
 
-The debugger is not directly programmable; but it is implemented as a
+The debugger supports aliases, which can save typing.  And aliases
-class from which you can derive your own debugger class, so you can
+can have parameters (see the alias help entry) which allows one a
-make as fancy as you like.
+certain level of adaptability to the context under examination.
+
+Multiple commands may be entered on a single line, separated by
+semi-colons.  No intelligence is applied to separating the commands;
+the input is split at the first ';', even if it is in the middle of
+a quoted string.
+
+If a file ".pdbrc" exists in your home directory or in the current
+directory, it is read in and executed as if it had been typed at
+the debugger prompt.  This is particularly useful for aliases.
+If both files exist, the one in the home directory is read first
+and aliases defined there can be overriden by the local file.
+
+Aside from aliases, the debugger is not directly programmable; but
+it is implemented as a class from which you can derive your own
+debugger class, which you can make as fancy as you like.
 
 
 Debugger commands
@@ -46,8 +61,7 @@ Debugger commands
 h(elp)
 	Without argument, print the list of available commands.
 	With a command name as argument, print help about that command
-        "help pdb" pipes the full documentation file to the $PAGER
+	(this is currently not implemented).
-        "help exec" gives help on the ! command
 
 w(here)
 	Print a stack trace, with the most recent frame at the bottom.
@@ -62,24 +76,47 @@ u(p)
 	Move the current frame one level up in the stack trace
 	(to a newer frame).
 
-b(reak) ([file:]lineno | function) [, "condition"]
+b(reak) [ ([filename:]lineno | function) [, "condition"] ]
-        With a line number argument, set a break there in the current
+	With a filename:line number argument, set a break there.  If
-        file.  With a function name, set a break at the entry of that
+	filename is omitted, use the current file.  With a function name,
-        function.  Without argument, list all breaks.  If a second
+	set a break at the first executable line of that function.
-        argument is present, it is a string specifying an expression
+	Without argument, list all breaks.  Each breakpoint is assigned
-        which must evaluate to true before the breakpoint is honored.
+	a number which is by all the other breakpoint commands refer to it.
 
-        The line number may be prefixed with a filename and a colon,
+	The condition argument, if present, is a string which must
-        to specify a breakpoint in another file (probably one that
+	evaluate to true in order for the breakpoint to be honored.
-        hasn't been loaded yet).  The file is searched on sys.path.
 
-cl(ear) [lineno]
+tbreak [ ([filename:]lineno | function) [, "condition"] ]
-        With a line number argument, clear that break in the current file.
+	Temporary breakpoint, which is removed automatically when it is
-        Without argument, clear all breaks (but first ask confirmation).
+	first hit.  The arguments are the same as break.
 
-        The line number may be prefixed with a filename and a colon,
+cl(ear) [bpnumber [bpnumber ...] ]
-        to specify a breakpoint in another file (probably one that
+	With a space separated list of breakpoint numbers, clear those
-        hasn't been loaded yet).  The file is searched on sys.path.
+	breakpoints.  Without argument, clear all breaks (but first
+	ask confirmation).
+
+disable bpnumber [bpnumber ...]
+	Disables the breakpoints given as a space separated list of
+	breakpoint numbers.  Disabling a breakpoint means it cannot cause
+	the program to stop execution, but unlike clearing a breakpoint, it
+	remains in the list of breakpoints and can be (re-)enabled.
+
+enable bpnumber [bpnumber ...]
+	Enables the breakpoints specified.
+
+ignore bpnumber count
+	Sets the ignore count for the given breakpoint number.  If
+	count is omitted, the ignore count is set to 0.  A breakpoint
+	becomes active when the ignore count is zero.  When non-zero,
+	the count is decremented each time the breakpoint is reached
+	and the breakpoint is not disabled and any associated condition
+	evaluates to true.
+
+condition bpnumber str_condition
+	str_condition is a string specifying an expression which
+	must evaluate to true before the breakpoint is honored.
+	If str_condition is absent, any existing condition is removed;
+	i.e., the breakpoint is made unconditional.
 
 s(tep)
 	Execute the current line, stop at the first possible occasion
@@ -110,15 +147,96 @@ p expression
 	Print the value of the expression.
 
 (!) statement
-        Execute the (one-line) statement in the context of
+	Execute the (one-line) statement in the context of the current
-        the current stack frame.
+	stack frame.  The exclamation point can be omitted unless the
-        The exclamation point can be omitted unless the first word
+	first word of the statement resembles a debugger command.
-        of the statement resembles a debugger command.
 	To assign to a global variable you must always prefix the
 	command with a 'global' command, e.g.:
 	(Pdb) global list_options; list_options = ['-l']
 	(Pdb)
 
+
+whatis arg
+	 Prints the type of the argument.
+
+alias [name [command]]
+	Creates an alias called 'name' that executes 'command'.  The command
+	must *not* be enclosed in quotes.  Replaceable parameters can be
+	indicated by %1, %2, and so on, while %* is replaced by all the 
+	parameters.  If no command is given, the current alias for name
+	is shown. If no name is given, all aliases are listed.
+
+	Aliases may be nested and can contain anything that can be
+	legally typed at the pdb prompt.  Note!  You *can* override
+	internal pdb commands with aliases!  Those internal commands
+	are then hidden until the alias is removed.  Aliasing is recursively
+	applied to the first word of the command line; all other words
+	in the line are left alone.
+
+	As an example, here are two useful aliases (especially when placed
+	in the .pdbrc file):
+
+	#Print instance variables (usage "pi classInst")
+	alias pi for k in %1.__dict__.keys(): print "%1." + k + "=" + %1.__dict__[k]
+	#Print instance variables in self
+	alias ps pi self
+		
+unalias name
+	Deletes the specified alias.
+
 q(uit)
 	Quit from the debugger.
 	The program being executed is aborted.
+
+
+How it works
+============
+
+Some changes were made to the interpreter:
+- sys.settrace(func) sets the global trace function
+- there can also a local trace function (see later)
+
+Trace functions have three arguments: (frame, event, arg)
+  - frame is the current stack frame
+  - event is a string: 'call', 'line', 'return' or 'exception'
+  - arg is dependent on the event type
+A trace function should return a new trace function or None.
+Class methods are accepted (and most useful!) as trace methods.
+
+The events have the following meaning:
+
+  'call':      A function is called (or some other code block entered).
+               The global trace function is called;
+               arg is the argument list to the function;
+               the return value specifies the local trace function.
+
+  'line':      The interpreter is about to execute a new line of code
+               (sometimes multiple line events on one line exist).
+               The local trace function is called; arg in None;
+               the return value specifies the new local trace function.
+
+  'return':    A function (or other code block) is about to return.
+               The local trace function is called;
+               arg is the value that will be returned.
+               The trace function's return value is ignored.
+
+  'exception': An exception has occurred.
+               The local trace function is called;
+               arg is a triple (exception, value, traceback);
+               the return value specifies the new local trace function
+
+Note that as an exception is propagated down the chain of callers, an
+'exception' event is generated at each level.
+
+Stack frame objects have the following read-only attributes:
+  f_code:      the code object being executed
+  f_lineno:    the current line number (-1 for 'call' events)
+  f_back:      the stack frame of the caller, or None
+  f_locals:    dictionary containing local name bindings
+  f_globals:   dictionary containing global name bindings
+
+Code objects have the following read-only attributes:
+  co_code:     the code string
+  co_names:    the list of names used by the code
+  co_consts:   the list of (literal) constants used by the code
+  co_filename: the filename from which the code was compiled