From 35c49cba4081578ae20a7036ab3a71dab3e9eaa8 Mon Sep 17 00:00:00 2001 From: Tassilo Horn Date: Sat, 9 Apr 2022 10:39:28 +0200 Subject: [PATCH] Improve README.md --- README.md | 113 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 78 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 593112f..6857ed0 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Swayr is a window switcher (and more) for sway +# Swayr & Swayrbar [![builds.sr.ht status](https://builds.sr.ht/~tsdh/swayr.svg)](https://builds.sr.ht/~tsdh/swayr?) [![latest release](https://img.shields.io/crates/v/swayr.svg)](https://crates.io/crates/swayr) @@ -6,12 +6,31 @@ [![dependency status](https://deps.rs/repo/sourcehut/~tsdh/swayr/status.svg)](https://deps.rs/repo/sourcehut/~tsdh/swayr) [![Hits-of-Code](https://hitsofcode.com/sourcehut/~tsdh/swayr?branch=main)](https://hitsofcode.com/sourcehut/~tsdh/swayr/view?branch=main) +## Table of Contents + +* [Swayr](#swayr) +* [Swayrbar](#swayrbar) +* [Questions and patches](#questions-and-patches) +* [Bugs](#bugs) +* [Build status](#build-status) +* [License](#license) + +## Swayr, a window-switcher & more for [sway](https://swaywm.org/) + Swayr consists of a demon, and a client. The demon `swayrd` records 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. -Right now, there are these subcommands: +### Swayr commands + +The `swayr` binary provides many subcommands of different categories. + +#### Non-menu switchers + +Those are just commands that toggle between windows without spawning the menu +program. + * `switch-to-urgent-or-lru-window` switches to the next window with urgency hint (if any) or to the last recently used window. * `switch-to-app-or-urgent-or-lru-window` switches to a specific window matched @@ -25,6 +44,12 @@ Right now, there are these subcommands: a "browser" mark to your browser window (using a standard sway `for_window` rule). Then you can provide "browser" as argument to this command to have a convenient browser <-> last-recently-used window toggle. + +#### Menu switchers + +Those spawn a menu program where you can select a window (or workspace, or +output, etc.) and act on that. + * `switch-window` displays all windows in the order urgent first, then last-recently-used, focused last and focuses the selected. * `switch-workspace` displays all workspaces in LRU order and switches to the @@ -55,6 +80,29 @@ Right now, there are these subcommands: like with `move-focused-to-workspace`. * `swap-focused-with` swaps the currently focused window or container with the one selected from the menu program. + +##### Menu shortcuts for non-matching input + +All menu switching commands (`switch-window`, `switch-workspace`, and +`switch-workspace-or-window`) now handle non-matching input instead of doing +nothing. The input should start with any number of `#` (in order to be able to +force a non-match), a shortcut followed by a colon, and some string as required +by the shortcut. The following shortcuts are supported. +- `w:`: Switches to a possibly non-existing workspace. + `` must be a digit, a name or `:`. The + `:` format is explained in `man 5 sway`. If that format is + given, `swayr` will create the workspace using `workspace number + :`. If just a digit or name is given, the `number` argument is + not used. +- `s:`: Executes the sway command `` using `swaymsg`. +- Any other input is assumed to be a workspace name and thus handled as + `w:` would do. + + +#### Cycling commands + +Those commands cycle through (a subset of windows) in last-recently-used order. + * `next-window (all-workspaces|current-workspace)` & `prev-window (all-workspaces|current-workspace)` focus the next/previous window in depth-first iteration order of the tree. The argument `all-workspaces` or @@ -74,6 +122,11 @@ Right now, there are these subcommands: stacked container, it is like `next-tiled-window` / `prev-tiled-window` if the current windows is in a tiled container, and is like `next-window` / `prev-window` otherwise. + +#### Layout modification commands + +These commands change the layout of the current workspace. + * `tile-workspace exclude-floating|include-floating` tiles all windows on the current workspace (excluding or including floating ones). That's done by moving all windows away to some special workspace, setting the current @@ -97,6 +150,9 @@ Right now, there are these subcommands: between a tabbed and tiled layout, i.e., it calls `shuffle-tile-workspace` if it is currently tabbed, and calls `shuffle-tile-workspace` if it is currently tiled. + +#### Miscellaneous commands + * `configure-outputs` lets you repeatedly issue output configuration commands until you abort the menu program. * `execute-swaymsg-command` displays most swaymsg which don't require @@ -107,24 +163,7 @@ Right now, there are these subcommands: one. (This is useful for accessing swayr commands which are not bound to a key.) -### Menu shortcuts for non-matching input - -All menu switching commands (`switch-window`, `switch-workspace`, and -`switch-workspace-or-window`) now handle non-matching input instead of doing -nothing. The input should start with any number of `#` (in order to be able to -force a non-match), a shortcut followed by a colon, and some string as required -by the shortcut. The following shortcuts are supported. -- `w:`: Switches to a possibly non-existing workspace. - `` must be a digit, a name or `:`. The - `:` format is explained in `man 5 sway`. If that format is - given, `swayr` will create the workspace using `workspace number - :`. If just a digit or name is given, the `number` argument is - not used. -- `s:`: Executes the sway command `` using `swaymsg`. -- Any other input is assumed to be a workspace name and thus handled as - `w:` would do. - -## Screenshots +### Screenshots ![A screenshot of swayr switch-window](misc/switch-window.png "swayr switch-window") @@ -133,13 +172,13 @@ 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 using `cargo`. -### Distro packages +#### Distro packages The following GNU/Linux and BSD distros package swayr. Thanks a lot to the respective package maintainers! Refer to the [repology @@ -148,7 +187,7 @@ site](https://repology.org/project/swayr/versions) for details. [![Packaging status](https://repology.org/badge/vertical-allrepos/swayr.svg)](https://repology.org/project/swayr/versions) [![AUR swayr-git package status](https://repology.org/badge/version-for-repo/aur/swayr.svg?allow_ignored=yes&header=AUR%20swayr-git)](https://repology.org/project/swayr/versions) -### Building with cargo +#### Building with cargo You'll need to install the current stable rust toolchain using the one-liner shown at the [official rust installation @@ -171,7 +210,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: @@ -220,7 +259,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. @@ -288,14 +327,14 @@ auto_tile_min_window_width_per_output_width = [ In the following, all sections are explained. -### The menu section +#### The menu section In the `[menu]` section, you can specify the menu program using the `executable` name or full path and the `args` (flags and options) it should get passed. If some argument contains the placeholder `{prompt}`, it is replaced with a prompt such as "Switch to window" depending on context. -### The format section +#### The format section In the `[format]` section, format strings are specified defining how selection choices are to be layed out. `wofi` supports [pango @@ -370,7 +409,7 @@ processed whereas for double-quoted strings (so-called basic strings) escape-sequences are processed. `rofi` requires a null character and a PARAGRAPH SEPARATOR for image sequences. -### The layout section +#### The layout section In the `[layout]` section, you can enable auto-tiling by setting `auto_tile` to `true` (the default is `false`). The option @@ -403,29 +442,33 @@ 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](NEWS.md) file listing the +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 doesn't seem to work as expected after an update, please consult this file to check if there has been some (possibly incompatible) change requiring an update of your config. -## Questions & Patches +## Swayrbar + +TODO: Write docs! + +## 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. -## Bugs +## Bugs Bugs and requests can be reported [here](https://todo.sr.ht/~tsdh/swayr). -## Build status +## Build status [![builds.sr.ht status](https://builds.sr.ht/~tsdh/swayr.svg)](https://builds.sr.ht/~tsdh/swayr?) -## License +## License -Swayr is licensed under the +Swayr & Swarybar are licensed under the [GPLv3](https://www.gnu.org/licenses/gpl-3.0.en.html) (or later).