带有 devtools 的 R github 包：警告未知宏 '\item'答案

【问题标题】：R github package w/ devtools: warning unknown macro '\item'带有 devtools 的 R github 包：警告未知宏 '\item'
【发布时间】：2017-02-01 21:31:42
【问题描述】：

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

但是：当我安装我的包时

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 参数，它们都是标准的（但可能是下游问题，一旦上游问题得到解决，就会得到解决）。

谁能想到可能导致这种情况的原因？我的帮助页面现在都无法点击，尽管有人会认为无论这个脚本 (gbm.valuemap.R) 有什么问题，其他的都应该没问题？

提前致谢。

【问题讨论】：

\item 仅在逐项“环境”中有效。你确定你的文档是这样的 \item 只出现在 \itemize{ \item hi \item bye} 或 \enumerate{ \item hi \item bye} 中吗？还有\value、\description 和\examples 应该是@value、@description 和@examples。有关这方面的更多指导，请参阅 roxygen2 指南。
使用 RStudio 打开有问题的 .Rd 文件并预览如何？如果您有以前的工作版本，您还可以比较两个版本的 .Rd 之间的差异。另一个疯狂的猜测是，如果你手动编辑了一些文件，可能会有你没有意识到的编码/行结束更改。
它可能是 & 行中的“使用（例如）read.csv 并指定”，尽管我不完全确定。我记得有些标点符号有问题，尤其是%。将& 更改为and 可能值得一试。
大家好。 @Chrisss \items 在由 roxygen2 骨架自动创建的 \arguments{} 内，与一切正常时的方式相同。格式是例如#' 示例在 R 脚本的 Roxygen2 位中没有（我不能在此处包含 at 符号），所以那里都是正确的。 dracodoc 好主意 - 正如 Benjamin 预测的那样，它原来是 % 符号。干杯，我现在会编辑这个并希望能解决它。
我收到这个错误是因为我在文档中有一个百分号，%。

标签： r github documentation package devtools

【解决方案1】：

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

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

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

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

为了使这个答案更完整，以下是@Benjamin 关于格式化 Rd 文件的提示：

可能是“使用（例如）read.csv 和指定导入”之类的行中的 & 虽然我不完全确定。我记得有些标点符号是有问题，尤其是 %。将 & 改为 and 可能值得一试

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

来自@Thomas：

如果你有一个流浪者{某处也可以出现

【讨论】：

谢谢。其他有此问题的人，还请注意@Thomas 的注意事项，以提防杂散的花括号
使用预览功能的好技巧！

【解决方案2】：

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

错误/错误：

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

固定/解决方案：

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

【讨论】：

其他可能的问题可能是：使用方括号（例如，表示数字的间隔）或转义百分比（\% 而不是 %）。

【解决方案3】：

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

【讨论】：