tldr for R functions ⏳ 📄

[goldingn]

TL;DR

create a community-contributed set of quick reference guides for R functions, like the tldr project does for the command line.

background

There's an awesome command-line tool, tldr, that lets you access a community-curated list of quick-reference helpfiles for command-line tools.

So when you get into a knotty command-line situation (like this), you can type a quick command and rapidly get common use cases:

tldr tar

 tar

  Archiving utility.
  Often combined with a compression method, such as gzip or bzip.

  - Create an archive from files:
    tar cf target.tar file1 file2 file3

  - Create a gzipped archive:
    tar czf target.tar.gz file1 file2 file3

  - Extract an archive in a target folder:
    tar xf source.tar -C folder

  - Extract a gzipped archive in the current directory:
    tar xzf source.tar.gz

  - Extract a bzipped archive in the current directory:
    tar xjf source.tar.bz2

  - Create a compressed archive, using archive suffix to determine the compression program:
    tar caf target.tar.xz file1 file2 file3

  - List the contents of a tar file:
    tar tvf source.tar

  - Extract files matching a pattern:
    tar xf source.tar --wildcards "*.html"

Each of those help files is stored as a small markdown document on GitHub, and these pages are contributed by community members (631 contributors and counting for tldr). If there isn't a page for the command you type, you're invited to submit a PR:

tldr doesnotexist

Page not found.
Feel free to send a pull request to: https://github.com/tldr-pages/tldr

These pages are not intended to replace the documentation for those commands, but they complement them, like cheatsheets do for R package documentation.

There are various interfaces to tldr, including an R package on GitHub. These interfaces all provide access to information about command-line tools, not R functions.

proposal

Build an equivalent library of quick reference guides for R functions, and a package to call them!

You wouldn't want to load the package before running the command, so I'd propose naming the package tl, with a single function dr, so you can just load the namespace and get a page rapidly like this:

tl::dr("hist")

 hist

  Plot histograms.

  - Plot a histogram in grey:
    hist(vector, col = "grey")

  - Plot a horizontal histogram:
    hist(vector, horiz = TRUE)

  - Get the binned histogram data, but don't plot it:
    data <- hist(vector, plot = FALSE)

tasks

• create a GitHub repo to store the pages
• write a package to download (and possibly cache?) and display the pages
• create guidelines, templates (and possibly automatic checks) for the formatting, style, and content of submitted pages
• start writing pages for R functions!

[danwwilson]

I also wonder whether it would be possible to include a function in the package to create a new description/code pair. The idea being that it is accessible to anyone to create documentation. The tradeoff would be that the barrier to entry (a GitHub account, and the ability to create a PR) is so low that quality may not be maintained.

[goldingn]

Nice idea! Maybe a usethis-like function to create a markdown template, and a function to automatically check it (with lintr?) would be useful.

I was imagining some sort of human review step before merging the PR too, but maybe not, what do you think @danwwilson?

[RPanczak]

tldr 'how to avoid loops' would be used by me (recovering from Stata foreach) on a daily basis.. like five times per day 😜

[njtierney]

@MilesMcBain could possible chime in here about a lifestyle that avoids loops :)

[MilesMcBain]

TIL about tldr - awesome!

What would also be cool is if the help could have links in it to relevant blog posts etc. To help collect some of the great 3rd party documentation that is out there.

Re avoiding loops, this is a great resource I really got a lot out of: https://resources.rstudio.com/webinars/thinking-inside-the-box-you-can-do-that-inside-a-data-frame-april-jenny-bryan

[goldingn]

Yes, a set of clickable links to the helpfile and other resources at the bottom of the page would be ace!

[danwwilson]

I think the human review step will likely include quality, however I think the code of conduct should be quite clear on how to handle responses to poorly created documents (I.e not snarky).

I was also wondering how namespaces get managed when the same function exists in multiple packages. Does it just become an argument or do we use the :: notation?

[goldingn]

Yes, good point, ensuring maintainers are welcoming is really important!

Yeah, I was thinking we could do what ? does and interpret :: so that users could do:

tl::dr(stats::glm) 

or something similar.

This:

tl::dr("glm", "stats") 

would be simpler to implement, but requires more typing.

[goldingn]

BTW, there's an implementation of web-hosted helpfiles in this project: https://github.com/zoonproject/zoon which may be worth borrowing from for some of the technical details. I can dig out the relevant bits as/when needed.

[raymondben]

@danwwilson I would think that a function name provided without a namespace would be best to resolve to whatever get() returns (i.e. the currently-visible object with that name). I like the namespace::fun style interface if the user needs to be specific.

The tl::dr(stats::glm) style implementation would not (I think??) introduce much extra difficulty:

dr <- function(thing) {
  if (is.function(thing)) return(dr(deparse(substitute(thing))))
  ## rest of code that relies on thing being a string
  ## use e.g. getFromNamespace() to resolve function names provided as ns::fun
}

[goldingn]

Yes, that sounds great @raymondben!
? does similar parsing, and handles the use cases we want sort of like this (I'm omitting a bunch of stuff ? does to handle other use cases, and haven't actually run this code):

function (e1) {
  topicExpr <- substitute(e1)
  if (is.call(topicExpr) && (topicExpr[[1L]] == "::" || topicExpr[[1L]] == ":::")) {
    package <- as.character(topicExpr[[2L]])
    topicExpr <- topicExpr[[3L]]
  } else {
    package <- NULL
  }
  topic <- if (is.name(topicExpr)) {
    as.character(topicExpr)
  }
  help(topic, package = package)
}

[goldingn]

The package (in progress) is here: https://github.com/ropenscilabs/tl