utftex(1)

✨ utftex(1) ✨ — the General Commands Manual, but make it fashion 💅

okay bestie, gather round, because utftex is genuinely one of the most underrated little tools in the whole unix ecosystem and i need you to be obsessed with it the way i am 🫶

---

🌸 NAME 🌸

utftex — An UTF-8 unicode equation renderer. literally what it says on the tin, no notes 💖

---

🦋 SYNOPSIS 🦋

utftex [options] [equation] ...

---

👑 DESCRIPTION 👑

so here's the whole vibe: utftex is here to use all the gorgeous possibilities unicode hands us so you can display math in simple UTF-8 encoded text. it renders mathematical equations in mono-space unicode characters, i.e. unicode-art. its whole purpose in life is to insert equations into source code, e-mails, and man-pages. and the best part?? it generally works without introducing additional dependencies, because most text editors and e-mail programs already support UTF-8 encoding out of the box. no cap. ✨

unicode provides many code-points which are intended for mathematical expressions. it even supplies some characters which are intended to "draw" math — like the top (⌠) and bottom (⌡) of an integral symbol. this way you can draw an integral symbol such as this:

⌠
⎮
⌡

utftex uses an (ASCII or UTF-8 encoded) input with a syntax similar to LaTeX and outputs an UTF-8 encoded text. iconic behaviour, truly. 💜

---

💅 OPTIONS 💅

All arguments are optional. If no arguments are passed utftex will read one equation from stdin. (yes bestie, it'll just sit there and wait for you. main character energy.)

• [equation] — Each [equation] argument is parsed as one latex equation (i.e. more than one equation may be passed). pass as many as your heart desires. 🌈
• --line-width, -l — Define the output line width. If it is 0 the line width is unlimited (default). This causes utftex to insert line breaks at suitable places to divide the expression over multiple lines. It is not guaranteed that suitable locations are found to insert line breaks and thus the actual line length may exceed the specified one. (it's doing its best, ok 😭)
• --symbol-list, -s — List all symbols supported by this version of utftex. Supported in this case means that an input command exists to generate the symbol as output, e.g. \alpha as input generates α as output. it's giving catalogue 🎀
• --test-texsymbols, -T — Same as above (list all symbols) in a more machine readable format. for the robots 🤖
• --version, -v — Print utftex and libtexprintf versions. cute little receipts 💖
• --show-input, -i — Print input before the rendered results. so you can see where it all came from ✨
• --wchar-width, -w — Specify the size of wide characters. Valid sizes are 1 and 2. Default is 2.
• --fchar-width, -f — Specify the size of full width characters. Valid sizes are 1 and 2. Default is 2.
• --default-font, -F — Specify the default font style to use. See the Fonts below. The font names correspond to the font commands minus the slash and the argument. e.g. one could pass -F mathnormal. Without this option the default font is set to "text" as not all fonts support the other font styles. 🦋
• --test-fonts, -t — Print table with chacters in various styles. 👑
• --test-stexprintf, -S — (no description in the original, bestie. it's mysterious. it's lowkey giving enigma 💀)
• --box-tree, -B — Print box structure (for debugging purposes). peek behind the curtain 🎀
• --ascii, -A — Try to stick to ASCII characters. This affects all "drawing" characters used for integral signs, brackets, fractions, and tables. It does not affect symbols like lpha (The user can avoid those, and there is no ASCII equivalent for lpha). 🌸
• --combine-errors, -E — Combines error messages in a semicolon delimited string. one message, all the tea ☕
• --mapsupersub, -m — Turns on or off sub/super script mapping (mapping of sub/super scripts to corresponding unicode code points for sub/super script symbols).
• --avoidcombining, -a — Per default utftex tries to use combining diacritical marks for accents whenever possible. This toggle swhich will change this in trying to avoid combining characters unless no alternative is available.
• --end-options, -e — Ends the option parser (allows to pass equations starting with a minus). for when your equation is being a little rebel 🔥

---

🌟 SYNTAX 🌟

🎀 Fonts 🎀

Unicode defines various font styles which may be accessed with utftex. For this the following commands are available:

\mathsfbfit{...}     Mathematical sans-serif bold italic fonts
\mathsfbf{...}       Mathematical sans-serif bold fonts
\mathfrak{...}       Fraktur caligraphic script
\mathbfit{...}       Mathematical serif bold italic fonts
\mathsfit{...}       Mathematical sans-serif italic fonts
\mathcal{...}        Mathematical caligraphic fonts
\mathscr{...}        Euler script fonts
\mathbf{...}         Mathematical serif bold fonts
\mathbb{...}         Mathematical black-board bold fonts
\mathsf{...}         Mathematical sans-serif fonts
\mathtt{...}         Mathematical typewriter fonts
\mathnormal{...}     Normal Mathematical fonts
\text{...}           Roman fonts (plain font style)
\it                  Switch current block to italic fonts
\bf                  Switch current block to bold fonts
\rm                  Switch current block to roman fonts

✨ commands to insert symbols, special characters, and operators ✨

There is a large set of symbols that may be inserted with the usual (or sometimes less usual) LaTeX commands. You can list the available symbols and corresponding commands by running utftex with the --symbol-list option. ok so let's go through them, bestie, because there are A LOT and they all ate 💅

• \frac{a}{b}, a\over b — A fraction of a and b.
• a^{b} — super-script. One can also omit the braces. In this case the first character following ^ will be in super-scripted. tiny and up high 🦋
• a_{b} — sub-script. Works just like super-script only now it is a sub-script. tiny and down low 🧚
• \sqrt[n]{a} — A n-th root of a, the argument [n] is optional. Without it it produces the square root of a. Note that these commands draw a variable size radix. The unicode radix signs (one character sized) are available as \utfsqrt \utfsqrt[3] and \utfsqrt[4].
• \sum — Expands to a large sigma symbol. The unicode sum symbol can be generated using \utfsum.
• \prod — Expands to the product symbol. The unicode product symbol can be generated using \utfprod.
• \int[S] — Expands to the integral symbol. The optional argument [S] makes the symbol scale with the height of the integrand. The unicode integral symbol can be generated using \utfint.
• \iint[S] — Expands to a double integral symbol. The optional argument [S] makes the symbol scale with the height of the integrand. The unicode double integral symbol can be generated using \utfiint.
• \iiint[S] — Expands to a triple integral symbol. The optional argument [S] makes the symbol scale with the height of the integrand. The unicode triple integral symbol can be generated using \utfiint.
• \iiiint[S] — Expands to a quadruple integral symbol. The optional argument [S] makes the symbol scale with the height of the integrand. The unicode quadruple integral symbol can be generated using \utfiint.
• \idotsint[S] — Expands to two integral symbols with dots in between. The optional argument [S] makes the symbol scale with the height of the integrand.
• \oint[S] — A contour integral. The optional argument [S] makes the symbol scale with the height of the integrand.
• \oiint[S] — A double contour integral. The optional argument [S] makes the symbol scale with the height of the integrand.
• \oiiint[S] — A tripple contour integral. The optional argument [S] makes the symbol scale with the height of the integrand.
• \oiiiint[S] — A quadruple contour integral. The optional argument [S] makes the symbol scale with the height of the integrand.
• \oidotsint[S] — Expands to two contour integral symbols with dots in between. The optional argument [S] makes the symbol scale with the height of the integrand.
• \left<delimiter> , \middle<delimiter> , \right<delimiter> — Creates variable sized delimiters around and in between content. Available variable size delimiters are: ( ), [ ], { }, < >, |, \uparrow, \Uparrow, \downarrow, \Downarrow, \updownarrow, \Updownarrow , \lceil \rceil, \lfloor \rfloor. The \middle command is optional and may be omitted. The special dot (.) delimiter is a dummy delimiter that can be used to open or close a \left ... \right construct without a delimiter being shown. 🌈
• \lim — Expands to a limit, i.e. \lim_{x \to 0}.
• \overline{X}, \bar{X} — Draws a line above expression X. little hat, but make it line 💅
• \underline{X} — Draws a line under expression X.
• \\ — Insert a line break.
• \ — Escapes the character.
• \limits — Controls the placements of sub and superscripts. Normally the sub and superscripts are places to the left of its arguments. Using limits you can change this to centered below and above its argument, e.g. \int\limits_a^b.
• \box{W}{H} — Makes an empty box which is W characters wide and H characters high. This may be used to adjust spacing.
• \raisebox{off}{...} — Makes a box and raises its contents by off characters.
• \phantom{...} — Makes an empty box with the same width and height as its rendered argument would have.
• \vphantom{...} — Makes an empty box with 0 width and the same height as its rendered argument would have.
• \hphantom{...} — Makes an empty box with 0 height and the same width as its rendered argument would have.
• \over — Alternative way of making a fraction, e.g. "a \over b".
• \choose — Alternative way of making a binominal, e.g. "n \choose k".
• \exp, \ln, \log, \min, \max, \sin, \cos, \tan, \cot, \arcsin, \arccos, \arctan, \arccot, \sinh, \cosh, \tanh, \coth, \sec, \csc — Functions (function names are formatted in normal text fonts).

🧚 Environments 🧚

Several array-like environments are available. The most general form is the array environment:

\begin{array}[pos]{column alignments}
    a00 & a01 & ... a0n \\
    a10 & a11 & ... a1n \\
    ... & ... & ... ... \\
    am0 & am1 & ... amn
\end{array}

Makes an array. The optional argument pos sets the alignment of the array to t(op), b(ottom) or c(enter). The column alignments consist of one character per column, l(eft), c(enter), or r(ight). Horizontal lines may be inserted with a \hline command. Vertical lines may be inserted by inserting |'s in the column alignment argument (as with LaTeX).

Several derived environments are provided.

\begin{aligned}
\end{aligned}

and

\begin{align}
\end{align}

to align equiations. (yes bestie, that's how it's spelled in the original and i am faithfully preserving it 🫶)

\begin{cases}
\end{cases}

Equivalent to \left{\begin{array}{c...c} ...\end{array}\right.

\begin{pmatrix}
\end{pmatrix}

Equivalent to \left(\begin{array}{c...c} ...\end{array}\right)

\begin{vmatrix}
\end{vmatrix}

Equivalent to \left|\begin{array}{c...c} ...\end{array}\right|

\begin{bmatrix}
\end{bmatrix}

Equivalent to \left[\begin{array}{c...c} ...\end{array}\right]

\begin{Bmatrix}
\end{Bmatrix}

Equivalent to \left{\begin{array}{c...c} ...\end{array}\right}

\begin{matrix}
\end{matrix}

Equivalent to \begin{array}{c...c} ...\end{array}

🌸 A NOTE ON FONTS 🌸

okay bestie, this one is IMPORTANT so pls actually read it, not just skim 💅

utftex depends on mono-space fonts. If your equations are all misaligned, that's your sign — make sure you're using a mono-space font.

But wait, there's more 🙈 even if you do pick a mono-spaced font, be aware that most fonts do not support all defined unicode code-points. When a font doesn't provide a requested unicode code-point, your program/system may use a fall-back font — or it just won't display the character properly at all. And here's the sneaky part: that can also mean your math still gets misaligned, even though you used a monospace font, if the fall-back font isn't mono-spaced 😭

So in that case, make sure the fall-back font is mono-spaced and that the spacing matches that of your primary font. I recommend "monospacifier" to generate an appropriate fall-back font for your primary font. Get it at

---

# ✨ A NOTE ON COMBINING DIACRITICAL MARKS ✨

`utftex` provides commands to insert combining diacritical marks, e.g. `\hat` for the Combining Circumflex Accent. In principle this system is great — iconic design, no notes — but due to limitations in the layout engine and/or the used fonts, such combining characters do not always display properly, and various glitches in display may be the result 😭

> fr fr, this is not a you problem, it's a font/engine problem. Just know it can happen 🫶

---

# 💖 EXAMPLES 💖

If the following equations do not render properly, make sure you read and understood the section **"A NOTE ON FONTS"**. 👑

A simple fraction:

utftex "\frac{1}{1+x}" 1 ─── 1+x

An arbitrary equation with the mathnormal font as default:

utftex -F mathnormal '\lfloor x\rfloor = x - \frac{1}{2} + \sum_{k=1}^{\infty} \frac{\sin(2 \pi k x)}{\pi k}' ∞ 1 ⎲ sin(2 π𝑘 𝑥) ⌊𝑥⌋ = 𝑥 - ─ + ⎳ ─────────── 2 𝑘=1 π𝑘

A small table of Laplace transforms:

utftex '\begin{array}{|l|l|} \hline f(t) & \mathscr{L}[f(t)]=F(s) \\hline 1 & \frac{1}{s} \\hline e^{at}f(t) & F(s-a) \\hline \delta(t) & 1 \\hline \delta(t-t_0) & e^{-st_0} \\hline \int_0^t f(x)g(t-x)dx & F(s)G(s) \hline \end{array}' ┌────────────────┬──────────────┐ │f(t) │ 𝓛[f(t)]=F(s) │ ├────────────────┼──────────────┤ │ │ 1 │ │1 │ ─ │ │ │ s │ ├────────────────┼──────────────┤ │ at │ │ │e f(t) │ F(s-a) │ ├────────────────┼──────────────┤ │δ(t) │ 1 │ ├────────────────┼──────────────┤ │ │ -st │ │ │ 0 │ │δ(t-t ) │ e │ │ 0 │ │ ├────────────────┼──────────────┤ │ t │ │ │⌠ │ │ │⎮ f(x)g(t-x)dx │ F(s)G(s) │ │⌡ │ │ │ 0 │ │ └────────────────┴──────────────┘

---

# 👑 AUTHOR 👑

Bart Pieters

---

# 🎀 LICENSE 🎀

GNU GENERAL PUBLIC LICENSE Version 3

---

# ⭐ VERSION ⭐

`1.0`

---

# 🌈 SEE ALSO 🌈

<pink>That's the whole page, bestie — nothing else linked out from here 💜</pink>

---

<purple>and that's a wrap!! this lil page is from `utftex(1)`, dated <cyan>05 Jul 2022</cyan> 🦋 go render some gorgeous math, you absolute icon 💅✨</purple>