[latex3-commits] [latex3/latex2e] develop: Describe \DeclareFont(Series|Shape)ChangeRule macros (#1303) (04632b18)

github at latex-project.org github at latex-project.org
Thu Mar 21 00:48:42 CET 2024 

Repository : https://github.com/latex3/latex2e
On branch  : develop
Link       : https://github.com/latex3/latex2e/commit/04632b180a72c8a67c57725c775a071631f77af1

>---------------------------------------------------------------

commit 04632b180a72c8a67c57725c775a071631f77af1
Author: dr-scsi <59777257+dr-scsi at users.noreply.github.com>
Date:   Thu Mar 21 00:48:42 2024 +0100

    Describe \DeclareFont(Series|Shape)ChangeRule macros (#1303)
    
    * Describe \DeclareFont(Series|Shape)ChangeRule macros
    
    * base/doc/fntguide.tex (subsection{Handling of current and
    requested font series and shape}): New section describing the
    macros \DeclareFontSeriesChangeRule and
    \DeclareFontShapeChangeRule. (#1051)
    
    * Update after review
    
    * base/doc/fntguide.tex (subsection{Handling of current and
    requested font series and shape}): Update after review from FMi.
    
    * Further update after review
    
    * base/doc/fntguide.tex (subsection{Handling of current and
    requested font series and shape}): Offer a more sensible example
    for \DeclareFontSeriesChangeRule and m?.
    Describe \fontseriesforce and \fontshapeforce as well.
    
    * base/doc/ltnews39.tex (subsection{Further updates to the
    guides}): Add a note about updated fntguide.tex.
    
    * Fix typo.
    
    * Final fixes.


>---------------------------------------------------------------

04632b180a72c8a67c57725c775a071631f77af1
 base/doc/fntguide.tex | 81 +++++++++++++++++++++++++++++++++++++++++++++++++--
 base/doc/ltnews39.tex |  8 +++++
 2 files changed, 87 insertions(+), 2 deletions(-)

diff --git a/base/doc/fntguide.tex b/base/doc/fntguide.tex
index 7cf5d239..9a801fc6 100644
--- a/base/doc/fntguide.tex
+++ b/base/doc/fntguide.tex
@@ -42,7 +42,7 @@
 
 \title{\LaTeXe{} font selection}
 
-\author{\copyright~Copyright 1995--2023, \LaTeX\ Project
+\author{\copyright~Copyright 1995--2024, \LaTeX\ Project
   Team.\thanks{Thanks to Arash Esbati for documenting the
     newer NFSS features of 2020}\\
   All rights reserved.%
@@ -52,7 +52,7 @@
    \texttt{fntguide.tex} for full details.}%
 }
 
-\date{October 2023}
+\date{March 2024}
 
 \begin{document}
 
@@ -1997,6 +1997,83 @@ For example,
 would use |sb| (semi-bold) when |\rmfamily\bfseries| is requested in
 document.
 
+\subsection{Handling of current and requested font series and shape}
+
+In the original NFSS implementation, the series was a single attribute
+stored in |\f at series| and so one always had to specify both weight and
+width together.  Hence, it was impossible to typeset a paragraph in a
+condensed font and inside have a few words in bold weight (but still
+condensed) without doing this manually by requesting
+|\fontseries{bc}\selectfont|.
+
+\NEWfeature{2020/02/02}
+The new implementation now works differently by looking both at the
+current value of |\f at series| and the requested new series and out of
+that combination selects a resulting series value.  Thus, if the current
+series is |c| and we ask for |b|, we now get |bc|.  This is done by
+consulting a simple lookup table where entries can be added or changed
+with |\DeclareFontSeriesChangeRule|:
+\begin{decl}
+  |\DeclareFontSeriesChangeRule| %
+  \arg{current series} \arg{requested series} \\
+  \leavevmode\hfill    \arg{result} \arg{alternative result}
+\end{decl}
+
+The \arg{current series} is the value currently stored in |\f at series|,
+\arg{requested series} is the new series requested, \arg{result} is the
+combined value if it exists for the given font family, and
+\arg{alternative result} is a fallback in case \arg{result} doesn't
+exist.  The example above now looks like this:
+\begin{verbatim}
+   \DeclareFontSeriesChangeRule{c}{b}{bc}{}
+\end{verbatim}
+which means: switch to the |bc| series if |c| is current and |b| is
+(additionally) requested, and if the current font doesn't have the
+combination, start the normal font substitution, i.e., switch back shape
+to |n| and if this combination doesn't succeed, switch back series to
+|m| as well, ending up with |m/n|.
+
+Another example is:
+\begin{verbatim}
+   \DeclareFontSeriesChangeRule{bc}{sc}{bsc}{bc}
+\end{verbatim}
+which means: if the current series is bold condensed (|bc|) and
+semi-condensed (|sc|) is requested (additionally), try bold
+semi-condensed (|bsc|) if available but stay with bold condensed if not.
+
+A special value is |m| which is used to reset both weight and width.  In
+order to reset only one of them, the special values |?m| (reset width)
+and |m?| (reset weight) are provided, e.g.:
+\begin{verbatim}
+   \DeclareFontSeriesChangeRule{bc}{m?}{c}{}
+\end{verbatim}
+
+The corresponding macro |\DeclareFontShapeChangeRule| is also provided
+for setting database entries for font shapes:
+\begin{decl}
+  |\DeclareFontShapeChangeRule| %
+  \arg{current shape} \arg{requested shape} \\
+  \leavevmode\hfill   \arg{result} \arg{alternative result}
+\end{decl}
+
+An example would be:
+\begin{verbatim}
+   \DeclareFontShapeChangeRule{it}{sc}{scit}{scsl}
+\end{verbatim}
+If italics is the current shape and small caps is requested, switch to
+|scit| (small caps italics) and if that doesn't exist, try |scsl| (small
+caps slanted).
+
+Finally, it is also possible to overrule the entries in the lookup
+tables and forcibly select a series or shape with:
+\begin{decl}
+  |\fontseriesforce| \arg{series} \qquad |\fontshapeforce| \arg{shape}
+\end{decl}
+
+With the example above for the |c| series, issuing |\fontseriesforce{b}|
+means that the series switches to |b| and not to |bc|.  Same applies to
+|\fontshapeforce|.
+
 \subsection{Handling of nested emphasis}
 
 \begin{decl}
diff --git a/base/doc/ltnews39.tex b/base/doc/ltnews39.tex
index e82cb145..43b846de 100644
--- a/base/doc/ltnews39.tex
+++ b/base/doc/ltnews39.tex
@@ -513,7 +513,15 @@ missing and sub-encoding 5 as declared in the kernel is correct.
 %
 \githubissue{1257}
 
+\section{Documentation improvements}
 
+\subsection{Further updates to the guides}
+
+We reported about the updated versions of \texttt{usrguide} and
+\texttt{clsguide} in \LaTeX{} News~37~\cite{39:ltnews37}.  We have now
+revised \texttt{fntguide} as well to reflect the changes and macros
+added to the kernel over the last years of development.  Note that the
+file name hasn't changed and there is no \texttt{fntguide-historic}.
 
 %\section{Bug fixes}

More information about the latex3-commits mailing list.