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>.

COPYRIGHT

       GPL v2.0