mathjaxr/ 0000755 0001762 0000144 00000000000 14017161376 012076 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 00000012760 14017153215 013354 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 `Suggests` or `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),
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 if you use `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`.
Package authors who want to ensure that users can see the rendered equations in the HTML help pages also when offline should add `mathjaxr` to `Imports`. To avoid the note from `R CMD check` that `All declared Imports should be used`, one can add `import(mathjaxr)` to `NAMESPACE`.
## 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).
## 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 13660221455 012647 5 ustar ligges users mathjaxr/man/preview_rd.Rd 0000644 0001762 0000144 00000005220 14010340633 015271 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)
}
\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"}, 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.}
}
\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 \code{preview_rd()} is called 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{
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 13653305122 014127 5 ustar ligges users mathjaxr/man/macros/mathjax.Rd 0000644 0001762 0000144 00000005046 13666430442 016067 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}{\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}{\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}{\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 00000011437 14015151175 016347 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{Suggests} or \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)
}
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 if you use \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}.
Package authors who want to ensure that users can see the rendered equations in the HTML help pages also when offline should add \pkg{mathjaxr} to \verb{Imports}. To avoid the note from \sQuote{\verb{R CMD check}} that \sQuote{\verb{All declared Imports should be used}}, one can add \verb{import(mathjaxr)} to \file{NAMESPACE}.
}
\section{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 \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