summaryrefslogtreecommitdiff
path: root/obsolete/macros/latex/contrib/substitutefont/substitutefont-doc.rst
blob: a88f81496370c2bc543111f5fb33b4ce9873023f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
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