Hard Wrap R Markdown and other text files

[colearendt]

To facilitate easier Github PRs, it would be nice to have the ability to enable automatic "hard-wrapping" of RMarkdown files.

This is possible in RStudio today in vim-mode. Highlight text visually (i.e. select line with V) and then gq to reflow. Not sure how to edit the wrap length, as :set textwidth is not working.

@scottmmjackson

[colearendt]

Also, to undo hard wraps during the editing process, visual select with V and then type J to remove hard wraps.

[jmcphers]

The thing you're doing with Vim mode can also be done without it. There's a Code -> Reflow Comment command which will hard-wrap anything (not just comments). The text width is set using the Margin Column setting in Options -> Code -> Display; even if the margin is not shown, it affects wrapping.

That said I'm guessing you're looking for a lower-friction experience. Are you thinking of reflow-as-you-type, reflow-on-save, or something else?

(cc @yihui who if memory serves has been interested in this feature in the past)

[yihui]

Your memory is amazing! Yes, I wanted reflow-as-I-type a number of years ago. That was one thing I missed most when I switched from Emacs to RStudio. Now I don't care as much.

[colearendt]

Yeah, my thought was more a reflow-as-you-type option to activate. Reflow-on-save seems a little more shady, since the file would be changed on save, which is not super intuitive.

[jmcphers]

@colearendt FWIW It's pretty common in some environments to clean things up on save (for example gofmt is traditionally run on save), and in fact we already have an option which does this -- you can have whitespace trimmed when you save.

However I'm with you in this instance; since saving a document is something you do to the whole document, the expectation is that the formatter will run on the whole document, too. Unless someone writes the equivalent of gofmt for R Markdown files, we probably don't want to attempt anything nearly so aggressive.

[jmcphers]

Had a talk with @jennybc about this. We think this could make this a lot better with very little additional effort by having the existing Reflow Comment command work against the current paragraph in R Markdown files when there's no text selected (right now invoking it with no selection causes the entire document to be reflowed as if it were a single comment, which is obviously wrong). With this change you'd just tap the reflow command from time to time as you edited in Markdown paragraphs.

Related, but perhaps out of scope for this discussion: @jennybc also mentioned that it'd be helpful for Reflow Comment to act only on the current paragraph when reflowing comments in a Roxygen comment.

[yihui]

Something like gofmt for R Markdown might be possible. I can spend some time on it (perhaps in June).

For roxygen comments, I'd prefer reflowing all lines instead of the current paragraph, because I think it is unlikely that you only want to reflow a particular paragraph but not others (i.e., you either wrap all lines or none). The only problem (not sure if it has been resolved) is \preformatted{} should not be wrapped when reflowing all roxygen comments.

[jennybc]

For roxygen comments, I'd prefer reflowing all lines instead of the current paragraph

My specific request is to not reflow bullet lists.

[yihui]

@jennybc May I ask why? There are certainly elements that we must not reflow (such as \preformatted{}, because line breaks are meaningful), but it doesn't seem to hurt to reflow bullet lists.

[jennybc]

May I ask why?

Because it destroys the bullet list?

Before reflow:

#' Title
#'
#' blah blah
#'   * point one
#'   * point two
#'
#' @param x something 
#'
#' @return
#' @export
#'
#' @examples
foo <- function(x = 1) {
  x + 1
}

After reflow:

#' Title
#'
#' blah blah * point one * point two
#'
#' @param x something
#'
#' @return
#' @export
#'
#' @examples
foo <- function(x = 1) {
  x + 1
}

I would of course love a reflow on the bullet list, that respected its structure. I currently do this by temporarily inserting blank lines around the to-be-reflowed bullet item, reflow that, then remove the blank lines.

[yihui]

I see. If you make each bullet a paragraph (i.e., add a blank line after each bullet), then reflowing the bullets won't hurt:

#' Title
#'
#' blah blah
#'
#'   * point one
#'
#'   * point two
#'
#' @param x something
#'
#' @return
#' @export
#'
#' @examples
foo <- function(x = 1) {
  x + 1
}

This won't change the meaning of bullets, either. Perhaps you don't feel comfortable with the extra blank lines, though.

BTW, just FYI: indenting a bullet by two spaces was not a problem for Pandoc 1.x, but may cause problems in Pandoc 2.x (in case of nested lists).

Regarding "reflow all" or ""reflow the current line/paragraph, the worse case is that we provide an extra option in the IDE instead of deciding it by ourselves. For myself, I just avoid using content that cannot be wrapped in roxygen :) (i.e. only hit the nails that my hammer is able to hit).

To sum it up, reflowing text certainly has several edge cases, and we will need a smarter algorithm that understands the context of the text. I guess this is not impossible, and I'll be happy to invest some time in it since I'm still interested in it, although it no longer hurts me.

[jennybc]

If you make each bullet a paragraph (i.e., add a blank line after each bullet), then reflowing the bullets won't hurt

Well, unless you start including explicit roxygen tags, this affects which section of the help your bullets show up in. Here's the help produced by your version with the intervening blank lines.

[yihui]

Fair enough. In this particular case, both reflowing and (having to use) the explicit @description tag are annoying, and the latter is probably less annoying... My personal preference for roxygen comments is that @description is always a single paragraph, and anything more complicated than that goes to @details (and even more complicated stuff goes to a vignette/website).

[salim-b]

I guess this issue is partially addressed by the recent introduction of Visual R Markdown in RStudio 1.4, i.e. activating canonical mode and setting wrap to the desired value.

Of course, this only applies to Markdown paragraphs (code chunks are not wrapped by Pandoc for obvious reasons), so we still lack a proper reflow command for (roxygen2) comments inside code chunks. Is there any progress on this?

[luisdamiano]

It'd be also useful to have reflow for Sweave (.Rnw) source files.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs, per https://github.com/rstudio/rstudio/wiki/Issue-Grooming. Thank you for your contributions.

[mikebessuille]

Related to #2563