Support for outline-minor-mode

[christophe-gouel]

A lot of programming modes in Emacs support outline-minor-mode out of the box, and all important text modes (org, md and tex) do it too, but ESS does not. This minor mode allows super fast navigation in files with well-structured sections and could be a good complement to imenu (imenu is great for navigating a package but almost useless for a data treatment pipeline with few functions).

I don't know for the other languages supported by ESS, but in R, RStudio has defined a sensible convention for outlines: https://posit.co/blog/rstudio-v1-4-preview-little-things/.

It is trivial to support this convention in Emacs. I have the following piece in my init.el (inside a use-package block) that works perfectly and have completely changed my interaction with R files:

  :hook
  ;; Outlining like in RStudio
  (ess-r-mode . (lambda ()
		  (setq outline-regexp "^[ \t]*#+ +.*\\(----\\|====\\|####\\)")
		  (defun outline-level ()
		    (cond ((looking-at "^[ \t]*# ") 1)
			  ((looking-at "^[ \t]*## ") 2)
			  ((looking-at "^[ \t]*### ") 3)
			  ((looking-at "^[ \t]*#### ") 4)
			  (t 1000)))))

Sure, it could be possible to have a more complete outlining like in python-mode or elisp-mode with support for functions and control flow, but it is likely secondary compared to supporting standard sections.

[christophe-gouel]

I am willing to provide a PR. This would simply add 2 setq-local to ess-r-mode: for outline-regexp and for outline-level.

However, before starting the work, to avoid wasting time, I would like to have feedback on the initiative.

[mmaechler]

For some reasons, I never got much into using outline-minor-mode, but I think other ESS-core / R-core people have used it (KH ?). ... I had been waiting for their reaction after you've opened this.
In any case, your proposal makes a lot of sense and so we should have answered "yes, please!" a while ago.

[christophe-gouel]

For some reasons, I never got much into using outline-minor-mode

For me, what made it stick was using org-mode keybindings for visibility cycling everywhere. Basically, everything is in my config:

(use-package outline
  :hook ((prog-mode text-mode) . outline-minor-mode)
  :custom
  (outline-minor-mode-cycle t) ; Use TAB on heading to cycle
  (outline-minor-mode-use-buttons 'in-margins) ; add in-margin buttons to fold/unfold
  :config
  (unbind-key "RET" outline-overlay-button-map)
  :bind (:map outline-minor-mode-map
	      ([C-tab] . outline-cycle)
	      ([S-tab] . outline-cycle-buffer)
	      ([backtab] . outline-cycle-buffer)))

My other goto tool is the consult-outline function that allows to jump quickly (with preview) to any header.

I will soon propose a PR for ess.

[mmaechler]

Thank you Christophe. I'm sorry I only now realized what the problem was and still is:
It has been raised 18.6 years ago already on the 'ESS-help' mailing list:
https://www.stat.math.ethz.ch/pipermail/ess-help/2006-February/003239.html
by Heinz Tüchler.. the thread got about 6-7 messages long. Do note the answers of Stephen Eglen and A.J. (Tony) Rossini, both very active ESS core members at the time.

Also, what wasn't mentioned there, but I alluded to above. Kurt Hornik (R core & also ESS core) has used outline-minor mode with R source code somewhat routinely.
In the tools package, in code mostly by KH, using M-x grep, I get

-*- mode: grep; default-directory: "......../R/src/library/tools/R/" -*-
Grep started at Wed Oct 29 22:21:08

grepr --color=auto -nHF -e outline-minor *.R
QC.R:10443:### mode: outline-minor ***
Rd.R:1322:### mode: outline-minor ***
Rd2pdf.R:948:### mode: outline-minor ***
Vignettes.R:1398:### mode: outline-minor ***
admin.R:1235:### mode: outline-minor ***
checktools.R:1210:### mode: outline-minor ***
index.R:251:### mode: outline-minor ***
install.R:3293:### mode: outline-minor ***
orcidtools.R:93:### mode: outline-minor ***
rortools.R:88:### mode: outline-minor ***
utils.R:2986:### mode: outline-minor ***

and I see similar usage in quite of my saved 'R CMD check ' outputs, notably the
<pkg>-Ex.Rout files (and hence some of the corresponding <pkg>-Ex.Rout.save files).
The reason for these, most importantly, are the following lines in R's sources

/share/R/examples-footer.R with these lines:

###
### Local variables: ***
### mode: outline-minor ***
### outline-regexp: "\\(> \\)?### [*]+" ***
### End: ***

which indeed "ensures" that the *-Ex.R and *-Ex.Rout.save files which are produced from e.g., R CMD check <pkg> do all have sections that can be hidden or shown, one section corresponding to one help file's examples R code.

[christophe-gouel]

Okay, so you are saying that ESS old-timers use a different convention for outlining.

This is perfectly fine.

First, any local variable would dominate the default configuration. For files that are likely to be shared among various people, it may be a good idea to define the standard directly in the file, as they have done. Second, nothing prevents us from defining various outlining styles, for example, following the example of styling in ess-test-style-alist.

If we don't want to define various styles, I can also give precise instructions in the info file about how to adjust a configuration to follow a different style.

However, for empathy with new ESS users, and because RStudio outlining style has become the de facto standard in the R ecosystem, I think it would be best if it were the default style.

What do you think?

[mmaechler]

>>>> Christophe Gouel >>>> on Thu, 30 Oct 2025 10:09:45 -0700 writes:

christophe-gouel left a comment (emacs-ess/ESS#1318) Okay, so you are saying that ESS old-timers use a different convention for outlining. This is perfectly fine. First, any local variable would dominate the default configuration. For files that are likely to be shared among various people, it may be a good idea to define the standard directly in the file, as they have done. Second, nothing prevents us from defining various outlining styles, for example, following the example of styling in `ess-test-style-alist`. If we don't want to define various styles, I can also give precise instructions in the info file about how to adjust a configuration to follow a different style. However, for empathy with new ESS users, and because RStudio outlining style has become the _de facto_ standard in the R ecosystem, I think it would be best if it were the default style. What do you think? Yaah.. I cannot entirely disagree. I mentioned it earlier, and I believe you, about what Rstudio (and Positron ???) are doing / ... I assume they got it from Markdown... which indeed is much more widely spread now than emacs ever was (KH's style I mentioned *does* follow Emacs Lisp (and I think other such languages style) where more comment characters meant more "title-like" and in R we do follow this style with R comments indentation: # ... indents to column 54 (or something) ## ... stays where you put it ### and #### are Title like and indent to the first column So, I'd say that not only old ESS users but older R users all are used to that ranking, notably from the way ESS indents comments. Your (indirect) proposal to allow more than one outlining style seems good to me, and I think we should at least already provide two different styles, the Rstudio one and the traditional base R (and ESS indentation logic !!) style. Martin

[christophe-gouel]

Good, I will update my PR

[christophe-gouel]

Let's summarize the outline styles we want (feel free to propose other names):

Rstudio

# Section 1 ---- or ==== or ####
## Section 2 ---- or ==== or ####
### Section 3 ---- or ==== or ####
#### Section 4 ---- or ==== or ####

They do not necessarily start from the first column (allowing for nicely sectioning within control flows).

stars
This is the outlining convention used in the tools package. I do not find it to be really lisp-based. The only thing borrowed from lisp is starting with ###, but the sections are indicated by stars. This is slightly weird. If the section levels are defined by stars, there is no need to use 3 #. But it is what it is.

### * Section 1
### ** Section 2
### *** Section 3

lisp-based
The last one you proposed, and that corresponds to another old practice.

### Section 1
#### Section 2
##### Section 3

Any other convention to include?

[mmaechler]

Ehhm, no to your lisp-based one (replacing lisp's ; by R's #).
The big difference is that the number of # has the meaning reversed from RStudio's style:
I'm just using ESS indentation rules
They would lead me to (something like , using LaTeX naming):

#### Chapter
###   Section
##     Subsection
#       Subsubsection [regular comments: inline, actually _end of line_ ]   

The ESS (and I think also R deparser) indentation rules would have

• ### and #### indented to column 0 (in all cases)
• ## indented "in line with the code before it"
• # indented to column 54 (or 40something or so)
  and for that reason: "the more #, the more important / dominant / ... the section level.

[christophe-gouel]

the more #, the more important / dominant / ... the section level.

We may have a problem implementing this: If we don't know in advance what the first outline level is, I don't see how this can be parsed. We can identify the section headers, but not assigned them to a particular level. We have to decide in advance what the first level is. If #### is the standard first level, I could implement it.

A name for this outline approach? reversed-sharp?

[mmaechler]

>>>> Christophe Gouel >>>> on Thu, 13 Nov 2025 00:36:37 -0800 writes:

christophe-gouel left a comment (emacs-ess/ESS#1318) > the more #, the more important / dominant / ... the > section level. We may have a problem implementing this: If we don't know in advance what the first outline level is, I don't see how this can be parsed. We can identify the section headers, but not assigned them to a particular level. We have to decide in advance what the first level is. If `####` is the standard first level, I could implement it. A name for this outline approach? **reversed-sharp**? well.. it's very natural for people knowing lisp and its ;;;; ;;; ;; ; hierarchy. I'd call the Rstudio / Markdown system __reversed__, also as it is historically much younger. I'd call something like the above the "first nation sharp", or "aboriginal sharp" .. or something like that.. ;-) More seriously, as I have not used outline-minor-mode much (rather used outline-mode with R scripts i.e., without inner levels); I think we should get comments from other ESS + R users. Anybody else, please?

[christophe-gouel]

it's very natural for people knowing lisp

Actually, and this is a source of confusion in our exchanges, the elisp outlining convention in Emacs the opposite of what you says:

;;; Section
;;;; Subsection
;;;;; Subsubsection

With ; and ;; introducing standard comments.

This can be seen clearly in lisp-outline-level from lisp-mode.el:

(defun lisp-outline-level ()
  "Lisp mode `outline-level' function."
  ;; Expects outline-regexp is ";;;\\(;* [^ \t\n]\\|###autoload\\)\\|("
  ;; and point is at the beginning of a matching line.
  (let ((len (- (match-end 0) (match-beginning 0))))
    (cond ((or (looking-at-p "(")
               (looking-at-p lisp-mode-autoload-regexp))
           1000)
          ((looking-at ";;\\(;+\\) ")
           (- (match-end 1) (match-beginning 1)))
          ;; Above should match everything but just in case.
          (t
           len))))

and in

(setq-local outline-regexp (concat ";;;;* [^ \t\n]\\|(\\|\\("
                                     lisp-mode-autoload-regexp
                                     "\\)"))

[mmaechler]

aah... indeed, a source for confusion! Ashes on my head!

[bastistician]

A quick comment from just stumbling across this issue. Personally, I also haven't used outline-minor-mode yet, but I think it would be nice if ESS had support for it for easier adoption.

Re the styles summarized in #1318 (comment):

• Markdown rules with # corresponding to h1, ## to h2, etc. would require ESS to indent # lines in the same way as ## (which I'd prefer anyway).
• "stars" (actually "org") is clearly influenced by ESS indentation rules, in that ### ensures a first-column position. I have seen this style only in the 'tools' package. It has the advantage that it clearly disambiguates code comments and section headers.
• "lisp-based" is simpler but I haven't seen it in the wild. It also has to use at least three hashes to disable indentation and to not interfere with normal code comments, which typically use # or ##.

I tend to use ## both for comments and structuring (which sometimes bothers me), and # only for trailing comments (because I don't like the otherwise centered indentation). So for an outline-minor-mode it does not currently make sense to me to consider # or ##. For sections I usually use ###, sometimes even with more visual separation, surrounded by a line of hashes. I rarely need more levels, otherwise I'd probably split the script.