cgit.sxemacs.org Git - packages/blob - xemacs-packages/python-modes/pydoc.el

   1 ;; LCD-ENTRY:    pydoc.el|Bob Weiner|bob@deepware.com|Interface to pydoc Python documentation viewer|Date|04/23/2001|01.02|www.deepware.com/pub/python
   2 ;;
   3 ;; FILE:         pydoc.el
   4 ;; SUMMARY:      Interface to pydoc Python documentation viewer
   5 ;; USAGE:        Autoloaded XEmacs Lisp Library, use {C-c M-h} to invoke
   6 ;; KEYWORDS:     help, languages, oop, tools
   7 ;;
   8 ;; AUTHOR:       Bob Weiner
   9 ;; ORG:          Deepware
  10 ;; E-MAIL:       bob@deepware.com
  11 ;;
  12 ;; ORIG-DATE:    18-Apr-01 at 19:11:27
  13 ;; LAST-MOD:     23-Apr-01 at 23:59:46 by Bob Weiner
  14 ;;
  15 ;; Copyright (C) 2001  Bob Weiner
  16 ;; Licensed under the Python license version 2.0 or higher.
  17 ;;
  18 ;; This file is part of InfoDock, available from:
  19 ;;   www.sourceforge.net/projects/infodock
  20 ;;
  21 ;; DESCRIPTION:
  22 ;;
  23 ;;   Globally adds key binding {C-c M-h} (pydoc-commands) which
  24 ;;   displays a menu of commands for interacting with the pydoc Python
  25 ;;   documentation viewer library.  See the documentation of
  26 ;;   `pydoc-menu-help' for details on each available command.
  27 ;;
  28 ;;   NOTE: You *must* install the following for pydoc.el to work:
  29 ;;
  30 ;;     python-mode.el 4.1.1 or higher as your Python editing mode (included
  31 ;;     in the pydoc.el distribution)
  32 ;;
  33 ;;     pydoc_lisp.py in your Python site-packages directory (unless
  34 ;;       these functions are already integrated into pydoc.py)
  35 ;;
  36 ;;     set the environment variable PYTHONDOCS to the root directory
  37 ;;       of your Python html documentation tree, for example:
  38 ;;       export PYTHONDOCS=$HOME/Python-2.1/Doc/html/
  39 ;;     and then startup your editor (otherwise, the environment variable
  40 ;;     setting won't be inherited by the editor and some commands will not
  41 ;;     work).
  42 ;;
  43 ;;   Install and byte-compile pydoc.el in one of your load-path directories
  44 ;;   and then either set it to autoload or do a (require 'pydoc) in your
  45 ;;   editor initialization file.  Then invoke it via the menu key binding.
  46 ;;
  47 ;; DESCRIP-END.
  48
  49 ;;; ************************************************************************
  50 ;;; Other required Elisp libraries
  51 ;;; ************************************************************************
  52
  53 (require 'python-mode)
  54
  55 ;; Ensure that the user has a python-mode version which supports pydoc.el.
  56 (if (string-lessp py-version "$Revision: 1.1 $")
  57     (error "(pydoc): you must upgrade from python-mode.el %s to 4.1.1 (or higher)"
  58            (if (string-match "[0-9.]+" py-version)
  59                (match-string 0 py-version) py-version)))
  60
  61 (provide 'pydoc)
  62
  63 ;;; ************************************************************************
  64 ;;; Public variables
  65 ;;; ************************************************************************
  66
  67 (defvar pydoc-version "01.01"
  68   "Release version of the Emacs Lisp interface to pydoc.")
  69
  70 ;; Provide easy access to (pydoc-commands) everywhere since the user may want
  71 ;; to reference Python doc when in a Python help buffer, a documentation file,
  72 ;; etc.  Use {C-c M-h} instead of {C-c C-h} for this next binding since
  73 ;; {C-c C-h} is an important key in InfoDock's outline-minor-mode which is
  74 ;; often used under python-mode, so this avoids conflicts.
  75
  76 ;;;###autoload
  77 (global-set-key "\C-c\M-h" 'pydoc-commands)
  78
  79 (defvar pydoc-buffer-prefix "Py: "
  80   "Prefix string attached to all pydoc display buffers.")
  81
  82 (defvar pydoc-xrefs-prefix "^Related help topics:"
  83   "Prefix regexp output before comma separated pydoc help section names.")
  84
  85 ;;; ************************************************************************
  86 ;;; Private variables
  87 ;;; ************************************************************************
  88
  89 (defvar pydoc-cmd-alist
  90   '(("A)propos"         . pydoc-apropos)
  91     ("H)elp"            . pydoc-help)
  92     ("K)eyword"         . pydoc-keywords)
  93     ("M)odule"          . pydoc-modules)
  94     ("P)ackage"         . pydoc-packages)
  95     ("T)opic"           . pydoc-topics)
  96     ("X)ref"            . pydoc-xrefs))
  97   "Association list of (HELP-CMD-PROMPT . CMD) elements for pydoc commands.")
  98
  99 (defvar pydoc-alist nil
 100   "Association list of (list-name . alist) elements used to build prompt completion tables.")
 101
 102 (defvar pydoc-menu-mode-map nil
 103   "Keymap containing pydoc-menu commands.")
 104
 105 (defvar pydoc-menu-special-keys '(?\C-g ?? ?\C-i ?\C-j ?\C-m ?\ ))
 106
 107 (if pydoc-menu-mode-map
 108     nil
 109   (setq pydoc-menu-mode-map (make-keymap))
 110   (suppress-keymap pydoc-menu-mode-map)
 111   (define-key pydoc-menu-mode-map
 112     (car (where-is-internal 'keyboard-quit)) 'pydoc-menu-enter)
 113   (mapcar #'(lambda (key)
 114               (define-key pydoc-menu-mode-map (char-to-string key) 'pydoc-menu-enter))
 115           pydoc-menu-special-keys)
 116   (let ((i 33))
 117     (while (<= i 127)
 118       (define-key pydoc-menu-mode-map (char-to-string i) 'pydoc-menu-enter)
 119       (setq i (1+ i)))))
 120
 121 ;;; ************************************************************************
 122 ;;; Commands
 123 ;;; ************************************************************************
 124
 125 ;;;###autoload
 126 (defun pydoc-commands (&optional init-flag)
 127   "Display a menu of commands for interacting with the pydoc Python documentation viewer library.
 128 With optional prefix arg INIT-FLAG, reinitializes the pydoc completion
 129 tables which includes the list of available Python modules.
 130 See the documentation for `pydoc-menu-help' for a description of the
 131 available commands."
 132   (interactive "P")
 133   (if (or init-flag (null pydoc-alist))
 134       (pydoc-initialize))
 135   (call-interactively (pydoc-select-command)))
 136
 137 ;;;###autoload
 138 (defun pydoc-apropos (&optional argument)
 139   "Call the Python module apropos function with optional ARGUMENT and display the output.
 140 ARGUMENT defaults to an identifier near point.
 141 The apropos function finds matches for ARGUMENT within the first line of
 142 module or package doc strings."
 143   (interactive)
 144   (if (not argument)
 145       (setq argument (pydoc-read-argument "Python module/package apropos: ")))
 146   (pydoc-call "apropos" (format "'%s'" argument) (concat "apropos " argument)))
 147
 148 ;;;###autoload
 149 (defun pydoc-help (&optional argument)
 150   "Call the Python help function with optional ARGUMENT and display the output.
 151 ARGUMENT defaults to an identifier near point.
 152 ARGUMENT is resolved as a name in any present Python namespace; use
 153 single 'quotes' to send ARGUMENT as a Python literal string."
 154   (interactive)
 155   (if (not argument)
 156       (setq argument (pydoc-read-argument "Python help (name or 'string'): ")))
 157   (pydoc-call "help" argument argument))
 158
 159 ;;;###autoload
 160 (defun pydoc-keywords (argument)
 161   "Prompt with completion for a Python keyword ARGUMENT and display its documentation."
 162   (interactive
 163    (list
 164     (let ((completion-ignore-case t))
 165       (completing-read "Python keyword help (RET for all): "
 166                        (cdr (assoc "keywords" pydoc-alist))
 167                        nil t))))
 168   (if (member argument '(nil ""))
 169       (setq argument "keywords"))
 170   (pydoc-call "help" (format "'%s'" argument) argument))
 171
 172 ;;;###autoload
 173 (defun pydoc-modules (argument)
 174   "Prompt with completion for a Python module/package ARGUMENT and display its documentation."
 175   (interactive
 176    (list
 177     (let ((completion-ignore-case t))
 178       (completing-read "Python module/package help (RET for all): "
 179                        (cdr (assoc "modules" pydoc-alist))
 180                        nil t))))
 181   (if (member argument '(nil ""))
 182       (setq argument "modules"))
 183   (if (string-match "\\`Pkg-" argument)
 184       (setq argument (substring argument (match-end 0))))
 185   (pydoc-call "help" (format "'%s'" argument) argument))
 186
 187 ;;;###autoload
 188 (defun pydoc-packages (argument)
 189   "Prompt with completion for a Python package ARGUMENT and display its documentation."
 190   (interactive
 191    (list
 192     (let ((completion-ignore-case t))
 193       (completing-read "Python package help (RET for all): "
 194                        (delq nil
 195                              (mapcar
 196                               #'(lambda (entry)
 197                                   (if (string-match "\\`Pkg-" entry)
 198                                       (list (substring entry (match-end 0)))))
 199                               (mapcar 'car (cdr (assoc "modules" pydoc-alist)))))
 200                        nil t))))
 201   (if (member argument '(nil ""))
 202       (setq argument "modules"))
 203   (if (string-match "\\`Pkg-" argument)
 204       (setq argument (substring argument (match-end 0))))
 205   (pydoc-call "help" (format "'%s'" argument) argument))
 206
 207 ;;;###autoload
 208 (defun pydoc-topics (argument)
 209   "Prompt with completion for a Python topic ARGUMENT and display its documentation."
 210   (interactive
 211    (list
 212     (let ((completion-ignore-case t))
 213       (completing-read "Python topic help (RET for all): "
 214                        (cdr (assoc "topics" pydoc-alist))
 215                        nil t))))
 216   (if (member argument '(nil ""))
 217       (setq argument "topics")
 218     (setq argument (upcase argument)))
 219   (pydoc-call "help" (format "'%s'" argument) argument))
 220
 221 ;;;###autoload
 222 (defun pydoc-xrefs ()
 223   "Display xref at point or prompt user with completion and display chosen xref.
 224 Xrefs are terms which follow the `pydoc-xrefs-prefix' regular expression."
 225   (interactive)
 226   (cond ((save-excursion
 227            (beginning-of-line)
 228            (looking-at pydoc-xrefs-prefix))
 229          ;; On an xref line
 230          (if (>= (point) (match-end 0))
 231              ;; After prefix, within an xref
 232              (pydoc-display-xref)
 233            ;; Prompt for with completion and display xref
 234            (pydoc-display-xref
 235             (save-excursion
 236               (goto-char (match-end 0))
 237               (pydoc-choose-xref "Display xref: ")))))
 238
 239         ;; Move to last xref line if any in buffer
 240         ((pydoc-xrefs-p)
 241          ;; Prompt for with completion and display xref
 242          (pydoc-display-xref
 243           (save-excursion
 244             (goto-char (match-end 0))
 245             (pydoc-choose-xref "Display xref: "))))
 246
 247         (t (error "(pydoc): No cross-references in this buffer"))))
 248
 249 ;;; ************************************************************************
 250 ;;; Public functions
 251 ;;; ************************************************************************
 252
 253 (defun pydoc-call (func-name argument buf-name-suffix)
 254   "Call the pydoc function FUNC-NAME with ARGUMENT (a string) and display in Py: BUF-NAME-SUFFIX."
 255   (let ((wind-config (current-window-configuration))
 256         (output-buf-name
 257          (py-execute-string
 258           (format
 259            "if not vars().has_key('%s'):\n    from pydoc import %s\n\n%s(%s)\n"
 260            func-name func-name func-name argument)))
 261         (async-process (pydoc-async-output-p))
 262         input-buf-name)
 263     (setq input-buf-name (if async-process
 264                              (buffer-name (process-buffer async-process))
 265                            " *Python Command*"))
 266     (if (buffer-live-p (get-buffer input-buf-name))
 267         (bury-buffer input-buf-name))
 268
 269     ;; current vintages of python-mode.el (4.6 at least)
 270     ;; no longer return a buffer [name].  We get t from the
 271     ;; final kill-buffer instead.  If we see t we use try to
 272     ;; guess a good buffer name.
 273     (if (eq output-buf-name t)
 274         (setq output-buf-name (if async-process
 275                                   (buffer-name (process-buffer async-process))
 276                                 "*Python Output*")))
 277
 278     (if (or (null output-buf-name)
 279             ;; In earlier versions of python-mode.el, py-execute-string does
 280             ;; not return a buffer name.
 281             (not (stringp output-buf-name))
 282             (not (buffer-live-p (get-buffer output-buf-name)))
 283             (and async-process (not (pydoc-wait-for-output input-buf-name 10.0))))
 284         (message "(\"%s(%s)\" finished with no output)" func-name argument)
 285       (set-window-configuration wind-config)
 286       (bury-buffer output-buf-name)
 287       (set-buffer output-buf-name)
 288       (goto-char (point-max)) ;; User may have moved point elsewhere.
 289       (let ((output-end
 290              ;; Skip any trailing Python prompt
 291              (save-excursion (beginning-of-line) (point)))
 292             (output-start (pydoc-output-start))
 293             (display-buf))
 294         (if (save-excursion
 295               (goto-char (point-max))
 296               (forward-line -1)
 297               (looking-at "^NameError:"))
 298             (progn (switch-to-buffer (car (buffer-list)))
 299                    (error "(pydoc): %s(%s) failed to find any matching term"
 300                           func-name argument))
 301           (setq display-buf (get-buffer-create
 302                              (concat pydoc-buffer-prefix buf-name-suffix)))
 303           (set-buffer display-buf)
 304           (toggle-read-only 0)
 305           (erase-buffer)
 306           (insert-buffer-substring output-buf-name output-start output-end)
 307           (goto-char (point-min))
 308           (set-buffer-modified-p nil)
 309           (message "")
 310           (help-mode)
 311           (pydoc-kill-async-output output-buf-name async-process)
 312           (pop-to-buffer display-buf))))))
 313
 314 (defun pydoc-display-apropos-entry ()
 315   "Detect module/package names in pydoc apropos buffer entries and display their code.
 316 Each module/package name must be at the beginning of the line
 317 and must be followed by a space, dash and then another space."
 318   (interactive)
 319   (if (string-match (concat "\\`" (regexp-quote pydoc-buffer-prefix)
 320                             "apropos ")
 321                     (buffer-name))
 322       (save-excursion
 323         (beginning-of-line)
 324         (if (looking-at "\\([^][-(){}<>'`\"/*+&^%$#@!=|?,~ \t\n\r]+\\) - ")
 325             (let* ((entry (buffer-substring
 326                            (match-beginning 1) (match-end 1)))
 327                    (path (pydoc-pathname entry)))
 328               (if (and path (file-exists-p path))
 329                   (find-file-other-window path)))))))
 330
 331 (defun pydoc-pathname (module-identifier)
 332   "Return the filename or package directory where MODULE-IDENTIFIER is defined, else nil."
 333   (setq module-identifier
 334         (replace-in-string module-identifier "\\."
 335                            (char-to-string directory-sep-char) t))
 336   (or (locate-file module-identifier (pydoc-paths-list) ".py:.pyc:.pyo:.pyd")
 337       ;; May be a package directory
 338       (locate-data-directory module-identifier (pydoc-paths-list))))
 339
 340 ;;; ************************************************************************
 341 ;;; Private functions
 342 ;;; ************************************************************************
 343
 344 (defun pydoc-commands-dialog-box (dialog-box)
 345   "Prompt user with DIALOG-BOX and return selected value.
 346 Assumes caller has checked that `dialog-box' function exists."
 347   (let ((echo-keystrokes 0)
 348         event-obj
 349         event)
 350     ;; Add cmd-help and cancel buttons to dialog box.
 351     (setq dialog-box (append dialog-box
 352                              (list nil '["Cmd-Help" (pydoc-menu-help) t]
 353                                    '["Cancel" 'keyboard-quit t])))
 354     (popup-dialog-box dialog-box)
 355     (catch 'pydoc-done
 356       (while t
 357         (setq event (next-command-event event)
 358               event-obj (event-object event))
 359         (cond ((and (menu-event-p event)
 360                     (memq event-obj '(abort menu-no-selection-hook)))
 361                (signal 'quit nil))
 362               ((button-release-event-p event) ;; don't beep twice
 363                nil)
 364               ((menu-event-p event)
 365                (throw 'pydoc-done (eval event-obj)))
 366               (t
 367                (beep)
 368                (message "Please answer the dialog box.")))))))
 369
 370 (defun pydoc-default-argument ()
 371   "Return a default identifier argument near point."
 372   (require 'etags)
 373   ;; Include periods as symbol constituents but remove any trailing period.
 374   (let* ((period-syntax (char-to-string (char-syntax ?\.)))
 375          (default (unwind-protect
 376                       (progn
 377                         (modify-syntax-entry ?\. "_")
 378                         (find-tag-default))
 379                     (modify-syntax-entry ?\. period-syntax))))
 380     (if (and (stringp default) (string-match "\\.+\\'" default))
 381         (setq default (substring default 0 (match-beginning 0))))
 382     default))
 383
 384 (defun pydoc-initialize()
 385   (message "Please wait a moment while the Python help system is initialized...")
 386   ;; XEmacs change: help python find pydoc_lisp.py OOTB.
 387   (let ((output-buf)
 388         (pydir (locate-data-directory "python-modes")))
 389     (save-window-excursion
 390       ;; Start a Python interpreter if not already running.
 391       (py-shell)
 392       (pydoc-wait-for-output (current-buffer) 3.0)
 393       (setq output-buf
 394             (py-execute-string
 395              (format
 396               "if not vars().has_key('pydoc_lisp'):
 397     import sys
 398     if not '%s' in sys.path:
 399         sys.path.append('%s')
 400     import pydoc_lisp
 401
 402 pydoc_lisp.pydoc_output_lisp()
 403 " pydir pydir)))
 404       ;; current vintages of python-mode.el (4.6 at least)
 405       ;; no longer return a buffer [name].  We get t from the
 406       ;; final kill-buffer instead.  If we see t we use the
 407       ;; python shell's buffer.
 408       (if (eq output-buf t)
 409           (setq output-buf
 410                 (buffer-name (process-buffer (pydoc-async-output-p)))))
 411
 412       (setq pydoc-alist (pydoc-lisp-read-result output-buf)))
 413     (if (member pydoc-alist '(nil None Traceback))
 414         (progn
 415           (setq pydoc-alist nil)
 416           (pop-to-buffer output-buf)
 417           (error "(pydoc): Initialization failed, Python did not output Lisp lists"))
 418       (pydoc-kill-async-output output-buf (pydoc-async-output-p))
 419       ;; Normalize Python search paths and make a regular list, not an alist
 420       (let ((paths (assoc "paths" pydoc-alist)))
 421         (setcdr paths (mapcar 'file-name-as-directory
 422                               (mapcar 'car (cdr paths)))))
 423       (message ""))))
 424
 425 (defun pydoc-lisp-read-result (result-buf)
 426   "Read and return the most recent python output in RESULT-BUF as a Lisp expression.
 427 If a timeout occurs before the expression is read, then return nil."
 428   (save-excursion
 429     (if (pydoc-wait-for-output result-buf 5.0)
 430         (progn (goto-char (pydoc-output-start))
 431                (read (current-buffer)))
 432       nil)))
 433
 434 (defun pydoc-output-start ()
 435   "Return the character position start of the most recent Python output."
 436   (save-excursion
 437     ;; Skip any trailing Python prompt
 438     (forward-line 0) ;; to bol
 439     (if (re-search-backward "^>>> " nil t)
 440         (if (not (zerop (forward-line 1)))
 441             (goto-char (point-max)))
 442       (goto-char (point-min)))
 443     (point)))
 444
 445 (defun pydoc-read-argument (prompt)
 446   "Read and return a string argument using PROMPT."
 447   (let* ((default (pydoc-default-argument))
 448          (argument
 449           (read-string
 450            (if default
 451                (format "%s(default %s) " prompt default)
 452              prompt))))
 453     (if (member argument '(nil ""))
 454         default
 455       argument)))
 456
 457 (defun pydoc-select-command ()
 458   "Interactively select and return a pydoc command to run."
 459   (let ((cmd-prompt)
 460         (cmd)
 461         ;; Use dialog box if last user event involved the mouse.
 462         (use-dialog-box (and (fboundp 'popup-dialog-box)
 463                              (fboundp 'button-press-event-p)
 464                              (or (button-press-event-p last-command-event)
 465                                  (button-release-event-p last-command-event)
 466                                  (menu-event-p last-command-event)))))
 467     ;; Create a prompt numbering each command available.
 468     (setq cmd-prompt
 469           (if use-dialog-box
 470               (mapcar
 471                #'(lambda (name-and-cmd)
 472                    (vector (car name-and-cmd)
 473                            (list 'quote (cdr name-and-cmd))
 474                            't))
 475                pydoc-cmd-alist)
 476             (concat
 477              "Pydoc>  "
 478              (mapconcat 'identity (mapcar 'car pydoc-cmd-alist) "  ")
 479              ": ")))
 480     ;; Prompt user.
 481     (if use-dialog-box
 482         (setq cmd (pydoc-commands-dialog-box
 483                    (cons "Choose pydoc command (or choose Cmd-Help for help on commands): " cmd-prompt)))
 484       ;; Otherwise, prompt in the minibuffer.
 485       (let ((item-keys (mapcar #'(lambda (item) (aref item 0))
 486                                (mapcar 'car pydoc-cmd-alist)))
 487             key)
 488         (while (and (not (memq (setq key (upcase
 489                                           (string-to-char
 490                                            (read-from-minibuffer
 491                                             "" cmd-prompt pydoc-menu-mode-map))))
 492                                item-keys))
 493                     (not (memq key pydoc-menu-special-keys)))
 494           (beep)
 495           (discard-input))
 496         (if (eq key ?\C-g)
 497             ;; abort
 498             (keyboard-quit))
 499         (if (memq key pydoc-menu-special-keys)
 500             (setq cmd (pydoc-menu-help))
 501           (setq cmd (cdr (nth (- (length pydoc-cmd-alist)
 502                                  (length (memq key item-keys)))
 503                               pydoc-cmd-alist))))))
 504     cmd))
 505
 506 ;;; Asynchronous handling
 507 (defun pydoc-async-output-p ()
 508   "Return the running asynchronous process for Python code evaluation or nil if none."
 509   (let ((proc (and (stringp py-which-bufname)
 510                    (get-process py-which-bufname))))
 511     (and proc (eq (process-status proc) 'run) proc)))
 512
 513 (defun pydoc-kill-async-output (output-buf async-process)
 514   (if async-process
 515       (progn
 516         (set-buffer output-buf)
 517         ;; Remove output so it doesn't clog up the interpreter buffer.
 518         (comint-kill-output))))
 519
 520 (defun pydoc-wait-for-output (buffer timeout)
 521   "Move to BUFFER and wait a maximum of TIMEOUT seconds or until Python command execution ends.
 522 Python command execution ends when Python returns a top-level prompt.
 523 Return t if waited less than TIMEOUT time (and thus received full output)."
 524   (set-buffer buffer)
 525   (goto-char (point-max)) ;; User may have moved point elsewhere.
 526   (let ((time-waited 0.0)
 527         (wait-time 0.1))
 528     (while (and (< time-waited timeout)
 529                 (not (save-excursion
 530                        (forward-line 0) ;; to bol
 531                        (looking-at ">>> \\'"))))
 532       (sleep-for wait-time)
 533       (setq time-waited (+ time-waited wait-time)))
 534     (< time-waited timeout)))
 535
 536
 537 ;;; Cmd menu handling
 538 (defun pydoc-menu-enter (&optional char-str)
 539   "Uses CHAR-STR or last input character as minibuffer argument."
 540   (interactive)
 541   (let ((input (or char-str (aref (recent-keys) (1- (length (recent-keys))))))
 542         (case-fold-search t))
 543     (cond
 544      ;; GNU Emacs 19 or above
 545      ((and (not (string-match "XEmacs" emacs-version))
 546            ;; Version 19 and above.
 547            (string-lessp "19" emacs-version))
 548       (and (not (integerp input))
 549            (eventp input)
 550            (setq input (event-basic-type input))))
 551      ((string-match "XEmacs" emacs-version)
 552       (if (eventp input)
 553           (setq input (event-to-character input)))))
 554     (erase-buffer)
 555     (insert input))
 556   (exit-minibuffer))
 557
 558 (defun pydoc-menu-help ()
 559   "Type one of the following characters:
 560
 561 a   - A)propos <term>    - list modules/packages with <term> in their first line doc strings
 562 h   - H)elp <term>       - display doc for name <term> or string literal '<term>'
 563 k   - K)eyword <keyword> - with completion, display doc for a Python <keyword>
 564 m   - M)odule <name>     - with completion, display doc for a Python module <name>
 565 p   - P)ackage <name>    - with completion, display doc for a Python package <name>
 566 t   - T)opic <topic>     - with completion, display Python reference doc for <topic>
 567 x   - X)ref <term>       - with completion, display doc for a pydoc cross-reference
 568
 569 ?   - show this help
 570 C-g - abort from menu"
 571   (interactive)
 572   (save-window-excursion
 573     (switch-to-buffer "*Help*")
 574     (setq buffer-read-only nil)
 575     (erase-buffer)
 576     (insert (documentation 'pydoc-menu-help))
 577     (goto-char (point-min))
 578     (pydoc-select-command)))
 579
 580 ;;; Pathname handling
 581 (defun pydoc-paths-list ()
 582   (cdr (assoc "paths" pydoc-alist)))
 583
 584
 585 ;;; Xref handling
 586 (defun pydoc-choose-xref (prompt &optional xrefs-alist)
 587   (or xrefs-alist (setq xrefs-alist (pydoc-xrefs-alist)))
 588   (if (null xrefs-alist)
 589       (error "(pydoc): No cross-references in this buffer")
 590     (let ((completion-ignore-case t)
 591           (default (pydoc-default-argument))
 592           (result))
 593       (if (not (assoc default xrefs-alist))
 594           (setq default nil))
 595       (while (not result)
 596         (setq result (completing-read
 597                       (if default
 598                           (format "%s(default %s) " prompt default)
 599                         prompt)
 600                       xrefs-alist nil t))
 601         (if (string-equal result "")
 602             (if default
 603                 (setq result default)
 604               (beep)
 605               (setq result nil))))
 606       result)))
 607
 608 (defun pydoc-delete-space (string)
 609   "Delete any leading and trailing space from STRING and return the STRING."
 610   (if (string-match "\\`[ \t\n\r\f]+" string)
 611       (setq string (substring string (match-end 0))))
 612   (if (string-match "[ \t\n\r\f]+\\'" string)
 613       (setq string (substring string 0 (match-beginning 0))))
 614   string)
 615
 616 (defun pydoc-display-xref (&optional xref)
 617   "Displays optional XREF (or prompts for and then displays it).
 618 Signals an error when there are no xrefs within the current buffer."
 619   (interactive)
 620   (if (member xref '(nil ""))
 621       ;; Triggers an error if there are no xrefs.
 622       (setq xref (pydoc-choose-xref "Display xref: ")))
 623   (let ((case-fold-search nil))
 624     (if (string-match "\\`[0-9A-Z_]+\\'" xref)
 625         ;; all uppercase, so is a topic
 626         (pydoc-topics xref)
 627       ;; assume is a module
 628       (pydoc-modules xref))))
 629
 630 (defun pydoc-xrefs-alist ()
 631   ;; Assumes all xrefs are on a single line following point.
 632   (mapcar #'(lambda (str) (list (pydoc-delete-space str)))
 633           (split-string (buffer-substring
 634                          (point) (save-excursion (end-of-line) (point)))
 635                         ",")))
 636
 637 (defun pydoc-xrefs-p ()
 638   "Return t if current buffer contains xrefs or nil otherwise.
 639 A call to \(match-end 0) returns the end of the xrefs-prefix."
 640   (save-excursion
 641     (goto-char (point-max))
 642     (re-search-backward pydoc-xrefs-prefix nil t)))
 643
 644