From 8dcae9333362c76efea16e344fa7009976a31826 Mon Sep 17 00:00:00 2001
From: Danilo Spinella <danilo.spinella@suse.com>
Date: Wed, 17 Apr 2024 09:40:48 +0200
Subject: [PATCH] Update wpaperd-output man page

---
 man/wpaperd-output.5.scd | 73 +++++++++++++++++++++++++++++-----------
 1 file changed, 53 insertions(+), 20 deletions(-)

diff --git a/man/wpaperd-output.5.scd b/man/wpaperd-output.5.scd
index fb3c5b9..0823b7e 100644
--- a/man/wpaperd-output.5.scd
+++ b/man/wpaperd-output.5.scd
@@ -2,55 +2,88 @@ wpaperd-output(5)
 
 # NAME
 
-wpaperd-output - format used by wpaperd to define the various outputs
+wpaperd-output - format used by wpaperd to define the various displays
 
 # DESCRIPTION
 
-The wpaperd output format contains the information about each input and the corresponding wallpaper.
-This data is stored in XDG_CONFIG_HOME/wpaperd/output.conf (which defaults to
-$HOME/.config/wpaperd/output.conf).
+The wpaperd configuration file contains the information about each display, the corresponding
+wallpaper and its settings. This file is located in XDG_CONFIG_HOME/wpaperd/config.toml
+(which defaults to $HOME/.config/wpaperd/config.toml).
 
 # SYNTAX
 
-This file is a simple TOML configuration divided in sections, one for each output (or screen).
+This file is a simple TOML configuration divided in sections, one for each display.
 
 ## SECTION
 
-Each section is named after the output identifier. If you are using _sway_, you can lookup
+Each section is named after the display identifier. If you are using _sway_, you can lookup
 the output identifier by calling:
 
 ```
 $ swaymsg -t get_outputs
 ```
 
-The valid keys for the section are the following:
+On Hyprland, you can do it with:
 
-- *path*, path to the image/directory
-- *duration*, how much time the image should be displayed until it is changed with a new one.
+```
+$ hyprctl monitors
+```
+
+The configuration file for *wpaperd* is located in `XDG_CONFIG_HOME/wpaperd/config.toml`
+(which defaults to `~/.config/wpaperd/config.toml`). Each section
+represents a different display and can contain the following keys:
+
+- `path`, path to the image to use as wallpaper or to a directory to pick the wallpaper from
+- `duration`, how much time the image should be displayed until it is changed with a new one.
+  It supports a human format for declaring the duration (e.g. `30s` or `10m`), described
+  [here](https://docs.rs/humantime/latest/humantime/fn.parse_duration.html).
   This is only valid when path points to a directory. (_Optional_)
-- *sorting*, choose the sorting order. Valid options are `ascending`, `descending`, and `random`,
-  with the unspecified or default being `random` (_Optional_)
+- `sorting`, choose the sorting order. Valid options are `ascending`, `descending`, and `random`,
+  with the default being `random`. This is only valid when path points to a directory. (_Optional_)
+- `mode`, choose how to display the wallpaper when the size is different than the display
+  resolution:
+  - `fit` shows the entire image with black corners covering the empty space left
+  - `center` centers the image on the screen, leaving out the corners of the image that couldn't fit
+  - `stretch` shows the entire image stretching it to fit the entire screen without leaving any
+    black corner, changing the aspect ratio
+  - `tile` shows the image multiple times horizontally and vertically to fill the screen
+- `transition_time`, how many milliseconds should the transition run. (_Optional_, `300` by default).
+- `queue_size`, decide how big the queue should be when `path` is set a directory and `sorting` is
+   set to `random`. (_Optional_, `10` by default)
 
 ## DEFAULT SECTION
 
-A special section is the one called "*Default*", that will be used as fallback for all the
-outputs not listed in this configuration file.
+The section "*default*" will be used as base for the all the display configuration; the section
+"*any*" will be used for all the displays that are not explictly listed. This allows to have a
+flexible configuration without repeating any settings. _wpaperd_ will check the configuration at
+startup and each time it changes and provide help when it is incorrect.
 
 # EXAMPLE
 
+The simplest configuration looks like this:
+
+```
+[DP-3]
+path = "/home/danyspin97/github_octupus.png"
+
+[DP-4]
+path = "/home/danyspin97/Wallpapers"
+duration = "30m"
+```
+
+A more complex configuration is also possible:
+
 ```
 [default]
-path = "/home/danyspin97/Pictures/Wallpapers/"
 duration = "30m"
+mode = "center"
 sorting = "ascending"
 
-[eDP-1]
-path = "/home/danyspin97/Pictures/Wallpapers/github_octupus.png"
-apply-shadow = true
+[any]
+path = "/home/danyspin97/default_wallpaper.png"
 
-[DP-2]
-path = "/home/danyspin97/Pictures/Landscapes/"
-sorting = "descending"
+[DP-3]
+path = "/home/danyspin97/Wallpapers"
 ```
 
 # AUTHOR