From d95ea697818d6c0c24ab06975ddde399d701eb96 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Mon, 1 Apr 2019 21:07:53 +0000 Subject: fontools (1apr19) git-svn-id: svn://tug.org/texlive/trunk@50695 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/man/man1/autoinst.1 | 439 +++++++++++++++++------------- 1 file changed, 245 insertions(+), 194 deletions(-) (limited to 'Master/texmf-dist/doc/man/man1/autoinst.1') diff --git a/Master/texmf-dist/doc/man/man1/autoinst.1 b/Master/texmf-dist/doc/man/man1/autoinst.1 index f559fb74845..b00c7c897f3 100644 --- a/Master/texmf-dist/doc/man/man1/autoinst.1 +++ b/Master/texmf-dist/doc/man/man1/autoinst.1 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) +.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== @@ -54,16 +54,20 @@ .\" Avoid warning from groff about undefined register 'F'. .de IX .. -.if !\nF .nr F 0 -.if \nF>0 \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" .. -. if !\nF==2 \{\ -. nr % 0 -. nr F 2 +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} . \} .\} +.rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. @@ -129,7 +133,7 @@ .\" ======================================================================== .\" .IX Title "AUTOINST 1" -.TH AUTOINST 1 "2018-08-10" "fontools" "Marc Penninga" +.TH AUTOINST 1 "2019-04-01" "fontools" "Marc Penninga" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -142,9 +146,9 @@ for installing and using OpenType fonts in (La)TeX. \&\fBautoinst\fR [\fIoptions\fR] \fBfontfile(s)\fR .SH "DESCRIPTION" .IX Header "DESCRIPTION" -Eddie Kohler's \fI\s-1LCDF\s0 TypeTools\fR are superb tools for installing -OpenType fonts in LaTeX, but they can be hard to use: -they need many, often long, command lines +Eddie Kohler's \fI\s-1LCDF\s0 TypeTools\fR are superb tools for installing +OpenType fonts in LaTeX, but they can be hard to use: +they need many, often long, command lines and don't generate the \fIfd\fR and \fIsty\fR files LaTeX needs. \&\fBautoinst\fR simplifies the use of the \fITypeTools\fR for font installation by generating and executing all commands for \fIotftotfm\fR @@ -172,16 +176,16 @@ Small caps Swash .IP "\fItl\fR" 8 .IX Item "tl" -Titling shape. Meant for all-caps text; letterspacing and the positioning of +Titling shape. Meant for all-caps text; letterspacing and the positioning of punctuation characters have been adjusted to suit all-caps text. -(This shape is only generated for the families with lining digits, +(This shape is only generated for the families with lining digits, since old-style digits make no sense with all-caps text.) .IP "\fIscit\fR, \fIscsl\fR" 8 .IX Item "scit, scsl" Italic and slanted small caps .IP "\fInw\fR" 8 .IX Item "nw" -\&\*(L"Upright swash\*(R"; usually roman text with a few \*(L"oldstyle\*(R" ligatures +\&\*(L"Upright swash\*(R"; usually roman text with a few \*(L"oldstyle\*(R" ligatures like ct, sp and st. .IP "\fItlit\fR, \fItlsl\fR" 8 .IX Item "tlit, tlsl" @@ -204,12 +208,12 @@ An ornament family, also in roman, italic and slanted shapes. .RS 2 .RE .PP -Of course, if your fonts don't contain italics, oldstyle digits, small caps +Of course, if your fonts don't contain italics, oldstyle digits, small caps etc., the corresponding shapes and families are not created. -In addition, the creation of most families and shapes can be controlled +In addition, the creation of most families and shapes can be controlled by the user (see \*(L"COMMAND-LINE \s-1OPTIONS\*(R"\s0 below). .PP -These families use the \fIFontPro\fR project's naming scheme: +These families use the \fIFontPro\fR project's naming scheme: \&\fI\-\fR, where \fI\fR is: .IP "\fI\s-1LF\s0\fR" 8 .IX Item "LF" @@ -225,7 +229,7 @@ proportional oldstyle figures tabular oldstyle figures .IP "\fISup\fR" 8 .IX Item "Sup" -superior characters (note that most fonts have only an incomplete set of +superior characters (note that most fonts have only an incomplete set of superior characters: digits, some punctuation and the letters \fIabdeilmnorst\fR; normal forms are used for other characters) .IP "\fIInf\fR" 8 @@ -247,14 +251,35 @@ where \fI\fR is the same as above (but in lowercase), \&\fI\fR is either empty, \*(L"sc\*(R", \*(L"swash\*(R" or \*(L"titling\*(R", and \fI\fR is the encoding (also in lowercase). A typical name in this scheme would be \*(L"FiraSans\-Light\-osf\-sc\-ly1\*(R". -.SS "On the choice of text encoding" -.IX Subsection "On the choice of text encoding" -By default, \fBautoinst\fR generates text fonts with \s-1OT1, T1\s0 and \s-1LY1\s0 -encodings, and the generated style files use \s-1LY1\s0 as the default text encoding. -\&\s-1LY1\s0 has been chosen over T1 because it has some empty slots to accommodate -the additional ligatures found in many OpenType fonts. -Other encodings can be chosen using the \fI\-encoding\fR option -(see \*(L"COMMAND-LINE \s-1OPTIONS\*(R"\s0 below). +.SS "A note for MiKTeX users" +.IX Subsection "A note for MiKTeX users" +Automatically installing the fonts into a suitable \s-1TEXMF\s0 tree +(as \fBautoinst\fR tries to do by default) only works for TeX-installations that use +the \fIkpathsea\fR library; with TeX distributions that implement their +own directory searching (such as MiKTeX), \fBautoinst\fR will complain that +it cannot find the \fIkpsewhich\fR program and move all generated files +into a subdirectory \f(CW\*(C`./autoinst_output/\*(C'\fR of the current directory. +If you use such a TeX distribution, you should either move these files +to their correct destinations by hand, or use the \fI\-target\fR option +(see \*(L"COMMAND-LINE \s-1OPTIONS\*(R"\s0 below) to manually specify a \s-1TEXMF\s0 tree. +.PP +Also, some OpenType fonts contain so many kerning pairs that the resulting +\&\fIpl\fR and \fIvpl\fR files are too big for MiKTeX's \fIpltotf\fR and \fIvptovf\fR; +the versions that come with W32TeX (\fIhttp://www.w32tex.org\fR) +and TeXLive (\fIhttp://tug.org/texlive\fR) don't seem to have this problem. +.SS "A note for MacTeX users" +.IX Subsection "A note for MacTeX users" +By default, \fBautoinst\fR will try to install all files into the \f(CW$TEXMFLOCAL\fR tree; +when this directory isn't user-writable, it will use the \f(CW$TEXMFHOME\fR tree instead. +Unfortunately, MacTeX's version of \f(CW\*(C`updmap\-sys\*(C'\fR +(which is called behind the scenes) doesn't search in \f(CW$TEXMFHOME\fR, +and hence MacTeX will not find the new fonts. +.PP +To remedy this, either run \fBautoinst\fR as root (so that it can install +everything into \f(CW$TEXMFLOCAL\fR) or manually run \f(CW\*(C`updmap \-user\*(C'\fR to tell +TeX about the files in \f(CW$TEXMFHOME\fR. +The latter option does, however, have some caveats; +see \fIhttps://tug.org/texlive/scripts\-sys\-user.html\fR. .SS "Using the fonts in your LaTeX documents" .IX Subsection "Using the fonts in your LaTeX documents" \&\fBautoinst\fR generates a style file for using the fonts in LaTeX documents, @@ -267,37 +292,37 @@ This style file defines a number of options: .ie n .IP """lining"", ""oldstyle"", ""tabular"", ""proportional""" 4 .el .IP "\f(CWlining\fR, \f(CWoldstyle\fR, \f(CWtabular\fR, \f(CWproportional\fR" 4 .IX Item "lining, oldstyle, tabular, proportional" -Choose which figure style to use. +Choose which figure style to use. The defaults are \*(L"oldstyle\*(R" and \*(L"proportional\*(R" (if available). .ie n .IP """scale=\fI\fP""" 4 .el .IP "\f(CWscale=\f(CI\f(CW\fR" 4 .IX Item "scale=" Scale the font by a factor of \fI\fR. -E.g., to increase the size of the font by 5%, use -\&\f(CW\*(C`\eusepackage[scale=1.05]{\f(CI\f(CW}\*(C'\fR. +E.g., to increase the size of the font by 5%, use +\&\f(CW\*(C`\eusepackage[scale=1.05]{\f(CI\f(CW}\*(C'\fR. May also be spelled \f(CW\*(C`scaled\*(C'\fR. .Sp This option is only available when you have the \fIxkeyval\fR package installed. -.ie n .IP """light"", ""medium"", ""book"", ""text"", ""regular""" 4 -.el .IP "\f(CWlight\fR, \f(CWmedium\fR, \f(CWbook\fR, \f(CWtext\fR, \f(CWregular\fR" 4 -.IX Item "light, medium, book, text, regular" -Select the weight that LaTeX will use as the \*(L"regular\*(R" weight; +.ie n .IP """medium"", ""book"", ""text"", ""regular""" 4 +.el .IP "\f(CWmedium\fR, \f(CWbook\fR, \f(CWtext\fR, \f(CWregular\fR" 4 +.IX Item "medium, book, text, regular" +Select the weight that LaTeX will use as the \*(L"regular\*(R" weight; the default is \f(CW\*(C`regular\*(C'\fR. -.ie n .IP """heavy"", ""ultrablack"", ""extrablack"", ""black"", ""ultrabold"", ""extrabold"", ""demibold"", ""semibold"", ""bold""" 4 -.el .IP "\f(CWheavy\fR, \f(CWultrablack\fR, \f(CWextrablack\fR, \f(CWblack\fR, \f(CWultrabold\fR, \f(CWextrabold\fR, \f(CWdemibold\fR, \f(CWsemibold\fR, \f(CWbold\fR" 4 -.IX Item "heavy, ultrablack, extrablack, black, ultrabold, extrabold, demibold, semibold, bold" -Select the weight that LaTeX will use as the \*(L"bold\*(R" weight; +.ie n .IP """heavy"", ""black"", ""extrabold"", ""demibold"", ""semibold"", ""bold""" 4 +.el .IP "\f(CWheavy\fR, \f(CWblack\fR, \f(CWextrabold\fR, \f(CWdemibold\fR, \f(CWsemibold\fR, \f(CWbold\fR" 4 +.IX Item "heavy, black, extrabold, demibold, semibold, bold" +Select the weight that LaTeX will use as the \*(L"bold\*(R" weight; the default is \f(CW\*(C`bold\*(C'\fR. .PP The previous two groups of options will only work if you have the \fImweights\fR package installed. .PP -The style file will also try to load the \fIfontaxes\fR package +The style file will also try to load the \fIfontaxes\fR package (available on \s-1CTAN\s0), which gives easy access to various font shapes and styles. -Using the machinery set up by \fIfontaxes\fR, the generated style file +Using the machinery set up by \fIfontaxes\fR, the generated style file defines a number of commands (which take the text to be typeset as argument) and declarations (which don't take arguments, but affect all text up to -the end of the current group) to access titling, superior and inferior +the end of the current group) to access titling, superior and inferior characters: .PP .Vb 1 @@ -325,103 +350,111 @@ running LaTeX on the file \fInfssfont.tex\fR (part of a standard LaTeX installation) and supplying the name of the ornament font. .PP To access ornament glyphs, \fBautoinst\fR creates a font-specific encoding file -\&\fI_orn.enc\fR, +\&\fI_orn.enc\fR, but only if that file doesn't yet exist in the current directory. This is a deliberate feature that allows you to provide your own encoding vector, e.g. if your fonts use non-standard glyph names for ornaments. .PP These commands are only generated for existing shapes and number styles; -no commands are generated for shapes and styles that don't exist, +no commands are generated for shapes and styles that don't exist, or whose generation was turned off by the user. -Also these commands are built on top of \fIfontaxes\fR, so if that package -cannot be found, you're limited to using the lower-level commands from +Also these commands are built on top of \fIfontaxes\fR, so if that package +cannot be found, you're limited to using the lower-level commands from standard \s-1NFSS\s0 (\f(CW\*(C`\efontfamily\*(C'\fR, \f(CW\*(C`\efontseries\*(C'\fR, \f(CW\*(C`\efontshape\*(C'\fR etc.). +.SS "On the choice of text encoding" +.IX Subsection "On the choice of text encoding" +By default, \fBautoinst\fR generates text fonts with \s-1OT1, T1\s0 and \s-1LY1\s0 +encodings, and the generated style files use \s-1LY1\s0 as the default text encoding. +\&\s-1LY1\s0 has been chosen over T1 because it has some empty slots to accommodate +the additional ligatures found in many OpenType fonts. +Other encodings can be chosen using the \fI\-encoding\fR option +(see \*(L"COMMAND-LINE \s-1OPTIONS\*(R"\s0 below). .SS "\s-1NFSS\s0 codes" .IX Subsection "NFSS codes" -\&\s-1NFSS\s0 identifies fonts by a combination of family, series -(the concatenation of weight and width), shape and size. -\&\fBautoinst\fR parses the output of \f(CW\*(C`otfinfo \-\-info\*(C'\fR to determine -these parameters. When this fails -(e.g., because the font family contains uncommon widths or weights), -\&\fBautoinst\fR ends up with different fonts having the \fIsame\fR values -for these font parameters, and so cannot be used in \s-1NFSS.\s0 -In that case, \fBautoinst\fR will split the font family into multiple subfamilies -(based on each font file's \*(L"Subfamily\*(R" value) and try again. -(Since many font vendors misunderstand the \*(L"Subfamily\*(R" concept -and make each font file its own separate subfamily, -this strategy is only used as a last resort.) +\&\fI\f(BI\s-1CAVEAT\s0\fI: this functionality was almost completely rewritten in release 2019\-03\-14. +Older versions tried to map all fonts directly to short \s-1NFSS\s0 codes, +but often had to invent non-standard codes in order to deal with the +many different weights and widths that occur in the wild. +These non-standard \s-1NFSS\s0 codes used by older versions of \f(BIautoinst\fI will no longer +work for fonts installed with newer versions; for those you'll have to either +use the long names or stick to the standard \s-1NFSS\s0 codes. +This change mainly concerns very light or very heavy weights and very condensed widths; +for more moderate weights and widths, existing code will very probably continue to work.\fR .PP -If a proliferation of font families is unwanted, either run \fBautoinst\fR -on a smaller set of fonts or add the missing widths, weights and shapes to -the tables \f(CW%FD_WIDTH\fR, \f(CW%FD_WEIGHT\fR and \f(CW%FD_SHAPE\fR, at the beginning -of the source code. Please also send a bug report (see \s-1AUTHOR\s0 below). +LaTeX's New Font Selection System (\s-1NFSS\s0) +identifies fonts by a combination of family, +series (the concatenation of weight and width), shape and size. +\&\fBautoinst\fR parses the font's metadata (more precisely: the output of \f(CW\*(C`otfinfo \-\-info\*(C'\fR) +to determine these parameters. +When this fails (usually because the font family contains uncommon weights, widths +or shapes), +\&\fBautoinst\fR ends up with different fonts having the \fIsame\fR values +for these font parameters; such fonts cannot be used in \s-1NFSS,\s0 +since there's no way distinguish them. +When \fBautoinst\fR detects such a situation, it will print an error message and abort. +If that happens, either rerun \fBautoinst\fR on a smaller set of fonts, +or add the missing widths, weights and shapes to the tables \f(CW%NFSS_WIDTH\fR, +\&\f(CW%NFSS_WEIGHT\fR and \f(CW%NFSS_SHAPE\fR, near the top of the source code. +Please also send a bug report (see \s-1AUTHOR\s0 below). .PP -\&\fBautoinst\fR maps widths, weights and shapes to \s-1NFSS\s0 codes using -the following tables. These are based on the standard \fIFontname\fR scheme -and Philipp Lehman's \fIFont Installation Guide\fR, but some changes had to be made -to avoid name clashes in font families with many widths and weights, -such as Helvetica Neue and Fira Sans. +The mapping of shapes to \s-1NFSS\s0 codes is done using the following table: .PP -.Vb 10 -\& WEIGHT WIDTH -\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -\& Two 2 Ultra Compressed up -\& Four 4 Extra Compressed ep -\& Eight 8 Compressed p -\& Hair a Compact p -\& Thin i Ultra Condensed uc -\& Ultra Light ul Extra Condensed ec -\& Extra Light el Condensed c -\& Light l Narrow n -\& Regular \- [1] Semicondensed sc -\& Text t [2] Regular \- [1] -\& Book o [2] Semiextended sx -\& Medium mb Extended x -\& Demibold db Expanded e -\& Semibold sb Wide w -\& Bold b -\& Extra Bold eb SHAPE -\& Ultra (Bold) ub \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -\& Black k Roman, Upright n [3] -\& Extra Black ek Italic, Cursive, -\& Ultra Black uk Kursiv it -\& Heavy h Oblique, Slanted, -\& Poster r Incline(d) sl +.Vb 5 +\& SHAPE CODE +\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\- +\& Roman, Upright n +\& Italic, Cursive, Kursive it +\& Oblique, Slant(ed), Incline(d) sl .Ve -.IP "[1]" 4 -.IX Item "[1]" -When \fIboth\fR weight and width are empty, the \s-1NFSS\s0 \*(L"series\*(R" attribute becomes \*(L"m\*(R". -.IP "[2]" 4 -.IX Item "[2]" -Until release 2017\-06\-16, \*(L"Text\*(R" and \*(L"Book\*(R" were treated as synonyms for -\&\*(L"Regular\*(R". As there are some font families (\s-1IBM\s0 Plex, Fira Sans) that contain -separate \*(L"Text\*(R" and \*(L"Book\*(R" weights in addition to \*(L"Regular\*(R" ones, -I decided to give them their own codes. -When there is no \*(L"Regular\*(R" weight, \fBautoinst\fR will generate \fIssub\fR rules -to substitute \*(L"Text\*(R" or \*(L"Book\*(R" (in that order) in its place. -.IP "[3]" 4 -.IX Item "[3]" -Adobe Silentium Pro contains two roman shapes; -\&\*(L"Roman I\*(R" is mapped to \*(L"n\*(R", \*(L"Roman \s-1II\*(R"\s0 to \*(L"it\*(R". -.SS "A note for MiKTeX users" -.IX Subsection "A note for MiKTeX users" -Automatically installing the fonts into a suitable \s-1TEXMF\s0 tree -(as \fBautoinst\fR tries to do by default) requires a TeX-installation that uses -the \fIkpathsea\fR library; with TeX distributions that implement their -own directory searching (such as MiKTeX), \fBautoinst\fR will complain that -it cannot find the \fIkpsewhich\fR program and install all generated files -into subdirectories of the current directory. -If you use such a TeX distribution, you should either move these files -to their correct destinations by hand, or use the \fI\-target\fR option -(see \*(L"COMMAND-LINE \s-1OPTIONS\*(R"\s0 below) to specify a \s-1TEXMF\s0 tree. .PP -Also, some OpenType fonts may lead to \fIpl\fR and \fIvpl\fR files that -are too big for MiKTeX's \fIpltotf\fR and \fIvptovf\fR; -the versions that come with W32TeX (\fIhttp://www.w32tex.org\fR) -and TeXLive (\fIhttp://tug.org/texlive\fR) don't seem to have this problem. +(\fIException:\fR Adobe Silentium Pro contains two Roman shapes; we map the first of these +to \*(L"n\*(R", for the second one we [ab]use the \*(L"it\*(R" code as this family doesn't contain +an Italic shape.) +.PP +The mapping of weights and widths to \s-1NFSS\s0 code is a more complex, two-step proces. +In the first step, all fonts are assigned a \*(L"series\*(R" name that is simply +the concatenation of its full weight and width (after expanding any abbreviations +and converting to lowercase). +So a font with \*(L"Cond\*(R" width and \*(L"Ultra\*(R" weight will be known as \*(L"ultrablackcondensed\*(R". +.PP +In the second step, \fBautoinst\fR tries to map all combinations of \s-1NFSS\s0 codes +(ul, el, l, sl, m, sb, b, eb and ub for weights; +uc, ec, c, sc, m, sx, x, ex and ux for widths) to actual fonts. +Of course, not all 81 combinations of these \s-1NFSS\s0 weights and widths will map to +existing fonts; and conversely it may not be possible to assign every existing font +a unique code in a sane way (especially on the weight axis, some font families +offer more choices or finer granularity than \s-1NFSS\s0's codes can handle; +e.g., Fira Sans contains fifteen(!) different weights, +including an additional \*(L"Medium\*(R" weight between Regular and Semibold). +.PP +This mapping between \s-1NFSS\s0 codes and actual fonts is based on a few principles: +.IP "\fBUsefulness\fR. As many of the most commonly used \s-1NFSS\s0 codes as possible should point to actual fonts." 4 +.IX Item "Usefulness. As many of the most commonly used NFSS codes as possible should point to actual fonts." +.PD 0 +.ie n .IP "\fBExactness\fR. Exact matches always win: if the font family contains a Semibold Condensed font, that's what the ""sbc"" code will map to." 4 +.el .IP "\fBExactness\fR. Exact matches always win: if the font family contains a Semibold Condensed font, that's what the ``sbc'' code will map to." 4 +.IX Item "Exactness. Exact matches always win: if the font family contains a Semibold Condensed font, that's what the sbc code will map to." +.ie n .IP "\fBSanity\fR. A code like ""sb"" will always map to something semi-boldish. If there's no Semibold font it might map to Demibold or Medium, but never to Black. If there is no close match, the \s-1NFSS\s0 code will simply not be used." 4 +.el .IP "\fBSanity\fR. A code like ``sb'' will always map to something semi-boldish. If there's no Semibold font it might map to Demibold or Medium, but never to Black. If there is no close match, the \s-1NFSS\s0 code will simply not be used." 4 +.IX Item "Sanity. A code like sb will always map to something semi-boldish. If there's no Semibold font it might map to Demibold or Medium, but never to Black. If there is no close match, the NFSS code will simply not be used." +.ie n .IP "\fBWell-ordering\fR. The mapping respects the ordering that is inherent in the \s-1NFSS\s0 codes, so ""sb"" will be heavier than ""m"" and lighter than ""b""." 4 +.el .IP "\fBWell-ordering\fR. The mapping respects the ordering that is inherent in the \s-1NFSS\s0 codes, so ``sb'' will be heavier than ``m'' and lighter than ``b''." 4 +.IX Item "Well-ordering. The mapping respects the ordering that is inherent in the NFSS codes, so sb will be heavier than m and lighter than b." +.ie n .IP "\fBUniqueness\fR. No two \s-1NFSS\s0 codes will map to the same font (with the exception of ""bx""; since this is so ubiquitous in Latex, \fBautoinst\fR will treat it as a synonym for ""b"" if there is no BoldExtended font)." 4 +.el .IP "\fBUniqueness\fR. No two \s-1NFSS\s0 codes will map to the same font (with the exception of ``bx''; since this is so ubiquitous in Latex, \fBautoinst\fR will treat it as a synonym for ``b'' if there is no BoldExtended font)." 4 +.IX Item "Uniqueness. No two NFSS codes will map to the same font (with the exception of bx; since this is so ubiquitous in Latex, autoinst will treat it as a synonym for b if there is no BoldExtended font)." +.PD +.PP +These rules should ensure that the standard \s-1NFSS\s0 codes (and high-level commands +such as \f(CW\*(C`\ebfseries\*(C'\fR, which are built on top of these codes) will \*(L"just work\*(R". +To access specific weights or widths, use the \f(CW\*(C`\efontseries\*(C'\fR command with +the full series name (i.e., \f(CW\*(C`\efontseries{demibold}\eselectfont\*(C'\fR). +.PP +To see exactly which \s-1NFSS\s0 codes map to which fonts, please refer to +the generated \fIfd\fR files. .SH "COMMAND-LINE OPTIONS" .IX Header "COMMAND-LINE OPTIONS" -\&\fBautoinst\fR tries hard to do The Right Thing (\s-1TM\s0) by default, +\&\fBautoinst\fR tries hard to do The Right Thing (\s-1TM\s0) by default, so you usually won't really need these options; but most aspects of its operation can be fine-tuned if you want to. .PP @@ -431,22 +464,21 @@ and option names may be shortened to a unique prefix but \fB\-e\fR is ambiguous (it may mean either \fB\-encoding\fR or \fB\-extra\fR)). .IP "\fB\-dryrun\fR" 4 .IX Item "-dryrun" -Don't generate any output files; only parse the input fonts and create +Don't generate any output files; only parse the input fonts and create \&\fIautoinst.log\fR showing which fonts would have been generated. .IP "\fB\-encoding\fR=\fIencoding[,encoding]\fR" 4 .IX Item "-encoding=encoding[,encoding]" -Generate the specified encoding(s) for the text fonts. The default is -\&\*(L"\s-1OT1,T1,LY1\*(R".\s0 +Generate the specified encoding(s) for the text fonts. Multiple text encodings may be +specified as a comma-separated list: \f(CW\*(C`\-encoding=OT1,T1,LY1\*(C'\fR (without spaces!). +The generated style file passes these encodings to \fIfontenc\fR in the specified order, +so the last one will become the default text encoding for your document. +.Sp +The default choice of encodings is \*(L"\s-1OT1,T1,LY1\*(R".\s0 For each encoding, a file \fI.enc\fR (in all \fIlowercase\fR!) should be somewhere where \fIotftotfm\fR can find it. Suitable encoding files for \s-1OT1, T1/TS1, LY1, LGR\s0 and T2A/B/C come with \fBautoinst\fR. (These files are called \fIfontools_ot1.enc\fR etc. to avoid name clashes with other packages; the \*(L"fontools_\*(R" prefix may be omitted.) -.Sp -Multiple text encodings can be specified as a comma-separated list: -\&\f(CW\*(C`\-encoding=OT1,T1\*(C'\fR (without spaces!). The generated style file passes these encodings -to \fIfontenc\fR in the specified order, so the last one will become -the default text encoding for your documents. .IP "\fB\-ts1\fR / \fB\-nots1\fR" 4 .IX Item "-ts1 / -nots1" Control the creation of TS1\-encoded fonts. The default is \fB\-ts1\fR @@ -493,18 +525,19 @@ Control the creation of titling fonts. The default is \fB\-titling\fR. .IX Item "-superiors / -nosuperiors" Control the creation of fonts with superior characters. The default is \fB\-superiors\fR. -.IP "\fB\-inferiors\fR=[ \fBsinf\fR | \fBsubs\fR | \fBdnom\fR ]" 4 -.IX Item "-inferiors=[ sinf | subs | dnom ]" -The OpenType standard defines several kinds of digits that might be used -as inferiors or subscripts: \*(L"Scientific Inferiors\*(R" -(OpenType feature \*(L"sinf\*(R"), \*(L"Subscripts\*(R" (\*(L"subs\*(R") and \*(L"Denominators\*(R" (\*(L"dnom\*(R"). +.IP "\fB\-inferiors\fR=[ \fBnone\fR | \fBauto\fR | \fBsubs\fR | \fBsinf\fR | \fBdnom\fR ]" 4 +.IX Item "-inferiors=[ none | auto | subs | sinf | dnom ]" +The OpenType standard defines several kinds of digits that might be used +as inferiors or subscripts: \*(L"Subscripts\*(R" (OpenType feature \*(L"subs\*(R"), +\&\*(L"Scientific Inferiors\*(R" (\*(L"sinf\*(R"), and \*(L"Denominators\*(R" (\*(L"dnom\*(R"). This option allows the user to determine which of these styles \fBautoinst\fR -should use for the inferior characters. The default is not to create fonts -with inferior characters. +should use for the inferior characters. +Alternatively, the value \*(L"auto\*(R" tells \fBautoinst\fR to use the first value +in the list \*(L"subs\*(R", \*(L"sinf\*(R" or \*(L"dnom\*(R" that is supported by the fonts. +The default value is \*(L"none\*(R". .Sp -\&\fINote that many fonts contain only one (or even none) of these types -of inferior characters. If you specify a style of inferiors that isn't -actually present in the font, \f(BIautoinst\fI silently falls back to its default +\&\fINote that if you specify a style of inferiors that isn't +present in the font, \f(BIautoinst\fI silently falls back to its default behaviour of not creating fonts with inferiors; it doesn't try to substitute one of the other features.\fR .IP "\fB\-fractions\fR / \fB\-nofractions\fR" 4 @@ -524,56 +557,69 @@ Tell \fBautoinst\fR which figure style is the current font family's default (i.e., which figures you get when you don't specify any OpenType features). .Sp \&\fIDon't use these options unless you are certain you need them!\fR -They are only needed for fonts that don't provide OpenType features -for their default figure style; and even in that case, -\&\fBautoinst\fR's default values (\fB\-defaultlining\fR and \fB\-defaulttabular\fR) +They are only needed for fonts that don't provide OpenType features +for their default figure style; and even in that case, +\&\fBautoinst\fR's default values (\fB\-defaultlining\fR and \fB\-defaulttabular\fR) are usually correct. .IP "\fB\-nofigurekern\fR" 4 .IX Item "-nofigurekern" Some fonts provide kerning pairs for tabular figures. -This is very probably not what you want +This is very probably not what you want (e.g., numbers in tables won't line up exactly). This option adds extra \fI \-\-ligkern\fR options -to the commands for \fIotftotfm\fR to suppress such kerns. +to the commands for \fIotftotfm\fR to suppress such kerns. Note that this option leads to very long commands (it adds one hundred \fI \-\-ligkern\fR options), which may cause problems on some systems. .IP "\fB\-mergewidths\fR / \fB\-nomergewidths\fR" 4 .IX Item "-mergewidths / -nomergewidths" -Some font families put Condensed and Extended fonts in separate families; -this option tells \fBautoinst\fR to merge those separate families into the \*(L"main\*(R" font family. +Some font families put Condensed, Narrow, Extended etc. fonts in separate families; +this option tells \fBautoinst\fR to merge those separate families into the main family. The default is \fB\-nomergewidths\fR. .IP "\fB\-extra\fR=\fItext\fR" 4 .IX Item "-extra=text" -Append \fItext\fR as extra options to the command lines for \fIotftotfm\fR. -To prevent \fItext\fR from accidentily being interpreted as options to \fBautoinst\fR, +Append \fItext\fR as extra options to the command lines for \fIotftotfm\fR. +To prevent \fItext\fR from accidentily being interpreted as options to \fBautoinst\fR, it should be properly quoted. .IP "\fB\-manual\fR" 4 .IX Item "-manual" -Manual mode. By default, \fBautoinst\fR immediately executes all \fIotftotfm\fR -commands it generates; with the \fB\-manual\fR option, these commands are -instead written to a file \fIautoinst.bat\fR. -Furthermore it adds the \fI \-\-pl\fR option -(which tells \fIotftotfm\fR to generate human readable/editable \fIpl\fR -and \fIvpl\fR files instead of the default \fItfm\fR and \fIvf\fR files) -and omits the \fI \-\-automatic\fR option (which causes \fIotftotfm\fR to -leave all generated files in the current directory, rather than install -them into your \s-1TEXMF\s0 tree). Manual mode is meant to enable tweaking -the generated commands and post-processing the generated files. +Manual mode; for users who want to post-process the generated files and commands. +By default, \fBautoinst\fR immediately executes all \fIotftotfm\fR commands it generates; +in manual mode, these are instead written to a file \fIautoinst.bat\fR. +Furthermore it tells \fIotftotfm\fR to generate human readable (and editable) +\&\fIpl/vpl\fR files instead of the default \fItfm/vf\fR ones, +and to place all generated files in a subdirectory \f(CW\*(C`./autoinst_output/\*(C'\fR +of the current directory, rather than install them into your TeX installation. .Sp -When using this option, run \fIpltotf\fR and \fIvptovf\fR after executing -the commands (to convert the \fIpl\fR and \fIvf\fR files to \fItfm\fR and \fIvf\fR format) -and move all generated files to their proper destinations. -.PP -All following options are only meaningful in automatic mode, -and hence ignored in manual mode: +When using this option, you need to execute the following manual steps after +\&\fBautoinst\fR has finished: +.RS 4 +.IP "\fB\-\fR run \fIpltotf\fR and \fIvptovf\fR on the generated \fIpl\fR and \fIvf\fR files, to convert them to \fItfm/vf\fR format;" 2 +.IX Item "- run pltotf and vptovf on the generated pl and vf files, to convert them to tfm/vf format;" +.PD 0 +.IP "\fB\-\fR move all generated files to a proper \s-1TEXMF\s0 tree, and, if necessary, update the filename database;" 2 +.IX Item "- move all generated files to a proper TEXMF tree, and, if necessary, update the filename database;" +.ie n .IP "\fB\-\fR tell TeX about the new \fImap\fR file (usually by running ""updmap"" or similar)." 2 +.el .IP "\fB\-\fR tell TeX about the new \fImap\fR file (usually by running \f(CWupdmap\fR or similar)." 2 +.IX Item "- tell TeX about the new map file (usually by running updmap or similar)." +.RE +.RS 4 +.PD +.Sp +Note that some options (\fI\-target\fR, \fI\-vendor\fR and \fI\-typeface\fR, \fI\-[no]updmap\fR) +are meaningless, and hence ignored, in manual mode. +.RE .IP "\fB\-target\fR=\fI\s-1DIRECTORY\s0\fR" 4 .IX Item "-target=DIRECTORY" Install all generated files into the \s-1TEXMF\s0 tree at \fI\s-1DIRECTORY\s0\fR. -This option allows the user to override \fBautoinst\fR's default behaviour, -which is to search the \f(CW$TEXMFLOCAL\fR and \f(CW$TEXMFHOME\fR paths and install all files -into subdirectories of the first writable \s-1TEXMF\s0 tree it finds -(or into subdirectories of the current directory, -if no writable directory is found). +.Sp +By default, \fBautoinst\fR searches the \f(CW$TEXMFLOCAL\fR and \f(CW$TEXMFHOME\fR trees +and installs all files into the first user-writable \s-1TEXMF\s0 tree it finds. +If \fBautoinst\fR cannot find such a user-writable directory +(which shouldn't happen, since \f(CW$TEXMFHOME\fR is supposed to be user-writable) +it will print a warning message and put all files into the subdirectory +\&\f(CW\*(C`./autoinst_output/\*(C'\fR of the current directory. +It's then up to the user to move the generated files to a better location +and update all relevant databases (usually by calling \fItexhash\fR and \fIupdmap\fR). .IP "\fB\-vendor\fR=\fI\s-1VENDOR\s0\fR" 4 .IX Item "-vendor=VENDOR" .PD 0 @@ -595,17 +641,17 @@ The default is \fB\-updmap\fR. .IX Header "SEE ALSO" Eddie Kohler's \fBTypeTools\fR (\fIhttp://www.lcdf.org/type\fR). .PP -\&\fBPerl\fR can be obtained from \fIhttp://www.perl.org\fR; +\&\fBPerl\fR can be obtained from \fIhttp://www.perl.org\fR; it is included in most Linux distributions. For Windows, try ActivePerl (\fIhttp://www.activestate.com\fR) or Strawberry Perl (\fIhttp://strawberryperl.com\fR). .PP \&\fBXeTeX\fR (\fIhttp://www.tug.org/xetex\fR) and \fBLuaTeX\fR (\fIhttp://www.luatex.org\fR) -are Unicode-aware TeX engines that can use OpenType fonts directly, +are Unicode-aware TeX engines that can use OpenType fonts directly, without any (La)TeX\-specific support files. .PP The \fBFontPro\fR project (\fIhttps://github.com/sebschub/FontPro\fR) -offers very complete LaTeX support (even for typesetting maths) for Adobe's +offers very complete LaTeX support (even for typesetting maths) for Adobe's Minion Pro, Myriad Pro and Cronos Pro font families. .SH "AUTHOR" .IX Header "AUTHOR" @@ -613,18 +659,19 @@ Marc Penninga (\fImarcpenninga@gmail.com\fR) .PP When sending a bug report, please give as much relevant information as possible. -If you see any error messages (either from \fBautoinst\fR itself, from the \fI\s-1LCDF\s0 TypeTools\fR, -from Perl or from the \s-1OS\s0), include these \fIverbatim\fR; don't paraphrase. +If you see any error messages +(whether from \fBautoinst\fR itself, from the \fI\s-1LCDF\s0 TypeTools\fR, from Perl +or from the \s-1OS\s0), include these \fIverbatim\fR; don't paraphrase. .SH "COPYRIGHT" .IX Header "COPYRIGHT" -Copyright (C) 2005\-2018 Marc Penninga. +Copyright (C) 2005\-2019 Marc Penninga. .SH "LICENSE" .IX Header "LICENSE" This program is free software; you can redistribute it and/or modify it under the terms of the \s-1GNU\s0 General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version. -A copy of the text of the \s-1GNU\s0 General Public License is included in +A copy of the text of the \s-1GNU\s0 General Public License is included in the \fIfontools\fR distribution; see the file \fIGPLv2.txt\fR. .SH "DISCLAIMER" .IX Header "DISCLAIMER" @@ -635,25 +682,29 @@ but \s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of .SH "RECENT CHANGES" .IX Header "RECENT CHANGES" (See the source for the full story, all the way back to 2005.) +.IP "\fI2019\-04\-01\fR" 12 +.IX Item "2019-04-01" +Fine-tuned the decision where to put generated files; +in particular, create \f(CW$TEXMFHOME\fR if it doesn't already exist +and \f(CW$TEXMFLOCAL\fR isn't user-writable. +.Sp +In manual mode, or when we can't find a user-writable \s-1TEXMF\s0 tree, +put all generated files into a subdirectory \f(CW\*(C`./autoinst_output/\*(C'\fR +instead of all over the current working directory. +.Sp +Added to \*(L"auto\*(R" value to the \fIinferiors\fR option, +to tell \fBautoinst\fR to use whatever inferior characters are available. +.IP "\fI2019\-03\-14\fR (never released to \s-1CTAN\s0)" 12 +.IX Item "2019-03-14 (never released to CTAN)" +Overhauled the mapping of fonts (more specifically of weights and widths; +the mapping of shapes didn't change) to \s-1NFSS\s0 codes. Instead of inventing our own codes +to deal with every possible weight and width out there, we now create \*(L"long\*(R" codes +based on the names in the font metadata. Then we add \*(L"ssub\*(R" rules to the \fIfd\fR +files to map the standard \s-1NFSS\s0 codes to our fancy names (see the section \fB\s-1NFSS\s0 codes\fR; +based on discussions with Frank Mittelbach and Bob Tennent). .IP "\fI2018\-08\-10\fR" 12 .IX Item "2018-08-10" Added encoding files for \s-1LGR\s0 and T2A/B/C to \fIfontools\fR. .IP "\fI2018\-03\-26\fR" 12 .IX Item "2018-03-26" -Added the \*(L"Text\*(R" weight and the \fI\-(no)mergewidths\fR option. -Changed the \s-1NFSS\s0 codes for \*(L"Thin\*(R" and \*(L"Book\*(R" to \*(L"i\*(R" and \*(L"o\*(R", respectively. -Tried to improve the documentation. -.IP "\fI2018\-01\-09\fR" 12 -.IX Item "2018-01-09" -Added the \*(L"sl\*(R" weight for font families (such as Fira Sans) that contain both -\&\*(L"Book\*(R" and \*(L"Regular\*(R" weights (reported by Bob Tennent). -Added the \*(L"Two\*(R", \*(L"Four\*(R", \*(L"Eight\*(R" and \*(L"Hair\*(R" weights (for Fira Sans). -.IP "\fI2017\-06\-16\fR" 12 -.IX Item "2017-06-16" -Changed the \fI\-inferiors\fR option from a binary yes-or-no choice to allow -the user to choose one of the \*(L"sinf\*(R", \*(L"subs\*(R" and \*(L"dnom\*(R" features. -\&\fBautoinst\fR now always creates a log file. -.IP "\fI2017\-03\-21\fR" 12 -.IX Item "2017-03-21" -Updated the \fIfontools_ot1.enc\fR encoding file to include the \*(L"Lslash\*(R" -and \*(L"lslash\*(R" glyphs (thanks to Bob Tennent). +Added the \fI\-(no)mergewidths\fR option; tried to improve the documentation. -- cgit v1.2.3