title: user_caps(5)

text:
# user_caps(5)

## NAME
user_caps - user-defined terminfo capability format

## SYNOPSIS
infocmp -x

tic -x

## DESCRIPTION

### Background
Before ncurses 5.0, terminfo databases used a fixed repertoire of terminal capabilities designed for the SVr2 terminal database in 1984, and extended in stages through SVr4 (1989), and standardized in X/Open Curses starting in 1995.

Most of the extensions in this fixed repertoire were additions to the tables of Boolean, numeric and string capabilities. Rather than change the meaning of an existing capability, a new name was added. The terminfo database uses a binary format; binary compatibility was ensured by using a header which gave the number of items in the tables for each type of capability. The standardization was incomplete:

•

The binary format itself is not described in the X/Open Curses documentation. Only the source format is described.

Library developers rely upon the SVr4 documentation, and reverse-engineering the compiled terminfo files to match the binary format.

•

Lacking a standard for the binary format, most implementations copy the SVr2 binary format, which uses 16-bit signed integers, and is limited to 4096-byte entries.

The format cannot represent very large numeric capabilities, nor can it represent large numbers of special keyboard definitions.

•

The tables of capability names differ between implementations.

Although they may provide all of the standard capability names, the position in the tables differs because some features were added as needed, while others were added (out of order) to comply with X/Open Curses.

While ncurses' repertoire of predefined capabilities is closest to Solaris, Solaris's terminfo database has a few differences from the list published by X/Open Curses. For example, ncurses can be configured with tables which match the terminal databases for AIX, HP-UX or OSF/1, rather than the default Solaris-like configuration.

•

In SVr4 curses and ncurses, the terminal database is defined at compile-time using a text file which lists the different terminal capabilities.

In principle, the text-file can be extended, but doing this requires recompiling and reinstalling the library. The text-file used in ncurses for terminal capabilities includes details for various systems past the documented X/Open Curses features. For example, ncurses supports these capabilities in each configuration:

memory_lock

(meml) lock memory above cursor

memory_unlock

(memu) unlock memory

box_chars_1

(box1) box characters primary set

The memory lock/unlock capabilities were included because they were used in the X11R6 terminal description for xterm(1). The box1 capability is used in tic to help with terminal descriptions written for AIX.

During the 1990s, some users were reluctant to use terminfo in spite of its performance advantages over termcap:

- The fixed repertoire prevented users from adding features for unanticipated terminal improvements (or required them to reuse existing capabilities as a workaround).

- The limitation to 16-bit signed integers was also mentioned. Because termcap stores everything as a string, it could represent larger numbers.

Although termcap's extensibility was rarely used (it was never the speaker who had actually used the feature), the criticism had a point. ncurses 5.0 provided a way to detect nonstandard capabilities, determine their type and optionally store and retrieve them in a way which did not interfere with other applications. These are referred to as user-defined capabilities because no modifications to the toolset's predefined capability names are needed.

The ncurses utilities tic and infocmp have a command-line option “-x” to control whether the nonstandard capabilities are stored or retrieved. A library function use_extended_names is provided for the same purpose.

When compiling a terminal database, if “-x” is set, tic will store a user-defined capability if the capability name is not one of the predefined names.

Because ncurses provides a termcap library interface, these user-defined capabilities may be visible to termcap applications:

•

The termcap interface (like all implementations of termcap) requires that the capability names are 2-characters.

When the capability is simple enough for use in a termcap application, it is provided as a 2-character name.

- There are other user-defined capabilities which refer to features not usable in termcap, e.g., parameterized strings that use more than two parameters or use more than the trivial expression support provided by termcap. For these, the terminfo database should have only capability names with 3 or more characters.

- Some terminals can send distinct strings for special keys (cursor-, keypad- or function-keys) depending on modifier keys (shift, control, etc.). While terminfo and termcap have a set of 60 predefined function-key names, to which a series of keys can be assigned, that is insufficient for more than a dozen keys multiplied by more than a couple of modifier combinations. The ncurses database uses a convention based on xterm(1) to provide extended special-key names.

Fitting that into termcap's limitation of 2-character names would be pointless. These extended keys are available only with terminfo.

### Recognized Capabilities
The ncurses library uses the user-definable capabilities. While the terminfo database may have other extensions, ncurses makes explicit checks for these:

AX

Boolean, asserts that the terminal interprets SGR 39 and SGR 49 by resetting the foreground and background color, respectively, to the default.

This is a feature recognized by the screen program as well.

E3

string, tells how to clear the terminal's scrollback buffer. When present, the clear(1) program sends this before clearing the terminal.

The command “tput clear” does the same thing.

NQ

Boolean, used to suppress a consistency check in tic for the ncurses capabilities in user6 through user9 (u6, u7, u8 and u9) which tell how to query the terminal's cursor position and its device attributes.

RGB

Boolean, number or string, used to assert that the set_a_foreground and set_a_background capabilities correspond to direct colors, using an RGB (red/green/blue) convention. This capability allows the color_content function to return appropriate values without requiring the application to initialize colors using init_color.

The capability type determines the values which ncurses sees:

Boolean

implies that the number of bits for red, green and blue are the same. Using the maximum number of colors, ncurses adds two, divides that sum by three, and assigns the result to red, green and blue in that order.

If the number of bits needed for the number of colors is not a multiple of three, the blue (and green) components lose in comparison to red.

number

tells ncurses what result to add to red, green and blue. If ncurses runs out of bits, blue (and green) lose just as in the Boolean case.

string

explicitly list the number of bits used for red, green and blue components as a slash-separated list of decimal integers.

Because there are several RGB encodings in use, applications which make assumptions about the number of bits per color are unlikely to work reliably. As a trivial case, for example, one could define RGB#1 to represent the standard eight ANSI colors, i.e., one bit per color.

U8

number, asserts that ncurses must use Unicode values for line-drawing characters, and that it should ignore the alternate character set capabilities when the locale uses UTF-8 encoding. For more information, see the discussion of NCURSES_NO_UTF8_ACS in ncurses(3X).

Set this capability to a nonzero value to enable it.

XM

string, override ncurses's built-in string which enables/disables xterm(1) mouse mode.

ncurses sends a character sequence to the terminal to initialize mouse mode, and when the user clicks the mouse buttons or (in certain modes) moves the mouse, handles the characters sent back by the terminal to tell it what was done with the mouse.

The mouse protocol is enabled when the mask passed in the mousemask function is nonzero. By default, ncurses handles the responses for the X11 xterm mouse protocol. It also knows about the SGR 1006 xterm mouse protocol, but must to be told to look for this specifically. It will not be able to guess which mode is used, because the responses are enough alike that only confusion would result.

The XM capability has a single parameter. If nonzero, the mouse protocol should be enabled. If zero, the mouse protocol should be disabled. ncurses inspects this capability if it is present, to see whether the 1006 protocol is used. If so, it expects the responses to use the SGR 1006 xterm mouse protocol.

The xterm mouse protocol is used by other terminal emulators. The terminal database uses building-blocks for the various xterm mouse protocols which can be used in customized terminal descriptions.

The terminal database building blocks for this mouse feature also have an experimental capability xm. The “xm” capability describes the mouse response. Currently there is no interpreter which would use this information to make the mouse support completely data-driven.

xm shows the format of the mouse responses. In this experimental capability, the parameters are

p1

y-ordinate

p2

x-ordinate

p3

button

p4

state, e.g., pressed or released

p5

y-ordinate starting region

p6

x-ordinate starting region

p7

y-ordinate ending region

p8

x-ordinate ending region

Here are examples from the terminal database for the most commonly used xterm mouse protocols:

```
  xterm+x11mouse|X11 xterm mouse protocol,

          kmous=\E[M, XM=\E[?1000%?%p1%{1}%=%th%el%;,

          xm=\E[M

             %?%p4%t%p3%e%{3}%;%' '%+%c

             %p2%'!'%+%c

             %p1%'!'%+%c,

  xterm+sm+1006|xterm SGR-mouse,

          kmous=\E[<, XM=\E[?1006;1000%?%p1%{1}%=%th%el%;,

          xm=\E[<%i%p3%d;

             %p1%d;

             %p2%d;

             %?%p4%tM%em%;,
```

### Extended Key Definitions
Several terminals provide the ability to send distinct strings for combinations of modified special keys. There is no standard for what those keys can send.

Since 1999, xterm(1) has supported shift, control, alt, and meta modifiers which produce distinct special-key strings. In a terminal description, ncurses has no special knowledge of the modifiers used. Applications can use the naming convention established for xterm to find these special keys in the terminal description.

Starting with the curses convention that capability codes describing the input generated by a terminal's key caps begin with “k”, and that shifted special keys use uppercase letters in their names, ncurses's terminal database defines the following names and codes to which a suffix is added.

Code

Description

kDC

shifted kdch1 (delete character)

kDN

shifted kcud1 (cursor down)

kEND

shifted kend (end)

kHOM

shifted khome (home)

kLFT

shifted kcub1 (cursor back)

kNXT

shifted knext (next)

kPRV

shifted kprev (previous)

kRIT

shifted kcuf1 (cursor forward)

kUP

shifted kcuu1 (cursor up)

Keycap nomenclature on the Unix systems for which curses was developed differs from today's ubiquitous descendants of the IBM PC/AT keyboard layout. In the foregoing, interpret “backward” as “left”, “forward” as “right”, “next” as “page down”, and “prev(ious)” as “page up”.

These are the suffixes used to denote the modifiers:

Value

Description

2

Shift

3

Alt

4

Shift + Alt

5

Control

6

Shift + Control

7

Alt + Control

8

Shift + Alt + Control

9

Meta

10

Meta + Shift

11

Meta + Alt

12

Meta + Alt + Shift

13

Meta + Ctrl

14

Meta + Ctrl + Shift

15

Meta + Ctrl + Alt

16

Meta + Ctrl + Alt + Shift

None of these are predefined; terminal descriptions can refer to names which ncurses will allocate at runtime to key-codes. To use these keys in an ncurses program, an application could do this:

- using a list of extended key names, ask tigetstr(3X) for their values, and

- given the list of values, ask key_defined(3X) for the key-code which would be returned for those keys by wgetch(3X).

## PORTABILITY
The “-x” extension feature of tic and infocmp has been adopted in NetBSD curses. That implementation stores user-defined capabilities, but makes no use of these capabilities itself.

## AUTHORS
Thomas E. Dickey

beginning with ncurses 5.0 (1999)

## SEE ALSO
infocmp(1M), tic(1M)

The terminal database section NCURSES USER-DEFINABLE CAPABILITIES summarizes commonly-used user-defined capabilities which are used in the terminal descriptions. Some of those features are mentioned in screen(1) or tmux(1).

XTerm Control Sequences provides further information on the xterm(1) features that are used in these extended capabilities.


fmtutil.cnf

package: texlive-collection-basic

title: fmtutil.cnf(5)

summary: configuration file for fmtutil

text:
# fmtutil.cnf(5)

## NAME
fmtutil.cnf - configuration file for fmtutil

## DESCRIPTION
The fmtutil.cnf file contains the configuration information for fmtutil(8). Each line contains the name of the format (e.g., ``tex´´, ``latex´´, ``omega´´), the name of the engine that is used by that format (e.g., ``tex´´, ``etex´´, ``omega´´), the pattern file (e.g., language.dat, language.def), and any arguments (name of an .ini file).

Fields are separated by whitespace and complete lines can be commented out with ``#´´. The ``pattern file´´ field cannot be used to define a file that is used while building the format. It tells fmtutil which files (separated by commas) the format creation procedure reads and it has an effect to the options --showhyphen and --byhyphen. If the format has no way to customize hyphenation, a ``-´´ can be used to indicate this.

## NOTES
The tex(1) and amstex(1) formats always load hyphen.tex. No customization by a pattern file is available for these formats. Therefore, the pattern-file field for the tex and amstex is usually indicated to be empty (``-´´).

You can, however, build customized formats on top of plain tex(1) or amstex(1) by using bplain.tex instead of plain.tex (b for the Babel system). See, for example, the bplain.ini file for the bplain format).

etex(1) loads language.def, not language.dat.

Symbolic links to the correct engines (e.g., bplain -> tex) are generated by the texlinks(8) script. Remember to run texlinks(8) if you run fmtutil(8) yourself, rather than using the FORMATS option in texconfig(8).

## FILES
fmtutil.cnf

default configuration file

language.dat

hyphenation pattern file

language.def

hyphenation pattern file

language.dat.lua

hyphenation pattern file

## SEE ALSO
amstex(1), etex(1), fmtutil(8), tex(1), texconfig(8), texlinks(8).

<https://tug.org/texlive/scripts-sys-user.html>

## BUGS
Email bug reports to <https://lists.tug.org/tex-k> (public mailing list).

## AUTHOR
fmtutil and fmtutil.cnf was originally written by Thomas Esser.

This manual page was written by C.M. Connelly for the Debian GNU/Linux system. It is now maintained as part of TeX Live.

branch: sisyphus


luaotfload.conf

title: luaotfload.conf(5)

summary: Luaotfload configuration file

text:
# luaotfload.conf(5)

## 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. In Opentype, these are specified as “decipoints” where one decipoint equals ten DTP style “big points”. When indexing fonts these values are converted to sp. In order to treat the values as though they were specified in TeX points or Didot points, set designsize-dimen to pt or 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>

keepnames

b

true

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.

The keepnames option decides if the ConTeXt fontloader should keep names it considers useless or if they should be discarded. This option only takes effect after font caches are regenererated.

### 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/latex3/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 was developed by the LuaLaTeX dev team (https://github.com/lualatex/). It is currently maintained by the LaTeX Project Team at https://github.com/latex3/luaotfload

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

## COPYRIGHT
GPL v2.0


prerex

title: prerex(5)

text:
# prerex(5)

## NAME
prerex_format -- a format for prerequisite-chart descriptions

## DESCRIPTION
This manual describes the format of prerequisite-chart descriptions that can be processed by [pdf]latex (normally using a suitable prerex.sty(7) style file) and edited using the prerex(1) interactive editor (or by any conventional text editor).

## TERMINOLOGY
A prerequisite chart consists of a number of course boxes, linked by arrows. Courses are either half or full, and may be required or optional (or neither). Each course box can contain a course code (upper left corner), a course title (lower half), and timetable information (upper right corner). An arrow can be either a prerequisite (solid), a corequisite (dotted), or recommended (dashed). When a conventional arrow would be inappropriate, a mini course just above a target box can be used.

## STRUCTURE
The file should contain exactly one instance of a LaTeX environment

\begin{chart} instruction ... \end{chart}

with at most one instruction per line. Note that a program such as prerex(1) analyzes prerex-format files without using TeX; for example, macro definitions will be ignored and macro calls will not be expanded.

Instructions may be preceded by white space. Lines that start with % are treated as comments and ignored. The order of instructions is not significant except that the instruction for the source and target box o an arrow should precede the instruction for the arrow. The instruction formats are described in the following sections.

## COURSE BOXES
The instructions producing course boxes have the following forms:

\halfcourse x,y:{code}{title}{timetable}

\fullcourse x,y:{code}{title}{timetable}

\reqhalfcourse x,y:{code}{title}{timetable}

\reqfullcourse x,y:{code}{title}{timetable}

\opthalfcourse x,y:{code}{title}{timetable}

\optfullcourse x,y:{code}{title}{timetable}

where x,y are the coordinates of the centerpoint of the box, relative to the origin of the coordinate system at the lower-left corner of the diagram. The code, title, and timetable arguments are arbitrary (well-bracketed) text, possibly with LaTeX markup.

The following are similar but take an additional argument to specify the (non-default) background color of the course box:

\halfcoursec x,y:{code}{title}{timetable}{color}

\fullcoursec x,y:{code}{title}{timetable}{color}

\reqhalfcoursec x,y:{code}{title}{timetable}{color}

\reqfullcoursec x,y:{code}{title}{timetable}{color}

\opthalfcoursec x,y:{code}{title}{timetable}{color}

\optfullcoursec x,y:{code}{title}{timetable}{color}

## MINI COURSE BOXES AND TEXT
A mini course is produced by an instruction of the form

\mini x,y:{code}

A text line is inserted into the chart by an instruction of the form

\text x,y:{line-of-text}

The maximum allowed length of a course-code may be smaller that the maximum allowed for a line of text.

## ARROWS
Arrows between course boxes (or from a mini to a course box) are produced by instructions of the form

\prereq x0,y0,x1,y1:

\coreq x0,y0,x1,y1:

\recomm x0,y0,x1,y1:

These produce, respectively, solid, dotted, and dashed arrows from the course box (or mini) centered at coordinates x0,y0 to the course box centered at coordinates x1,y1.

In some implementations, certain arrows by default have a non-zero curvature. It is possible to override the default curvature for a particular arrow by using the instructions

\prereqc x0,y0,x1,y1;c:

\coreqc x0,y0,x1,y1;c:

\recommc x0,y0,x1,y1;c:

where c is an integer in the range -100:100 specifying the desired curvature; for example, c=0 will produce a straight arrow. To change the default curvature, the user program may redefine the \DefaultCurvature command.

## COORDINATE GRID
The following instruction produces a coordinate grid, which is useful for editing a diagram:

\grid

This is normally placed before all the other instructions so that grid lines are in the background, covered by course boxes, minis, and arrows.

## WEB LINKS
Course boxes may be linked to web addresses. The URL for course boxes may be set by the user by redefining the \CourseURL command; when called for a course box, it is supplied with three arguments, the x and y coordinates of the box, mini, or textline, and the code argument of the course box. For example,

\renewcommand{\CourseURL}[3]{http://www.cs.queensu.ca/undergraduate/courses/#3.html}

is appropriate for courses at the School of Computing, Queen's University. The first two arguments can be used to display the coordinates of a box, mini, or textline in some PDF viewers while the mouse hovers over it when the source file is being edited.

## AUTHOR
R. D. Tennent (rdt@cs.queensu.ca)

## SEE ALSO
prerex(1), prerex.sty(7).


synctex

title: synctex(5)

summary: Synchronize TeXnology help file

text:
# synctex(5)

## NAME
synctex — Synchronize TeXnology help file

## DESCRIPTION
Synchronize TeXnology help file (synctexs) are text files that help input/output synchronization during document preparation with the TeX typesetting system.

## BASICS
The structure of this file should not be considered public, in the sense that no one should need to parse its contents, except the synctex command line utility, and the synctex_parser library which are both publicly available. Unless it is absolutely not avoidable, access to the contents of the synctex file should only be made through requests made to the synctex command line utility.

## STRUCTURE
The element structure of a synctex file is a list of text line records as follows. ‘*’, ‘+’, and ‘?’ have their usual EBNF meanings: ‘*’ means zero or more, ‘+’ means one or more, and ‘?’ means zero or one (i.e., optional).

- <SyncTeX> ::= (The whole contents in 4 sections)

- <Preamble>

- <Content>

- <Postamble>

- <Post Scriptum>

Each section starts with the first occurrence of a sectioning line, and ends with the next section, if any. In the following definitions, we do not mention the section ending condition.

## The preamble

- <Preamble> ::=

- "SyncTeX Version:" <Version Number> <EOL>

- <Input Line>*

- "Magnification:" <TeX magnification> <EOL>

- "Unit:" <unit in scaled point> <EOL>

- "X Offset:" <horizontal offset in scaled point> <EOL>

- "Y Offset:" <vertical offset in scaled point> <EOL>

- <Input Line> ::= "Input:" <tag> ":" <File Name> <EOL>

## The content

- <Content> ::=

- <byte offset record>

- "Content:" <EOL>

- (<Form(k)>|<Input Line>)*

- <sheet(1)>

- (<Form(k)>|<Input Line>)*

- <sheet(2)>

- (<Form(k)>|<Input Line>)*

- ...

- <sheet(N)>

- (<Form(k)>|<Input Line>)*

- <byte offset record> ::= "!" <byte offset> <end of record>

- <sheet(n)> ::=

- <byte offset record>

- "{" <the integer n> <end of record>

- <vbox section>|<hbox section>

- <byte offset record>

- "}" <the integer n> <end of record>

- <Form> ::=

- <byte offset record>

- "<" <form tag> <end of record>

- <vbox section>|<hbox section>

- <byte offset record>

- ">" <end of record>

- <form tag> ::= <integer>

Forms are available with pdfTeX. All the numbers are integers encoded using the decimal representation with "C" locale. The <box content> describes what is inside a box. It is either a vertical or horizontal box, with some records related to glue, kern or math nodes.

- <box content> ::=

- <vbox section>|<hbox section>

- |<void vbox record>|<void hbox record>

- |<current record>|<glue record>|<kern record>

- |<math record>|<form ref record>|<Form>

- <vbox section> ::=

- "[" <link> ":" <point> ":" <size> <end of record>

- <box content>*

- "]" <end of record>

- <hbox section> ::=

- ( <link> ":" <point> ":" <size> <end of record>

- <box content>*

- ")" <end of record>

Void boxes:

- <void vbox record> ::= "v" <link> ":" <point> ":" <size> <end of record>

- <void hbox record> ::= "h" <link> ":" <point> ":" <size> <end of record>

- <link> ::= <tag> "," <line>( "," <column>)?

- <point> ::= <full point>|<compressed point>

- <full point> ::= <integer> "," <integer>

- <compressed point> ::= <integer> ",="

- <line> ::= <integer>

- <column> ::= <integer>

- <size> ::= <Width> "," <Height> "," <Depth>

- <Width> ::= <integer>

- <Height> ::= <integer>

- <Depth> ::= <integer>

The forthcoming records are basic one liners.

- <current record> ::= "x" <link> ":" <point> <end of record>

- <kern record> ::= "k" <link> ":" <point> ":" <Width> <end of record>

- <glue record> ::= "g" <link> ":" <point> <end of record>

- <math record> ::= "$" <link> ":" <point> <end of record>

- <form ref record> ::= "f" <form tag> ":" <point> <end of record>

## The postamble
The postamble closes the file If there is no postamble, it means that the typesetting process did not end correctly.

- <Postamble>::=

- <byte offset record>

- "Count:" <Number of records> <EOL>

## The post scriptum
The post scriptum contains material possibly added by 3rd parties. It allows to append some transformation (shift and magnify). Typically, one applies a dvi to pdf filter with offset options and magnification, then he appends the same options to the synctex file, for example

```
synctex update -o foo.pdf -m 0.486 -x 9472573sp -y 13.3dd source.dvi
```

- <Post Scriptum>::=

- <byte offset record>

- "Post Scriptum:" <EOL>

- "Magnification:" <number> <EOL> (Set additional magnification)

- "X Offset:" <dimension> <EOL> (Set horizontal offset)

- "Y Offset:" <dimension> <EOL> (Set vertical offset)

This second information will override the offset and magnification previously available in the preamble section. All the numbers are encoded using the decimal representation with "C" locale.

## USAGE
The <current record> is used to compute the visible size of hbox's. The byte offset is an implicit anchor to navigate the synctex file from sheet to sheet. The second coordinate of a compressed point has been replaced by a "=" character which means that it is the second coordinate of the last full point available above.

## SEE ALSO
synctex(1) tex(1)

## AUTHOR
The Synchronize TeXnology is essentially due to Jerome Laurens, with useful suggestions by some well known actors of the TeX world.

## HISTORY
This document has been updated on Sat Apr 22 09:57:20 UTC 2017 to include \pdfxform support.


updmap.cfg

title: updmap.cfg(5)

text:
# updmap.cfg(5)

## NAME
updmap.cfg - configuration of font mapping/inclusion for dvips and friends.

## DESCRIPTION
The file updmap.cfg is the central font configuration file of a teTeX system and is read by updmap(1). It describes if and how fonts should be included (or not included) into PS-/PDF-files. This works for Outline (Postscript Type1) and Bitmap Fonts (Postscript Type3) mostly coming from MetaFont.

updmap is a utility that creates font configuration files for dvips(1), pdftex(1), xdvi(1), ps2pk(1), gsftopk(1), and dvipdfmx(1). In an ideal world, updmap would be unnecessary -- each of these programs would read the same configuration file to learn what fonts are available and how they should be treated. As things stand, however, each of these tools has subtly different requirements and thereby needs its own font configuration file. updmap creates font configuration files for all of these programs from several sources, namely all updmap.cfg, allowing you to easily keep all the different configuration files in sync.

Running "updmap --help" will output the main documentation for using updmap.

dvipsPreferOutline

Configures if dvips (by default) should prefer bitmap fonts or outline fonts if both are available? Independent of this setting, outlines can be forced by putting "p psfonts_t1.map" into a config file that dvips reads. Bitmaps can be forced by putting "p psfonts_pk.map" into a config file. We provide such config files which can be enabled via dvips -Poutline (resp. dvips -Ppk).

Valid settings for dvipsPreferOutline are true / false.

LW35

Which fonts of the "Basic 35 Laserwriter Fonts" do you want to use and how are the filenames chosen? Valid settings:

URW: URW fonts with "vendor" filenames (e.g. n019064l.pfb)

URWkb: URW fonts with "berry" filenames (e.g. uhvbo8ac.pfb)

ADOBE: Adobe fonts with "vendor" filenames (e.g. hvnbo___.pfb)

ADOBEkb: Adobe fonts with "berry" filenames (e.g. phvbo8an.pfb)

dvipsDownloadBase35

Configures if dvips (by default) should download the 35 base PostScript fonts into the document (set true) or should these fonts be used from the ps interpreter / printer (set false).

The user can override the default by specifying dvips -Pdownload35 (resp. dvips -Pbuiltin35) to download the LW35 fonts (resp. use the built-in fonts).

Valid settings are true / false.

pdftexDownloadBase14

Should pdftex download the 14 base PDF fonts? Since some configurations (ps / pdf tools / printers) use bad default fonts, it is safer to download the fonts. The pdf files get bigger, but that is the cost.

Valid settings are true (download the fonts) or false (don't download the fonts). Adobe recommends embedding all fonts.

pxdviUse

Should special map files for pxdvi be created? pxdvi is an adaption of xdvi with support for reading and displaying files generated by the ptex family of engines.

Valid settings are true (generate configuration) or false. See http://www.tug.org/texlive/updmap-kanji.html for detailed discussion.

kanjiEmbed

kanjiVariant

The options kanjiEmbed and kanjiVariant specify special replacements in the map lines. In a map, the string "@kanjiEmbed@" will be replaced by the value of that option; similarly for kanjiVariant. In this way, users of Japanese TeX can select different fonts to be included in the final output.

Map

Points to a map file, which describes a mapping from a font (called in the TeX document) to the pfb file containing the Postscript code.

Usage: Map filename.map

The syntax of map files is the same as dvips(1) uses, see the section "psfonts.map" in the manual of dvips(1).

MixedMap

Similar to Map. It should be used when there is Type1 and a bitmap implementation of the font (the latter mostly coming from MetaFont). These entries will not be used in the default map of dvips if dvipsPreferOutline is set to false.

Usage: MixedMap filename.map

KanjiMap

Similar to Map. This should be used for kanji fonts.

Usage: KanjiMap filename.map

The sign # precedes a comment.

Map files not to be used should be commented out using the string #! at the beginning of the line. Such entries can be (de-)activated using updmap with the options --enable and --disable, respectively.

## AUTHOR
This manual page was written by Hilmar Preusse <hille42@web.de> and extended by Norbert Preining <preining@logic.at>, for the Debian GNU/Linux system by simply copying the comments from updmap.cfg and rewriting some of them. It may be used by other distributions without contacting the author. Any mistakes or omissions in the manual page are our fault; inquiries about or corrections to this manual page should be directed to tex-live@tug.org.

## SEE ALSO
updmap(1), dvips(1)

## THANKS TO
Frank Kuester, Thomas Esser.


thermal-conf.xml

package: thermald

title: thermal-conf.xml(5)

summary: Configuration file for thermal daemon

text:
# thermal-conf.xml(5)

## NAME
thermal-conf.xml - Configuration file for thermal daemon

## SYNOPSIS
$(TDCONFDIR)/etc/thermald/thermal-conf.xml

## DESCRIPTION
thermal-conf.xml is a configuration file for the thermal daemon. It is used to configure thermal sensors, zone and cooling devices. The location of this file depends on the configuration option used during build time.

The terminology used in this file conforms to "Advanced Configuration and Power Interface Specification". The ACPI thermal model is based around conceptual platform regions called thermal zones that physically contain devices, thermal sensors, and cooling controls. For example of a thermal zone can be a CPU or a laptop cover. A zone can contain multiple sensors for monitoring temperature. A cooling device provides interface to reduce the temperature of a source device, which causes increase in the temperature. An example of a cooling device is a FAN or some Linux driver which can throttle the source device.

A thermal zone configuration includes one or more trip points. A trip point is a temperature at which a cooling device needs to be activated.

A cooling device can be either active or passive. An example of an active device is a FAN, which will not reduce performance at the cost of consuming more power and noise. A passive device uses performance throttling to control temperature. In addition to cooling devices present in the thermal sysfs, the following cooling devices are built into the thermald, which can be used as valid cooling device type:

- rapl_controller

- intel_pstate

- cpufreq

- LCD

The thermal sysfs under Linux (/sys/class/thermal) provides a way to represent per platform ACPI configuration. The kernel thermal governor uses this data to keep the platform thermals under control. But there are some limitations, which thermald tries to resolve. For example:

- If the ACPI data is not optimized or buggy. In this case thermal-conf.xml can be used to correct the behavior without change in BIOS.

- There may be thermal zones exposed by the thermal sysfs without associated cooling actions. In this case thermal conf.xml can be used to tie the cooling devices to those zones.

- The best cooling method may not be in the thermal sysfs. In this case thermal-conf.xml can be used to bind a zone to an external cooling device.

- Specify thermal relationships. A zone can be influenced by multiple source devices with varying degrees. In this case thermal-conf.xml can be used to define the relative influence for apply compensation.

## FILE FORMAT
The configuration file format conforms to XML specifications. A set of tags defined to define platform, sensors, zones, cooling devices and trip points.

```
<ThermalConfiguration>

  <Platform>

    <Name>Example Platform Name</Name>

    <!-- UUID is optional, if present this will be matched. Both product

         name and UUID can contain wild card "*", which matches any

         platform. -->

    <UUID>Example UUID</UUID>

    <!-- configuration file format conforms to XML specifications. A

         set of tags defined to define platform, sensors, zones, cooling

         devices and trip points. -->

    <ProductName>Example Product Name</ProductName>

    <Preference>QUIET|PERFORMANCE</Preference>

    <!-- Quiet mode will only use passive cooling device. "PERFORMANCE"

         will only select active devices. -->

    <ThermalSensors>

      <ThermalSensor>

        <!-- New Sensor with a type and path -->

        <Type>example_sensor_1</Type>

        <Path>/some_path</Path>

        <AsyncCapable>0</AsyncCapable>

      </ThermalSensor>

      <ThermalSensor>

        <!-- Already present in thermal sysfs, enable this or

             add/change config For example, here we are indicating

             that sensor can do async events to avoid polling. -->

        <Type>example_thermal_sysfs_sensor</Type>

        <!-- If async capable, then we don't need to poll. -->

        <AsyncCapable>1</AsyncCapable>

      </ThermalSensor>

    </ThermalSensors>

    <ThermalZones>

      <ThermalZone>

        <Type>Example Zone type</Type>

        <TripPoints>

          <TripPoint>

            <SensorType>example_sensor_1</SensorType>

            <!-- Temperature at which to take action. -->

            <Temperature> 75000 </Temperature>

            <!-- max/passive/active If a MAX type is specified, then

                 daemon will use PID control to aggressively throttle

                 to avoid reaching this temp. -->

            <type>max</type>

            <!-- SEQUENTIAL | PARALLEL. When a trip point temp is

                 violated, then number of cooling devices can be

                 activated. If control type is SEQUENTIAL then, it

                 will exhaust first cooling device

                 before trying next. -->

            <ControlType>SEQUENTIAL</ControlType>

            <CoolingDevice>

              <index>1</index>

              <type>example_cooling_device</type>

              <!-- Influence will be used order cooling devices. First

                   cooling device will be used, which has highest

                   influence. -->

              <influence> 100 </influence>

              <!-- Delay in using this cdev, this takes some time too

                   actually cool a zone. -->

              <SamplingPeriod> 12 </SamplingPeriod>

              <!-- Set a specific state of this cooling device when this

                   trip is violated. -->

              <TargetState> 6 </TargetState>

            </CoolingDevice>

          </TripPoint>

        </TripPoints>

      </ThermalZone>

    </ThermalZones>

    <CoolingDevices>

      <CoolingDevice>

        <!-- Cooling device can be specified by a type and optionally

             a sysfs path. If the type is already present in thermal

             sysfs, there is no need of a path. Compensation can use

             min/max and step size to increasing cool the system.

             Debounce period can be used to force a waiting period

             for action. -->

        <Type>example_cooling_device</Type>

        <MinState>0</MinState>

        <IncDecStep>10</IncDecStep>

        <ReadBack> 0 </ReadBack>

        <MaxState>50</MaxState>

        <DebouncePeriod>5000</DebouncePeriod>

        <!-- If there are no PID parameters, compensation increase step

             wise and exponentially (if single step is not able to

             change trend).

             Alternatively a PID parameters can be specified then next

             step will use PID calculation using provided PID

             constants. -->

        <PidControl>

          <kp>0.001</kp>

          <kd>0.0001</kd>

          <ki>0.0001</ki>

        </PidControl>

        <!-- Write some prefix attached to state value, like below the

             prefix is "level ". It will preserve spaces as entered

             when writing to sysfs. -->

        <WritePrefix>level </WritePrefix>

      </CoolingDevice>

    </CoolingDevices>

  </Platform>
</ThermalConfiguration>
```

## EXAMPLE CONFIGURATIONS
Example 1: This is a very simple configuration, to change the passive limit on the CPU. Instead of default, this new temperature 86C in the configuration is used. This will start cooling, once the temperature reaches 86C.

```
<?xml version="1.0"?>
<ThermalConfiguration>

  <Platform>

    <Name>Override CPU default passive</Name>

    <ProductName>*</ProductName>

    <Preference>QUIET</Preference>

    <ThermalZones>

      <ThermalZone>

        <Type>cpu</Type>

        <TripPoints>

          <TripPoint>

            <Temperature>86000</Temperature>

            <type>passive</type>

          </TripPoint>

        </TripPoints>

      </ThermalZone>

    </ThermalZones>

  </Platform>
</ThermalConfiguration>
```

Example 2: In this configuration, we are controlling backlight when some sensor "SEN2" reaches 60C. Here "LCD" is a standard cooling device, which uses Linux backlight sysfs interface. "LCD_Zone" is a valid thermal zone in Linux thermal sysfs on the test platform, hence we don't need to provide path for sysfs for "LCD_Zone". The Linux thermal sysfs is already parsed and loaded by the thermald program.

```
<?xml version="1.0"?>
<ThermalConfiguration>

  <Platform>

    <Name>Change Backlight</Name>

    <ProductName>*</ProductName>

    <Preference>QUIET</Preference>

    <ThermalZones>

      <ThermalZone>

        <Type>LCD_Zone</Type>

        <TripPoints>

          <TripPoint>

            <SensorType>SEN2</SensorType>

            <Temperature>60000</Temperature>

            <type>passive</type>

            <CoolingDevice>

              <Type>LCD</Type>

            </CoolingDevice>

          </TripPoint>

        </TripPoints>

      </ThermalZone>

    </ThermalZones>

  </Platform>
</ThermalConfiguration>
```

Example 3: In this example Lenovo Thinkpad X220 and fan speed is controlled. Here a cooling device "_Fan", can be controlled via sysfs /sys/devices/platform/thinkpad_hwmon/pwm1. When the x86_pkg_temp reaches 45C, Fan is started with increasing speeds, if the temperature can't be controlled at 45C.

```
<?xml version="1.0"?>
<ThermalConfiguration>

  <Platform>

    <Name>Lenovo ThinkPad X220</Name>

    <ProductName>*</ProductName>

    <Preference>QUIET</Preference>

    <ThermalZones>

      <ThermalZone>

        <Type>x86_pkg_temp</Type>

        <TripPoints>

          <TripPoint>

            <SensorType>x86_pkg_temp</SensorType>

            <Temperature>45000</Temperature>

            <type>passive</type>

            <ControlType>SEQUENTIAL</ControlType>

            <CoolingDevice>

              <index>1</index>

              <type>_Fan</type>

              <influence> 100 </influence>

              <SamplingPeriod> 12 </SamplingPeriod>

            </CoolingDevice>

          </TripPoint>

        </TripPoints>

      </ThermalZone>

    </ThermalZones>

    <CoolingDevices>

      <CoolingDevice>

        <Type>_Fan</Type>

        <Path>/sys/devices/platform/thinkpad_hwmon/pwm1</Path>

        <MinState>0</MinState>

        <IncDecStep>30</IncDecStep>

        <ReadBack> 0 </ReadBack>

        <MaxState>255</MaxState>

        <DebouncePeriod>5</DebouncePeriod>

      </CoolingDevice>

    </CoolingDevices>

  </Platform>
</ThermalConfiguration>
```

Example 4: The following example shows how PID can be used. Here once temperature exceeds 80C, compensation is calculated using PID using 80C as set point of PID. The compensation depends on error from the set point. Here the default built in processor cooling device is used with min state as 0 and max state as 10.

```
<?xml version="1.0"?>
<ThermalConfiguration>

  <Platform>

    <Name>Use PID param </Name>

    <ProductName>*</ProductName>

    <Preference>QUIET</Preference>

    <ThermalZones>

      <ThermalZone>

        <Type>x86_pkg_temp</Type>

        <TripPoints>

          <TripPoint>

            <SensorType>x86_pkg_temp</SensorType>

            <Temperature>80000</Temperature>

            <type>passive</type>

            <ControlType>SEQUENTIAL</ControlType>

            <CoolingDevice>

              <type>Processor</type>

            </CoolingDevice>

          </TripPoint>

        </TripPoints>

      </ThermalZone>

    </ThermalZones>

    <CoolingDevices>

      <CoolingDevice>

        <Type>Processor</Type>

        <PidControl>

          <kp>0.0002</kp>

          <kd>0</kd>

          <ki>0</ki>

        </PidControl>

      </CoolingDevice>

    </CoolingDevices>

  </Platform>
</ThermalConfiguration>
```

Example 5: The following example shows how to control Fan when the sysfs expects some string prefix. For example instead of just write a number to fan control sysfs, the interface requires "level " in front of the speed index value.

```
<?xml version="1.0"?>
<ThermalConfiguration>

  <Platform>

    <Name>Use Fan control first then CPU throttle </Name>

    <ProductName>*</ProductName>

    <Preference>QUIET</Preference>

    <ThermalZones>

      <ThermalZone>

        <Type>x86_pkg_temp</Type>

        <TripPoints>

          <TripPoint>

            <SensorType>x86_pkg_temp</SensorType>

            <Temperature>80000</Temperature>

            <type>passive</type>

            <ControlType>SEQUENTIAL</ControlType>

            <CoolingDevice>

              <type>_fan_</type>

            </CoolingDevice>

          </TripPoint>

        </TripPoints>

      </ThermalZone>

    </ThermalZones>

    <CoolingDevices>

      <CoolingDevice>

        <Type>_fan_</Type>

        <Path>/proc/acpi/ibm/fan</Path>

        <WritePrefix>level </WritePrefix>

        <MinState>0</MinState>

        <MaxState>5</MaxState>

        <DebouncePeriod>10</DebouncePeriod>

      </CoolingDevice>

    </CoolingDevices>

  </Platform>
</ThermalConfiguration>
```

Example 6: Similar to example 5, but write different speeds at different temperatures.

```
<?xml version="1.0"?>
<ThermalConfiguration>

  <Platform>

    <Name>Use Fan control first then CPU throttle </Name>

    <ProductName>*</ProductName>

    <Preference>QUIET</Preference>

    <ThermalZones>

      <ThermalZone>

        <Type>x86_pkg_temp</Type>

        <TripPoints>

          <TripPoint>

            <SensorType>x86_pkg_temp</SensorType>

            <Temperature>80000</Temperature>

            <type>passive</type>

            <CoolingDevice>

              <type>_fan_</type>

              <TargetState>1</TargetState>

            </CoolingDevice>

          </TripPoint>

          <TripPoint>

            <SensorType>x86_pkg_temp</SensorType>

            <Temperature>85000</Temperature>

            <type>passive</type>

            <CoolingDevice>

              <type>_fan_</type>

              <TargetState>2</TargetState>

            </CoolingDevice>

          </TripPoint>

        </TripPoints>

      </ThermalZone>

    </ThermalZones>

    <CoolingDevices>

      <CoolingDevice>

        <Type>_fan_</Type>

        <Path>/proc/acpi/ibm/fan</Path>

        <WritePrefix>level </WritePrefix>

        <MinState>0</MinState>

        <MaxState>5</MaxState>

        <DebouncePeriod>10</DebouncePeriod>

      </CoolingDevice>

    </CoolingDevices>

  </Platform>
</ThermalConfiguration>
```

Example 7: Use RAPL power limits to control.

```
<?xml version="1.0"?>
<!-- BEGIN -->
<ThermalConfiguration>
<Platform>
	<Name> TEST </Name>
	<ProductName>Example_RAPL_Power </ProductName>
	<Preference>QUIET</Preference>
	<PPCC>
		<!--
		Specify the Maximum/Minimum RAPL power limit for the
		platform. The limits are in milli watts.
		The step size to reduce/increase for each sampling interval
		Time window in miili seconds.
		-->
		<PowerLimitIndex>0</PowerLimitIndex>
		<PowerLimitMaximum>15000</PowerLimitMaximum>
		<PowerLimitMinimum>2000</PowerLimitMinimum>
		<TimeWindowMinimum>20</TimeWindowMinimum>
		<TimeWindowMaximum>30</TimeWindowMaximum>
		<StepSize>1000</StepSize>
	</PPCC>
	<ThermalZones>
		<ThermalZone>
			<Type>TestZone</Type>
			<TripPoints>
				<TripPoint>
					<SensorType>SEN3</SensorType>
					<Temperature>50000</Temperature>
					<Type>Passive</Type>
					<CoolingDevice>
						<Type>B0D4</Type>
						<SamplingPeriod>3</SamplingPeriod>
						<TargetState>2147483647</TargetState>
							<!--
							This setting means that when SEN3 reaches 50C, set the RAPL
							max power limit to whatever the maximum power limit of the
							platform.
							-->
					</CoolingDevice>
				</TripPoint>
				<TripPoint>
					<SensorType>SEN3</SensorType>
					<Temperature>52000</Temperature>
					<Type>Passive</Type>
					<CoolingDevice>
						<Type>B0D4</Type>
						<SamplingPeriod>3</SamplingPeriod>
						<TargetState>8500000</TargetState>
							<!--
							This setting means that when SEN3 reaches 52C, set the RAPL
							max power limit to 8.5W.
							-->
					</CoolingDevice>
				</TripPoint>
				<TripPoint>
					<SensorType>SEN3</SensorType>
					<Temperature>60000</Temperature>
					<Type>Passive</Type>
					<CoolingDevice>
						<Type>B0D4</Type>
						<SamplingPeriod>3</SamplingPeriod>
						<TargetState>4500000</TargetState>
							<!--
							This setting means that when SEN3 reaches 60C, set the RAPL
							max power limit to 4.5W.
							-->
					</CoolingDevice>
				</TripPoint>
				<TripPoint>
					<SensorType>SEN3</SensorType>
					<Temperature>65000</Temperature>
					<Type>Passive</Type>
					<CoolingDevice>
						<Type>B0D4</Type>
						<SamplingPeriod>3</SamplingPeriod>
							<!--
							This setting means that when SEN3 reaches 65C, set the RAPL
							max power limit to minimum power limit for the platform.
							-->
					</CoolingDevice>
				</TripPoint>
			</TripPoints>
		</ThermalZone>
	</ThermalZones>
</Platform>
</ThermalConfiguration>
```


thinkfan.conf

package: thinkfan

title: thinkfan.conf(5)

summary: YAML-formatted config for

text:
# thinkfan.conf(5)

## NAME
thinkfan.conf - YAML-formatted config for thinkfan(1)

## DESCRIPTION
YAML is a very powerful, yet concise notation for structured data. Its full specification is available at https://yaml.org/spec/1.2/spec.html. Thinkfan uses only a small subset of the full YAML syntax, so it may be helpful, but not strictly necessary for users to take a look at the spec.

The most important thing to note is that indentation is syntactically relevant. In particular, tabs should not be mixed with spaces. We recommend using two spaces for indentation, like it is shown below.

The thinkfan config has three main sections:

sensors:

Where temperatures should be read from. All hwmon-style drivers are supported, as well as /proc/acpi/ibm/thermal, and, depending on the compile-time options, libatasmart (to read temperatures directly from hard disks) and NVML (via the proprietary nvidia driver).

fans:

Which fans should be used (currently only one allowed). Support for multiple fans is currently in development and planned for a future release. Both hwmon-style PWM controls and /proc/acpi/ibm/fan can be used.

levels:

Maps temperatures to fan speeds. A “simple mapping” just specifies one temperature as the lower and upper bound (respectively) for a given fan speed. In a “detailed mapping”, the upper and lower bounds are specified for each driver/sensor configured under sensors:. This mode should be used when thinkfan is monitoring multiple devices that can tolerate different amounts of heat.

Under each of these sections, there must be a list of key-value maps, each of which configures a sensor driver, fan driver or fan speed mapping.

## SENSOR & FAN DRIVERS
For thinkfan to work, it first needs to know which temperature sensor drivers and which fan drivers it should use. The mapping between temperature readings and fan speeds is specified in a separate config section (see the FAN SPEEDS section below).

### Sensor Syntax
The entries under the sensors: section can specify sysfs/hwmon, lm_sensors, thinkpad_acpi, NVML or atasmart drivers. Support for lm_sensors, NVML and atasmart requires the appropriate libraries and must have been enabled at compile time. There can be any number (greater than zero) and combination of hwmon, tpacpi, nvml and atasmart entries. However there may be at most one instance of the tpacpi entry.

The syntax for identifying each type of sensors looks as follows:

```
########
sensors:
  - hwmon: hwmon-path          # A path to a sysfs/hwmon sensor
    name: hwmon-name           # Optional entry
    model: hwmon-model         # Optional entry for nvme
    indices: index-list        # Optional entry
  - chip: chip-name            # An lm_sensors/libsensors chip...
    ids: id-list               # ... with some feature IDs
  - tpacpi: /proc/acpi/ibm/thermal  # Provided by the thinkpad_acpi kernel module
    indices: index-list        # Optional entry
  - nvml: nvml-bus-id          # Uses the proprietary nVidia driver
  - atasmart: disk-device-file # Requires libatasmart support
  - ...
```

Additionally, each sensor entry can have a number of settings that modify its behavior:

```
########
sensors:
  - ...: ... # A sensor specification as shown above
    correction: correction-list  # Optional entry
    optional: bool-ignore-errors # Optional entry
    max_errors: num-max-errors   # Optional entry
```

### Fan Syntax
Since version 2.0, thinkfan can control multiple fans. So any number of hwmon fan sections can be specified. Note however that the thinkpad_acpi kernel module only supports one fan, so there can be at most one tpacpi section:

```
# ...
fans:
  - tpacpi: /proc/acpi/ibm/fan
  - hwmon: hwmon-path
    name: hwmon-name
    indices: index-list
  - ...
```

The behavior of any fan can optionally be controlled with the optional and max_errors keywords, and by specifying a local fan speed config under the levels: keyword:

```
# ...
fans:
  - ...:  ... # A fan specification as shown above
    optional: bool-ignore-errors # Optional entry
    max_errors: num-max-errors   # Optional entry
    levels: levels-section       # Optional entry
```

### Values
hwmon-path

There are three ways of specifying hwmon fans or sensors:

1)

A full path of a “temp*_input” or “pwm*” file, like “/sys/class/hwmon/hwmon0/pwm1” or “/sys/class/hwmon/hwmon0/temp1_input”. In this case, the “indices: index-list” and “name: hwmon-name” entries are unnecessary since the path uniquely identifies a specific fan or sensor.

Note that this method may lead to problems when the load order of the drivers changes across bootups, because in the “hwmonX” folder name, the X actually corresponds to the load order. Use method 2) or 3) to avoid this problem.

2)

A directory that contains a specific hwmon driver, for example “/sys/devices/platform/nct6775.2592”. Note that this path does not contain the load-order dependent “hwmonX” folder. As long as it contains only a single hwmon driver/interface it is sufficient to specify the “indices: index-list” entry to tell thinkfan which specific sensors to use from that interface. The “name: hwmon-name” entry is unnecessary.

3)

A directory that contains multiple or all of the hwmon drivers, for example “/sys/class/hwmon”. Here, both the “name: hwmon-name” and “indices: index-list” entries are required to tell thinkfan which interface to select below that path, and which sensors or which fan to use from that interface.

hwmon-name

The name of a hwmon interface, typically found in a file called “name”. This has to be specified if hwmon-path is a base path that contains multiple hwmons. This method of specifying sensors is particularly useful if the full path to a particular hwmon keeps changing between bootups, e.g. due to changing load order of the driver modules.

hwmon-model

The model of a device in a hwmon interface usually found for NVME devices in a file under “device” called “model”. For example, you might have an NVME “/sys/class/hwmon/hwmon3/device/model” and you might have an external NVME over USB or Thunderbolt that you don't want to monitor or you might have two NVME's.

index-list

A YAML list [ X1, X2, ... ] that specifies which sensors, resp. which fan to use from a given interface. Both /proc/acpi/ibm/thermal and also many hwmon interfaces contain multiple sensors, and not all of them may be relevant for fan control.

- For hwmon entries, this is required if hwmon-path does not refer directly to a single “tempXi_input” file, but to a folder that contains one or more of them. In this case, index-list specifies the Xi for the “tempXi_input” files that should be used. A hwmon interface may also contain multiple PWM controls for fans, so in that case, index-list must contain exactly one entry.

- For tpacpi sensors, this entry is optional. If it is omitted, all temperatures found in /proc/acpi/ibm/thermal will be used.

chip-name

The unique name of an lm-sensors hwmon chip. lm-sensors or libsensors is the official client library to access the sysfs hwmon subsystem, and as such it is the preferred way of specifying sensors. Available chips can be listed by running the sensors command as root. The header above each block will be the chip name.

ids

A list of lm-sensors feature IDs, for example “[ SYSTIN, CPUTIN, "Sensor 2" ]”. In the sensors command output, the name before the colon on each line will be the feature ID.

nvml-bus-id

NOTE: only available if thinkfan was compiled with USE_NVML enabled. The PCI bus ID of an nVidia graphics card that is run with the proprietary nVidia driver. Can be obtained with e.g. “lspci | grep -i vga”. Usually, nVidia cards will use the open source nouveau driver, which should support hwmon sensors instead.

disk-device-file

NOTE: only available if thinkfan was compiled with USE_ATASMART enabled. Full path to a device file for a hard disk that supports S.M.A.R.T. See also the -d option in thinkfan(1) that prevents thinkfan from waking up sleeping (mechanical) disks to read their temperature.

correction-list (optional, zeroes by default)

A YAML list that specifies temperature offsets for each sensor in use by the given driver. Use this if you want to use the “simple” level syntax, but need to compensate for devices with a lower heat tolerance. Note however that the detailed level syntax is usually the better (i.e. more fine-grained) choice.

bool-ignore-errors (optional, false by default)

A truth value (yes/no/true/false) that specifies whether thinkfan should ignore all errors when using a given sensor or fan. Normally, thinkfan will exit with an error message if it fails reading temperatures from a sensor or writing to a fan. An optional device will not delay startup. Instead, thinkfan will commence normal operation with the remaining devices and re-try initializing unavailable optional devices in every loop until all are found.

Marking a sensor/fan as optional may be useful for removable hardware or devices that may get switched off entirely to save power.

num-max-errors (optional, 0 by default)

A positive integer that specifies how often thinkfan is allowed to re-try if if fails to initialize, read from or write to a given sensor or fan. On startup, thinkfan will attempt to initialize the device num-max-errors times before commencing normal operation. If the device cannot be initialized after the given number of attempts, thinkfan will fail. When a device with a positive num-max-errors fails during runtime, thinkfan will likewise attempt to re-initialize it the given number of times before failing.

levels-section (optional, use global levels section by default)

As of thinkfan 2.0, multiple fans can be configured. To this end, each fan can now have its own levels: section (cf. FAN SPEEDS below). The syntax of the global vs. the fan-specific levels: section are identical, the only difference being that in a fan-specific one, the speed value(s) refer only the fans configured in that particular fans: entry. NOTE: Global and fan-specific levels: are mutually exclusive, i.e. there cannot be both a global one and fan-specific sections.

## FAN SPEEDS
The levels: section specifies a list of fan speeds with associated lower and upper temperature bounds. If temperature(s) drop below the lower bound, thinkfan switches to the previous level, and if the upper bound is reached, thinkfan switches to the next level.

Since thinkfan 2.0, this section can appear either under an individual fan (cf. levels: keyword under Fan Syntax), or globally.

### Simple Syntax
In the simplified form, only one temperature is specified as an upper/lower limit for a given fan speed. In that case, the lower-bound and upper-bound are compared only to the highest temperature found among all configured sensors. All other temperatures are ignored. This mode is suitable for small systems (like laptops) where there is only one device (e.g. the CPU) whose temperature needs to be controlled, or where the required fan behaviour is similar enough for all heat-generating devices.

```
# ...
levels:
  - [ fan-speed, lower-bound, upper-bound ]
  - ...
```

### Detailed Syntax
This mode is suitable for more complex systems, with devices that have different temperature ratings. For example, many modern CPUs and GPUs can deal with temperatures above 80°C on a daily basis, whereas a hard disk will die quickly if it reaches such temperatures. In detailed mode, upper and lower temperature limits are specified for each sensor individually:

```
# ...
levels:
  - speed: [ fan1-speed, fan2-speed, ... ]
    lower_limit: [ l1, l2, ... ]
    upper_limit: [ u1, u2, ... ]
  - ...
```

### Values
fan1-speed, fan2-speed, ...

fan-speed

When multiple fans are specified under the fans: section, value of the speed: keyword must be a list of as many fanX-speed values. They are applied to the fans by their order of appearance, i.e. the first speed value applies to the fan that has been specified first, the second value to the second fan, and so on. If there is just one fan, instead of a list with just one element, the speed value can be given as a scalar. The possible speed values for fanX-speed are different depending on which fan driver is used:

- For a hwmon fan, fanX-speed is a numeric value ranging from 0 to 255, corresponding to the PWM values accepted by the various kernel drivers.

- For a tpacpi fan on Lenovo/IBM ThinkPads and some other Lenovo laptops (see SENSORS & FAN DRIVERS above), numeric values and strings can be used. The numeric values range from 0 to 7. The string values take the form "level lvl-id", where lvl-id may be a value from 0 to 7, auto, full-speed or disengaged. The numeric values 0 to 7 correspond to the regular fan speeds used by the firmware, although many firmwares don't even use level 7. The value "level auto" gives control back to the firmware, which may be useful if the fan behavior only needs to be changed for certain specific temperature ranges (usually at the high and low end of the range). The values "level full-speed" and "level disengaged" take the fan speed control away from the firmware, causing the fan to slowly ramp up to an absolute maximum that can be achieved within electrical limits. Note that this will run the fan out of specification and cause increased wear, though it may be helpful to combat thermal throttling.

l1, l2, ...

u1, u2, ...

The lower and upper temperature limits refer to the sensors in the same order in which they were found when processing the sensors: section (see SENSOR & FAN DRIVERS above). For the first level entry, the lower_limit may be omitted, and for the last one, the upper_limit may be omitted. For all levels in between, the lower limits must overlap with the upper limits of the previous level, to make sure the entire temperature range is covered and that there is some hysteresis between speed levels. Instead of a temperature, an underscore (_) can be given. An underscore means that the temperature of that sensor should be ignored at the given speed level.

## SEE ALSO
The thinkfan manpage: thinkfan(1)

```
Example configs shipped with the source distribution, also available at:
https://github.com/vmatare/thinkfan/tree/master/examples
```

```
The Linux hwmon user interface documentation:
https://www.kernel.org/doc/html/latest/hwmon/sysfs-interface.html
```

```
The thinkpad_acpi interface documentation:
https://www.kernel.org/doc/html/latest/admin-guide/laptops/thinkpad-acpi.html
```

## BUGS

```
Report bugs on the github issue tracker:
https://github.com/vmatare/thinkfan/issues
```


thinkfan.conf.legacy

title: thinkfan.conf.legacy(5)

text:
# thinkfan.conf.legacy(5)

## NAME
thinkfan.conf.legacy - the old, backwards-compatible config syntax for thinkfan thinkfan(1)

## DESCRIPTION
The thinkfan config file specifies one or more temperature input(s), exactly one fan to control and the fan levels. A fan level associates a certain fan speed to a lower and an upper temperature bound. If the temperature reaches the upper bound, we switch to the next fan level, and if it drops below the lower bound, we switch to the previous fan level. Temperature bounds can either be a single temperature (simple mode) or consist of multiple temperatures (complex mode). In simple mode, only the highest of all known temperature is compared to the upper & lower bound. If you have devices with very different temperature ratings (e.g. CPU vs. mechanical hard drives), you should specify correction values to equalize their temperature ranges, or better: use complex mode. In complex mode, the upper and lower bounds of each fan level are specified for each sensor individually. Thinkfan then switches to the next fan level if one of the upper bounds is reached, and to the previous fan level if all temperatures have dropped below their respective lower bounds.

## THERMAL SENSORS
Multiple sensor keywords can be combined in one config file, but note that the ordering is significant with respect to the upper and lower fan level bounds if you use complex mode. I.e. if /proc/acpi/ibm/thermal contains 16 temperatures and you specify an hwmon sensor after the tp_thermal statement, the hwmon sensor will be the 17th temperature. After each sensor path, an optional correction-value can be specified. This value (can be negative) is always added to the temperature reading from that sensor. Correction values should be specified if you use Simple Mode with components that have a different temperature rating, like hard disks and CPUs. Note though that Complex Mode is generally the better solution since it gives you full control over fan levels and temperature ranges for each sensor, instead of just adding a fixed value to equalize temperature ranges.

tp_thermal /proc/acpi/ibm/thermal [ (correction-value ...) ]

Use the thermal sensors provided by the thinkpad_acpi kernel module on older thinkpads. These normally reside in /proc/acpi/ibm/thermal, so this keyword will hardly be used with other paths. This file usually contains 8-16 temperatures, some of which may be reserved for removable hardware or completely unused. Unused temperature slots always contain the value -128. Since this file contains all temperatures the thinkpad_acpi module knows about, there cannot be more than one tp_thermal statement in a config file.

hwmon sysfs-path [ (correction-value) ]

Use a standard hwmon temperature input that may be provided by all kinds of kernel drivers. sysfs-path is usually a file named ‘temp*_input’, somewhere under /sys, so you can search for them e.g. with ‘find /sys -type f -name "temp*_input"’. Each of these files contains one temperature, so you need to add a hwmon statement for each device whose temperature you wish to control.

atasmart device-path [ (correction-value) ]

NOTE: only available if thinkfan was compiled with USE_ATASMART enabled.

Read the temperature directly from a hard disk using S.M.A.R.T. See also the -d option in thinkfan(1) that prevents thinkfan from waking up sleeping (mechanical) disks to read their temperature.

nv_thermal pci-bus-id [ (correction-value) ]

NOTE: only available if thinkfan was compiled with USE_NVML enabled.

Read the temperature of an nVidia graphics card from the proprietary nVidia driver. This does not work with the open-source Nouveau driver, it depends specifially on libnvidia-ml.so that is usually installed with the binary nVidia driver. The correct pci-bus-id can be retrieved using e.g. lspci with: ‘lspci | grep -i vga’. Most open-source graphics drivers (radeon, nouveau, possibly others too) can instead be used with the hwmon keyword described above.

## FANS
Currently, thinkfan can control only one fan at a time. In theory, you can run multiple instances of the program simultaneously (with multiple config files) to control multiple fans, but that requires enabling DANGEROUS mode and will likely break most init scripts. It is an error to have more than one fan statement per config file.

tp_fan /proc/acpi/ibm/fan

Use the fan control provided by the thinkpad_acpi kernel module, which needs to be loaded with the option fan_control=1. The path is defined by the thinkpad_acpi kernel module and will hardly change. Besides the fan levels ranging from 0 to 7, it also supports the disengaged and auto modes.

The auto mode should delegate fan control to the firmware, so it can be regarded as a ‘default’ mode that does not change the fan behavior. This is useful for example if you only want to change the fan behavior at high and/or low temperatures.

The disengaged or full-speed mode effectively disables the fan RPM limiter. Fan speed will slowly ramp up until the fan uses the maximum electrical power available from the embedded controller. Use this only to prevent potentially destructive overheating, since it runs the fan outside of specifications and wears its bearings down quickly.

pwm_fan sysfs-path

Control a sysfs PWM fan. Many hwmon drivers that provide a ‘temp*_input’ file also allow fan control, although there may also be drivers that are specific to either temperature reading or fan control. You can search for a PWM control file e.g. with ‘find /sys -type f -name "pwm?"’. Note that with PWM, fan levels usually range from 0 to 255, although besides a file like pwm1 there may also be pwm1_min and pwm1_max that specify different (soft or recommended?) limits for a particular fan.

## FAN LEVELS
Defining the fan levels is the meat of the config file. Here you make use of your previously defined temperature inputs to set the lower and upper bounds for the fan speeds. You cannot mix simple fan levels with complex fan levels. The general syntax of a simple fan level is:

( fan-level [,] lower-bound [,] upper-bound )

The fan-level is either a numeric value (0-7 or 0-255, depending on whether a tp_fan or a pwm_fan is used) or a string enclosed in double quotes. When a tp_fan is used, specifying 0 has the same effect as specifying "level 0". In addition to the numeric fan levels, tp_fan also supports "level auto" and "level disengaged" or "level full-speed". See above for an explanation of what these mean. The format of lower-bound and upper-bound depends on whether you want to use Simple Mode or Complex Mode.

### Simple Mode
In simple mode, the lower-bound and upper-bound of a fan level are each specified as a single temperature value. Both are compared only to the highest temperature found in all of the configured thermal sensors. Using this mode of operation makes sense e.g. if all temperature readings come from the on-DIE thermal sensors of a multicore processor. The fan speed will affect all of these temperatures in the same way because they share a single thermal connection to the heatsink, so it makes sense to ignore all but the highest of these temperatures. As a rule of thumb, if your thermal sensors cover multiple devices you should use Complex Mode, or at least specify correction values to account for different temperature ratings.

### Complex Mode
In complex mode, both the lower-bound and upper-bound are lists of temperatures, the length of which must match the number of temperature readings thinkfan knows about. Each bound must be enclosed in braces, with individual values separated by commas or spaces, so the specific syntax of a complex mode fan level is:

```
{ fan-level
    ( lower-1 [lower-2 ...] )
    ( upper-1 [upper-2 ...] )
}
```

The optional commas have been omitted here for readability, and the curly braces are interchangeable with round braces. Note that it is not possible to mix simple fan levels with complex fan levels.

Complex mode is generally the preferred mode of operation since it allows you to specify precisely what the fan should to to keep each component within its specified temperature range.

## SEE ALSO
thinkfan(1)

Example configs shipped with the source distribution, also available at https://github.com/vmatare/thinkfan/tree/master/examples.