You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
463 lines
16 KiB
463 lines
16 KiB
;; ess-rd.el --- Support for editing R documentation (Rd) source -*- lexical-binding: t; -*-
|
|
|
|
;; Copyright (C) 1997--2005 A.J. Rossini, Richard M. Heiberger, Martin
|
|
;; Maechler, Kurt Hornik, Rodney Sparapani, and Stephen Eglen.
|
|
|
|
;; Author: KH <Kurt.Hornik@ci.tuwien.ac.at>
|
|
;; Created: 25 July 1997
|
|
;; Maintainer: ESS-core <ESS-core@r-project.org>
|
|
|
|
;; This file is part of ESS (Emacs Speaks Statistics).
|
|
|
|
;; This file is free software; you may redistribute it and/or modify it
|
|
;; under the terms of the GNU General Public License as published by the
|
|
;; Free Software Foundation; either version 2, or (at your option) any
|
|
;; later version.
|
|
;;
|
|
;; This is distributed in the hope that it will be useful, but WITHOUT
|
|
;; ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
|
|
;; FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
|
|
;; for more details.
|
|
;;
|
|
;; A copy of the GNU General Public License is available on the World
|
|
;; Wide Web at https://www.gnu.org/copyleft/gpl.html. You can also
|
|
;; obtain it by writing to the Free Software Foundation, Inc., 675 Mass
|
|
;; Ave, Cambridge, MA 02139, USA.
|
|
|
|
|
|
;;; Commentary:
|
|
;;
|
|
|
|
;;; Code:
|
|
(eval-when-compile
|
|
(require 'subr-x))
|
|
|
|
(require 'ess-help)
|
|
(require 'ess-inf)
|
|
;; Silence the byte compiler, see TODO below; can we remove these?
|
|
(defvar ess-help-r-sec-regex)
|
|
(defvar ess-help-r-sec-keys-alist)
|
|
(defvar ess-r-customize-alist)
|
|
|
|
(defcustom Rd-mode-hook nil
|
|
"Hook to be run when Rd mode is entered."
|
|
:type 'hook
|
|
:group 'ess-R
|
|
:group 'ess-hooks)
|
|
|
|
(define-abbrev-table 'Rd-mode-skeleton-abbrev-table
|
|
'(("`ag" "\\arguments" nil :system t)
|
|
("`al" "\\alias" nil :system t)
|
|
("`au" "\\author" nil :system t)
|
|
("`bf" "\\bold" nil :system t)
|
|
("`co" "\\code" nil :system t)
|
|
("`de" "\\describe" nil :system t)
|
|
("`dn" "\\description" nil :system t)
|
|
("`dt" "\\details" nil :system t)
|
|
("`em" "\\emph" nil :system t)
|
|
("`en" "\\enumerate" nil :system t)
|
|
("`ex" "\\examples" nil :system t)
|
|
("`fi" "\\file" nil :system t)
|
|
("`fo" "\\format" nil :system t)
|
|
("`it" "\\item" nil :system t)
|
|
("`iz" "\\itemize" nil :system t)
|
|
("`kw" "\\keyword" nil :system t)
|
|
("`li" "\\link" nil :system t)
|
|
("`me" "\\method" nil :system t)
|
|
("`na" "\\name" nil :system t)
|
|
("`no" "\\note" nil :system t)
|
|
("`re" "\\references" nil :system t)
|
|
("`sa" "\\seealso" nil :system t)
|
|
("`se" "\\section" nil :system t)
|
|
("`so" "\\source" nil :system t)
|
|
("`ss" "\\subsection" nil :system t)
|
|
("`sy" "\\synopsis" nil :system t)
|
|
("`ta" "\\tabular" nil :system t)
|
|
("`ti" "\\title" nil :system t)
|
|
("`us" "\\usage" nil :system t)
|
|
("`va" "\\value" nil :system t))
|
|
"Abbrev table for R documentation keywords.
|
|
All Rd mode abbrevs start with a grave accent (`)."
|
|
:case-fixed t)
|
|
|
|
(define-abbrev-table 'Rd-mode-abbrev-table ()
|
|
"Abbrev table for Rd mode."
|
|
:parents (list Rd-mode-skeleton-abbrev-table))
|
|
|
|
(defvar Rd-mode-syntax-table
|
|
(let ((tab (copy-syntax-table text-mode-syntax-table)))
|
|
(modify-syntax-entry ?\\ "\\" tab)
|
|
(modify-syntax-entry ?\{ "(}" tab)
|
|
(modify-syntax-entry ?\} "){" tab)
|
|
;; Nice for editing, not for parsing ...
|
|
(modify-syntax-entry ?\( "()" tab)
|
|
(modify-syntax-entry ?\) ")(" tab)
|
|
(modify-syntax-entry ?\[ "(]" tab)
|
|
(modify-syntax-entry ?\] ")[" tab)
|
|
;; To get strings right
|
|
;; (modify-syntax-entry ?\' "\"" Rd-mode-syntax-table)
|
|
(modify-syntax-entry ?\" "\"" tab)
|
|
;; To make abbrevs starting with a grave accent work ...
|
|
(modify-syntax-entry ?\` "w" tab)
|
|
;; Comments
|
|
(modify-syntax-entry ?\% "<" tab)
|
|
(modify-syntax-entry ?\n ">" tab)
|
|
tab)
|
|
"Syntax table for `Rd-mode'.")
|
|
|
|
(defvar Rd-mode-parse-syntax-table
|
|
(let ((tab (copy-syntax-table Rd-mode-syntax-table)))
|
|
;; To make parse-partial-sexps do the thing we want for computing
|
|
;; indentations
|
|
(modify-syntax-entry ?\( "_" tab)
|
|
(modify-syntax-entry ?\) "_" tab)
|
|
(modify-syntax-entry ?\[ "_" tab)
|
|
(modify-syntax-entry ?\] "_" tab)
|
|
tab)
|
|
"Syntax table for parsing Rd mode.")
|
|
|
|
(defvar Rd-section-names
|
|
'("Rdversion" "arguments" "alias" "author" "concept" "describe" "description"
|
|
"details" "docType" "encoding" "enumerate" "examples" "format"
|
|
"itemize" "keyword" "name" "note" "preformatted" "references"
|
|
"seealso" "section" "source" "subsection" "synopsis"
|
|
"tabular" "title" "usage"
|
|
"value"))
|
|
|
|
(defvar Rd-keywords
|
|
'(
|
|
;; the next two lines: only valid in R <= 2.8.1
|
|
;; commented out on 2011-01-14 for ESS version 5.13:
|
|
;; "Alpha" "Gamma" "alpha" "beta" "epsilon" "lambda" "mu" "pi" "sigma"
|
|
;; "ge" "le" "left" "right"
|
|
;;
|
|
"R" "RdOpts" "S3method" "S4method" "Sexpr" "acronym"
|
|
"bold" "cite" "code" "command" "cr" "dQuote" "deqn" "dfn" "dontrun"
|
|
"dontshow" "donttest" "dots" "email" "emph" "enc" "env" "eqn" "figure" "file"
|
|
"href" "if" "ifelse"
|
|
"item" "kbd" "ldots" "linkS4class" "link" "method"
|
|
"newcommand" "option" "out"
|
|
"pkg" "sQuote" "renewcommand"
|
|
"samp" "strong" "tab" "url" "var" "verb"
|
|
;; System macros (from <R>/share/Rd/macros/system.Rd ):
|
|
"CRANpkg" "PR" "sspace" "doi"
|
|
"packageTitle" "packageDescription" "packageAuthor"
|
|
"packageMaintainer" "packageDESCRIPTION" "packageIndices"
|
|
))
|
|
|
|
(defvar Rd-font-lock-keywords
|
|
(list
|
|
(cons
|
|
(concat "\\\\\\("
|
|
(mapconcat 'identity Rd-section-names "\\|")
|
|
"\\>\\)")
|
|
'font-lock-reference-face) ; Rd-bold-face
|
|
(cons
|
|
(concat "\\\\\\("
|
|
(mapconcat 'identity Rd-keywords "\\|")
|
|
"\\>\\)")
|
|
'font-lock-keyword-face)
|
|
'("^#\\(ifn?def\\)\\s-+\\(\\sw+\\)"
|
|
(1 font-lock-builtin-face)
|
|
(2 font-lock-variable-name-face nil t))
|
|
'("^#\\(endif\\)" 1 font-lock-builtin-face))
|
|
"Additional Rd expressions to highlight.")
|
|
|
|
(defvar Rd-indent-level 2
|
|
"Indentation of Rd code with respect to containing blocks.")
|
|
|
|
(defvar Rd-mode-map
|
|
(let ((map (make-sparse-keymap)))
|
|
(define-key map "\t" #'indent-according-to-mode)
|
|
(define-key map "\C-j" #'reindent-then-newline-and-indent)
|
|
(define-key map "\C-m" #'reindent-then-newline-and-indent)
|
|
(define-key map "\C-c\C-p" #'Rd-preview-help)
|
|
(define-key map "\C-c\C-j" #'Rd-mode-insert-item)
|
|
(define-key map "\C-c\C-e" #'Rd-mode-insert-skeleton)
|
|
(define-key map "\C-c\C-f" #'Rd-font)
|
|
(define-key map "\C-c\C-s" #'Rd-mode-insert-section)
|
|
(define-key map "\C-c\C-n" #'ess-eval-line-visibly-and-step)
|
|
(define-key map "\C-c\C-r" #'ess-eval-region)
|
|
(define-key map "\C-c\C-c" #'ess-eval-region-or-function-or-paragraph-and-step)
|
|
(define-key map "\C-\M-x" #'ess-eval-region-or-function-or-paragraph)
|
|
(define-key map "\C-c\C-v" #'ess-display-help-on-object)
|
|
(define-key map "\C-c\C-w" #'ess-switch-process)
|
|
(define-key map "\C-c\C-y" #'ess-switch-to-ESS)
|
|
(define-key map "\C-c\C-z" #'ess-switch-to-end-of-ESS)
|
|
map)
|
|
"Keymap used in Rd mode.")
|
|
|
|
(defvar Rd-mode-menu
|
|
(list "Rd"
|
|
["Markup [word]" Rd-font t]
|
|
["Insert Item" Rd-mode-insert-item t]
|
|
["Insert Section" Rd-mode-insert-section t]
|
|
["Insert Skeleton" Rd-mode-insert-skeleton t]
|
|
"-"
|
|
["Preview" Rd-preview-help t]
|
|
"-"
|
|
["Eval Line" ess-eval-line-visibly-and-step t]
|
|
["Eval Region" ess-eval-region t]
|
|
["Switch to ESS Process" ess-switch-to-ESS t]
|
|
["Switch the ESS Process" ess-switch-process t]
|
|
["Switch to end{ESS Pr}" ess-switch-to-end-of-ESS t]
|
|
"-"
|
|
["Toggle Abbrev Mode" abbrev-mode t]
|
|
["Toggle Auto-Fill Mode" auto-fill-mode t]
|
|
"-"
|
|
["Submit Bug Report" ess-submit-bug-report t]
|
|
"-"
|
|
["Describe Rd Mode" describe-mode t])
|
|
"Menu used in Rd mode.")
|
|
|
|
(defvar Rd-to-help-command "R CMD Rd2txt"
|
|
"Shell command for converting R documentation source to help text.")
|
|
|
|
(defvar Rd-font-list
|
|
'((?\C-b "\\bold{" "}")
|
|
(?\C-c "\\code{" "}")
|
|
(?\C-e "\\emph{" "}")
|
|
(?\C-l "\\link{" "}")
|
|
(?l "\\code{\\link{" "}}")
|
|
(?\C-m "\\email{" "}")
|
|
(?\C-q "\\eqn{" "}")
|
|
(?\C-u "\\url{" "}")
|
|
)
|
|
"List of \"fonts\" used by `Rd-font'.
|
|
Each entry is a list. The first element is the key to activate
|
|
the font. The second element is the string to insert before
|
|
point, and the third element is the string to insert after
|
|
point.")
|
|
|
|
|
|
;;;###autoload
|
|
(define-derived-mode Rd-mode text-mode "Rd"
|
|
"Major mode for editing R documentation source files.
|
|
|
|
Type \\[list-abbrevs] to display the built-in abbrevs for Rd
|
|
keywords.To automatically turn on the abbrev(iate) features, add
|
|
the following to your Emacs configuration file:
|
|
|
|
(add-hook 'Rd-mode-hook #'abbrev-mode)"
|
|
(setq ess-language "S" ess-dialect "R")
|
|
(require 'ess-r-mode)
|
|
(ess-setq-vars-local ess-r-customize-alist)
|
|
|
|
(setq-local indent-line-function 'Rd-mode-indent-line)
|
|
(setq fill-column 72)
|
|
(setq-local comment-start-skip "\\s<+\\s-*")
|
|
(setq-local comment-start "% ")
|
|
(setq-local comment-end "")
|
|
(setq font-lock-defaults
|
|
'(Rd-font-lock-keywords nil nil))
|
|
|
|
;; Here is a workaround for an Emacs bug related to indirect buffers and
|
|
;; spurious lockfiles that rears its ugly head with .Rd files
|
|
;; https://lists.gnu.org/archive/html/bug-gnu-emacs/2013-02/msg01368.html
|
|
;; https://debbugs.gnu.org/cgi/bugreport.cgi?bug=14328
|
|
(setq-local create-lockfiles nil)
|
|
|
|
(easy-menu-define Rd-mode-menu-map Rd-mode-map
|
|
"Menu keymap for Rd mode." Rd-mode-menu)
|
|
|
|
(turn-on-auto-fill))
|
|
|
|
;;;###autoload
|
|
(add-to-list 'auto-mode-alist '("\\.Rd\\'" . Rd-mode))
|
|
|
|
(defun Rd-describe-major-mode ()
|
|
"Describe the current major mode."
|
|
(declare (obsolete describe-mode "ESS 19.04"))
|
|
(describe-function major-mode))
|
|
|
|
(defun Rd-mode-in-verbatim-p ()
|
|
"Return non-nil if in a usage, examples, or synopsis."
|
|
(let ((pos (point)))
|
|
(save-excursion
|
|
(if (and (re-search-backward
|
|
"\\\\\\(usage\\|examples\\|synopsis\\)" nil t)
|
|
(re-search-forward "\\s(" nil t))
|
|
(condition-case ()
|
|
(progn
|
|
(up-list 1)
|
|
(< pos (point)))
|
|
(error t))
|
|
nil))))
|
|
|
|
(defun Rd-mode-in-preprocessor-line-p ()
|
|
"Return non-nil if in a preprocessor line."
|
|
(save-excursion
|
|
(beginning-of-line)
|
|
(looking-at "[ \t]*#\\(ifdef\\|endif\\)")))
|
|
|
|
(defun Rd-mode-calculate-indent ()
|
|
"Return appropriate indentation for current line in Rd mode."
|
|
(save-excursion
|
|
(beginning-of-line)
|
|
(cond
|
|
((Rd-mode-in-verbatim-p)
|
|
;; Don't do anything in verbatims
|
|
nil)
|
|
((Rd-mode-in-preprocessor-line-p)
|
|
;; Indent to 0
|
|
0)
|
|
(t
|
|
(let ((p (progn
|
|
(re-search-forward "[ \t]*\\s)*" (point-at-eol) t)
|
|
(point))))
|
|
(if (or (< (forward-line -1) 0)
|
|
(Rd-mode-in-verbatim-p))
|
|
0
|
|
(set-syntax-table Rd-mode-parse-syntax-table)
|
|
(while (and (or (looking-at "[ \t]*$")
|
|
(Rd-mode-in-preprocessor-line-p))
|
|
(not (bobp)))
|
|
(forward-line -1))
|
|
(re-search-forward "[ \t]*\\s)*" (point-at-eol) t)
|
|
(prog1
|
|
(+ (current-indentation)
|
|
(* (car (parse-partial-sexp (point) p))
|
|
Rd-indent-level))
|
|
(set-syntax-table Rd-mode-syntax-table))))))))
|
|
|
|
(defun Rd-mode-indent-line ()
|
|
"Indent current line as Rd source."
|
|
(when-let ((ic (Rd-mode-calculate-indent))
|
|
(rp (- (current-column) (current-indentation))))
|
|
(when (< ic 0)
|
|
(error "Unmatched parenthesis"))
|
|
(indent-line-to ic)
|
|
(when (> rp 0)
|
|
(move-to-column (+ ic rp)))))
|
|
|
|
(defun Rd-mode-insert-item ()
|
|
"Insert \\item{ on a newline."
|
|
(interactive)
|
|
(reindent-then-newline-and-indent)
|
|
(insert "\\item{")
|
|
)
|
|
|
|
(defun Rd-mode-insert-section ()
|
|
"Insert a section from `Rd-section-names'."
|
|
(interactive)
|
|
(let ((s (ess-completing-read
|
|
"Insert section: "
|
|
(mapcar (lambda (x) (cons x x)) Rd-section-names)
|
|
nil t)))
|
|
(if (string= s "")
|
|
(progn (insert "\\section{}{") (backward-char 2))
|
|
(insert (format "\\%s{" s)))))
|
|
|
|
(defun Rd-mode-insert-skeleton ()
|
|
"Insert several empty Rd fields."
|
|
(interactive)
|
|
;; Hmm: in theory this should be kept in sync with prompt()
|
|
;; --- maybe using prompt() [or promptClass()...] would be better anyway?!
|
|
(insert "\\name{}\n")
|
|
(insert "\\alias{}\n")
|
|
(insert "\\title{}\n")
|
|
(insert "\\description{\n}\n")
|
|
(insert "\\usage{\n}\n")
|
|
(insert "\\arguments{\n}\n")
|
|
(insert "\\value{\n}\n")
|
|
(insert "\\details{\n}\n")
|
|
(insert "\\references{\n}\n")
|
|
(insert "\\seealso{\n}\n")
|
|
(insert "\\examples{\n}\n")
|
|
(insert "\\author{}\n")
|
|
(insert "\\keyword{}\n"))
|
|
|
|
;; This is an `easy' version of (defun TeX-font ..) in AUCtex's tex.el ;
|
|
;; see TeX-font-list and also LaTeX-font-list in latex.el
|
|
|
|
(defun Rd-font (what)
|
|
"Insert template for font command.
|
|
WHAT determines the font to use, as specified by `Rd-font-list'."
|
|
(interactive "c")
|
|
;;TeX had : (Rd-update-style)
|
|
(let* ((entry (assoc what Rd-font-list))
|
|
(before (nth 1 entry))
|
|
(after (nth 2 entry)))
|
|
(cond ((null entry) ;; help on possibilities :
|
|
(let ((help
|
|
(concat
|
|
"Rd Markup (available from C-c C-f):\n\n\t"
|
|
"KEY Rd-Markup\n\n"
|
|
(mapconcat
|
|
(lambda (entry)
|
|
;; A textual description of an ENTRY in TeX-font-list.
|
|
(concat (format "%11s "
|
|
(key-description
|
|
(char-to-string (nth 0 entry))))
|
|
(format "%14s %-3s"
|
|
(nth 1 entry) (nth 2 entry))))
|
|
Rd-font-list "\n"))))
|
|
(with-output-to-temp-buffer "*Help*"
|
|
(set-buffer "*Help*")
|
|
(insert help))))
|
|
|
|
((region-active-p)
|
|
(save-excursion
|
|
(cond ((> (mark) (point))
|
|
(insert before)
|
|
(goto-char (mark))
|
|
(insert after))
|
|
(t
|
|
(insert after)
|
|
(goto-char (mark))
|
|
(insert before)))))
|
|
(t
|
|
(insert before)
|
|
(save-excursion
|
|
(insert after))))))
|
|
|
|
(defun Rd-preview-help (&optional via-shell)
|
|
"Preview the current Rd buffer contents as help.
|
|
If the current buffer is not associated with a file, create a
|
|
temporary one in variable `temporary-file-directory'."
|
|
(declare (advertised-calling-convention () "ESS 19.04"))
|
|
(interactive "P") ; If optional VIA-SHELL is set, using `Rd-to-help-command'.
|
|
(let ((file buffer-file-name)
|
|
(pbuf (get-buffer-create "R Help Preview"))
|
|
del-p)
|
|
(unless file
|
|
(setq file (make-temp-file "RD_" nil ".Rd"))
|
|
(write-region (point-min) (point-max) file)
|
|
(setq del-p t))
|
|
|
|
(if via-shell ;; FIXME eventually get rid of this option
|
|
;; only method in ESS <= 14.09 -- calls "R" even if in "R-devel"; slower
|
|
(let ((shcmd (format "%s '%s'" Rd-to-help-command file)))
|
|
(set-buffer pbuf)
|
|
(erase-buffer)
|
|
(ess-write-to-dribble-buffer
|
|
(format "Rd-preview-help: (shell-command |%s| t)" shcmd))
|
|
(shell-command shcmd t))
|
|
;; else directly:
|
|
(ess-force-buffer-current "R process to use: ")
|
|
(ess-command (format ".ess_Rd2txt(\"%s\")\n" file) pbuf)
|
|
(set-buffer pbuf))
|
|
|
|
;; FIXME(2): once got rid of via-shell, consider
|
|
;; (ess--flush-help-into-current-buffer file "tools::Rd2txt(\"%s\")\n")
|
|
;; instead of all this :
|
|
(ess-setq-vars-local ess-r-customize-alist)
|
|
;; mostly cut'n'paste from ess--flush-help* (see FIXME(2)):
|
|
(ess-help-underline)
|
|
(ess--help-major-mode)
|
|
;; FIXME: Is this really needed?
|
|
(setq ess-help-sec-regex ess-help-r-sec-regex
|
|
ess-help-sec-keys-alist ess-help-r-sec-keys-alist)
|
|
(goto-char (point-min))
|
|
(set-buffer-modified-p 'nil)
|
|
(setq buffer-read-only t)
|
|
(setq truncate-lines nil)
|
|
(when del-p (delete-file file))
|
|
(unless (get-buffer-window pbuf 'visible)
|
|
(display-buffer pbuf t))))
|
|
|
|
(define-obsolete-function-alias 'Rd-submit-bug-report 'ess-submit-bug-report "2018-08-16")
|
|
|
|
(provide 'ess-rd)
|
|
|
|
;;; ess-rd.el ends here
|