olog/symconf
1
0
Fork 0
Code Issues 1 Pull Requests Packages Projects Releases 1 Wiki Activity

add minor details to usage docs

Browse Source
This commit is contained in:
smgr
2025-09-28 03:43:59 -07:00
parent 4d707b97e4
commit 13e366d1fe
8 changed files with 535 additions and 331 deletions
Download Patch File Download Diff File Expand all files Collapse all files

169
docs/reference/configuring.md
View File

@@ -1,61 +1,64 @@
# 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` 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.
`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/`
- 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.)
`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:
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:
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.
- `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.
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:
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>
@@ -66,30 +69,31 @@ terminal emulator. The following tree demonstrates a valid setup:
└── 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
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`.
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.
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,
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>
@@ -99,22 +103,22 @@ or palettes (matching them in the same way as config files). For example,
└── 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:
`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.
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:
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>]
@@ -128,22 +132,22 @@ config_map = {
}
```
(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:
(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`:
- `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]
@@ -152,8 +156,9 @@ following options:
}
```
This tells `symconf` to symlink the exact location `~/.config/kitty/kitty.conf` to
the matching `kitty.conf` under the `apps/kitty` directory.
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: