summaryrefslogtreecommitdiff
path: root/macros/luatex/optex/base/f-heros.opm
diff options
context:
space:
mode:
Diffstat (limited to 'macros/luatex/optex/base/f-heros.opm')
-rw-r--r--macros/luatex/optex/base/f-heros.opm203
1 files changed, 203 insertions, 0 deletions
diff --git a/macros/luatex/optex/base/f-heros.opm b/macros/luatex/optex/base/f-heros.opm
new file mode 100644
index 0000000000..d369ec8936
--- /dev/null
+++ b/macros/luatex/optex/base/f-heros.opm
@@ -0,0 +1,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.