#9279: remove the pdb.doc file, put its contents in pdb.__doc__. Also sync this and the pdb docs, introduce a new directive for pdb commands and a role to link to them.
diff --git a/Lib/pdb.py b/Lib/pdb.py
index 43520d6..b93a5af 100755
--- a/Lib/pdb.py
+++ b/Lib/pdb.py
@@ -1,8 +1,217 @@
#! /usr/bin/env python3
-"""A Python debugger."""
+"""
+The Python Debugger Pdb
+=======================
-# (See pdb.doc for documentation.)
+To use the debugger in its simplest form:
+
+ >>> import pdb
+ >>> pdb.run('<a statement>')
+
+The debugger's prompt is '(Pdb) '. This will stop in the first
+function call in <a statement>.
+
+Alternatively, if a statement terminated with an unhandled exception,
+you can use pdb's post-mortem facility to inspect the contents of the
+traceback:
+
+ >>> <a statement>
+ <exception traceback>
+ >>> import pdb
+ >>> pdb.pm()
+
+The commands recognized by the debugger are listed in the next
+section. Most can be abbreviated as indicated; e.g., h(elp) means
+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. Alternatives in the command syntax are separated
+by a vertical bar (|).
+
+A blank line repeats the previous command literally, except for
+'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
+debugged. Python statements can also be prefixed with an exclamation
+point ('!'). This is a powerful way to inspect the program being
+debugged; it is even possible to change variables or call functions.
+When an exception occurs in such a statement, the exception name is
+printed but the debugger's state is not changed.
+
+The debugger supports aliases, which can save typing. And aliases can
+have parameters (see the alias help entry) which allows one a certain
+level of adaptability to the context under examination.
+
+Multiple commands may be entered on a single line, separated by the
+pair ';;'. 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
+=================
+
+h(elp)
+ Without argument, print the list of available commands. With
+ a command name as argument, print help about that command.
+
+w(here)
+ Print a stack trace, with the most recent frame at the bottom.
+ An arrow indicates the "current frame", which determines the
+ context of most commands.
+
+d(own) [ count ]
+ Move the current frame count (default one) levels down in the
+ stack trace (to a newer frame).
+
+u(p) [ count ]
+ Move the current frame count (default one) levels up in the
+ stack trace (to an older frame).
+
+b(reak) [ ([filename:]lineno | function) [, condition] ]
+ With a filename:lineno argument, set a break there. If
+ filename is omitted, use the current file. With a function
+ name, set a break at the first executable line of that
+ function. Without argument, list all breaks. Each breakpoint
+ is assigned a number to which all the other breakpoint
+ commands refer.
+
+ The condition argument, if present, is a string which must
+ evaluate to true in order for the breakpoint to be honored.
+
+tbreak [ ([filename:]lineno | function) [, condition] ]
+ Temporary breakpoint, which is removed automatically when it
+ is first hit. The arguments are the same as for break.
+
+cl(ear) [bpnumber [bpnumber ...] ]
+ With a space separated list of breakpoint numbers, clear those
+ breakpoints. Without argument, clear all breaks (but first
+ ask confirmation).
+
+disable bpnumber [bpnumber ...]
+ Disable 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 ...]
+ Enable the breakpoints specified.
+
+ignore bpnumber [count]
+ Set 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 [condition]
+ Set a new condition for the breakpoint, an expression which
+ must evaluate to true before the breakpoint is honored. If
+ condition is absent, any existing condition is removed; i.e.,
+ the breakpoint is made unconditional.
+
+commands [bpnumber]
+ Specify a list of commands for the breakpoint. Type a line
+ containing just 'end' to terminate the commands. The commands
+ are executed when the breakpoint is hit.
+
+ With no breakpoint number argument, refers to the last
+ breakpoint set.
+
+s(tep)
+ Execute the current line, stop at the first possible occasion
+ (either in a function that is called or in the current
+ function).
+
+n(ext)
+ Continue execution until the next line in the current function
+ is reached or it returns.
+
+unt(il)
+ Continue execution until the line with a number greater than
+ the current one is reached or until the current frame returns.
+
+r(eturn)
+ Continue execution until the current function returns.
+
+run [args...]
+ Restart the debugged python program. If a string is supplied
+ it is splitted with "shlex", and the result is used as the new
+ sys.argv. History, breakpoints, actions and debugger options
+ are preserved. "restart" is an alias for "run".
+
+c(ont(inue))
+ Continue execution, only stop when a breakpoint is encountered.
+
+l(ist) [first [,last]]
+ List source code for the current file.
+ Without arguments, list 11 lines around the current line
+ or continue the previous listing.
+ With one argument, list 11 lines starting at that line.
+ With two arguments, list the given range;
+ if the second argument is less than the first, it is a count.
+
+a(rgs)
+ Print the argument list of the current function.
+
+p expression
+ Print the value of the expression.
+
+(!) statement
+ Execute the (one-line) statement in the context of the current
+ stack frame. The exclamation point can be omitted unless the
+ first word 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
+ Print 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
+ Delete the specified alias.
+
+q(uit)
+ Quit from the debugger. The program being executed is aborted.
+"""
import sys
import linecache
@@ -905,7 +1114,7 @@
prompt_prefix), file=self.stdout)
- # Help methods (derived from pdb.doc)
+ # Help methods (derived from docstring)
def help_help(self):
self.help_h()
@@ -1281,15 +1490,8 @@
# print help
def help():
- for dirname in sys.path:
- fullname = os.path.join(dirname, 'pdb.doc')
- if os.path.exists(fullname):
- sts = os.system('${PAGER-more} '+fullname)
- if sts: print('*** Pager exit status:', sts)
- break
- else:
- print('Sorry, can\'t find the help file "pdb.doc"', end=' ')
- print('along the Python search path')
+ import pydoc
+ pydoc.pager(__doc__)
def main():
if not sys.argv[1:] or sys.argv[1] in ("--help", "-h"):