% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/macros.R
\name{define_macro}
\alias{define_macro}
\alias{clear_macros}
\alias{list_macros}
\title{Define a user-level LaTeX macro}
\usage{
define_macro(name, definition)

clear_macros(name = NULL)

list_macros()
}
\arguments{
\item{name}{Macro name \strong{without} the leading backslash. For
\code{clear_macros}, the macro name to drop, or \code{NULL}
(default) to clear all.}

\item{definition}{LaTeX source the macro expands to.}
}
\value{
\itemize{
\item \code{define_macro}: Invisibly returns \code{NULL}.
\item \code{clear_macros}: Invisibly returns \code{NULL}.
\item \code{list_macros}: A named character vector mapping
macro names to their expansions. Empty if no macros are defined.
}
}
\description{
Registers a zero-argument shorthand that is expanded by text
substitution before the expression reaches the MicroTeX parser.
Useful for domain-specific notation (e.g. \code{\\RR} for
\code{\\mathbb\{R\}}) you reuse across many plots.
}
\section{Choosing between this and \code{\\newcommand}}{

MicroTeX also accepts \code{\\newcommand} and plain-TeX \code{\\def}
written inside the expression itself, and those are the more capable
form: they take up to nine arguments, which \code{define_macro()} does
not --- it substitutes text and nothing else.

\preformatted{
  # parameterised, but local to this one expression
  grid.latex(r"(\\def\\norm#1{\\left\\lVert #1 \\right\\rVert}
                \\norm{\\vec{v}})")
}

What they cannot do is persist: the user-macro table is cleared at the
start of every parse, so a \code{\\newcommand} written in one call is
gone by the next. That is the one thing \code{define_macro()} is for.
Use \code{\\newcommand} / \code{\\def} for an abbreviation local to a
single label, and \code{define_macro()} for notation you want available
to every label in a script.
}

\examples{
\donttest{
  define_macro("RR", "\\\\mathbb{R}")
  define_macro("eps", "\\\\varepsilon")
  grid::grid.newpage()
  grid.latex("\\\\forall \\\\eps > 0, \\\\eps \\\\in \\\\RR")
  clear_macros()
}
}
\seealso{
\code{\link{latex_grob}}, \code{\link{latex_options}}
}
