What to do about \dontshow?

[jennybc]

I gather from #1540 that pkgdown's current (non) handling of \dontshow is intentional.

There's a specific use we make of \dontshow in several packages and I'm wondering if it's compelling enough to resurrect the matter. Or if it leads to some new feature idea with a narrower scope than full \dontshow support, but that still meets our needs.

Here's a search for \dontshow in tidyverse and r-lib:
https://cs.github.com/?scopeName=tidyverse+and+r-lib&scope=org%3Atidyverse+OR+org%3Ar-lib&q=dontshow+path%3AR%2F*

fs, usethis, readr, asciicast all use \dontshow to hide some yucky stuff that we need to do behind the scenes, but that add unnecessary noise to the examples when being consumed by a normal user.

Almost all of the use is to temporarily set working directory to session temp directory, demo something that writes files, then restore working directory. Lots of this:

#' \dontshow{.old_wd <- setwd(tempdir())}
#' file_create("foo")
#' link_create(path_abs("foo"), "bar")
#' link_path("bar")
#'
#' # Cleanup
#' file_delete(c("foo", "bar"))
#' \dontshow{setwd(.old_wd)}

That's from the docs for fs::link_path() and, indeed all the \dontshow commands are actually shown. Which is true for all of the hits. (BTW the \dontshow content is not showing in local help topics.)

Do we want to reconsider \dontshow or maybe address this common working directory maneuver directly (i.e. another special case similar to @examplesIf)?

[hadley]

I took a bit of a look at this and it's going to be a reasonable amount of work because we somehow need to wrap the dontshow tags in some custom HTML so it's still run as part of the example, but isn't shown on the final page.

[hadley]

I think we'll need to enforce the limitation that the \dontshow must be it's own complete line, since I have no idea what 1\dontshow{+}1 would be expected to display. I don't think that should be a limitation in practice.

[hadley]

Needs r-lib/evaluate#125