summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/man/man1/autoinst.1
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/man/man1/autoinst.1')
-rw-r--r--Master/texmf-dist/doc/man/man1/autoinst.1439
1 files changed, 245 insertions, 194 deletions
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<FontFamily>\-<Suffix>\fR, where \fI<Suffix>\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<suffix>\fR is the same as above (but in lowercase),
\&\fI<shape>\fR is either empty, \*(L"sc\*(R", \*(L"swash\*(R" or \*(L"titling\*(R",
and \fI<enc>\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<number>\fP""" 4
.el .IP "\f(CWscale=\f(CI<number>\f(CW\fR" 4
.IX Item "scale=<number>"
Scale the font by a factor of \fI<number>\fR.
-E.g., to increase the size of the font by 5%, use
-\&\f(CW\*(C`\eusepackage[scale=1.05]{\f(CI<FontFamily>\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<FontFamily>\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<FontFamily>_orn.enc\fR,
+\&\fI<FontFamily>_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<encoding>.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.