support "any" graphic device
- shift temp-file generation from time-based to 'tempfile()', reduces
the (slim) possibility of same-name images being created (e.g.,
parallel production, fast rendering)
- add some graphic helper funcs for generalizing things across all
'spec_*' plotting functions: is_svg, dev_chr, and graphics_dev
- add 'make_inline_plot' to centralize formation of the
'kableExtraInlinePlots' object; prepend 'file:///' to paths when not
is_latex, fixes display of some raster graphics; added "list" as a
secondary class
- add 'listify_args' to enable any single-plot function to be able to
vectorize any of its arguments (so that different plots on different
rows can have different arguments)
- update 'spec_plot' to use these mechanisms
diff --git a/man/graphics_helpers.Rd b/man/graphics_helpers.Rd
new file mode 100644
index 0000000..02210af
--- /dev/null
+++ b/man/graphics_helpers.Rd
@@ -0,0 +1,80 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/graphics_helpers.R
+\name{graphics_helpers}
+\alias{graphics_helpers}
+\alias{graphics_dev}
+\alias{is_svg}
+\alias{dev_chr}
+\title{Helper functions to use various graphics devices}
+\usage{
+graphics_dev(filename, width, height, res, ..., dev)
+
+is_svg(dev)
+
+dev_chr(dev)
+}
+\arguments{
+\item{filename}{Passed through to the graphics device.}
+
+\item{width, height}{Plot dimensions in pixels.}
+
+\item{res}{The resolution of the plot; default is 300.}
+
+\item{...}{extra parameters passing to the graphics-device function.}
+
+\item{dev}{Character (e.g., "svg", "pdf") or function (e.g.,
+\code{grDevices::svg}, \code{grDevices::pdf}).}
+}
+\value{
+'graphics_dev': nothing, a plot device is opened
+
+'is_svg': logical
+
+\code{dev_chr}: character
+}
+\description{
+These helper functions generalize the use of strings (e.g.,
+\code{"svg"}, \code{"pdf"}) or graphic device functions (e.g.,
+\code{grDevices::svg}, \code{grDevices::pdf}) for in-table plots.
+}
+\details{
+\itemize{
+\item \code{graphics_dev} generalizes the use of 'res' and plot dimensions
+across graphic devices. Raster-based devices (e.g., 'png',
+'jpeg', 'tiff', 'bmp') tend to use 'res' and the width/height
+units default to pixels. All other devices (e.g., 'pdf', 'svg')
+tend to use inches as the default units for width/height, and
+error when 'res' is provided.
+
+The current heuristic is the look for the 'res' argument in the
+function's formals; if that is present, then it is assumed that
+the default units are in pixels, so 'width', 'height', and 'res'
+are passed through unmodified. If 'res' is not present, then
+'width' and 'height' are converted from pixels to inches, and
+'res' is not passed to the function
+
+Another purpose of this function is to generalize the different
+graphic functions' use of 'file=' versus 'filename='.
+}
+
+\itemize{
+\item \code{is_svg} determines if the plot device is svg-like, typically one
+of \verb{"svg", }grDevices::svg\verb{, or }svglite::svglite`
+}
+
+\itemize{
+\item \code{dev_chr} determines the filename extension for the applicable
+plot function; when \code{dev} is a string, then it is returned
+unchanged; when \code{dev} is a function, the formals of the function
+are checked for clues (i.e., default value of a \verb{file=} argument)
+}
+}
+\section{Functions}{
+\itemize{
+\item \code{graphics_dev}: Generalize 'res' and 'filename across dev functions
+
+\item \code{is_svg}: Determine if plot device is svg-like
+
+\item \code{dev_chr}: Determine filename extension
+}}
+
diff --git a/man/listify_args.Rd b/man/listify_args.Rd
new file mode 100644
index 0000000..20f55cf
--- /dev/null
+++ b/man/listify_args.Rd
@@ -0,0 +1,52 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/graphics_helpers.R
+\name{listify_args}
+\alias{listify_args}
+\title{Convert arguments for a single call into Map-able args}
+\usage{
+listify_args(
+ ...,
+ lengths = NA,
+ passthru = c("x", "y"),
+ notlen1vec = c("lim", "xlim", "ylim"),
+ notlen1lst = c("minmax", "min", "max"),
+ ignore = c("same_lim")
+)
+}
+\arguments{
+\item{...}{Arbitrary arguments to be possibly converted into lists
+of arguments.}
+
+\item{lengths}{Allowable lengths of the arguments, typically 1 and
+the length of the main variable (e.g., "x"). If 'NA' (default),
+it is not enforced.}
+
+\item{passthru}{Character vector of variables to pass through with
+no conversion to lists of values. Extra names (not provided in
+\code{...}) are ignored.}
+
+\item{notlen1vec}{Character vector of variables that are known to
+be length over 1 for a single plot call, so it will always be
+list-ified and extra care to ensure it is grouped correctly.
+Extra names (not provided in \code{...}) are ignored.}
+
+\item{notlen1lst}{Character vector of variables that are lists, so
+the inner list length is not checked/enforced. (For example, if a
+single plot call takes an argument \code{list(a=1,b=2,d=3)} and the
+multi-data call creates three plots, then a naive match might
+think that the first plot would get \code{list(a=1)}, second plot gets
+\code{list(b=2)}, etc. Adding that list-argument to this 'notlen1lst'
+will ensure that the full list is passed correctly.) Extra names
+(not provided in \code{...}) are ignored.}
+
+\item{ignore}{Character vector of variables to ignore, never
+returned. (Generally one can control this by not adding the
+variable in the first place, but having this here allows some
+sanity checks and/or programmatic usage.)}
+}
+\value{
+list, generally a list of embedded lists
+}
+\description{
+Convert arguments for a single call into Map-able args
+}
diff --git a/man/make_inline_plot.Rd b/man/make_inline_plot.Rd
new file mode 100644
index 0000000..5312a7b
--- /dev/null
+++ b/man/make_inline_plot.Rd
@@ -0,0 +1,30 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/graphics_helpers.R
+\name{make_inline_plot}
+\alias{make_inline_plot}
+\title{Combine file (or svg text) and parameters into a 'kableExtraInlinePlots' object}
+\usage{
+make_inline_plot(filename, file_ext, dev, width, height, res, del = TRUE)
+}
+\arguments{
+\item{filename}{Passed through to the graphics device.}
+
+\item{file_ext}{Character, something like "png".}
+
+\item{dev}{Character (e.g., "svg", "pdf") or function (e.g.,}
+
+\item{width, height}{Plot dimensions in pixels.}
+
+\item{res}{The resolution of the plot; default is 300.}
+
+\item{del}{If the file is svg-like, then the default action is to
+read the file into an embedded SVG object; once done, the file is
+no longer used. The default action is to delete this file early,
+set this to 'FALSE' to keep the file.}
+}
+\value{
+list object, with class 'kableExtraInlinePlots'
+}
+\description{
+Combine file (or svg text) and parameters into a 'kableExtraInlinePlots' object
+}
diff --git a/man/spec_plot.Rd b/man/spec_plot.Rd
index 1917de1..829bae8 100644
--- a/man/spec_plot.Rd
+++ b/man/spec_plot.Rd
@@ -29,7 +29,7 @@
max = minmax,
dir = if (is_latex()) rmd_files_dir() else tempdir(),
file = NULL,
- file_type = if (is_latex()) "png" else "svg",
+ file_type = if (is_latex()) "pdf" else "svg",
...
)
}
@@ -85,8 +85,9 @@
\item{file}{File name. If not provided, a random name will be used}
-\item{file_type}{Graphic device. Support \code{png} or \code{svg}. SVG is recommended
-for HTML output.}
+\item{file_type}{Graphic device. Can be character (e.g., \code{"pdf"})
+or a graphics device function (\code{grDevices::pdf}). This defaults
+to \code{"pdf"} if the rendering is in LaTeX and \code{"svg"} otherwise.}
\item{...}{extra parameters passing to \code{plot}}
}