Xaringan: Strip trailing whitespace for finding slide breaks

[MichaelChirico]

As raised here:

https://stackoverflow.com/questions/51120186/xaringan-slide-separator-not-separating-slides

A confusing UX caused by trailing whitespace. Seems natural to me for the default parsing option to axe this in finding slide breaks.

[yihui]

https://stackoverflow.com/questions/51120186/xaringan-slide-separator-not-separating-slides#comment89241178_51120707

[MichaelChirico]

if this is the recommended solution I guess Rstudio should be added to
Suggests

On Mon, Jul 2, 2018, 1:08 PM Yihui Xie [e-mail] wrote:

Closed #151 https://github.com/yihui/xaringan/issues/151.

—
You are receiving this because you authored the thread.
Reply to this email directly, view it on GitHub
https://github.com/yihui/xaringan/issues/151#event-1710696699, or mute
the thread
https://github.com/notifications/unsubscribe-auth/AHQQdcOP_nUSwmF3Khy-T-urmlXFptSIks5uCaq9gaJpZM4U-je5
.

[yihui]

Rstudio should be added to Suggests

I don't understand what that means, because 1) "Rstudio" is not an R package, and 2) I don't know how adding it to Suggests could technically help at all (if you meant the Suggests filed of the DESCRIPTION file).

[MichaelChirico]

My point is the suggested solution is creating an unstated ~dependency on using RStudio as an IDE.

A quick glance suggests maybe this line could be ^---\\s*$ instead?

https://github.com/yihui/xaringan/blob/master/R/utils.R#L56

[mschilli87]

@MichaelChirico:I fail to see a dependency introduced by this comment. The solution to catch this mistake on the users side (the slide separator is defined and documented as ^---$ so not recognizing ^--- $ is the documented behaviour) is clearly editor specific. As many R users use Rstudio, the commenter on SO explained how to strip whitespace on saving in Rstudio. But I can do the same in [neo]vi(m) and I'd be surprise if an emacs user wouldn't know how to do this in [spac]emacs.

So in my mind, xaringan should keep behaving as it does, which is predictable and documented and every user that cannot hesitate dropping random whitespace-noise while coding should read the manual of his/her editor of choice to figure out how to strip it off instead of switching to Rstudio.

[MichaelChirico]

You're appealing to the documentation as if it's immutable canon.

Even experienced users are encountering frustrating "bugs" and can spend hours trying to discover something like this.

Unless there's a more compelling reason _not_ to make the slide separator ^---\\s*$, as designers we're just intentionally introducing impediments to usability.

[mschilli87]

I'm not gonna comment here any further as I made my point clear and I accept your point of view which is different.

Just to name one more example: What if a user depends of that behavious (as a feature not bug), to include a horizontal line in their slides (as they read to documentation and understood that xaringan will not interpret this)? You proposed change would break this users presentation that used to
work just fine after he/she updates xaringan.

And again, IMHO this is not xaringan or even R specific: Trailing whitespace can cause problems in may situations and I believe this should be addressed in the editor. I get it highlighted in red while typing and before commiting to git. For me that's enough to decide if I want to keep it (e.g. to break lines in a quote in markdown by two trailing spaces) or not (e.g. the case discussed here) and fix it if needed. If I'd like it to be stripped upon save, I'd configure my editor to do so.

[MichaelChirico]

Regardless, you claim the separator "is defined and documented as ^---$", but I don't see said documentation anywhere in this repo -- the man/ folder, README, and README-cited presentation here all fail to mention this.

the only place I see --- in the whole repo is in utils.R:

l = sapply(list.files('.', recursive = TRUE, full.names = TRUE), function(f) {x = readLines(f); grep('---', x, value = TRUE, fixed = TRUE)}); l[lengths(l) > 0]
# Warning message:
# In readLines(f) :
#   incomplete final line found on './inst/rmarkdown/templates/xaringan/resources/hygge-duke.css'
# $`./inst/examples/ghoul.Rmd`
# [1] "---" "---" "---" "---" "---" "---" "---"
# 
# $`./inst/rmarkdown/templates/xaringan_zh-CN/skeleton/skeleton.Rmd`
#  [1] "---" "---" "---" "---" "---" "---" "---" "---" "---" "---" "---" "---" "---" "---" "---" "---" "---" "---"
# [19] "---" "---" "---" "---" "---" "---" "---" "---" "---" "---" "---" "---" "---" "---"
# 
# $`./inst/rmarkdown/templates/xaringan/resources/default.html`
# [1] "---"
# 
# $`./inst/rmarkdown/templates/xaringan/skeleton/skeleton.Rmd`
#  [1] "---" "---" "---" "---" "---" "---" "---" "---" "---" "---" "---" "---" "---" "---" "---" "---" "---" "---"
# [19] "---" "---" "---" "---" "---" "---" "---" "---" "---" "---" "---" "---" "---" "---" "---" "---" "---" "---"
# [37] "---" "---" "---"
# 
# $`./R/utils.R`
# [1] "  i = grep('^---\\\\s*$', x)"                         "  i = grep('^---$', x)"                              
# [3] "  if (length(i) == 0) return(c(x, '---', b))"         "  x[j] = paste(c('---', b, '---'), collapse = '\\n')"

[MichaelChirico]

Just to name one more example: What if a user depends of that behavious (as a feature not bug), to include a horizontal line in their slides (as they read to documentation and understood that xaringan will not interpret this)?

Again, I don't know what documentation you're referring to, but yes, this is _exactly_ what I was hoping for in this discussion. _This_ is a compelling reason not to change the behavior, namely, ^---\s+$ already has a well-defined interpretation.

Now that I know this (again, I tried reading the documentation that I found before posting this issue and again several more times in these follow-up comments), in fact I agree the current behavior should remain.

Thank you.

[mschilli87]

@MichaelChirico: xaringan is build on top of remark and in their wiki the slide separator is defined.

This is also referred to in https://slides.yihui.name/xaringan/#11 which I consider (part of) the xaringan documentation (as does @yihui, it seems (see point 8)), actually specifically in the context of how to create a new slide.

Both, the remark wiki and the documentation presentation, are also mentioned in the xaringan README.

Sorry for not double-checking this in detail before posting.

[yihui]

@MichaelChirico I can definitely see your frustration, but this is a very general and common problem in software that depends on upstream packages -- in this case, xaringan depending on remark.js (and as a wrapper of remark.js). It is not practical for xaringan to fully document remark.js. The behavior of --- followed by white spaces is not defined by xaringan, but remark.js. Should I document this particular case? I don't really know.

[ekstroem]

Three dashes are used for a split
But careful when using your wit
'Cause you must erase
any sign of a space
or else it will just look like ...

(running for cover).

I better go and do something useful

[MichaelChirico]

@yihui thanks; I understand the dilemma. Agree completely that forking remark.js documentation to xaringan would be silly.

I think maybe what threw me off was the phrasing here:

Please see the full documentation as a presentation here (中文版在此).

I filed a PR to hopefully address this: https://github.com/yihui/xaringan/pull/152

[mschilli87]

Just to be fair, let me quote that 'full' documentation (emphasis mine):

You can see an introduction of remark.js from its homepage. You should read the remark.js Wiki at least once to know how to

• create a new slide (Markdown syntax* and slide properties);

• format a slide (e.g. text alignment);

• configure the slideshow;

• and use the presentation (keyboard shortcuts).

It is important to be familiar with remark.js before you can understand the options in xaringan.

The xaringan README also already contained the follwing:

The remark.js Wiki contains detailed documentation about how to format slides and use the presentation (keyboard shortcuts).

That said, I agree that it won't hurt to make it even more clear in the README.
The simple fact that this issue was created shows that there was demand for clarification.