1 ;;; ess-help.el --- Support for viewing ESS help files
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.
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>
14 ;; This file is part of ESS
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)
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.
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.
32 ;; Code for dealing with ESS help files. See README.<LANGUAGE> where
33 ;; <LANGUAGE> is one of `S', `SAS', `Stata'or `XLispStat'.
37 \f ; Requires and autoloads
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
)
54 (autoload 'ess-beginning-of-function
"ess-mode" "[autoload]" t
)
55 (autoload 'ess-end-of-function
"ess-mode" "[autoload]" t
)
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
)
67 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
70 ;;;; * The function ess-display-help-on-object
71 ;;;; * The major mode ess-help-mode
72 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
74 (defun ess-help-bogus-buffer-p (buffer &optional nr-first return-match debug
)
75 "Return non-nil if BUFFER looks like a bogus ESS help buffer.
76 NR-FIRST is the number of characters at the start of the buffer
77 to examine when deciding if the buffer if bogus. If nil, the
78 first 120 characters of the buffer are searched. Return pair
79 of (match-beg. match-end) when optional RETURN-MATCH is non-nil.
80 Utility used in \\[ess-display-help-on-object]."
82 ;; search in first nr-first (default 120) chars only
83 (if (not nr-first
) (setq nr-first
120))
85 (let* ((searching nil
)
86 (buffer-ok (bufferp buffer
))
89 (save-excursion;; ask for new buffer if old one looks bogus ..
92 (ess-write-to-dribble-buffer
93 (format "(ess-help-bogus-buffer-p %s)" (buffer-name))))
97 (case-fold-search t
) )
98 (or ;; evaluate up to first non-nil (or end):
99 (< (- (point-max) PM
) 80); buffer less than 80 chars
100 (not (setq searching t
))
101 (progn (goto-char PM
) ;; R:
102 (re-search-forward "Error in help" nr-first t
))
103 (progn (goto-char PM
) ;; S-plus 5.1 :
104 (re-search-forward "^cat: .*--" nr-first t
))
105 (progn (goto-char PM
) ;; S version 3 ; R :
106 (re-search-forward "no documentation" nr-first t
))
110 (ess-write-to-dribble-buffer
111 (format " |--> %s [searching %s]\n" res searching
)))
113 (if (and res return-match searching
)
114 (list (match-beginning 0) (match-end 0))
118 ;;*;; Access function for displaying help
120 (defun ess-display-help-on-object (object)
121 "Display documentation for OBJECT in another window.
122 If prefix arg is given, forces a query of the ESS process for the help
123 file. Otherwise just pops to an existing buffer if it exists.
124 Uses the variable `inferior-ess-help-command' for the actual help command."
125 (interactive (ess-find-help-file "Help on: "))
126 (let* ((hb-name (concat "*help["
127 ess-current-process-name
129 (old-hb-p (get-buffer hb-name
))
130 (curr-win-mode major-mode
)
131 (tbuffer (get-buffer-create hb-name
))
132 (curr-help-command inferior-ess-help-command
)
133 ;;-- pass the buffer-local 'ess-help-sec-..' to the ess-help buffer:
134 (curr-help-sec-regex ess-help-sec-regex
)
135 (curr-help-sec-keys-alist ess-help-sec-keys-alist
)
136 (curr-help-syntax-table (syntax-table))
137 (alist ess-local-customize-alist
))
140 (ess-setq-vars-local (eval alist
))
141 (setq ess-help-sec-regex curr-help-sec-regex
)
142 (setq ess-help-sec-keys-alist curr-help-sec-keys-alist
)
143 ;; see above, do same for inferior-ess-help-command... (i.e. remove
144 ;; hack, restore old code :-).
146 (if (or (not old-hb-p
)
148 (ess-help-bogus-buffer-p old-hb-p nil nil
'debug
)
151 ;; Ask the corresponding ESS process for the help file:
153 (if buffer-read-only
(setq buffer-read-only nil
))
154 (delete-region (point-min) (point-max))
156 (setq ess-local-process-name ess-current-process-name
)
157 (ess-command (format curr-help-command object
) tbuffer
)
158 ;; was inferior-ess-help-command
161 ;; Stata is clean, so we get a big BARF from this.
162 (if (not (string= ess-language
"STA"))
165 (goto-char (point-min))))
168 (let ((PM (point-min))
169 (nodocs (ess-help-bogus-buffer-p (current-buffer) nil
'give-match
))
173 ess-help-kill-bogus-buffers
)
175 (if (not (listp nodocs
))
176 (setq nodocs
(list PM
(point-max))))
177 (ess-write-to-dribble-buffer
178 (format "(ess-help: error-buffer '%s' nodocs (%d %d)\n"
179 (buffer-name) (car nodocs
) (cadr nodocs
)))
180 ;; Avoid using 'message here -- may be %'s in string
181 ;;(princ (buffer-substring (car nodocs) (cadr nodocs)) t)
182 ;; MM [3/2000]: why avoid? Yes, I *do* want message:
183 (message "%s" (buffer-substring (car nodocs
) (cadr nodocs
)))
184 ;; ^^^ fixme : remove new lines from the above {and abbrev.}
186 (kill-buffer tbuffer
))
188 ;; else : show the help buffer.
190 ;; Check if this buffer describes where help can be found in
191 ;; various packages. (R only). This is a kind of bogus help
192 ;; buffer, but it should not be killed immediately even if
193 ;; ess-help-kill-bogus-buffers is t.
195 ;; e.g. if within R, the user does:
197 ;; > options("help.try.all.packages" = TRUE)
201 ;; then a list of packages for where ?rlm is defined is
202 ;; shown. (In this case, rlm is in package MASS). This
203 ;; help buffer is then renamed *help[R](rlm in packages)* so
204 ;; that after MASS is loaded, ?rlm will then show
207 (if (equal inferior-ess-program inferior-R-program-name
)
208 ;; this code should be used only for R processes.
210 (goto-char (point-min))
211 (if (looking-at "Help for topic")
214 (concat "*help[" ess-current-process-name
215 "](" object
" in packages)*")))
216 ;; if NEWBUF already exists, remove it.
217 (if (get-buffer newbuf
)
218 (kill-buffer newbuf
))
219 (rename-buffer newbuf
)))))
221 ;;dbg (ess-write-to-dribble-buffer
222 ;;dbg (format "(ess-help '%s' before switch-to..\n" hb-name)
223 (let ((special-display-regexps
224 (if ess-help-own-frame
'(".") nil
))
225 (special-display-frame-alist ess-help-frame-alist
)
226 (special-display-function
227 (if (eq ess-help-own-frame
'one
)
229 special-display-function
)))
230 (if (eq curr-win-mode
'ess-help-mode
)
231 (if ess-help-own-frame
232 (pop-to-buffer tbuffer
)
233 (switch-to-buffer tbuffer
))
234 (ess-display-temp-buffer tbuffer
)))
235 (if curr-help-syntax-table
236 (set-syntax-table curr-help-syntax-table
))
237 (set-buffer-modified-p 'nil
)
238 (toggle-read-only t
))))))
240 (defvar ess-help-frame nil
241 "Stores the frame used for displaying R help buffers.")
243 (defun ess-help-own-frame (buffer &rest ignore
)
244 "Put all ESS help buffers into `ess-help-frame'."
245 ;; SJE: Code adapted from Kevin Rodgers.
246 (if (frame-live-p ess-help-frame
)
248 (or (frame-visible-p ess-help-frame
)
249 (make-frame-visible ess-help-frame
))
250 (raise-frame ess-help-frame
)
251 (select-frame ess-help-frame
)
252 (switch-to-buffer buffer
)
255 (let ((window (special-display-popup-frame buffer
)))
256 (set-window-dedicated-p window nil
)
257 (setq ess-help-frame
(window-frame window
))
264 ;(defun ess-display-w3-help-on-object-other-window (object)
265 ; "Display R-documentation for OBJECT using W3"
266 ; (interactive "s Help on :")
267 ; (let* ((ess-help-url (concat ess-help-w3-url-prefix
268 ; ess-help-w3-url-funs
271 ;;(w3-fetch-other-window ess-help-url)
275 ;;*;; Major mode definition
278 (defvar ess-help-sec-map nil
"Sub-keymap for ESS help mode.")
281 (setq ess-help-sec-map
(make-sparse-keymap))
282 (mapcar '(lambda (key)
283 (define-key ess-help-sec-map
(char-to-string key
)
284 'ess-skip-to-help-section
))
285 (mapcar 'car ess-help-sec-keys-alist
))
286 (define-key ess-help-sec-map
"?" 'ess-describe-sec-map
)
287 (define-key ess-help-sec-map
">" 'end-of-buffer
)
288 (define-key ess-help-sec-map
"<" 'beginning-of-buffer
)
291 (defvar ess-help-mode-map nil
"Keymap for ESS help mode.")
292 (if ess-help-mode-map
294 (setq ess-help-mode-map
(make-keymap)); Full keymap, in order to
295 (suppress-keymap ess-help-mode-map
) ; suppress all usual "printing" characters
296 (define-key ess-help-mode-map
" " 'scroll-up
)
297 (define-key ess-help-mode-map
"b" 'scroll-down
)
298 (define-key ess-help-mode-map
"q" 'ess-switch-to-end-of-ESS
)
299 (define-key ess-help-mode-map
"\C-m" 'next-line
)
300 (define-key ess-help-mode-map
"\177" 'scroll-down
) ; DEL
301 (define-key ess-help-mode-map
"s" ess-help-sec-map
)
302 (define-key ess-help-mode-map
"h" 'ess-display-help-on-object
)
303 ;; TODO: `electric mouse-2'
304 ;; (define-key ess-help-mode-map [mouse-2] 'ess-display-help-on-object)
305 (define-key ess-help-mode-map
"l" 'ess-eval-line-and-step
)
306 (define-key ess-help-mode-map
"r" 'ess-eval-region-and-go
)
307 (define-key ess-help-mode-map
"n" 'ess-skip-to-next-section
)
308 (define-key ess-help-mode-map
"p" 'ess-skip-to-previous-section
)
309 (define-key ess-help-mode-map
"/" 'isearch-forward
)
310 (define-key ess-help-mode-map
">" 'end-of-buffer
)
311 (define-key ess-help-mode-map
"<" 'beginning-of-buffer
)
312 (define-key ess-help-mode-map
"x" 'ess-kill-buffer-and-go
)
313 (define-key ess-help-mode-map
"k" 'kill-buffer
)
314 (define-key ess-help-mode-map
"?" 'ess-describe-help-mode
)
315 ;;-- those should be "inherited" from ess-mode-map :
316 (define-key ess-help-mode-map
"\C-c\C-s" 'ess-switch-process
)
317 (define-key ess-help-mode-map
"\C-c\C-r" 'ess-eval-region
)
318 (define-key ess-help-mode-map
"\C-c\M-r" 'ess-eval-region-and-go
)
319 (define-key ess-help-mode-map
"\C-c\C-f" 'ess-eval-function
)
320 (define-key ess-help-mode-map
"\M-\C-x" 'ess-eval-function
)
321 (define-key ess-help-mode-map
"\C-c\M-f" 'ess-eval-function-and-go
)
322 (define-key ess-help-mode-map
"\C-c\C-j" 'ess-eval-line
)
323 (define-key ess-help-mode-map
"\C-c\M-j" 'ess-eval-line-and-go
)
324 (define-key ess-help-mode-map
"\M-\C-a" 'ess-beginning-of-function
)
325 (define-key ess-help-mode-map
"\M-\C-e" 'ess-end-of-function
)
326 (define-key ess-help-mode-map
"\C-c\C-y" 'ess-switch-to-ESS
)
327 (define-key ess-help-mode-map
"\C-c\C-z" 'ess-switch-to-end-of-ESS
)
328 (define-key ess-help-mode-map
"\C-c\C-l" 'ess-load-file
)
329 (define-key ess-help-mode-map
"\C-c\C-v" 'ess-display-help-on-object
)
330 (define-key ess-help-mode-map
"\C-c\C-k" 'ess-request-a-process
))
332 ;; One reason for the following menu is to <TEACH> the user about key strokes
333 (defvar ess-help-mode-menu
335 ["Next Section" ess-skip-to-next-section t
]
336 ["Previous Section" ess-skip-to-previous-section t
]
337 ["Search Forwards" isearch-forward t
]
338 ["Help on Section Skipping" ess-describe-sec-map t
]
339 ["Beginning of Buffer" beginning-of-buffer t
]
340 ["End of Buffer" end-of-buffer t
]
342 ["Help on ..." ess-display-help-on-object t
]
344 ["Eval Line" ess-eval-line-and-step t
]
345 ["Eval Region & Go" ess-eval-region-and-go t
]
346 ["Switch to ESS Process" ess-switch-to-ESS t
]
348 ["Describe ESS-help Mode" ess-describe-help-mode t
]
350 ["Kill Buffer" kill-buffer t
]
351 ["Kill Buffer & Go" ess-kill-buffer-and-go t
]
352 ["Back to end of ESS Pr." ess-switch-to-end-of-ESS t
]
354 "Menu used in ess-help mode.")
357 (defun ess-help-mode ()
358 ;;; Largely ripped from more-mode.el,
359 ;;; originally by Wolfgang Rupprecht wolfgang@mgm.mit.edu
360 "Mode for viewing ESS help files.
361 Use SPC and DEL to page back and forth through the file.
362 Use `n' and `p' to move to next and previous section,
363 `s' to jump to a particular section; `s ?' for help.
364 Use `q' to return to your ESS session; `x' to kill this buffer first.
365 The usual commands for evaluating ESS source are available.
366 Other keybindings are as follows:
367 \\{ess-help-mode-map}"
369 (setq major-mode
'ess-help-mode
)
370 (setq mode-name
"ESS Help")
371 (use-local-map ess-help-mode-map
)
372 (make-local-variable 'ess-local-process-name
)
374 ;;; Keep <tabs> out of the code.
375 (make-local-variable 'indent-tabs-mode
)
376 (setq indent-tabs-mode nil
)
379 (easy-menu-define ess-help-mode-menu-map ess-help-mode-map
380 "Menu keymap for ess-help mode." ess-help-mode-menu
)
381 (easy-menu-add ess-help-mode-menu-map ess-help-mode-map
)
383 (run-hooks 'ess-help-mode-hook
))
385 ;;*;; User commands defined in ESS help mode
387 (defun ess-skip-to-help-section nil
388 "Jump to a section heading of a help buffer. The section selected
389 is determined by the command letter used to invoke the command, as
390 indicated by `ess-help-sec-keys-alist'. Use \\[ess-describe-sec-map]
391 to see which keystrokes find which sections."
393 (let ((old-point (point))
394 (case-fold-search nil
))
395 (goto-char (point-min))
396 (let ((the-sec (cdr (assoc last-command-char
397 ess-help-sec-keys-alist
))))
398 (if (not the-sec
) (error "Invalid section key: %c"
400 (if (re-search-forward (concat "^" the-sec
) nil t
) nil
401 (message "No %s section in this help. Sorry." the-sec
)
402 (goto-char old-point
))))))
404 (defun ess-skip-to-next-section nil
405 "Jump to next section in ESS help buffer."
407 (let ((case-fold-search nil
))
408 (if (re-search-forward ess-help-sec-regex nil
'no-error
) nil
409 (message "No more sections."))))
411 (defun ess-skip-to-previous-section nil
412 "Jump to previous section in ESS help buffer."
414 (let ((case-fold-search nil
))
415 (if (re-search-backward ess-help-sec-regex nil
'no-error
) nil
416 (message "No previous section."))))
418 (defun ess-describe-help-mode nil
419 "Display help for `ess-mode'."
421 (describe-function 'ess-help-mode
))
423 (defun ess-kill-buffer-and-go nil
424 "Kill the current buffer and switch back to the ESS process."
426 (kill-buffer (current-buffer))
427 (ess-switch-to-ESS nil
))
429 (defun ess-describe-sec-map nil
430 "Display help for the `s' key."
432 (describe-function 'ess-skip-to-help-section
)
434 (set-buffer "*Help*")
435 (toggle-read-only nil
)
436 (goto-char (point-max))
437 (insert "\n\nCurrently defined keys are:
440 --------- -------\n")
441 (mapcar '(lambda (cs) (insert " "
445 ess-help-sec-keys-alist
)
446 (insert "\nFull list of key definitions:\n"
447 (substitute-command-keys
448 "\\{ess-help-sec-map}"))))
450 (defun ess-read-helpobj-name-default (olist)
451 ;;; Returns the object name at point, or else the name of the
452 ;;; function call point is in if that has a help file. A name has a
453 ;;; help file if it is a member of olist.
454 (or (car (assoc (ess-read-object-name-default) olist
))
458 (narrow-to-region (max (point-min) (- (point) 1000))
462 (car (assoc (ess-read-object-name-default) olist
))))
465 (defun ess-find-help-file (p-string)
466 "Find help, prompting for P-STRING. Note that we can't search SAS,
467 Stata or XLispStat for additional information."
468 (ess-make-buffer-current)
471 (string-match "XLS" ess-language
)
472 (string-match "STA" ess-language
)
473 (string-match "SAS" ess-language
)))
474 (let* ((help-files-list (or (ess-get-help-files-list)
477 ess-current-process-name
))))
478 (default (ess-read-helpobj-name-default help-files-list
))
479 (prompt-string (if default
480 (format "%s(default %s) " p-string default
)
482 (spec (completing-read prompt-string help-files-list
)))
484 ((string= spec
"") default
)
486 (let* ((spec (read-string p-string
)))
490 ;;*;; Utility functions
492 (defun ess-get-help-files-list ()
493 "Return a list of files which have help available."
496 (mapcar '(lambda (dirname)
497 (if (file-directory-p dirname
)
498 (directory-files dirname
)))
499 (mapcar '(lambda (str) (concat str
"/.Help"))
500 (ess-search-list))))))
502 (defun ess-nuke-help-bs ()
504 ;;; This function is a modification of nuke-nroff-bs in man.el from the
505 ;;; standard emacs 18 lisp library.
506 ;; Nuke underlining and overstriking (only by the same letter)
507 (goto-char (point-min))
508 (while (search-forward "\b" nil t
)
509 (let* ((preceding (char-after (- (point) 2)))
510 (following (following-char)))
511 (cond ((= preceding following
)
519 (delete-region (1- (point)) (1+ (point)))))))
520 ;; Crunch blank lines
521 (goto-char (point-min))
522 (while (re-search-forward "\n\n\n\n*" nil t
)
523 (replace-match "\n\n"))
524 ;; Nuke blanks lines at start.
525 (goto-char (point-min))
526 (skip-chars-forward "\n")
527 (delete-region (point-min) (point)))
529 (defun ess-help-underline ()
530 "Replace ^_H codes with underline face."
532 (goto-char (point-min))
533 (while (search-forward "_\b" nil t
)
534 (backward-delete-char 2)
535 (put-text-property (point) (1+ (point)) 'face
'underline
))))
539 (defun ess-goto-info (node)
540 "Display node NODE from ess-mode info."
544 (Info-goto-node (concat "(ess)" node
)))
548 (defun ess-submit-bug-report ()
549 "Submit a bug report on the ess-mode package."
553 (let ((reporter-prompt-for-summary-p 't
))
554 (reporter-submit-bug-report
555 "ess-bugs@stat.math.ethz.ch"
556 (concat "ess-mode " ess-version
)
559 'ess-ask-for-ess-directory
560 'ess-ask-about-transfile
563 'ess-source-directory
)
565 (lambda () (goto-char (point-max)) (insert-buffer "*ESS*")))))
572 \f ; Local variables section
574 ;;; This file is automatically placed in Outline minor mode.
575 ;;; The file is structured as follows:
578 ;;; Subsections: ;;;*;;;
579 ;;; Components: defuns, defvars, defconsts
580 ;;; Random code beginning with a ;;;;* comment
584 ;;; mode: outline-minor
585 ;;; outline-regexp: "\^L\\|\\`;\\|;;\\*\\|;;;\\*\\|(def[cvu]\\|(setq\\|;;;;\\*"
588 ;;; ess-help.el ends here