[Spice-devel] [PATCH spice-space-pages 4/5] multiple-monitors: Expand fullscreen configuration

[Jonathon Jongsma]

Move to a separate section and expand the documentation of the
configuration options a bit.
---
 multiple-monitors.rst | 54 ++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 45 insertions(+), 9 deletions(-)

diff --git a/multiple-monitors.rst b/multiple-monitors.rst
index 91352ad..18ffe0c 100644
--- a/multiple-monitors.rst
+++ b/multiple-monitors.rst
@@ -216,15 +216,51 @@ same arrangement as the client monitors. For example, if the client has
 four monitors arranged in a 2x2 grid, the guest displays will also be
 configured to a 2x2 grid instead of a horizontal array of 4 monitors.
 
-One additional feature of fullscreen mode is the ability to use a configuration
-file to fine-tune this behavior. If you have multiple client monitors, but you
-want to run virt-viewer in fullscreen mode on only a subset of those monitors,
-you can do so with the `monitor-mapping` configuration option to specify which
-monitors to use. This option is an array of mappings between guest displays and
-client monitors. For example, if you have 3 monitors and want to run
-virt-viewer in fullscreen mode on the last two, you can use
-`monitor-mapping=1:2;2:3`. That will place guest display 1 on client monitor 2,
-and guest display 2 on client monitor 3.
+Per-client configuration
+************************
+One additional feature of virt-viewer is the ability to use a configuration
+file to fine-tune the fullscreen behavior. If your client machine has multiple
+monitors, but you want to run virt-viewer in fullscreen mode on only a subset
+of those monitors, you can specify which monitors to use. Perhaps you want to
+retain one client monitor to use for local applications, but want to display
+the remote guest on the second and third monitors. To do so, you can edit the
+virt-viewer configuration file (located at `~/.config/virt-viewer/settings` on
+linux). This behavior is controlled by the `monitor-mapping` configuration
+option. `monitor-mapping` is a semi-colon separated array of mappings from
+guest display IDs to client monitor IDs. 
+For example, the following configuration will
+apply to every guest that you connect to. It will place the first guest display
+on the second client monitor and will place the second guest display on the
+third client monitor:
+
+::
+
+    monitor-mapping=1:2;2:3
+
+If you want the same configuration applied to every remote guest, the
+`monitor-mapping` option should be placed within the `[fallback]` group (create
+the group if it doesn't already exist).
+
+::
+
+    [fallback]
+    monitor-mapping=1:2;2:3
+
+If you want the configuration to apply to only a single guest, then create a
+group named according to the UUID of the appropriate guest and place the
+configuration option within that group. For example:
+
+::
+
+    [139eb0bb-9cfd-4783-85ed-a70bbd362c2d]
+    monitor-mapping=1:2;2:3
+
+This configuration option only affects fullscreen mode, and there are some
+limitations. For example, guest displays should be specified in order without
+any gaps. For example, you should not try to enable only guest display 2. If
+the second display is enabled, the first should also be enabled.  Also note
+that since this configuration is specified in the client's settings file, it
+will only apply to that particular client machine.
 
 Additional Notes
 ++++++++++++++++
-- 
2.9.3