--- title: "Introduction to gridmicrotex" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Introduction to gridmicrotex} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r setup, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>", dpi = 300, dev = "png" ) ``` ## What is gridmicrotex? **gridmicrotex** renders LaTeX math as native R `grid` graphics objects. It embeds the [MicroTeX](https://github.com/NanoMichael/MicroTeX) C++ engine: MicroTeX parses the LaTeX, builds the TeX box model and computes exact glyph coordinates, and the package maps that layout onto grid primitives (`pathGrob`, `segmentsGrob`, `rectGrob`, `textGrob`), returning a `gTree`. No LaTeX installation is required, and the result is resolution independent on every R device. - Full math: fractions, roots, integrals, matrices, Greek, accents, delimiters, and colour via `\textcolor{}` - Two bundled math fonts, plus any OpenType math font through `load_math_font()` - CJK, RTL and multilingual text inside `\text{}` - ggplot2 integration --- `geom_latex()` and `element_latex()`, see `vignette("ggplot2-integration")` - Markdown with inline math --- see `vignette("markdown")` ## Quick start `latex_grob()` returns a grob; `grid.latex()` builds and draws one. ```{r basic, fig.height=1, fig.width=2.4, out.width="45%"} library(gridmicrotex) library(grid) grid.newpage() grid.latex(r"($\frac{\textcolor{red}{-b} \pm \sqrt{b^2 - 4ac}}{2a}$)") ``` **Write LaTeX in a raw string.** `r"(...)"` passes backslashes through untouched, so what you paste is what renders. Every example here uses one. In an ordinary `"..."` string each `\` has to be doubled --- and LaTeX's own row separator `\\` becomes a bewildering `\\\\`. ### Mixing text and math The default `input_mode = "mixed"` reads the string as prose and typesets only what sits inside `$…$` or `\(…\)` as math, which is why `Famous:` below needs no markup. It saves typing, but the split is heuristic. `input_mode = "math"` treats the whole string as math, so prose must be wrapped in `\text{}`; that suits heavy math and pasted LaTeX. These two render identically: ```{r modes, fig.height=1.2, fig.width=3.2, out.width="45%"} grid.newpage() grid.latex(r"(Famous: $E = mc^2$)", x = 0.05, y = 0.7, hjust = 0, ) grid.latex(r"(\text{Famous: } E = mc^2)", input_mode = "math", x = 0.05, y = 0.3, hjust = 0, ) ``` Set the mode for a whole session with `latex_options(input_mode = )`. ## What it can render Two figures before the details, because the range is easier to see than to describe. A coloured `array` with `\multicolumn`, `\rowcolor`, `\cellcolor`, a custom column type and a nested matrix: ```{r showcase-table, fig.height = 3, fig.width = 8, out.width="70%"} grid.newpage() grid.latex(r"( \newcolumntype{s}{>{\color{#1234B6}}c} \begin{array}{|c|c|c|s|} \hline \rowcolor{Tan}\multicolumn{4}{|c|}{\textcolor{white}{\bold{\text{Table Head}}}}\\ \hline \text{Matrix}&\multicolumn{2}{|c|}{\text{Multicolumns}}&\text{Font size commands}\\ \hline \begin{pmatrix} \alpha_{11}&\cdots&\alpha_{1n}\\ \hdotsfor{3}\\ \alpha_{n1}&\cdots&\alpha_{nn} \end{pmatrix} &\large \text{Left}&\cellcolor{#00bde5}\small \textcolor{white}{\text{\bold{Right}}} &\small \text{small Small}\\ \hline \multicolumn{4}{|c|}{\text{Table Foot}}\\ \hline \end{array} )", ) ``` And a page of assorted notation --- `split` alignment, fraktur, stacked delimiters, `\sideset`, extensible arrows, `\rotatebox`, `\reflectbox` and a boxed result: ```{r showcase-equation, fig.height = 9, fig.width = 9, out.width="70%"} grid.newpage() grid.latex(r"( \definecolor{gris}{gray}{0.9} \definecolor{noir}{rgb}{0,0,0} \fatalIfCmdConflict{false} \newcommand{\pa}{\left|} \begin{array}{c} \LaTeX\\ \begin{split} |I_2| &= \pa\int_0^T\psi(t)\left\{ u(a,t)-\int_{\gamma(t)}^a \frac{d\theta}{k} (\theta,t) \int_a^\theta c(\xi) u_t (\xi,t)\,d\xi\right\}dt\right|\\ &\le C_6 \Bigg|\pa f \int_\Omega \pa\widetilde{S}^{-1,0}_{a,-} W_2(\Omega, \Gamma_1)\right|\ \right|\left| |u|\overset{\circ}{\to} W_2^{\widetilde{A}}(\Omega\Gamma_r,T)\right|\Bigg|\\ &\\ &\begin{pmatrix} \alpha&\beta&\gamma&\delta\\ \aleph&\beth&\gimel&\daleth\\ \mathfrak{A}&\mathfrak{B}&\mathfrak{C}&\mathfrak{D}\\ \boldsymbol{\mathfrak{a}}&\boldsymbol{\mathfrak{b}}&\boldsymbol{\mathfrak{c}}&\boldsymbol{\mathfrak{d}} \end{pmatrix} \quad{(a+b)}^{\frac{n}{2}}=\sqrt{\sum_{k=0}^n\tbinom{n}{k}a^kb^{n-k}}\quad \Biggl(\biggl(\Bigl(\bigl(()\bigr)\Bigr)\biggr)\Biggr)\\ &\forall\varepsilon\in\mathbb{R}_+^*\ \exists\eta>0\ |x-x_0|\leq\eta\Longrightarrow|f(x)-f(x_0)|\leq\varepsilon\\ &\det \begin{bmatrix} a_{11}&a_{12}&\cdots&a_{1n}\\ a_{21}&\ddots&&\vdots\\ \vdots&&\ddots&\vdots\\ a_{n1}&\cdots&\cdots&a_{nn} \end{bmatrix} \overset{\mathrm{def}}{=}\sum_{\sigma\in\mathfrak{S}_n}\varepsilon(\sigma)\prod_{k=1}^n a_{k\sigma(k)}\\ &\Delta f(x,y)=\frac{\partial^2f}{\partial x^2}+\frac{\partial^2f}{\partial y^2}\qquad\qquad \fcolorbox{noir}{gris} {n!\underset{n\rightarrow+\infty}{\sim} {\left(\frac{n}{e}\right)}^n\sqrt{2\pi n}}\\ &\sideset{_\alpha^\beta}{_\gamma^\delta}{ \begin{pmatrix} a&b\\ c&d \end{pmatrix}} \xrightarrow[T]{n\pm i-j}\sideset{^t}{}A\xleftarrow{\overrightarrow{u}\wedge\overrightarrow{v}} \underleftrightarrow{\iint_{\mathds{R}^2}e^{-\left(x^2+y^2\right)}\,\mathrm{d}x\mathrm{d}y} \end{split}\\ \rotatebox{30}{\sum_{n=1}^{+\infty}}\quad\mbox{Mirror rorriM}\reflectbox{\mbox{Mirror rorriM}} \end{array} )", render_mode = "path") ``` Both are ordinary LaTeX, pasted unchanged. The rest of this vignette is about placing such things, choosing fonts, and knowing where the supported set ends. ### Aligning to the math baseline `hjust` and `vjust` also take names. The useful one is `vjust = "baseline"`, which puts the formula's *math baseline* --- not the bounding-box centre --- on the anchor, so a formula sits beside running text the way it would in a typeset document. ```{r baseline-align, fig.height=1.1, fig.width=6, out.width="70%"} grid.newpage() y <- 0.5 grid.segments(unit(0, "npc"), unit(y, "npc"), unit(1, "npc"), unit(y, "npc"), gp = gpar(col = "grey80")) grid.text("if ", x = 0.10, y = y, just = c(0, 0.5), gp = gpar(fontsize = 20)) grid.latex(r"($x \geq \sqrt{2\pi}$)", x = 0.22, y = y, hjust = "left", vjust = "baseline", gp = gpar(fontsize = 20)) grid.text(", then proceed.", x = 0.62, y = y, just = c(0, 0.5), gp = gpar(fontsize = 20)) ``` `hjust` accepts `"left"`/`"bbleft"`, `"center"`/`"centre"`/`"middle"`/ `"bbcentre"`, and `"right"`/`"bbright"`. `vjust` accepts `"bottom"`, `"center"`/`"centre"`/`"middle"`, `"top"`, and `"baseline"`. ### Named anchors with `\mark{}` `\mark{name}` records a named anchor inside the formula, and `grobMark()` resolves it to a pair of grid units ready to drive an arrow or a callout. Marks work at any nesting level --- even inside a superscript or a fraction --- and inherit the surrounding transform (font shrink, scaling, rotation), so the anchor lands on the rendered glyph. ```{r mark, fig.height=2.4, fig.width=5, out.width="70%"} g <- latex_grob(r"($a^2 + b\mark{term}^2 \mark{equals}= c^2$)", x = 0.5, y = 0.4) grid.newpage() grid.draw(g) # The "=" sign, pointed at from above. mk_eq <- grobMark(g, "equals") grid.segments(mk_eq$x, mk_eq$y + unit(15, "mm"), mk_eq$x, mk_eq$y + unit(3, "mm"), arrow = arrow(length = unit(2, "mm"), type = "closed"), gp = gpar(col = "red")) grid.text("equals", x = mk_eq$x, y = mk_eq$y + unit(18, "mm"), gp = gpar(col = "red")) # The b^2 term, from below -- the mark sits at the end of the term, # including the superscript's smaller scale. mk_bsq <- grobMark(g, "term") grid.segments(mk_bsq$x - unit(6, "mm"), mk_bsq$y - unit(15, "mm"), mk_bsq$x - unit(2, "mm"), mk_bsq$y - unit(3, "mm"), arrow = arrow(length = unit(2, "mm"), type = "closed"), gp = gpar(col = "blue")) grid.text("b² term", x = mk_bsq$x - unit(7, "mm"), y = mk_bsq$y - unit(18, "mm"), just = "right", gp = gpar(col = "blue")) ``` The returned units carry the grob's viewport position and `hjust`/`vjust`, so they go straight into any grid drawing function with no offset arithmetic. A mark is a single point, not a span: to centre a callout over a multi-glyph term, use a pair (`\mark{l}…\mark{r}`) and take the midpoint. ## Display and inline style TeX sets the same expression two ways. In *display* style a `\sum` is drawn at full size with its limits above and below; in *text* (inline) style it shrinks and the limits become scripts beside it. This is a choice about spacing and layout, not about size --- size is always `gp$fontsize`. By default the delimiters decide, exactly as in a LaTeX document: `$…$` gives text style and `$$…$$` gives display style. A label written without delimiters --- a plot title, an axis title, an `element_latex()` --- has nothing for the parser to go on, so it gets text style. `tex_style` overrides that for the whole expression, and takes all four of TeX's styles: ```{r style-options, fig.height=1.9, fig.width=6.5, out.width="100%"} sum_expr <- r"(\sum_{i=1}^{n} \frac{x_i}{n})" styles <- c("display", "text", "script", "scriptscript") labels <- c('"display" ($$...$$)', '"text" ($...$)', '"script"', '"scriptscript"') grid.newpage() for (i in seq_along(styles)) { pushViewport(viewport(x = (i - 0.5) / 4, width = 1 / 4)) grid.text(labels[i], y = 0.88, gp = gpar(cex = 0.75, fontface = "bold")) grid.latex(sum_expr, y = 0.42, input_mode = "math", tex_style = styles[i], gp = gpar(fontsize = 20)) grid.rect(gp = gpar(col = "grey85", fill = NA)) popViewport() } ``` Every panel is `gp = gpar(fontsize = 20)`. The display version is taller and narrower because the limits moved above and below the operator instead of sitting beside it --- worth knowing when you are budgeting space for a label, and `latex_dims()` reports the difference if you need the numbers. `"script"` and `"scriptscript"` are the sizes TeX uses for first- and second-level scripts; they are occasionally handy for a compact sub-label, and rarely needed otherwise. To change style for part of an expression rather than all of it, use the inline commands `\displaystyle`, `\textstyle`, `\scriptstyle` and `\scriptscriptstyle` instead. `latex_options(tex_style = )` sets a session default. ## Wrapping and justification `max_width`, in big points, wraps a label over as many lines as it needs. ```{r wrap, fig.height = 2, fig.width = 4, out.width = "65%"} prose <- paste(rep( r"(The quick brown fox jumps over the lazy dog, and $x^2$ too.)", 3), collapse = " ") grid.newpage() pushViewport(viewport(layout = grid.layout(2, 1))) pushViewport(viewport(layout.pos.row = 1)) grid.text("ragged (default)", x = 0.02, y = 0.98, hjust = 0, vjust = 1, gp = gpar(col = "grey40")) grid.latex(prose, x = 0.02, y = 0.78, hjust = 0, vjust = 1, max_width = 3.6 * 72, gp = gpar(fontsize = 11)) popViewport() pushViewport(viewport(layout.pos.row = 2)) grid.text("justified + optimal", x = 0.02, y = 0.98, hjust = 0, vjust = 1, gp = gpar(col = "grey40")) grid.latex(prose, x = 0.02, y = 0.78, hjust = 0, vjust = 1, max_width = 3.6 * 72, justify = TRUE, line_break = "optimal", gp = gpar(fontsize = 11)) popViewport(2) ``` Both refinements are off by default. `justify = TRUE` fills every line but the last; `line_break = "optimal"` chooses the breaks by total fit rather than one line at a time. Justifying a narrow column opens wide word gaps, since nothing may break inside a word --- mark the words that may with `\-`, as in `in\-ter\-na\-tion\-al`. ## Including a figure `\includegraphics` draws an image inside the formula. PNG, JPEG and SVG are supported, sized with `width`, `height` or `scale` in any LaTeX length; give one of width/height and the aspect ratio is kept, or both plus `keepaspectratio` to fit inside them. As in LaTeX the extension may be omitted (`{plots/fig}` finds `plots/fig.svg` or `plots/fig.png`), and `\graphicspath{{figs/}}` adds a directory to search. `angle` rotates the figure, like `\rotatebox`; `trim` and `clip` are recognised but not applied, and say so. ```{r img-basic, fig.height = 1.6, fig.width = 4, out.width = "60%"} fig <- tempfile(fileext = ".svg") svglite::svglite(fig, width = 2, height = 1.2) grid.newpage() grid.circle(r = 0.35, gp = gpar(fill = "steelblue", col = NA)) dev.off() grid.newpage() grid.latex(sprintf(r"(\text{before }\includegraphics[width=1in]{%s}\text{ after})", fig), input_mode = "math", gp = gpar(fontsize = 20)) ``` Inline, the image sits **on the baseline**, as in LaTeX --- `\raisebox` moves it. A paragraph holding only an image is a **block**, flush left unless `halign` or a `text-align` rule on `img` says otherwise. ```{r img-raise, fig.height = 1.5, fig.width = 4.5, out.width = "70%"} icon <- sprintf(r"(\includegraphics[width=14bp]{%s})", fig) grid.newpage() grid.latex(sprintf(r"(\text{baseline }%s\text{, raised }\raisebox{4bp}{%s})", icon, icon), input_mode = "math", gp = gpar(fontsize = 20)) ``` ### A caption `\caption` renders where it is written. A caption after `\includegraphics` therefore sits below the figure, and one written before a `tabular` sits above the table --- which is what makes raw `xtable` and `kable` output come out the right way round without any float logic. `\centering` is dropped, because a grob has no page to centre against. A one-column `array` does the job instead: it centres the figure and its caption on each other. ```{r img-caption, fig.height = 1.4, fig.width = 3, out.width = "45%"} logo <- system.file("img", "Rlogo.png", package = "png") grid.newpage() grid.latex(sprintf(r"(\begin{array}{c} \includegraphics[width=0.6in]{%s}\\ \caption{Figure 1: the R logo} \end{array})", logo), gp = gpar(fontsize = 11)) ``` Remove the `array` and the same two lines come out flush left. LaTeX numbers captions from a counter; here the number is yours to write. **Prefer SVG.** An SVG is drawn as real grid primitives, so it stays sharp at any output resolution — there is no dpi to choose. A PNG or JPEG is a fixed grid of pixels, so if you display one much larger than it was saved you get a blurry result; the package warns when the effective resolution falls below 150 dpi and tells you what pixel size would reach 300. The rule is `pixels = display_inches * output_dpi`. PDF and EPS are **not** supported. Save the figure as SVG instead: it needs no external tool and, unlike a rasterised PDF, its text stays text. ## Fonts Two layers are in play. **MicroTeX** chooses the math glyphs and their metrics; **grid** draws everything inside `\text{}` using `gp$fontfamily`, so prose follows R's ordinary font handling --- Latin, CJK, Cyrillic and anything else the device supports. Two math fonts ship with the package and load automatically: | Alias | Font | Style | Pairs with | |-------|------|-------|------------| | `"lete"` (default) | Lete Sans Math | Sans-serif | `fontfamily = "sans"` | | `"stix"` | STIX Two Math | Serif | `fontfamily = "serif"` | ```{r fonts-list} available_math_fonts() ``` Set one per call with `math_font`, or for the session with `latex_options(math_font = )`. Both rows below are the same formula --- only the math font and its paired text family differ: ```{r fonts, fig.height=1.5, fig.width=3.4, out.width="60%"} formula <- r"(Theorem: $\int_0^1 f(x)\,dx \geq 0$)" grid.newpage() pushViewport(viewport(layout = grid.layout(2, 1))) pushViewport(viewport(layout.pos.row = 1)) grid.latex(formula, gp = gpar(fontfamily = "sans")) upViewport() pushViewport(viewport(layout.pos.row = 2)) grid.latex(formula, math_font = "stix", gp = gpar(fontfamily = "serif")) upViewport(2) ``` `check_math_fonts()` gives a diagnostic report. Any font available to R works for the text half --- base families like `"sans"`, `"serif"` and `"mono"`, or anything registered through **systemfonts**: ```{r cjk, fig.height=1, fig.width=5, out.width="55%", dev = "ragg_png", dev.args = list(), purl = FALSE} grid.newpage() grid.latex(r"(如果 $x > 0$ 则 $y = x^2$)", gp = gpar(fontfamily = "sans")) ``` Right-to-left scripts work the same way, mixed with Latin included. Two things do not: wrapping a right-to-left paragraph across lines needs the optional [FriBidi](https://github.com/fribidi/fribidi) library, and a math atom between two right-to-left runs --- `\text{…}$x^2$\text{…}` --- falls back to left-to-right order. ### Naming a font for one run `gp$fontfamily` applies to the whole grob. For a *single run*, use `\gmfontfamily{family}{content}` --- a gridmicrotex extension, not standard LaTeX. `\textrm{…}` goes the other way, returning content to `gp$fontfamily` even inside a `\textsf{…}`, `\texttt{…}` or `\gmfontfamily{…}{…}` group, and without disturbing bold or italic: ```{r gmfontfamily, fig.height=0.8, fig.width=4.5, out.width="85%", dev = "ragg_png", dev.args = list()} grid.newpage() grid.latex( r"(\textsf{sans \textrm{body} sans} \quad \gmfontfamily{mono}{mono})", gp = gpar(fontfamily = "serif") ) ``` `family` is anything `gp$fontfamily` accepts: a generic (`"sans"`, `"serif"`, `"mono"`) or a specific name such as `"Georgia"`, which `\textsf{…}` / `\texttt{…}` cannot express. Unresolvable names fall back silently. The content is typeset as text, so this styles prose, not math --- math glyphs follow `math_font`. It composes with emphasis in either nesting order, but a nested `\gmfontfamily` *replaces* the family it sits inside. The name is deliberately not `\fontfamily`: LaTeX's takes one argument, does nothing until `\selectfont`, and wants an NFSS code (`ptm`) rather than a font name. Since gridmicrotex accepts pasted LaTeX, claiming that name would silently misparse real input. This is also what markdown's `font-family` CSS compiles to --- see `vignette("markdown")`. ### Loading a custom math font `load_math_font()` adds any OpenType math font. The OpenType MATH table is parsed directly in C++, so no companion metrics file and no external toolchain are needed: ```r load_math_font("path/to/MyFont.otf") ``` This is only for **math** fonts. Text fonts need no loading at all --- set `gp$fontfamily`, or name one for a run with `\gmfontfamily{}{}`. ## Devices and render modes - **`"typeface"`** (default) draws glyphs as native text, so PDF and SVG output stays selectable and searchable: a line of prose is emitted as a single element, so a viewer finds a phrase and not merely a word. Text given a `max_width` is the exception --- it is emitted one word per element, because the spaces are where the lines break. Fonts are read straight from their OTF files, with no system-wide install --- but this needs a device with the R \eqn{\geq} 4.3 glyph engine (`ragg`, `svglite`, `cairo_pdf`). On others, such as the base `pdf()` device, it falls back to path mode with a warning. - **`"path"`** draws each glyph as a filled vector path. Works on every device; the text is not selectable, and files are larger. ```r grid.latex(r"($E = mc^2$)") # typeface grid.latex(r"($E = mc^2$)", gp = gpar(fontsize = 24), render_mode = "path") # path ``` Prefer `ragg::agg_png()`, `svglite::svglite()` or `grDevices::cairo_pdf()`. The default devices on Windows and macOS may not find the bundled math fonts and will warn `font family not found in Windows font database`; the README covers the setup, and compares the package with `tikzDevice`, `xdvir`, `latex2exp` and `plotmath`. > **Do not use `showtext::showtext_auto()` with typeface mode.** showtext > intercepts all text rendering and converts it to paths, silently > defeating typeface mode even on `svglite` and `ragg`. Call > `showtext::showtext_auto(FALSE)` before drawing formulas. ## Utilities ### Measuring `latex_dims()` returns the bounding box of an expression, for layout arithmetic and for checking that a label fits: ```{r dims} latex_dims(r"(\frac{a}{b})", gp = gpar(fontsize = 20)) ``` ### Session defaults `latex_options()` sets `math_font`, `render_mode` and `input_mode` for calls that don't supply them; explicit arguments always win. Size stays at the grob level, via `gp$fontsize` / `gp$lineheight`. ```{r options, eval=FALSE} latex_options(math_font = "stix", render_mode = "typeface") latex_options() # query reset_latex_options() # back to built-in defaults ``` ### User-defined macros `define_macro()` registers zero-argument shorthands, expanded by text substitution before the expression reaches MicroTeX: ```{r macros, fig.height=0.7, fig.width=3, out.width="50%"} define_macro("RR", r"(\mathbb{R})") define_macro("eps", r"(\varepsilon)") grid.newpage() grid.latex(r"(\forall \eps > 0, \eps \in \RR)") clear_macros() ``` Names must be ASCII letters, and expansion iterates to a fixed point so macros can reference each other. `list_macros()` shows what is registered; `clear_macros()` drops everything. For parameterised macros (0--9 arguments) MicroTeX also accepts plain-TeX `\def`. These live only for the expression they appear in, so use them for an abbreviation local to one label and `define_macro()` for one that should persist: ```{r def-inline, fig.height=0.7, fig.width=4, out.width="60%"} grid.newpage() grid.latex( r"(\def\norm#1{\left\lVert #1 \right\rVert} \norm{\vec{v}} = \sqrt{\langle \vec{v}, \vec{v} \rangle})" ) ``` ### Caching and introspection Parsed layouts are memoised by `(tex, fontsize, math_font, render_mode, …)`, so a repeated axis label is laid out once: ```{r cache, eval=FALSE} latex_cache_info() # size / max_size / hits / misses latex_cache_limit(1024) # LRU capacity; 0 disables caching latex_cache_clear() # wipe (e.g. after re-loading fonts) ``` `latex_tree()` returns the raw draw records plus bbox metadata, and `debug = TRUE` overlays the bounding box, baseline and record origins --- both useful when checking alignment: ```{r debug, fig.height=1, fig.width=3, out.width="60%"} grid.newpage() grid.latex(r"($x^{2} + y_{i}$)", debug = TRUE) ``` ## LaTeX reference MicroTeX is a **math formula renderer**, not a document typesetter. It covers the vast majority of notation used in plots and figures, but does not replace a LaTeX installation. This section is the boundary. ### Lists `itemize` and `enumerate` lay their items out as a left-aligned column, one per row --- `itemize` prefixes a bullet, `enumerate` numbers them: ```{r lists, fig.height=1.4, fig.width=3, out.width="45%"} grid.newpage() grid.latex(r"(\begin{enumerate} \item e^{i\pi} + 1 = 0 \item \begin{itemize} \item \alpha \item \beta \end{itemize} \end{enumerate})", gp = gpar(fontsize = 20)) ``` An optional `[…]` argument customises the marker. For `itemize` it is the literal marker (`\begin{itemize}[\star]`); for `enumerate` it is a counter template containing one of `\arabic*`, `\alph*`, `\Alph*`, `\roman*` or `\Roman*` (e.g. `\begin{enumerate}[\Roman*.]`). Lists nest, and an item may contain any math, including a `\begin{array}` table. Because MicroTeX is a math engine, each item is a **math-mode, single-line** expression: no paragraph flow, no line wrapping, and prose inside an item needs `\text{}` (`\item \text{First point}`). The `description` environment is not supported. ### Pasting LaTeX from other sources Input generated by other tools --- ready-to-compile `tabular` snippets, fragments copied out of a `.tex` file --- usually arrives wrapped in document-level constructs MicroTeX does not implement. Rather than refusing it, gridmicrotex rewrites or removes a small set of well-known wrappers before parsing, so `knitr::kable(format = "latex")` and `xtable::print.xtable()` output can be pasted in unedited: ```{r pasted, fig.height = 1.1, fig.width = 3.2, out.width = "55%"} snippet <- r"( % latex table generated by kable() \begin{table}[ht] \centering \caption{Model coefficients} \begin{tabular}{lrr} \toprule Term & Estimate & \emph{p} \\ \midrule Intercept & 2.14 & 0.003 \\ Slope & 0.42 & 0.001 \\ \bottomrule \end{tabular} \end{table} )" grid.newpage() grid.latex(snippet, input_mode = "mixed", gp = gpar(fontsize = 11)) ``` Six things were handled without any editing: the `%` comment and the `table` float were dropped, `\centering` removed, `\caption` set as a line above the table, `\toprule`/`\bottomrule` became thick rules, `\midrule` a plain one, and `\emph` became italic. Note that the cell text is set in math italics. A `tabular` is a math environment, so its contents are math whichever `input_mode` you choose --- the two modes give an identical layout for the snippet above. What `"mixed"` buys you here is the prose *outside* the environment, such as the caption. For upright cell text, wrap the cells in `\text{}`. **Removed silently (no visual effect):** | Construct | Why | |---|---| | `%`-to-end-of-line comments (`\%` is preserved) | comments are non-visual in LaTeX too | | `\documentclass[…]{…}`, `\usepackage[…]{…}` | preamble metadata | | `\begin{document}` / `\end{document}` | document boundary, structural only | | `\maketitle`, `\title{…}`, `\author{…}` | title-page metadata, no body output | | `\label{…}` | cross-reference target, never rendered in LaTeX either | | `\begin{table}[…]` / `\end{table}`, `\begin{figure}[…]` / `\end{figure}` (and starred variants) | float wrappers; the contents stay | | `\centering`, `\raggedright`, `\raggedleft`, `\flushleft`, `\flushright` | alignment scope declarations | | `\noindent`, `\relax` | content-free declarations | **Rewritten to a MicroTeX equivalent:** | Construct | Becomes | |---|---| | `\emph{X}` | `\textit{X}` | | `\textnormal{X}` | `\text{X}` | | `\par`, `\newline` | `\\` (line break) | | `\toprule`, `\bottomrule` | `\thickhline` (rendered ~2× thickness) | | `\midrule` | `\hline` | | `\cmidrule[trim]?(parenarg)?{a-b}` | `\cline{a-b}` --- partial-column rule | | `\caption[short]{X}` | `\text{X}` plus a line break, at its source position --- so a caption written above the table stays above it | | `\smallskip`, `\medskip`, `\bigskip` | `\vspace{0.25em}` / `\vspace{0.5em}` / `\vspace{1em}` --- em-relative so they scale with `gp$fontsize` | | `\hfill`, `\vfill` | `\quad` / `\vspace{1em}` --- static proxies for rubber lengths | | `\url{X}` | coloured monospace text --- a grob cannot be a hyperlink, so only the appearance survives | | `\href{U}{X}` | `X`, coloured. Matches `hyperref` with `colorlinks=true`; markdown links use HTML's blue-and-underlined convention instead | Three of those are approximations. `\caption` renders where it appears in the source, not where LaTeX's float machinery would move it, so caption-above or caption-below follows whatever your tool emits. The skips are em-relative rather than LaTeX's absolute 3/6/12 pt, so they stay visible at any `gp$fontsize`; use `\vspace{Xpt}` for an exact amount. And `\hfill` / `\vfill` are *rubber* lengths with nothing to fill in a fixed-size grob, so they become a static 1 em gap --- right position, no elasticity. **Not honored** --- rendered as literal text, which is intentional: it makes unsupported markup easy to spot. - Declarative font scopes: `\bfseries`, `\itshape`, `\ttfamily`, `\sffamily`, `\rmfamily`. These affect text within their group in LaTeX, which needs scope tracking we do not implement. Use the argument-bearing forms instead --- `\textbf{…}`, `\textit{…}`, `\texttt{…}`, `\textsf{…}`, `\textrm{…}` --- all of which nest. To choose the text font itself, set `gp$fontfamily` or use `\gmfontfamily{…}{…}`. - References: `\ref{…}`, `\cite{…}` --- there is nothing to resolve against. - Footnotes: `\footnote{…}` --- the positioning machinery is page-bound. - Small caps: `\textsc{…}` --- MicroTeX has no small-caps glyphs. ### What is not supported These need a real document compiler and are outside a formula renderer's scope: document structure (`\section`, page layout, `\tableofcontents`); automatic hyphenation (`\-` marks a break point yourself, and `max_width` / `justify` do handle line breaking); TikZ/PGF; cross-references and bibliographies; theorem environments; the `description` list environment (`itemize` and `enumerate` *are* supported); and `\tag` / equation numbering. `\usepackage{…}` is accepted but loads nothing --- every supported command is built into MicroTeX. For axis labels, annotations, legends and in-plot formulas, the supported set is more than sufficient.