substitutefont
--------------
Combine font families
*********************

:Copyright:   © 2010, 2023 Günter Milde <milde@users.sf.net>

:Contributor: Special thanks to Ulrike Fischer who provided
              the indirect definition with active ``\nfss@catcodes``.

:Licence:     This work may be distributed and/or modified under the
              conditions of the `LaTeX Project Public License`_,
              either version 1.3 of this license or (at your option)
              any later version.

.. admonition:: Obsolete:

   The package is obsoleted by the LaTeX kernel command
   ``\DeclareFontFamilySubstitution`` added in the
   2020-02 LaTeX release [ltnews31]_.
   
   Existing documents can be updated by removing
   ``\usepackage{substitutefont}`` and replacing all uses of
   ``\substitutefont`` with ``\DeclareFontFamilySubstitution``.


Description
===========

In traditional 8-bit LaTeX, fonts are restricted to 256 glyphs per file.
To support different languages and scripts, the New Font Selection Scheme
uses a set of TeX `font encodings` [encguide]_.

Many Latin TeX fonts do not support Greek or Cyrillic, while many
non-Latin fonts are extensions of a Latin font family but use a different
family name due to license reasons or the creators preference.

The `substitutefont` package facilitated the task to set up a font family
as substitute for another one in a specified font encoding.
It is obsoleted by the standard LaTeX kernel command
``\DeclareFontFamilySubstitution``.


Usage
=====

The macro
``\DeclareFontFamilySubstitution{<encoding>}{<family>}{<new-family>}``
selects the font family <new-family> as replacement for <family> in the
font encoding <encoding> [fntguide]_. The substitution must be defined
before the first use of the specified font encoding, preferably in the
document preamble. [#]_

The ``<encoding>`` is one of the LaTeX `font encodings`, e.g., T1 for
Latin, T2A for Cyrillic(Russian), or LGR for Greek [encguide]_.

For ``<family>`` and ``<new-family>``, use the «TeX names» of the font.
They are defined by a TeX font package's ``*.fd`` or ``*.sty`` file(s).
LaTeX stores the default family names for Roman, Sans-Serif, and Teletype
fonts in the ``\rmdefault``, ``\sfdefault``, and ``\ttdefault`` macros
respectively.


.. [#] In contrast to the deprecated ``\substitutefontfamily`` macro
   provided by Babel_, ``\substitutefont`` and
   ``\DeclareFontFamilySubstitution`` do not write auxiliary files.


Examples
========

Set the font family to Palatino using the standard package
`mathpazo` for Latin and `GFS Didot`_ for Greek.

Using the obsolete `substitutefont` package::

    \usepackage[sc,slantedGreek]{mathpazo}
    \usepackage{substitutefont}
    \substitutefont{LGR}{\rmdefault}{udidot}

Using the standard command::

    \usepackage[sc,slantedGreek]{mathpazo}
    \DeclareFontFamilySubstitution{LGR}{\rmdefault}{udidot}

Example documents:

* Palatino with Greek from `GFS Didot`_:
  `<greek-palatino-didot.tex>`__, `<greek-palatino-didot.pdf>`__
* Times/Helvetica/Courier (newtx_) with `GFS Artemisia`_, `GFS
  Neohellenic`_, and teletype from the CB_ fonts:
  `<greek-times-artemisia.tex>`__, `<greek-times-artemisia.pdf>`__
  (see also package txfontsb_)
* Latin Modern with Cyrillic from `CM LGC`_:
  `<cyrillic-lm-lgc.tex>`__, `<cyrillic-lm-lgc.pdf>`__
* Times/Helvetica/Courier (TeX Gyre) with Cyrillic ParaType_ fonts:
  `<cyrillic-paratype.tex>`__, `<cyrillic-paratype.pdf>`__
* Simple test with Latin fonts:
  `<substitutefont-test.tex>`__, `<substitutefont-test.pdf>`__


Source
======

`<substitutefont.sty>`_
  The literate source was converted with PyLit_ to reStructuredText_ and
  with Docutils_ to the HTML documentation `<substitutefont.sty.html>`__.


References
==========

.. [encguide] Frank Mittelbach, Robin Fairbairns, Werner Lemberg,
   LaTeX3 Project Team, `LaTeX font encodings`:
   https://mirrors.ctan.org/macros/latex/doc/encguide.pdf.

.. [fntguide] LaTeX3 Project Team, `LaTeX 2e font selection`:
   https://mirrors.ctan.org/macros/latex/doc/fntguide.pdf.

.. [ltnews31] `LaATeX News`, Issue 31, February 2020, p. 3:
   https://www.latex-project.org/news/latex2e-news/ltnews31.pdf.

.. _LaTeX Project Public License: http://www.latex-project.org/lppl.txt

.. _Babel: https://ctan.org/pkg/babel
.. _CM LGC: https://ctan.org/pkg/cm-lgc
.. _CB: https://ctan.org/pkg/cbgreek-complete
.. _GFS Artemisia: https://ctan.org/pkg/gfsartemisia
.. _GFS Didot: https://ctan.org/pkg/gfsdidot
.. _GFS Neohellenic: https://ctan.org/pkg/gfsneohellenic
.. _mathpazo: https://ctan.org/pkg/mathpazo
.. _newtx: https://ctan.org/pkg/newtx
.. _txfontsb: https://ctan.org/pkg/txfontsb
.. _ParaType: https://ctan.org/pkg/paratype

.. _PyLit: https://pypi.org/project/pylit/
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
.. _Docutils: http://docutils.sourceforge.net/rst.html