From 5f4ba065668089e7d5b158f60f26dd0be893ccf8 Mon Sep 17 00:00:00 2001
From: Isaac Freund <ifreund@ifreund.xyz>
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;
     }