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.
You can use RStudio to help on package development in several aspects:
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.
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
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
}
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.
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.
Related
When I try to render the latest version of the book R for Data Science (R4DS), I get as far as LaTeX compilation, then am stopped by the following error message.
! Text line contains an invalid character.
l.406 #> -- ^^[
[1mAttaching packages^^[[22m --------------------------------...
Error: LaTeX failed to compile _main.tex. See https://yihui.org/tinytex/r/#debugging for debugging tips. See _main.log for more info.
>
This corresponds to the part of the R4DS book where we are shown how to load the tidyverse and, looking at the _main.tex file, I see many lines with what look like ANSI escape sequences starting on this line. They have the form ^[[1m, ^[[22m, and so on. I manually compiled the LaTeX output using lualatex and found that there are dozens if not hundreds of examples of this throughout the book. I suspected it was because I was using the colorout package in R, but it appears that that package is required, so others who are rendering successfully must be using it too. I believe I have successfully updated all relevant packages.
It looks like I "solved" the problem by changing an option in the _common.R file from crayon.enabled=TRUE to crayon.enabled=FALSE. This removed the ANSI escape sequences from the book. Previously I had tried setting options(crayon.enabled=FALSE) in my R session, but this was evidently being overridden by the setting in _common.R.
Update: 23 Nov 2022
The process for rendering the files is completely different now because of the switch to Quarto. Here's how I did it.
Rscript -e 'update.packages()'
Rscript -e 'install.packages('quarto')'
Rscript -e 'devtools::install_github("hadley/r4ds")
git clone https://github.com/hadley/r4ds.git
cd r4ds
Next, I wrote a small perl script to avoid the error messages I was getting about trying to render html material to pdf. (I'm omitting a lot of dead-ends I encountered in the process.)
#!/usr/bin/perl
use File::Slurp qw(prepend_file);
my #files = glob( '*.qmd' );
my $header = "\n---\nprefer-html: true\n---\n\n";
foreach my $file (#files) {
prepend_file($file, $header);
}
I ran the above script in the r4ds directory.
Next I loaded R and did the following:
library(quarto)
quarto_render("index.qmd", output_format = "pdf")
The above failed with the error message: "\begin{document} not found". Luckily, the aborted process leaves an index.tex file I can process and also gives a line number for the error. I went to that line number in the index.tex file and deleted the block of html I found there.
After that, I ran
lualatex index.tex
twice and got a successful render, minus the cover page. (You could presumably run xelatex index.tex instead.) There are a lot of problems with my render, such as the plots being too large to fit on the page. If I decide to spend time fixing them (unlikely, since Hadley seems to want us to use the online version) I'll modify this answer.
I was getting this error when running devtools::document but had no idea how to troubleshoot. The file that popped up on my installed package when I entered ?MyPackage-package did not match the text in MyPackage-package.R at all. I initially suspected it might have been from adding the awesome citation functionality from RDpack, but this was not the culprit. How did I go about ultimately fixing the problem?
The error resulted from incorrect formatting in my PackageName-package.R file.
I had heavily edited the file created by usethis::use_package_doc(), and added all of my roxygen comments Below the default content added by usethis. After looking at the documentation for merTools, I saw that it was ok to have the stuff I understand to be important for roxygen2 to make the .Rd files after and not before all the other roxygen comments.
After moving the stuff created by usethis::use_package_doc() (and not just the NULL line; that was already at the end) to the bottom of the .R file, everything seemed to render fine and this error disappeared.
When I try to use roxygen2::roxygenize() in RStudio, I get an error message. The message I am coming across is this:
Warning message:
trainModel.Rd not generated by roxygen2. Skipped.
I have tried so much to fix this, but it just won't get fixed unless I remove all of the #' comments out (which would remove the purpose of using roxygen2 in the first place). I even took out everything except for the parts describing the title, description, and details and the error still persists (which makes me imagine that the error is in one of those three parts. But how?). My other document's Rd file gets generated just fine, but this one does not. Can somebody please help?
Try deleting the current Rd file.
I replicated this warning by creating file with your function, roxygenizing the code, and then removing the lines from the resulting Rd file
% Generated by roxygen2 (4.1.1): do not edit by hand
% Please edit documentation in R/trainmode.R
It looks like roxygen2 doesn't want to overwrite files it didn't create. If you delete the current trainmode.Rd file, roxygen2 will generate a new .Rd file the next time roxygenize your code.
In an earlier post, I asked about declaring such functions in R packages and making them work. Having succeeded, I'm now trying to document one such function.
I created an Rd file with the function's name as a title, but when running the CHECK, I get the following warning:
* checking for missing documentation entries ... WARNING
Undocumented code objects:
'%IN%'
I tried several names such as %IN%.Rd or '%IN%'.Rd, to no avail. Any hints on how to make this work?
The goto guide would definitely be section 2.1.1 "Documenting functions"[1] of the "Writing R Extensions" manual. As #joran pointed out in a comment the important part maybe the use of an \alias. According to the "Writing R extensions" manual the %s need to be escaped at least in \alias and in the text. About \name it states: " [name should not contain] ‘!’ ‘|’ nor ‘#’, and to avoid possible problems with the HTML help system it should not contain ‘/’ nor a space. (LaTeX special characters are allowed, but may not be collated correctly in the index.)"[2] and about \alias: " Percent and left brace need to be escaped by a backslash."[3]
Running LyX on Windows 7 with MiKTeX. I was trying to export LyX's "Embedded Objects tutorial" to PDF, but got this error:
Undefined control sequence
\hline
The control sequence at the end of the top line
of your error message was never \def'ed. If you have
misspelled it (e.g., `\hobx'), type `I' and the correct
spelling (e.g., `I\hbox'). Otherwise just continue,
and I'll forget about whatever was undefined.
The offending code seems to be
\let\myHlineC\hline
\renewcommand{\hline}
{\arrayrulecolor{red}\myHlineC\arrayrulecolor{black}}
(section 2.11.2 of the document).
May or may not be relevant: The document's preamble.
You can download the pdf of the manual online here:
http://wiki.lyx.org/LyX/DocumentationDevelopment#EmbeddedObjects
Do you have the following packages installed?
arydshln, colortbl, diagbox, lettrine, marginnote, picinpar and sidecap
Although it says that you should be able to export without them, I've found that sometimes they are required. If this is true in your case, can you post which package was causing the problem so we can try to fix the document? To find this out, install the above packages one by one and test if you can export after each one. Don't forget to reconfigure LyX via Tools > Reconfigure after each install of a new package.