symconf/docs/reference/configuring.md

# Configuring
`symconf` operates on a central directory that houses all of the config files you may wish
to apply. The default location for this directory is your `$XDG_CONFIG_HOME` (e.g.,
`~/.config/symconf/`), but it can be any location on your system so long as it's specified
(see more in Usage). 

`symconf` expects you to create two top-level components in your config directory: an
`apps/` directory and an `app_registry.toml` file.

**High-level view**:

- `symconf` operates on a single directory that houses all your config files
- Config files in this directory must be placed under an `apps/<app-name>/` folder to be
  associated with the app `<app-name>`
- For apps to be visible, you need an `app_registry.toml` file that tells `symconf` where
  to symlink your files in `apps/`

## Apps directory
An `apps/` directory should be created in your config home, with a subdirectory
`apps/<app-name>/` for each app with config files that you'd like to be visible to
`symconf`. Note that simply populating an app's config folder here will do nothing on its
own; the app must also have been registered (discussed in item #2) in order for these
files to be used when `symconf` is invoked. (This just means you can populate your `apps/`
folder safely without expecting any default behavior. More often than not you'll be
expected to tell `symconf` exactly where your config files should end up, meaning you know
exactly what it's doing.)

### User config 
Inside your app-specific subdirectory, your managed config files should be placed in a
`user/` subdirectory (distinguishing them from those generated by templates; see more
in Themes). Your config files themselves are then expected to follow a specific naming
scheme:

```sh
<palette>-<scheme>.<config-name>
```

This ties your config file to a particular theme setting as needed, and `symconf` will
apply it if it matches the theme setting you provide when invoked. The specific values are
as follows:

- `scheme`: can be `light`, `dark`, or `none`. Indicates whether the config file should
  be applied specifically when requesting a light or dark mode. Use `none` to indicate
  that the config file does not have settings specific to a light/dark mode.
- `palette`: a "palette name" of your choosing, or `none`. The palette name you use
  here may refer specifically to a color palette used by the config file, but can be
  used generally to indicate any particular group of config settings (e.g., fonts,
  transparency, etc). Use `none` to indicate that the file does not correspond to any
  particular style group.
- `config-name`: the _name_ of the config file. This should correspond to _same path
  name_ that is expected by the app being configured. For example, if your app expects a
  config file at `a/b/c/d.conf`, "`d.conf`" is the path name.

When invoking `symconf` with specific scheme and palette settings (see more in Usage),
appropriate config files can be matched based on how you've named your files.

For example, suppose I want to set up a simple light/dark mode switch for the `kitty`
terminal emulator. The following tree demonstrates a valid setup:

```sh
<config-home>
└── apps/
    └── kitty/
        └── user/
            ├── none-light.kitty.conf
            └── none-dark.kitty.conf
```

where `none-light.kitty.conf` may set a light background and `none-dark.kitty.conf` a dark
one. `none` is used for the `<palette>` part of the name to indicate the configuration does
not pertain to any specific palette and can be matched even if one is not provided. With
an appropriate `app_regsitry.toml` file (see below), invoking 

```sh
symconf --theme=light --apps=kitty
```

would symlink `$XDG_CONFIG_HOME/symconf/apps/kitty/user/none-light.kitty.conf` to
`~/.config/kitty/kitty.conf`.

### Templatized config
Note the potential inconvenience in needing to manage two separate config files in the
above example, very likely with all but one line of difference. Templating enables
populating config template files dynamically with theme-specific variables of your
choosing.


### Reload scripts
After symlinking a new set of config files, it is often necessary to reload the system or
relevant apps in order for the new config settings to apply. Within an app's subdirectory,
a `call/` folder can be created to hold scripts that should apply based on certain schemes
or palettes (matching them in the same way as config files). For example,

```sh
<config-home>
└── apps/
    └── kitty/
        └── call/
            └── none-none.sh
```

`none-none.sh` might simply contain `kill -s USR1 $(pgrep kitty)`, which is a way to tell
all running `kitty` instances to reload their config settings. Again, following the naming
scheme for config files, a script named `none-none.sh` will apply under any scheme or
palette specification. Thus, in our light/dark mode switch example, invoking `symconf
--theme=light --apps=kitty` would:

1. Search and match the config name `none-light.kitty.conf` and symlink it to
   `~/.config/kitty/kitty.conf`.
2. Search and match `none-none.sh` and execute it, applying the new light mode settings to
   all running `kitty` instances.


## App registry
An `app_registry.toml` file, used to specify the target locations for app-specific
config files. To "register" an app, you simply need to add the following text block to
the `app_registry.toml` file:

```toml
[app.<app-name>]
# DEFINE *ONE* OF THE FOLLOWING
config_dir = "<path-to-app-config-folder>"
# OR 
config_map = {
    "<conf-pathname-1>" = "<path-to-exact-config-file>"
    "<conf-pathname-2>" = "<path-to-exact-config-file>"
    # ...
}
```

(Note that text in angle brackets refers to values that should be replaced.) This tells
`symconf` how it should handle each app's config files. The `<app-name>` (e.g.,
`kitty`) should correspond to a subdirectory under `apps/` (e.g., `apps/kitty/`) that
holds your config files for that app. As shown, you then need to supply either of the
following options:

- `config_dir`: specifies a single directory where all of the app's matching config
  files should be symlinked. In the `kitty` example, this might be `~/.config/kitty`.
  This is the simplest and most common option provided most apps expect all of their
  config files to be in a single directory.
- `config_map`: a dictionary mapping config file _path names_ to the _exact paths_ that
  should be created during the symlink process. This is typically needed when an app
  has many config files that need to be set in several disparate locations across your
  system. In the `kitty` example, although not necessary (and in general you should
  prefer to set `config_dir` when applicable), we could have the following
  `config_map`:

  ```toml
  [app.kitty]
  config_map = {
      "kitty.conf": "~/.config/kitty/kitty.conf"
  }
  ```

  This tells `symconf` to symlink the exact location `~/.config/kitty/kitty.conf` to
  the matching `kitty.conf` under the `apps/kitty` directory.

## Directory structure
In total, the structure of your base config directory can look as follows:

```sh
~/.config/symconf/
├── app_registry.toml
└── apps/
    └── <app>/
        ├── user/                      # user managed
        │   └── none-none.<config-name>
        ├── generated/                 # automatically populated
        │   └── none-none.<config-name>
        ├── templates/                 # config templates
        │   └── none-none.template
        └── call/                      # reload scripts
            └── none-none.sh
```

## Misc remarks

### Multiple config files with same path name