# Local Customization

BRLTTY supports the XDG configuration file paradigm. The most important capability this offers is an easy way to customize your BRLTTY configuration that won't be overwritten during an upgrade, reinstall, etc. The XDG paradigm defines standard locations for your own data files that will override BRLTTY's provided data files. In other words, you no longer need to modify BRLTTY's provided data files in order to make your own local customizations.

The following data files are covered by this feature:

- The configuration file (`brltty.conf`).
- Text tables (`*.ttb`) and subtables (`*.tti`). See Text Tables for details.
- Attributes tables (`*.atb`) and subtables (`*.ati`). See Attributes Tables for details.
- Contraction tables (`*.ctb`) and subtables (`*.cti`). See Contraction Tables for details.
- Key tables (`*.ktb`) and subtables (`*.kti`). See Key Tables for details.

The standard directory where you should put your customized files is `/etc/xdg/brltty/`.

The simplest way to customize a provided data file is to copy it to this directory, and then to modify your copy as needed. You can, however, just place your changes in your version of the file, and then `include` the provided file in order to automatically always pick up the latest versions of all the unchanged lines.

For example: Let's say that you'd like to add your own key bindings to the `laptop` keyboard table. To do so, create `/etc/xdg/brltty/laptop.ktb`, and place lines like these into it:

    bind Key1 COMMAND1
    bind Key2 COMMAND2
    ...
    include laptop.ktb

The `XDG_CONFIG_HOME` environment variable defines the base directory in which to check before the standard directory is checked. If it's set and not empty then the primary override directory is `$XDG_CONFIG_HOME/brltty/`. If it either isn't set or is empty, but the `HOME` environment variable is set and not empty (the usual case when you're logged in) then the primary override directory is `$HOME/.config/brltty/`. If both the `XDG_CONFIG_HOME` and `HOME` environment variables are either not set or empty (the usual case during the system boot sequence) then the primary override directory isn't defined.

The `XDG_CONFIG_DIRS` environment variable defines a colon-separated list of secondary base directories. The `brltty/` subdirectory of each of these secondary base directories is BRLTTY's corresponding secondary override directory. So, for example, if `XDG_CONFIG_DIRS` is set to `/a:/b` then BRLTTY will check `/a/brltty/` and `/b/brltty/` (in that order). If `XDG_CONFIG_DIRS` is set and not empty then `/etc/xdg/brltty/` is no longer implicitly checked.

For backward compatibility, the original data file override paradigm is also supported. If the `HOME` environment variable is set and not empty then the tertiary override directory is `$HOME/.brltty/`. If it isn't set, or if it's empty, then the tertiary override directory is `./.brltty/`.