In an earlier post, I asked about declaring such functions in R packages and making them work. Having succeeded, I'm now trying to document one such function.
I created an Rd file with the function's name as a title, but when running the CHECK, I get the following warning:
* checking for missing documentation entries ... WARNING
Undocumented code objects:
'%IN%'
I tried several names such as %IN%.Rd or '%IN%'.Rd, to no avail. Any hints on how to make this work?
The goto guide would definitely be section 2.1.1 "Documenting functions"[1] of the "Writing R Extensions" manual. As #joran pointed out in a comment the important part maybe the use of an \alias. According to the "Writing R extensions" manual the %s need to be escaped at least in \alias and in the text. About \name it states: " [name should not contain] ‘!’ ‘|’ nor ‘#’, and to avoid possible problems with the HTML help system it should not contain ‘/’ nor a space. (LaTeX special characters are allowed, but may not be collated correctly in the index.)"[2] and about \alias: " Percent and left brace need to be escaped by a backslash."[3]
Related
The standard way of writing documentation with code formatting is by using \code{}.
That is, #' #param foo value passed on to \code{bar()} becomes
Arguments
foo value passed on to bar()
However, I've seen some packages (i.e. dplyr) using backticks instead of \code{} to the same effect. This is much better, since it's less clunky and allows for very nice syntax highlighting.
However, if I try that on my own package, the backticks get interpreted as... just backticks, like any other character.
The documentation for dplyr::across(), for example, starts with:
#' #description
#' `across()` makes it easy to apply the same transformation to multiple [...]
which gets compiled and displayed in the man page as:
Description
across() makes it easy to apply the same transformation to multiple [...]
But if I try something similar on my package, I get:
Description
`across()` makes it easy to apply the same transformation to multiple [...]
Weirdly, I've forked the package glue (which also manages to use backticks for code formatting) for a simple PR, and if I build the package locally, the backticks work (I get code formatting). Can't for the life of me figure out why it works there but not for my package.
So, is there some setting I need to modify to get this to work? I checked the dplyr.Rproj but found nothing relevant. I also glanced at the Doxyfile, but didn't know what it did or what I'd even be looking for there.
All credit goes to #rawr's comment to the question, just formalizing it with an answer:
The secret is in the roxygen2 documentation: just add the following to the end of the package DESCRIPTION file:
# DESCRIPTION file
# [... rest of file ...]
Roxygen: list(markdown = TRUE)
RoxygenNote: 7.1.2 # actually works since 6.0.0
As that code would imply, this sets roxygen2 to interpret the commands as good ol' Markdown like we're used to using here on SO and elsewhere. This also implies all the other standard Markdown commands such as **bold** and *italics*, as well as [text](http://www.url.com), code blocks defined by ```, itemized and enumerated lists, etc. It's a huge improvement across the board.
Though be careful and take a look at the documentation, since there are a few gotchas. For instance, an empty line isn't necessary to start lists, so don't start any lines with #' 1. [...] or #' * [...] or you'll accidentally create a list!). There's also a few things which don't work yet, but they're pretty minor.
I am building my my first pacakge, and when running R CMD check after devtools::build() I found a bunch of issues with "checking PDF version of the manual." I struggled to find directions on how to troubleshoot so I'm going to ask this question: "How can I identify the problematic text in my .R files that Roxygen uses to make the .Rd files that make up the manual?" and then go ahead an answer in hopes that it is useful to someone else down the line.
I would get a long series of WARNINGS, and the unique components are below:
LaTeX errors when creating PDF version.
This typically indicates Rd problems.
LaTeX errors found:
! LaTeX Error: Bad math environment delimiter.
See the LaTeX manual or LaTeX Companion for explanation. Type H
for immediate help.
! Package inputenc Error: Unicode character ℓ (U+2113) (inputenc)
not set up for use with LaTeX.
See the inputenc package documentation for explanation. Type H
for immediate help.
I thought these were pretty clear: Somewhere I have bad Latex (like a missing curly bracket or dollar sign, a imagine), and also there is some issue with including this unicode character.
My question is, "How do I identify the offending lines?"
Following up on #user2554330's comment. Here's a simple way to check for eventual unicode characters in your functions and documentation:
# functions
functions <- list.files(path = './R', all.files = T, recursive = T, full.names = T)
lapply(X=functions, FUN = tools::showNonASCIIfile)
# documentation
docs <- list.files(path = './man', all.files = T, recursive = T, full.names = T)
lapply(X=docs, FUN = tools::showNonASCIIfile)
Running R CMD check produces a directory, mypackagename.Rcheck/
In my case there is a file in there called Rdlatex.log
This logfile has more verbose (and very helpful/ clear) warning and error messages with line numbers and file names to allow me to find the offending text and develop some ideas of how to fix it :-)
There may be other issues (e.g. I noticed in other related questions the suggestion to check the installation and paths for the underlying latex infrastructure), but it seems like starting with my .R files is likely to be fruitful.
This is platform-specific but I'm pretty sure there are text editors equivalent on other platforms.
On MacOSX I use BareBones Edit, and it has some commands like "Zap Gremlins" which eliminate all non-ASCII characters and/or optionally replace things like 'smart quotes' with ASCII quote characters.
As to fixing LaTeX embedded command strings: best I can suggest is using some tool like "KLatexFormula" (Windows) or equivalent to play with the strings until they render.
What I have read
I have read this SO question and related answers but I am still a bit at loss of how to document a defunct function properly in my package.
What I have tried
I replaced the code of my defunctfucntion by a call of .Defunct("<pointer to a function to be used instead>", "<my package name>")
I deleted the .Rd file containing the old documentation of my function
I created a mypackage-defunct.Rd file with an alias pointing to my now defunct function name
In mypackage-defunct.Rd I created an \usage entry for my old function and replaced the function arguments by \dots (as I do not see the need to keep track about the old arguments. I followed a bit what is done in base-defunct)
What I have got
When running RCMD CHECK I get the following WARNING:
checking Rd \usage sections ... WARNING
Undocumented arguments in documentation object 'mypackage-defunct'
'...'
Functions with \usage entries need to have the appropriate \alias
entries, and all their arguments documented.
The \usage entries must correspond to syntactically valid R code.
See chapter 'Writing R documentation files' in the 'Writing R
Extensions' manual.
What I would like to have
How do i get rid of the warning? Do I need to document arguments from defunct functions? Bonus question: What is the recommended way for a defunct function. Should I remove all arguments and replace them by ...? Looking at base-defunct, I see a mix of functions with proper argument names, . and ...arguments and empty argument lists. What is the "correct" way?
What is the possible documentation available for R package? For example I try to understand sp package.
In addition to help(sp), what are the other functions for searching through help and documentation?
Getting help on a function that you know the name of
Use ? or, equivalently, help.
?mean
help(mean) # same
For non-standard names use quotes or backquotes; see An Introduction to R: Getting help with functions and features:
For a feature specified by special characters, the argument must be enclosed in double or single quotes, making it a “character string”: This is also necessary for a few words with syntactic meaning including if, for and function."
?`if`
?"if" # same
help("if") # same
There are also help pages for datasets, general topics and some packages.
?iris
?Syntax
?lubridate
Use the example function to see examples of how to use it.
example(paste)
example(`for`)
The demo function gives longer demonstrations of how to use a function.
demo() # all demos in loaded pkgs
demo(package = .packages(all.available = TRUE)) # all demos
demo(plotmath)
demo(graphics)
Finding a function that you don't know the name of
Use ?? or, equivalently, help.search.
??regression
help.search("regression")
Again, non-standard names and phrases need to be quoted.
??"logistic regression"
apropos finds functions and variables in the current session-space (but not in installed but not-loaded packages) that match a regular expression.
apropos("z$") # all fns ending with "z"
rseek.org is an R search engine with a Firefox plugin.
RSiteSearch searches several sites directly from R.
findFn in sos wraps RSiteSearch returning the results as a HTML table.
RSiteSearch("logistic regression")
library(sos)
findFn("logistic regression")
Finding packages
available.packages tells you all the packages that are available in the repositories that you set via setRepositories. installed.packages tells you all the packages that you have installed in all the libraries specified in .libPaths. library (without any arguments) is similar, returning the names and tag-line of installed packages.
View(available.packages())
View(installed.packages())
library()
.libPaths()
Similarly, data with no arguments tells you which datasets are available on your machine.
data()
search tells you which packages have been loaded.
search()
packageDescription shows you the contents of a package's DESCRIPTION file. Likewise news read the NEWS file.
packageDescription("utils")
news(package = "ggplot2")
Getting help on variables
ls lists the variables in an environment.
ls() # global environment
ls(all.names = TRUE) # including names beginning with '.'
ls("package:sp") # everything for the sp package
Most variables can be inspected using str or summary.
str(sleep)
summary(sleep)
ls.str is like a combination of ls and str.
ls.str()
ls.str("package:grDevices")
lsf.str("package:grDevices") # only functions
For large variables (particularly data frames), the head function is useful for displaying the first few rows.
head(sleep)
args shows you the arguments for a function.
args(read.csv)
General learning about R
The Info page is a very comprehensive set of links to free R resources.
Many topics in R are documented via vignettes, listed with browseVignettes.
browseVignettes()
vignette("intro_sp", package = "sp")
By combining vignette with edit, you can get its code chunks in an editor.
edit(vignette("intro_sp",package="sp"))
This answer already gives you a very comprehensive list.
I would add that findFn("some search terms") in package sos is extremely helpful, if you only have an idea/keywords of what you are looking for and don't already have a package or function in mind.
And also the task views on CRAN: not really a search process but a great place to wander as you wonder.
This thread contains many good suggestions. Let me add one more.
For finding which packages are loaded, plus extra goodies, ?sessionInfo is quite nice.
help(package="<package-name>") where of course <package-name> is the name of the package you want help for.
Often the same function name is used by several packages. To get help on a function from a specific package, use:
help(aggregate, package="stats")
help(aggregate, package="sp")
In the RStudio IDE you can click on any function name and press F1, which will directly open the associated function help text in its pane. Like you would have called help() or ?fun().
My package passed Rcmd check successfully. but in constructed PDF format of R documentation, within the examples section, half of the line (R code) is out of the paper. I also found another CRAN submitted package, ftsa , that suffer from overfulling in a line too, see ftsa Reference manual.
I guess this
problem roots in the behavior of the verbatim environment in Latex. However there are some Latex packages to deal with this, https://tex.stackexchange.com/questions/14342/verbatim-environment-that-can-break-too-long-lines, but I do not know how to use them with Rcmd.
In dealing with these cases, why Rcmd check does not show any error, warnings or note as Latex does?
How can I force line breaking in examples section?
Thank you
R CMD check does not analyze / forward all LaTeX warnings. Yes, in an ideal world it would.
It has been the case, always that you should format the \examples{ ... } section
well, yourself,
notably including sensible line breaks (and leading spaces) for nice alignment of multi -line examples.
Use the sources of R itself or recommended packages (or those authored by me, as I do pay attention to this quite a bit), to see good examples in their *.Rd files.
Remember: The current development sources of R are always web accessible at
R (devel) source tree # svn.r-project.org, i.e. R's standard packages at R sources src/library.