NAME

utftex - An UTF-8 unicode equation renderer

SYNOPSIS

utftex [options] [equation] ...

DESCRIPTION

The aim of utftex is to use the possibilities unicode provides to display math in simple UTF-8 encoded text. utftex renders mathematical equations in mono-space unicode characters, i.e. unicode-art. It is intended to insert equations in source code, e-mails, and man-pages. It generally works without introducing additional dependencies as most text editors and e-mail programs already support UTF-8 encoding out of the box.

Unicode provides many code-points which are intended for mathematical expressions. It even supplies some characters which are intended to "draw" math such as 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.

OPTIONS

All arguments are optional. If no arguments are passed utftex will read one equation from stdin.

[equation]
Each [equation] argument is parsed as one latex equation (i.e. more than one equation may be passed).

[--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.

[--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

[--test-texsymbols -T]
Same as above (list all symbols) in a more machine readable format.

[--version -v]
Print utftex and libtexprintf versions.

[--show-input -i]
Print input before the rendered results.

[--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]

[--box-tree -B]
Print box structure (for debugging purposes)

[--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.

[--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).

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

\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.

a_{b}
sub-script Works just like super-script only now it is a sub-script.

\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

\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.

\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

utftex depends on mono-space fonts. If your equations are all misaligned make sure you use a mono-space fonts. If you do specify a mono-spaced font, be aware that most fonts do not support all defined unicode code-points. When a font does not provide a requested unicode code-point your program/system may use a fall-back font or simply not display the character properly. This could also mean your math will still get misaligned, despite using a monospace font, if the fall-back font is not mono-spaced. In this 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
https://github.com/cpitclaudel/monospacifier

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 but due to limitations in layout engine and/or the used fonts such combining characters do not always display properly and various glitches in display may be the result.

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