Bioconductor / BiocStyle

Issues and pull requests for BiocStyle should go here.
12 stars 19 forks source link

Enable horizontal scroll for code chunks #74

Closed LTLA closed 3 years ago

LTLA commented 4 years ago

Consider this rather innocuous Rmarkdown file:

---
title: blah
author: me
output:
  BiocStyle::html_document
---

Let's make some very long thing that is forced to wrap across multiple lines because it doesn't fit on a single line, which makes it super annoying to read.

```{r, message=FALSE}
library(S4Vectors)
set.seed(10)
df <- DataFrame(
   super=1:10,
   cali=sample(letters, 10),
   fragi=runif(10),
   listic=sample(LETTERS, 10),
   expi=rnorm(10),
   ali=rbinom(10, 1, 0.5)==0,
   docious="X")
df

Upon compilation, I get:

![Screenshot from 2020-04-21 21-50-13](https://user-images.githubusercontent.com/8166669/79941840-200d9a80-841a-11ea-987f-7ad92139ff4f.png)

Can we stop the wrapping and get some horizontal scroll bars here? There is no obvious rationale for wrapping output like this. The same could also be said of the code chunks; if I don't toe the 80-character limit to the letter, I get textwraps that really makes my formatting ugly:

title: blah author: me output: BiocStyle::html_document

Same again, for code:

for (x in 1:10) {
     print( x + stats::runif( 1 ) * 10000000000000 + 89734928378 - 587368764875 + 9871827  )
     print("BLAH BLAH BLAH")
     print( x + stats::runif( 1 ) * 10000000000000 + 89734928378 - 587368764875 + 9871827  )
     print("BLAH BLAH BLAH")
     print( x + stats::runif( 1 ) * 10000000000000 + 89734928378 - 587368764875 + 9871827  )
     print("BLAH BLAH BLAH")
}


The aesthetic penalty for exceeding the character limit is pretty harsh:

![Screenshot from 2020-04-21 21-45-57](https://user-images.githubusercontent.com/8166669/79941603-8645ed80-8419-11ea-9ef5-fc743dbb43bb.png)

These are created using the current `master` (4802b8c9a88f4ba60b3062006a78ad93c53bdce6).
aoles commented 4 years ago

Hi Aaron,

Thanks for your detailed feedback!

Re the output code chunks I agree, it makes sense to change the overflow policy on these considering the fact that often there is little control over the line length of the results.

However, when it comes to the input chunks I believe it should be possible to format the code such that it adheres to the 80 characters limit. I would argue that having longer lines makes them difficult to comprehend anyway and scrollbars are not perfect in this case either. Actually, it was a deliberate choice not use scrollbars in order not to encourage bad coding practices. Another thing was facilitating easy switching between HTML and PDF output. pdf_document does not allow you to do anything about overflows other than reformatting the code manually.

Cheers, Andrzej

LTLA commented 4 years ago

I'll be honest, I've never been a fan of this 80 character limit. It's suffocating, especially in code with moderately deep indenting. 100-120 characters makes so much more sense, I don't know who has such a tiny screen that they can't afford an extra 40 characters. Even if we pretend that 80 characters is a "good width", there should not be much difference between the readability of 80 and 81 characters; but the current textwrap behavior severely punishes an extra character.

Now with that rant out of the way, let's talk practicalities. I'm a big fan of BiocStyle but it's hard to convince others to use it when their >80 width code gets wrapped like this. They try it out, they see how ugly it becomes, and they pass. Throwing in a scrollbar seems like an easy win to smooth the path; the code becomes "no less pretty" upon using BiocStyle::html_document, and the scrollbar itself is a gentle reminder that their code is - in your opinion - too long.

PDFs are their own problem, but we might as well solve it for HTMLs while we can.