From 5f4ba065668089e7d5b158f60f26dd0be893ccf8 Mon Sep 17 00:00:00 2001 From: Isaac Freund Date: Wed, 30 Dec 2020 14:25:37 +0100 Subject: [PATCH] docs: improve explanation of tags "tagmask" is a misleading term as the arguments are used much more like a set of tags than a mask. --- contrib/config.sh | 16 ++++++++-------- doc/riverctl.1.scd | 37 +++++++++++++++++++++++-------------- river/command/tags.zig | 2 +- 3 files changed, 32 insertions(+), 23 deletions(-) diff --git a/contrib/config.sh b/contrib/config.sh index 5169409..969ceb6 100755 --- a/contrib/config.sh +++ b/contrib/config.sh @@ -68,26 +68,26 @@ riverctl map-pointer normal $mod BTN_RIGHT resize-view for i in $(seq 1 9) do - tagmask=$((1 << ($i - 1))) + tags=$((1 << ($i - 1))) # Mod+[1-9] to focus tag [0-8] - riverctl map normal $mod $i set-focused-tags $tagmask + riverctl map normal $mod $i set-focused-tags $tags # Mod+Shift+[1-9] to tag focused view with tag [0-8] - riverctl map normal $mod+Shift $i set-view-tags $tagmask + riverctl map normal $mod+Shift $i set-view-tags $tags # Mod+Ctrl+[1-9] to toggle focus of tag [0-8] - riverctl map normal $mod+Control $i toggle-focused-tags $tagmask + riverctl map normal $mod+Control $i toggle-focused-tags $tags # Mod+Shift+Ctrl+[1-9] to toggle tag [0-8] of focused view - riverctl map normal $mod+Shift+Control $i toggle-view-tags $tagmask + riverctl map normal $mod+Shift+Control $i toggle-view-tags $tags done # Mod+0 to focus all tags # Mod+Shift+0 to tag focused view with all tags -all_tags_mask=$(((1 << 32) - 1)) -riverctl map normal $mod 0 set-focused-tags $all_tags_mask -riverctl map normal $mod+Shift 0 set-view-tags $all_tags_mask +all_tags=$(((1 << 32) - 1)) +riverctl map normal $mod 0 set-focused-tags $all_tags +riverctl map normal $mod+Shift 0 set-view-tags $all_tags # Mod+Space to toggle float riverctl map normal $mod Space toggle-float diff --git a/doc/riverctl.1.scd b/doc/riverctl.1.scd index 4d87300..6994fcd 100644 --- a/doc/riverctl.1.scd +++ b/doc/riverctl.1.scd @@ -92,25 +92,34 @@ control and configure river. Bump the focused view to the top of the layout stack to make it the new master. -## ACTIONS ON TAGS +## TAG MANAGEMENT -Tags are like workspaces but more flexible: You can assign views to multiple -tags and look at multiple tags at once. A _tagmask_ is used to represent which -tags are visible. The following commands take a _tagmask_ in base 10 as -argument but _tagmasks_ are best understood in binary: 000000001 means that the -first tag is visible; 111111111 means that tag 1 through 9 are visible. +Tags are similar to workspaces but more flexible. You can assign views multiple +tags and focus multiple tags simultaneously. Bitfields are used to describe +sets of tags when interfacing with river. As such, the following commands +take a normal base 10 number as their argument but the semantics are best +understood in binary. The binary number 000000001 represents a set containing +only tag 1 while 100001101 represents a set containing tags 1, 3, 4, and 9. -*set-focused-tags* _tagmask_ - Show the tags specified with _tagmask_. +At least one tag must always be focused and each view must be assigned at +least one tag. Operations that would violate either of these requirements +are ignored by river. -*set-view-tags* _tagmask_ - Assign focused view to tags specified with _tagmask_. +*set-focused-tags* _tags_ + Show views with tags corresponding to the set bits of _tags_ on the + currently focused output. -*toggle-focused-tags* _tagmask_ - Toggle visibility of tags specified with _tagmask_. +*set-view-tags* _tags_ + Assign the currently focused view the tags corresponding to the set + bits of _tags_. -*toggle-view-tags* _tagmask_ - Toggle tags of focused view as specified with _tagmask_. +*toggle-focused-tags* _tags_ + Toggle visibility of views with tags corresponding to the set bits + of _tags_ on the currently focused output. + +*toggle-view-tags* _tags_ + Toggle the tags of the currently focused view corresponding to the + set bits of _tags_. ## CONFIGURATION COMMANDS diff --git a/river/command/tags.zig b/river/command/tags.zig index 2ede528..fa89626 100644 --- a/river/command/tags.zig +++ b/river/command/tags.zig @@ -100,7 +100,7 @@ fn parseTags( const tags = try std.fmt.parseInt(u32, args[1], 10); if (tags == 0) { - out.* = try std.fmt.allocPrint(allocator, "tagmask may not be 0", .{}); + out.* = try std.fmt.allocPrint(allocator, "tags may not be 0", .{}); return Error.Other; }