\documentclass{beerydoc}


\begin{document}


\section*{\stepfontsize{1}The \pkg{fontscale} package}

A flexible interface for setting font sizes

Oliver Beery

Version 5.0.0\quad 17 February 2026


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

\subsection{About}
\label{subsec:about}

\listheading
  {The \pkg{fontscale} package provides the following functionalities:}
\begin{itemize}
  \item
  Set font sizes using a classic or musical typographic scale.
  \item
  Set arbitrary font sizes and font baselineskips for the standard \LaTeX{}
  font size commands: \cs{tiny}, \cs{scriptsize}, \cs{footnotesize},
  \cs{small}, \cs{normalsize}, \cs{large}, \cs{Large}, \cs{LARGE}, \cs{huge},
  and \cs{Huge}.
  \item
  Defines lengths that store the current font size, font baselineskip, and the
  font size of \cs{normalsize}.
  \item
  Set the font size relative to the current font size using more robust tools
  than the \pkg{scalefnt} and \pkg{relsize} packages.
  \item
  Defines \pkg{expl3} variables that store the font size and font baselineskip
  of each font size command from \cs{tiny} to \cs{Huge} and the current font
  size and font baselineskip.
\end{itemize}

\subsection{Loading the package}
\label{subsec:loading}

\listheading{Requirements:}
\begin{itemize}
  \item \LaTeXe{} version 2023-11-01 or newer
  \item \pkg{l3kernel} version 2023-11-01 or newer
\end{itemize}

For historical reasons, the Computer Modern font is available only in a number
of discrete font sizes.
If you get a warning that Computer Modern is not available in the requested
size, you may need to add the following code before \cs{documentclass} to make
Computer Modern available at arbitrary font sizes:
\begin{verbatim}
\RequirePackage{fix-cm}
\end{verbatim}
Alternatively, you can use the Latin Modern font by loading the \pkg{lmodern}
package.

When loaded, this package uses \cs{normalsize} after declaring and initializing
the font size commands from \cs{tiny} to \cs{Huge}.

Many \LaTeX{} classes have a font size option (e.g. \key{10pt}, \key{11pt},
\key{12pt}) which not only changes the font sizes, but also modifies additional
settings such as the page layout and vertical spacing which were specifically
designed to work with those font sizes.
For this reason, you may want to set the class font size option close to the
font size of \cs{normalsize} set by this package.

\subsection{The font size commands from \cs{tiny} to \cs{Huge}}
\label{subsec:names}

\begin{code}
  {
    \tiny,
    \scriptsize,
    \footnotesize,
    \small,
    \normalsize,
    \large,
    \Large,
    \LARGE,
    \huge,
    \Huge,
    \@currsize
  }
  \listheading
    {
      The font size commands from \cs{tiny} to \cs{Huge} defined by this
      package:
    }
  \begin{itemize}
    \item
    First set \cs{@currsize} to have the same meaning as the font size command.
    This is needed only for backwards compatibility.
    \item
    Set the font size and font baselineskip using \cs{fontsize} and
    \cs{selectfont}.
    You can change the font sizes and font baselineskips that are set by the
    font size commands by setting the \pkg{fontscale} package keys
    (\S\ref{sec:keys}).
    (The font baselineskip should not be confused with the paragraph
    baselineskip
    \cs{baselineskip}.)
    \item
    Cannot be used in math mode.
    \item
    Have no other functionality.
    In particular, they do not change the vertical spacing for displayed math
    and list structures.
    This differs from the font size commands defined by many \LaTeX{} classes.
    You can add arbitrary code to the font size commands using hooks, which are
    documented in \pkg{lthooks} and \pkg{ltcmdhooks}.
  \end{itemize}
\end{code}

\subsection{Syntax}
\label{subsec:syntax}

This documentation uses the syntaxes listed below.
The syntaxes on the left have the same meaning as the argument to the
corresponding command on the right.
The commands on the right are documented in \pkg{usrguide}.
\input{fontscale-syntax.tex}


\section{Keys}
\label{sec:keys}

This section documents the keys provided by the \pkg{fontscale} package.
Set the package keys using \cs{fontscalesetup} (\S\ref{subsec:setup}).

\subsection{The key \key{typographic-scale}}
\label{subsec:typographicscale}

The font sizes of the font size commands from \cs{tiny} to \cs{Huge} are
initially set by the key \key{typographic-scale}.

\begin{code}{typographic-scale}
  \begin{syntax}
    \key{typographic-scale=\choices{classic,musical}}
  \end{syntax}
  Choice key that sets the font size of each font size command from \cs{tiny}
  to \cs{Huge} using a classic or musical typographic scale.
  These are common methods of choosing a set of document font sizes.
  The initial value is \key{=classic}.
\end{code}

\begin{code}{classic, musical}
  Meta keys that set the key \key{typographic-scale} to the named value.
\end{code}

\subsubsection{The classic typographic scale}
\label{subsubsec:classictypographicscale}

\begin{code}{classic/base, classic/point}
  \begin{syntax}
    \key{classic/base=\choices{10,11,12}}
    \key{classic/point=\choices{pt,bp,dd,nd}}
  \end{syntax}
  Setting the key \key{typographic-scale=classic} sets the font size of each
  font size command from \cs{tiny} to \cs{Huge} using the classic typographic
  scale.
  The classic typographic scale consists of the traditional font sizes in units
  of points:%
  \footnote
    {See \textit{The Elements of Typographic Style} by Robert Bringhurst.}
  \input{fontscale-classic-list.tex}%
  They have been used since the sixteenth century and are the default font
  sizes on some computer software.

  The choice key \key{classic/base} sets the base font size of the classic
  typographic scale to the named value in units of points.
  The base font size is the font size of \cs{normalsize}.
  The font sizes of the other font size commands are the adjacent font sizes in
  the classic typographic scale in units of points.
  The initial value is \key{=10}.
  The choice key \key{classic/point} sets which \enquote{point} is used.
  The initial value is \key{=pt}.
  Table \ref{table:classic} displays the font size of each font size command
  from \cs{tiny} to \cs{Huge} when setting the key
  \key{typographic-scale=classic}.
\end{code}

\input{./fontscale-table-classic.tex}

\subsubsection{The musical typographic scale}
\label{subsubsec:musicaltypographicscale}

\begin{code}{musical/base, musical/ratio, musical/notes}
  \begin{syntax}
    \key{musical/base=\meta{dimen}}
    \key{musical/ratio=\meta{number}}
    \key{musical/notes=\meta{integer}}
  \end{syntax}
  Setting the key \key{typographic-scale=musical} calculates the font size of
  each font size command from \cs{tiny} to \cs{Huge} using the formula for the
  musical typographic scale:%
  \footnote
    {%
      I have referenced this article by Spencer Mortensen:
      \newline
      \url{https://spencermortensen.com/articles/typographic-scale/}%
    }
  \begin{equation*}
    f_i = f_0 \times r ^ { i / n }
  \end{equation*}
  $f_i$ is the font size of the $i$th note.
  $f_0$ is the base font size.
  $n$ is the number of notes, the number of font sizes above $f_0$.
  $r$ is the musical ratio, the ratio of the highest to the lowest note
  $ f_n / f_0 $.

  The key \key{musical/base} sets the base font size $f_0$ to \meta{dimen}.
  The base font size is the font size of \cs{normalsize}.
  The initial value is \qty{10}{pt}.
  The key \key{musical/ratio} sets the musical ratio $r$ to \meta{number}.
  The initial value is \num{2}.
  The key \key{musical/notes} sets the number of notes $n$ to \meta{integer}.
  The initial value is \num{5}.
  Table \ref{table:musical} displays the font size of each font size command
  from \cs{tiny} to \cs{Huge} when setting the key
  \key{typographic-scale=musical}.
\end{code}

\input{./fontscale-table-musical.tex}

\subsection{The key \key{baselineskip-size-ratio}}
\label{subsec:baselineskipsizeratio}

The font baselineskips of the font size commands from \cs{tiny} to \cs{Huge}
are initially set by the key \key{baselineskip-size-ratio}.

\begin{code}{baselineskip-size-ratio}
  \begin{syntax}
    \key{baselineskip-size-ratio=\meta{number}}
  \end{syntax}
  Sets the font baselineskip of each font size command from \cs{tiny} to
  \cs{Huge} equal to its font size \texttimes{} \meta{number}.
  The initial value is \num{1.2}.
  This key also affects the behavior of \cs{setfontsize}
  (\S\ref{subsec:fontsize}).
\end{code}

\subsection{Overwriting the previous keys}
\label{subsec:overwriting}

This subsection documents keys for setting the font sizes and font
baselineskips of the font size commands from \cs{tiny} to \cs{Huge} in a more
direct manner.

When setting the font sizes, you should take care to ensure that their lengths
remain correctly ordered from \cs{tiny} to \cs{Huge}.
This is important for typographic and syntactic consistency.
If the font sizes are in the wrong order, then \cs{fontscalesetup} will issue a
warning and some package features may not work correctly.

\begin{code}
  {
    tiny/size-normalsize-ratio,
    scriptsize/size-normalsize-ratio,
    footnotesize/size-normalsize-ratio,
    small/size-normalsize-ratio,
    large/size-normalsize-ratio,
    Large/size-normalsize-ratio,
    LARGE/size-normalsize-ratio,
    huge/size-normalsize-ratio,
    Huge/size-normalsize-ratio
  }
  \begin{syntax}
    \key{\meta{font size command}/size-normalsize-ratio=\meta{number}}
  \end{syntax}
  Sets the font size of \cs{\meta{font size command}} equal to the font size of
  \cs{normalsize} \texttimes{} \meta{number}.
  Overwrites the font size set by the key \key{typographic-scale}.
  The initial value is \meta{not set}.
  The key \key{normalsize/size-normalsize-ratio} is not defined.
\end{code}

\begin{code}
  {
    tiny/size,
    scriptsize/size,
    footnotesize/size,
    small/size,
    normalsize/size,
    large/size,
    Large/size,
    LARGE/size,
    huge/size,
    Huge/size
  }
  \begin{syntax}
    \key{\meta{font size command}/size=\meta{dimen}}
  \end{syntax}
  Sets the font size of \cs{\meta{font size command}} to \meta{dimen}.
  Overwrites the font size set by the keys \key{typographic-scale} and
  \key{\meta{font size command}/size-normalsize-ratio}.
  The initial value is \meta{not set}.
\end{code}

\begin{code}
  {
    tiny,
    scriptsize,
    footnotesize,
    small,
    normalsize,
    large,
    Large,
    LARGE,
    huge,
    Huge
  }
  \begin{syntax}
    \key{\meta{font size command}=\meta{dimen}}
  \end{syntax}
  Meta keys that set the key \key{\meta{font size command}/size=\meta{dimen}}.
\end{code}

\begin{code}
  {
    tiny/baselineskip-size-ratio,
    scriptsize/baselineskip-size-ratio,
    footnotesize/baselineskip-size-ratio,
    small/baselineskip-size-ratio,
    normalsize/baselineskip-size-ratio,
    large/baselineskip-size-ratio,
    Large/baselineskip-size-ratio,
    LARGE/baselineskip-size-ratio,
    huge/baselineskip-size-ratio,
    Huge/baselineskip-size-ratio
  }
  \begin{syntax}
    \key{\meta{font size command}/baselineskip-size-ratio=\meta{number}}
  \end{syntax}
  Sets the font baselineskip of \cs{\meta{font size command}} equal to its font
  size \texttimes{} \meta{number}.
  Overwrites the font baselineskip set by the key
  \key{baselineskip-size-ratio}.
  The initial value is \meta{not set}.
\end{code}

\begin{code}
  {
    tiny/baselineskip,
    scriptsize/baselineskip,
    footnotesize/baselineskip,
    small/baselineskip,
    normalsize/baselineskip,
    large/baselineskip,
    Large/baselineskip,
    LARGE/baselineskip,
    huge/baselineskip,
    Huge/baselineskip
  }
  \begin{syntax}
    \key{\meta{font size command}/baselineskip=\meta{skip}}
  \end{syntax}
  Sets the font baselineskip of \cs{\meta{font size command}} to \meta{skip}.
  Overwrites the font baselineskip set by the keys
  \key{baselineskip-size-ratio} and
  \key{\meta{font size command}/baselineskip-size-ratio}.
  The initial value is \meta{not set}.
\end{code}


\section{Commands}
\label{sec:commands}

This section documents the commands provided by the \pkg{fontscale} package.

\subsection{Setting the keys}
\label{subsec:setup}

\begin{code}{\fontscalesetup}
  \begin{syntax}
    \cs{fontscalesetup} \sarg{} \marg{key-value list}
  \end{syntax}
  Sets and processes the \pkg{fontscale} package keys (\S\ref{sec:keys}) in
  \meta{key-value list} and then uses \cs{normalsize}.
  Adding the optional star first sets all the \pkg{fontscale} package keys to
  their initial values.
  All assignments made by \cs{fontscalesetup} are local to the current group.
  Can be used mid-document.
  Cannot be used in math mode.
\end{code}

\subsection{Lengths}
\label{subsec:lengths}

\begin{code}{\currentfontsize}
  Dimen register (rigid length) that stores the current font size.
  This is more convenient than using \cs{f@size}.
\end{code}

\begin{code}{\currentfontbaselineskip}
  Skip register (rubber length) that stores the current font baselineskip.
  This is more convenient than using \cs{f@baselineskip}.
  (The font baselineskip should not be confused with the paragraph baselineskip
  \cs{baselineskip}.)
\end{code}

\begin{code}{\currentnormalsize}
  Dimen register (rigid length) that stores the current font size of
  \cs{normalsize}.
\end{code}

\subsection{More font size commands}
\label{subsec:fontsize}

\begin{code}{\setfontsize}
  \begin{syntax}
    \cs{setfontsize} \oarg{skip} \marg{dimen}
  \end{syntax}
  Sets the font size to \meta{dimen}.
  Sets the font baselineskip to \meta{skip} or, if the optional argument is
  omitted, equal to the new font size \texttimes{} the value of the key
  \key{baselineskip-size-ratio} (\S\ref{subsec:baselineskipsizeratio}).
  Cannot be used in math mode.
  This command is a more robust alternative to \cs{fontsize} + \cs{selectfont}.
\end{code}

\begin{code}{\stepfontsize}
  \begin{syntax}
    \cs{stepfontsize} \marg{integer}
  \end{syntax}
  Increases the font size by an \meta{integer} number of \enquote{steps}.
  Changing the font size by one step means incrementing\slash decrementing from
  a font size equal to the font size of a font size command from \cs{tiny} to
  \cs{Huge} to the next larger\slash smaller \cs{\meta{font size command}} by
  using \cs{\meta{font size command}}.
  Changing the font size by more than one step does not use any intermediate
  \cs{\meta{font size command}}.
  If $\meta{integer}=\num{0}$ and the current font size equals the font size of
  any \cs{\meta{font size command}}, then \cs{stepfontsize} uses
  \cs{\meta{font size command}}.

  \listheading{Some exceptions:}
  \begin{itemize}
    \item
    Issues a warning if the current font size does not equal the font size of
    any font size command from \cs{tiny} to \cs{Huge}.
    \item
    Issues an error if the font size would be changed by more than nine steps.
    \item
    Issues a warning and uses \cs{tiny} if the new font size would be smaller
    than \cs{tiny}.
    \item
    Issues a warning and uses \cs{Huge} if the new font size would be larger
    than \cs{Huge}.
    \item
    Cannot be used in math mode.
  \end{itemize}
\end{code}

\subsection{Setting only the font baselineskip}
\label{subsec:fontbaselineskip}

\begin{code}{\setfontbaselineskip}
  \begin{syntax}
    \cs{setfontbaselineskip} \marg{skip}
  \end{syntax}
  Sets the font baselineskip to \meta{skip}.
  Does not change the font size.
  Cannot be used in math mode.
\end{code}

\subsection{Printing sample text}
\label{subsec:printsampletext}

\begin{code}{\printsampletext}
  \begin{syntax}
    \cs{printsampletext} \sarg{} \marg{text}
  \end{syntax}
  Prints \meta{text} in each font size ordered from \cs{tiny} to \cs{Huge} each
  followed by \cs{par}.
  \meta{text} can contain \cs{par} tokens.
  Adding the optional star reverses the order of the font sizes.
\end{code}

\begin{code}{\printfontsizecommand}
  Prints \cs{\meta{font size command}} if the current font size equals the font
  size of any font size command from \cs{tiny} to \cs{Huge}.
  Otherwise, prints \enquote{\ttfamily\string\undefined}.
  The command name is printed in \cs{ttfamily}.
\end{code}


\section{Programming}
\label{sec:expl3}

This section documents the \pkg{expl3} programming support provided by the
\pkg{fontscale} package.

\subsection{Compatibility with \cs{text_purify:n}}
\label{subsec:textpurify}

This package uses \cs{text_declare_purify_equivalent:Nn} to make
\cs{text_purify:n} correctly remove the text formatting commands defined by
this package.

\subsection{Variables set by \cs{fontscalesetup}}
\label{subsec:varsetup}

\begin{code}
  {
    \l_fontscale_tiny_size_dim,
    \l_fontscale_scriptsize_size_dim,
    \l_fontscale_footnotesize_size_dim,
    \l_fontscale_small_size_dim,
    \l_fontscale_normalsize_size_dim,
    \l_fontscale_large_size_dim,
    \l_fontscale_Large_size_dim,
    \l_fontscale_LARGE_size_dim,
    \l_fontscale_huge_size_dim,
    \l_fontscale_Huge_size_dim
  }
  \begin{syntax}
    \cs{l_fontscale_\meta{font size command}_size_dim}
  \end{syntax}
  Stores the font size of \cs{\meta{font size command}}.
  \cs{l_fontscale_normalsize_size_dim} is equivalent to \cs{currentnormalsize}
  (\S\ref{subsec:lengths}).
\end{code}

\begin{code}
  {
    \l_fontscale_tiny_baselineskip_skip,
    \l_fontscale_scriptsize_baselineskip_skip,
    \l_fontscale_footnotesize_baselineskip_skip,
    \l_fontscale_small_baselineskip_skip,
    \l_fontscale_normalsize_baselineskip_skip,
    \l_fontscale_large_baselineskip_skip,
    \l_fontscale_Large_baselineskip_skip,
    \l_fontscale_LARGE_baselineskip_skip,
    \l_fontscale_huge_baselineskip_skip,
    \l_fontscale_Huge_baselineskip_skip
  }
  \begin{syntax}
    \cs{l_fontscale_\meta{font size command}_baselineskip_skip}
  \end{syntax}
  Stores the font baselineskip of \cs{\meta{font size command}}.
\end{code}

\subsection{Variables set in the \hook{selectfont} hook}
\label{subsec:varselectfont}

\begin{code}{\l_fontscale_size_dim}
  Stores the current font size.
  Equivalent to \cs{currentfontsize} (\S\ref{subsec:lengths}).
\end{code}

\begin{code}{\l_fontscale_baselineskip_skip}
  Stores the current font baselineskip.
  Equivalent to \cs{currentfontbaselineskip} (\S\ref{subsec:lengths}).
\end{code}


\end{document}