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 [options] fontfile(s)
11
13 Eddie Kohler's LCDF TypeTools are superb tools for installing OpenType
14 fonts in LaTeX, but they can be hard to use: they need many, often
15 long, command lines and don't generate the fd and sty files LaTeX
16 needs. autoinst simplifies the use of the TypeTools for font
17 installation by generating and executing all commands for otftotfm and
18 by creating and installing all necessary fd and sty files.
19 Given a family of font files (in otf or ttf format), autoinst will
21 create several LaTeX font families:
22 - Four text families (with lining and oldstyle digits, each in both
24 tabular and proportional variants), all with the following shapes:
25 n Roman (i.e., upright) text
27 it, sl Italic and slanted (sometimes called oblique) text
29 sc Small caps
31 scit, scsl
33 Italic and slanted small caps
34 sw Swash
36 nw "Upright swash"
38 - For each T1-encoded text family: a family of TS1-encoded symbol
40 fonts, in roman, italic and slanted shapes.
41 - Families with superiors, inferiors, numerators and denominators,
43 in roman, italic and slanted shapes.
44 - Families with "Titling" characters; these "... replace the default
46 glyphs with corresponding forms designed specifically for titling.
47 These may be all-capital and/or larger on the body, and adjusted
48 for viewing at larger sizes" (according to the OpenType
49 Specification).
50 - An ornament family, also in roman, italic and slanted shapes.
52 Of course, if your fonts don't contain italics, oldstyle digits, small
54 caps etc., the corresponding shapes and families are not created. In
55 addition, the creation of most families and shapes can be controlled by
56 the user (see "COMMAND-LINE OPTIONS" below).
57 These families use the FontPro project's naming scheme:
59 <FontFamily>-<Suffix>, where <Suffix> is:
60 LF proportional (i.e., figures have varying widths) lining figures
62 TLF tabular (i.e., all figures have the same width) lining figures
64 OsF proportional oldstyle figures
66 TOsF tabular oldstyle figures
68 Sup superior characters (note that most fonts have only an
70 incomplete set of superior characters: digits, some punctuation
71 and the letters abdeilmnorst; normal forms are used for other
72 characters)
73 Inf inferior characters; usually only digits and some punctuation,
75 normal forms for other characters
76 Titl Titling characters; see above.
78 Orn ornaments
80 Numr numerators
82 Dnom denominators
84 The individual fonts are named <FontName>-<suffix>-<shape>-<enc>, where
86 <suffix> is the same as above (but in lowercase), <shape> is either
87 empty, "sc" or "swash", and <enc> is the encoding (also in lowercase).
88 A typical name in this scheme would be "FiraSans-Light-osf-sc-ly1".
89 About the log file
91 autoinst writes some info about what it thinks it's doing to a log
92 file. By default this is called <fontfamily>.log, but this choice can
93 be overridden by the user; see the -logfile command-line option in
94 "COMMAND-LINE OPTIONS" below. If this log file already exists,
95 autoinst will append its data to the end rather than overwrite it. Use
96 the -verbose command-line option to ask for more detailed info.
97 A note for MiKTeX users
99 Automatically installing the fonts into a suitable TEXMF tree (as
100 autoinst tries to do by default) only works for TeX-installations that
101 use the kpathsea library; with TeX distributions that implement their
102 own directory searching (such as MiKTeX), autoinst will complain that
103 it cannot find the kpsewhich program and move all generated files into
104 a subdirectory "./autoinst_output/" of the current directory. If you
105 use such a TeX distribution, you should either move these files to
106 their correct destinations by hand, or use the -target option (see
107 "COMMAND-LINE OPTIONS" below) to manually specify a TEXMF tree.
108 Also, some OpenType fonts contain so many kerning pairs that the
110 resulting pl and vpl files are too big for MiKTeX's pltotf and vptovf;
111 the versions that come with W32TeX (http://www.w32tex.org) and TeXLive
112 (http://tug.org/texlive) don't seem to have this problem.
113 A note for MacTeX users
115 By default, autoinst will try to install all files into the $TEXMFLOCAL
116 tree; when this directory isn't user-writable, it will use the
117 $TEXMFHOME tree instead. Unfortunately, MacTeX's version of
118 "updmap-sys" (which is called behind the scenes) doesn't search in
119 $TEXMFHOME, and hence MacTeX will not find the new fonts.
120 To remedy this, either run autoinst as root (so that it can install
122 everything into $TEXMFLOCAL) or manually run "updmap -user" to tell TeX
123 about the files in $TEXMFHOME. The latter option does, however, have
124 some caveats; see https://tug.org/texlive/scripts-sys-user.html.
125 Using the fonts in your LaTeX documents
127 autoinst generates a style file for using the fonts in LaTeX documents,
128 named <FontFamily>.sty. This style file also takes care of loading the
129 fontenc and textcomp packages. To use the fonts, add the command
130 "\usepackage{<FontFamily>}" to the preamble of your document.
131 This style file defines a number of options:
133 "lining", "oldstyle", "tabular", "proportional"
135 Choose which figure style to use. The defaults are "oldstyle" and
136 "proportional" (if available).
137 "scale=<number>"
139 Scale the font by a factor of <number>. E.g., to increase the size
140 of the font by 5%, use "\usepackage[scale=1.05]{<FontFamily>}".
141 May also be spelled "scaled".
142 This option is only available when you have the xkeyval package
144 installed.
145 "medium", "book", "text", "regular"
147 Select the weight that LaTeX will use as the "regular" weight; the
148 default is "regular".
149 "heavy", "black", "extrabold", "demibold", "semibold", "bold"
151 Select the weight that LaTeX will use as the "bold" weight; the
152 default is "bold".
153 The previous two groups of options will only work if you have the
155 mweights package installed.
156 The style file will also try to load the fontaxes package (available on
158 CTAN), which gives easy access to various font shapes and styles.
159 Using the machinery set up by fontaxes, the generated style file
160 defines a number of commands (which take the text to be typeset as
161 argument) and declarations (which don't take arguments, but affect all
162 text up to the end of the current group) to access titling, superior
163 and inferior characters:
164 DECLARATION COMMAND SHORT FORM OF COMMAND
166 \tlshape \texttitling \texttl
168 \sufigures \textsuperior \textsu
169 \infigures \textinferior \textin
170 In addition, the "\swshape" and "\textsw" commands are redefined to
172 place swash on fontaxes' secondary shape axis (fontaxes places it on
173 the primary shape axis) to make them behave properly when nested, so
174 that "\swshape\upshape" will give upright swash.
175 There are no commands for accessing the numerator and denominator
177 fonts; these can be selected using fontaxes' standard commands, e.g.,
178 "\fontfigurestyle{numerator}\selectfont".
179 The style file also provides a command "\ornament{<number>}", where
181 "<number>" is a number from 0 to the total number of ornaments minus
182 one. Ornaments are always typeset using the current family, series and
183 shape. A list of all ornaments in a font can be created by running
184 LaTeX on the file nfssfont.tex (part of a standard LaTeX installation)
185 and supplying the name of the ornament font.
186 To access ornament glyphs, autoinst creates a font-specific encoding
188 file <FontFamily>_orn.enc, but only if that file doesn't yet exist in
189 the current directory. This is a deliberate feature that allows you to
190 provide your own encoding vector, e.g. if your fonts use non-standard
191 glyph names for ornaments.
192 These commands are only generated for existing shapes and number
194 styles; no commands are generated for shapes and styles that don't
195 exist, or whose generation was turned off by the user. Also these
196 commands are built on top of fontaxes, so if that package cannot be
197 found, you're limited to using the lower-level commands from standard
198 NFSS ("\fontfamily", "\fontseries", "\fontshape" etc.).
199 On the choice of text encoding
201 By default, autoinst generates text fonts with OT1, T1 and LY1
202 encodings, and the generated style files use LY1 as the default text
203 encoding. LY1 has been chosen over T1 because it has some empty slots
204 to accommodate the additional ligatures found in many OpenType fonts.
205 Other encodings can be chosen using the -encoding option (see "COMMAND-
206 LINE OPTIONS" below).
207 NFSS codes
209 CAVEAT: this functionality was almost completely rewritten in release
210 2019-03-14. Older versions tried to map all fonts directly to short
211 NFSS codes, but often had to invent non-standard codes in order to deal
212 with the many different weights and widths that occur in the wild.
213 Such non-standard NFSS codes will no longer work for fonts installed
214 with newer versions; for those you'll have to either use the long names
215 or stick to the standard NFSS codes. (This change mainly concerns very
216 light or very heavy weights and very condensed widths; for more
217 moderate weights and widths, existing code will very probably continue
218 to work.)
219 LaTeX's New Font Selection System (NFSS) identifies fonts by a
221 combination of family, series (the concatenation of weight and width),
222 shape and size. autoinst parses the font's metadata (more precisely:
223 the output of "otfinfo --info") to determine these parameters. When
224 this fails (usually because the font family contains uncommon weights,
225 widths or shapes), autoinst ends up with different fonts having the
226 same values for these font parameters; such fonts cannot be used in
227 NFSS, since there's no way distinguish them. When autoinst detects
228 such a situation, it will print an error message and abort. If that
229 happens, either rerun autoinst on a smaller set of fonts, or add the
230 missing widths, weights and shapes to the tables "NFSS_WIDTH",
231 "NFSS_WEIGHT" and "NFSS_SHAPE", near the top of the source code.
232 Please also send a bug report (see AUTHOR below).
233 The mapping of shapes to NFSS codes is done using the following table:
235 SHAPE CODE
237 -------------------------------- ----
238 Roman, Upright n
239 Italic, Cursive, Kursive it
240 Oblique, Slant(ed), Incline(d) sl
241 (Exception: Adobe Silentium Pro contains two Roman shapes; we map the
243 first of these to "n", for the second one we (ab)use the "it" code as
244 this family doesn't contain an Italic shape.)
245 The mapping of weights and widths to NFSS codes is a more complex, two-
247 step proces. In the first step, all fonts are assigned a "series" name
248 that is simply the concatenation of its weight and width (after
249 expanding any abbreviations and converting to lowercase). A font with
250 "Cond" width and "Ultra" weight will then be known as
251 "ultrablackcondensed".
252 In the second step, autoinst tries to map all combinations of NFSS
254 codes (ul, el, l, sl, m, sb, b, eb and ub for weights; uc, ec, c, sc,
255 m, sx, x, ex and ux for widths) to actual fonts. Of course, not all 81
256 combinations of these NFSS weights and widths will map to existing
257 fonts; and conversely it may not be possible to assign every existing
258 font a unique code in a sane way (especially on the weight axis, some
259 font families offer more choices or finer granularity than NFSS's codes
260 can handle; e.g., Fira Sans contains fifteen(!) different weights,
261 including an additional "Medium" weight between Regular and Semibold).
262 autoinst tries hard to ensure that the most common NFSS codes (and
264 high-level commands such as "\bfseries", which are built on top of
265 those codes) will "just work".
266 To see exactly which NFSS codes map to which fonts, see the log file
268 (pro tip: run autoinst with the -dryrun option to check the chosen
269 mapping beforehand). The -nfssweight and -nfsswidth command-line
270 options can be used to finetune the mapping between NFSS codes and
271 fonts.
272 To access specific weights or widths, one can always use the
274 "\fontseries" command with the full series name (i.e.,
275 "\fontseries{demibold}\selectfont").
276
278 autoinst tries hard to do The Right Thing (TM) by default, so you
279 usually won't really need these options; but most aspects of its
280 operation can be fine-tuned if you want to.
281 You may use either one or two dashes before options, and option names
283 may be shortened to a unique prefix (e.g., -encoding may be abbreviated
284 to -enc or even -en, but -e is ambiguous (it may mean either -encoding
285 or -extra)).
286 -dryrun
288 Don't generate output; just parse input fonts and write a log file
289 saying what it would have done.
290 -logfile=filename
292 Write log data to filename instead of the default <fontfamily>.log.
293 If the file already exist, autoinst appends to it; it doesn't
294 overwrite an existing file.
295 -verbose
297 Add more details to the log file. Repeat this option for even more
298 info.
299 -encoding=encoding[,encoding]
301 Generate the specified encoding(s) for the text fonts. Multiple
302 encodings may be specified as a comma-separated list:
303 "-encoding=OT1,T1,LY1" (without spaces!). The style file passes
304 these to fontenc in the specified order, so the last one will
305 become the default text encoding of your document.
306 The default choice of encodings is "OT1,T1,LY1". For each
308 encoding, a file <encoding>.enc (in all lowercase!) should be
309 somewhere where otftotfm can find it. Suitable encoding files for
310 OT1, T1/TS1, LY1, LGR and T2A/B/C come with autoinst. (These files
311 are called fontools_ot1.enc etc. to avoid name clashes with other
312 packages; the "fontools_" prefix may be omitted.)
313 -ts1 / -nots1
315 Control the creation of TS1-encoded fonts. The default is -ts1 if
316 the text encodings (see -encoding above) include T1, -nots1
317 otherwise.
318 -serif, -sanserif, -typewriter
320 Install the font as a serif, sanserif or typewriter font,
321 respectively. This changes how you access the font in LaTeX: with
322 "\rmfamily"/"\textrm", "\sffamily"/"\textsf" or
323 "\ttfamily"/"\texttt". The generated style file redefines
324 "\familydefault", so including it will still make this font the
325 default text font.
326 -lining / -nolining
328 Control the creation of fonts with lining figures. The default is
329 -lining.
330 -oldstyle / -nooldstyle
332 Control the creation of fonts with oldstyle figures. The default is
333 -oldstyle.
334 -proportional / -noproportional
336 Control the creation of fonts with proportional figures. The
337 default is -proportional.
338 -tabular / -notabular
340 Control the creation of fonts with tabular figures. The default is
341 -tabular.
342 -smallcaps / -nosmallcaps
344 Control the creation of small caps fonts. The default is
345 -smallcaps.
346 -swash / -noswash
348 Control the creation of swash fonts. The default is -swash.
349 -titling / -notitling
351 Control the creation of titling families. The default is -titling.
352 -superiors / -nosuperiors
354 Control the creation of fonts with superior characters. The
355 default is -superiors.
356 -inferiors=[ none | auto | subs | sinf | dnom ]
358 The OpenType standard defines several kinds of digits that might be
359 used as inferiors or subscripts: "Subscripts" (OpenType feature
360 "subs"), "Scientific Inferiors" ("sinf"), and "Denominators"
361 ("dnom"). This option allows the user to determine which of these
362 styles autoinst should use for the inferior characters.
363 Alternatively, the value "auto" tells autoinst to use the first
364 value in the list "subs", "sinf" or "dnom" that is supported by the
365 fonts. The default value is "none".
366 If you specify a style of inferiors that isn't present in the font,
368 autoinst will fall back to its default behaviour of not creating
369 fonts with inferiors at all; it won't try to substitute one of the
370 other styles.
371 -fractions / -nofractions
373 Control the creation of fonts with numerators and denominators.
374 The default is -nofractions.
375 -ligatures / -noligatures
377 Some fonts create glyphs for the standard f-ligatures (ff, fi, fl,
378 ffi, ffl), but don't provide a "liga" feature to access these.
379 This option tells autoinst to add extra "LIGKERN" rules to the
380 generated fonts to enable the use of these ligatures. The default
381 is -ligatures, unless the user specified the ligatures option.
382 Specify -noligatures to disable the generation of ligatures even
384 for fonts that do contain a "liga" feature.
385 -defaultlining / -defaultoldstyle
387 -defaulttabular / -defaultproportional
388 Tell autoinst which figure style is the current font family's
389 default (i.e., which figures you get when you don't specify any
390 OpenType features).
391 Don't use these options unless you are certain you need them! They
393 are only needed for fonts that don't provide OpenType features for
394 their default figure style; and even in that case, autoinst's
395 default values (-defaultlining and -defaulttabular) are usually
396 correct.
397 -nofigurekern
399 Some fonts provide kerning pairs for tabular figures. This is very
400 probably not what you want (e.g., numbers in tables won't line up
401 exactly). This option adds extra --ligkern options to the
402 commands for otftotfm to suppress such kerns. Note that this
403 option leads to very long commands (it adds one hundred --ligkern
404 options), which may cause problems on some systems.
405 -mergewidths / -nomergewidths
407 Some font families put their Condensed, Narrow, Extended etc.
408 widths in separate families; this option tells autoinst to merge
409 those separate families into the main family. The default is
410 -mergewidths.
411 -mergesmallcaps / -nomergesmallcaps
413 Even more annoyingly, some font families put their small caps fonts
414 in a separate family; this option tells autoinst to merge the small
415 caps fonts into the main family. The default is -mergesmallcaps.
416 -nfssweight=code=weight, -nfsswidth=code=width
418 Map the NFSS code code to the given weight or width, overriding the
419 built-in tables. Each of these options may be given multiple
420 times, to override more than one NFSS code. Example: to map the
421 "ul" code to the "Thin" weight, use "-nfssweight=ul=thin". To
422 inhibit the use of the "ul" code completely, use "-nfssweight=ul=".
423 -extra=text
425 Append text as extra options to the command lines for otftotfm. To
426 prevent text from accidentily being interpreted as options to
427 autoinst, it should be properly quoted.
428 -manual
430 Manual mode; for users who want to post-process the generated files
431 and commands. By default, autoinst immediately executes all
432 otftotfm commands it generates; in manual mode, these are instead
433 written to a file autoinst.bat. Furthermore it tells otftotfm to
434 generate human readable (and editable) pl/vpl files instead of the
435 default tfm/vf ones, and to place all generated files in a
436 subdirectory "./autoinst_output/" of the current directory, rather
437 than install them into your TeX installation.
438 When using this option, you need to execute the following manual
440 steps after autoinst has finished:
441 - run pltotf and vptovf on the generated pl and vf files, to
443 convert them to tfm/vf format;
444 - move all generated files to a proper TEXMF tree, and, if
445 necessary, update the filename database;
446 - tell TeX about the new map file (usually by running "updmap" or
447 similar).
448 Note that some options (-target, -vendor and -typeface,
450 -[no]updmap) are meaningless, and hence ignored, in manual mode.
451 -target=DIRECTORY
453 Install all generated files into the TEXMF tree at DIRECTORY.
454 By default, autoinst searches the $TEXMFLOCAL and $TEXMFHOME trees
456 and installs all files into the first user-writable TEXMF tree it
457 finds. If autoinst cannot find such a user-writable directory
458 (which shouldn't happen, since $TEXMFHOME is supposed to be user-
459 writable) it will print a warning message and put all files into
460 the subdirectory "./autoinst_output/" of the current directory.
461 It's then up to the user to move the generated files to a better
462 location and update all relevant databases (usually by calling
463 texhash and updmap).
464 -vendor=VENDOR
466 -typeface=TYPEFACE
467 These options are equivalent to otftotfm's --vendor and
468 --typeface options: they change the "vendor" and "typeface" parts
469 of the names of the subdirectories in the TEXMF tree where
470 generated files will be stored. The default values are "lcdftools"
471 and the font's FontFamily name.
472 Note that these options change only directory names, not the names
474 of any generated files.
475 -updmap / -noupdmap
477 Control whether or not updmap is called after the last call to
478 otftotfm. The default is -updmap.
479
481 Eddie Kohler's TypeTools (http://www.lcdf.org/type).
482 Perl can be obtained from http://www.perl.org; it is included in most
484 Linux distributions. For Windows, try ActivePerl
485 (http://www.activestate.com) or Strawberry Perl
486 (http://strawberryperl.com).
487 XeTeX (http://www.tug.org/xetex) and LuaTeX (http://www.luatex.org) are
489 Unicode-aware TeX engines that can use OpenType fonts directly, without
490 any (La)TeX-specific support files.
491 The FontPro project (https://github.com/sebschub/FontPro) offers very
493 complete LaTeX support (even for typesetting maths) for Adobe's Minion
494 Pro, Myriad Pro and Cronos Pro font families.
495
497 Marc Penninga (marcpenninga@gmail.com)
498 When sending a bug report, please give as much relevant information as
500 possible; this usually includes (but may not be limited to) the log
501 file (please add the -verbose command-line option, for extra info). If
502 you see any error messages, please include these verbatim; don't
503 paraphase.
504
506 Copyright (C) 2005-2019 Marc Penninga.
507
509 This program is free software; you can redistribute it and/or modify it
510 under the terms of the GNU General Public License as published by the
511 Free Software Foundation, either version 2 of the License, or (at your
512 option) any later version. A copy of the text of the GNU General
513 Public License is included in the fontools distribution; see the file
514 GPLv2.txt.
515
517 This program is distributed in the hope that it will be useful, but
518 WITHOUT ANY WARRANTY; without even the implied warranty of
519 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
520 General Public License for more details.
521
523 (See the source for the full story, all the way back to 2005.)
524 2019-05-17 Changed the way the -ligatures option works: -ligatures
526 enables f-ligatures (even without a "liga" feature),
527 -noligatures now disables f-ligatures (overriding a "liga"
528 feature).
529 2019-05-11 Separate small caps families are now also recognised when
531 the family name ends with "SC" (previously autoinst only
532 looked for "SmallCaps").
533 2019-04-22 Fixed a bug in the generation of swash shapes.
535 2019-04-19 Fixed a bug that affected -mergesmallcaps with multiple
537 encodings.
538 2019-04-16 Added the <-mergesmallcaps> option, to handle cases where
540 the small caps fonts are in separate font families.
541 Titling shape is now treated as a separate family instead
542 of a distinct shape; it is generated only for fonts with
543 the 'titl' feature. Only add f-ligatures to fonts when
544 explicitly asked to (-ligatures).
545 2019-04-11 Tried to make the log file more relevant. Added the
547 -nfssweight and -nfsswidth options, and finetuned the
548 automatic mapping between fonts and NFSS codes. Changed
549 the name of the generated log file to <fontfamily>.log, and
550 revived the -logfile option to allow overriding this
551 choice. Made -mergewidths the default (instead of
552 -nomergewidths).
553 2019-04-01 Fine-tuned the decision where to put generated files; in
555 particular, create $TEXMFHOME if it doesn't already exist
556 and $TEXMFLOCAL isn't user-writable.
557 In manual mode, or when we can't find a user-writable TEXMF
559 tree, put all generated files into a subdirectory
560 "./autoinst_output/" instead of all over the current
561 working directory.
562 Added "auto" value to the inferiors option, to tell
564 autoinst to use whatever inferior characters are available.
565 2019-03-14 (never released to CTAN)
567 Overhauled the mapping of fonts (more specifically of
569 weights and widths; the mapping of shapes didn't change) to
570 NFSS codes. Instead of inventing our own codes to deal
571 with every possible weight and width out there, we now
572 create "long" codes based on the names in the font
573 metadata. Then we add "ssub" rules to the fd files to map
574 the standard NFSS codes to our fancy names (see the section
575 NFSS codes; based on discussions with Frank Mittelbach and
576 Bob Tennent).
577 2018-08-10 Added encoding files for LGR and T2A/B/C to fontools.
579 2018-03-26 Added the -(no)mergewidths option; tried to improve the
581 documentation.
582fontools 2019-05-17 AUTOINST(1)