From 59664d3b2154d1b8ded99550c19b999410f7cb63 Mon Sep 17 00:00:00 2001 From: Tassilo Horn Date: Sat, 9 Apr 2022 22:02:47 +0200 Subject: [PATCH] Write docs for swayrbar --- README.md | 149 +++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 137 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 6857ed0..f45eb89 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,14 @@ ## Table of Contents * [Swayr](#swayr) + * [Commands](#swayr-commands) + * [Screenshots](#swayr-screenshots) + * [Installation](#swayr-installation) + * [Usage](#swayr-usage) + * [Configuration](#swayr-configuration) + * [Version changes](#swayr-version-changes) * [Swayrbar](#swayrbar) + * [Configuration](#swayrbar-configuration) * [Questions and patches](#questions-and-patches) * [Bugs](#bugs) * [Build status](#build-status) @@ -22,7 +29,7 @@ window/workspace creations, deletions, and focus changes using sway's JSON IPC interface. The client `swayr` offers subcommands, see `swayr --help`, and sends them to the demon which executes them. -### Swayr commands +### Swayr commands The `swayr` binary provides many subcommands of different categories. @@ -163,7 +170,7 @@ These commands change the layout of the current workspace. one. (This is useful for accessing swayr commands which are not bound to a key.) -### Screenshots +### Screenshots ![A screenshot of swayr switch-window](misc/switch-window.png "swayr switch-window") @@ -172,7 +179,7 @@ switch-window") switch-workspace-or-window](misc/switch-workspace-or-window.png "swayr switch-workspace-or-window") -### Installation +### Installation Some distros have packaged swayr so that you can install it using your distro's package manager. Alternatively, it's easy to build and install it yourself @@ -210,7 +217,7 @@ cargo install-update --all cargo install-update -- swayr ``` -### Usage +### Usage You need to start the swayr demon `swayrd` in your sway config (`~/.config/sway/config`) like so: @@ -259,7 +266,7 @@ bindsym $mod+Shift+c exec env RUST_BACKTRACE=1 \ Of course, configure the keys to your liking. Again, enabling rust backtraces and logging are optional. -### Configuration +### Configuration Swayr can be configured using the `~/.config/swayr/config.toml` or `/etc/xdg/swayr/config.toml` config file. @@ -376,9 +383,10 @@ right now. * `fallback_icon` is a path to some PNG/SVG icon which will be used as `{app_icon}` if no application-specific icon can be determined. -All the placeholders except `{app_icon}`, `{indent}`, `{urgency_start}`, and -`{urgency_end}` may optionally provide a format string as specified by -[Rust's std::fmt](https://doc.rust-lang.org/std/fmt/). The syntax is +All the placeholders except `{app_icon}`, +`{indent}`, `{urgency_start}`, and `{urgency_end}` may optionally provide a +format string as specified by [Rust's +std::fmt](https://doc.rust-lang.org/std/fmt/). The syntax is `{:}`. For example, `{app_name:{:>10.10}}` would mean that the application name is printed with exactly 10 characters. If it's shorter, it will be right-aligned (the `>`) and padded with spaces, if @@ -442,7 +450,7 @@ over IPC. Therefore, auto-tiling is triggered by new-window events, close-events, move-events, floating-events, and also focus-events. The latter are a workaround and wouldn't be required if there were resize-events. -### Version Changes +### Version changes Since version 0.8.0, I've started writing a [NEWS](swayr/NEWS.md) file listing the news, and changes to `swayr` commands or configuration options. If something @@ -452,17 +460,134 @@ of your config. ## Swayrbar -TODO: Write docs! +`swayrbar` is a status command for sway's `swaybar` implementing the +[`swaybar-procotol(7)`](https://man.archlinux.org/man/swaybar-protocol.7). +This means, you would setup your `swaybar` like so in your +`~/.config/sway/config`: + +```conf +bar { + swaybar_command swaybar + # Use swayrbar as status command with some logging output which + # is redirected to /tmp/swayrbar.log. Be sure to only redirect + # stderr because the swaybar protocol requires the status_command + # to emit JSON to stdout which swaybar reads. + status_command env RUST_BACKTRACE=1 RUST_LOG=swayr=debug swayrbar 2> /tmp/swayrbar.log + position top + font pango:Iosevka 11 + height 20 + + colors { + statusline #f8c500 + background #33333390 + } +} +``` + +`swayrbar`, like [waybar](https://github.com/Alexays/Waybar/), consists of a +set of modules which you can enable and configure via its config file, either +system-wide (`/etc/xdg/swayrbar/config.toml`) or per user +(`~/.config/swayrbar/config.toml`). Modules emit information which `swaybar` +then displays and mouse clicks on a module's space in `swaybar` are propagated +back and trigger some action (e.g., a shell command). + +Right now, there are the following modules: + +1. The `window` module can show the title and application name of the current + window in sway. +2. The `sysinfo` module can show things like CPU/memory utilization or system + load. +3. The `battery` module can show the current [state of + charge](https://en.wikipedia.org/wiki/State_of_charge), the state (e.g., + charging), and the [state of + health](https://en.wikipedia.org/wiki/State_of_health). +4. The `date` module can show, you guess it, the current date and time! + +I guess there will be more modules in the future as time permits. I personally +would enjoy a `volume` module. [Patches](#questions-and-patches) are certainly +very welcome! + +### Configuration + +When `swayrbar` is run for the very first time and doesn't find an existing +configuration file at `~/.config/swayrbar/config.toml` (user-specific) or +`/etc/xdg/swayrbar/config.toml` (system-wide), it'll create a new user-specific +one where all modules are enabled and set up with some reasonable (according to +the author) default values. Adapt it to your needs. + +The syntax of the config file is [TOML](https://toml.io/en/). Here's a short +example with all top-level options (one!) and one module. + +```toml +refresh_interval = 1000 + +[[modules]] +name = 'window' +instance = '0' +format = '🪟 {title} — {app_name}' +html_escape = false + +[modules.on_click] +Left = ['swayr', 'switch-to-urgent-or-lru-window'] +Right = ['kill', '{pid}'] +``` + +The `refresh_interval` defines the number of milliseconds between refreshes of +`swaybar`. + +The remainder of the configuration defines a list of modules with their +configuration (which is an [array of +tables](https://toml.io/en/v1.0.0#array-of-tables) in TOML where a module's +`on_click`). + +* `name` is the name or type of the module, e.g., `window`, `sysinfo`, + `battery`, `date`,... +* `instance` is an arbitrary string used for distinguishing two modules of the + same `name`. For example, you might want to have two `sysinfo` modules, one + for CPU and one for memory utilization, simply to have a separator between + these different kinds of information. That's easily doable, just give them + different `instance` values. +* `format` is the string to be printed in `swaybar` where certain placeholders + are substituted with module-specific values. Usually, such placeholders are + written like `{title}`, i.e., inside braces. Like in `swayr`, formatting is + available, see [here](#fmt-placeholders). +* `html_escape` defines if `<` and `>` should be escaped as `<` and `>` + because `format` may contain [pango + markup](https://docs.gtk.org/Pango/pango_markup.html). Obviously, if you + make use of this feature, you want to set `html_escape = true` for that + module. This option is optional and may be omitted. +* `on_click` is a table defining actions to be performed when you click on a + module's space in `swaybar`. All placeholders available in `format` are + available here, too. The action for each mouse button is specified as an + array `['command', 'arg1', 'arg2',...]`. The available button names to be + assigned to are `Left`, `Middle`, `Right`, `WheelUp`, `WheelDown`, + `WheelLeft`, and `WheelRight`. + +The `on_click` table can also be written as: + +```toml +on_click = { + Left = ['swayr', 'switch-to-urgent-or-lru-window'] + Right = ['kill', '{pid}'] +} +``` + +I think this version is more readable but the version shown in the beginning of +this section is what the [toml crate](https://crates.io/crates/toml) exports. + ## Questions & Patches For asking questions, sending feedback, or patches, refer to [my public inbox (mailinglist)](https://lists.sr.ht/~tsdh/public-inbox). Please mention the -project you are referring to in the subject. +project you are referring to in the subject, e.g., `swayr` or `swayrbar` (or +other projects in different repositories). ## Bugs -Bugs and requests can be reported [here](https://todo.sr.ht/~tsdh/swayr). +It compiles, therefore there are no bugs. Oh well, if you still found one or +want to request a feature, you can do so +[here](https://todo.sr.ht/~tsdh/swayr). ## Build status