13

I made a package with the help of RStudio & devtools for namespace, DESCRIPTION & Roxygen2 for the man pages. This worked fine, and the help pages I've recently added worked too. I decided to add author name, email, and some details. Initially by manually editing the man page file (BAD) then editing the R script Roxygen2 parts & pushing the change to the Rm file with document()

But: when I install my package

devtools::install_github('SimonDedman/gbm.auto')

I get the following warnings:

Warning: /tmp/RtmpNladba/devtools27303e05b1fc/SimonDedman-gbm.auto-dbe3cb0/man/gbm.valuemap.Rd:35: unknown macro '\item'
Warning: /tmp/RtmpNladba/devtools27303e05b1fc/SimonDedman-gbm.auto-dbe3cb0/man/gbm.valuemap.Rd:37: unknown macro '\item'
Warning: /tmp/RtmpNladba/devtools27303e05b1fc/SimonDedman-gbm.auto-dbe3cb0/man/gbm.valuemap.Rd:39: unknown macro '\item'
Warning: /tmp/RtmpNladba/devtools27303e05b1fc/SimonDedman-gbm.auto-dbe3cb0/man/gbm.valuemap.Rd:41: unknown macro '\item'
Warning: /tmp/RtmpNladba/devtools27303e05b1fc/SimonDedman-gbm.auto-dbe3cb0/man/gbm.valuemap.Rd:43: unknown macro '\item'
Warning: /tmp/RtmpNladba/devtools27303e05b1fc/SimonDedman-gbm.auto-dbe3cb0/man/gbm.valuemap.Rd:45: unknown macro '\item'
Warning: /tmp/RtmpNladba/devtools27303e05b1fc/SimonDedman-gbm.auto-dbe3cb0/man/gbm.valuemap.Rd:47: unknown macro '\item'
Warning: /tmp/RtmpNladba/devtools27303e05b1fc/SimonDedman-gbm.auto-dbe3cb0/man/gbm.valuemap.Rd:49: unknown macro '\item'
Warning: /tmp/RtmpNladba/devtools27303e05b1fc/SimonDedman-gbm.auto-dbe3cb0/man/gbm.valuemap.Rd:51: unexpected section header '\value'
Warning: /tmp/RtmpNladba/devtools27303e05b1fc/SimonDedman-gbm.auto-dbe3cb0/man/gbm.valuemap.Rd:55: unexpected section header '\description'
Warning: /tmp/RtmpNladba/devtools27303e05b1fc/SimonDedman-gbm.auto-dbe3cb0/man/gbm.valuemap.Rd:65: unexpected section header '\examples'
Warning: /tmp/RtmpNladba/devtools27303e05b1fc/SimonDedman-gbm.auto-dbe3cb0/man/gbm.valuemap.Rd:69: unexpected END_OF_INPUT '
'

Those items are just simple @param arguments which i've not changed, look fine and worked before. Ditto the value / description / examples arguments, which are all standard (but probably a downstream issue which will get solved once the upstream issue is fixed).

Can anyone think what might cause this? None of my help pages are clickable now, even though one would have thought that whatever this problem is with the one script (gbm.valuemap.R), the others should be fine?

Thanks in advance.

7
  • 1
    \item is only valid in an itemize "environment". Are you sure your docs are such that \item only appears within \itemize{ \item hi \item bye} or \enumerate{ \item hi \item bye} ? Also \value, \description and \examples should be @value, @description and @examples. See the roxygen2 guide for more guidance on this.
    – Chrisss
    Commented Sep 23, 2016 at 22:57
  • 1
    how about using RStudio to open the problematic .Rd file and preview it? If you have previous working version, you can also compare the difference between two version of .Rd. Another wild guess is if you edited some file manually, there could be encoding/line ending changes you didn't realize.
    – dracodoc
    Commented Sep 23, 2016 at 23:03
  • 4
    It may be the & in lines like "Import with (e.g.) read.csv & specify" although I'm not entirely sure. I recall some of the punctuation being problematic, especially %. Changing & to and might be worth a shot.
    – Benjamin
    Commented Sep 24, 2016 at 1:06
  • 1
    Hi all. @Chrisss the \items are within an \arguments{} which was autocreated by the roxygen2 skeleton, & is the same way it was when everything was working. Format is e.g. #' examples None (with at symbol I can't include here) in the Roxygen2 bit of the R script so all correct there. dracodoc great idea - turns out it was the % sign, as Benjamin predicted. Cheers all, I'll edit this now & hopefully solve it.
    – dez93_2000
    Commented Sep 24, 2016 at 15:24
  • 2
    I got this error because I had a percent symbol in the documentation, %. Commented Feb 9, 2020 at 16:02

4 Answers 4

13

You can use RStudio to help on package development in several aspects:

  1. use build & load tool in build panel for package project. You can build, update documents (you may want to check more options in setting about Roxygen2, some are not turned on by default), load package in one click. The error you met should be found earlier, and you don't need to manually install to test.

  2. use the preview feature for .Rd file

Another method is to compare the working and non-working version source file, .Rd file to find the difference.

Generally direct editing of generated file should be avoided.

To make this answer more complete, here are tips from @Benjamin about formatting in Rd files:

It may be the & in lines like "Import with (e.g.) read.csv & specify" although I'm not entirely sure. I recall some of the punctuation being problematic, especially %. Changing & to and might be worth a shot

N.B. Changing % to \% in the .Rd documentation file, or the underlying roxygen comment, should prevent issues relating to use of the % symbol. This is due to the use of LaTeX.

From @Thomas:

Can also come up if you have a stray { somewhere

2
  • Thanks. Anyone else with this problem, also note @Thomas' note to watch out for stray curly brackets
    – dez93_2000
    Commented Sep 24, 2016 at 22:34
  • Great tip to use the preview feature!
    – jbaums
    Commented Oct 18, 2019 at 0:34
6

For me, this was happening when I was using \n in the description of a function in a library I was writing (I was describing what that backslash "n" escape sequence meant. I fixed it by escaping the escape sequence itself in the function's .Rd file. Example:

BAD/ERRORED:

\description{
Blah blah and `\n` is an example of blah blah blah
}

FIXED/SOLUTION:

\description{
Blah blah and `\\n` is an example of blah blah blah
}
1
  • 1
    Other possible problems may be: Using square brackets (e.g. to denote intervals of numbers) or escaping percentages (\% instead of %).
    – jarauh
    Commented Jan 22, 2021 at 12:16
6

For me the issue was using "%" sign in the text. When I removed it or escaped it ("\%"), it no longer threw an error. If you open the roxygen generated .Rd file in the editor, it can give you a hint, for me the text after the % was coloured differently.

2
  • How funny, I'd completely forgotten about this issue but coincidentally had the same problem with a different package yesterday, and realised % was causing it. Cheers!
    – dez93_2000
    Commented Apr 8, 2022 at 16:21
  • Yes, escaping % characters in the text solved the issue here too. Commented May 16, 2022 at 12:17
2

I had the same error with the unknown macro '\item' and resolved it by removing a repeated @author XXX line from the file. Seems that repeated @{item} parameters that are not meant to be repeated may raise that error.

Not the answer you're looking for? Browse other questions tagged or ask your own question.