🔧 chore: add man pages
This commit is contained in:
@@ -0,0 +1,109 @@
|
||||
---
|
||||
title: WALLREEL
|
||||
section: 1
|
||||
header: User Commands
|
||||
footer: WallReel 2.0.0
|
||||
date: 2026-03-24
|
||||
---
|
||||
|
||||
# NAME
|
||||
|
||||
wallreel - Choose and set desktop wallpapers with customizable themes and actions
|
||||
|
||||
# SYNOPSIS
|
||||
|
||||
**wallreel** [*options*]
|
||||
|
||||
# DESCRIPTION
|
||||
|
||||
**wallreel** is a Qt6 application for browsing wallpaper images, previewing candidates,
|
||||
and applying a selected image.
|
||||
|
||||
Configuration is loaded from a JSON file. CLI options are available for logging,
|
||||
one-shot operations, and runtime overrides.
|
||||
|
||||
# OPTIONS
|
||||
|
||||
**-h, --help**
|
||||
: Display help for command-line options.
|
||||
|
||||
**-v, --version**
|
||||
: Display version information.
|
||||
|
||||
**-V, --verbose**
|
||||
: Set log level to DEBUG (default is INFO).
|
||||
|
||||
**-C, --clear-cache**
|
||||
: Clear image cache and exit.
|
||||
|
||||
**-q, --quiet**
|
||||
: Suppress log output.
|
||||
|
||||
**-d, --append-dir** _dir_
|
||||
: Append an additional wallpaper search directory.
|
||||
|
||||
This option can be provided multiple times.
|
||||
|
||||
**-c, --config-file** _file_
|
||||
: Use a custom configuration file.
|
||||
|
||||
**-D, --disable-actions**
|
||||
: Disable actions defined in the configuration file.
|
||||
|
||||
**-a, --apply** _file_
|
||||
: Apply the specified image as wallpaper and exit.
|
||||
|
||||
In this mode, the configuration is still parsed. Action placeholders are resolved
|
||||
from the selected image and any captured state values.
|
||||
|
||||
# BEHAVIOR NOTES
|
||||
|
||||
- CLI options are generally optional; configuration is the preferred customization path.
|
||||
- Some options are mutually exclusive (for example `--verbose` and `--quiet`).
|
||||
- With `--apply`, WallReel executes configured selection actions without opening the UI.
|
||||
|
||||
# FILES
|
||||
|
||||
`~/.config/wallreel/config.json`
|
||||
: Default configuration file location.
|
||||
|
||||
`~/.cache/wallreel/`
|
||||
: Runtime cache location.
|
||||
|
||||
# EXAMPLES
|
||||
|
||||
Run with default configuration:
|
||||
|
||||
```bash
|
||||
wallreel
|
||||
```
|
||||
|
||||
Use a custom configuration file:
|
||||
|
||||
```bash
|
||||
wallreel --config-file ~/.config/wallreel/config.json
|
||||
```
|
||||
|
||||
Append additional search directories:
|
||||
|
||||
```bash
|
||||
wallreel --append-dir ~/Pictures/Wallpapers --append-dir ~/Art
|
||||
```
|
||||
|
||||
Apply a wallpaper and exit:
|
||||
|
||||
```bash
|
||||
wallreel --apply ~/Pictures/wallpaper.jpg
|
||||
```
|
||||
|
||||
# EXIT STATUS
|
||||
|
||||
Returns `0` on success. Returns a non-zero value on failure.
|
||||
|
||||
# SEE ALSO
|
||||
|
||||
**wallreel**(5)
|
||||
|
||||
# AUTHOR
|
||||
|
||||
Uyanide <github.com/Uyanide>
|
||||
@@ -0,0 +1,233 @@
|
||||
---
|
||||
title: WALLREEL
|
||||
section: 5
|
||||
header: File Formats Manual
|
||||
footer: WallReel 2.0.0
|
||||
date: 2026-03-24
|
||||
---
|
||||
|
||||
# NAME
|
||||
|
||||
wallreel-config - configuration format for wallreel
|
||||
|
||||
# SYNOPSIS
|
||||
|
||||
`~/.config/wallreel/config.json`
|
||||
|
||||
# DESCRIPTION
|
||||
|
||||
WallReel reads configuration from a JSON document. The root object is divided into
|
||||
five sections:
|
||||
|
||||
- `wallpaper`
|
||||
- `theme`
|
||||
- `action`
|
||||
- `style`
|
||||
- `cache`
|
||||
|
||||
For complete machine-readable validation details, refer to `config.schema.json`.
|
||||
|
||||
# WALLPAPER SECTION
|
||||
|
||||
Defines where WallReel looks for images and what to exclude.
|
||||
|
||||
If both `paths` and `dirs` are empty or omitted, WallReel defaults to recursively
|
||||
scanning the user's Pictures directory and treating all supported image files as
|
||||
wallpaper candidates.
|
||||
|
||||
`paths` (array of string, default: `[]`)
|
||||
: Exact paths to specific image files.
|
||||
|
||||
`dirs` (array of object, default: `[]`)
|
||||
: Directories to scan for images.
|
||||
|
||||
Each item has:
|
||||
|
||||
- `path` (string)
|
||||
- `recursive` (boolean)
|
||||
|
||||
`excludes` (array of string, default: `[]`)
|
||||
: Exclude patterns as regular expressions.
|
||||
|
||||
# THEME SECTION
|
||||
|
||||
Configures color palettes.
|
||||
|
||||
A dominant color is extracted from each wallpaper. If a palette is selected,
|
||||
WallReel picks the closest palette color as the primary color.
|
||||
|
||||
`palettes` (array of object, default: `[]`)
|
||||
: Custom palette definitions.
|
||||
|
||||
Each palette has:
|
||||
|
||||
- `name` (string)
|
||||
- `colors` (array)
|
||||
|
||||
Each color item has:
|
||||
|
||||
- `name` (string)
|
||||
- `value` (hex string, for example `"#89b4fa"`)
|
||||
|
||||
# ACTION SECTION
|
||||
|
||||
Configures commands executed for preview, selection, and restore behavior.
|
||||
|
||||
`previewDebounceTime` (integer, default: `300`)
|
||||
: Debounce interval in milliseconds for preview actions.
|
||||
|
||||
`printSelected` (boolean, default: `true`)
|
||||
: Print selected wallpaper path to stdout on confirmation.
|
||||
|
||||
`printPreview` (boolean, default: `false`)
|
||||
: Print previewed wallpaper path to stdout on preview.
|
||||
|
||||
`onSelected` (string, default: `""`)
|
||||
: Command executed when a wallpaper is confirmed.
|
||||
|
||||
`onPreview` (string, default: `""`)
|
||||
: Command executed when a wallpaper is previewed.
|
||||
|
||||
`saveState` (array of object, default: `[]`)
|
||||
: Commands for capturing system values before changing wallpaper.
|
||||
|
||||
Each item has:
|
||||
|
||||
- `key` (placeholder key)
|
||||
- `fallback` (default value)
|
||||
- `command` (stdout-mapped command)
|
||||
- `timeout` (milliseconds)
|
||||
|
||||
`onRestore` (string, default: `""`)
|
||||
: Command executed on restore. Saved state keys are usable as placeholders.
|
||||
|
||||
`quitOnSelected` (boolean, default: `false`)
|
||||
: Exit application immediately after confirming a selection.
|
||||
|
||||
`restoreOnClose` (boolean, default: `true`)
|
||||
: Run `onRestore` when application closes without a final selection.
|
||||
|
||||
## ACTION PLACEHOLDERS
|
||||
|
||||
The following placeholders are available in `onSelected`, `onPreview`, and
|
||||
`onRestore` (where applicable):
|
||||
|
||||
`{{ path }}`
|
||||
: Full path of selected or previewed wallpaper.
|
||||
|
||||
`{{ name }}`
|
||||
: File name of selected or previewed wallpaper.
|
||||
|
||||
`{{ size }}`
|
||||
: Size in bytes of selected or previewed wallpaper.
|
||||
|
||||
`{{ palette }}`
|
||||
: Selected palette name (`"null"` if none).
|
||||
|
||||
`{{ colorName }}`
|
||||
: Chosen primary color name (`"null"` if none).
|
||||
|
||||
`{{ colorHex }}`
|
||||
: Chosen primary color hex (`"null"` if none).
|
||||
|
||||
`{{ domColorHex }}`
|
||||
: Dominant color hex extracted from the wallpaper.
|
||||
|
||||
`{{ <key> }}`
|
||||
: Value of a saved state item with matching key.
|
||||
|
||||
# STYLE SECTION
|
||||
|
||||
Controls window layout and thumbnail dimensions.
|
||||
|
||||
`image_width` (integer, default: `320`)
|
||||
: Width of each thumbnail.
|
||||
|
||||
`image_height` (integer, default: `180`)
|
||||
: Height of each thumbnail.
|
||||
|
||||
`image_focus_scale` (number, default: `1.5`)
|
||||
: Focus scale multiplier for highlighted thumbnail.
|
||||
|
||||
`window_width` (integer, default: `750`)
|
||||
: Initial window width.
|
||||
|
||||
`window_height` (integer, default: `500`)
|
||||
: Initial window height.
|
||||
|
||||
# CACHE SECTION
|
||||
|
||||
Controls persisted UI state.
|
||||
|
||||
`saveSortMethod` (boolean, default: `true`)
|
||||
: Persist sort method and direction.
|
||||
|
||||
`savePalette` (boolean, default: `true`)
|
||||
: Persist selected palette.
|
||||
|
||||
`maxImageEntries` (integer, default: `1000`)
|
||||
: Maximum number of image cache entries. Older entries are evicted.
|
||||
|
||||
# EXAMPLE
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "https://raw.githubusercontent.com/Uyanide/WallReel/refs/heads/master/config.schema.json",
|
||||
"wallpaper": {
|
||||
"paths": ["/home/user/Pictures/favorite.jpg"],
|
||||
"dirs": [
|
||||
{
|
||||
"path": "/home/user/Pictures/Wallpapers",
|
||||
"recursive": true
|
||||
}
|
||||
],
|
||||
"excludes": ["\\.gif$"]
|
||||
},
|
||||
"theme": {
|
||||
"palettes": [
|
||||
{
|
||||
"name": "Dark",
|
||||
"colors": [
|
||||
{ "name": "blue", "value": "#89b4fa" },
|
||||
{ "name": "red", "value": "#f38ba8" }
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
"action": {
|
||||
"previewDebounceTime": 500,
|
||||
"quitOnSelected": true,
|
||||
"onPreview": "swww img {{ path }}",
|
||||
"onSelected": "cp {{ path }} ~/.config/wallpaper/current/ && swww img {{ path }}",
|
||||
"saveState": [
|
||||
{
|
||||
"key": "current_wp",
|
||||
"fallback": "/home/user/Pictures/default.jpg",
|
||||
"command": "find ~/.config/wallpaper/current -type f | head -n 1",
|
||||
"timeout": 1000
|
||||
}
|
||||
],
|
||||
"onRestore": "swww img {{ current_wp }}"
|
||||
},
|
||||
"style": {
|
||||
"image_width": 640,
|
||||
"image_height": 400,
|
||||
"image_focus_scale": 1.2,
|
||||
"window_width": 1280,
|
||||
"window_height": 720
|
||||
},
|
||||
"cache": {
|
||||
"saveSortMethod": true,
|
||||
"savePalette": true,
|
||||
"maxImageEntries": 300
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
# SEE ALSO
|
||||
|
||||
**wallreel**(1)
|
||||
|
||||
# AUTHOR
|
||||
|
||||
Uyanide <github.com/Uyanide>
|
||||
Reference in New Issue
Block a user