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.

dez93_2000
  • 1,730
  • 2
  • 23
  • 34
  • 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 Sep 23 '16 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 Sep 23 '16 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 Sep 24 '16 at 01: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 Sep 24 '16 at 15:24
  • @dracodoc & ben: if either of you want to submit yours answers together as an official answer I'll happily mark it correct. If not I'll collate them and do it. Thanks both! – dez93_2000 Sep 24 '16 at 15:45
  • 1
    Can also come up if you have a stray `{` somewhere. – Thomas Sep 24 '16 at 19:42
  • 2
    I got this error because I had a percent symbol in the documentation, %. – Sal Mangiafico Feb 09 '20 at 16:02

4 Answers4

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

J M Swift
  • 3
  • 3
dracodoc
  • 2,603
  • 1
  • 23
  • 33
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
}
Samantha Karlaina Rhoads
  • 243
  • 5
  • 9
  • 1
    Other possible problems may be: Using square brackets (e.g. to denote intervals of numbers) or escaping percentages (\% instead of %). – jarauh Jan 22 '21 at 12:16
5

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.

M4RT1NK4
  • 433
  • 1
  • 4
  • 9
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.

Rob
  • 265
  • 2
  • 11