summaryrefslogtreecommitdiff
path: root/macros/luatex/optex/base/f-heros.opm
blob: d369ec89369440cbc6498d3b38165c9fda922cc8 (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
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
%% This is part of OpTeX project, see http://petr.olsak.net/optex

\_famdecl [Heros] \Heros {TeX Gyre Heros fonts based on Helvetica}
     {\caps \cond} {\rm \bf \it \bi} {FiraMath}
     {[texgyreheros-regular]}
     {\_def\_fontnamegen{[texgyreheros\_condV-\_currV]:\_capsV\_fontfeatures}}

\_wlog{\_detokenize{%
Modifiers:^^J
 \caps ...... caps & small caps^^J
 \cond ...... condensed variants^^J
}}

\_moddef \resetmod {\_fsetV caps={},cond={} \_fvars regular bold italic bolditalic }
\_moddef \caps     {\_fsetV caps=+smcp;+onum; }
\_moddef \nocaps   {\_fsetV caps={} }
\_moddef \cond     {\_fsetV cond=cn }
\_moddef \nocond   {\_fsetV cond={} }

\_initfontfamily % new font family must be initialized

\_loadmath {[FiraMath-Regular]}

\_endcode

The font family file declares the font family for selecting fonts from such
family at arbitrary size and with various shapes. Unicode fonts (OTF)
are preferred. The following example declares the Heros family:

\printdoc f-heros.opm

If you want to write such font file, you need to keep following rules.

\begitems
* Use the \^`\_famdecl` command first. It has the following syntax:
\begtt \catcode`\<=13
\_famdecl [<Name of family>] \<Familyselector> {<comments>}
     {<modifiers>} {<variant selectors>} {<comments about math fonts>}
     {<font-for-testing>}
     {\_def\_fontnamegen{<font name or font file name generated>}}
\endtt
  This writes information about font family at the
  terminal and prevents loading such file twice. Moreover, it probes
  existence of `<font-for-testing>` in your system. If it doesn't exist, the
  file loading is skipped with a warning on the terminal.
  The \^`\_ifexistfam` macro returns false in such case.
  The `\_fontnamegen` macro must be defined in the last parameter of the
  `\_famdecl`. More about it is documented below.
* You can use `\_wlog{\_detokenize{...` to write aditional information into
  log file.
* You can declare optical sizes using `\_regoptsizes` if there are more font files
  with different optical sizes (like in Latin Modern). See `f-lmfonts.ofm`
  file for more information about this special feature.
* Declare font modifiers using `\_moddef` if they are present. The \`\resetmod` 
  must be declared in each font family.
* Check if all your declared modifiers does not produce any space in
  horizontal mode. For example check: `X\caps Y`, the letters `XY` must 
  be printed without any space. 
* Optionally, declare new variants by the \^`\famvardef` macro.
* Run `\_initfontfamily` in order to start the family.
* If math font should be loaded, use `\_loadmath{<math font>}`.
\enditems

{\noindent \bf The \`\_fontnamegen` macro} 
(declared in the last parameter of the `\_famdecl`) 
must expand (at expand processor level only) to a file name of loaded font (or to its font
name) and to optional font features appended. The Font Selection 
System uses this macro at primitive level in the following sense:

\begtt
\font \<selector> {\_fontnamegen} \_sizespec
\endtt
%
Note that the extended `\font` syntax 
`\font\<selector> {<font name>:<font features>} <size spec.>` or
`\font\<selector> {[<font file name>]:<font features>} <size spec.>`
is expected here.

\bigskip
{\noindent\bf Example.} 
Assume an abstract font family with fonts `xx-Regular.otf`,
`xx-Bold.otf`, `xx-Italic.otf` and `xx-BoldItalic.otf`. Then you can declare
the `\resetmod` (for initializing the family) by:
\begtt
\_moddef\resetmod{\_fvars Regular Bold Italic BoldItalic }
\endtt
and define the `\_fontnamegen` in the last parameter of the `\_famdecl` by:
\begtt
\_famdecl ...
    {\def\_fontnamegen{[xx-\_currV]}}
\endtt
The following auxiliary macros are used here:
\begitems
* \^`\moddef` declares the family dependent modifier. The `\resetmod` saves
  initial values for the family.
* \^`\_fvars` saves four names to the memory, they are used by the \^`\_currV` macro.
* \^`\_currV` expands to one of the four names dependent on `\rm` or `\bf` or
  `\it` or `\bi` variant is required.
\enditems
Assume that the user needs `\it` variant in this family. Then the
`\_fontnamegen` macro expands to `[xx-\_currV]` and it expands to
`[xx-Italic]`. The Font Selection System uses `\font {[xx-Italic]}`.
This command loads the `xx-Italic.otf` font file.

See more advanced examples in `f-<family>.opm` files. The `f-heros.opm` is listed
here. When Heros family is selected and `\bf` is asked then
\begtt
\font {[texgyreheros-bold]:+tlig;} at10pt
\endtt
%
is processed.

You can use any expandable macros or expandable primitives in the `\_fontnamegen`
macro. The simple macros in our example with names `\_<word>V` are preferred. They
expand typically to their content. The macro `\_fsetV <word>=<content>`
(terminated by a space) is equivalent to `\def\_<word>V{<content>}` and you
can use it in font modifiers. You can use the `\_fsetV` macro in more
general form:

\begtt \catcode`\<=13
   \_fsetV <word-a>=<value-a>,<word-b>=<value-b>  ...etc. terminated by a space 
\endtt
%
with obvious result `\def \_<word-a>V {<value-a>}\def \_<word-b>V {<value-b>}` etc.

Example: if both font modifiers `\caps` and `\cond` were applied from the Heros
family, then `\def\_capsV{+smcp;+onum}` and `\def\_condV{cn}` were processed
by these font modifiers. If user needs the `\bf` variant at 11\,pt now then
the

\begtt
  \font {[texgyreheroscn-bold]:+smcp;+onum;+tlig;} at11pt
\endtt
%
is processed. We assume that a font file `texgyreheroscn-bold.otf` is present
in your TeX system.

Recommendation: the \^`\_fontfeatures` macro at the end of the `\_fontnamegen`
macro in order to the \^`\setff`, \^`\setfontcolor`, \^`\setletterspace`
macros can work. 

\bigskip
{\noindent\bf The \^`\moddef` macro} 
does more things than simple `\_def`:

\begitems
* The modifier macros are defined as `\_protected`.
* The modifier macros are defined as family-dependent. 
\enditems
\noindent
The \^`\famvardef` macro has the same features.

\bigskip
{\noindent\bf The `\<Familyselector>`}
is defined by the \^`\_famdecl` macro as:
\begtt \catcode`<=13
\protected\def\<Familyselector> {%
   \_def\_currfamily {<Familyselector>}%
   \_def\_fontnamegen {<font name or font file name generated>}%
   \resetmod 
\endtt

{\noindent\bf  The font context} consists from
   \begitems
   * Family context, i.\,e.\ \^`\_currfamily` and \^`\_fontnamegen` values
     saved by the `\<Familyselector>`,
   * \^`\_sizespec` value saved by the \^`\setfontsize` macro,
   * whatever what influences the expansion of the `\_fontnamegen` macro,
     they are typically macros `\_<key>V` saved by the font modifiers.
   \enditems

{\noindent\bf The \^`\_initfontfamily` must be run} after modifers decaration. 
It sets `\_let\_resetmod=\resetmod` and runs the `\<Familyselector>`. 
Finally, it runs `\_rm`, so first font from new family is loaded and it 
is ready to use it.

\bigskip
{\noindent\bf Name conventions.}
Create font modifiers, new variants and the `\<Familyselector>` only as public, i.e.
without `_` prefix. We assume that if user re-defines them then he/she needs
not them, so we have no problems.

The name of `\<Familyselector>` should begin with uppercase letter.

If you need to declare your private modifier (because it is used in another
modifiers or macros, for example), use the name `\_wordM`. You can be
sure that such name does not influence the private name space used by \OpTeX/.

\bigskip
{\noindent\bf Additional notes.}
See the font family file `f-libertine-s.opm` which is another example where no
font files but font names are used.

See the font family file `f-lmfonts.opm` where you can find the 
the example of the optical sizes declaration including a documentation about
it.

If you need to create font family file with non-Unicode font, you can do it.
The `\_fontnamegen` must expand to the name of TFM file in such case. But we
don't prefer such font family files, because they are usable only with
languages with alphabet subset to ISO-8859-1 (Unicodes are equal to letter
codes of such alphabets), but middle or east Europe use languages where
such condition is not true.