bionic (5) luaotfload.conf.5.gz

Provided by: texlive-luatex_2017.20180305-1_all bug

NAME

       luaotfload.conf - Luaotfload configuration file

SYNOPSIS

./luaotfload{.conf,rc}XDG_CONFIG_HOME/luaotfload/luaotfload{.conf,rc}~/.luaotfloadrc

DESCRIPTION

       The  file  luaotfload.conf  contains  configuration  options  for  Luaotfload,  a  font  loading and font
       management component for LuaTeX.

EXAMPLE

       A small Luaotfload configuration file with few customizations could look as follows:

          [db]
              formats = afm,ttf
              compress = false

          [misc]
              termwidth = 60

          [run]
              log-level = 6

       This will make Luaotfload ignore all font files except for PostScript binary fonts with  a  matching  AFM
       file,  and  Truetype  fonts.  Also,  an  uncompressed index file will be dumped which is going to be much
       larger than the default gzip’ed index. The terminal width is truncated to 60 characters which  influences
       the  verbose  output  during  indexing. Finally, the verbosity is increased greatly: each font file being
       processed will be printed to the stdout on a separate line, along with lots of other information.

       To observe the difference in behavior, save above snippet to ./luaotfload.conf and update the font index:

          luaotfload-tool --update --force

       The current configuration can be written to disk using luaotfload-tool:

          luaotfload-tool --dumpconf > luaotfload.conf

       The result can itself be used as a configuration file.

SYNTAX

       The configuration file syntax follows the common INI format. For a more detailed description please refer
       to the section “CONFIGURATION FILE” of git-config(1). A brief list of rules is given below:

          • Blank lines and lines starting with a semicolon (;) are ignored.

          • A  configuration file is partitioned into sections that are declared by specifying the section title
            in brackets on a separate line:

                [some-section]
                ... section content ...

          • Sections consist of one or more variable assignments of the form variable-name = value  E. g.:

                [foo]
                    bar = baz
                    quux = xyzzy
                    ...

          • Section and variable names may contain only uppercase and lowercase letters as well as dashes (-).

VARIABLES

       Variables in belong into a configuration section and their values must be of a certain type. Some of them
       have  further  constraints.  For  example,  the  “color  callback”  must be a string of one of the values
       post_linebreak_filter, pre_linebreak_filter, or pre_output_filter, defined in  the  section  run  of  the
       configuration file.

       Currently, the configuration is organized into four sections:

       db     Options relating to the font index.

       misc   Options without a clearly defined category.

       paths  Path and file name settings.

       run    Options controlling runtime behavior of Luaotfload.

       The list of valid variables, the sections they are part of and their type is given below. Types represent
       Lua types that the values must be convertible to; they are abbreviated as follows: s for the string type,
       n for number, b for boolean. A value of nil means the variable is unset.

   Section db
                                       ┌─────────────────┬──────┬───────────────┐
                                       │variable         │ type │ default       │
                                       ├─────────────────┼──────┼───────────────┤
                                       │compress         │ b    │ true          │
                                       ├─────────────────┼──────┼───────────────┤
                                       │designsize-dimen │ b    │ bp            │
                                       ├─────────────────┼──────┼───────────────┤
                                       │formats          │ s    │ "otf,ttf,ttc" │
                                       ├─────────────────┼──────┼───────────────┤
                                       │max-fonts        │ n    │ 2^51          │
                                       ├─────────────────┼──────┼───────────────┤
                                       │scan-local       │ b    │ false         │
                                       ├─────────────────┼──────┼───────────────┤
                                       │skip-read        │ b    │ false         │
                                       ├─────────────────┼──────┼───────────────┤
                                       │strip            │ b    │ true          │
                                       ├─────────────────┼──────┼───────────────┤
                                       │update-live      │ b    │ true          │
                                       └─────────────────┴──────┴───────────────┘

       The  flag compress determines whether the font index (usually luaotfload-names.lua[.gz] will be stored in
       compressed forms.  If unset it is equivalent of passing --no-compress to luaotfload-tool. Since the  file
       is  only created for convenience and has no effect on the runtime behavior of Luaotfload, the flag should
       remain set. Most editors come with zlib support anyways.

       The setting designsize-dimen applies when looking up fonts from families with design sizes.  The  default
       of DTP-style “big points” can be changed for pt or even dd.

       The  list  of  formats  must  be  a  comma  separated sequence of strings containing one or more of these
       elements:

       • otf               (OpenType format),

       • ttf and ttc       (TrueType format),

       • afm               (Adobe Font Metrics),

       It corresponds loosely to the --formats option to  luaotfload-tool.  Invalid  or  duplicate  members  are
       ignored;  if  the  list  does  not contain any useful identifiers, the default list "otf,ttf,ttc" will be
       used.

       The variable max-fonts determines after processing how many font files the font  scanner  will  terminate
       the search. This is useful for debugging issues with the font index and has the same effect as the option
       --max-fonts to luaotfload-tools.

       The scan-local flag, if set, will incorporate the current working directory as a  font  search  location.
       NB: This will potentially slow down document processing because a font index with local fonts will not be
       saved to disk, so these fonts will have to be re-indexed whenever the document is built.

       The skip-read flag is only useful for debugging:  It  makes  Luaotfload  skip  reading  fonts.  The  font
       information for rebuilding the index is taken from the presently existing one.

       Unsetting  the  strip flag prevents Luaotfload from removing data from the index that is only useful when
       processing font files. NB: this can increase the size of the index files significantly and has no  effect
       on the runtime behavior.

       If  update-live is set, Luaotfload will reload the database if it cannot find a requested font. Those who
       prefer to update manually using luaotfload-tool should unset this  flag.  This  option  does  not  affect
       rebuilds due to version mismatch.

   Section default-features
       By  default  Luaotfload  enables node mode and picks the default font features that are prescribed in the
       OpenType standard. This behavior may be overridden in the default-features section. Global defaults  that
       will  be  applied  for  all scripts can be set via the global option, others by the script they are to be
       applied to. For example, a setting of

          [default-features]
              global = mode=base,color=0000FF
              dflt   = smcp,onum

       would force base mode, tint all fonts blue  and  activate  small  capitals  and  text  figures  globally.
       Features  are specified as a comma separated list of variables or variable-value pairs. Variables without
       an explicit value are set to true.

   Section misc
                                      ┌───────────┬──────┬──────────────────────┐
                                      │variable   │ type │ default              │
                                      ├───────────┼──────┼──────────────────────┤
                                      │statistics │ b    │ false                │
                                      ├───────────┼──────┼──────────────────────┤
                                      │termwidth  │ n    │ nil                  │
                                      ├───────────┼──────┼──────────────────────┤
                                      │version    │ s    │ <Luaotfload version> │
                                      └───────────┴──────┴──────────────────────┘

       With statistics enabled, extra statistics will be collected during index creation  and  appended  to  the
       index file. It may then be queried at the Lua end or inspected by reading the file itself.

       The  value of termwidth, if set, overrides the value retrieved by querying the properties of the terminal
       in which Luatex runs. This is useful if the  engine  runs  with  shell_escape  disabled  and  the  actual
       terminal dimensions cannot be retrieved.

       The  value of version is derived from the version string hard-coded in the Luaotfload source. Override at
       your own risk.

   Section paths
                                 ┌─────────────┬──────┬───────────────────────────────┐
                                 │variable     │ type │ default                       │
                                 ├─────────────┼──────┼───────────────────────────────┤
                                 │cache-dir    │ s    │ "fonts"                       │
                                 ├─────────────┼──────┼───────────────────────────────┤
                                 │names-dir    │ s    │ "names"                       │
                                 ├─────────────┼──────┼───────────────────────────────┤
                                 │index-file   │ s    │ "luaotfload-names.lua"        │
                                 ├─────────────┼──────┼───────────────────────────────┤
                                 │lookups-file │ s    │ "luaotfload-lookup-cache.lua" │
                                 └─────────────┴──────┴───────────────────────────────┘

       The  paths  cache-dir  and  names-dir  determine  the  subdirectory  inside the Luaotfload subtree of the
       luatex-cache directory where the font cache and the font index will be stored, respectively.

       Inside the index directory, the names of the index file and the font lookup cache will  be  derived  from
       the respective values of index-file and lookups-file. This is the filename base for the bytecode compiled
       version as well as -- for the index -- the gzipped version.

   Section run
                                   ┌───────────────┬──────┬─────────────────────────┐
                                   │variable       │ type │ default                 │
                                   ├───────────────┼──────┼─────────────────────────┤
                                   │anon-sequence  │ s    │ "tex,path,name"         │
                                   ├───────────────┼──────┼─────────────────────────┤
                                   │color-callback │ s    │ "post_linebreak_filter" │
                                   ├───────────────┼──────┼─────────────────────────┤
                                   │definer        │ s    │ "patch"                 │
                                   ├───────────────┼──────┼─────────────────────────┤
                                   │log-level      │ n    │ 0                       │
                                   ├───────────────┼──────┼─────────────────────────┤
                                   │resolver       │ s    │ "cached"                │
                                   ├───────────────┼──────┼─────────────────────────┤
                                   │fontloader     │ s    │ "default"               │
                                   └───────────────┴──────┴─────────────────────────┘

       Unqualified font lookups are treated with the flexible “anonymous” mechanism. This involves  a  chain  of
       lookups applied successively until the first one yields a match. By default, the lookup will first search
       for TFM fonts using the Kpathsea library. If this wasn’t successful, an attempt is made  at  interpreting
       the  request as an absolute path (like the [/path/to/font/foo.ttf] syntax) or a file name (file:foo.ttf).
       Finally, the request is interpreted as a font name and retrieved from the index (name:Foo Regular).  This
       behavior  can be configured by specifying a list as the value to anon-sequence.  Available items are tex,
       path, name -- representing the lookups described  above,  respectively  --,  and  file  for  searching  a
       filename  but  not  an absolute path. Also, my lookups are valid values but they should only be used from
       within TeX documents, because there is no means of customizing a my lookups on the command line.

       The color-callback option determines the stage at which fonts that defined with  a  color=xxyyzz  feature
       will   be   colorized.  By  default  this  happens  in  a  post_linebreak_filter  but  alternatively  the
       pre_linebreak_filter or pre_output_filter may be chosen, which is faster but might  produce  inconsistent
       output.  The  pre_output_filter  used  to  be  the  default in the 1.x series of Luaotfload, whilst later
       versions up to and including 2.5 hooked into the pre_linebreak_filter which naturally didn’t  affect  any
       glyphs  inserting during hyphenation. Both are kept around as options to restore the previous behavior if
       necessary.

       The definer allows for switching the define_font callback.  Apart from the default  patch  one  may  also
       choose  the  generic  one that comes with the vanilla fontloader. Beware that this might break tools like
       Fontspec that rely on the patch_font callback provided by Luaotfload to perform important corrections  on
       font data.

       The fontloader backend can be selected by setting the value of fontloader. The most important choices are
       default, which will load the dedicated Luaotfload fontloader, and  reference,  the  upstream  package  as
       shipped with Luaotfload. Other than those, a file name accessible via kpathsea can be specified.

       Alternatively,  the  individual  files  that constitute the fontloader can be loaded directly. While less
       efficient, this greatly aids debugging since error messages will reference the actual line numbers of the
       source  files and explanatory comments are not stripped. Currently, three distinct loading strategies are
       available: unpackaged will load the batch that is part of Luaotfload. These contain the identical  source
       code  that the reference fontloader has been compiled from.  Another option, context will attempt to load
       the same files by their names in the Context format from the search path. Consequently this option allows
       to  use  the  version  of Context that comes with the TeX distribution. Distros tend to prefer the stable
       version (“current” in Context jargon) of those files so certain bugs encountered  in  the  more  bleeding
       edge  Luaotfload  can  be  avoided  this  way. A third option is to use context with a colon to specify a
       directory  prefix  where  the  TEXMF  is  located  that  the  files  should  be  loaded   from,   e.   g.
       context:~/context/tex/texmf-context.  This  can  be  used  when referencing another distribution like the
       Context minimals that is installed under a different path not indexed by kpathsea.

       The value of log-level sets the default verbosity  of  messages  printed  by  Luaotfload.  Only  messages
       defined  with a verbosity of less than or equal to the supplied value will be output on the terminal.  At
       a log level of five Luaotfload can be very noisy. Also, printing too many messages  will  slow  down  the
       interpreter due to line buffering being disabled (see setbuf(3)).

       The  resolver  setting  allows  choosing the font name resolution function: With the default value cached
       Luaotfload saves the result of a successful font name request to a cache  file  to  speed  up  subsequent
       lookups. The alternative, normal circumvents the cache and resolves every request individually. (Since to
       the restructuring of the font name index in Luaotfload 2.4 the performance difference between the  cached
       and uncached lookups should be marginal.)

FILES

       Luaotfload  only processes the first configuration file it encounters at one of the search locations. The
       file name may be either luaotfload.conf or luaotfloadrc, except  for  the  dotfile  in  the  user’s  home
       directory which is expected at ~/.luaotfloadrc.

       Configuration  files are located following a series of steps. The search terminates as soon as a suitable
       file is encountered. The sequence of locations that Luaotfload looks at is

       i.   The current working directory of the LuaTeX process.

       ii.  The    subdirectory    luaotfload/    inside    the    XDG     configuration     tree,     e.     g.
            /home/oenothea/config/luaotfload/.

       iii. The dotfile.

       iv.  The TEXMF (using kpathsea).

SEE ALSO

       luaotfload-tool(1), luatex(1), lua(1)

       • texdoc luaotfload to display the PDF manual for the Luaotfload package

       • Luaotfload development https://github.com/lualatex/luaotfload

       • LuaLaTeX mailing list  http://tug.org/pipermail/lualatex-dev/

       • LuaTeX                 http://luatex.org/

       • Luaotfload on CTAN     http://ctan.org/pkg/luaotfload

REFERENCES

       • The XDG base specification http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html.

AUTHORS

       Luaotfload is maintained by the LuaLaTeX dev team (https://github.com/lualatex/).

       This manual page was written by Philipp Gesang <phg@phi-gamma.net>.

       GPL v2.0