---

2 Loading Initialization Files and Search Paths ¶

Warning: The texi2any-config.pm file related paths and even the use of texi2any-config.pm files is not definitive.

You can write so-called initialization files, or init files for short, to modify almost every aspect of output formatting. The program loads init files named texi2any-config.pm each time it is run. The directories lookup is based on the XDG Base Directory Specification with defaults based on installation directories. The texi2any-config.pm files are looked for in the following directories:

datadir/texi2any/

(where datadir is the system data directory specified at compile-time, e.g., /usr/local/share)

XDG_CONFIG_DIRS/texi2any

(for each directory in the : delimited XDG_CONFIG_DIRS environment variable, in reverse order)

sysconfdir/xdg/texi2any/

(where sysconfdir is specified at compile time, e.g., /usr/local/etc)

~/.config/texi2any/

(where ~ is the current user’s home directory, only if XDG_CONFIG_HOME is not set)

XDG_CONFIG_HOME/texi2any

(with XDG_CONFIG_HOME an environment variable)

./.texi2any/

(under the current directory)

./

(the current directory)

All texi2any-config.pm files found are loaded, in the above order. Thus, ./texi2any-config.pm can override entries in, say, datadir/texi2any/texi2any-config.pm.

However, the most common way to load an initialization file path is with the --init-file option, explicitly specifying the file path to be loaded. If the initialization file path contains directories, it is loaded if found. Otherwise, if the file path is a simple file name, the following directories are searched, in the following order by default. Only the first file found is used:

1. The current directory ./;
2. ./.texi2any/ under the current directory;
3. XDG_CONFIG_HOME/texi2any if the XDG_CONFIG_HOME environment is set, otherwise ~/.config/texi2any/ where ~ is the current user’s home directory;
4. sysconfdir/xdg/texi2any/ where sysconfdir is the system configuration directory specified at compile-time, e.g., /usr/local/etc;
5. if the environment variable XDG_CONFIG_DIRS is set, directory/texi2any for each directory in the : delimited XDG_CONFIG_DIRS environment variable value;
6. datadir/texi2any/ Where datadir is the system data directory specified at compile time, e.g., /usr/local/share;
7. ./.texinfo/init/ under the current directory;
8. XDG_CONFIG_HOME/texinfo/init if the XDG_CONFIG_HOME environment is set, otherwise ~/.config/texinfo/init/ where ~ is the current user’s home directory;
9. sysconfdir/xdg/texinfo/init/ with sysconfdir as above;
10. if the environment variable XDG_CONFIG_DIRS is set, directory/texinfo/init for each directory in the : delimited XDG_CONFIG_DIRS environment variable value;
11. datadir/texinfo/init/ with datadir as above.
12. datadir/texinfo/ext/ with datadir as above.

The datadir/texinfo/ext/ directory contains the init files directly loaded from texi2any code. When loaded from texi2any code directly, init files are only searched for in that directory, being considered as part of the program and not as user customization. Since the directory is also in the list of directories searched for init files loaded by the --init-file option, those init files can also be loaded as regular user specified init files.

Additional directories may be prepended to the list with the --conf-dir option (see Invoking texi2any in Texinfo).