summaryrefslogtreecommitdiff
path: root/macros/luatex/optex/f-heros.opm
diff options
context:
space:
mode:
Diffstat (limited to 'macros/luatex/optex/f-heros.opm')
-rw-r--r--macros/luatex/optex/f-heros.opm250
1 files changed, 128 insertions, 122 deletions
diff --git a/macros/luatex/optex/f-heros.opm b/macros/luatex/optex/f-heros.opm
index 5a03746cae..d369ec8936 100644
--- a/macros/luatex/optex/f-heros.opm
+++ b/macros/luatex/optex/f-heros.opm
@@ -1,8 +1,9 @@
%% This is part of OpTeX project, see http://petr.olsak.net/optex
-\_fontdecl [Heros] \Heros {TeX Gyre Heros fonts based on Helvetica}
- {\caps \cond} {\rm \bf \it \bi} {FiraMath}
- {[texgyreheros-regular]}
+\_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
@@ -10,11 +11,6 @@ Modifiers:^^J
\cond ...... condensed variants^^J
}}
-\_protected\_def \Heros {%
- \_def \_currfamily {Heros}%
- \_def \_fontnamegen {[texgyreheros\_condV-\_currV]:\_capsV\_fontfeatures}%
- \_resetmod
-}
\_moddef \resetmod {\_fsetV caps={},cond={} \_fvars regular bold italic bolditalic }
\_moddef \caps {\_fsetV caps=+smcp;+onum; }
\_moddef \nocaps {\_fsetV caps={} }
@@ -27,171 +23,181 @@ Modifiers:^^J
\_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:
-The usage of font \OpTeX/ selection system is described in the
-fonts-select.opm file.
-
-
-\sec How to write font-macro-file for \OpTeX/ like this file
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\printdoc f-heros.opm
-The font-macro-file declares a font family for selecting a font from such
-family at arbitrary size and with various shapes. Unicode fonts (OTF)
-are preferred. If we want to write such font file, we need to keep following
-rules.
+If you want to write such font file, you need to keep following rules.
\begitems
-* Use
-\begtt
-\_fontdecl [<Name of family>] \<Main-command> {<comments>}
+* 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
- as first command in this file. This writes information about font family at
+ 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 isn't exist, the
+ 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 \^`\_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.
-* Define `\<Main-command>` (the commend `\Heros` here) as a `\_protected`
- macro. This macro initializes the family and it must do:
- \begitems
- * Define `\_currfamily` as a short name of the font family. It must be
- exactly the same as `<Main-command>` name but without backslash
- (it is case sensitive).
- * Define `\_fontfeatures` if they are something special.
- * Define `\_fontnamegen` as a template of generic font name used as file
- names (or font names) of OTF fonts. The rules about `\_fontnamegen` macro
- are documented below.
- * Use \_resetmod modifier to initialize values.
- \enditems
* 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.
+* 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. Do the same test with \<Main-command>
- before releasing your font file, for example X\Heros Y.
+ 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
-The font file must declare `\_fontnamegen` macro which must expand (at
-expand processor level only) to a file name of loaded font (or to its font
-name) and to optional fontfeatures appended. The font selection
-system uses this macro at primitive level in the following sense:
+{\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
+\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.
-For example, using macros from `f-heros.opm` the `\font` command expands its
-parameters to:
-
+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-regular]:+tlig;} at10pt
+\font {[texgyreheros-bold]:+tlig;} at10pt
\endtt
+%
+is processed.
-if the `\rm` variant is processed and if no additional font modifiers are
-activated. Of course, you need to know something about fontname syntax for
-extended `\font` primitive used with OTF fonts. The `[` `]` brackets tell us
-that the file name (no font name) is specified inside such brackets. This
-file (with additional `.otf` or `.ttf` extension) must be accessible by
-Lua\TeX/ in your filesystem. Without spaces, there are font features
-appended to file name (or font name) divided by semicolon. The `+tlig` font
-feature means that TeX like ligatures (minus minus = endash, for example)
-are active. Normal ligatures are active by default. You can list font
-features of given font by `otfinfo -f fontfile.otf`.
-
-The `\_fontnamegen` macro must include colon followed by family dependent
-font features (optional) and followed by `\_fontfeatures` (required).
-If this is not true then font modifiers `\setff`, `\setfontcolor`,
-`\setletterspace` and `\setwordspace` don't work.
-
-You can use any expandable macros or expandable primitives in `\fontnamegen`
-macro. The simple macros in it with names `\_<word>V` are preferred. They
+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
- \_fsetV <wordA>=<valueA>,<wordB>=<valueB> ...etc. terminated by a space
-\endtt
-
-with obvious result `\def\_<wordA>V{<valueA>}\def\_<wordB>V{<valueB>} etc.
-
-There is one special macro `\_currV` which expands to one of four variants
-depending on which variant selector is in process. Four strings can be
-saved by `\_fvars rm-variant bf-variant it-variant bi-varaiant` (all four strings
-must be terminated by a space). One of these
-string is used as expansion output of `\_currV` macro. Because we store
-
-\begtt
- \_fvars regular bold italic bolditalic
+\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.
-in `\resetmod` modifier then the `\_currV` expands (for example)
-to `italic` if the `\it` variant selector is in process.
-
-Example: if both modifiers `\caps` and `\cond` were applied from this family
-Heros and `\bf` variant is needed at 11pt then
+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;+tlig;} at11pt
+ \font {[texgyreheroscn-bold]:+smcp;+onum;+tlig;} at11pt
\endtt
-
-is processed. We assume that a font file texgyreheroscn-bold.otf is present
+%
+is processed. We assume that a font file `texgyreheroscn-bold.otf` is present
in your TeX system.
-Define all modifiers using `\_moddef` macro.
-The `\_moddef` macro does more things than simple `\_def`:
+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. If user loads more
- families then `\LMfonts \caps` does somewhat different job than
- `\Heros \caps`, for example.
+* 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
-Finally the `\_initfontfamily` must be run. It runs \<Main-command>.
-So, the `\_resetmod` macro (declared as `\resetmod`) is processed. Finally it
-runs `\_rm`, so first font from new family is loaded and is ready to use it.
-
-\secc Name conventions
-%---------------------
-
-Create modificators, new variants and `\<Main-command>` only as public, i.e.
-without `_` prefix. We assume that if user re-defines them then he/she need
+{\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/.
-The private variant `\_resetmod` must be used in your
-`\<Main-command>` but you need not to declare it as private,
-it is done automatically. Declare only `\restmod` by `\_moddef` macro.
-
-The name of `\<Main-command>` should begin with uppercase letter.
-
-See font-macro-file `f_libertine-s.opm` which is another example where no
+\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.
-\secc Additional notes
-%---------------------
-
-In very rare situations we have more files with almost the same font but
-designed for different optimal sizes (so called "optical sizes"). See a
-collection of lmroman*.otf files, for example. You can declare such font
-files for various optical sizes using `\_optname` macro in the
-`\_fontnamegen` macro. See the file `f-lmfonts.opm` for more details.
+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-macro-file with non unicode font, you can do 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-macro-files, because they are usable only with
-laguages with alphabet subset to ISO-8859-1 (unicodes are equal to letter
+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.