OTFTOTFM(1)

📦
version 70015 · 4 versions
, in arch rolling, fedora 44, nixos 26.05, nixpkgs unstable, opensuse-leap 16.0

✨ OTFTOTFM — the manual page, bestie edition 💖

okay so real talk: this is the General Commands Manual entry for otftotfm, and I'm gonna walk you through every single line of it like we're texting at 2am. no skips. no "you get the gist." we're doing the whole thing. 🫶

🌸 NAME 🌸

otftotfm — create TeX font metrics from OpenType fonts

🎀 SYNOPSIS 🎀

otftotfm [-a] [options] fontfile [texname]

💅 DESCRIPTION 💅

Otftotfm creates the font metric and encoding files you need to actually use an OpenType font with TeX. That's the whole vibe. ✨

So here's the deal — you bring:

  • an OpenType .otf or .ttf font file,
  • a base .enc encoding,
  • a TeX name texname for the resulting font,
  • and you tell it which OpenType features should be turned on.

Then otftotfm generates <em>and installs</em> the corresponding TeX-related metric files: .tfm TeX font metrics, .vf virtual fonts, and .enc encoding files. That's the trio. 👑

It works on both PostScript-flavored and TrueType-flavored OpenType fonts — though ngl, TrueType-flavor support will only work easily with pdftex. Just saying it like it is.

The easiest way to use otftotfm is with the -a option — see Automatic Mode below. Without -a, otftotfm writes all its output files to the current directory. periodt.

After running otftotfm fontfile texname and installing the results (manually or with -a), you can use the OpenType font in plain TeX with a command like this:

\font\myfont=texname at 10pt
{\myfont This text uses the OpenType font.}

LaTeX users will generally make a .fd input file so that commands like \renewcommand{\rmdefault}{TeXName} work correctly. See the EXAMPLE section for more; check the DIAGNOSTICS and FREQUENTLY ASKED QUESTIONS sections if you have trouble. 🦋

🌈 OpenType Features 🌈

OpenType fonts support optional features that change their appearance. Use the -f option to turn on selected features. For example, -fsmcp replaces lower-case letters with the corresponding small capitals, in fonts that support this. iconic behavior honestly.

You'll generally provide at least the -fkern and -fliga options, which activate pair kerns and f-ligatures. Other interesting features include:

  • -fcpsp, for capital spacing
  • -fdlig, for optional ligatures
  • -flnum, -fonum, -fpnum, and -ftnum, to control digit glyphs
  • -fsmcp, for small capitals
  • -fswsh, for swash variants
  • -fcswh, for contextual swash

See the FEATURE DIRECTORY section below for more. The otfinfo(1) program will report which features a font supports; run otfinfo -f fontfile. 💫

Feature options can also apply a feature to a subset of characters in the font. For example, --lf smcp only replaces letters with small capitals, whereas -fsmcp might additionally replace digits and punctuation marks with small-capital versions. the way that works?? chef's kiss. 💅

🌟 Automatic Mode 🌟

Automatic mode, triggered by the -a/--automatic option, installs font metrics and encoding files where TeX can find them, and <em>additionally</em> installs a Type 1 font and mapping for dvips(1). This requires a TeX installation that follows the TeX Directory Structure standard (http://www.tug.org/tds/), such as most Unix TeX installations.

Automatic mode should run seamlessly out of the box. Otftotfm will install metrics files, encodings, map files, and Type 1 fonts into $HOME/.texmf-var or any other writable TEXMF directory, and run updmap(1) to update the global lists of installed fonts. 🎀

Heads up bestie: on older teTeX installations, you may first need to copy the system's updmap.cfg file to $HOME/texmf/web2c and run mktexlsr(1). On newer TeXLive installations, you may need to set the TEXMFVAR environment variable.

You can then run otftotfm -a fontfile texname and immediately refer to the font in TeX using the texname you supplied. Again, you will have to write .fd files and/or typescripts to make the font conveniently accessible from LaTeX or ConTeXt. See the DIAGNOSTICS section if you have problems with these instructions.

In automatic mode, otftotfm searches your $TEXMFVAR or $TEXMF path for a writable directory, then installs files under that directory tree as follows:

Where everything goes, file type by file type: 🗂️

  • TFM — directory TEXMF/fonts/tfm/vendor/typeface/, filename texname[--base].tfm
  • VF — directory TEXMF/fonts/vf/vendor/typeface/, filename texname.vf
  • PL — directory TEXMF/fonts/pl/vendor/typeface/, filename texname[--base].pl
  • VPL — directory TEXMF/fonts/vpl/vendor/typeface/, filename texname.vpl
  • encoding — directory TEXMF/fonts/enc/dvips/vendor/ or TEXMF/dvips/vendor/, filename a_signature.enc
  • font map — directory TEXMF/fonts/map/dvips/vendor/ or TEXMF/dvips/vendor/, filename vendor.map

TEXMF stands for the writable TEXMF directory. Texname is the font name supplied as otftotfm's second argument. The vendor and typeface strings are required by TDS; they default to lcdftools and the font's family name, respectively, but see the --vendor and --typeface options. Signature is an opaque 6-character encoding signature. (opaque. mysterious. we love her. 🙈)

Otftotfm also installs a font file suitable for printing. PostScript-flavored OpenType fonts are translated to Type 1 format and installed as PFB fonts. TrueType-flavored fonts are normally installed as is, since pdftex and pdflatex can read TrueType directly; but if you provide the --type42 option, otftotfm will translate TrueType fonts to Type 42 format, which dvips understands.

Important: Otftotfm does not overwrite existing font files. no take-backs, no overwrites. 💀

The installation paths are as follows, where PSname is the font's PostScript name:

  • PFB — TEXMF/fonts/type1/vendor/typeface/ → PSname.pfb
  • TrueType — TEXMF/fonts/truetype/vendor/typeface/ → fontfile
  • Type 42 — TEXMF/fonts/type42/vendor/typeface/ → PSname.t42

You can override these directories with environment variables and options as follows. Options take precedence over environment variables. 👑

  • TFM — environment variable TFMDESTDIR, option --tfm-directory
  • VF — environment variable VFDESTDIR, option --vf-directory
  • PL — environment variable PLDESTDIR, option --pl-directory
  • VPL — environment variable VPLDESTDIR, option --vpl-directory
  • encoding — environment variable ENCODINGDESTDIR, option --encoding-directory
  • PFB — environment variable T1DESTDIR, option --type1-directory
  • TrueType — environment variable TRUETYPEDESTDIR, option --truetype-directory
  • Type 42 — environment variable T42DESTDIR, option --type42-directory
  • font map — environment variable: <em>none</em> (-), option --map-file

Otftotfm will update the TEXMF/ls-R file when installing files under TEXMF. It will also run the updmap(1) program after changing a map file, <em>unless</em> the --no-updmap option was supplied.

However — plot twist 🍓 — if an executable file called TEXMF/dvips/updmap exists, this file is executed (from the TEXMF/dvips directory) rather than the global updmap. This is so you can write a fast, customized version of updmap if desired. main character energy fr fr. 💜

more parts coming, bestie — don't go anywhere 🌈✨

🌸 EXAMPLE 🌸

okay bestie, real talk — this is the part where we actually do the thing. We're gonna use MinionPro to walk through one way of installing OpenType fonts for LaTeX. We start with six fonts: MinionPro-Regular.otf, MinionPro-It.otf, MinionPro-Semibold.otf, MinionPro-SemiboldIt.otf, MinionPro-Bold.otf, and MinionPro-BoldIt.otf. Six girls, one mission. 💅

Our first task is deciding how to encode the fonts. The "encoding scheme" is what TeX uses to figure out how to typeset accents and symbols like $. The "LY1" encoding scheme has reasonable accent support and is a good choice for many OpenType fonts. LY1 corresponds to the texnansx.enc encoding file, so we hand otftotfm the -e texnansx option. ✨

Expert note: Strictly speaking, LY1 corresponds to the texnansi.enc encoding file. Since the texnansx.enc version omits duplicate characters, it has more room for font-specific glyphs and is generally a better choice; but if you plan to type characters like ae directly into your editor, rather than using TeX commands like \ae, you should use texnansi.enc. iykyk 🦋

Next up: naming scheme for the font metric files. Let's use the OpenType font names as a base. (There's generally no need to follow the six-character "Karl Berry" naming scheme, bestie — we're not doing all that.) Just in case we come back later and add a different encoding scheme, we'll prepend LY1-- to each name. 🎀

We're now ready to run otftotfm for the first set of fonts. Note the -fkern -fliga options, which access pair kerns and the default f ligatures. iconic behavior, honestly.

otftotfm -a -e texnansx MinionPro-Regular.otf \
        -fkern -fliga LY1--MinionPro-Regular
otftotfm -a -e texnansx MinionPro-It.otf \
        -fkern -fliga LY1--MinionPro-It
otftotfm -a -e texnansx MinionPro-Semibold.otf \
        -fkern -fliga LY1--MinionPro-Semibold
otftotfm -a -e texnansx MinionPro-SemiboldIt.otf \
        -fkern -fliga LY1--MinionPro-SemiboldIt
otftotfm -a -e texnansx MinionPro-Bold.otf \
        -fkern -fliga LY1--MinionPro-Bold
otftotfm -a -e texnansx MinionPro-BoldIt.otf \
        -fkern -fliga LY1--MinionPro-BoldIt

The small-caps fonts get generated with an extra -fsmcp option. We append --fsmcp to the font metric names too, so they don't get confused with the regular fonts. And yeah — even though MinionPro's italic fonts support small-caps, the LaTeX font selection scheme can't access them easily, so we've left them off. tragic but necessary. 🙈

otftotfm -a -e texnansx MinionPro-Regular.otf \
        -fkern -fliga -fsmcp LY1--MinionPro-Regular--fsmcp
otftotfm -a -e texnansx MinionPro-Semibold.otf \
        -fkern -fliga -fsmcp LY1--MinionPro-Semibold--fsmcp
otftotfm -a -e texnansx MinionPro-Bold.otf \
        -fkern -fliga -fsmcp LY1--MinionPro-Bold--fsmcp

To get old-style numerals, just add the -fonum option to each invocation — and, to reduce confusion, append --fonum to the font metric names. clean, organized, no chaos. we love to see it. 💖

At this point all our font metric files are installed, and it's finally time to create the .fd file. (The .fd format is documented in The LaTeX Companion, if you wanna go read up.) Let's call the LaTeX font family MinionPro. Then the .fd file is LY1MinionPro.fd, and it contains:

\DeclareFontFamily{LY1}{MinionPro}{}
\DeclareFontShape{LY1}{MinionPro}{m}{n}%
        { <-> LY1--MinionPro-Regular }{}
\DeclareFontShape{LY1}{MinionPro}{m}{it}{ <-> LY1--MinionPro-It }{}
\DeclareFontShape{LY1}{MinionPro}{m}{sc}%
        { <-> LY1--MinionPro-Regular--fsmcp }{}
\DeclareFontShape{LY1}{MinionPro}{sb}{n}%
        { <-> LY1--MinionPro-Semibold }{}
\DeclareFontShape{LY1}{MinionPro}{sb}{it}%
        { <-> LY1--MinionPro-SemiboldIt }{}
\DeclareFontShape{LY1}{MinionPro}{sb}{sc}%
        { <-> LY1--MinionPro-Semibold--fsmcp }{}
\DeclareFontShape{LY1}{MinionPro}{b}{n}{ <-> LY1--MinionPro-Bold }{}
\DeclareFontShape{LY1}{MinionPro}{b}{it}%
        { <-> LY1--MinionPro-BoldIt }{}
\DeclareFontShape{LY1}{MinionPro}{b}{sc}%
        { <-> LY1--MinionPro-Bold--fsmcp }{}
\DeclareFontShape{LY1}{MinionPro}{bx}{n}%
        { <-> ssub * MinionPro/b/n }{}
\DeclareFontShape{LY1}{MinionPro}{bx}{it}%
        { <-> ssub * MinionPro/b/it }{}
\DeclareFontShape{LY1}{MinionPro}{bx}{sc}%
        { <-> ssub * MinionPro/b/sc }{}

We're now ready to use MinionPro in LaTeX, with lines like this in the document preamble:

\usepackage[LY1]{fontenc}
\renewcommand{\rmdefault}{MinionPro}
\renewcommand{\bfdefault}{b}

And of course we're free at any time to add more MinionPro variants with otftotfm; they'll become accessible to LaTeX as soon as we edit the MinionPro.fd file. main character energy: the .fd file updates, the whole doc glows up. 👑

✨ OPTIONS ✨

With long options, you need type only as many characters as will make the option unique. lazy typing is valid, bestie, as long as it's unambiguous. 😌

🌈 Font Feature and Transformation Options 🌈

  • -s script[.lang], --script=script[.lang] — Apply features suitable to the script system script and language system lang. Scripts and language systems are two-to-four-letter names assigned by Microsoft and Adobe. Examples include latn (Latin script), grek (Greek script), and yi.YIC (Yi script with classic characters). If lang isn't specified, otftotfm will use the default language system for that script. You can give this option multiple times. Run otfinfo -s font to see the list of scripts and languages a font supports. Defaults to latn.
  • -f feature, --feature=feature — Activate the feature named feature. Features are four-letter names assigned by Microsoft and Adobe; they're meant to correspond to font behaviors, such as kerning or small-capitals. Examples include liga (default ligatures), dlig (discretionary ligatures), kern (kerning), and c2sc (replacing capitals with small capitals). Give this option multiple times to apply multiple features. Run otfinfo -f [--script option] font to see the list of features a font supports for a specified script. Defaults to any features required by the selected scripts.
  • --lf feature, --letter-feature=feature — Activate the feature named feature, but only for letters. For instance, the -f smcp option will apply the small-caps feature to all characters in the encoding; this may result in changes to punctuation and numbers as well as letters. The --lf smcp option will apply the small-caps feature only to letters, meaning characters with the Letter Unicode property. so specific. so intentional. we stan a scoped feature. 💅
  • --subs-filter pattern — see the whole substitution squad below, bestie:
  • --include-subs pattern
  • --exclude-subs pattern
  • --clear-subs

Limit the characters that otftotfm will substitute. Substitution is allowed on an input character if it matches at least one of the --include patterns, and none of the --exclude patterns. Each pattern applies to all following features, except that the --clear option clears any accumulated patterns. The --subs-filter pattern option acts like --clear-subs followed by --include-subs pattern. For pattern syntax, see GLYPH PATTERNS, below.

In the command line below, the '<Number>' pattern will force the onum feature to substitute only numbers (and not, for example, punctuation). The salt feature can still substitute any character.

otftotfm -fsalt --include-subs="<Number>" -fonum ...
  • -E fac, --extend=fac — Widen, or extend, the font by a factor of fac. Like afm2tfm(1)'s -e option.
  • -S amt, --slant=amt — Oblique, or slant, the font by amt. Like afm2tfm(1)'s -s option.
  • -L amt, --letterspacing=amt — Letterspace each character by amt units, where 1000 units equals one em. The width of each character increases by amt, with half the space distributed to each sidebearing. Boundary-character kerns are added to maintain alignment at the ends of lines. yes it's giving spaced-out-elegant, and yes it's doing math about it. ✨
  • --math-spacing[=skewchar] — Ignore the font's claimed character widths, deriving horizontal metrics from bounding boxes instead. This results in similar spacing as the Computer Modern Math Italic font, with increased sidebearings for letters like f and j.

If you provide skewchar, a number between 0 and 255 or a single character, then otftotfm adds heuristically-derived kerns to the font that may improve accent positions in math mode. To get the benefits, you must tell TeX about the skewchar with a command like \skewchar\font=skewchar.

  • -k N, --min-kern=N — Only output kerning pairs whose absolute value is N or larger. Larger minimum kerns make kerning less precise, but shrink the output TFM file. The default minimum kern is 2.0, or 0.002 em. tradeoff alert: precision vs. file size, pick your fighter. ⭐
  • --space-factor=fac — Scale the width of the inter-word space by a factor of fac.
  • --design-size=size — Set the output font's design size to size, a value in TeX points. This value is mostly just documentation, since LaTeX essentially ignores fonts' design sizes, but plain TeX may occasionally use the design size to decide how large a font should be. (Loading a font in TeX at a particular size effectively ignores the design size; loading a font plain or scaled by a given factor uses the design size.) The default is taken from the input font's optical size feature, or 10pt if it has no such feature.
  • --fixed-width — Set the font to fixed-width (its space character will have no stretch or shrink). Normally you won't need this option; the font will tell otftotfm whether it is fixed width. The opposite of --fixed-width is --proportional-width. the font usually snitches on itself, so you rarely need to say it. 🫶
  • --italic-angle=angle — Set the output font's default italic angle to angle, a number of degrees. This value is used by TeX to position accents. Normally you won't need this option; the font will tell otftotfm its italic angle.
  • --x-height=val — Set the output font's x-height to val. This value is used by TeX to position accents. Normally you won't need this option. Val may be a number expressed in font units; ‘x’, which uses the height of the font's lowercase x; or ‘font’, which uses the font's declared x-height metric.

🦋 Encoding Options 🦋

  • -e encoding, --encoding=encoding — Select the output metrics's base dvips(1) encoding. Otftotfm will search for encoding[.enc] the same way that dvips would, so you may not need to give a full pathname. Say -e - to start with the font's default encoding. See ENCODINGS, below, for more information. pro tip from the manpage itself, not from me: see ENCODINGS below. fr fr. 💖
  • --boundary-char=char — Set the font's boundary character to char, which should either be a single non-digit character, or a number between -1 and 255. The default is taken from the encoding.
  • --altselector-char=char — sets your font's alternate selector character to char. And char has to be either a single non-digit character, or a number between -1 and 255, no in-between shenanigans 💅

Okay so alternate selectors are literally the moment: they let TeX authors pick between different versions of a character, on purpose, themselves. Like, --altselector-char="*" turns the "*" character into a special little switch that cycles between alternates. So the TeX input "A" gives you the normal version of the "A" Unicode character, "A*" gives you the first alternate, "A**" gives you the second alternate, and so on forever, bestie, it just keeps going ✨

And ALSO (this is the slay part): "s*t" will activate any discretionary "s_t" ligature in the font. Obsessed.

The --altselector-char mechanism uses the features specified by --altselector-feature options.

You can also specify the alternate-selector character in the encoding; see ENCODINGS, below. And go read Sivan Toledo's article cited in the SEE ALSO section for more info, iykyk 📚

  • --altselector-feature=feature — activates the feature named feature for the --altselector-char mechanism. Give this option multiple times to activate multiple features, no cap. Heads up though: this option activates features only for use with --altselector-char — if you want features activated globally, that's the --feature option's job. Defaults to the salt and dlig features. 🫶
  • --alternates-filter=pattern
  • --include-alternates=pattern
  • --exclude-alternates=pattern
  • --clear-alternates — these four are the girlies that limit which alternate characters otftotfm will select. An alternate gets used if it matches at least one of the --include patterns, and none of the --exclude patterns. Each pattern applies to all following features, except that the --clear option clears any accumulated patterns. And the --alternates-filter pattern option acts like --clear-alternates followed by --include-alternates pattern. For pattern syntax, see GLYPH PATTERNS, below 🔍

Real talk: OpenType fonts can have SO many alternates per character, and most of them are not the vibe. For example, the character "a" in WarnockPro-Regular has five alternates — "ordfeminine", "Asmall", "asuperior", "a.end", and "orn.013". The --altselector-char option lets you cycle through these alternates, but honestly it's better to leave out the ones you don't want, so you don't end up with overfull encodings (a mess, truly 💀). So if you were only interested in ".end" variants, you might supply an --include-alternates="*.end" option.

In the command line below, the *.end pattern will apply to "aalt" alternates, but not to "salt" alternates:

otftotfm -fsalt --include-alternates="*.end" -faalt ...
  • --ligkern=command — adds a LIGKERN command to the encoding. For example, --ligkern "T {L} h" suppresses any T_h ligature in the font. You can supply multiple --ligkern options, stack 'em up. See ENCODINGS, below.
  • --position=command — adds a POSITION command to the encoding. For example, --position "T 10 0 20" adds ten units of space to either side of the "T" character. You can supply multiple --position options too. See ENCODINGS, below.
  • --unicoding=command — adds a UNICODING command to the encoding. For example, --unicoding "pi1 =: uni03D6" tells otftotfm to encode /pi1 as U+03D6 GREEK PI SYMBOL. You can supply multiple --unicoding options. See ENCODINGS, below. 🎀
  • --no-encoding-commands — ignores any LIGKERN and/or UNICODING commands in the encoding file. Bye bestie 👋
  • --no-default-ligkern — don't include otftotfm's default LIGKERN commands.
  • --coding-scheme=scheme — adds a CODINGSCHEME to the encoding. See ENCODINGS, below.
  • --warn-missing — warns you about encoded characters the font doesn't support. See the WARNMISSING command in ENCODINGS, below. It's giving protective friend energy 🛡️
  • --literal-encoding=encoding — selects the dvips(1) encoding used for the font. No glyph substitutions will be permitted, so the output encoding will equal the input encoding — and otftotfm will not generate an output encoding at all. What you put in is what you get, periodt.
  • --base-encodings=file — experts only, bestie, this one's for the advanced girlies 🔥 Allows the output font to refer to existing "base" fonts. This can greatly reduce the number of base fonts generated by otftotfm, which is a huge slay. Each line in the file argument contains a TeX font name (as for --name) and a corresponding literal encoding file (as for --literal-encoding); for example:
WarnoProReg--eka eka
WarnoProReg--exp1 exp1

The named fonts must have been created by prior runs of otftotfm on the same input OpenType font, with the same --extend and --slant options as the current run. The current output font will refer to glyphs from the named base fonts when possible. And if the base fonts cover all glyphs required by the output font, otftotfm won't generate any new base fonts at all — zero, none, iconic 💅

The file can also refer to dotless-J fonts using the following syntax:

WarnoProReg--lcdfj - dotlessj

🌈 Automatic Mode Options 🌈

  • -a, --automatic — selects automatic mode. Let the program be the main character for once ✨
  • -v vendor, --vendor=vendor — sets the font vendor name, which is used to locate files within the TDS. Defaults to "lcdftools".

In automatic mode, TeX and friends will generally find required font files independently of the vendor you select. So it's lowkey fine either way 🦋

  • --typeface=typeface — sets the font typeface name, which is used to locate files within the TDS. Defaults to the current font's family name with unsuiable characters removed.
  • --no-type1 — do not use cfftot1(1) to create Type 1 fonts corresponding to the OpenType input fonts.
  • --no-dotlessj — do not use t1dotlessj(1) to create a special dotless-j font when the input font doesn't have dotless-j. (Not the dotless j erasure 😭)
  • --no-truetype — do not install TrueType-flavored fonts.
  • --type42 — install TrueType-flavored fonts in translated Type 42 format. Fancy ✨
  • --no-updmap — do not run an updmap(1) program. This can be useful if you're installing a bunch of fonts; it is much faster to run updmap once, at the end, than to run it once per font. Efficiency queen behavior 👑

💖 Output Options 💖

  • -n texname, --name=texname — sets the TeX name of the output font, which is used in font map files and, in automatic mode, to generate the output filename. The default is derived from the OpenType font's name and the features you selected.
  • -p, --pl — outputs human-readable PL and VPL metrics, not binary TFM and VF metrics. Note: Otftotfm's PL and VPL output files are legal, but the fontinst program may not accept them (it has a picky parser, honestly a bit much of it 🙄). Make sure to supply a --coding-scheme; if that doesn't help, run the TFM output through tftopl(1).
  • --no-virtual — do not generate virtual fonts (VFs and VPLs). Otftotfm will warn if the selected font features cannot be implemented without virtual fonts. It'll let you know, don't worry 🫶
  • --no-encoding — do not generate an encoding file.
  • --output-encoding[=file] — only generate an encoding file; do not generate any other output. The encoding file is written to file, or to standard output if no file argument is supplied.
  • --no-map — do not generate a font map line for the font.

🦋 File Location Options 🦋

  • --tfm-directory=dir
  • --pl-directory=dir
  • --vf-directory=dir
  • --vpl-directory=dir
  • --encoding-directory=dir
  • --type1-directory=dir
  • --truetype-directory=dir
  • --type42-directory=dir
  • --directory=dir — sets the directory used for various output types. Each directory may be set by an environment variable, and defaults to a TDS directory in automatic mode, or to "." otherwise. Environment variable names and default TDS locations are described in the Automatic Mode section above. And the --directory option sets the default directory for all output types — one option to rule them all 💅
  • --map-file=filename — sets the file in which otftotfm will write a font map line for the font. The default is the standard output in manual mode, and "TEXMF/fonts/map/dvips/vendor/vendor.map" (or "TEXMF/dvips/vendor/vendor.map" on older installations) in automatic mode.

🎀 Miscellaneous Options 🎀

  • --glyphlist=file — use file as an Adobe glyph list, which helps translate glyph names to Unicode code points. Give multiple options to include multiple files. See ENCODINGS, below, for more information.
  • -V, --verbose — writes progress messages to standard error. Tell me everything, bestie 🗣️
  • --no-create — do not create or modify any files. Instead, it writes messages about the program's hypothetical progress to standard error. It's a vibe check run, nothing actually happens 💭
  • --force — generates all files, even if it looks like versions are already installed. No chill, just output.
  • -q, --quiet — do not generate any error messages. Silence is golden 🤫
  • --kpathsea-debug=flags — sets path searching debugging flags. See the Kpathsea manual for details.
  • -h, --help — prints usage information and exits. Your bestie when you're lost 🫶
  • --version — prints the version number and some short non-warranty information and exits.

💖 ENCODINGS 💖

Okay bestie, so otftotfm reads encoding files as Unicode, periodt 💅. Like imagine an input encoding has /dotlessi chillin at position 10. Otftotfm is like “bestie, position 10 should contain Unicode character U+0131 LATIN SMALL LETTER DOTLESS I” and it uses the font’s glyph for that character (possibly modified by any active features). The selected glyph might not be named dotlessi; only the Unicode value matters, no cap ✨.

Otftotfm assigns Unicode values to glyph names using a table published by Adobe (SEE ALSO has a reference), with extensions for TeX. Want more fine-grained control? Add UNICODING commands to the input encoding file. These commands have the following format:

% UNICODING glyph =: choice1 [choice2 ...] ;

This tells otftotfm that the glyph named glyph translates into the first Unicode value in the choice list that has a character in the font. glyph and the choices are PostScript glyph names; the initial % sign is required; and each UNICODING line can contain multiple commands, separated by spaced semicolons. For example:

% UNICODING pi1 =: uni03D6 ;

encodes the character /pi1 as U+03D6 GREEK PI SYMBOL, and:

% UNICODING Delta =: uni0394 uni2206 ;

makes U+0394 GREEK CAPITAL LETTER DELTA preferred to U+2206 INCREMENT as an encoding for /Delta. You can also supply glyph names:

% UNICODING Delta =: Deltagreek Delta ;

A mapping with no Unicode values removes that glyph from the input encoding. For instance, this erases any f-ligature characters from the encoding:

% UNICODING ff =: ; fi =: ; fl =: ; ffi =: ; ffl =: ;

The slots are then available for otftfm’s own use, for example for other characters required by the font. (If the f-ligatures themselves are required by the font, for instance by a 'liga' feature, then they will be stored into their old slots when possible.) Map a glyph to 'emptyslot' if you don’t want otftotfm to use the slot. For example, this will leave the 'ff' slot unused if the font has no 'ff' glyph:

% UNICODING ff =: ff emptyslot ;
Note: most OpenType fonts provide a visible representation for unused encoding slots, namely a box with an X inside. 💀

LIGKERN comments in the encoding can add ligatures and inhibit kerns, as in afm2tfm(1). To add a ligature, say:

% LIGKERN glyph1 glyph2 =: result ;

The =: operator indicates a normal ligature, where both the input glyphs are removed and replaced by result. To preserve the left-hand glyph, for an effect like glyph1 glyph2 =: glyph1 result, use |=: instead; to preserve the right-hand glyph, use =:|. To remove all kerns between two characters, say:

% LIGKERN glyph1 {} glyph2 ;

A * matches any character, so:

% LIGKERN a {} * ;

removes all kerns with a as the left-hand character, and:

% LIGKERN * {} * ;

removes all kerns. Slay. 👑

Otftotfm also supports extended syntax for setting kern values and inhibiting ligatures. To add an n-unit kern between two glyphs, say:

% LIGKERNX glyph1 {n} glyph2 ;

where n is an integer. This:

% LIGKERNX glyph1 {L} glyph2 ;

inhibits any ligature between glyph1 and glyph2. {LK} and {KL} inhibit both ligatures and kerns.

You can set the --boundary-char and --altselector-char from an encoding file with commands like this:

% LIGKERN || = boundarychar ;
% LIGKERNX ^^ = altselectorchar ;

As with UNICODING, each LIGKERN or LIGKERNX line can contain multiple commands, separated by spaced semicolons.

Otftotfm has a default set of eight ligatures, namely:

space l =: lslash ; space L =: Lslash ;
question quoteleft =: questiondown ; exclam quoteleft =: exclamdown ;
hyphen hyphen =: endash ; endash hyphen =: emdash ;
quoteleft quoteleft =: quotedblleft ;
quoteright quoteright =: quotedblright

LIGKERN commands in the encoding file and --ligkern options can override these defaults, or supply the --no-default-ligkern option to turn them off.

The POSITION command shifts a glyph within its bounding box. The syntax is:

% POSITION glyph pdx pdy adx ;

This will add pdx units of space to glyph’s left edge; raise it up by pdy units; and add adx units to its width. For example, to add 10 units of space to either side of the "T" glyph, supply:

% POSITION T 10 0 20

To move the "degree" symbol up by 20 units, supply:

% POSITION degree 0 20 0

The CODINGSCHEME command specifies the coding scheme for fonts using this encoding. This is a string, less than 40 characters long and containing no parentheses, that classifies the encoding for TeX’s purposes. Sample coding schemes include "TEX TEXT", "TEX MATH ITALIC", and "EXTENDED TEX FONT ENCODING - LATIN". For example:

% CODINGSCHEME EXTENDED TEX FONT ENCODING - LATIN

Most tools ignore the coding scheme; fontinst is an exception. Otftotfm uses the encoding’s PostScript name for the default coding scheme.

Finally, the WARNMISSING command makes any glyphs not supported by the input font appear as black boxes. The dvips(1) processor will also print a warning when encountering these glyphs. For example:

% WARNMISSING yes

The --unicoding, --ligkern, --position, --coding-scheme, and --warn-missing options add UNICODING, LIGKERN/LIGKERNX, POSITION, CODINGSCHEME, and WARNMISSING commands to an encoding, and can override commands in the encoding itself. Some common encoding files have commands that are inappropriate for OpenType fonts; for example, "t1.enc" hard-codes f-ligatures, which can cause problems with small-cap fonts. Supply the --no-encoding-commands option to ignore all commands from the encoding file. Commands from options like --ligkern are processed in any case.

🌱 New Glyphs 🌱

New glyphs, such as ligatures and contextual substitutions, are added to the encoding in any empty spaces, using their original locations when possible. If the encoding doesn’t have enough space for all new glyphs, shorter ligatures composed of unaccented letters get precedence.

✨ Synthetic Glyphs ✨

Otftotfm can synthesize some glyphs using virtual font manipulations, if a required glyph is not available in the input font. Specifically, it will synthesize:

  • cwm — TeX’s compound word mark (a zero-width "strut" rule with height equal to the font’s x-height)
  • ascendercompwordmark — "cwm" with height equal to the font’s ascenders
  • capitalcompwordmark — "cwm" with height equal to the font’s capitals
  • visualspace — A square cup used to represent spaces
  • dotlessj — A dotless "j", synthesized with t1dotlessj(1)
  • dblbracketleft — Kerned version of "[["
  • dblbracketright — Kerned version of "]]"
  • bardbl — The parallel symbol "||"
  • asteriskmath — Vertically-centered "*"
  • ringfitted — Ring accent centered on the width of "A"
  • twelveudash — 2/3-em-wide dash
  • threequartersemdash — 3/4-em-wide dash
  • centigrade — "(degrees)C"
  • interrobang — Combined "?!" symbol
  • interrobangdown — Inverted interrobang
  • pertenthousand — Per-ten-thousand sign (% with two extra 0s)
  • IJ — "IJ" ligature
  • ij — "ij" ligature
  • Germandbls — "SS" (a capital sharp-s)
  • SSsmall — Small-capital version of "SS"
  • FFsmall — Small-capital version of "FF"
  • FIsmall — Small-capital version of "FI"
  • FLsmall — Small-capital version of "FL"
  • FFIsmall — Small-capital version of "FFI"
  • FFLsmall — Small-capital version of "FFL"

🌈 GLYPH PATTERNS 🌈

The --include-subs and --include-alternates options, and their --exclude and --*-filter variants, accept the following types of pattern.

  • Glyph names. Example: "Aacute". For PostScript-flavored fonts, use otfinfo(1)’s -g option to see a font’s glyph names, and "cfftot1 font.otf | t1testpage" to generate a PostScript file showing each glyph.
  • Glyph name patterns using the shell-style glob-matching rules: "*" matches any number of characters, "?" matches any single character, and "[...]" matches any character in a set. Example: "*.end".
  • Unicode category properties in angle brackets. Examples: "<Letter>", "<UppercaseLetter>", "<Lu>". The complete list of both short and long names: Letter/L, UppercaseLetter/Lu, LowercaseLetter/Ll, TitlecaseLetter/Lt, ModifierLetter/Lm, OtherLetter/Lo; Number/N, DecimalNumber/Nd, LetterNumber/Nl, OtherNumber/No; Punctuation/P, ConnectorPunctuation/Pc, DashPunctuation/Pd, OpenPunctuation/Ps, ClosePunctuation/Pe, InitialPunctuation/Pi, FinalPunctuation/Pf, OtherPunctuation/Po; Symbol/S, MathSymbol/Sm, CurrencySymbol/Sc, ModifierSymbol/Sk, OtherSymbol/So; Mark/M, SpacingMark/Mc, EnclosingMark/Me, NonspacingMark/Mn; Separator/Z, SpaceSeparator/Zs, LineSeparator/Zl, ParagraphSeparator/Zp; Other/C, Surrogate/Cs, Format/Cf, Control/Cc, PrivateUse/Co, Unassigned/Cn. Category values current as of Unicode 4.0.
  • Unicode ranges. Example: "U+007f-U+008C".

The "!" prefix negates a pattern, and you can separate multiple patterns by spaces.

✨ FEATURE DIRECTORY ✨

okay so this section is like a whole directory of features that are common in Western OpenType fonts, and it spills the tea on how otftotfm handles them for common fonts. if otftotfm isn't handling a feature you need, or you think it's handling something wrong, bestie, just send the author mail, okay? 💌

  • aalt, Access All Alternates — so this one lets you pick between ALL the alternate forms for a character. we're talking superscript and subscript variants, different styles (like swash, for example), and even ornaments. the --altselector-feature=aalt option can help an --altselector-char give you useful access to alternates, but honestly, the aalt feature isn't usually useful on its own. try the salt and calt features instead, bestie. 🦋
  • c2sc, Small Capitals From Capitals — replaces capital letters with small capitals — it's like the converse of the more conventional smcp feature, which replaces lower-case letters with small capitals. supported. 💯
  • calt, Contextual Alternates — lets you choose between context-appropriate swash forms for each character. like, imagine the word "DREW" in a cursive typeface — the "R E W" might get translated to calmer forms than the initial "D". there might be more than one choice for a given letter, and you should be able to pick among them. TeX can't support complex contextual alternates or alternate selection, but otftotfm handles some fonts pretty well. the input encoding should have lots of empty space for variants, and it should specify a boundary character. see also cswh. ✨
  • case, Case-Sensitive Forms — shifts punctuation marks up to a position that works well with ALL-CAPS sequences. for example, the hyphen character — which usually centers vertically on the x-height — gets raised up to center vertically on a capital letter. it also replaces text figures with lining figures, and accent marks with forms more appropriate for capitals. supported. 👑
  • cpsp, Capital Spacing — adds a little bit of space on either side of each capital letter. supported. (but heads up: the OpenType tag registry suggests that cpsp be on by default, but only applying to all-caps text; TeX can't easily implement that contextual intelligence.) 🧚
  • cswh, Contextual Swash — lets you choose between context-appropriate swash forms for each character. like, in the words "Ab AC", the first "A" might get translated to a swash form, while the second might not. there might be more than one choice for a given letter, and you should be able to select among them. otftotfm supports some fonts quite well. the input encoding should have lots of empty space for swash variants, and it should specify a boundary character. see also calt and swsh. 🌸
  • dlig, Discretionary Ligatures — activates uncommon ligatures, like "c_t", "s_p", and "s_t". supported. 🎀
  • dnom, Denominators — replaces digits and some punctuation marks with smaller forms sitting on the baseline — perfect for fraction denominators. supported. 🍓
  • fina, Terminal Forms — substitutes appropriate forms for letters that show up at the ends of words. this feature doesn't select swash variants; it's meant for normal use, and the spec recommends it be on by default. partially supported: TeX will only treat spaces as the ends of words, where a correct implementation would probably include punctuation too. see cswh for selecting swash variants active at the ends of words. 💅
  • frac, Fractions — replaces simple sequences like "1/2" with nice-looking fractions. supported, but beware: many fonts will translate "11/32" into "1" + "1/3" + "2". 😬
  • hist, Historical Forms — replaces characters with historical variants. usually that means at least translating regular "s" to long "s". supported. 📜
  • kern, Kerning — adjusts the space between characters (pair kerning). generally supported, and you should probably turn it on. as a special case, -fkern can also read kerning information from the kern table in conventional TrueType fonts. 🔥
  • liga, Standard Ligatures — activates common ligatures, like "f_f", "f_i", "f_f_j", and (in some Adobe fonts) "T_h". generally supported, and you should probably turn it on. 💖
  • lnum, Lining Figures — uses lining figures — the set of digits that are all about as high as capital letters. supported. compare onum; see also pnum and tnum. 🔢
  • numr, Numerators — replaces digits and some punctuation marks with smaller, raised forms meant for fraction numerators. supported, but not usually useful. 🤷
  • onum, Oldstyle Figures — uses old-style figures, aka text figures. this is the set of digits that have ascenders and descenders like lower-case letters. supported. compare lnum; see also pnum and tnum. 🌈
  • ordn, Ordinals — designed for Spanish and French. replaces ordinal numbers, like "2.o", with forms where the "o" is raised, and replaces the sequence "No" with an integrated glyph. supported. 🇪🇸🇫🇷
  • ornm, Ornaments — replaces some alphabetic characters in the font with ornaments, and links the bullet character to a set of all bullet-like ornaments that you can choose from. partially supported: TeX can handle alphabetic substitutions, but not bullet choice. 💀
  • pnum, Proportional Figures — digits will have different widths. supported. compare tnum; see also lnum and onum. 📏
  • salt, Stylistic Alternates — lets you choose between stylistic alternate forms for a character. the --altselector-char mechanism gives you useful access to this feature. if you turn on salt globally, otftotfm takes the first alternate form whenever there's more than one choice. see also aalt and ss01; salt is generally more useful than aalt for TeX, since it refers exclusively to stylistic alternates. 🧂
  • sinf, Scientific Inferiors — replaces digits and some punctuation marks with smaller, lowered forms meant for subscripts. supported. compare subs. 🔬
  • size, Optical Size — this feature stores info about the range of optical sizes the font was intended for. there's literally no point in selecting it with otftotfm, since it shouldn't change the font's appearance in any way. 👀
  • smcp, Small Capitals — replaces lower-case letters with small capitals. supported. compare c2sc. 🅰️
  • ss01-ss20, Stylistic Sets 1-20 — stylistic sets 1-20. replaces characters with a uniform set of stylistic alternates. differs from features like salt in that a Stylistic Set is uniform: an ssXX feature should never involve selection from a set of possible alternate characters. supported. 🎨
  • subs, Subscript — replaces characters with smaller, lowered forms meant for subscripts. supported. compare sinf; some fonts support sinf but not subs. ⬇️
  • sups, Superscript — replaces digits, some punctuation marks, and some lower-case letters with smaller, raised forms meant for superscripts. supported. ⬆️
  • swsh, Swash — activates all swash forms for each character. there might be more than one swash form, in which case otftotfm will pick the first one listed. supported, except that swash variants other than the first are inaccessible. note that some fonts with swash variants support the cswh feature exclusively. ✒️
  • tnum, Tabular Figures — all digits will have the same width, so tables and stuff will align visually. supported. compare pnum; see also lnum and onum. 📊
  • zero, Slashed Zero — replaces the zero character with a slashed zero. supported. 🚫0️⃣

🩺 DIAGNOSTICS AND TROUBLESHOOTING 🩺

no writable directory found in $TEXMF

otftotfm couldn't find a writable directory in your $TEXMFVAR or $TEXMF path. did you create a $HOME/.texmf-var or $HOME/texmf directory? if so, run the command kpsewhich --expand-path='$TEXMF' to verify that directory is not being found. you may need to set your TEXMF environment variable, to '{!!'"$HOME"'/texmf,!!$TEXMFMAIN}', for instance (note the different kinds of quotes; on my machine, this expands to '{!!/home/kohler/texmf,!!$TEXMFMAIN}'). 🏠

'char' has no encoding, ignoring kern removal (or ligature removal, lig/kern removal, or ligature)

these messages mean there's a slight problem with your encoding file: one of the LIGKERN commands referred to a character not present in the encoding. this might be a misspelling in the LIGKERN command or the encoding file, or it might be an oversight. either fix the encoding file or ignore the warning. your call. 🤷

can't map 'char' to Unicode

another encoding file problem: one of the glyph names in an UNICODING block couldn't be converted to Unicode. this is problematic since UNICODING exists wholly to translate glyph names into Unicode. fix the encoding file or ignore the warning. 🔍

not enough room in encoding, ignoring N glyph(s) ...

there wasn't space in the encoding for all the glyphs that the features you selected referred to. for example, maybe the font had more ligatures than there were empty slots in the encoding. fix this warning by selecting fewer features, or by using an encoding with more empty slots, like the 7t.enc encoding distributed with otftotfm. 📦

The '-a' option did not install my font correctly.

try again with the --verbose option, which makes otftotfm explain its behavior. note that by default, otftotfm will not re-install files already present in your system's TeX search paths (in the current directory, for instance). use --force to override this behavior. 💪

💖 FREQUENTLY ASKED QUESTIONS 💖

okay bestie, these are the questions everyone slides into our inbox with. let's go 💅

How can I get a small-caps "SS" in place of the German sharp-S?

just hand it the option --unicoding "germandbls =: SSsmall" and you're done, no cap 🫶

How can I prevent f-ligatures from forming in a small-caps font?

so this should happen automatically, fr fr — but some overzealous encoding files go ahead and add f-ligatures even when the font isn't requesting them. if that's messing with your vibe, try the --no-encoding-commands option. ✨

Otftotfm seems to take a long time.

not it taking forever 😭 use the -V option to see what it's actually doing in there. usually the culprit is the updmap(1) program; so if you're planning to run otftotfm multiple times, give it the --no-updmap option and then run updmap manually once you're all done. efficiency queen behavior 👑

How can I refer to the different forms of phi?

okay so otftotfm follows TeX practice and the widely-distributed TeX encoding vectors, which means /phi in an input encoding vector should map to a "straight" phi and /phi1 should map to a "loopy" phi. 💫

but heads up — TeX practice differs from the PostScript standard naming conventions, where /phi is "loopy" and /phi1 is "straight". which means otftotfm may map /phi in an input encoding vector to a font's /phi1 glyph, and vice versa. 🙈

and if you want the most unambiguous route possible: use /uni03D5 for the "straight" form and /uni03C6 for the "loopy" form. periodt. 💅

How can I get lining figures (that is, normal line-height digits) with small caps (-fsmcp)?

so many fonts use old-style figures by default with small caps. and since the default is not specified, it's wise — like, genuinely wise — to explicitly supply -flnum or -fonum. don't leave it up to the universe, bestie. 🎀

🐛 BUGS 🐛

if you have problems running otftotfm's output through fontinst, go read the documentation for --pl above. iykyk.

👀 SEE ALSO 👀

👑 AUTHOR 👑

Eddie Kohler (ekohler@gmail.com) — an actual legend, we stan 💜

and huge thanks to Karl Berry, Marco Kuhlmann, Adam Lindsay, Bruce D'Arcus, Thomas Esser, Claire Connelly, Nelson H.F. Beebe, and Ryuji Suzuki for suggestions, bug reports, and help. 🫶

and particular thanks to Achim Blumensath and Michael Zedler for suggestions and patches, some of them extensive. iconic behavior, honestly 🌈

and that's the whole page, bestie!! this was Version 2.110 of the LCDF Typetools — you just read the OTFTOTFM(1) man page, cover to cover, and you ATE. no crumbs. go make some fonts 💖✨🎀

📦 where this page comes from