[virt-tools-list] [PATCH virt-viewer 1/2] Add documentation for fullscreen monitor mapping

[Jonathon Jongsma]

see https://bugzilla.redhat.com/show_bug.cgi?id=1142769
---
 man/remote-viewer.pod | 43 ++++++++++++++++++++++++++++++++++++-------
 man/virt-viewer.pod   | 34 ++++++++++++++++++++++++++++++++++
 2 files changed, 70 insertions(+), 7 deletions(-)

diff --git a/man/remote-viewer.pod b/man/remote-viewer.pod
index 2c84432..1683e44 100644
--- a/man/remote-viewer.pod
+++ b/man/remote-viewer.pod
@@ -15,8 +15,8 @@ protocols are SPICE and VNC.
 Starting remote-viewer without URI will open a simple dialog with an
 entry and a list of previously successfully accessed URI.
 
-The URI can also point to a connection settings file, see FILE section
-for a description of the format.
+The URI can also point to a connection settings file, see the CONNECTION FILE
+section for a description of the format.
 
 =head1 OPTIONS
 
@@ -44,10 +44,12 @@ Zoom level of the display window in percentage. Range 10-400.
 
 Start with the windows maximized to fullscreen.
 
-If supported, the remote display will be reconfigured to match at best the
-client physical monitor configuration on initialization, by enabling or
-disabling extra monitors as necessary. This is currently implemented by the
-Spice backend only.
+If supported, the remote display will be reconfigured to match the physical
+client monitor configuration, by enabling or disabling extra monitors as
+necessary. This is currently implemented by the Spice backend only.
+
+To specify which client monitors are used in fullscreen mode, see the
+CONFIGURATION section below.
 
 =item -t TITLE, --title TITLE
 
@@ -113,7 +115,7 @@ the associated action.
 It must be composed of modifiers (shift, ctrl or alt) and a
 non-modifier key. For example, "shift+f11".
 
-=head1 FILE
+=head1 CONNECTION FILE
 
 B<remote-viewer> connection file is of INI file format, with a
 mandatory [virt-viewer] group and "type" key.
@@ -267,6 +269,33 @@ port 8080, use the value "http://foobar:8080".
 
 =back
 
+=head1 CONFIGURATION
+
+A small number of configuration options can be controlled by editing the
+settings file located in the user configuration directory:
+
+    <USER-CONFIG-DIR>/virt-viewer/settings
+
+This file is a text file in INI format, with application options in the
+[virt-viewer] group and per-guest options in a group identified by the guest's
+UUID. The application options should not be edited manually. There is also a
+special [fallback] group which specifies options for all guests that don't have
+an explicit group.
+
+For each guest, the initial fullscreen monitor configuration can be specified
+by using the B<monitor-mapping> key. This configuration only takes effect when
+the -f/--full-screen option is specified.
+
+The value of this key is a list of mappings between a guest display and a
+client monitor. Each mapping is separated by a semicolon character, and the
+mappings have the format <GUEST-DISPLAY-ID>:<CLIENT-MONITOR-ID>.
+
+For example, to map guest displays 1 and 2 to client monitors 2 and 3 for the
+guest with a UUID of e4591275-d9d3-4a44-a18b-ef2fbc8ac3e2, use:
+
+    [e4591275-d9d3-4a44-a18b-ef2fbc8ac3e2]
+    monitor-mapping=1:2;2:3
+
 =head1 EXAMPLES
 
 To connect to SPICE server on host "makai" with port 5900
diff --git a/man/virt-viewer.pod b/man/virt-viewer.pod
index ac9b268..e976c69 100644
--- a/man/virt-viewer.pod
+++ b/man/virt-viewer.pod
@@ -71,6 +71,13 @@ socket connection.
 
 Start with the window maximised to fullscreen
 
+If supported, the remote display will be reconfigured to match the physical
+client monitor configuration, by enabling or disabling extra monitors as
+necessary. This is currently implemented by the Spice backend only.
+
+To specify which client monitors are used in fullscreen mode, see the
+CONFIGURATION section below.
+
 =item --debug
 
 Print debugging information
@@ -117,6 +124,33 @@ option, and will attempt to do a reconnection before it quits.
 
 =back
 
+=head1 CONFIGURATION
+
+A small number of configuration options can be controlled by editing the
+settings file located in the user configuration directory:
+
+    <USER-CONFIG-DIR>/virt-viewer/settings
+
+This file is a text file in INI format, with application options in the
+[virt-viewer] group and per-guest options in a group identified by the guest's
+UUID. The application options should not be edited manually. There is also a
+special [fallback] group which specifies options for all guests that don't have
+an explicit group.
+
+For each guest, the initial fullscreen monitor configuration can be specified
+by using the B<monitor-mapping> key. This configuration only takes effect when
+the -f/--full-screen option is specified.
+
+The value of this key is a list of mappings between a guest display and a
+client monitor. Each mapping is separated by a semicolon character, and the
+mappings have the format <GUEST-DISPLAY-ID>:<CLIENT-MONITOR-ID>.
+
+For example, to map guest displays 1 and 2 to client monitors 2 and 3 for the
+guest with a UUID of e4591275-d9d3-4a44-a18b-ef2fbc8ac3e2, use:
+
+    [e4591275-d9d3-4a44-a18b-ef2fbc8ac3e2]
+    monitor-mapping=1:2;2:3
+
 =head1 EXAMPLES
 
 To connect to the guest called 'demo' running under Xen
-- 
1.9.3