I konw that's kind of a meta question but here it is: Is RefManageR the new citr package in R?
I am using citr since 1 year now and I just realized that it is not maintained on the CRAN anymore (https://cran.r-project.org/web/packages/citr/index.html). Otherwise, they refer to the package RefManageR (https://cran.r-project.org/web/packages/RefManageR/index.html).
I am using a bookdown project to compile pdf/html/docx document from Markdown and would like to know if it is compatible
I think they have different purposes:
RefManageR helps with handling .bib files (e.g. if you want to read into R your bibliography collection taken from Zotero). Something like:
bib_path <- here::here ("my_folder", "my_bibliography.bib")
# as list
mybib <- RefManageR::ReadBib(bib_path, check = FALSE )
While citr, which is now only available as development version, is a very handy Rstudio Addin that allows you to easily enter a bibliography item in your Bookdown/RMarkdown document - drawing from the .bib file in your environment as shown here.
Related
I have succsesfully performed the below steps to create my own R package :
created skeleton of the package and pasted .Rd, NAMESPACE and DESCRIPTION files.
executed R CMD check package_name : no errors, it also generated 2 pdf's
One of which contains the output's from .Rd file examples and second is the PDF manual that comprises the documentation itself.
My question is how to make edits to this manual created, such as to change the font size or add an Introductory page to this manual? I read that roxygen / devtools might help but no resource on that was attained. I also went through the Writing R Extensions link that is available but couldn't help me.
Would there be a way using Rd2pdf? but such that even non .Rd files are also included
As in this question, I would like to include citations to articles in function documentation. I use roxygen2 for all documentation, and it appears that there was a pull request to roxygen2 with the necessary functionality, but Hadley turned it down since roxygen2 was in maintenance mode. Have things changed since then? Is there another way to cite/ include article references stored in BibTeX format?
The Rdpack package promises to deliver the functionality that you requested.
To get set up, you also need to add the line RdMacros: Rdpack to your package's DESCRIPTION file (note the capital M), and add Rdpack to the Imports: field.
Then you can save your bibtex library in to inst/REFERENCES.bib, and cite them in your documentation with:
#' #references{
#' \insertRef{bibtexKey}{YourPackageName}
#' }
#'
#' # The below line ought to be included in at least one of your documentation
#' # sections, so that roxygen2 adds Rdpack to your NAMESPACE file.
#'
#' #importFrom Rdpack reprompt
I initially encountered some errors when first using the package; re-starting R seemed to do the trick.
Warnings about unknown macro '\insertRef' will be encountered if building documentation with devtools::document(), as devtools does not read the 'RdMacros' line of the DESCRIPTION file; they can be safely ignored. The references may not be rendered correctly by devtools, but will be when the package is finally built; to view them in their proper formatting in the interim you can run R CMD Rd2pdf from a separate command window.
Nicely summarized by ms609. I would add that the releases of Rdpack in 2018 provided also macros for citation and the ability to produce the bibliography with a single command insertAllCited{}. Vignette Inserting_bibtex_references, linked also by ms609, provides up-to-date information.
Rdpack::viewRd() can be used to view the rendered citations without building the package, something like:
Rdpack::viewRd("./man/filename.Rd") # text
Rdpack::viewRd("./man/filename.Rd", type = "html") # html
This may be particularly useful for roxygen2 users since roxygen2 processes the Rd files but doesn't render the references. Just don't forget to update the documentation using devtools::document() or another suitable command before invoking Rdpack::viewRd().
http://cran.r-project.org/doc/manuals/r-release/R-exts.html#Writing-package-vignettes states:
"...In addition to the help files in Rd format, R packages allow the inclusion of documents in arbitrary other formats. The standard location for these is subdirectory inst/doc of a source package, the contents will be copied to subdirectory doc when the package is installed. Pointers from package help indices to the installed documents are automatically created. Documents in inst/doc can be in arbitrary format, however we strongly recommend providing them in PDF format, so users on almost all platforms can easily read them..."
I used roxygen package. It produced .Rd files for me. I produced .pdf of my package via " R CMD Rd2pdf causfinder/" from Windows command line ( or, via during build/install process via "roxygenize("causfinder"); build("causfinder"); install("causfinder")".)
I wanted to add some supplementary .pdf help files (that I created outside of R; from Word via save as .pdf etc.) to my package other than the one that is produced via above techniques. These supplementary .pdf files include the detailed mathematical theory and lots of samples of the functions of my package which illustrate the usage of the functions via various plots, graphs, etc. I called it TheoryOfcausfinder.pdf.
I wanted to add this supplementary .pdf file to my package. As is directed from R's above manual, I put TheoryOfcausfinder.pdf to inst\doc folder in my R's working directory. Upon build/install process, I obtained causfinder/doc/index.html and causfinder/doc/TheoryOfcausfinder.pdf in my R's library location.
The content of index.html:
"...Vignettes from package 'causfinder': The package contains no vignette meta-information.
Other files in the doc directory: TheoryOfcausfinder.pdf..."
I want the future users of causfinder to easily access/open this supplementary TheoryOfcausfinder.pdf. (I will add that there is such a file in functions' help documents)
Is there a way to open/access TheoryOfcausfinder.pdf in R's library location from (within) R's console?
(Important: By the way, since I am novice of Sweave and knitr, I do not wanna enter that path! I look for a solution outside Sweave and knitr.)
Any help will be greatly appreciated.
I don't know if you have found another solution or not yet, but I am posting some possible ideas below.
source http://www.r-bloggers.com/show-me-the-pdf-already/
# under Unix types
pdf <- getOption("pdfviewer", default='')
f <- system.file("doc", "TheoryOfcausfinder.pdf", package = "causfinder")
system2(pdf, args = f)
source http://www.r-bloggers.com/show-me-the-pdf-already/
# under MS Windows
f <- system.file("doc", "TheoryOfcausfinder.pdf", package = "causfinder")
shell.exec(normalizePath(f))
source Opening PDF within R studio using file.show studio-using-file-show/33791818
# under OS X
f <- system.file("doc", "TheoryOfcausfinder.pdf", package = "causfinder")
system2('open', args = f, wait = FALSE)
What is the proper way, to include a static PDF file as a "vignette" in a CRAN package as of R 3.0?
The trick described in this document of using an empty stub Rnw does not seem to work in R 3.0. The document suggests that there is now a better way based on \VignetteEngine{} but it's not quite clear how this works for static PDF files.
With R.rsp (>= 1.19.0) you can include a static PDF 'vignettes/main.pdf' by adding a tiny 'vignettes/main.pdf.asis' text file that contains:
%\VignetteIndexEntry{My amazing package}
%\VignetteEngine{R.rsp::asis}
and make sure to have:
Suggests: R.rsp
VignetteBuilder: R.rsp
in your package's DESCRIPTION file. This also works for static HTML vignettes. This is also explained in one of the R.rsp vignettes.
This works with a plain LaTeX trick as described in in this blog post.
I recently switched to doing this with the current R version (i.e. now 3.6.0), see this wrapper .Rnw file which contains just:
\documentclass{article}
\usepackage{pdfpages}
%\VignetteIndexEntry{Using Annoy in C++}
%\VignetteKeywords{Rcpp, Annoy, R, Cpp, Approximate Nearest Neighbours}
%\VignettePackage{RcppAnnoy}
\begin{document}
\includepdf[pages=-, fitpaper=true]{UsingAnnoyInCpp.pdf}
\end{document}
The advantage is that this uses Sweave for a completely traditional vignette build, and imposes no additional dependencies whatsover.
UPDATE 2014-06-08: For a better solution to including static PDFs and HTML files in an R package, see my other answer in this thread on how to use R.rsp (>= 0.19.0) and its R.rsp::asis vignette engine.
All you need is a <name>.Rnw file with a name matching your static <name>.pdf file, e.g.
vignettes/
static.pdf
static.Rnw
where <name>.Rnw (here static.Rnw) is a minimal valid Sweave file, e.g.
%\VignetteIndexEntry{<title to be displayed on the R vignette index page>}
\documentclass{article}
\begin{document}
\end{document}
This vignette source file (<name>.Rnw) tricks R CMD build to build it, i.e. R's tools::buildVignettes() will first Sweave <name>.Rnw into <name>.tex as usual. However, due to how buildVignettes() is designed it will detect our static <name>.pdf file as already being created by the Sweave engine and therefore it will not compile that dummy TeX file into a PDF file (which would overwrite our static file).
What is important to understand is that (i) vignettes are "build" during R CMD build, (ii) and when built they are copied over to the inst/doc/ directory (created if missing) of the built package. Also, (iii) the vignettes/ directory will not be part of the build package, i.e. <pkgname>_<version>.tar.gz file. So, make sure to look in inst/doc/.
So, to be clear here, using a dummy <name>.Rnw could be considered a hack that may break if someone decides to prevent against this strategy. However, if that happens, it is fully possible to create a non-Sweave vignette engine which sole purpose is to compile a <name>.pdf file into a ... <name>.pdf file. This is valid and possible due to the non-Sweave support added in R (>= 3.0.0). I've been considering adding such engine to the R.rsp package, e.g. \VignetteEngine{R.rsp::StaticPDF}. With that you would not even have to have that dummy Rnw file - only the PDF file.
Hope this helps
Can I include some PDF in the pkg/doc folder so that the vignette function works, but no corresponding Rnw, Rtex, etc exists?
I am thinking of slides or documents containing markdown text weaved with R chunks, which have a different build process and hence different file extensions.
The writing R extensions guide suggests that it should be possible to include documents which can not be build at installation time, but the vignette function seems to look for files with special extensions (Rnw, Rtex, etc) and also for a file called vignette.rds.
Any hints are appreciated.
I asked about this several years ago, and while Fritz Leisch is amenable to the idea, he hasn't had the time to implement it.
(Cross-posted from a response I just left on R-help:)
As a workaround, you could include your own xvignette function in your package: see below.
It won't show you indices, but it will pick up any appropriately named file that you include in the inst/doc directory of your
package ...
xvignette <- function(vname,pkg,ext="pdf") {
vname <- paste(vname,ext,sep=".")
fn <- system.file("doc",vname,package=pkg)
if (nchar(fn)==0) stop("file not found")
utils:::print.vignette(list(pdf=fn))
invisible(fn)
}
You'll have to somehow alert your package users to the fact that this alternative documentation exists -- perhaps in the help file for the package itself.
You might fill in the default value of pkg above with your package name to make it easier on the user: I thought about using some variant of getPackageName(environment(xvignette)) to do it automatically, but that seems too complicated ...
Brian Ripley also mentioned in his response to the question that:
At present vignette() means Sweave documents, as only they have
metadata like titles. This is planned to be changed soon.
... but I don't know what "soon" means (it will be about 6 months until 2.14.0 comes out, I think)
edit: http://article.gmane.org/gmane.comp.lang.r.devel/28449 details another workaround (creating a dummy vignette that incorporates the existing PDF file)
edit 2: And
here's what Yihui Xie has to say about including knitr-based vignettes in packages (essentially another "dummy vignette" strategy)
vignette about non-Sweave vignettes from the R.rsp package
This is supported natively as of R 3.0.0, see http://yihui.name/knitr/demo/vignette/.
Instructions to use knitr as vignette engine boil down to:
add %\VignetteEngine{knitr::knitr} to the Rnw source document (note you still need %\VignetteIndexEntry{} as before)
specify VignetteBuilder: knitr in the package DESCRIPTION file
add Suggests: knitr in DESCRIPTION if knitr is needed only for vignettes
See also the official R documentation on that topic.