From c7cf542dedc102bd9cbef08f8bdb8732734f16de Mon Sep 17 00:00:00 2001
From: Frank Richter <frank.richter@gmail.com>
Date: Sun, 11 Aug 2024 16:04:10 +0200
Subject: [PATCH] Add documentation on display selection

---
 README.md | 26 ++++++++++++++++++++++++--
 1 file changed, 24 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index b24f584..2e08d03 100644
--- a/README.md
+++ b/README.md
@@ -25,12 +25,14 @@ Syntax:
 ## `on` command
 Turns HDR on on all supported displays.
 
-Does not accept any options.
+The affected displays are determined by the configuration made with the [`select` command](#select-command) or,
+if given, a list of displays specified with the `-d` argument ([see "Display arguments"](#display-arguments)).
 
 ## `off` command
 Turns HDR off on all supported displays.
 
-Does not accept any options.
+The affected displays are determined by the configuration made with the [`select` command](#select-command) or,
+if given, a list of displays specified with the `-d` argument ([see "Display arguments"](#display-arguments)).
 
 ## `status` command
 Prints the current HDR status to the console. Has a special mode that returns an exit code depending on the status.
@@ -42,6 +44,18 @@ Specifies how the status should be reported. Accepts the following values:
 * `long`, `l`: Print the overall HDR status and status per display.
 * `exitcode`, `x`: Special mode for scripting. Exit code is 0 if HDR is on, 1 if HDR is off, and 2 if HDR is unsupported. (Other values indicate some error.)
 
+## `select` command
+This command selects the displays that are affected by HDRCmd commands or HDRTry actions.
+
+### `list` subcommand
+Prints a list of all displays, their current HDR status, and whether they're currently selected.
+
+### `on` subcommand
+Includes displays specified by the arguments ([see "Display arguments"](#display-arguments)) when enabling or disabling HDR.
+
+### `off` subcommand
+Excludes displays specified by the arguments ([see "Display arguments"](#display-arguments)) when enabling or disabling HDR.
+
 ## `startup` command
 Prints or changes the 'Start when logging in' option for the notification area icon to the console.
 
@@ -54,6 +68,14 @@ Turn the 'Start when logging in' option on. HDRTray will be automatically starte
 ### `off` subcommand
 Turn the 'Start when logging in' option off. HDRTray will no longer be automatically started upon login. Prints new status to the console.
 
+## Display arguments
+Some commands require, or can optionally accept, a set of displays.
+
+Displays can be specified in the following ways:
+
+* Display number. This is simply the value in the `Display #` column when displaying the long HDR status or using `select list`. _Note: The display number is not persistent and may change if displays are connected, disconnected, or even on HDR mode changes. This makes the display number somewhat unsuitable for scripting._
+* Display name or part of name. A display is used if either the full display name (the value in the `Name` column when displaying the long HDR status or using `select list`) is a case-insensitive match, or the given string is part of the display name (again, case-insensitively). Any match must be unambiguous (ie only a single display matches).
+
 Latest Release
 --------------
 The latest release can be found on the [“Releases” tab of the GitHub project page](https://github.com/res2k/HDRTray/releases).