mathjaxr/ 0000755 0001762 0000144 00000000000 14207153672 012077 5 ustar ligges users mathjaxr/NAMESPACE 0000644 0001762 0000144 00000000023 13657731606 013320 0 ustar ligges users export(preview_rd)
mathjaxr/README.md 0000644 0001762 0000144 00000013437 14207135707 013365 0 ustar ligges users mathjaxr: Using Mathjax in Rd Files
===================================
[](https://github.com/wviechtb/mathjaxr/actions)
[](https://CRAN.R-project.org/package=mathjaxr)

## Description
The `mathjaxr` package allows for easy inclusion of [MathJax](https://www.mathjax.org/) equations in Rd files. Package authors wanting to make use of the package and its functionality need to:
1. install the `mathjaxr` package,
2. add `mathjaxr` to `Imports` in the `DESCRIPTION` file of their package,
3. add `mathjaxr` to `RdMacros` in the `DESCRIPTION` file of their package (or add `RdMacros: mathjaxr` if the `DESCRIPTION` file does not yet contain a `RdMacros` entry),
4. add `import(mathjaxr)` in the `NAMESPACE` file of their package.
One can then enable the use of MathJax by calling the `\loadmathjax` macro (that is provided by the `mathjaxr` package) within the `\description{}` section of an Rd file (or within the `@description` section when using `roxygen2`).
An inline equation can then be added with the `\mjeqn{latex}{ascii}` macro, with the LaTeX commands for the equation given between the first set of curly brackets (which will be rendered in the HTML and PDF help pages) and the plain-text version of the equation given between the second set of curly brackets (which will be shown in the plain text help). With the `\mjdeqn{latex}{ascii}` macro, one can add 'displayed equations' (as in LaTeX's `displaymath` environment).
Single argument versions of these macros, `\mjseqn{latexascii}` and `\mjsdeqn{latexascii}`, are also available. For the relatively rare case that one must specify different LaTeX commands for the PDF and HTML pages, there are also triple argument versions of these macros, namely `\mjteqn{pdflatex}{htmllatex}{ascii}` and `\mjtdeqn{pdflatex}{htmllatex}{ascii}`.
## Details
The Javascript code for MathJax is contained in this package. If a user viewing a help page has `mathjaxr` installed, it will be retrieved from there, otherwise it will be retrieved from the CDN site https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml-full.js. To force use of the CDN site, the user can set the environment variable `MATHJAXR_USECDN` to any non-blank value (e.g., `Sys.setenv(MATHJAXR_USECDN=TRUE)`). The URL for a diferent CDN can be specified via the environment variable `MATHJAXR_CDN`.
## Notes/Issues
- Care must be taken when using the less-than and greater-than symbols in equations as these might get interpreted by the browser as HTML tags. See [here](https://docs.mathjax.org/en/latest/input/tex/html.html) for further details. Adding space around these symbols should solve this problem (e.g., instead of writing `\mjseqn{i
where  denotes the mean of the distribution and  its standard deviation.
## Installation
The current official (i.e., [CRAN](https://cran.r-project.org/package=mathjaxr)) release can be installed within R with:
```r
install.packages("mathjaxr")
```
The development version of the package can be installed with:
```r
install.packages("remotes")
remotes::install_github("wviechtb/mathjaxr")
```
This builds the package from source based on the current version on [GitHub](https://github.com/wviechtb/mathjaxr). Note that Windows users must have [Rtools](https://cran.r-project.org/bin/windows/Rtools/rtools40.html) installed for this to work.
## Meta
The `mathjaxr` package is licensed under the [GNU General Public License Version 3](https://www.gnu.org/licenses/gpl-3.0.txt), while MathJax itself is licensed under the [Apache License, Version 2.0](https://github.com/mathjax/MathJax/blob/master/LICENSE). To report any issues or bugs, please go [here](https://github.com/wviechtb/mathjaxr/issues).
mathjaxr/man/ 0000755 0001762 0000144 00000000000 14207127734 012652 5 ustar ligges users mathjaxr/man/preview_rd.Rd 0000644 0001762 0000144 00000005520 14207130230 015272 0 ustar ligges users \name{preview_rd}
\alias{preview_rd}
\title{Preview rendered version of an Rd file}
\description{
Function to preview the rendered version of an Rd file.
}
\usage{
preview_rd(Rdfile, view = TRUE, type = "html", verbose = FALSE, dark = FALSE, \dots)
}
\arguments{
\item{Rdfile}{character string with the name of the Rd file to preview (either with or without the \code{.Rd} or \code{.rd} extension).}
\item{view}{logical indicating whether the rendered version of the help file should be displayed.}
\item{type}{character string indicating which version should be rendered (either \code{"html"}, \code{"txt"}/\code{"text"}, or \code{"pdf"}).}
\item{verbose}{logical indicating whether diagnostic output will be shown.}
\item{dark}{logical indicating whether the rendererd HTML page should use a dark mode.}
\item{\dots}{other arguments.}
}
\details{
The function is useful when writing a help file that contains MathJax equations. Instead of having to reinstall the package under development to check if the equations are being rendered correctly, one can just set the current working directory to the root of the package (or its \code{man} directory) and then use \code{preview_rd()} to preview the HTML, plain-text, or PDF version of an Rd file on the fly.
For \code{type="html"}, the HTML page will be opened in the browser with the \code{\link{browseURL}} function. When making further changes to the Rd file, reopening the page each time with \code{preview_rd()} is inconvenient as this will usually open up a new tab in the browser. Setting \code{view=FALSE} prevents this. Reloading the page in the open tab should then reflect the updates. In RStudio, the generated HTML version will be displayed in the \sQuote{Viewer} pane and the \code{view} argument is then irrelevant.
Setting \code{dark=TRUE} (in combination with \code{type="html"}) renders the HTML page in dark mode. Unfortunately, this does not work in RStudio.
For \code{type="txt"} (or \code{type="text"}), the plain-text version of the help file will be shown (using the \code{\link{file.show}} function and directly on the console in RStudio).
For \code{type="pdf"}, the PDF is generated using \command{R CMD Rd2pdf} and should open up in the default PDF viewer.
}
\note{
Any links to local help pages used in the Rd file to preview will be shown in the rendered HTML or PDF help file, but are non-functional.
Due to some limitations as to how MathJax can be loaded via the \pkg{mathjaxr} package, MathJax must be loaded via the CDN when using the \code{preview_rd()} function. Hence, rendering of equations in HTML will only work in the preview with an active internet connection.
}
\author{
Wolfgang Viechtbauer \email{wvb@wvbauer.com} \url{https://www.wvbauer.com/}
}
\examples{
\dontrun{
setwd("/path/to/root/of/package")
preview_rd("someRdfile")
}
}
\keyword{utilities}
mathjaxr/man/macros/ 0000755 0001762 0000144 00000000000 14144301562 014127 5 ustar ligges users mathjaxr/man/macros/mathjax.Rd 0000644 0001762 0000144 00000005073 14144301562 016057 0 ustar ligges users % macro to load MathJax
%\newcommand{\loadmathjax}{\if{html}{\Sexpr[results=rd,stage=render]{if (nchar(system.file("doc/mathjax/es5/tex-chtml-full.js", package="mathjaxr")) && !nzchar(Sys.getenv("MATHJAXR_USECDN"))) '\\\\\\out{}' else '\\\\\\out{}'}}}
%\newcommand{\loadmathjax}{\if{html}{\Sexpr[results=rd,stage=render]{MATHJAXR_USECDN <- Sys.getenv("MATHJAXR_USECDN"); MATHJAXR_CDN <- Sys.getenv("MATHJAXR_CDN"); if (!nzchar(MATHJAXR_CDN)) MATHJAXR_CDN <- "https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml-full.js"; PATH <- system.file('doc/mathjax/es5/tex-chtml-full.js', package='mathjaxr'); TEXT <- paste0("if (nchar(\"", PATH, "\") && !nzchar(\"", MATHJAXR_USECDN, "\")) '\\\\\\\\\\\\\\out{}' else '\\\\\\\\\\\\\\out{}'"); eval(str2expression(TEXT))}}}
\newcommand{\loadmathjax}{\if{html}{\Sexpr[results=rd,stage=render]{MATHJAXR_USECDN <- Sys.getenv("MATHJAXR_USECDN"); MATHJAXR_CDN <- Sys.getenv("MATHJAXR_CDN"); if (!nzchar(MATHJAXR_CDN)) MATHJAXR_CDN <- "https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml-full.js"; PATH <- system.file("doc/mathjax/es5/tex-chtml-full.js", package="mathjaxr"); if (nchar(PATH) && !nzchar(MATHJAXR_USECDN)) '\\\\\\out{}' else paste0('\\\\\\out{}')}}}
% two-argument macros \mjeqn{latex}{ascii} and \mjdeqn{latex}{ascii}
\newcommand{\mjeqn}{\ifelse{html}{\emph{}\out{\(#1\)}}{\eqn{#1}{#2}}}
\newcommand{\mjdeqn}{\ifelse{html}{\out{\[#1\]}}{\deqn{#1}{#2}}}
% single-argument macros \mjseqn{latexascii} and \mjsdeqn{latexascii}
\newcommand{\mjseqn}{\ifelse{html}{\emph{}\out{\(#1\)}}{\eqn{#1}}}
\newcommand{\mjsdeqn}{\ifelse{html}{\out{\[#1\]}}{\deqn{#1}}}
% tripple-argument macros \mjteqn{pdflatex}{htmllatex}{ascii} and \mjtdeqn{pdflatex}{htmllatex}{ascii}
% \newcommand{\mjteqn}{\ifelse{latex}{\eqn{#1}}{\ifelse{html}{\out{\(#2\)}}{\eqn{#3}}}}
% \newcommand{\mjtdeqn}{\ifelse{latex}{\deqn{#1}}{\ifelse{html}{\out{\[#2\]}}{\deqn{#3}}}}
\newcommand{\mjteqn}{\if{latex}{\eqn{#1}}\if{html}{\emph{}\out{\(#2\)}}\if{text}{\eqn{#3}}}
\newcommand{\mjtdeqn}{\if{latex}{\deqn{#1}}\if{html}{\out{\[#2\]}}\if{text}{\deqn{#3}}}
mathjaxr/man/mathjaxr-package.Rd 0000644 0001762 0000144 00000011762 14144301677 016357 0 ustar ligges users \name{mathjaxr-package}
\alias{mathjaxr-package}
\alias{mathjaxr}
\docType{package}
\title{Using MathJax in Rd Files}
\description{
\loadmathjax
The \pkg{mathjaxr} package allows for easy inclusion of \href{https://www.mathjax.org/}{MathJax} equations in Rd files. Package authors wanting to make use of the package and its functionality need to:
\enumerate{
\item install the \pkg{mathjaxr} package,
\item add \verb{mathjaxr} to \verb{Imports} in the \file{DESCRIPTION} file of their package,
\item add \verb{mathjaxr} to \verb{RdMacros} in the \file{DESCRIPTION} file of their package (or add \verb{RdMacros: mathjaxr} if the \file{DESCRIPTION} file does not yet contain a \verb{RdMacros} entry),
\item add \verb{import(mathjaxr)} in the \file{NAMESPACE} file of their package.
}
One can then enable the use of MathJax by calling the \code{\\loadmathjax} macro (that is provided by the \pkg{mathjaxr} package) within the \verb{\\description{}} section of an Rd file (or within the \verb{@description} section when using \pkg{roxygen2}).
An inline equation can then be added with the \code{\\mjeqn{latex}{ascii}} macro, with the \LaTeX commands for the equation given between the first set of curly brackets (which will be rendered in the HTML and PDF help pages) and the plain-text version of the equation given between the second set of curly brackets (which will be shown in the plain text help). With the \code{\\mjdeqn{latex}{ascii}} macro, one can add \sQuote{displayed equations} (as in \LaTeX's \code{displaymath} environment).
Single argument versions of these macros, \code{\\mjseqn{latexascii}} and \code{\\mjsdeqn{latexascii}}, are also available. For the relatively rare case that one must specify different \LaTeX commands for the PDF and HTML pages, there are also triple argument versions of these macros, namely \code{\\mjteqn{pdflatex}{htmllatex}{ascii}} and \code{\\mjtdeqn{pdflatex}{htmllatex}{ascii}}.
}
\details{
The Javascript code for MathJax is contained in this package. If a user viewing a help page has \pkg{mathjaxr} installed, it will be retrieved from there, otherwise it will be retrieved from the CDN site \url{https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml-full.js}. To force use of the CDN site, the user can set the environment variable \env{MATHJAXR_USECDN} to any non-blank value (e.g., \code{Sys.setenv(MATHJAXR_USECDN=TRUE)}). The URL for a diferent CDN can be specified via the environment variable \env{MATHJAXR_CDN}.
}
\section{Notes/Issues}{
\itemize{
\item Care must be taken when using the less-than and greater-than symbols in equations as these might get interpreted by the browser as HTML tags. See \href{https://docs.mathjax.org/en/latest/input/tex/html.html}{here} for further details. Adding space around these symbols should solve this problem (e.g., instead of writing \code{\\mjseqn{i