% $Id: typeface.tex 907 2012-06-18 04:42:32Z Geoffrey $
%
% typeface.tex Copyright (C) 2012 Geoffrey Jones

\documentclass[oneside,a4paper]{ltxdockit}[2010/09/26]

\RequirePackage[typeface=adobeminionpro,
                sanstypeface=adobemyriadpro,
                monotypeface=latinmodern,
                textfigures=oldstylefigures,
                inputencoding=dontload,   % already loaded by ltxdockit
                textcomp=dontload,        % ditto
               ]{typeface}

\usepackage[
%  showframe,
]{geometry}

\geometry{
  bindingoffset = 3em,
  marginparsep  = 0.5em,
  vmarginratio  = 9:10,
  headheight    = 5ex,
  headsep       = 2ex,
  footskip      = 6ex,
  hcentering,
}

\usepackage{calc}
\geometry{width  = 154mm,
          height = 154mm * \real{1.61803}}  % golden ratio
\setlength{\parindent}{0pt}
% \flushbottom

\usepackage{ragged2e}
\usepackage{xspace}
\usepackage{fancyhdr}
\fancypagestyle{plain}{%
  \fancyhf{}
  \fancyfoot[C]{\liningstylenums{\thepage}}
  \renewcommand{\headrulewidth}{0pt}
  \renewcommand{\footrulewidth}{0pt}
}
\pagestyle{plain}

\usepackage[babel]{microtype}
\usepackage[american]{babel}
\usepackage[strict]{csquotes}
\MakeAutoQuote{}{}
\MakeAutoQuote*{<}{>}

\usepackage{shortvrb}
\MakeShortVerb{\|}

\newrobustcmd*\keyword[1]{\mbox{\verbatimfont#1}}
\newrobustcmd*\typei{\keyword{Type1}\xspace}

\usepackage[dvipsnames,svgnames,x11names]{xcolor}
\definecolor{spot}{named}{MidnightBlue}
\definecolor{optspot}{named}{MidnightBlue}
\definecolor{option}{named}{black}
\definecolor{suboption}{named}{black}

\renewrobustcmd*{\opt}[1]{\mbox{\color{option}\verbatimfont#1}}
\newrobustcmd*{\subopt}[1]{\mbox{\color{suboption}\verbatimfont#1}}
\newrobustcmd*{\optlabel}[1]{\mbox{\color{optspot}\verbatimfont#1}}

\usepackage{caption}
\usepackage{booktabs}
\usepackage{needspace}
\usepackage{enumitem}
\usepackage{placeins}

\usepackage{tabularx}
\newcolumntype{H}{>{\sffamily\bfseries\spotcolor}l}
\newcolumntype{P}{>{\raggedright}l}
\newcommand*\colA[1]{\textrm{#1}}

\lstset{xleftmargin=1em,aboveskip=\medskipamount,belowskip=\medskipamount}

\newcommand*\OR{\thinspace\textbar\thinspace}
\newcommand*\np{\vspace{0.3\baselineskip}\\\noindent} % don't ask
\newcommand*\example[1]{\bigskip\emph{Example #1.}\smallskip}
\makeatletter
\newcommand*\tfrmfont{\tf@rmfont}
\renewcommand*\@makefntext[1]{%
  \hskip-1.2em%
  \leftskip=1.2em%
  \makebox[1.2em][l]{\@thefnmark}#1%
}
\setlength{\@fptop}{0pt}
\makeatother

\usepackage{dtklogos}
\newcommand*\LaTeXiie{%
  \LaTeX{}\kern.0em\liningstylenums{2}$_{\textstyle\varepsilon}$}
\newcommand*\LaTeXiii{%
  \LaTeX{}\kern.0em\liningstylenums{3}}

\titlepage{%
  title={The \sty{typeface} Package},
  subtitle={A package for simplifying \LaTeX\space \typei font setup},
  url={http://www.ctan.org/tex-archive/macros/latex/contrib/typeface/},
  author={Geoffrey Jones},
  email={geoffrey.jones@uqconnect.edu.au},
  revision={\liningstylenums{0.1} (preliminary release)},
  date={\liningstylenums{18 June 2012}}
}

\hypersetup{%
  pdftitle={The typeface Package},
  pdfsubject={A package for simplifying LaTeX Type1 font setup},
  pdfauthor={Geoffrey Jones},
  pdfkeywords={typeface, font, fonts, type1, pdf}
}

\begin{document}

\printtitlepage
\tableofcontents

\section{Introduction}
\label{sec:intro}

\subsection[About typeface]{About \sty{typeface}}

The \sty{typeface} package provides a relatively simple facility for setting up default roman, sans serif, teletype, math, symbols and lining/text figures \typei fonts in \LaTeX\space documents. Its purpose is to make it as easy as possible to mix, match, scale, test and use whatever combinations you might like from the main \typei font sets available at \acr{CTAN}\fnurl{http://www.ctan.org/tex-archive/fonts}. Other \typei fonts can be readily integrated into \sty{typeface} package management by modifying the provided configuration file.
\np%
As a document font manager, \sty{typeface} bears certain similarities to Will Robertson's and Khaled Hosny's more extensive \href{http://ctan.org/tex-archive/macros/latex/contrib/fontspec}{fontspec} package. While the role of \sty{typeface} is to simplify configuring and loading document default \typei fonts, \sty{fontspec}'s purpose is to simplify most things connected with using \keyword{OpenType} and, to some extent,  \keyword{TrueType} fonts. However, unlike \sty{fontspec} which cannot be used under \LaTeX, with a few restrictions, \sty{typeface} performs as advertised under \LuaTeX\space and \XeTeX.  That said, each package has its natural role and home environment---\sty{typeface} for simplifying setting up default \typei fonts in \LaTeX\space documents, and \sty{fontspec} for managing \keyword{OpenType} fonts in \LuaTeX\space and \XeTeX\space documents.

\subsubsection{Motivation}

This work is grounded in the observation that, despite the tremendous strides that have been made by more modern \TeX\space engines and compilation formats, \LaTeX\footnote{By which I mean \LaTeXiie, including reasonably strict supersets such as \LaTeXiii.} remains a document production mainstay for many individuals, institutions and publication houses. Given this and its relative stability, things will most likely remain this way for some time to come. However, the task of setting up fonts in \LaTeX\space documents all too frequently takes more effort than it reasonably should.  The approaches for loading fonts typically depend more on the programming styles of font package authors than on actual necessity---given, that is, that relevant font loading packages even exist. The Berry names\fnurl{http://www.tug.org/fontname/fontname.pdf} for individual typefaces can prove frustrating to recall when using fonts that have not been thus supplied.  The methods for scaling fonts can often prove exasperating to remember and apply. Worse, font scaling is often not included as a load-time option in font loading packages or font descriptor (\file{.fd}) files.  For such a routine task, scaling one font to match another is seldom, if ever, automated. Notwithstanding the \ae sthetic appropriateness of the task, freely mixing and matching combinations of text and math typefaces can prove technically difficult to get right. Switching between text figures (\begin{textnums}12345\end{textnums}) and lining figures (\begin{liningnums}12345\end{liningnums}) is often so burdensome that \LaTeX\space users all too often give up, preferring to render body text, titles and adornments like page numbers equally, either in all lining figures or in all text figures.%
\footnote{\LaTeX's native \cmd{oldstylenums} command provides some support for this. Unfortunately, it is surrounded by several noteworthy limitations, including patchy coverage across the breadth of \typei fonts and missing reciprocal function (\cmd{liningstylenums}?).}
Nevertheless, the beauty of a finished \LaTeX\space document typeset with well-configured fonts can make memories of the frustrations that went into creating it quickly recede.  The \sty{fontspec} package overcomes many of these difficulties in the \LuaTeX\space and \XeTeX\space worlds.  This work sets out to reduce the effort of default \typei font setup in the \LaTeX\space world.

\subsection{License}

Copyright \textcopyright\ 2011--2012 Geoffrey Jones. Permission is granted to copy, distribute and\slash or modify this software under the terms of the \lppl, version 1.3 or later.\fnurl{http://www.ctan.org/tex-archive/macros/latex/base/lppl.txt} This package is author"=maintained.

\subsection{About this Manual}

This manual was compiled using Philipp Lehman's \sty{ltxdockit} document class. Document fonts were specified with the following command:

\begin{ltxcode}
\RequirePackage[typeface=<<adobeminionpro>>,
                sanstypeface=<<adobemyriadpro>>,
                monotypeface=<<latinmodern>>,
                textfigures=<<oldstylefigures>>
               ]{typeface}
\end{ltxcode}

As Adobe Myriad Pro, at least, is not a readily available Postscript \typei font, you might need to make substitutions before regenerating this document.
\np%
As an early aside, note as you read this manual that the \sty{typeface} package was not instructed about font scaling. Rather, during loading, the \sty{typeface} package automatically scaled the \textsf{sans serif} and \texttt{teletype} font ex-heights to match the roman font ex-height size.

\subsection{Package Contents}
\label{sec:pkgcontents}

The \sty{typeface} package contains the following files:
  \begin{itemize}[noitemsep]
     \item \file{README}---the package README file
     \item \file{typeface.pdf}---the package manual (this document)
     \item \file{typeface.tex}---the package manual source
     \item \file{typeface.sty}---the \sty{typeface} package
     \item \file{typeface.cfg}---installation customisation and reconfiguration file
     \item \file{typeface-test.tex}---\sty{typeface} package test harness
     \item \file{typeface-all-rm.pdf}---a \emph{very} large typeface exhibits file (\begin{liningnums}16\end{liningnums}MB or thereabouts)
     \item \file{typeface-all-rm.bat}---the \acr{ms-dos} script used to produce the file above
   \end{itemize}

\subsection{Installation}

Installation involves placing \file{typeface.sty} somewhere in your \file{texmf} tree then rehashing \TeX's name database using \keyword{texhash} or whatever. These actions are performed automatically if you install this package using \MiKTeX's or \TeXLive's system package managers.
\np%
Likewise, configuration file \file{typeface.cfg} should be placed in a suitable location in your system or local \file{texmf} trees, re-\keyword{texhash}-ing when you are done.  Alternatively, you could save a customised version of \file{typeface.cfg} in your document directory should your document have highly particular \sty{typeface} configuration needs.

\begin{enumerate}[leftmargin=0em,itemindent=0em,labelsep=0.5em]
  \item[\emph{Caveat}:] Please take extra precautions to ensure any site-local versions of \file{typeface.cfg} are not overwritten if using \MiKTeX's or \TeXLive's system package managers. As usual, versioning or otherwise backing up your configuration files might prove a useful idea.
\end{enumerate}

Finally, note that \sty{typeface} cannot access \LaTeX\space\typei fonts unless they are properly installed. Please ensure that this is done before attempting to access them through this package. \MiKTeX's and \TeXLive's system package managers make this chore a breeze.

\subsection{Typeface Exhibits File}

The \sty{typeface} package includes a large typeface exhibits file presenting all the roman fonts and many of the other font sets that it manages. This file, \file{typeface-all-rm.pdf}, was produced by compiling \file{typeface-test.tex} with parameters set out in \file{typeface-all-rm.bat}\footnote{It should be relatively trivial to convert this script to Unix-compatible form.}.  The first few pages in \file{typeface-all-rm.pdf} contain the output produced using \keyword{default} options, \kvopt{debug}{true}, \kvopt{fontencoding}{OT1}, typeface options set to (typographically hideous) example non-\opt{default} values, and  suboption \opt{scale} set to \opt{1}, a value that switches off font scaling.  The remaining pages contain exhibits of \acr{CTAN}-available roman fonts accompanied by randomly selected sans serif, teletype, math and substitute text figures companion typefaces automatically scaled to match the roman font size. Exhibits of some widely available commercial fonts are included at the end of the file.

\subsection{Prerequisite Conditions}

This package requires \sty{e-TeX}.
\np%
This package requires \sty{microtype} if (and only if) text figures substitute font letter spacing is desired (advanced usage; see section \ref{sec:textfigures}, below). Note that \sty{microtype} generally does not partner well with bitmap fonts, especially if any scaling is involved. Should you select bitmap fonts (\keyword{concrete}, \keyword{cmbright}, etc.), \sty{microtype} will probably raise ``auto expansion is only possible with scalable fonts'' errors during document compilation. Bottom line: either avoid bitmap fonts (for example, install the \keyword{hfbright} package to use a \typei variant of \keyword{cmbright}), or avoid \sty{microtype}.

\subsection{Auxiliary File}

The \sty{typeface} package produces auxiliary file \prm{jobname}\file{.tf} during the course of each run. The package will issue a warning whenever changes made to the auxiliary file necessitate a recompile.

\section{Package Options}
\label{sec:opt}

This package performs most of its work at package load time. Except for a small number of  commands for typesetting text and lining figures and a few others for printing font information, \sty{typeface} exposes very little functionality to users after it has been loaded. Thus, users should ordinarily focus on understanding the package's main options before turning to use its few available commands.

\subsection{Options Syntax}

All package options are given in \kvopt{\prm{key}}{\prm{option}\prm{suboptions}} syntax, where \prm{suboptions} is constructed by appending zero or more :\prm{suboption} terms to \kvopt{\prm{key}}{\prm{option}} productions.
\np%
Spaces are ignored within these constructs, so may be freely included wherever you like, presumably for better aiding readability.

\subsection{Default Options}

Default behaviour occurs whenever a particular \keyval option is not explicitly supplied or, given the keyword \opt{default} has not been modified, package option \kvopt{\prm{key}}{default} is explicitly specified.
\np%
Please note that this package can be extensively reconfigured in order to meet the requirements of the different locales, institutions or installations where it might be used. Both the keyword \opt{default} and the default behaviour of package keys can be modified. Thus, you should check the contents of \file{typeface.cfg} if you feel concerned that the package's default behaviour has been overridden in some way. See section \ref{sec:config}, below, for further details.

\subsection{Typeface Selection}

\begin{optionlist}

\optitem[default]{typeface}{\prm{roman font}\prm{suboptions}}\vspace{-\baselineskip}
\optitem{rm}{\prm{roman font}\prm{suboptions}}

The \opt{typeface} (syn: \opt{rm}) option can be used to set up \cmd{rmdefault}, that is, the document's default roman font. The value \prm{roman font} may be one of the font names or shorthand terms (aliases) set out in table \ref{tab:rmopt}. This list can be extended by modifying the package configuration file \file{typeface.cfg} (see section \ref{sec:config}).

A number of roman typefaces can take suboptions. These are set out in table \ref{tab:rmsubopt}. Users should refer to the relevant font documentation or simply try them out to determine what they do.

Note that \cmd{encodingdefault}, the font encoding in place at font load time, can influence the typeface that is used. Font encodings are discussed in section \ref{sec:enc}, below.

Unless reconfigured in the configuration file \file{typeface.cfg}, package option

\begin{ltxcode}
typeface=<<default>>
\end{ltxcode}\vspace{-\medskipamount}

is essentially a \keyword{no-op}.  In other words, \sty{typeface} will not alter whatever value \cmd{rmdefault} might expand to at \sty{typeface} package load time.

\begin{table}[!ht]
\tablesetup
\texttt{%
\begin{tabularx}{\columnwidth}{@{}PPX@{}}
  \toprule
  \multicolumn{1}{@{}H}{Typeface Name}  &
  \multicolumn{1}{H}{Option}            &
  \multicolumn{1}{H}{Aliases}           \\
  \midrule
    \colA{ADF Baskervald} & adfbaskervald & baskervald \\
    \colA{ADF Berenis} & adfberenis & berenis \\
    \colA{ADF Electrum} & adfelectrum & electrum \\
    \colA{ADF Romande} & adfromande & romande \\
    \colA{ADF Venturis} & adfventuris & venturis \\
    \colA{Adobe Minion Pro} & adobeminionpro & minionpro \\
    \colA{Adobe Utopia} & adobeutopia & utopia \\
    \colA{AE} & ae & \\
    \colA{Antykwa P\'o\l tawskiego} & antykwapoltawski & antpol, poltawski \\
    \colA{Antykwa Toru\'nska} & antykwatorunska & anttor, torunska \\
    \colA{Artificial Uncial} & uncial & \\
    \colA{Augie} & augie & \\
    \colA{Auriocus Kalligraphicus} & auriocuskalligraphicus & auriocus, kalligraphicus \\
    \colA{Bera Serif} & beraserif & bera \\
    \colA{Bitstream Charter} & bitstreamcharter & charter \\
    \colA{CM Bright} & cmbright & \\
    \colA{CM Dunhill} & cmdunhill & \\
    \colA{CM Fibonacci} & cmfibonacci & \\
    \colA{Computer Modern} & computermodern & cm, cmr \\
    \colA{Concrete} & concrete & \\
    \colA{Day Roman} & dayroman & dayrom \\
    \colA{DejaVu} & dejavu & \\
    \colA{Droid} & droid & \\
    \colA{European Modern} & europeanmodern & em \\
    \colA{GFS Artemisia} & gfsartemisia & artemisia \\
    \colA{GFS Bodoni} & gfsbodoni & bodoni \\
    \colA{GFS Didot} & gfsdidot & didot \\
    \colA{GFS Neohellenic} & gfsneohellenic & neohellenic \\
    \colA{Gyre Bonum} & gyrebonum & bonum, tgbonum \\
    \colA{Gyre Pagella} & gyrepagella & pagella, tgpagella \\
    \colA{Gyre Schola} & gyreschola & schola, tgschola \\
    \colA{Gyre Termes} & gyretermes & termes, tgtermes \\
    \colA{Iwona} & iwona & \\
    \colA{JAM Times} & jamtimes & jam \\
    \colA{KP Fonts} & kpfonts & kp, kepler \\
    \colA{Kerkis} & kerkis & \\
    \colA{Kurier} & kurier & \\
    \colA{Latin Modern} & latinmodern & lm, lmodern \\
    \colA{Libertine} & libertine & \\
    \colA{Lucida Bright} & lucidabright & lucidabr, lucida \\
    \colA{New Century Schoolbook} & newcenturyschoolbook & nc, newcentury \\
    \colA{PT Serif} & ptserif & pt, paratype \\
    \colA{PX Fonts} & pxfonts & px \\
    \colA{Palatino} & palatino & \\
    \colA{TX Fonts} & txfonts & tx \\
    \colA{Times Roman} & times & \\
    \colA{URW Antiqua} & urwantiqua & antiqua \\
    \colA{URW Bookman} & urwbookman & bookman \\
    \colA{URW Garamond} & urwgaramond & garamond \\
    \colA{URW Nimbus} & urwnimbus & nimbus \\
    \colA{Zapf Chancery} & zapfchancery & chancery, zapf \\
  \bottomrule
\end{tabularx}%
}
\caption[Typeface Options]{\raggedright{Roman typeface options.
                           Usage: \kvopt{typeface}{\prm{option}\prm{suboptions}}, where \prm{option} is an item from the \textsf{\spotcolor{Option}} or \textsf{\spotcolor{Aliases}} columns, and \prm{suboptions} is formed by concatenating zero or more :\prm{suboption} terms, for which, see table \ref{tab:rmsubopt}.}}
\label{tab:rmopt}
\end{table}

\begin{table}[!ht]
\tablesetup
\texttt{%
\begin{tabularx}{\columnwidth}{@{}PX>{\hsize=.01\hsize}X@{}}
  \toprule
  \multicolumn{1}{@{}H}{Typeface Name}  &
  \multicolumn{1}{H}{Suboptions}        &
  \multicolumn{1}{H@{}}{Reference Packages} \\
  \midrule
    \colA{ADF Baskervald} & lig & baskervald \\
    \colA{ADF Berenis} & tab, lig & berenis \\
    \colA{ADF Electrum} & lig & electrum \\
    \colA{ADF Romande} & alt & romande \\
    \colA{ADF Venturis} & 2, old & venturis, venturis2, venturisold \\
    \colA{AE} & slides & ae \\
    \colA{Adobe Minion Pro} & smallfamily, medfamily, fullfamily, noopticals, opticals, slides, normalsize, nonormalsize & MinionPro \\
    \colA{Antykwa P\'o\l tawskiego} & light & \\
    \colA{Antykwa Toru\'nska} & mathnoalias, light, condensed & anttor \\
    \colA{Auriocus Kalligraphicus} & backslant & aurical \\
    \colA{CM Bright} & slantedGreek, standard-baselineskips & cmbright \\
    \colA{Concrete} & exscale, amsfonts, amssymb, sansbold, boldsans & concmath \\
    \colA{Day Roman} & s & dayrom \\
    \colA{DejaVu} & condensed &  DejaVuSerif, DejaVuSerifCondensed \\
    \colA{GFS Artemisia} & euler & gfsartemisia \\
    \colA{GFS Neohellenic} & symbols & gfsneohellenic \\
    \colA{Iwona} & light, condensed & iwona \\
    \colA{KP Fonts} & oldstyle, veryoldstyle, rmx, light, largesmallcaps, nofligatures, easyscsl, oldstylenumsmath (\textrm{syn:}\hspace{0.4em}osf, oldstylenums), noamsmath, sfmath, sfmathbb, rmmathbb, nomathscript, mathcalasscript, classicReIm, uprightRoman, frenchstyle, upright, oldstylenumsmath, oldstylemath, veryoldstylemath, narrowiints, partialup, widermath, noDcommand, intlimits, nointlimits, fullintlimits, sumlimits, nosumlimits, fullsumlimits, uprightgreeks, slantedGreeks & kpfonts \\
    \colA{Kurier} & light, condensed & kurier \\
    \colA{Latin Modern} & boldsc\textsuperscript{\textit{a}} &  \\
    \colA{Lucida Bright} & seriftt, expert, noexpert, lucidascale, nolucidascale, lucidasmallscale,          mathitalic1, mathitalic2, mathitalic3, slantedgreek, uprightgreek, vargreek, noamssymbols, amsmath, OT1, T1, LY1, seriftt, fax, casual, calligraphic, handwriting, altbullet, errorshow, warningshow, nofontinfo & lucidabr, lucbmath\\
    \colA{TX Fonts} & new\textsuperscript{\textit{b}} & txfonts, newtxtext \\
  \bottomrule
\end{tabularx}%
}
\caption[Typeface Suboptions]{\raggedright{Roman typeface suboptions. See reference packages for the meaning of these terms.\par\footnotesize{\textsuperscript{\textit{a}}Draws bold smallcaps from Computer Modern. Font encoding \keyword{T1} only.}\par\footnotesize{\textsuperscript{\textit{b}}Loads TX Fonts from the \keyword{newtx} package.}\par}}
\label{tab:rmsubopt}
\end{table}

\optitem[default]{sanstypeface}{\prm{sans serif font}\prm{suboptions}}\vspace{-\baselineskip}
\optitem{sf}{\prm{sans serif  font}\prm{suboptions}}

\optitem[default]{monotypeface}{\prm{teletype font}\prm{suboptions}}\vspace{-\baselineskip}
\optitem{tt}{\prm{teletype font}\prm{suboptions}}

The \opt{sanstypeface} (syn: \opt{sf}) and \opt{monotypeface} (syn: \opt{tt}) options can be used to set up \cmd{sfdefault} and \cmd{ttdefault}, that is, the document's default sans serif and teletypewriter fonts.  As with setting \kvopt{typeface}{default}, setting \kvopt{sanstypeface}{default} and/or \kvopt{monotypeface}{default} does very little at all---\cmd{sfdefault} and \cmd{ttdefault} are not altered in these cases.

Key values \prm{sans serif font} and \prm{teletype font} can be selected from the font names or shorthand terms (aliases) set out in tables \ref{tab:sfopt} and \ref{tab:ttopt}. These lists can be expanded by modifying package configuration file \file{typeface.cfg}.

In addition to fine-tuning font selections by applying the \prm{suboptions} listed in tables \ref{tab:sfsubopt} and \ref{tab:ttsubopt}, sans serif and teletype fonts can be scaled using the \subopt{scale} suboption. This suboption is discussed in section \ref{sec:scaling}, below.

\begin{table}[!ht]
\tablesetup
\texttt{%
\begin{tabularx}{\columnwidth}{@{}PPX@{}}
  \toprule
  \multicolumn{1}{@{}H}{Typeface Name}  &
  \multicolumn{1}{H}{Option}            &
  \multicolumn{1}{H}{Aliases}           \\
  \midrule
    \colA{ADF Libris} & adflibris & libris \\
    \colA{ADF Venturis Sans} & adfventuris & venturis \\
    \colA{AE Sans} & ae & \\
    \colA{Arev Sans} & arevsans & arev \\
    \colA{Augie} & augie & \\
    \colA{Avant Garde} & avantgarde & \\
    \colA{Biolinum} & biolinum & libertine \\
    \colA{Bitstream Vera Sans} & berasans & bera \\
    \colA{CM Bright Sans} & cmbright & \\
    \colA{Cantarell} & cantarell & \\
    \colA{Comfortaa} & comfortaa & \\
    \colA{Computer Modern Sans} & computermodern & cm, cms \\
    \colA{Cyklop} & cyklop & \\
    \colA{DejaVu Sans} & dejavu & \\
    \colA{Droid Sans} & droid & \\
    \colA{European Modern Sans} & europeanmodern & em \\
    \colA{GFS Neohellenic} & gfsneohellenic & neohellenic \\
    \colA{Gyre Adventor} & gyreadventor & adventor, tgadventor \\
    \colA{Gyre Heros} & gyreheros & heros, tgheros \\
    \colA{Helvetica} & helvetica & helv \\
    \colA{Iwona} & iwona & \\
    \colA{KP Fonts Sans} & kpfonts & kp, kepler \\
    \colA{Kerkis Sans} & kerkis & \\
    \colA{Kurier Sans} & kurier & \\
    \colA{Latin Modern Sans} & latinmodern & lm, lmodern \\
    \colA{Lato} & lato & \\
    \colA{Lucida Bright Sans} & lucidabright & lucidabr, lucida \\
    \colA{Open Sans} & opensans & \\
    \colA{PT Sans} & ptsans & pt, paratype \\
    \colA{PX Fonts Sans} & px fonts & px \\
    \colA{TX Fonts Sans} & tx fonts & tx \\
    \colA{URW Arial} & urwarial & arial \\
    \colA{URW Classico} & urwclassico & classico, optima \\
    \colA{URW Grotesq} & urwgrotesq & grotesq \\
    \colA{URW Nimbus Sans} & urwnimbus & nimbus \\
  \bottomrule
\end{tabularx}%
}
\caption[Sans Serif Options]{\raggedright{Sans serif typeface options. See table \ref{tab:sfsubopt} for associated suboptions.}}
\label{tab:sfopt}
\end{table}

\begin{table}[!ht]
\tablesetup
\texttt{%
\begin{tabularx}{\columnwidth}{@{}PPX@{}}
  \toprule
  \multicolumn{1}{@{}H}{Typeface Name}  &
  \multicolumn{1}{H}{Suboptions}        &
  \multicolumn{1}{H@{}}{Reference Packages} \\
  \midrule
    \colA{ADF Venturis Sans} & 2 & venturis \\
    \colA{AE Sans} & slides & ae \\
    \colA{Biolinum} & osf & libertine \\
    \colA{Computer Modern Sans} & quotation &  \\
    \colA{DejaVu Sans} & condensed & dejavu \\
    \colA{GFS Neohellenic} & symbols & gfsneohellenic \\
    \colA{Iwona} & light, condensed & iwona \\
    \colA{KP Fonts Sans} & osf & kpfonts\\
    \colA{Kurier Sans} & light, condensed & kurier \\
    \colA{Latin Modern Sans} & extended & \\
    \colA{Open Sans} & osf & opensans \\
  \bottomrule
\end{tabularx}%
}
\caption[Sans Serif Suboptions]{\raggedright{Sans serif typeface suboptions. See reference packages for the meaning of each term.}}
\label{tab:sfsubopt}
\end{table}

\begin{table}[!ht]
\tablesetup
\texttt{%
\begin{tabularx}{\columnwidth}{@{}PPX@{}}
  \toprule
  \multicolumn{1}{@{}H}{Typeface Name}  &
  \multicolumn{1}{H}{Option}            &
  \multicolumn{1}{H}{Aliases}           \\
  \midrule
    \colA{AE Mono} & ae & \\
    \colA{Bitstream Vera Mono} & beramono & bera \\
    \colA{Computer Modern Mono Light} & cmbright & \\
    \colA{Courier} & courier & \\
    \colA{DejaVu Mono} & dejavu & \\
    \colA{Droid Mono} & droid & \\
    \colA{European Modern Mono} & europeanmodern & em \\
    \colA{Gyre Cursor} & gyrecursor & cursor, tgcursor \\
    \colA{Inconsolata} & inconsolata & \\
    \colA{KP Fonts Mono} & kpfonts & kp, kepler \\
    \colA{Latin Modern Mono} & latinmodern & lm, lmodern \\
    \colA{Lucida Bright Mono} & lucidabright & lucidabr, lucida \\
    \colA{Luxi Mono} & luximono & luxi \\
    \colA{PT Mono} & ptmono & pt, paratype \\
    \colA{PX Fonts Mono} & pxfonts & px \\
    \colA{TX Fonts Mono} & txfonts & tx \\
    \colA{} & computermodern & cm, cmt \\
  \bottomrule
\end{tabularx}%
}
\caption[Teletype Options]{\raggedright{Teletype typeface options. See table \ref{tab:ttsubopt} for associated suboptions.}}
\label{tab:ttopt}
\end{table}

\begin{table}[!ht]
\tablesetup
\texttt{%
\begin{tabularx}{\columnwidth}{@{}PX>{\hsize=.01\hsize}X@{}}
  \toprule
  \multicolumn{1}{@{}H}{Typeface Name}  &
  \multicolumn{1}{H}{Suboptions}        &
  \multicolumn{1}{H@{}}{Reference Packages} \\
  \midrule
    \colA{AE Mono} & slides & ae\\
    \colA{Computer Modern Mono Light} & light, proportional, L & \\
    \colA{KP Fonts Mono} & osf & kpfonts \\
    \colA{Latin Modern Mono} & proportional & lmodern \\
    \colA{Lucida Bright Mono} & serif, seriftt, sans & lucidabr \\
  \bottomrule
\end{tabularx}%
}
\caption[Teletype Suboptions]{\raggedright{Teletype typeface suboptions. See reference packages for their meaning.}}
\label{tab:ttsubopt}
\end{table}

\begin{table}[!ht]
\tablesetup
\texttt{%
\begin{tabularx}{\columnwidth}{@{}PPX@{}}
  \toprule
  \multicolumn{1}{@{}H}{Typeface Name}  &
  \multicolumn{1}{H}{Option}            &
  \multicolumn{1}{H}{Aliases}           \\
  \midrule
    \colA{Adobe Minion Pro} & adobeminionpro &  \\
    \colA{AMS Math} & amsmath & ams \\
    \colA{Antykwa Toru\'nska} & antykwatorunska & anttor, torunska \\
    \colA{Arev Math} & arevmath & arev \\
    \colA{CM Bright} & cmbright &  \\
    \colA{Concrete Math} & concrete &  \\
    \colA{Euler} & euler &  \\
    \colA{European Modern} & europeanmodern & em \\
    \colA{Fourier} & fourier &  \\
    \colA{GFS Artemisia} & gfsartemisia & artemisia \\
    \colA{GFS Bodoni} & gfsbodoni & bodoni \\
    \colA{GFS Didot} & gfsdidot & didot \\
    \colA{GFS Neohellenic} & gfsneohellenic & neohellenic \\
    \colA{Iwona} & iwona &  \\
    \colA{KP Fonts} & kpfonts & kp, kepler \\
    \colA{Kerkis} & kerkis &  \\
    \colA{Kurier} & kurier &  \\
    \colA{LX Fonts} & lxfonts & lx \\
    \colA{Latin Modern} & latinmodern & lm, lmodern \\
    \colA{Lucida Bright} & lucidabright & lucidabr, lucida \\
    \colA{Math Design} & mathdesign &  \\
    \colA{MathTime 2} & mathtimepro & mtpro \\
    \colA{Math PTMX} & mathptmx & ptmx \\
    \colA{PX Fonts} & pxfonts & px \\
    \colA{Pazo} & mathpazo & pazo \\
    \colA{TX Fonts} & txfonts & tx \\
  \bottomrule
\end{tabularx}%
}
\caption[Math Typeface Options]{\raggedright{Math typeface options. See table \ref{tab:mathsubopt} for associated suboptions.}}
\label{tab:mathopt}
\end{table}

\begin{table}[!ht]
\tablesetup
\texttt{%
\hspace{-.05\columnwidth}\begin{tabularx}{1.05\columnwidth}{@{}PX>{\hsize=.01\hsize}X@{}}
  \toprule
  \multicolumn{1}{@{}H}{Typeface Name}  &
  \multicolumn{1}{H}{Suboptions}        &
  \multicolumn{1}{H@{}}{Reference Packages} \\
  \midrule
    \colA{Adobe Minion Pro} & smallfamily, medfamily, fullfamily, noopticals, opticals, slides, normalsize, nonormalsize, liningstylefigures (syn: lf, lsf, lining, liningstyle, mathlf), oldstylefigures (syn: osf, oldstyle, oldfigures, mathosf), mathtabular, mnsy, cmsy, swash, abx, amsbb, fourierbb, lucidabb, mixedgreek, italicgreek, frenchmath, minionint, openg, loosequotes, footnotefigures & MinionPro \\
    \colA{AMS Math} & tbtags, nosumlimits, intlimits, nonamelimits, donotfixamsmathbugs & amsmath \\
    \colA{Antykwa Toru\'nska} & light, condensed & anttor \\
    \colA{Arev Math} & origletters, vara, vari, varI, varf, oldf, varl, varu, varv, varw, varGamma, varXi, varPi, varSigma, varPhi & arevmath \\
    \colA{CM Bright} & slantedGreek, standard-baselineskips &  cmbright\\
    \colA{Concrete Math} & exscale, amsfonts, amssymb, sansbold, boldsans &  concrete\\
    \colA{Euler} & small, euler-digits, euler-hat-accent, T1, OT1, LY1, icomma & eulervm \\
    \colA{European Modern} & T1, LY1, LM1 & em \\
    \colA{Fourier} & nc, newcentury, newcenturyschoolbook, utopia, adobeutopia, upright, widespace, expert, oldstyle, fulloldstyle & fourier \\
    \colA{GFS Artemisia} & euler & gfsartemisia \\
    \colA{Iwona} & light, condensed &  iwona\\
    \colA{KP Fonts} & light, noamsmath, sfmath, sfmathbb, rmmathbb, nomathscript, mathcalasscript, classicReIm, uprightRoman, frenchstyle, upright, oldstylefigures (syn: osf, oldstyle, oldfigures, oldstylenums, oldstylenumsmath), oldstylemath, veryoldstylemath, narrowiints, partialup, widermath, noDcommand, intlimits, nointlimits, fullintlimits, sumlimits, nosumlimits, fullsumlimits, uprightgreeks, slantedGreeks & kpfonts \\
    \colA{Kerkis} & light, condensed & kerkis\\
    \colA{Lucida Bright} & expert, noexpert, lucidascale, nolucidascale, lucidasmallscale, mathitalic1, mathitalic2, mathitalic3, slantedgreek, uprightgreek, vargreek, amsmath, noamssymbols, OT1, T1, LY1, seriftt, fax, casual, calligraphic, handwriting, altbullet,errorshow, warningshow, nofontinfo & lucidabr, lucbmath \\
    \colA{Math Design} & expert, uppercase:upright,uppercase:italicized, greekuppercase:upright,greekuppercase:italicized, greeklowercase:upright,greeklowercase:italicized, greekuppercase, greeklowercase, urwgaramond, garamond, adobeutopia, utopia, bitstreamcharter, charter & mathdesign \\
    \colA{MathTime 2} & amssymbols, noamssymbols, slantedGreek, uprightGreek, slantedoperators, uprightoperators, subscriptcorrection, nosubscriptcorrection, zswash, nozswash, curlybraces, straightbraces, morphedbraces, cmcal, lucidacal, eucal, mtpluscal, mtpcal, mtpccal, lucidascr, mtplusscr, mtpscr, eufrak, mtpfrak, compatiblegreek, amsbb, mtpbb, mtpbbd, mtphrb, mtphrd, mtpbbi, mtphbi, errorshow, warningshow, nofontinfo, lite & mtpro2 \\
    \colA{Pazo} & slantedGreek, noBBpl &  mathpazo\\
    \colA{TX Fonts} & new\textsuperscript{\textit{a}}, varg, libertine, cmintegrals, uprightGreek, cmbraces, varbb, nosymbolsc, amssymbols, noamssymbols, ptmxitalics & txfonts, newtxmath \\
  \bottomrule
\end{tabularx}%
}
\caption[Math Typeface Suboptions]{\raggedright{Math typeface suboptions. See reference packages for their meaning.\par\footnotesize{\textsuperscript{\textit{a}}Loads TX Fonts from the \keyword{newtx} package.}}}
\label{tab:mathsubopt}
\end{table}

\FloatBarrier

\begin{table}[!ht]
\tablesetup
\texttt{%
\begin{tabularx}{\columnwidth}{@{}PPX@{}}
  \toprule
  \multicolumn{1}{@{}H}{Typeface Name}  &
  \multicolumn{1}{H}{Option}            &
  \multicolumn{1}{H}{Aliases}           \\
  \midrule
    \colA{AMS Symbols} & amssymb &  ams \\
    \colA{FD Symbol} & fdsymbol &  fd \\
    \colA{Math abx} & mathabx &  abx \\
    \colA{MdSymbol} & mdsymbol &  md \\
    \colA{MnSymbol} & mnsymbol &  mn \\
  \bottomrule
\end{tabularx}%
}
\caption[Symbols Options]{\raggedright{Symbols typeface options. See table \ref{tab:symsubopt} for associated suboptions.}}
\label{tab:symopt}
\end{table}

\begin{table}[!ht]
\tablesetup
\texttt{%
\begin{tabularx}{\columnwidth}{@{}PX>{\hsize=.01\hsize}X@{}}
  \toprule
  \multicolumn{1}{@{}H}{Typeface Name}  &
  \multicolumn{1}{H}{Suboptions}        &
  \multicolumn{1}{H@{}}{Reference Packages} \\
  \midrule
    \colA{FD Symbol} & normalweightRegular, normalweightAuto, boldweightMedium, boldweightAuto, largedelims &  fdsymbol \\
    \colA{MdSymbol} & autolight, autoregular, autosemibold, Bold, bold, largedelims, Light, light, onlysansmath, regular, Regular, retainmissing, semibold, Semibold & mdsymbol \\
  \bottomrule
\end{tabularx}%
}
\caption[Symbols Suboptions]{\raggedright{Symbols typeface suboptions. See reference packages for their meaning.}}
\label{tab:symsubopt}
\end{table}

\optitem[default]{mathtypeface}{\prm{math font}\prm{suboptions}}\vspace{-\baselineskip}
\optitem{math}{\prm{math  font}\prm{suboptions}}

\optitem[default]{symbolstypeface}{\prm{symbols font}\prm{suboptions}}\vspace{-\baselineskip}
\optitem{sym}{\prm{symbols font}\prm{suboptions}}

The \opt{mathtypeface} (syn: \opt{math}) and \opt{symbolstypeface} (syn: \opt{sym}) options can be used to set up math and symbols fonts.  See tables \ref{tab:mathopt} and \ref{tab:symopt} for values of \prm{math font} and \prm{symbols font}, respectively. Like other \prm{typeface} options, these lists can be extended by modifying package configuration file \file{typeface.cfg}.

Apart from registering math and symbols typeface print names, \kvopt{mathtypeface}{default} and \kvopt{symbolstypeface}{default} do nothing noticeable at all.

Math and symbols \prm{suboptions} are listed in tables \ref{tab:mathsubopt} and \ref{tab:symsubopt}.

In addition to the functions invoked by these suboptions, math and symbols typefaces can be scaled using the \subopt{scale} suboption with the \opt{mathtypeface} key. As math and symbols fonts are scaled in unison, the \subopt{scale} suboption is ignored, and therefore should not be used, with the \opt{symbolstypeface} key.  The \subopt{scale} suboption only applies to \opt{mathtypeface} options. See section \ref{sec:scaling}, below.

\end{optionlist}

\subsection{Text Figures}
\label{sec:textfigures}

\begin{optionlist}

\optitem[default]{textfigures}{\prm{option}\prm{suboptions}}

This option is used to specify the text figures font configuration. Text figures may be sourced from the typeface established using the \kvopt{typeface}{\prm{roman font}} package option, they may  be sourced from a substitute text figures font, or they may be switched off entirely.

Once configured, the text figures font is selected using the \cmd{textstylenums} command or \env{textnums} environment. The \cmd{liningstylenums} command or \env{liningnums} environment selects the lining style figures font. See section \ref{sec:textnums} for usage.

Text figures \prm{option}s include:
\begin{enumerate}[leftmargin=0em,itemindent=0em,labelsep=0.5em,format=\optlabel]
  \item[default] This option does nothing at all.
  \item[false] (syn: \opt{lf}, \opt{lsf}, \opt{lining}, \opt{liningstyle}, \opt{liningfigures}, \opt{liningstylefigures})

      This option sets  \cmd{rmdefault} to the lining figures variant of the font requested using the \kvopt{typeface}{\prm{roman font}} package option.  Thus, given \kvopt{typeface}{\tfrmfont} and \kvopt{textfigures}{false}, the three lines of code:
      {\lstset{xleftmargin=-2em}\begin{ltxcode}
      12345
      <<\textstylenums>>{12345}
      <<\begin{textnums}>>12345<<\end{textnums}>>
      \end{ltxcode}}\vspace{-\medskipamount}
      each produce \liningstylenums{12345}, that is, \keyword{12345} rendered in \rmprintname's lining style (uppercase) figures typeface variant.

      Note again: the \cmd{textstylenums} command and the \env{textnums} environment generate \emph{lining style figures} if \kvopt{textfigures}{false}.

      On the other hand, no matter what the value of the \opt{textfigures} option, the \LaTeX\space command:
      {\lstset{xleftmargin=-2em}\begin{ltxcode}
      <<\oldstylenums>>{12345}
      \end{ltxcode}}\vspace{-\medskipamount}
      will use the font's text figures (lowercase) variant, if it exists, to produce \oldstylenums{12345}.

      Note that in a few rare cases, the selected roman font cannot render true lining figures. Examples include Day Roman and Auriocus Kalligraphicus typefaces. An error will be issued if \kvopt{textfigures}{false} is specified under these circumstances.

  \item[true] (syn: \opt{osf}, \opt{oldstyle}, \opt{oldfigures}, \opt{oldstylefigures}, \opt{textfigures})\\
      This option sets \cmd{rmdefault} to the text figures variant of the \kvopt{typeface}{\prm{roman font}} font.  Given \kvopt{textfigures}{true}, arbitrary \kvopt{typeface}{\prm{roman font}}, and input string:
      {\lstset{xleftmargin=-2em}\begin{ltxcode}
      12345
      \end{ltxcode}}\vspace{-\medskipamount}
      the output will be typeset using the text style figures font variant (\textstylenums{12345}) if and only if \prm{roman font} is natively capable of supplying these glyphs. Fortunately, several roman fonts are capable of this. Unfortunately, many more are not.

      The following lines of code:
      {\lstset{xleftmargin=-2em}\begin{ltxcode}
      <<\textstylenums>>{12345}
      <<\begin{textnums}>>12345<<\end{textnums}>>
      \end{ltxcode}}\vspace{-\medskipamount}
      are semantically identical. If \prm{roman font} is natively capable of rendering text style figures, output is the same as that immediately above (\textstylenums{12345}). If not, that is, if input \texttt{12345} produces \liningstylenums{12345}, then \texttt{\string\textstylenums\{12345\}} and \texttt{\string\begin\{textnums\}12345\string\end\{textnums\}} will attempt to generate text style figures by sourcing glyphs from the font's \keyword{TS1}-encoded or \keyword{smallcaps} character sets. Around one half of the roman fonts managed by \sty{typeface} succeed with this approach, leaving around a final one third unable to produce text figures from their own font sets in any shape or form.  An error will be issued if the \kvopt{textfigures}{true} option is specified in these instances.

      No matter what these outcomes, the command:
      {\lstset{xleftmargin=-2em}\begin{ltxcode}
      <<\liningstylenums>>{12345}
      \end{ltxcode}}\vspace{-\medskipamount}
      will, as described above, attempt to typeset its argument using the font's lining figures variant.

  \item[\prm{substitute font}] This option provides a last ditch technique for typesetting text figures in cases when the \kvopt{typeface}{\prm{roman font}} document font provides no other means for doing so.  Substitute text figures should be used carefully, that is, with keen attention for blending in with the established \cmd{rmdefault} font.  Perfect seamlessness may be difficult to achieve. In any event, the mere attempt will certainly provoke  derision by typographical purists.  Life can be hard.

      \prm{substitute font} may be one of the following:
  \begin{itemize}[leftmargin=4em,noitemsep,format=\optlabel]
    \item[adobeminionpro]  also accepting suboption \subopt{tabular} (syn: \subopt{tab}) for tabular, that is, monospaced figures
    \item[dayroman]  (syn: \opt{dayrom})
    \item[kpfonts]  (syn: \opt{kp},  \opt{kepler}),  also accepting suboption \subopt{light} for a lighter weight font
    \item[latinmodern]  (syn: \opt{lm},  \opt{lmodern})
    \item[libertine]
    \item[lucidabright]  (syn: \opt{lucidabr},  \opt{lucida})
    \item[palatino]
    \item[times]
  \end{itemize}
  In these cases, arguments of the \cmd{textstylenums} command or \env{textnums} environment:
  {\lstset{xleftmargin=0em}\begin{ltxcode}
  <<\textstylenums>>{12345}
  <<\begin{textnums}>>12345<<\end{textnums}>>
  \end{ltxcode}}\vspace{-\medskipamount}
  will be typeset in the nominated substitute font. All other text will be rendered in the non-substitute typeface. This includes figures passed to the \cmd{liningstylenums} command or the \env{liningnums} environment, and all output generated while \cmd{sffamily} or \cmd{ttfamily} selections are in force.

  \begin{enumerate}[leftmargin=0em,itemindent=0em,labelsep=0.5em]
  \item[\emph{Caveat}:] Advanced usage. The inter-character spacing, inter-unit kerning and the overall scaling of substitute text figures will generally require fine-tuning to promote seamless integration with the surrounding roman text. The following suboptions provide the means for making some very fine-grained adjustments:
    \begin{itemize}[leftmargin=4em,noitemsep,format=\optlabel,midpenalty=10000]
      \item[scale:\prm{scale factor}] adjust the size of the substitute text figures font
      \item[spacing:\prm{adjustment}] adjust the substitute text figures font inter-character spacing
      \item[lkern:\prm{adjustment}]   kern the space preceding the substitute text figures block
      \item[rkern:\prm{adjustment}]   kern the space after the substitute text figures block
    \end{itemize}
    Substitute text figures font scaling is described in section \ref{sec:scaling}, below.

    The \subopt{spacing}, \subopt{lkern} and \subopt{rkern} suboptions rely on the \sty{microtype} package for the fine-grained adjustments they provide.  Consequently, they cannot be applied unless \sty{microtype} is loaded before loading \sty{typeface}. The \prm{adjustment} parameter of these suboptions accepts integers between $-1000$ and $1000$, inclusive.
  \end{enumerate}
\end{enumerate}

\end{optionlist}

\subsection{Font Scaling}
\label{sec:scaling}

\begin{optionlist}

\varitem[ex]{typeface}{\prm{typeface name}\prm{suboptions}[\opt{:scale}\prm{scale factor}]\prm{suboptions}}

\begin{enumerate}[labelsep=0.5em,noitemsep,format=\optlabel,midpenalty=10000]
  \item[\prm{typeface}] Package option \opt{sanstypeface}, \opt{monotypeface}, \opt{mathtypeface}, \opt{textfigures} or any of their synonyms.
  \item[\prm{typeface name}] Any typeface name accepted by \prm{typeface}.
  \item[\prm{suboptions}] Zero or more \subopt{:\prm{suboption}} terms accepted by the \kvopt{\prm{typeface}}{\prm{typeface name}} tuple.
  \item[\prm{scale factor}] Optional: preceded by a colon separator, \subopt{ex}, \subopt{uppercase}, \subopt{lowercase}, \subopt{figures} or any positive real number.
\end{enumerate}

Scaling defaults to \opt{ex} if the \opt{scale}\prm{scale factor} suboption is not included among \prm{typeface} suboptions or if \prm{scale factor} is empty.

The \subopt{scale} suboption scales \prm{typeface name} by an absolute or reference font relative amount. In all cases, the reference font is the font loaded by the \kvopt{typeface}{\prm{roman font}} package option.

Reference font relative scaling parameters include:

\begin{enumerate}[labelsep=0.5em,noitemsep,format=\optlabel,midpenalty=10000]
  \item[ex] the ex-height of \prm{typeface name} is auto-scaled to the ex-height of the reference font
  \item[uppercase] (syn: \subopt{uc}) the height of full-ascender uppercase characters in \prm{typeface name} is auto-scaled to the height of full-ascender uppercase characters in the reference font
  \item[lowercase] (syn: \subopt{lc}) the height of full-ascender lowercase characters in \prm{typeface name} is auto-scaled to the height of full-ascender lowercase characters in the reference font
  \item[figures]   (syn: \subopt{fig}) the height of numerals in \prm{typeface name} is auto-scaled to the height of numerals in the reference font
\end{enumerate}

Scaling parameters \subopt{uppercase}, \subopt{lowercase}, \subopt{figures} and synonyms do not apply, and will be rejected, whenever \prm{typeface} is \opt{textfigures}.

Font scaling, whether by absolute or reference font relative amounts, is not guaranteed.  Much depends on the quality of the internal font metrics in the installed \typei fonts\footnote{Extant varieties of \sty{biolinum sans} \typei provide particularly egregious examples of poor internal font metrics. Unless recently fixed, users should stick to scaling \sty{biolinum sans} by absolute and not reference font relative amounts.}, or on the load time information in their font descriptor \file{.fd} files.  The supplied test harness and font exhibits file might prove useful for determining individual font scaling capabilities (see section \ref{sec:pkgcontents}, above).

\end{optionlist}

\subsection{Font Load Order}
\label{sec:loadorder}

\begin{optionlist}

\optitem[default]{fontloadorder}{\prm{load order list}}

\begin{enumerate}[leftmargin=0em,itemindent=0em,labelsep=0.5em]
  \item[\emph{Caveat}:] Advanced usage. You probably do not want to use this option in any serious way. It can cause no end of trouble.
\end{enumerate}

\sty{Typeface}'s default font load order is \opt{textfigures:symbols:math:rm:sf:tt}. That is, the substitute text figure font, if specified, is loaded, then the symbols, math, roman, sans serif, and teletype fonts in succession.

Internally, much of \sty{typeface}'s work involves orchestrating font package loading to achieve the user's intended results. In addition to the primary fonts they load, many font packages also load a range of complementary fonts, ostensibly to provide greater value for their users. This situation introduces considerable potential for downstream font loading conflicts when, rather than wanting to use the package's complementary typeface choices, one would prefer to match other typefaces with the package's primary font instead. Font package loading nonorthogonalities can be particularly troublesome between symbols and math or between math and roman choices.  The \sty{typeface} package does its best to insulate users from these problems. On extremely rare occasions, however, better results might be obtained by adjusting \sty{typeface}'s inbuilt font load order rule to suit.

All six terms must be included in the colon-separated \prm{load order list}. However, be mindful that \opt{fontloadorder} is ``more what you'd call `guidelines' than actual rules''---the font load order cannot always be rearranged, no matter what your instruction.

Example: symbols will \emph{probably} be loaded after math fonts rather than before them by specifying \kvopt{fontloadorder}{textfigures:math:symbols:rm:sf:tt}.

Take this option with a grain of salt---it is there should you need it. However, you should best avoid it if you can.

\end{optionlist}

\subsection{Ancillary Packages}

\begin{optionlist}

\makeatletter
\label{sec:enc}
\optitem[\TF@DEFAULTFONTENCODING]{fontencoding}{\subopt{default}\OR\subopt{dontload}\OR\subopt{ignore}\OR\prm{fontencodings list}}\vspace{-\baselineskip}
\optitem[\TF@DEFAULTINPUTENCODING]{inputencoding}{\subopt{default}\OR\subopt{dontload}\OR\subopt{ignore}\OR\prm{inputencoding}}\vspace{-\baselineskip}
\optitem[\TF@DEFAULTTEXTCOMP]{textcomp}{\subopt{default}\OR\subopt{dontload}\OR\subopt{ignore}\OR\prm{textcomp}}\vspace{-\baselineskip}
\optitem[\TF@DEFAULTCMAP]{cmap}{\subopt{default}\OR\subopt{dontload}\OR\subopt{ignore}\OR\subopt{resetfonts}\OR\subopt{noresetfonts}}
\makeatother

The \sty{typeface} package loads the \sty{fontenc}, \sty{inputenc}, \sty{textcomp} and  \sty{cmap}\footnote{The \sty{cmap} option might be withdrawn in an upcoming ``release'' version.  Alternatively, it might be replaced by an option for  loading \file{glyphtounicode.tex}.  Bearing in mind that \sty{typeface's} principal constituency is novice \LaTeX\space users, ideas about the best way to proceed would be warmly welcomed by the author.} packages by default. Descriptions of these can be found in many places, for example, in the UK \TeX\space FAQ.\fnurl{http://www.tex.ac.uk/faq} \sty{Typeface} will not load these packages if \opt{dontload} or \opt{ignore} are supplied. Default values and the sets of valid parameters can be reconfigured by modifying \file{typeface.cfg} as described in section \ref{sec:config}, below.

The \opt{fontencoding} option accepts a colon-separated list of font encodings. In processing these, the \sty{fontenc} package records the last item in the list in \cmd{encodingdefault}.

\end{optionlist}

\subsection{Package Testing}

\begin{optionlist}

\optitem[false]{debug}{\subopt{true}\OR\subopt{false}}

If \kvopt{debug}{true}, the \sty{typeface} package writes extra load-time and run-time processing information in the job log file.  It also colour-codes output text according to selected font family. The short form \opt{debug} is equivalent to \kvopt{debug}{true}.  Debug colours can be reconfigured by modifying \file{typeface.cfg}.

\optitem[false]{printinfo}{\subopt{true}\OR\subopt{false}}

Package test harness \file{typeface-test.tex} provides a useful testbed for exploring and testing various font scenarios. The \sty{typeface} package exposes several commands for supporting this if \kvopt{printinfo}{true}. The short form \opt{printinfo} is equivalent to \kvopt{printinfo}{true}.

The following commands become available when \kvopt{printinfo}{true}:

\begin{enumerate}[leftmargin=5em,labelsep=0.5em,noitemsep,format=\optlabel,beginpenalty=5000,midpenalty=10000]
  \item[\cmd{tfprintpackageoptions}] Prints current package option values.
  \item[\cmd{tfprintinfo}] Prints roman, substitute text figures (if specified), sans serif, teletype, math and symbols typeface information, including \TeX\space font name, em size, ex height, and scale factor metrics.
  \item[\cmd{tfprinttext\{\#1\}}] Prints a small exhibit of alphanumeric text in different shapes and weights. Text is drawn from \opt{\#1} family where \opt{\#1} may be \opt{rm}, \opt{sf} or \opt{tt}.
  \item[\cmd{tfprintfigures\{\#1\}}] Prints a small exhibit of numeric text in different shapes and weights, including output from \env{math}, \env{liningnums} and \env{textnums} environments and from \cmd{textstylenums} and \cmd{oldstylenums} commands. Figures are drawn from \opt{\#1} family, given \opt{\#1} contains \opt{rm}, \opt{sf} or \opt{tt}.
  \item[\cmd{tfprintmathsample\{\#1\}}] Prints a small block of math-oriented prose, including calligraphic, blackboard and greek fonts where defined. Text is drawn from \opt{\#1} family, with \opt{\#1} being \opt{rm}, \opt{sf} or \opt{tt}.
  \item[\cmd{tfprintmathfonts}] Prints a 16 element vector of math family \TeX font names.
  \item[\cmd{tfprinttextsample\{\#1\}}] Prints a small block of prose. Text is drawn from \opt{\#1} family where \opt{\#1} is \opt{rm}, \opt{sf} or \opt{tt}.
  \item[\cmd{tfprinttextalphabets}] Prints \opt{math}, \opt{rm}, \opt{sf} and \opt{tt} intermixed lines of lowercase, uppercase and numeric text. Useful for comparing relative print sizes across different font families.
  \item[\cmd{tfprintinfopage}] Executes several of the commands described above.
\end{enumerate}

See \file{typeface-all-rm.pdf}, the font exhibits file included with this package for example usage of these commands.

\end{optionlist}

\section{Author Commands}


\subsection{Text and Lining Figures}
\label{sec:textnums}

The \sty{typeface} package provides very few author-level commands. Those that it provides include commands and environments for switching between text and lining figures:

\begin{enumerate}[leftmargin=4em,labelsep=0.5em,noitemsep,format=\optlabel,beginpenalty=5000,midpenalty=10000]
  \item[\cmd{textstylenums}] This command is a homologue of \LaTeX's native \cmd{oldstylenums}. Unlike \cmd{oldstylenums}, \cmd{textstylenums} renders text style figures if:
  \begin{enumerate}[noitemsep]
    \item package option \kvopt{textfigures}{true} (or a synonym for such) and the roman font established by setting \kvopt{typeface}{\prm{roman font}} provides text figures natively, via \keyword{TS1}-encoding or through smallcaps selection; \emph{or}
    \item package option \kvopt{textfigures}{\prm{substitute font}}.
  \end{enumerate}

  However, \cmd{textstylenums} generates \emph{lining style figures} if \kvopt{textfigures}{false} (or a synonym for such). The result is indeterminate if \kvopt{textfigures}{default}.

  \item[\env{textnums}] The \env{textnums} environment is semantically equivalent to the \cmd{textstylenums} command.
  \item[\cmd{liningstylenums}] This command provides a reciprocal of sorts to \cmd{textstylenums}. In all but a few exceptional cases, its argument will be rendered in lining style figures font.
  \item[\env{liningnums}] The \env{liningnums} environment is semantically equivalent to the \cmd{liningstylenums} command.
\end{enumerate}

While their use is not particularly recommended, the commands \cmd{tsn} and \cmd{lsn} can be used in place of \cmd{textstylenums} and \cmd{liningstylenums}.
\np%
See section \ref{sec:textfigures} for information about configuring text figure fonts.

\subsection{Typeface Print Names}
\label{sec:printname}

Typeface print names can be accessed with the following commands:

\begin{ltxcode}
<<\rmprintname>>
<<\sfprintname>>
<<\ttprintname>>
<<\mathprintname>>
<<\symbolsprintname>>
<<\textfiguresprintname>>
\end{ltxcode}

For example, using \cmd{rmprintname} in this manual produces \keyword{\rmprintname}.  All bets are off if the user or some package modified \cmd{rmdefault}, \cmd{sfdefault}, etcetera after \sty{typeface} was loaded.

\section{Package Configuration}
\label{sec:config}

The \sty{typeface} package was developed with locale and institution specific customisations in mind. Customisation is carried out by modifying the \file{typeface.cfg} file. A sample \file{typeface.cfg} file is bundled with this package.
\np%
Note: \file{typeface.cfg} is loaded early during \sty{typeface} package processing. At that time, it has complete freedom to access or introduce new \sty{typeface} package commands. Due care should be applied. Many of \sty{typeface}'s internal commands contain the \keyword{@} character in their names. There is no need to, and therefore you should not, wrap \keyword{@}-containing identifiers between \cmd{makeatletter} and \cmd{makeatother} parse-time modifiers.

\subsection{Typeface Options}

Each of the six \opt{typeface} option defaults can be redefined. Here are some (typographically dubious) examples:

\begin{ltxcode}
\renewcommand*<<\TF@DEFAULTRMFONT>>{kpfonts:veryoldstyle:largesmallcaps}
\renewcommand*<<\TF@DEFAULTSFFONT>>{helv:scale:0.75}
\renewcommand*<<\TF@DEFAULTTTFONT>>{luxi:scale:lowercase}
\renewcommand*<<\TF@DEFAULTMATHFONT>>{iwona:light:condensed}
\renewcommand*<<\TF@DEFAULTSYMBOLSFONT>>{ams}
\renewcommand*<<\TF@DEFAULTTEXTFIGURESFONT>>{palatino:spacing:20:lkern:-20}
\end{ltxcode}

Observe that these definitions literally substitute for default user package options. Accordingly, note that list separators are colons and not commas.
\np%
Extra code can be executed immediately before and/or after each typeface family is loaded. To do so, define
\cmd{beforeloading}\prm{fam} and/or \cmd{afterloading}\prm{fam} in \file{typeface.cfg}. Here, \prm{fam} is any of \opt{textfigures}, \opt{symbols}, \opt{math}, \opt{rm}, \opt{sf} or \opt{tt}.
\np%
For example:
\begin{ltxcode}
\newcommand*<<\beforeloadingmath>>{
  \ifthenelse{\equal{\tf@mathfont}{amsfonts}}{
    % undefine the following to prevent amsfonts namespace clashes
    \tf@undefinecommands{\underrightarrow,\underleftarrow}
    \TF@PackageDebugInfoNoLine[\TF@CONFIGFILE]{%
      Blew away \string\underrightarrow\space and
      \string\underleftarrow\MessageBreak
      symbols before loading amsfonts package}
  }{}
}
\end{ltxcode}


\subsection{Ancillary Package Options}

Ancillary package option defaults can be configured in \file{typeface.cfg}.  For example:

\begin{ltxcode}
\renewcommand*<<\TF@DEFAULTFONTENCODING>>{EU1:T1}
\renewcommand*<<\TF@DEFAULTINPUTENCODING>>{dontload}
\renewcommand*<<\TF@DEFAULTTEXTCOMP>>{safe}
\renewcommand*<<\TF@DEFAULTCMAP>>{ignore}
\end{ltxcode}

Extra choices can be added to \sty{typeface}'s \opt{fontencoding} and \opt{inputencoding} package options lists. For example, suppose you wanted to make (fictitious) \opt{K9} and \opt{K10} font encodings available to \sty{typeface} package users. Then, after ensuring \file{k9enc.def} and \file{k10enc.def} encoding files are installed, simply include:

\begin{ltxcode}
\renewcommand*<<\tf@fontencodingchoices>>{K9,K10}
\end{ltxcode}

in \file{typeface.cfg}. Similarly, use \cmd{tf@inputencodingchoices} to add more options to \sty{typeface}'s inbuilt \opt{inputencoding} choice list.


\subsection{\cmd{newtypeface} Command}
\label{sec:newtypeface}

The \cmd{newtypeface} command can be used to place additional \typei fonts under \sty{typeface} package access management. This command takes one optional and four mandatory arguments:

\begin{enumerate}[labelsep=0.5em,noitemsep,format=\small\texttt,beginpenalty=5000,midpenalty=10000]
\item[\#1] optional comma-separated list of typeface name aliases (enclose in square brackets)
\item[\#2] primary typeface name
\item[\#3] human-readable print name, accessible through commands outlined in section \ref{sec:printname}
\item[\#4] typeface family: \opt{rm}, \opt{sf}, \opt{tt}, \opt{math}, \opt{symbols} or \opt{textfigures}
\item[\#5] typeface initialisation code
\end{enumerate}

\example{1}

\begin{ltxcode}
% Adobe Bembo
<<\newtypeface>>[bembo]{adobebembo}{Adobe Bembo}{rm}{
  \renewcommand*\rmdefault{pbb}
  <<\tf@SCencodedosf>>
}
\end{ltxcode}

Assuming Adobe Bembo is installed on the system and accessible by its \keyword{pbb} Berry font name, \sty{typeface} users can now set their document's default roman font to Adobe Bembo using options \kvopt{typeface}{adobebembo} or \kvopt{typeface}{bembo}. Text figures will be selected from Adobe Bembo's smallcaps font.
\np%
Text figures declarations like \cmd{tf@SCencodedosf} apply only to \cmd{newtypeface} \opt{rm} definitions. Four commands are available for text figures configuration:

\begin{enumerate}[labelsep=0.5em,noitemsep,format=\optlabel,beginpenalty=5000,midpenalty=10000]
  \item[\cmd{tf@TSencodedosf}]   Source text figures via \keyword{TS1} font encoding
  \item[\cmd{tf@SCencodedosf}]   Source text figures by switching to smallcaps
  \item[\cmd{TF@NativeOSFError}] Advise user that the selected font does not accept package option \kvopt{textfigures}{true}
  \item[\cmd{TF@NativeLFError}]  Advise user that the selected font \emph{requires} package option \kvopt{textfigures}{true} (in practice, this is very rare)
\end{enumerate}

Absent these declarations, text figures are assumed to be natively available in the requested roman font.  Nevertheless, without further configuration, the \cmd{textstylenums} and \cmd{liningstylenums} commands (resp: the \env{textnums} and \env{liningnums} environments) do very little at all. Therefore, at a minimum, you should specify the font's text figures and lining figures configuration. One way of doing this is shown below:

\clearpage% manual adjustment - remove if things change

\example{2}

\begin{ltxcode}
% Adobe Sabon
<<\newtypeface>>[sabon]{adobesabon}{Adobe Sabon}{rm}{
  \ifthenelse{\equal{<<\tf@osf@method>>}{<<\TF@OSF@JF>>}}{
    \renewcommand*\rmdefault{psbj}  % Native old style figures
    <<\tf@define@liningfigures>>{psb}
  }{
    \renewcommand*\rmdefault{psb}   % Native lining figures
  }
}
\end{ltxcode}

By the time \cmd{newtypeface} \keyword{rm} initialisation code is reached, internal macro \cmd{tf@osf@method} will have been initialised with one of the following four values\footnote{\cmd{tf@osf@method} initialisation occurs during \opt{textfigures} option processing. This processing will not have taken place before \cmd{newtypeface} \keyword{rm} initialisation code is executed if \subopt{rm} precedes \subopt{textfigures} in package option \opt{fontloadorder} (another reason to use this option with great care---see section \ref{sec:loadorder}).  In that event, \cmd{tf@osf@method} will expand to \cmd{TF@OSF@NF}.}:

\begin{enumerate}[labelsep=0.5em,noitemsep,format=\optlabel,beginpenalty=5000,midpenalty=10000]
  \item[\cmd{TF@OSF@LF}] the user set package option \kvopt{textfigures}{false} (or synonym)
  \item[\cmd{TF@OSF@JF}] the user set package option \kvopt{textfigures}{true} (or synonym)
  \item[\cmd{TF@OSF@XF}] the user set package option \kvopt{textfigures}{\prm{substitute font}}
  \item[\cmd{TF@OSF@NF}] the user has implicitly or explicitly set package option \kvopt{textfigures}{default}
\end{enumerate}

Thus, in this example, we set the document's default roman font to \keyword{psbj} (Adobe Sabon with old style figures) and the lining figures font to \keyword{psb} (Adobe Sabon with lining style figures) whenever the user sets \kvopt{textfigures}{true}, and to \keyword{psb} otherwise.

\example{3}

\begin{ltxcode}
% Adobe Myriad Pro
<<\newtypeface>>{adobemyriadpro}{Adobe Myriad Pro}{sf}{
  <<\tf@ifsuboption>>{<<osf>>}{<<\tf@sffontoptions>>}{
    % Myriad Pro has an OSF variant (depending on your installation)
    \renewcommand*\sfdefault{Myriad-OsF}
    \xdef\tf@sfprintname{\tf@sfprintname\ OSF}
  }{
    \renewcommand*\sfdefault{Myriad-LF}
  }
}
\end{ltxcode}

We set up sans serif font Adobe Myriad Pro in this example. This \keyword{sf} font is quite unusual in possessing lining and old style figures variants. We allow users their choice with this by testing for \opt{sanstypeface} suboption \subopt{osf} in the \cmd{newtypeface} code, initialising the font and its print name appropriately.
\np%
Note that we did nothing special to enable \keyword{rm} font relative scaling in this case.  The \sty{typeface} package automatically handles this in (most) cases where the corresponding \keyword{sf} or \keyword{tt} font descriptor \file{.fd} file \emph{does not} contain scaling instructions.\footnote{Compare PXFonts Sans \file{t1pxss.fd} which does not contain scaling instructions and Helvetica \file{t1phv.fd} which contains scaling machinery. The \cmd{newtypeface} command automatically accommodates typeface scaling in the former case without special intervention. However, we must provide the \cmd{newtypeface} command explicit instruction about how to initialise scaling in the latter case.  This is explored in examples 4 and 5.}

% \clearpage% manual adjustment - remove if things change

\example{4}

\begin{ltxcode}
% Helvetica
<<\newtypeface>>[helv]{helvetica}{Helvetica}{sf}{
  <<\scaletypeface>>{sf}
    {\PassOptionsToPackage{scaled=<<\tf@sfscalefactor>>}{helvet}}
  <<\tf@usefontpackage>>{helvet}
}
\end{ltxcode}

In this example, using \sty{typeface}'s \cmd{scaletypeface} command, we simply pass the font family appropriate scale factor, \cmd{tf@sfscalefactor}, to the \opt{scaled} option in the \sty{helvet} package.
\np%
Note that \sty{typeface} command \cmd{tf@usefontpackage} is an instrumented version of \cmd{usepackage}. It should be used whenever loading font packages (and only then) since it facilitates debug information logging whenever package option \kvopt{debug}{true}.

\example{5}

\begin{ltxcode}
% Helvetica
<<\newtypeface>>[helv]{helvetica}{Helvetica}{sf}{
  <<\scaletypeface>>{sf}{\newcommand*\Hv@scale{<<\tf@sfscalefactor>>}}
  \renewcommand*\sfdefault{phv}
}
\end{ltxcode}

We take an alternative approach to sans serif font scaling configuration in this example. As outlined in example 4, internal \sty{typeface} command  \cmd{scaletypeface} accepts any scaling code eventually recognised by the target font definition (\file{.fd}) file.  Here, we initialise \cmd{Hv@scale} to \sty{typeface}'s pre-computed sans serif font scale factor and specify the font we want in \cmd{sfdefault}. Again, there is no more to do in order to set up reference font (\keyword{rm}) relative scaling for \keyword{sans serif} and \keyword{teletype} fonts.

\example{6}

\begin{ltxcode}
% Adobe Sabon text figures
<<\newtypeface>>[sabon]{adobesabon}{Adobe Sabon}{textfigures}{
  <<\tf@initialisetextfiguresfont>>{T1}
  <<\tf@DeclareOsfFontShape>>{m}{n}  {psbr9d}
  <<\tf@DeclareOsfFontShape>>{m}{sc} {psbrc9d}
  <<\tf@DeclareOsfFontShape>>{m}{it} {psbri9d}
  <<\tf@DeclareOsfFontShape>>{m}{sl} {psbri9d}
  <<\tf@DeclareOsfFontShape>>{b}{n}  {psbb9d}
  <<\tf@DeclareOsfFontShape>>{b}{it} {psbbi9d}
  <<\tf@DeclareOsfFontShape>>{b}{sl} {psbbi9d}
  <<\tf@DeclareOsfFontShape>>{bx}{n} {psbb9d}
  <<\tf@DeclareOsfFontShape>>{bx}{it}{psbbi9d}
  <<\tf@DeclareOsfFontShape>>{bx}{sl}{psbbi9d}
}
\end{ltxcode}

This example demonstrates how to set up a new text figures typeface. This task requires just two commands. First, we declare the text figures font encoding using \cmd{tf@initialisetextfiguresfont}. That done, we transliterate the information from the appropriate font descriptor (\file{.fd}) file\footnote{In our case, turning to file \file{t1psbj.fd} for the required values.} into a series of \cmd{tf@DeclareOsfFontShape} commands.
\np%
Further examples of \cmd{newtypeface} usage can be found in the bundled configuration file and, of course, in package file \file{typeface.sty} itself.

\subsection{Redefining Predefined Typefaces}

\sty{Typeface} package typeface definitions might not always be what you want them to be. In such cases, you can override \sty{typeface}'s inbuilt \cmd{newtypeface} declarations by defining and saving new versions in \file{typeface.cfg}.  Simply use the \cmd{newtypeface} command as before, the only requirement being that, to override an internal \cmd{newtypeface} definition, you must use the same key identifier {\small{\keyword{\#2}}} (the primary typeface name) and {\small{\keyword{\#4}}} (the typeface family) in your new typeface declaration.

\clearpage% manual adjustment - remove if things change

\section{Revision History}

\begin{changelog}

\begin{release}{0.1}{2012-06-18}

\item Initial release for comments (pre-release).

\end{release}

\end{changelog}

\end{document}