1AUTOINST(1) Marc Penninga AUTOINST(1)
2
6 autoinst - wrapper around the LCDF TypeTools, for installing and using
7 OpenType fonts in LaTeX.
8
10 autoinst -help
11 autoinst [options] font(s)
13
15 Eddie Kohler's LCDF TypeTools are superb tools for installing OpenType
16 fonts in LaTeX, but they can be hard to use: they need many, often
17 long, command lines and don't generate the fd and sty files LaTeX
18 needs. autoinst simplifies the use of the TypeTools for font
19 installation by generating and executing all commands for otftotfm, and
20 by creating and installing all necessary fd and sty files.
21 Given a family of font files (in otf or ttf format), autoinst will
23 create several LaTeX font families:
24 - Four text families (with lining and oldstyle digits, each in both
26 tabular and proportional variants), all with the following shapes:
27 n Roman (i.e., upright) text
29 it, sl Italic and slanted (sometimes called oblique) text
31 sc Small caps
33 scit, scsl
35 Italic and slanted small caps
36 sw Swash
38 nw "Upright swash"
40 - For each T1-encoded text family: a family of TS1-encoded symbol
42 fonts, in roman, italic and slanted shapes.
43 - Families with superiors, inferiors, numerators and denominators,
45 in roman, italic and slanted shapes.
46 - Families with "Titling" characters; these "... replace the default
48 glyphs with corresponding forms designed specifically for titling.
49 These may be all-capital and/or larger on the body, and adjusted
50 for viewing at larger sizes" (according to the OpenType
51 Specification).
52 - An ornament family; also in roman, italic and slanted shapes.
54 Of course, if your fonts don't contain italics, oldstyle digits, small
56 caps etc., the corresponding shapes and families are not created. In
57 addition, the creation of most families and shapes can be controlled by
58 the user (see "COMMAND-LINE OPTIONS" below).
59 These families use the FontPro project's naming scheme:
61 <FontFamily>-<Suffix>, where <Suffix> is:
62 LF proportional (i.e., figures have varying widths) lining figures
64 TLF tabular (i.e., all figures have the same width) lining figures
66 OsF proportional oldstyle figures
68 TOsF tabular oldstyle figures
70 Sup superior characters (note that most fonts have only an
72 incomplete set of superior characters: digits, some punctuation
73 and the letters abdeilmnorst; normal forms are used for other
74 characters)
75 Inf inferior characters; usually only digits and some punctuation,
77 normal forms for other characters
78 Titl Titling characters; see above
80 Orn ornaments
82 Numr, Dnom
84 numerators and denominators
85 The individual fonts are named <FontName>-<suffix>-<shape>-<enc>, where
87 <suffix> is the same as above (but in lowercase), <shape> is either
88 empty, "sc" or "swash", and <enc> is the encoding (also in lowercase).
89 A typical name in this scheme would be FiraSans-Light-osf-sc-ly1.
90 Using the fonts in your LaTeX documents
92 autoinst generates a style file for using the fonts in LaTeX documents,
93 named <FontFamily>.sty. This style file also loads the fontenc and
94 textcomp packages, if necessary. To use the fonts, add the command
95 "\usepackage{<FontFamily>}" to the preamble of your document.
96 This style file has a few options:
98 "mainfont"
100 Redefine "\familydefault" to make this font the main font for the
101 document. This is a no-op if the font is installed as a serif
102 font; but if the font is installed as a sanserif or typewriter
103 font, this option saves you from having to redefine
104 "\familydefault" yourself.
105 "lining", "oldstyle", "tabular", "proportional"
107 Choose which figure style to use. The defaults are "oldstyle" and
108 "proportional" (if available).
109 "scale=<number>", "scale=MatchLowercase"
111 Scale the font by a factor of <number>. E.g., to increase the size
112 of the font by 5%, use "\usepackage[scale=1.05]{<FontFamily>}".
113 The special value "MatchLowercase" may be used to scale the font so
114 that its x-height matches that of the current main font (which is
115 usually Computer Modern Roman, unless you have loaded another font
116 package before this one). The name "scaled" may be used as a
117 synonym for "scale".
118 "medium", "book", "text", "normal", "regular"
120 Select the weight that LaTeX will use as the "regular" weight.
121 "heavy", "black", "extrabold", "demibold", "semibold", "bold"
123 Select the weight that LaTeX will use as the "bold" weight.
124 The last two groups of options will only work if you have the mweights
126 package installed. The default here is not to change LaTeX's default,
127 i.e. use the "m" and "b" weights.
128 The style file will also try to load the fontaxes package (on CTAN),
130 which gives easy access to various font shapes and styles. Using the
131 machinery set up by fontaxes, the generated style file defines a number
132 of commands (which take the text to be typeset as argument) and
133 declarations (which don't take arguments, but affect all text up to the
134 end of the current group) to access titling, superior and inferior
135 characters:
136 DECLARATION COMMAND SHORT FORM OF COMMAND
138 \tlshape \texttitling \texttl
140 \supfigures \textsuperior \textsup, \textsu
141 \inffigures \textinferior \textinf, \textin
142 In addition, the existing "\swshape" and "\textsw" commands are
144 redefined to place swash on fontaxes' secondary shape axis (fontaxes
145 places it on the primary shape axis) to make them behave properly when
146 nested, so that "\swshape\upshape" will give upright swash.
147 There are no commands for accessing the numerator and denominator
149 fonts; these can be selected using fontaxes' standard commands, e.g.,
150 "\fontfigurestyle{numerator}\selectfont".
151 These commands are only generated for existing shapes and number
153 styles; no commands are generated for shapes and styles that are
154 missing from your fonts. Also these commands are built on top of
155 fontaxes, so if that package cannot be found, you're limited to using
156 the lower-level commands from standard NFSS ("\fontfamily",
157 "\fontseries", "\fontshape" etc.).
158 By default, autoinst generates text fonts with OT1, LY1 and T1
160 encodings, and the generated style files use T1 as the default text
161 encoding. Other encodings can be chosen using the -encoding option
162 (see "COMMAND-LINE OPTIONS" below).
163 Maths
165 This is an experimental feature; USE AT YOUR OWN RISK! Test the
166 results thoroughly before using them in real documents, and be warned
167 that future versions of autoinst may introduce incompatible changes.
168 The -math option tells autoinst to generate basic math fonts. When
170 enabled, the generated style file defines a few extra options to access
171 these math fonts:
172 "math"
174 Use these fonts for the maths in your document.
175 "mathlining", "matholdstyle"
177 Choose which figure style to use in maths. The default is
178 "mathlining".
179 "mathcal"
181 Use the swash characters from your fonts as the "\mathcal"
182 alphabet. (This option will only exist if your fonts actually
183 contain swash characters, plus a "swsh" feature to access them).
184 "nomathgreek"
186 Don't redeclare greek letters in math.
187 "math-style=<style>"
189 Choose the "math style" to use. With "math-style=ISO", all latin
190 and greek letters in math are italic; with "math-style=TeX" (the
191 default), uppercase greek is upright; with "math-style=french", all
192 greek as well as uppercase latin is upright; and with
193 "math-style=upright" all letters are upright.
194 Note that this "math" option only affects digits, latin and greek
196 letters, plus a few basic punctuation characters; all other
197 mathematical symbols, operators, delimiters etc. are left as they were
198 before. If you don't want to use TeX's default versions of those
199 symbols, load another math package (such as mathdesign or newtxmath)
200 before loading the autoinst-generated style file.
201 Finally, note that autoinst doesn't check if your fonts actually
203 contains all of the required characters; it just assumes that they do
204 and sets up the style file accordingly. Even if your fonts contain
205 greek, characters such as "\varepsilon" may be missing. You may also
206 find that some glyphs are present in your fonts, but don't work well in
207 equations or don't match with other symbols; edit the generated style
208 file to remove the declarations of these offending characters. Once
209 again: test the results before using them! If the characters
210 themselves are fine but spaced too tightly, you may try increasing the
211 side bearings in math fonts with the -mathspacing option (see below),
212 e.g. "-mathspacing=50".
213 NFSS codes
215 LaTeX's New Font Selection System (NFSS) identifies fonts by a
216 combination of family, series (the concatenation of weight and width),
217 shape and size. autoinst parses the font's metadata to determine these
218 parameters. When this fails (usually because the font family contains
219 uncommon weights, widths or shapes), autoinst ends up with multiple
220 fonts having the same values for these font parameters; such fonts
221 cannot be used in NFSS, since there's no way distinguish them. When
222 autoinst detects such a situation, it will print an error message and
223 abort. If that happens, either rerun autoinst on a smaller set of
224 fonts, or add the missing widths, weights and shapes to the tables
225 @WIDTH, @WEIGHT and %SHAPE in the source code. Please also send a bug
226 report (see AUTHOR below).
227 The mapping of shapes to NFSS codes is done using the following table:
229 SHAPE CODE
231 -------------------------------- ----
232 Roman, Upright n
233 Italic it
234 Oblique, Slant(ed), Incline(d) sl
235 (Exception: Adobe Silentium Pro contains two Roman shapes; we map the
237 first of these to "n", for the second one we (ab)use the "it" code as
238 this family doesn't contain an Italic shape.)
239 For weights and widths, autoinst tries to the standard NFSS codes (ul,
241 el, l, sl, m, sb, b, eb and ub for weights; uc, ec, c, sc, m, sx, x, ex
242 and ux for widths) as much as possible. Of course, not all 81
243 combinations of these NFSS weights and widths will map to existing
244 fonts; and conversely it may not be possible to assign every existing
245 font a unique code in a sane way (especially for the weights, some font
246 families offer more variants than NFSS's codes can handle; e.g., Fira
247 Sans contains fifteen different weights!). Therefore every font is
248 also assigned a "series" name that is the concatenation of its weight
249 and width, after expanding any abbreviations and converting to
250 lowercase. A font of "Cond" width and "Ultra" weight will then be
251 known as "ultrablackcondensed".
252 The exact mapping between fonts and NFSS codes can be found in the
254 generated fd files and in the log file (you may want to run autoinst
255 with the -dryrun option to check the chosen mapping beforehand). The
256 -nfssweight and -nfsswidth command-line options can be used to finetune
257 the mapping between NFSS codes and fonts.
258 To access specific weights or widths, one can always use the
260 "\fontseries" command with the full series name (i.e.,
261 "\fontseries{demibold}\selectfont").
262 Ornaments
264 Ornament fonts are regular LY1-encoded fonts, with a number of
265 "regular" characters replaced by ornament glyphs. The OpenType
266 specification says that fonts should only put their ornaments in place
267 of the lowercase ASCII letters, but some fonts put them in other
268 positions (such as those of the digits) as well.
269 Ornaments can be accessed like "{\ornaments a}" and
271 "{\ornaments\char"61}", or equivalently "\textornaments{a}" and
272 "\textornaments{\char"61}". To see which ornaments a font contains
273 (and at which positions), run LaTeX on the file nfssfont.tex (which is
274 included in any standard LaTeX installation), supply the name of the
275 ornament font (i.e., "GaramondLibre-Regular-orn-u") and give the
276 command "\table\bye"; this will create a table of all glyphs in that
277 font.
278 Note that versions of autoinst up to 20200428 handled ornaments
280 differently, and fonts and style files generated by those versions are
281 not compatible with files generated by newer versions.
282
284 OpenType fonts and licensing issues
285 Since pdfTeX cannot subset otf-flavoured OpenType fonts, otftotfm will
286 convert such fonts to Type1 (pfb) format. However, many fonts (at
287 least those licensed under the SIL Open Font License) do not allow
288 distributing such converted versions under their original name.
289 To meet these licensing requirements, autoinst provides a -t1suffix
291 command-line option that appends a user-defined suffix to the names
292 (both the filename and the internal font name) of all generated Type1
293 fonts; see "COMMAND-LINE OPTIONS" below.
294 A note for MiKTeX users
296 Automatically installing the fonts into a suitable TEXMF tree (as
297 autoinst tries to do by default) only works for TeX-installations that
298 use the kpathsea library; with TeX distributions that implement their
299 own directory searching, such as MiKTeX, autoinst will complain that it
300 cannot find the kpsewhich program and move all generated files into a
301 subdirectory "autoinst_output/" of the current directory. If you use
302 such a TeX distribution, you should either move these files to their
303 correct destinations by hand, or use the -target option (see "COMMAND-
304 LINE OPTIONS" below) to manually specify a TEXMF tree.
305 Also, some OpenType fonts contain so many kerning pairs that the
307 resulting pl and vpl files are too big for MiKTeX's pltotf and vptovf;
308 the versions that come with W32TeX (http://www.w32tex.org) and TeXLive
309 (http://tug.org/texlive) don't seem to have this problem.
310 A note for MacTeX users
312 By default, autoinst will try to install all generated files into the
313 $TEXMFLOCAL tree; when this directory isn't user-writable, it will use
314 the $TEXMFHOME tree instead. Unfortunately, MacTeX's version of
315 "updmap-sys" doesn't search in $TEXMFHOME, and hence MacTeX will not
316 find the new fonts.
317 To remedy this, either run autoinst as root (so that it can install
319 everything into $TEXMFLOCAL) or manually run "updmap -user" to tell TeX
320 about the files in $TEXMFHOME. This latter option does, however, come
321 with some caveats; see https://tug.org/texlive/scripts-sys-user.html.
322
324 autoinst tries hard to do The Right Thing (TM) by default, so you
325 usually won't need these options; but most aspects of its operation can
326 be fine-tuned if you want to.
327 You may use either one or two dashes before options, and option names
329 may be shortened to a unique prefix (e.g., -encoding may be abbreviated
330 to -enc or even -en, but -e is ambiguous (it may mean either -encoding
331 or -extra)).
332 General options
334 -help
335 Print a (relatively) short help text and exit.
336 -dryrun
338 Don't generate output; just parse input fonts and write the results
339 to the log file.
340 -verbose
342 Add more details to the log file.
343 -version
345 Print autoinst's version number and exit.
346 Font creation options
348 -encoding=encoding[,encoding]
349 Generate the specified encoding(s) for the text fonts. Multiple
350 encodings may be specified as a comma-separated list (without
351 spaces!); the default choice of encodings is "OT1,LY1,T1".
352 For each encoding argument, autoinst will first check if it is the
354 filename of an encoding file, and if found it will use that;
355 otherwise the argument is assumed to be the name of one of the
356 built-in encodings. Currently autoinst comes with built-in support
357 for the OT1, T1/TS1, LY1, LGR, T2A/B/C and T3/TS3 encodings.
358 (These files are called fontools_ot1.enc etc. to avoid name clashes
359 with other packages; the fontools_ prefix may be omitted.)
360 -ts1/-nots1
362 Control the creation of TS1-encoded fonts. The default is -ts1 if
363 the text encodings (see -encoding above) include T1, -nots1
364 otherwise.
365 -lining/-nolining
367 Control the creation of fonts with lining figures. The default is
368 -lining.
369 -oldstyle/-nooldstyle
371 Control the creation of fonts with oldstyle figures. The default is
372 -oldstyle.
373 -proportional/-noproportional
375 Control the creation of fonts with proportional figures. The
376 default is -proportional.
377 -tabular/-notabular
379 Control the creation of fonts with tabular figures. The default is
380 -tabular.
381 -smallcaps/-nosmallcaps
383 Control the creation of small caps fonts. The default is
384 -smallcaps.
385 -swash/-noswash
387 Control the creation of swash fonts. The default is -swash.
388 -titling/-notitling
390 Control the creation of titling families. The default is -titling.
391 -superiors/-nosuperiors
393 Control the creation of fonts with superior characters. The
394 default is -superiors.
395 -inferiors [ = none | auto | subs | sinf | dnom ]
397 -noinferiors
398 The OpenType standard defines several kinds of digits that might be
399 used as inferiors or subscripts: "Subscripts" (OpenType feature
400 "subs"), "Scientific Inferiors" ("sinf"), and "Denominators"
401 ("dnom"). This option allows the user to determine which of these
402 styles autoinst should use for the inferior characters.
403 Alternatively, the value "auto" tells autoinst to use the first
404 value in "sinf", "subs" or "dnom" that is supported by the font.
405 Saying just -inferiors is equivalent to -inferiors=auto; otherwise
406 the default is -noinferiors.
407 If you specify a style of inferiors that isn't present in the font,
409 autoinst will fall back to its default behaviour of not creating
410 fonts with inferiors at all; it won't try to substitute one of the
411 other styles.
412 -fractions/-nofractions
414 Control the creation of fonts with numerators and denominators.
415 The default is -nofractions.
416 -ligatures/-noligatures
418 Some fonts contain glyphs for the standard f-ligatures (ff, fi, fl,
419 ffi, ffl), but don't provide a "liga" feature to access these.
420 This option tells autoinst to add extra "LIGKERN" rules to the
421 generated fonts to enable the use of these ligatures. The default
422 is -ligatures, except for typewriter fonts.
423 Specify -noligatures to disable generation of ligatures even for
425 fonts that do contain a "liga" feature.
426 -ornaments/-noornaments
428 Control the creation of ornament fonts. The default is -ornaments.
429 -serif/-sanserif/-typewriter
431 Install the font as a serif, sanserif or typewriter font,
432 respectively. This changes how you access the font in LaTeX: with
433 "\rmfamily"/"\textrm", "\sffamily"/"\textsf" or
434 "\ttfamily"/"\texttt".
435 Installing the font as a typewriter font will cause two further
437 changes: it will - by default - turn off the use of f-ligatures
438 (though this can be overridden with the -ligatures option), and it
439 will disable hyphenation for this font. This latter effect cannot
440 be re-enabled in autoinst; if you want typewriter text to be
441 hyphenated, use the hyphenat package.
442 If none of these options is specified, autoinst tries to guess: if
444 the font's filename contains the string "mono" or if the field
445 "isFixedPitch" in the font's "post" table is True, it will select
446 -typewriter; else if the filename contains "sans" it will select
447 -sanserif; otherwise it will opt for -serif.
448 -math
450 Tells autoinst to create basic math fonts (see above).
451 -mathspacing=amount
453 Letterspace each character in the math fonts by amount units, where
454 1000 units equal one em. In my opinion, many text fonts benefit
455 from letterspacing by 50 to 100 units when used in maths; some
456 fonts need even more. Use your own judgement!
457 Output options
459 -t1suffix [ = SUFFIX ]
460 Tell autoinst to modify the font names of all generated
461 Type1-fonts, by adding SUFFIX to the family name. If you use this
462 option without specifying a SUFFIX value, autoinst will use the
463 value "PS". The default behaviour when this option is not given is
464 to not modify font names at all.
465 See also "OpenType fonts and licensing issues" in "WARNINGS AND
467 CAVEATS" above.
468 -target=DIRECTORY
470 Install all generated files into the TEXMF tree at DIRECTORY.
471 By default, autoinst searches the $TEXMFLOCAL and $TEXMFHOME trees
473 and installs all files into the first user-writable TEXMF tree it
474 finds. If autoinst cannot find such a user-writable directory
475 (which shouldn't happen, since $TEXMFHOME is supposed to be user-
476 writable) it will print a warning message and put all files into
477 the subdirectory "autoinst_output/" of the current directory. It's
478 then up to the user to move the generated files to a better
479 location and update all relevant databases (usually by calling
480 texhash and updmap).
481 -vendor=VENDOR
483 -typeface=TYPEFACE
484 These options are equivalent to otftotfm's --vendor and
485 --typeface options: they change the "vendor" and "typeface" parts
486 of the names of the subdirectories in the TEXMF tree where
487 generated files will be stored. The default values are "lcdftools"
488 and the font's FontFamily name. These options change only
489 directory names, not the names of any generated files.
490 -logfile=filename
492 Write log data to filename instead of the default <fontfamily>.log.
493 If the file already exists, autoinst appends to it; it doesn't
494 overwrite an existing file.
495 Specialist options
497 -defaultlining/-defaultoldstyle
498 -defaulttabular/-defaultproportional
499 Tell autoinst which figure style is the current font family's
500 default (i.e., which figures you get when you don't specify any
501 OpenType features).
502 Don't use these options unless you are certain you need them! They
504 are only needed for fonts that don't provide OpenType features for
505 their default figure style; and even in that case, autoinst's
506 default values (-defaultlining and -defaulttabular) are usually
507 correct.
508 -nfssweight=code=weight
510 -nfsswidth=code=width
511 Map the NFSS code code to the given weight or width, overriding the
512 built-in tables. Each of these options may be given multiple
513 times, to override more than one NFSS code. Example: to map the
514 "ul" code to the "Thin" weight, use "-nfssweight=ul=thin". To
515 inhibit the use of the "ul" code completely, use "-nfssweight=ul=".
516 -extra=extra options
518 Pass extra options to the commands for otftotfm. To prevent extra
519 options from accidentily being interpreted as options to autoinst,
520 they should be properly quoted.
521 -nofigurekern
523 Some fonts provide kerning pairs for tabular figures. This is very
524 probably not what you want (e.g., numbers in tables won't line up
525 exactly). This option adds extra --ligkern options to the
526 commands for otftotfm to suppress such kerns. Note that this
527 option leads to very long commands (it adds one hundred --ligkern
528 options), which may cause problems on some systems; hence it is not
529 active by default.
530
532 Eddie Kohler's TypeTools and T1Utils (http://www.lcdf.org/type).
533 Perl can be obtained from http://www.perl.org; it is included in most
535 Linux distributions. For Windows, try ActivePerl
536 (http://www.activestate.com) or Strawberry Perl
537 (http://strawberryperl.com).
538 LuaTeX (http://www.luatex.org) and XeTeX (http://www.tug.org/xetex) are
540 Unicode-aware TeX engines that can use OpenType fonts directly, without
541 any (La)TeX-specific support files.
542 The FontPro project (https://github.com/sebschub/FontPro) offers very
544 complete LaTeX support (even for typesetting maths) for Adobe's Minion
545 Pro, Myriad Pro and Cronos Pro font families.
546
548 Marc Penninga (marcpenninga@gmail.com)
549 When sending a bug report, please give as much relevant information as
551 possible; this usually includes (but may not be limited to) the log
552 file (please add the -verbose command-line option, for extra info). If
553 you see any error messages, please include these verbatim; don't
554 paraphase.
555
557 Copyright (C) 2005-2021 Marc Penninga.
558
560 This program is free software; you can redistribute it and/or modify it
561 under the terms of the GNU General Public License as published by the
562 Free Software Foundation, either version 2 of the License, or (at your
563 option) any later version. A copy of the text of the GNU General
564 Public License is included in the fontools distribution; see the file
565 GPLv2.txt.
566
568 This program is distributed in the hope that it will be useful, but
569 WITHOUT ANY WARRANTY; without even the implied warranty of
570 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
571 General Public License for more details.
572
574 This document describes autoinst version 20210401.
575
577 (See the source for the full story, all the way back to 2005.)
578 2021-04-01 The -encoding option now also accepts filenames of encoding
580 files in directories other than the current directory.
581 Directory names containing spaces do (or at least should)
582 also work.
583 2020-12-18 Fixed a problem with files not being found on Windows.
585 Added extra "--unicoding" options to prevent getting
586 lowercase f-ligatures in smallcaps for some buggy fonts.
587 Optimized font info parsing for DTL and TypeBy font
588 families. Cleaned up the code for better maintainability.
589 2020-07-29 Some changes in the generated sty and fd files, to improve
591 compatibility with the microtype package. Made sure that
592 pfb fonts are always generated whenever the input fonts are
593 in otf format. Added the -t1suffix command-line option, to
594 modify the font and file names of those generated Type1
595 fonts.
596 2020-06-19 Added the "nomathgreek" option to generated style files.
598 Reorganized the generated style files to make them more
599 standards-conforming.
600 2020-05-27 Added basic (and still somewhat experimental) math support.
602 Implemented the "scale=MatchLowercase" option value in the
603 generated style files. "Wide" fonts are mapped to the "sx"
604 NFSS code instead of "x", to cater for League Mono
605 Variable's Wide and Extended widths. The generated style
606 files now use "\textsup" and "\textinf" instead of the more
607 cryptic "\textsu" and "\textin" to access superior and
608 inferior characters (though the old forms are retained for
609 backwards compatibility).
610 2020-05-11 When present, use encoding files in the current working
612 directory in preference of the ones that come with
613 autoinst. Changed the way ornament fonts are created;
614 ornament glyphs are now always included in the position
615 chosen by the font's designer.
616 2020-04-28 Fix a bug where the first font argument would be mistaken
618 for an argument to -inferiors.
619 2020-01-29 Don't create empty subdirectories in the target TEXMF tree.
621fontools 2021-04-01 AUTOINST(1)