branch: externals/ess
commit a3301e64c78619d8c43a0fcdf96d0d6f7b437ac5
Author: Christophe Gouel <[email protected]>
Commit: Martin Mächler <[email protected]>
docs(ess): Clarify RStudio outline style
Explain handling of single-hash comments and recommend setting
ess-indent-with-fancy-comments to nil or ess-style to 'RStudio.
Update manual and ess-r-outline-style docstring to describe behavior
and examples.
---
doc/ess.texi | 9 +++++++--
lisp/ess-custom.el | 9 +++++++--
2 files changed, 14 insertions(+), 4 deletions(-)
diff --git a/doc/ess.texi b/doc/ess.texi
index 74b3b6eb7e..677c5288e3 100644
--- a/doc/ess.texi
+++ b/doc/ess.texi
@@ -3108,8 +3108,13 @@ RStudio.
#### Helpers ####
@end example
-The number of leading @samp{#} characters sets the outline depth. Use
-standard Outline commands (such as @kbd{C-c @ C-t}) to cycle visibility once
+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.
+
+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
mode hook:
diff --git a/lisp/ess-custom.el b/lisp/ess-custom.el
index 2b051dd376..ac8aa63464 100644
--- a/lisp/ess-custom.el
+++ b/lisp/ess-custom.el
@@ -1573,8 +1573,13 @@ by `ess-function-template'."
(defcustom ess-r-outline-style 'RStudio
"Outline convention used by `ess-r-mode'.
-Choose between the comment rulers like RStudio and the \"stars\" headings
- (\"### ***\")."
+Choose between comment rulers like RStudio (\"### Section title ----\")
+and \"stars\" 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."
:group 'ess-R
:type '(choice (const :tag "RStudio comment rulers" RStudio)
(const :tag "Stars (### *** headings)" stars))
