branch: externals/ess
commit c95cf87ccb5bc7784f0fbce390b7fe1e3b6c1f66
Author: Christophe Gouel <[email protected]>
Commit: Martin Mächler <[email protected]>
Add a default outline style and automatically handle conflicts between
options
---
ChangeLog | 15 +++++++++++++++
doc/ess.texi | 21 +++++++++++++--------
lisp/ess-custom.el | 20 +++++++++++---------
lisp/ess-r-mode.el | 53 ++++++++++++++++++++++++++++++++++++++++++++++++-----
4 files changed, 87 insertions(+), 22 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index bb8e3d0edd..b0af3e7f99 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,18 @@
+2026-01-25 Christophe Gouel <[email protected]>
+
+ * lisp/ess-custom.el (ess-r-outline-style): Change default from
+ 'RStudio to 'none for backward compatibility. Add 'none option to
+ preserve previous behavior where outline support was not active.
+ Update docstring to document automatic adjustment of
+ ess-indent-with-fancy-comments.
+ * lisp/ess-r-mode.el (ess-r--outline-level-none)
+ (ess-r--saved-indent-with-fancy-comments): Add support for 'none
+ outline style. Automatically set ess-indent-with-fancy-comments to
+ nil when using RStudio style, and restore previous value when
+ switching away.
+ * doc/ess.texi (Outline navigation): Document 'none as default,
+ explain automatic adjustment of ess-indent-with-fancy-comments.
+
2026-01-04 Christophe Gouel <[email protected]>
* lisp/ess-custom.el (ess-r-outline-style) (ess-r-outline-regexp):
diff --git a/doc/ess.texi b/doc/ess.texi
index 91b1942b6d..ac2cf07872 100644
--- a/doc/ess.texi
+++ b/doc/ess.texi
@@ -3095,7 +3095,9 @@ toggle the minor mode (for example via @kbd{M-x
outline-minor-mode} or
by adding it to @code{ess-r-mode-hook}), ESS assigns
@code{ess-r-outline-level} to @code{outline-level} and configures
@code{outline-regexp} according to @code{ess-r-outline-style} so that
-comment headings drive folding. With the default @code{RStudio} style,
+comment headings drive folding. By default, outline support is disabled
+(@code{none}), but you can enable it by setting @code{ess-r-outline-style}
+to @code{RStudio} or @code{Org-like}. With the @code{RStudio} style,
lines that begin with one or more @samp{#}, followed by text and a
trailing marker of @samp{----}, @samp{====}, or @samp{####}, are treated
as outline headings. This matches the section markers convention adopted by
@@ -3109,10 +3111,12 @@ RStudio.
@end example
The number of leading @samp{#} characters sets the outline depth. When using
-this outline style, it is recommended to use
-@code{setq ess-indent-with-fancy-comments nil} or
-@code{setq ess-style 'RStudio}. Otherwise, single-hash comments are treated as
-right-margin comments with comment-column 40.
+the RStudio outline style, @code{ess-indent-with-fancy-comments} is
+automatically set to @code{nil} locally in the buffer to prevent single-hash
+comments from being treated as right-margin comments with @code{comment-column}
+40. When switching back to a different outline style, the original local
+binding is restored; if the variable was not buffer-local, the current global
+default applies.
Use standard Outline commands (such as @kbd{C-c @ C-t}) to cycle visibility
once
the minor mode is active. To enable Outlining automatically, add it to the R
@@ -3124,9 +3128,10 @@ mode hook:
@defvr {User Option} ess-r-outline-style
Select which outline convention @code{ess-r-mode} should use. The
-default @code{RStudio} style recognises the comment rulers shown above.
-Choose @code{Org-like} to match the @samp{### * Section} pattern,
-inspired from org-mode:
+default @code{none} disables outline support to preserve backward
+compatibility. Set to @code{RStudio} to recognise the comment rulers
+shown above, or choose @code{Org-like} to match the @samp{### * Section}
+pattern, inspired from org-mode:
@example
### * Setup
diff --git a/lisp/ess-custom.el b/lisp/ess-custom.el
index 36d50f9097..b7686175f9 100644
--- a/lisp/ess-custom.el
+++ b/lisp/ess-custom.el
@@ -1571,17 +1571,19 @@ by `ess-function-template'."
:group 'ess
:type 'regexp)
-(defcustom ess-r-outline-style 'RStudio
+(defcustom ess-r-outline-style 'none
"Outline convention used by `ess-r-mode'.
-Choose between comment rulers like RStudio (\"### Section title ----\")
-and \"Org-like\" headings \(\"### *** Section title\").
-
-When using the RStudio outline style, it is recommended to use \(setq
-ess-indent-with-fancy-comments nil) or \(setq ess-style 'RStudio).
-Otherwise, single-hash comments are treated as right-margin comments
-with `comment-column' 40."
+Choose between comment rulers like RStudio (\"### Section title ----\"),
+\"Org-like\" headings \(\"### *** Section title\"), or no outline support.
+
+When using the RStudio outline style, `ess-indent-with-fancy-comments'
+is automatically set to nil locally in the buffer. When switching back,
+the original local binding is restored; if the variable was not
+buffer-local, the current global default applies. You can also use
+\(setq ess-style 'RStudio) to achieve the same effect globally."
:group 'ess-R
- :type '(choice (const :tag "RStudio comment rulers" RStudio)
+ :type '(choice (const :tag "No outline support" none)
+ (const :tag "RStudio comment rulers" RStudio)
(const :tag "Org-Like (### *** headings)" Org-like))
:safe #'symbolp)
diff --git a/lisp/ess-r-mode.el b/lisp/ess-r-mode.el
index 2a8a0e2a3f..b483107036 100644
--- a/lisp/ess-r-mode.el
+++ b/lisp/ess-r-mode.el
@@ -333,8 +333,15 @@ namespace.")
(length (match-string 1))
1000)))
+(defun ess-r--outline-level-none ()
+ "Dummy outline level function for no outline support."
+ 1000)
+
(defconst ess-r-outline-style-alist
- `((RStudio
+ `((none
+ (outline-regexp . "\\`a\\`")
+ (outline-level . ,#'ess-r--outline-level-none))
+ (RStudio
(outline-regexp . ,ess-r--outline-rstudio-regexp)
(outline-level . ,#'ess-r--outline-level-rstudio))
(Org-like
@@ -346,18 +353,54 @@ namespace.")
"R mode `outline-level` dispatcher for the current outline style."
(funcall (ess-r--outline-style-value 'outline-level)))
+(defvar-local ess-r--saved-indent-with-fancy-comments nil
+ "Saved state of `ess-indent-with-fancy-comments' before RStudio style.
+Stored as (VALUE . WAS-LOCAL) to restore both value and local binding.")
+
(defun ess-r-set-outline-style (&optional style)
- "Apply STYLE (or `ess-r-outline-style') to the current buffer."
+ "Apply STYLE (or `ess-r-outline-style') to the current buffer.
+
+When switching to RStudio style, `ess-indent-with-fancy-comments' is
+automatically set to nil locally. The previous value is saved and
+restored when switching to a different style."
(interactive
(list (intern (completing-read
"Outline style"
(mapcar (lambda (entry) (symbol-name (car entry)))
ess-r-outline-style-alist)
nil t nil nil
- (symbol-name (or ess-r-outline-style 'RStudio))))))
+ (symbol-name (or ess-r-outline-style 'none))))))
(let* ((style (or style ess-r-outline-style))
- (entry (ess-r--outline-style-definition style)))
- (setq-local ess-r-outline-style (car entry))
+ (entry (ess-r--outline-style-definition style))
+ (old-style ess-r-outline-style)
+ (new-style (car entry)))
+ ;; Handle ess-indent-with-fancy-comments adjustment
+ (cond
+ ;; Switching TO RStudio style
+ ((and (eq new-style 'RStudio)
+ (not (eq old-style 'RStudio)))
+ ;; Save current value if not already saved
+ (unless ess-r--saved-indent-with-fancy-comments
+ (setq ess-r--saved-indent-with-fancy-comments
+ (cons (if (local-variable-p 'ess-indent-with-fancy-comments)
+ ess-indent-with-fancy-comments
+ (default-value 'ess-indent-with-fancy-comments))
+ (local-variable-p 'ess-indent-with-fancy-comments))))
+ (setq-local ess-indent-with-fancy-comments nil))
+ ;; Switching FROM RStudio style to another
+ ((and (eq old-style 'RStudio)
+ (not (eq new-style 'RStudio))
+ ess-r--saved-indent-with-fancy-comments)
+ ;; Restore saved value and local state
+ (let ((saved-value (car ess-r--saved-indent-with-fancy-comments))
+ (saved-local (cdr ess-r--saved-indent-with-fancy-comments)))
+ (if saved-local
+ (setq-local ess-indent-with-fancy-comments saved-value)
+ (when (local-variable-p 'ess-indent-with-fancy-comments)
+ (kill-local-variable 'ess-indent-with-fancy-comments))))
+ (setq ess-r--saved-indent-with-fancy-comments nil)))
+ ;; Apply outline style
+ (setq-local ess-r-outline-style new-style)
(setq-local outline-regexp (ess-r--outline-style-value 'outline-regexp
style))
(setq-local outline-level #'ess-r-outline-level)))
