summaryrefslogtreecommitdiff
path: root/macros/luatex/generic/luaotfload/luaotfload-main.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/luatex/generic/luaotfload/luaotfload-main.tex')
-rw-r--r--macros/luatex/generic/luaotfload/luaotfload-main.tex195
1 files changed, 183 insertions, 12 deletions
diff --git a/macros/luatex/generic/luaotfload/luaotfload-main.tex b/macros/luatex/generic/luaotfload/luaotfload-main.tex
index 9fe9060695..79d7411b20 100644
--- a/macros/luatex/generic/luaotfload/luaotfload-main.tex
+++ b/macros/luatex/generic/luaotfload/luaotfload-main.tex
@@ -32,7 +32,7 @@
\beginfrontmatter
\setdocumenttitle {The \identifier{luaotfload} package}
- \setdocumentdate {2019-11-10 v3.11}
+ \setdocumentdate {2020-02-02 v3.12}
\setdocumentauthor {LaTeX3 Project\\
Elie Roux · Khaled Hosny · Philipp Gesang · Ulrike Fischer · Marcel Krüger\\
Home: \hyperlink {https://github.com/latex3/luaotfload}}
@@ -62,10 +62,20 @@ Supported is the \identifier{luatex} versions of a current TeXLive 2019 (and a c
\endsection
\beginsection{Changes}
+\beginsubsection {New in version 3.12 (by Ulrike Fischer/Marcel Krüger)}
+\begin{itemize}
+\item Corrected a number of small bugs in harf mode.
+\item Extension\marginpar{Experimental!} of the \identifier{color} key to allow
+coloring of specific output glyphs, see page~\pageref{color-glyphs}
+\item A\marginpar{Experimental!} new \identifier{fallback} key to allow to define fallback fonts, see page~\pageref{fallback}
+\item A\marginpar{Experimental!} new \identifier{multiscript} key to allow to use a font
+for more than one script, see page~\pageref{multiscript}
+\end{itemize}
+
\beginsubsection {New in version 3.11 (by Ulrike Fischer/Marcel Krüger)}
\begin{itemize}
\item Changed the handling of the \identifier{script} key in harf mode to be more compatible with behaviour of the node mode. It now expects the name of a script that is actually in the font instead of a ISO 15924 script tag. See issue 117.
-\item Corrected a number of small typos and bugs in harf mode.
+\item Corrected a number of small typos and bugs in harf mode.
\end{itemize}
\beginsubsection {New in version 3.1 (by Ulrike Fischer/Marcel Krüger)}
\begin{itemize}
@@ -771,7 +781,7 @@ obviously, \inlinecode{random}.
\identifier{harf} mode is new in version 3.1 and needs the new \identifier{luahbtex} engine (the mode is ignored if \identifier{luahbtex} is not used). With it is possible to render a font using the harfbuzz library in-built in the new engine. \identifier{harf} mode improves greatly the rendering of indic and arabic scripts and is highly recommended for such scripts.
- When using \identifier{harf} mode it is required to set also the script correctly.
+ When using \identifier{harf} mode it is required to set also the script correctly.
\beginlisting
@@ -787,7 +797,7 @@ obviously, \inlinecode{random}.
It is possible to call other font renderers with the mode key. A simple example with a plain reader can be found at \url{https://github.com/latex3/luaotfload/pull/26#issuecomment-437716326}.
\endaltitem
- \beginaltitem {shaper} \label{shaper-tag}
+ \beginaltitem {shaper} \phantomsection\label{shaper-tag}
If \identifier{luahbtex} and \identifier{harf} mode are used it is possible to specify a shaper, like \identifier{graphite2} or \identifier{ot} (open type).
\beginlisting
@@ -805,7 +815,7 @@ obviously, \inlinecode{random}.
\includegraphics{shaper-demo-graphite}
\endaltitem
- \beginaltitem {script} \label{script-tag}
+ \beginaltitem {script} \phantomsection\label{script-tag}
An \OpenType script tag;\footnote{%
See \hyperlink {http://www.microsoft.com/typography/otspec/scripttags.htm}
for a list of valid values.
@@ -839,6 +849,42 @@ obviously, \inlinecode{random}.
\beginlisting
\font \test = "Latin Modern Roman:color=FF0000BB"
\endlisting
+
+ Experimental!\marginpar{\mbox{}\hfill NEW in v3.12!}\phantomsection\label{color-glyphs} The \identifier{color} key has been
+ extended to accept a table with color declarations of (output) glyphs. For example
+
+ \beginlisting
+ \directlua{
+ luaotfload.add_colorscheme("myscheme",
+ {
+ ["00FFFF30"] = {"default"},
+ ["FF0000"] = {"kabeng","ebeng"},
+ ["00FF00"] = {"ivowelsignbeng"},
+ ["0000FF"] = {369} %% 369 is the GID of "nadarabeng"
+ })
+ }
+ \endlisting
+
+ The keys in such a table are like above RGB colors with an optional transparency setting.
+ The values are either lists of glyph names or GID numbers.
+ Both types are font dependant! Not every font use the same
+ glyph names (or even glyph names at all). GID number are font specific anyway. The GID can be found
+ by looking up the \verb+["index"]+ entry in the lua file of a font.
+
+ Such a colorscheme can then be used like this:
+ \beginlisting
+ \font\test={name:Noto Sans Bengali:mode=harf;script=bng2;color=myscheme}
+ \endlisting
+
+ and then would give this output:
+
+
+ {\font\test={name:Noto Sans Bengali:mode=harf;script=bng2;color=myscheme}\test
+ কণ্যা এখন কি করিবে
+ \char"0995 \char"09BF
+ \char"09A8 \char"09CD \char"09A6
+ \char"09CD \char"09B0}
+
\endaltitem
@@ -856,7 +902,7 @@ obviously, \inlinecode{random}.
\endaltitem
- \beginaltitem {kernfactor \& letterspace}\label{p:letterspace}
+ \beginaltitem {kernfactor \& letterspace}\phantomsection\label{p:letterspace}
Define a font with letterspacing (tracking) enabled.
%
In \identifier{luaotfload}, letterspacing is implemented by
@@ -1025,6 +1071,117 @@ obviously, \inlinecode{random}.
\endaltitem
+
+ \beginaltitem {multiscript}\phantomsection\label{multiscript}
+ In\marginpar{New in 3.12 -- experimental} fonts many shaping rules are implemented only for specific scripts and so you get correct typesetting only if the \identifier{script} feature is correctly set. This means that to write a text which uses more than one script you have to declare a font for each script and switch fonts even if the font contains glyphs for all scripts.
+ \identifier{multiscript} tries to help here. The feature is experimental and bound to change. Feedback is welcome but you use it at your risk.
+
+ \identifier{multiscript} allows you to declare fonts for various script. The value is either \identifier{auto} described below, or a name which has been previously declared or a combination of both. An example for such a named multiscript could look like this (the colors are only for demonstration):
+
+ \beginlisting
+ \directlua{
+ luaotfload.add_multiscript
+ ("cyrlgrekbeng",
+ {
+ Cyrl = "DejaVuSans:mode=node;script=cyrl;color=FF0000;",
+ Grek = "texgyreheros:mode=harf;script=grek;color=0000FF;",
+ Beng = "NotoSansBengali:mode=harf;script=bng2;color=00FF00;"
+ }
+ )
+ }
+ \endlisting
+
+ \identifier{cyrlgrekbeng} is the name of the multiscript (the name is case insensitive). The keys are ISO language tags (not open type tags!). They are case insensitive too: the example uses an uppercase letter for ISO tags to differentiate them from script tags. The values are font declarations.
+
+ The multiscript can then be used in a font like this:
+
+ \beginlisting
+ \font\test={name:DejaVuSans:mode=node;multiscript=cyrlgrekbeng;}
+ \endlisting
+
+ This would lead to this output:
+
+ {\Large \font\test={name:DejaVuSans:mode=node;multiscript=cyrlgrekbeng;}\test
+ „a^^^^0301123!?“ „π^^^^0301123!?“ „a!?“ „Б123!?“ a „\char"0995\char"09BF 123“
+ }
+
+ It shows that fonts are switched with the scripts.
+
+ Be aware of the following drawbacks:
+
+ \begin{itemize}
+ \item Quite a lot chars can and should be used with more than one script, they belong to the Common or Inherited class. Examples are punctuation chars, digits, accents but also emoji. Currently these chars follow the active script. That's why the digits are all typeset with a different font, the accent over the pi is different to the one over the a, and why the opening quote is sometimes different to the closing quote. It is clear that some tools to force a script (and so a font) locally and globally for such chars are needed.
+
+ \item \identifier{multiscript} doesn't change hyphenation patterns or other language or script related features.
+
+ \item Language packages like \identifier{babel} or \identifier{polyglossia} have code to change the script too which could interfere or clash. This hasn't been tested yet.
+
+ \item \identifier{multiscript} can slow down the compilation.
+ \end{itemize}
+
+ It is possible to use the value \identifier{auto} with \identifier{multiscript}. luaotfload will then switch the script if it detects a char belonging to another script (and if the font support this script). This can be useful for fonts supporting more than one script or when using the \identifier{fallback} key described below.
+
+ It is also possible to combine \identifier{auto} with a named multiscript with the syntax \identifier{multiscript=auto+name}. The rules of the named multiscript will in such cases take precedence and \identifier{auto} used only for other scripts.
+
+
+
+ \endaltitem
+
+ \beginaltitem {fallback}\label{fallback}
+ This\marginpar{New in 3.12 -- experimental} allows you to define a chain of fonts which are used if glyphs are missing in the main font. It works only for text fonts, not for math fonts set with the \identifier{unicode-math} package.
+ The feature is experimental and bound to change. Feedback is welcome but you use it at your risk.
+ For example
+
+ \beginlisting
+ \directlua
+ {luaotfload.add_fallback
+ ("myfallback",
+ {
+ "DejaVuSans:mode=harf;script=grek;color=FF0000;",
+ "cmuserif:mode=node;script=cyrl;color=00FF00;",
+ "NotoSansBengali:mode=harf;script=bng2;color=0000FF;"
+ "NotoColorEmoji:mode=harf;"
+ }
+ )
+ }
+ \endlisting
+
+ This fallback can then be used e.g. like this:
+
+ \beginlisting
+ \font\test={name:LatinModernRoman:mode=node;fallback=myfallback;}
+ \endlisting
+
+ {\Large
+ \font\test={name:LatinModernRoman:mode=node;fallback=myfallback;}\test
+ 1234 a^^^^0301 π^^^^0301 a!? π123!? a БѨ123!? a \char"1F600\ \char"1F986\ \char"0995\char"09BF a „π“ a „Б“
+ }
+
+ Interesting points in the output are
+ \begin{itemize}
+ \item The accent over the pi, the digits and the quotes are all from the base font. Only missing glyphs are from the fallback.
+ \item The cyrillic is printed with the DejaVu font, despite the fact that is sets the script to \identifier{grek} and that the next font in the fallback chain would fit better.
+ \item The duck emoji is from the Noto font, while the face is from DejaVu as it comes first in the chain.
+ \end{itemize}
+
+ The \identifier{fallback} can be combined with the \identifier{multiscript}. For example
+
+ \beginlisting
+ \font\test={name:LatinModernRoman:mode=node;fallback=myfallback;multiscript=auto;}
+ \endlisting
+
+ {\Large
+ \font\test={name:LatinModernRoman:mode=node;fallback=myfallback;multiscript=auto;}\test
+ 1234 a^^^^0301 π^^^^0301 a!? π123!? a БѨ123!? a \char"1F600\ \char"1F986\ \char"0995\char"09BF a „π“ a „Б“
+ }
+
+ Now the accent over the pi is better. The digits after the pi and the closing quote use the DejaVu font. The digits after
+ the cyrillic use the Latin Modern font because of an interesting \enquote{feature} of this font: It claims to know the \identifier{cyrl} script despite the fact that it doesn't contain any cyrillic glyphs.
+
+ \identifier{fallback} can be nested: fonts in the fallback table can refer to another \identifier{fallback} table.
+
+ As with the \identifier{multiscript} key more control over the used glyph and script in edge cases will be needed.
+ \endaltitem
\enddescriptions
\endsubsection
@@ -1093,8 +1250,8 @@ Currently (2014) there are three of them:
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\beginsection {Combining fonts}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-Version 2.7 and later support combining characters from multiple fonts into a
+Beside the new keys \identifier{multiscript} and \identifier{fallback} described earlier
+Version 2.7 and later support another method to combine characters from multiple fonts into a
single virtualized one. This requires that the affected fonts be loaded in
advance as well as a special \emphasis{request syntax}. Furthermore, this
allows to define \emphasis{fallback fonts} to supplement fonts that may lack
@@ -1898,18 +2055,32 @@ are defined for which scripts.
has glyph \luaident{index}.
\endaltitem
- \beginaltitem {aux.slot_of_name(name : string)}
- Translates an Adobe Glyph name to the corresponding glyph
- slot.
+ \beginaltitem {aux.slot_of_name(id : int, name : string)}
+ Translates a name for a glyph in font \luaident{id} to the
+ corresponding glyph slot which can be used e.g.\ as an argument to
+ \inlinecode{\char}. The number is assigned by the \identifier{luaotfload} code
+ and not related to the glyph index (GID) of the font as stored in the \identifier{[index]} field
+ of the lua-file.
\endaltitem
- \beginaltitem {aux.name_of_slot(slot : int)}
+ \beginaltitem {aux.gid_of_name(id : int, name : string)}
+ Translates\marginpar{New version 3.12} a name for a glyph in font \luaident{id} to the
+ corresponding glyph index (GID) as stored in the \identifier{[index]} field.
+ \endaltitem
+
+ \beginaltitem {aux.name_of_slot(id : int, slot : int)}
The inverse of \luaident{slot_of_name}; note that this
might be incomplete as multiple glyph names may map to the
same codepoint, only one of which is returned by
\luaident{name_of_slot}.
\endaltitem
+ \beginaltitem {aux.gid_of_name(id : int, name : string)}
+ Translates a Glyph name to the corresponding GID in font
+ \luaident{id}. This corresponds to the value returned by
+ \inlinecode{\XeTeXglyphindex} in \XeTeX.
+ \endaltitem
+
\beginaltitem {aux.provides_script(id : int, script : string)}
Test if a font supports \luaident{script}.
\endaltitem