R github包与devtools: 警告未知宏'\item'

Question

我使用RStudio和devtools的帮助创建了一个包，用于命名空间、DESCRIPTION和Roxygen2的man页面。这个过程很顺利，我最近添加的帮助页面也可以正常工作。我决定添加作者姓名、电子邮件和一些详细信息。最开始我通过手动编辑man页面文件（不好）然后编辑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）有问题的问题，其他脚本应该都没问题?

提前感谢。

- dez93_2000

---

\item只能在“itemize”环境中使用。你确定你的文档是这样的，\item只会出现在\itemize{ \item hi \item bye}或\enumerate{ \item hi \item bye}里吗？另外，\value、\description和\examples应该改为@value、@description和@examples。请参考roxygen2指南获取更多关于此的指导信息。 - Chrisss

用RStudio来打开有问题的.Rd文件并预览一下怎么样？如果您有之前工作正常版本，也可以比较两个版本的.Rd文件的差异。另一个猜测是，如果您手动编辑了某个文件，则可能存在您没有意识到的编码/行结束符更改。 - dracodoc

可能是像"使用（例如）read.csv＆指定"中的"&"符号导致问题，尽管我不完全确定。我记得有些标点符号会出现问题，特别是"% "。尝试将"&"改为"and"可能值得一试。 - Benjamin

大家好。@Chrisss，\items在\arguments{}中，这是由roxygen2骨架自动创建的，当一切正常时，它的格式是相同的。例如，在R脚本的Roxygen2部分中，没有示例（我无法在此处包含at符号），所以一切都正确。dracodoc的想法很棒——结果是百分号，就像Benjamin预测的那样。谢谢大家，我现在会编辑并希望解决问题。 - dez93_2000

我之所以出现这个错误，是因为我的文档中有一个百分号符号“%”。 - Sal Mangiafico

Answer 1

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

1. 使用构建和加载工具来构建项目中的软件包。您可以一键构建、更新文档（您可能需要在Roxygen2设置中检查更多选项，因为有些选项默认未打开），并加载软件包。您遇到的错误应该尽早发现，而且您无需手动安装即可进行测试。

2. 使用预览功能来预览 .Rd 文件。

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

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

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

可能是类似于“使用（例如）read.csv＆amp; specify”的行中的 & 这个符号。虽然我不是完全确定。我记得一些标点符号会有问题，特别是“%”。将 & 更改为 and 可能值得一试。

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

从@Thomas这里得到的信息：

如果在某个位置有一个杂项 {，也可能会出现该问题。

- dracodoc

---

谢谢。任何遇到此问题的人，请注意 @Thomas 的提示，要小心多余的花括号。 - dez93_2000

使用预览功能是一个很好的技巧！ - jbaums

Answer 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
}

- Samantha Karlaina Rhoads

---

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

Answer 3

对我而言，问题出在文本中使用了“%”符号。当我将其删除或转义（"\%"）时，便不再抛出错误。如果您在编辑器中打开 roxygen 生成的 .Rd 文件，它可以为您提供提示，对我来说，“%”后面的文本呈现不同颜色。

- M4RT1NK4

---

多么有趣，我完全忘记了这个问题，但昨天碰巧在使用另一个软件包时遇到了同样的问题，并意识到百分号是导致问题的原因。干杯！ - dez93_2000

是的，在文本中转义％字符也解决了这个问题。 - Kasper Skytte Andersen

Answer 4

我曾遇到与“未知宏‘\item’”相同的错误，并通过从文件中删除重复的“@作者XXX”行来解决它。似乎重复的不应重复的“@ {item}”参数可能会引发该错误。

- Rob