docs: align man pages with code + fill documentation gaps (0.16.0 audit)

A full man<->code consistency audit surfaced options, format placeholders
and CSS classes that were implemented but undocumented, documented but not
implemented (some causing fmt crashes when copied from examples), and
defaults that disagreed with the code. This aligns the docs with the code
and fixes a few genuine code gaps.

Docs:
- Add the missing waybar-user(5) man page (and register it in meson.build)
- Document previously-undocumented options/placeholders/CSS across many
  modules (custom image-path/image-name/icon-size, graph_type/width/
  datapoints; battery smooth-power; wireplumber format-source/only-physical;
  mpris {position}/prefer-album-artist; network {signalStrengthApp}/compact
  bandwidth; pulseaudio {source_volume}/{source_desc}; upower {temperature}/
  {model}/{native-path}; wwan {power_state}/{imei}; tray ignore-list; and
  many CSS state classes: .sink-muted, .source-muted, .workspace-hover, etc.)
- Correct documented defaults to match the code (hyprland format {name},
  gamemode {count}, cpu-graph interval 5, cava input_delay 4, niri taskbar
  icon-size 16, disk/gps/wayfire formats, menu-actions object type, ...)
- Remove placeholders/options that do not apply (custom-graph {icon}/format/
  format-icons/rotate) and fix crashing examples (wwan {mode}, gps
  format-no-fix); note cava background/foreground/continuous_rendering are
  cava-config-file options

Code:
- bluetooth: accept the documented `controller` key as a synonym of
  `controller-alias` (the option was silently ignored)
- mango/workspaces: supply the documented `{name}` fmt arg (was missing ->
  fmt::format threw)
- privacy: read `tooltip` as a bool (was guarded on isString(), so the
  documented `tooltip: false` was silently ignored)

All man pages validated with scdoc 1.11.4. Not compiled locally (no gtkmm);
C++ build relies on CI.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Alex
2026-07-04 02:39:38 +02:00
co-authored by Claude Opus 4.8
parent 14cb78b835
commit 72fdf77c19
49 changed files with 445 additions and 88 deletions
+94
View File
@@ -0,0 +1,94 @@
waybar-user(5) "waybar-user" "User Manual"
# NAME
waybar - user module
# DESCRIPTION
The *user* module displays the currently logged in user, the system uptime and,
optionally, the user's avatar image.
# CONFIGURATION
Addressed by *user*
[- *Option*
:- *Typeof*
:- *Default*
:- *Description*
|[ *interval*
:[ integer
:[ 60
:[ The interval in which the information gets polled
|[ *format*
:[ string
:[ *{user} {work_H}:{work_M}*
:[ The format, how the information should be displayed. See *FORMAT REPLACEMENTS* below
|[ *icon*
:[ bool
:[ false
:[ When enabled, displays the user's avatar image next to the label
|[ *avatar*
:[ string
:[ *$HOME/.face*
:[ Path to the avatar image to display. Only used when *icon* is enabled. When unset, the default path *$HOME/.face* is used
|[ *height*
:[ integer
:[ 20
:[ The height of the avatar image in pixels
|[ *width*
:[ integer
:[ 20
:[ The width of the avatar image in pixels
|[ *open-on-click*
:[ bool
:[ false
:[ When enabled, left-clicking the module opens the user's home directory (or *open-path*) with the default file manager
|[ *open-path*
:[ string
:[
:[ Overrides the path that is opened when *open-on-click* is enabled. When empty, the user's home directory is used
|[ *rotate*
:[ integer
:[
:[ Positive value to rotate the text label (in 90 degree increments)
|[ *tooltip*
:[ bool
:[ true
:[ Option to enable tooltip on hover
# FORMAT REPLACEMENTS
- *{user}*: The login name of the currently logged in user, in uppercase
- *{work_d}*: Whole days the system has been up
- *{work_H}*: Hours part of the system uptime (00-23)
- *{work_M}*: Minutes part of the system uptime (00-59)
- *{work_S}*: Seconds part of the system uptime (00-59)
- *{up_H}*: Hour the system was booted (00-23)
- *{up_M}*: Minute the system was booted (00-59)
- *{up_d}*: Day of the month the system was booted (01-31)
- *{up_m}*: Month the system was booted (01-12)
- *{up_Y}*: Year the system was booted
# EXAMPLES
```
"user": {
"format": "{user} up {work_H}:{work_M}:{work_S}",
"interval": 60,
"icon": true,
"avatar": "/home/alice/.face",
"height": 24,
"width": 24,
"open-on-click": true
}
```
# STYLE
- *#user*
# AUTHOR
Alexis Rouillard <contact@arouillard.fr>