From 99eed5c01c1a5c5d41bd46e9599e00016f783965 Mon Sep 17 00:00:00 2001
From: James Reed <jcrd@tuta.io>
Date: Tue, 24 Nov 2020 16:12:09 -0700
Subject: [PATCH] Clarify conceptual usage

---
 README.md | 41 ++++++++++++++++++++++++++++++++++++-----
 init.lua  |  6 +++---
 2 files changed, 39 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index f80ea52..d0a8ab1 100644
--- a/README.md
+++ b/README.md
@@ -11,6 +11,37 @@ $ cd awesome-viewport
 $ luarocks make --local rockspec/awesome-viewport-devel-1.rockspec
 ```
 
+## Concept
+
+Once connected to a screen, selecting a single tag will make that tag the active
+viewport. This tag will remember any other selected tags when the viewport
+changes, so that when it is re-selected, all previously selected tags are
+viewed.
+
+For example:
+
+![Tag 1 is selected, becoming the active viewport][1]
+
+* Tag 1 is selected, becoming the active viewport.
+
+![Tag 2 is toggled into view][2]
+
+* Tag 2 is toggled into view. Tag 1, as the active viewport, will record this.
+
+![Tag 2 is selected, but tag 1 is not viewed][3]
+
+* If tag 2 is selected, it becomes the new active viewport, and tag 1 will not be
+  viewed. The association is one way.
+
+![Tag 1 is selected, toggling tag 2 into view][2]
+
+* Tag 1 is re-selected, becoming the active viewport. Because tag 2 was viewed
+  when tag 1 was previously the active viewport, it is toggled back into view.
+
+[1]: https://github.com/jcrd/awesome-viewport/blob/assets/1.png
+[2]: https://github.com/jcrd/awesome-viewport/blob/assets/2.png
+[3]: https://github.com/jcrd/awesome-viewport/blob/assets/3.png
+
 ## Usage
 
 Require the library:
@@ -30,9 +61,9 @@ View a single tag:
 tag1:view_only()
 ```
 
-This tag will be the new viewport.
+This tag will be the active viewport.
 
-Get the viewport for the focused screen:
+Get the active viewport for the focused screen:
 
 ```lua
 viewport()
@@ -43,9 +74,9 @@ Toggle another tag into view:
 awful.tag.viewtoggle(tag2)
 ```
 
-`tag1` will remember that `tag2` is toggled while its the viewport, so that if
-the viewport changes and `tag1` is re-viewed, `tag2` will also be toggled into
-view.
+`tag1` will remember that `tag2` is toggled while its the active viewport, so
+that if the viewport changes and `tag1` is re-viewed, `tag2` will also be
+toggled into view.
 
 See the [API documentation](https://jcrd.github.io/awesome-viewport/) for
 descriptions of all functions.
diff --git a/init.lua b/init.lua
index 03e38eb..44467f5 100644
--- a/init.lua
+++ b/init.lua
@@ -3,12 +3,12 @@
 --- Manage tags based on viewports.
 --
 -- Once connected to a screen via `viewport.connect(screen)`, selecting a single
--- tag will make that tag the new viewport. This tag will remember any other
+-- tag will make that tag the active viewport. This tag will remember any other
 -- selected tags when the viewport changes, so that when it is re-selected,
 -- all previously selected tags are viewed.
 --
 -- @author James Reed &lt;jcrd@tuta.io&gt;
--- @copyright 2019 James Reed
+-- @copyright 2019-2020 James Reed
 -- @module awesome-viewport
 
 local awful = require("awful")
@@ -32,7 +32,7 @@ local function update(s)
     end
 end
 
---- Get the viewport of a given screen.
+--- Get the active viewport of a given screen.
 --
 -- @param s The screen, defaults to `awful.screen.focused().selected_tag`.
 -- @return The viewport tag.