[R-pkg-devel] Advice on identifying parsing failures with examples when trying to pkgdown my package

Chris Evans chr|@ho|d @end|ng |rom p@yctc@org
Sat Apr 10 22:23:54 CEST 2021

Brilliant: exactly what I needed.  I see a happy hour tomorrow morning sorting those.

Many thanks (again) Duncan and very best to all here!


----- Original Message -----
> From: "Duncan Murdoch" <murdoch.duncan using gmail.com>
> To: "Chris Evans" <chrishold using psyctc.org>, "r-package-devel" <r-package-devel using r-project.org>
> Sent: Saturday, 10 April, 2021 21:20:40
> Subject: Re: [R-pkg-devel] Advice on identifying parsing failures with examples when trying to pkgdown my package

> Here's a better way to do the file-at-a-time check:
> Load the .Rd file in RStudio, and click on Preview.  Copy the whole
> examples section to a test.R file.  RStudio will mark all the syntax
> errors, but won't be fooled by the \% escapes, since the Preview handled
> them.
> Duncan Murdoch
> On 10/04/2021 4:01 p.m., Duncan Murdoch wrote:
>> On 10/04/2021 3:28 p.m., Chris Evans wrote:
>>> My beginner package https://github.com/cpsyctc/CECPfuns is evolving slowly and I
>>> had no problems (that I could see)
>>> with the help pages created through roxygen.  Today I came back to try using
>>> pkgdown to ... pkgdown the package.
>>> So I used a copy of the package directory and ran:
>>> usethis::use_pkgdown()
>>> and then
>>> pkgdown::build_site()
>>> That produced the start of exactly what I wanted as a nicely pkgdown'ed site.
>>> However, the console showed error
>>> messages for three examples (which, as I say, all seem to produce OK html help
>>> pages through the usual roxygen
>>> processing).  The error message was
>>>      Failed to parse example for topic
>>> and sure enough the examples section in the pkgdown docs html was empty.  If
>>> anyone wants to look at one of
>>> the functions, checkAllUnique was one of the three that threw the errors.
>>> I tried some searching and the most pertinent seeming page I hit was this:
>>>      https://github.com/r-lib/pkgdown/issues/1149
>>> where Hadley Wickham says "That's not valid .Rd code because you didn't escape
>>> the Rd comment symbol" which may
>>> well be my problem too ... but I don't understand the advice (sorry!)
>> In Example code, % needs to be escaped, or it will be interpreted as a
>> comment.  Sometimes that means the examples just compute the wrong
>> thing, e.g.
>> A %*% b
>> is parsed as A when the rest of the line is ignored as a comment.
>> Sometimes it makes the code illegal.  I don't know which you're seeing.
>>> When I tried to tweak one of those functions by inserting a lot of "#" to mask
>>> results, i.e. replaced
>>> #' [1] something
>>> with:
>>> #' # [1] something
>>> (as I probably should have done that in the examples I have, they are dontrun
>>> examples so I hadn't noticed).
>> pkgdown tries to parse \dontrun examples, so this was a good thing, but
>> I think you missed some:  e.g. in checkAllUnique.Rd, I see this around
>> lines 55-60:
>> \examples{
>> \dontrun{
>> ### letters gets us the 26 lower case letters of the English alphabet so
>> should test OK
>> checkAllUnique(letters)
>> [1] TRUE
>> ### good!
>> That line containing TRUE is not legal R code, so should be commented.
>> You can find these one by one by copying the text from the Rd example
>> section into a file, and trying to parse that file, e.g.
>> Put this in "test.R":
>>     ### letters gets us the 26 lower case letters of the English alphabet
>> so should test OK
>>     checkAllUnique(letters)
>>     [1] TRUE
>>     ### good!
>> then run parse("test.R"):
>> Error in parse("test.R") : test.R:3:1: unexpected '['
>> 2: checkAllUnique(letters)
>> 3: [
>>      ^
>> You can do it for a file at a time by loading the test.R file into
>> RStudio; it'll put markers beside each syntax error.  Unfortunately, it
>> thinks
>> checkAllUnique(tmpTib \%>\% pull(1))
>> is a syntax error:  those escapes are required in Rd, but are illegal in R.
>> I don't know if there's a way to do it directly from the Roxygen source.
>> Duncan Murdoch
>>> However, when I reran pkgdown::build_site() I got a new error message that is,
>>> to me, thoroughly confusing:
>>> Error in utils::modifyList(meta, override) : is.list(x) is not TRUE
>>> At that point I decided to back out and come here and ask the question in the
>>> subject line!

Chris Evans (he/him) <chris using psyctc.org> Visiting Professor, University of Sheffield <chris.evans using sheffield.ac.uk>
I do some consultation work for the University of Roehampton <chris.evans using roehampton.ac.uk> and other places
but <chris using psyctc.org> remains my main Email address.  I have a work web site at:
and a site I manage for CORE and CORE system trust at:
I have "semigrated" to France, see: 

If you want an Emeeting, I am trying to keep them to Thursdays and my diary is at:
Beware: French time, generally an hour ahead of UK.

More information about the R-package-devel mailing list