%% 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 [] \ {} {} {} {} {} {\_def\_fontnamegen{}} \endtt This writes information about font family at the terminal and prevents loading such file twice. Moreover, it probes existence of `` 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{}`. \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 \ {\_fontnamegen} \_sizespec \endtt % Note that the extended `\font` syntax `\font\ {:} ` or `\font\ {[]:} ` 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-.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 `\_V` are preferred. They expand typically to their content. The macro `\_fsetV =` (terminated by a space) is equivalent to `\def\_V{}` and you can use it in font modifiers. You can use the `\_fsetV` macro in more general form: \begtt \catcode`\<=13 \_fsetV =,= ...etc. terminated by a space \endtt % with obvious result `\def \_V {}\def \_V {}` 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 `\`} is defined by the \^`\_famdecl` macro as: \begtt \catcode`<=13 \protected\def\ {% \_def\_currfamily {}% \_def\_fontnamegen {}% \resetmod \endtt {\noindent\bf The font context} consists from \begitems * Family context, i.\,e.\ \^`\_currfamily` and \^`\_fontnamegen` values saved by the `\`, * \^`\_sizespec` value saved by the \^`\setfontsize` macro, * whatever what influences the expansion of the `\_fontnamegen` macro, they are typically macros `\_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 `\`. 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 `\` 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 `\` 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.