lisp/ess-help.el

   1 ;;; ess-help.el --- Support for viewing ESS help files
   2
   3 ;; Copyright (C) 1989-1994 Bates, Kademan, Ritter and Smith
   4 ;; Copyright (C) 1997, A.J. Rossini <rossini@stat.sc.edu>
   5 ;; Copyright (C) 1998--2001 A.J. Rossini, Martin Maechler, Kurt Hornik and
   6 ;;      Richard M. Heiberger <rmh@temple.edu>.
   7 ;; Copyright (C) 2001--2004 A.J. Rossini, Rich M. Heiberger, Martin
   8 ;;      Maechler, Kurt Hornik, Rodney Sparapani, and Stephen Eglen.
   9
  10 ;; Original Author: David Smith <dsmith@stats.adelaide.edu.au>
  11 ;; Created: 7 Jan 1994
  12 ;; Maintainers: ESS-core <ESS-core@stat.math.ethz.ch>
  13
  14 ;; This file is part of ESS
  15
  16 ;; This file is free software; you can redistribute it and/or modify
  17 ;; it under the terms of the GNU General Public License as published by
  18 ;; the Free Software Foundation; either version 2, or (at your option)
  19 ;; any later version.
  20
  21 ;; This file is distributed in the hope that it will be useful,
  22 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  23 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  24 ;; GNU General Public License for more details.
  25
  26 ;; You should have received a copy of the GNU General Public License
  27 ;; along with GNU Emacs; see the file COPYING.  If not, write to
  28 ;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
  29
  30 ;;; Commentary:
  31
  32 ;; Code for dealing with ESS help files.  See README.<LANGUAGE> where
  33 ;; <LANGUAGE> is one of `S', `SAS', `Stata'or `XLispStat'.
  34
  35 ;;; Code:
  36
  37 \f ; Requires and autoloads
  38
  39 (eval-when-compile
  40   (require 'reporter)
  41   (require 'ess-inf)
  42   (require 'info))
  43
  44 (require 'ess)
  45
  46 (autoload 'ess-eval-region              "ess-inf" "[autoload]" t)
  47 (autoload 'ess-eval-region-and-go       "ess-inf" "[autoload]" t)
  48 (autoload 'ess-eval-function            "ess-inf" "[autoload]" t)
  49 (autoload 'ess-eval-function-and-go     "ess-inf" "[autoload]" t)
  50 (autoload 'ess-eval-line                "ess-inf" "[autoload]" t)
  51 (autoload 'ess-eval-line-and-go         "ess-inf" "[autoload]" t)
  52 (autoload 'ess-eval-line-and-step       "ess-inf" "[autoload]" t)
  53
  54 (autoload 'ess-beginning-of-function    "ess-mode" "[autoload]" t)
  55 (autoload 'ess-end-of-function          "ess-mode" "[autoload]" t)
  56
  57 (autoload 'ess-load-file                "ess-inf" "[autoload]" t)
  58 (autoload 'ess-command                  "ess-inf" "(autoload)" nil)
  59 (autoload 'ess-display-temp-buffer      "ess-inf" "(autoload)" nil)
  60 (autoload 'ess-switch-to-ESS            "ess-inf" "(autoload)" nil)
  61 (autoload 'ess-read-object-name-default "ess-inf" "(autoload)" nil)
  62 (autoload 'ess-make-buffer-current      "ess-inf" "(autoload)" nil)
  63 (autoload 'ess-search-list              "ess-inf" "(autoload)" nil)
  64 (autoload 'ess-get-object-list          "ess-inf" "(autoload)" nil)
  65
  66 (autoload 'ess-ddeclient-p              "ess-inf" "(autoload)" nil)
  67
  68 (autoload 'ess-display-help-on-object-ddeclient "ess-dde" "(autoload)" nil)
  69
  70
  71 \f ; ess-help-mode
  72 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  73 ;;;; In this section:
  74 ;;;;
  75 ;;;; * The function ess-display-help-on-object
  76 ;;;; * The major mode ess-help-mode
  77 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  78
  79 (defun ess-help-bogus-buffer-p (buffer &optional nr-first return-match debug)
  80   "Return non-nil if  BUFFER  looks like a bogus ESS help buffer.
  81 NR-FIRST is the number of characters at the start of the buffer
  82 to examine when deciding if the buffer if bogus.  If nil, the
  83 first 120 characters of the buffer are searched.  Return pair
  84 of (match-beg. match-end) when optional RETURN-MATCH is non-nil.
  85 Utility used in \\[ess-display-help-on-object]."
  86
  87   ;; search in first nr-first (default 120) chars only
  88   (if (not nr-first) (setq nr-first 120))
  89
  90   (let* ((searching nil)
  91          (buffer-ok (bufferp buffer))
  92          (res
  93           (or (not buffer-ok)
  94               (save-excursion;; ask for new buffer if old one looks bogus ..
  95                 (set-buffer buffer)
  96                 (if debug
  97                     (ess-write-to-dribble-buffer
  98                      (format "(ess-help-bogus-buffer-p %s)" (buffer-name))))
  99
 100                 (let
 101                     ((PM (point-min))
 102                      (case-fold-search t) )
 103                   (or  ;; evaluate up to first non-nil (or end):
 104                    (< (- (point-max) PM) 80); buffer less than 80 chars
 105                    (not (setq searching t))
 106                    (progn (goto-char PM) ;; R:
 107                           (re-search-forward "Error in help"    nr-first t))
 108                    (progn (goto-char PM) ;; S-plus 5.1 :
 109                           (re-search-forward "^cat: .*--"       nr-first t))
 110                    (progn (goto-char PM) ;; S version 3 ; R :
 111                           (re-search-forward "no documentation" nr-first t))
 112                    )))
 113               )))
 114     (if debug
 115         (ess-write-to-dribble-buffer
 116          (format " |--> %s [searching %s]\n" res searching)))
 117
 118     (if (and res return-match searching)
 119         (list (match-beginning 0) (match-end 0))
 120       ;; else
 121       res)))
 122
 123 (defun ess-display-help-on-object (object)
 124   "Display documentation for OBJECT in another window.
 125 If prefix arg is given, forces a query of the  ESS process for the help
 126 file.  Otherwise just pops to an existing buffer if it exists.
 127 Uses the variable `inferior-ess-help-command' for the actual help command.
 128 Prompts for the object name based on the cursor location for all cases
 129 except the S-Plus GUI.  With S-Plus on Windows (both GUI and in an inferior
 130 emacs buffer) the GUI help window is used."
 131   (interactive
 132    (if (ess-ddeclient-p)
 133        (list (read-string "Help on: "))
 134      (ess-find-help-file "Help on: ")))
 135
 136   (if (or (ess-ddeclient-p)
 137           (equal inferior-ess-help-filetype "chm"))
 138       (if (ess-ddeclient-p)
 139           (ess-display-help-on-object-ddeclient object) ;; ddeclient version
 140         (ess-eval-linewise (concat "help(" object ")"))) ;; "chm" version
 141
 142     ;; else: "normal", non-DDE behavior:
 143     (let* ((hb-name (concat "*help["
 144                             ess-current-process-name
 145                             "](" object ")*"))
 146            (old-hb-p    (get-buffer hb-name))
 147            (curr-win-mode major-mode)
 148            (tbuffer     (get-buffer-create hb-name))
 149            (curr-help-command           inferior-ess-help-command)
 150            ;;-- pass the buffer-local 'ess-help-sec-..'  to the ess-help buffer:
 151            (curr-help-sec-regex         ess-help-sec-regex)
 152            (curr-help-sec-keys-alist    ess-help-sec-keys-alist)
 153            (curr-help-syntax-table      (syntax-table))
 154            (curr-help-filetype          inferior-ess-help-filetype)
 155            (alist               ess-local-customize-alist))
 156
 157       (set-buffer tbuffer)
 158       (ess-setq-vars-local (eval alist))
 159       (setq ess-help-sec-regex    curr-help-sec-regex)
 160       (setq ess-help-sec-keys-alist curr-help-sec-keys-alist)
 161       (setq inferior-ess-help-filetype curr-help-filetype)
 162       ;; see above, do same for inferior-ess-help-command... (i.e. remove
 163       ;; hack, restore old code :-).
 164
 165       (if (or (not old-hb-p)
 166               current-prefix-arg
 167               (ess-help-bogus-buffer-p old-hb-p nil nil 'debug)
 168               )
 169
 170           ;; Ask the corresponding ESS process for the help file:
 171           (progn
 172             (if buffer-read-only (setq buffer-read-only nil))
 173             (delete-region (point-min) (point-max))
 174             (ess-help-mode)
 175             (setq ess-local-process-name ess-current-process-name)
 176             (ess-command (format curr-help-command object) tbuffer)
 177             ;; was inferior-ess-help-command
 178
 179             (ess-help-underline)
 180             ;; Stata is clean, so we get a big BARF from this.
 181             (if (not (string= ess-language "STA"))
 182                 (ess-nuke-help-bs))
 183
 184             (goto-char (point-min))))
 185
 186       (save-excursion
 187         (let ((PM (point-min))
 188               (nodocs
 189                (ess-help-bogus-buffer-p (current-buffer) nil 'give-match )))
 190           (goto-char PM)
 191           (if (and nodocs
 192                    ess-help-kill-bogus-buffers)
 193               (progn
 194                 (if (not (listp nodocs))
 195                     (setq nodocs (list PM (point-max))))
 196                 (ess-write-to-dribble-buffer
 197                  (format "(ess-help: error-buffer '%s' nodocs (%d %d)\n"
 198                          (buffer-name) (car nodocs) (cadr nodocs)))
 199                 ;; Avoid using 'message here -- may be %'s in string
 200                 ;;(princ (buffer-substring (car nodocs) (cadr nodocs)) t)
 201                 ;; MM [3/2000]: why avoid?  Yes, I *do* want message:
 202                 (message "%s" (buffer-substring (car nodocs) (cadr nodocs)))
 203                 ;; ^^^ fixme : remove new lines from the above {and abbrev.}
 204                 (ding)
 205                 (kill-buffer tbuffer))
 206
 207             ;; else : show the help buffer.
 208
 209             ;; Check if this buffer describes where help can be found in
 210             ;; various packages. (R only).  This is a kind of bogus help
 211             ;; buffer, but it should not be killed immediately even if
 212             ;; ess-help-kill-bogus-buffers is t.
 213
 214             ;; e.g. if within R, the user does:
 215
 216             ;; > options("help.try.all.packages" = TRUE)
 217
 218             ;; > ?rlm
 219
 220             ;; then a list of packages for where ?rlm is defined is
 221             ;; shown.  (In this case, rlm is in package MASS).  This
 222             ;; help buffer is then renamed *help[R](rlm in packages)* so
 223             ;; that after MASS is loaded, ?rlm will then show
 224             ;; *help[R](rlm)*
 225
 226             (if (equal inferior-ess-program inferior-R-program-name)
 227                 ;; this code should be used only for R processes.
 228                 (save-excursion
 229                   (goto-char (point-min))
 230                   (if (looking-at "Help for topic")
 231                       (let
 232                           ( (newbuf
 233                              (concat "*help[" ess-current-process-name
 234                                      "](" object " in packages)*")))
 235                         ;; if NEWBUF already exists, remove it.
 236                         (if (get-buffer newbuf)
 237                             (kill-buffer newbuf))
 238                         (rename-buffer  newbuf)))))
 239
 240             ;;dbg (ess-write-to-dribble-buffer
 241             ;;dbg        (format "(ess-help '%s' before switch-to..\n" hb-name)
 242             (let ((special-display-regexps
 243                    (if ess-help-own-frame '(".") nil))
 244                   (special-display-frame-alist ess-help-frame-alist)
 245                   (special-display-function
 246                    (if (eq ess-help-own-frame 'one)
 247                        'ess-help-own-frame
 248                      special-display-function)))
 249               (if (eq curr-win-mode 'ess-help-mode)
 250                   (if ess-help-own-frame
 251                       (pop-to-buffer tbuffer)
 252                     (switch-to-buffer tbuffer))
 253                 (ess-display-temp-buffer tbuffer)))
 254             (if curr-help-syntax-table
 255                 (set-syntax-table curr-help-syntax-table))
 256             (set-buffer-modified-p 'nil)
 257             (toggle-read-only t)))))))
 258
 259 (defvar ess-help-frame nil
 260   "Stores the frame used for displaying R help buffers.")
 261
 262 (defun  ess-help-own-frame (buffer &rest ignore)
 263   "Put all ESS help buffers into `ess-help-frame'."
 264   ;; SJE: Code adapted from Kevin Rodgers.
 265   (if (frame-live-p ess-help-frame)
 266       (progn
 267         (or (frame-visible-p ess-help-frame)
 268             (make-frame-visible ess-help-frame))
 269         (raise-frame ess-help-frame)
 270         (select-frame ess-help-frame)
 271         (switch-to-buffer buffer)
 272         (selected-window))
 273     ;; else
 274     (let ((window (special-display-popup-frame buffer)))
 275       (set-window-dedicated-p window nil)
 276       (setq ess-help-frame (window-frame window))
 277       window)))
 278
 279
 280
 281 ;;; THIS WORKS!
 282 ;;(require 'w3)
 283 ;(defun ess-display-w3-help-on-object-other-window (object)
 284 ;  "Display R-documentation for OBJECT using W3"
 285 ;  (interactive "s Help on :")
 286 ;  (let* ((ess-help-url (concat ess-help-w3-url-prefix
 287 ;                              ess-help-w3-url-funs
 288 ;                              object
 289 ;                              ".html")))
 290     ;;(w3-fetch-other-window ess-help-url)
 291 ;    ))
 292
 293
 294 ;;*;; Major mode definition
 295
 296
 297 (defvar ess-help-sec-map nil "Sub-keymap for ESS help mode.")
 298 ;; this breaks "s ?" rather than to fix any (unbroken !) thing:
 299 ;; (make-variable-buffer-local 'ess-help-sec-map)
 300
 301 (defvar ess-help-mode-map nil "Keymap for ESS help mode.")
 302 (if ess-help-mode-map
 303     nil
 304   (setq ess-help-mode-map (make-keymap)); Full keymap, in order to
 305   (suppress-keymap ess-help-mode-map)   ; suppress all usual "printing" characters
 306   (define-key ess-help-mode-map " " 'scroll-up)
 307   (define-key ess-help-mode-map "b" 'scroll-down)
 308   (define-key ess-help-mode-map "\177" 'scroll-down) ; DEL
 309   (define-key ess-help-mode-map "q" 'ess-switch-to-end-of-ESS)
 310   (define-key ess-help-mode-map "\C-m" 'next-line)
 311   ;; (define-key ess-help-mode-map "s" ess-help-sec-map)
 312   (define-key ess-help-mode-map "h" 'ess-display-help-on-object)
 313 ;; TODO: `electric mouse-2'
 314 ;; (define-key ess-help-mode-map [mouse-2] 'ess-display-help-on-object)
 315   (define-key ess-help-mode-map "l" 'ess-eval-line-and-step)
 316   (define-key ess-help-mode-map "r" 'ess-eval-region-and-go)
 317   (define-key ess-help-mode-map "f" 'ess-eval-function-or-paragraph-and-step)
 318   (define-key ess-help-mode-map "n" 'ess-skip-to-next-section)
 319   (define-key ess-help-mode-map "p" 'ess-skip-to-previous-section)
 320   (define-key ess-help-mode-map "/" 'isearch-forward)
 321   (define-key ess-help-mode-map ">" 'end-of-buffer)
 322   (define-key ess-help-mode-map "<" 'beginning-of-buffer)
 323   (define-key ess-help-mode-map "x" 'ess-kill-buffer-and-go)
 324   (define-key ess-help-mode-map "k" 'kill-buffer)
 325   (define-key ess-help-mode-map "?" 'ess-describe-help-mode)
 326   ;;-- those should be "inherited" from ess-mode-map ( ./ess-mode.el )
 327   (define-key ess-help-mode-map "\C-c\C-s" 'ess-switch-process)
 328   (define-key ess-help-mode-map "\C-c\C-r" 'ess-eval-region)
 329   (define-key ess-help-mode-map "\C-c\M-r" 'ess-eval-region-and-go)
 330   (define-key ess-help-mode-map "\C-c\C-f" 'ess-eval-function)
 331   (define-key ess-help-mode-map "\M-\C-x"  'ess-eval-function)
 332   (define-key ess-help-mode-map "\C-c\M-f" 'ess-eval-function-and-go)
 333   (define-key ess-help-mode-map "\C-c\C-j" 'ess-eval-line)
 334   (define-key ess-help-mode-map "\C-c\M-j" 'ess-eval-line-and-go)
 335   (define-key ess-help-mode-map "\M-\C-a"  'ess-beginning-of-function)
 336   (define-key ess-help-mode-map "\M-\C-e"  'ess-end-of-function)
 337   (define-key ess-help-mode-map "\C-c\C-y" 'ess-switch-to-ESS)
 338   (define-key ess-help-mode-map "\C-c\C-z" 'ess-switch-to-end-of-ESS)
 339   (define-key ess-help-mode-map "\C-c\C-l" 'ess-load-file)
 340   (define-key ess-help-mode-map "\C-c\C-v" 'ess-display-help-on-object)
 341   (define-key ess-help-mode-map "\C-c\C-k" 'ess-request-a-process))
 342
 343 ;; One reason for the following menu is to <TEACH> the user about key strokes
 344 (defvar ess-help-mode-menu
 345   (list "ESS-help"
 346         ["Search Forward"               isearch-forward t]
 347         ["Next Section"                 ess-skip-to-next-section t]
 348         ["Previous Section"             ess-skip-to-previous-section t]
 349         ["Help on Section Skipping"     ess-describe-sec-map t]
 350         ["Beginning of Buffer"          beginning-of-buffer t]
 351         ["End of Buffer"                end-of-buffer t]
 352         "-"
 353         ["Help on ..."                  ess-display-help-on-object t]
 354         "-"
 355         ["Eval Line"                    ess-eval-line-and-step t]
 356         ["Eval Paragraph & step"        ess-eval-paragraph-and-step t]
 357         ["Eval Region & Go"             ess-eval-region-and-go t]
 358         ["Switch to ESS Process"        ess-switch-to-ESS t]
 359         ["Switch to End of ESS Proc."   ess-switch-to-end-of-ESS t]
 360         ["Switch _the_ Process"         ess-switch-process t]
 361         "-"
 362         ["Describe ESS-help Mode"       ess-describe-help-mode t]
 363         "-"
 364         ["Kill Buffer"                  kill-buffer t]
 365         ["Kill Buffer & Go"             ess-kill-buffer-and-go t]
 366         )
 367   "Menu used in ess-help mode.")
 368
 369
 370 (defun ess-help-mode ()
 371 ;;; Largely ripped from more-mode.el,
 372 ;;; originally by Wolfgang Rupprecht wolfgang@mgm.mit.edu
 373   "Mode for viewing ESS help files.
 374 Use SPC and DEL to page back and forth through the file.
 375 Use `n'  and `p' to move to next and previous section,
 376     `s' to jump to a particular section;   `s ?' for help.
 377 Use `q' to return to your ESS session; `x' to kill this buffer first.
 378 The usual commands for evaluating ESS source are available.
 379 Other keybindings are as follows:
 380 \\{ess-help-mode-map}"
 381   (interactive)
 382   (setq major-mode 'ess-help-mode)
 383   (setq mode-name "ESS Help")
 384   (use-local-map ess-help-mode-map)
 385
 386   ;;; Keep <tabs> out of the code.
 387   (make-local-variable 'indent-tabs-mode)
 388   (setq indent-tabs-mode nil)
 389
 390   (require 'easymenu)
 391   (easy-menu-define ess-help-mode-menu-map ess-help-mode-map
 392                     "Menu keymap for ess-help mode." ess-help-mode-menu)
 393   (easy-menu-add ess-help-mode-menu-map ess-help-mode-map)
 394
 395   ;; Add the keys for navigating among sections; this is done
 396   ;; dynamically since different languages (e.g. S vs R) have different
 397   ;; section headings.
 398
 399   (setq ess-help-sec-map (make-sparse-keymap))
 400   (mapcar '(lambda (key)
 401             (define-key ess-help-sec-map (char-to-string key)
 402               'ess-skip-to-help-section))
 403             (mapcar 'car ess-help-sec-keys-alist))
 404   (define-key ess-help-sec-map "?" 'ess-describe-sec-map)
 405   (define-key ess-help-sec-map ">" 'end-of-buffer)
 406   (define-key ess-help-sec-map "<" 'beginning-of-buffer)
 407   (define-key ess-help-mode-map "s" ess-help-sec-map)
 408
 409   (run-hooks 'ess-help-mode-hook))
 410
 411 ;;*;; User commands defined in ESS help mode
 412
 413 (defun ess-skip-to-help-section nil
 414   "Jump to a section heading of a help buffer.  The section selected
 415 is determined by the command letter used to invoke the command, as
 416 indicated by `ess-help-sec-keys-alist'.  Use \\[ess-describe-sec-map]
 417 to see which keystrokes find which sections."
 418   (interactive)
 419   (let ((old-point (point))
 420         (case-fold-search nil))
 421     (goto-char (point-min))
 422     (let ((the-sec (cdr (assoc last-command-char
 423                                ess-help-sec-keys-alist))))
 424       (if (not the-sec) (error "Invalid section key: %c"
 425                                last-command-char)
 426         (if (re-search-forward (concat "^" the-sec) nil t) nil
 427             (message "No %s section in this help. Sorry." the-sec)
 428             (goto-char old-point))))))
 429
 430 (defun ess-skip-to-next-section nil
 431   "Jump to next section in ESS help buffer."
 432   (interactive)
 433   (let ((case-fold-search nil))
 434     (if (re-search-forward ess-help-sec-regex nil 'no-error) nil
 435       (message "No more sections."))))
 436
 437 (defun ess-skip-to-previous-section nil
 438   "Jump to previous section in ESS help buffer."
 439   (interactive)
 440   (let ((case-fold-search nil))
 441     (if (re-search-backward ess-help-sec-regex nil 'no-error) nil
 442       (message "No previous section."))))
 443
 444 (defun ess-describe-help-mode nil
 445   "Display help for `ess-mode'."
 446  (interactive)
 447  (describe-function 'ess-help-mode))
 448
 449 (defun ess-kill-buffer-and-go nil
 450   "Kill the current buffer and switch back to the ESS process."
 451   (interactive)
 452   (kill-buffer (current-buffer))
 453   (ess-switch-to-ESS nil))
 454
 455 (defun ess-describe-sec-map nil
 456   "Display help for the `s' key."
 457   (interactive)
 458   (let ((keys-alist ess-help-sec-keys-alist))
 459     (describe-function 'ess-skip-to-help-section)
 460
 461     (with-current-buffer "*Help*"
 462       (toggle-read-only nil)
 463       (goto-char (point-max))
 464       (insert "\n\nCurrently defined keys are:
 465
 466 Keystroke    Section
 467 ---------    -------\n")
 468       (mapcar '(lambda (cs) (insert "    "
 469                                     (car cs)
 470                                     "      "
 471                                     (cdr cs) "\n"))
 472               keys-alist)
 473       (insert "\nFull list of key definitions:\n"
 474               (substitute-command-keys
 475                "\\{ess-help-sec-map}")))))
 476
 477 (defun ess-read-helpobj-name-default (olist)
 478   ;;; Returns the object name at point, or else the name of the
 479   ;;; function call point is in if that has a help file. A name has a
 480   ;;; help file if it is a member of olist.
 481   (or (car (assoc (ess-read-object-name-default) olist))
 482       (condition-case ()
 483           (save-excursion
 484             (save-restriction
 485               (narrow-to-region (max (point-min) (- (point) 1000))
 486                                 (point-max))
 487               (backward-up-list 1)
 488               (backward-char 1)
 489               (car (assoc (ess-read-object-name-default) olist))))
 490         (error nil))))
 491
 492 (defun ess-find-help-file (p-string)
 493   "Find help, prompting for P-STRING.  Note that we can't search SAS,
 494 Stata or XLispStat for additional information."
 495   (ess-make-buffer-current)
 496   (if (not
 497        (or
 498         (string-match "XLS" ess-language)
 499         (string-match "STA" ess-language)
 500         (string-match "SAS" ess-language)))
 501       (let* ((help-files-list (or (ess-get-help-files-list)
 502                                   (mapcar 'list
 503                                           (ess-get-object-list
 504                                            ess-current-process-name))))
 505              (default (ess-read-helpobj-name-default help-files-list))
 506              (prompt-string (if default
 507                                 (format "%s(default %s) " p-string default)
 508                               p-string))
 509              (spec (completing-read prompt-string help-files-list)))
 510         (list (cond
 511                ((string= spec "") default)
 512                (t spec))))
 513     (let* ((spec (read-string p-string)))
 514       (list spec))))
 515
 516
 517 ;;*;; Utility functions
 518
 519 (defun ess-get-help-files-list ()
 520   "Return a list of files which have help available."
 521   (mapcar 'list
 522           (apply 'append
 523                  (mapcar '(lambda (dirname)
 524                             (if (file-directory-p dirname)
 525                                 (directory-files dirname)))
 526                          (mapcar '(lambda (str) (concat str "/.Help"))
 527                                  (ess-search-list))))))
 528
 529 (defun ess-nuke-help-bs ()
 530   "Remove ASCII underlining and overstriking performed by ^H codes."
 531   ;; This function is a modification of nuke-nroff-bs in man.el from the
 532   ;; standard emacs 18 lisp library.
 533   ;; Nuke underlining and overstriking (only by the same letter)
 534   (goto-char (point-min))
 535   (while (search-forward "\b" nil t)
 536     (let* ((preceding (char-after (- (point) 2)))
 537            (following (following-char)))
 538       (cond ((= preceding following)
 539              ;; x\bx
 540              (delete-char -2))
 541             ((= preceding ?\_)
 542              ;; _\b
 543              (delete-char -2))
 544             ((= following ?\_)
 545              ;; \b_
 546              (delete-region (1- (point)) (1+ (point)))))))
 547   ;; Crunch blank lines
 548   (goto-char (point-min))
 549   (while (re-search-forward "\n\n\n\n*" nil t)
 550     (replace-match "\n\n"))
 551   ;; Nuke blanks lines at start.
 552   (goto-char (point-min))
 553   (skip-chars-forward "\n")
 554   (delete-region (point-min) (point)))
 555
 556 (defun ess-help-underline ()
 557   "Replace _^H codes with underline face."
 558   (save-excursion
 559     (goto-char (point-min))
 560     (while (search-forward "_\b" nil t)
 561       (backward-delete-char 2)
 562       (put-text-property (point) (1+ (point)) 'face 'underline))))
 563
 564 ;;*;; Link to Info
 565
 566 (defun ess-goto-info (node)
 567   "Display node NODE from ess-mode info."
 568   (require 'info)
 569   (split-window)
 570   ;;(other-window 1)
 571   (Info-goto-node (concat "(ess)" node)))
 572
 573 \f ; Bug Reporting
 574
 575 (defun ess-submit-bug-report ()
 576   "Submit a bug report on the ess-mode package."
 577   (interactive)
 578   (require 'ess-mode)
 579   (require 'reporter)
 580   (let ((reporter-prompt-for-summary-p 't))
 581     (reporter-submit-bug-report
 582      "ess-bugs@stat.math.ethz.ch"
 583      (concat "ess-mode " ess-version)
 584      (list 'ess-language
 585            'ess-dialect
 586            'ess-ask-for-ess-directory
 587            'ess-ask-about-transfile
 588            'ess-directory
 589            'ess-keep-dump-files
 590            'ess-source-directory)
 591      nil
 592      (lambda ()
 593        ;;(goto-char (point-max))
 594        (rfc822-goto-eoh)
 595        (forward-line 1)
 596        (insert "\nThis bug report will be sent to the ESS bugs email list\n")
 597        (insert "Press C-c C-c when you are ready to send your message.\n\n")
 598        (insert "\n\n\n")
 599        (insert-buffer-substring "*ESS*")))))
 600
 601
 602 ;;; Provide
 603
 604 (provide 'ess-help)
 605
 606 \f ; Local variables section
 607
 608 ;;; This file is automatically placed in Outline minor mode.
 609 ;;; The file is structured as follows:
 610 ;;; Chapters:     ^L ;
 611 ;;; Sections:    ;;*;;
 612 ;;; Subsections: ;;;*;;;
 613 ;;; Components:  defuns, defvars, defconsts
 614 ;;;              Random code beginning with a ;;;;* comment
 615
 616 ;;; Local variables:
 617 ;;; mode: emacs-lisp
 618 ;;; mode: outline-minor
 619 ;;; outline-regexp: "\^L\\|\\`;\\|;;\\*\\|;;;\\*\\|(def[cvu]\\|(setq\\|;;;;\\*"
 620 ;;; End:
 621
 622 ;;; ess-help.el ends here