R github 包 w/devtools：警告未知宏 '\item'

Question

我在 RStudio 和 devtools 的帮助下制作了一个包，用于命名空间，DESCRIPTION 和 Roxygen2 用于手册页。这工作正常，我最近添加的帮助页面也工作正常。我决定添加作者姓名、电子邮件和一些详细信息。最初通过手动编辑手册页文件 (BAD) 然后编辑 R 脚本 Roxygen2 部分并将更改推送到 Rm 文件 document()

但是：当我安装我的包时

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

我收到以下警告：

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 '
'

这些项目只是简单的 @param 参数，我没有改变，看起来很好并且以前工作过。同上 value / description / examples 参数，它们都是标准的（但可能是下游问题，一旦上游问题得到解决，就会得到解决）。

谁能想到是什么原因造成的？ None 我的帮助页面现在可以点击了，尽管有人会认为无论一个脚本 (gbm.valuemap.R) 有什么问题，其他的都应该没问题吗？

提前致谢。

Answer 1

您可以使用 RStudio 在几个方面帮助开发包：

在打包项目的构建面板中使用构建和加载工具。您可以构建、更新文档（您可能需要在有关 Roxygen2 的设置中查看更多选项，有些默认情况下未打开）、一键加载包。你遇到的错误应该早点发现，不需要手动安装测试
使用 .Rd 文件的预览功能

另一种方法是比较工作版本和非工作版本源文件，.rd 文件以找出差异。

通常应避免直接编辑生成的文件。

为了使这个答案更完整，这里有来自@Benjamin 的关于在 Rd 文件中格式化的提示：

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。在 .Rd 文档文件或底层 roxygen 注释中将 % 更改为 \% 应该可以防止与使用 % 符号相关的问题。这是由于使用了 LaTeX。

来自@Thomas：

Can also come up if you have a stray { somewhere

Answer 2

对我来说，当我在我正在编写的库中的函数描述中使用 \n 时发生了这种情况（我正在描述反斜杠 "n" 转义序列的含义。我修复了它通过在函数的 .Rd 文件中转义转义序列本身来实现。示例：

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
}

Answer 3

我在 unknown macro '\item' 中遇到了同样的错误，并通过从文件中删除重复的 @author XXX 行解决了这个问题。似乎重复 @{item} 不应该重复的参数可能会引发该错误。

Answer 4

对我来说，问题是在文本中使用“%”符号。当我删除它或转义它 ("\%") 时，它不再抛出错误。如果你在编辑器中打开 roxygen 生成的 .Rd 文件，它可以给你一个提示，对我来说，% 之后的文本颜色不同。

R github 包 w/devtools：警告未知宏 '\item'

R github package w/ devtools: warning unknown macro '\item'

documentation

r

github

devtools

package