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.
Related
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.
I am new to the R/exams package and I try to produce a pdf document from one of the templates provided by the developers. (http://www.R-exams.org/templates/confint3/)
I am able to compile a Rnw file into a HTML document using the commands
library("exams")
exams2html("confint3.Rnw")
When calling the function
exams2pdf("confint3.Rnw")
it gives the error message
! LaTeX Error: File `Sweave.sty' not found.
I have Latex installed and there are no problems using it in general. I do not understand:
Do I need to tell exams2pdf() the location of the latex installation?
Do I need to define a template (as plain.tex) first? How should it look like?
What is it that I do not understand?
I looked at the documentation of the exams package, I also tried exams2pdf() after installing and calling library("tinytex").
Any help where to look at or what to do is highly appreciated. Thank you!
Minimal example:
install.packages("exams")
install.packages("tth")
library("exams")
set.seed(1090)
exams2html("confint3.Rnw")
set.seed(1090)
exams2pdf("confint3.Rnw")
It is hard to diagnose what exactly goes wrong with the information provided. In any case, when running pdfLaTeX either through utils::texi2dvi() (the default when the R package tinytex is not installed) or through tinytex::latexmk() (the default when the R package tinytex is installed) does not find the Sweave.sty file provided by the R base system. What is not clear to me which LaTeX engine is running in the background: MikTeX on Windows?
There are several strategies that could resolve this issue:
Tell your LaTeX installation about the texmf directory provided by the R base system so that it is found no matter where on your system you call pdfLaTeX.
Use a different LaTeX installation, e.g., by installing TinyTeX (the LaTeX distribution) through tinytex (the R package): tinytex::install_tinytex(). This might be particularly attractive if you are not actually a LaTeX user and just need it to compile PDF exams.
Avoid using the Sweave.sty file in a custom template file, say myplain.tex. A suggestion for such a file is included at the end of this post.
Further details are discussed in this thread: https://tex.stackexchange.com/questions/153193/latex-error-sweave-sty-not-found
As for your three questions:
As already explained above: exams2pdf() leverages either utils::texi2dvi() or tinytex::latexmk(). So these need to know about the LaTeX installation - but this seems to be the case. They just don't find the texmf provided by base R.
You should not have to do this but it is certainly an option that you can use. As a starting point, run exams_skeleton(markup = "latex", writer = "exams2pdf"). Among other things this creates a templates folder where you could put the myplain.tex template below.
As I said above, it's hard to answer that with the information provided. Hopefully, one of the clues provided here gets you a couple of steps forward.
Content of myplain.tex:
\documentclass[a4paper]{article}
\usepackage[utf8]{inputenc}
\usepackage{a4wide,graphicx,color,verbatim,url,fancyvrb,ae,amsmath,amssymb,booktabs,longtable,eurosym}
\newenvironment{question}{\item \textbf{Problem}\newline}{}
\newenvironment{solution}{\textbf{Solution}\newline}{}
\newenvironment{answerlist}{\renewcommand{\labelenumi}{(\alph{enumi})}\begin{enumerate}}{\end{enumerate}}
\providecommand{\tightlist}{\setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}
\setkeys{Gin}{keepaspectratio}
\DefineVerbatimEnvironment{Sinput}{Verbatim}{fontshape=sl}
\DefineVerbatimEnvironment{Soutput}{Verbatim}{}
\DefineVerbatimEnvironment{Scode}{Verbatim}{fontshape=sl}
\newenvironment{Schunk}{}{}
\begin{document}
\begin{enumerate}
%% \exinput{exercises}
\end{enumerate}
\end{document}
I've been reading through R's Affy manual, and it refers to other vignettes. Does the difference between these two terms simply relate to quantity of content, or is there more to it?
Reference Manuals
The reference manual of a package is a single document beginning with the package description and containing all of the content from the .Rd help files for the packages. Generally, this means it has the help files for (exported) functions in the package, any documented data sets, and package-level documentation (if included). It is automatically generated from the .Rd sources.
Every package has a manual. Even a package with no exported functions and documentation would still have a manual (when built) consisting of the text from the Description file.
Vignettes
Vignettes are free-form documents. Generally, package authors use them to demonstrate the use of their package. They are optional, some packages have several (as I write this dplyr has 8 vignettes) and many packages have none.
As mentioned in the comments the R Extensions Manual is the definitive source for all things package-related. Here is Josh's link to the Vignettes Section, and 2.15 Processing documentation files describes how reference manuals are built.
I am wondering it there exists a method to link to function from other package when I'm trying to write a documentation for new package using roxygen2.
Something like \link{pck=PACKAGE_NAME, fun=FUNCTION_NAME}?
You have to type \link[pkg]{function} e.g. \link[stringi]{stri_c}
Roxygen2 now also supports documentation written in markdown.
The markdown syntax is for the link is [foo::bar()] which is translated to
\code{\link[foo:bar]{foo::bar()}} in the generated .Rd file. (See Roxygen2 vignette.)
Note that you may need to specifically turn on Markdown support by writing Roxygen: list(markdown = TRUE) in your DESCRIPTION file, or by putting an #' #md comment if you want to enable markdown only for a specific man page. This is also explained at the very top of the linked vignette. (Thanks to #Tjebo for the comment)
Note that there are two colons in the markdown version whereas there is only one colon in the Rd version.
There are two ways to achieve this, using:
1. .Rd syntax
From "R packages" book:
\code{\link{function}} - function in this package.
\code{\link[MASS]{abbey}} - function in another package.
\link[=dest]{name} - link to dest, but show name.
\code{\link[MASS:abbey]{name}} - link to function in another package, but show name.
\linkS4class{abc} - link to an S4 class.
2. markdown syntax
From roxygen2 vignette
roxygen2 comment
description
generated Rd code
[func()]
func() in this package
\code{\link[=func]{func()}}
[pkg::func()]
func() in the pkg
\code{\link[pkg:func]{pkg::func()}}
[thing]
topic in this package
\link{thing}
[pkg::thing]
topic in the pkg
\link[pkg:thing]{pkg::thing}
[`thing`]
topic in this package
\code{\link{thing}}
[`pkg::thing`]
topic in the pkg
\code{\link[pkg:thing]{pkg::thing}}
Remember to put Roxygen: list(markdown = TRUE) in the DESCRIPTION
Markdown shortcodes available from roxygen2>=6.0.0
In addition to the answer by potockan:
Some packages document several functions in a single help page. For example, the trim function from Bioconductor package GenomicRanges is documented in intra-range-methods (which is also the name of a help page from other packages such as IRanges).
To link to the right page with roxygen2 you can use:
\link[GenomicRanges:intra-range-methods]{trim}
or
\code{\link[GenomicRanges:intra-range-methods]{trim}}
to format the text correctly.
The help page will only show trim but will link to the right help page.
To link to a function, we slightly abuse markdown syntax by using [function()] or [pkg::function()].
Re-document your package by pressing Cmd/Ctrl + Shift + D.
Build and install your package by clicking in the build pane or by pressing Ctrl/Cmd + Shift + B. This installs it in your regular library, then restarts R and reloads your package.
Preview documentation with ?
I'm planning to condense some of my code into a package, and was looking at the source of a few published packages on CRAN as a guide. I notice many packages include the file R\zzz.R, so I presume there must be some convention surrounding this.
However, I cannot find any mention of zzz.R in the official Writing R Extensions guide. What is this file for, and do I need to include one in my package? Why is it named the way it is - why not zzzz.R?
It's a file where one usually puts actions on load of the package. It is tradition/convention that it's called zzz.R and could be called anything.R
You only need to include this if you want you package to do something out of the ordinary when it loads. Keep looking at what people put in there and you'll begin to get a sense of what they're used for.
This zzz.R file was also mentioned by Hadley Wickham in his book "R packages", at the bottom of "When you do need side-effects" section.
https://r-pkgs.org/Code.html#when-you-do-need-side-effects
If you use .onLoad(), consider using .onUnload() to clean up any side effects. By convention, .onLoad() and friends are usually saved in a file called R/zzz.R. (Note that .First.lib() and .Last.lib() are old versions of .onLoad() and .onUnload() and should no longer be used.)