How to use devices: better cross-referencing

A lot of options of ``qvm-device`` command have been converted to Sphinx
options directives and references.

The `action-1` role doesn't seem to be used and the duplicate title was
producing a warning.

The Qubes Device Widget tray icon is presented as a figure, to get a
more consitent paragraph.

SYNOPSIS have been changed to code blocks.

The Device Widget icon is updated (from
(qubes-desktop-linux-manager)[QubesOS/qubes-desktop-linux-manager/tree/release4.2/].
As the original PNG was deleted, all the ``how-to-use-*-devices`` have
been updated too.
QubesOS/qubes-issues#4692 is closed so the corresponding paragraph has
been removed.

attachment/doc/qubes-devices.svg

@@ -0,0 +1 @@
+<svg xmlns:xlink="http://www.w3.org/1999/xlink" width="26.136" xmlns="http://www.w3.org/2000/svg" height="27.392" id="screenshot-de3f5f2e-651c-801e-8003-497b6baebd5c" viewBox="-5.227 -1.305 26.136 27.392" style="-webkit-print-color-adjust: exact;" fill="none" version="1.1"><g id="shape-de3f5f2e-651c-801e-8003-497b6baebd5c" rx="0" ry="0"><g id="shape-de3f5f2e-651c-801e-8003-497abeb7e6e4"><g class="fills" id="fills-de3f5f2e-651c-801e-8003-497abeb7e6e4"><path d="M10.235777410044818,2.5312758605410863 h6.5 a1,1 0 0 1 1,1 v6 a0,0 0 0 1 0,0 h-8.5 a0,0 0 0 1 0,0 v-6 a1,1 0 0 1 1,-1 z" x="9.235777410044818" y="2.5312758605410863" transform="matrix(0.767072, 0.641561, -0.641561, 0.767072, 7.010645, -7.247096)" width="8.5" height="7" style="fill: rgb(155, 155, 155); fill-opacity: 1;"/></g></g><g id="shape-de3f5f2e-651c-801e-8003-497ad39f5ab2"><g class="fills" id="fills-de3f5f2e-651c-801e-8003-497ad39f5ab2"><rect rx="0" ry="0" x="14.469714467628762" y="5.386935461206235" transform="matrix(0.767072, 0.641561, -0.641561, 0.767072, 7.700937, -8.437069)" width="2" height="2" style="fill: rgb(235, 235, 235); fill-opacity: 1;"/></g></g><g id="shape-de3f5f2e-651c-801e-8003-497ad9b00fdb"><g class="fills" id="fills-de3f5f2e-651c-801e-8003-497ad9b00fdb"><rect rx="0" ry="0" x="11.78496225215207" y="3.141472136746529" transform="matrix(0.767072, 0.641561, -0.641561, 0.767072, 5.634982, -7.237668)" width="2.000000000000057" height="2.0000000000001137" style="fill: rgb(235, 235, 235); fill-opacity: 1;"/></g></g><g id="shape-de3f5f2e-651c-801e-8003-497aedbb68e1"><g class="fills" id="fills-de3f5f2e-651c-801e-8003-497aedbb68e1"><path d="M-1.725502478416331,7.459286392639228 h13.999999999999886 a0,0 0 0 1 0,0 v10 a6,6 0 0 1 -6,6 h-1.9999999999998863 a6,6 0 0 1 -6,-6 v-10 a0,0 0 0 1 0,0 z" x="-1.725502478416331" y="7.459286392639228" transform="matrix(0.767072, 0.641561, -0.641561, 0.767072, 11.146652, 0.216988)" width="13.999999999999886" height="16" style="fill: rgb(155, 155, 155); fill-opacity: 1;"/></g></g></g></svg>

developer/system/audio.rst

@@ -67,4 +67,4 @@ In Qubes R4.1 and later, ``pacat-simple-vchan`` is controlled over a UNIX socket
 
 These commands can be sent using the ``qubes.AudioInputEnable+VMNAME`` and ``qubes.AudioInputDisable+VMNAME`` qrexec services, respectively. The current status is written into QubesDB at ``/audio-input/VMNAME`` (where ``VMNAME`` is the VM’s name) with either ``1`` or ``0`` values. The lack of a key means that the ``pacat-simple-vchan`` for a given VM is not running.
 
-In either version, it is exposed to the user as device of class ``mic``, which can be attached to a VM (for example, using the ``qvm-device mic`` command).
+In either version, it is exposed to the user as device of class ``mic``, which can be attached to a VM (for example, using the :option:`qvm-device mic` command).

user/how-to-guides/how-to-use-block-storage-devices.rst

@@ -15,7 +15,13 @@ Using the Devices Widget to Attach a Drive
 
 Qubes OS supports the ability to attach a USB drive (or just its partitions) to any qube easily, no matter which qube handles the USB controller.
 
-Attaching USB drives is integrated into the Devices Widget: |device manager icon| Simply insert your USB drive and click on the widget. You will see multiple entries for your USB drive; typically, ``sys-usb:sda``, ``sys-usb:sda1``, and ``sys-usb:2-1`` for example. Entries starting with a number (e.g. here ``2-1``) are the :doc:`whole usb-device </user/how-to-guides/how-to-use-usb-devices>`. Entries without a number (e.g. here ``sda``) are the whole block-device. Other entries are partitions of that block-device (e.r. here ``sda1``).
+.. figure:: /attachment/doc/qubes-devices.svg
+   :alt:
+   :align: center
+
+   Qubes Devices Widget tray icon 
+
+Attaching USB drives is integrated into the Devices Widget. Simply insert your USB drive and click on the widget. You will see multiple entries for your USB drive; typically, ``sys-usb:sda``, ``sys-usb:sda1``, and ``sys-usb:2-1`` for example. Entries starting with a number (e.g. here ``2-1``) are the :doc:`whole usb-device </user/how-to-guides/how-to-use-usb-devices>`. Entries without a number (e.g. here ``sda``) are the whole block-device. Other entries are partitions of that block-device (e.r. here ``sda1``).
 
 The simplest option is to attach the entire block drive. In our example, this is ``sys-usb:sda``, so hover over it. This will pop up a submenu showing running VMs to which the USB drive can be connected. Click on one and your USB drive will be attached!
 
@@ -47,7 +53,7 @@ Command Line Tool Guide
 -----------------------
 
 
-The command-line tool you may use to mount whole USB drives or their partitions is ``qvm-block``, a shortcut for ``qvm-device block``.
+The command-line tool you may use to mount whole USB drives or their partitions is ``qvm-block``, a shortcut for :option:`qvm-device block`.
 
 ``qvm-block`` won’t recognise your device by any given name, but rather the device-node the sourceVM assigns. So make sure you have the drive available in the sourceVM, then list the available block devices (step 1.) to find the corresponding device-node.
 
@@ -182,7 +188,7 @@ To attach a file as block device to another qube, first turn it into a loopback
 
    `This command <https://linux.die.net/man/8/losetup>`__ will create the device node ``/dev/loop0`` or, if that is already in use, increase the trailing integer until that name is still available. Afterwards it prints the device-node-name it found.
 
-2. If you want to use the GUI, you’re done. Click the Device Manager |device manager icon| and select the ``loop0``-device to attach it to another qube.
+2. If you want to use the GUI, you’re done. Click the Device Widget and select the ``loop0``-device to attach it to another qube.
 
    - If you rather use the command line, continue:
 
@@ -278,5 +284,3 @@ usage example:
 
 
 This option accepts ``cdrom`` and ``disk``, default is ``disk``.
-
-.. |device manager icon| image:: /attachment/doc/media-removable.png

user/how-to-guides/how-to-use-devices.rst

@@ -2,7 +2,6 @@
 How to use devices
 ==================
 
-
 This is an overview of device handling in Qubes OS. For specific devices (:doc:`block </user/how-to-guides/how-to-use-block-storage-devices>`, :doc:`USB </user/how-to-guides/how-to-use-usb-devices>` and :doc:`PCI </user/how-to-guides/how-to-use-pci-devices>` devices), please visit their respective pages.
 
 **Important security warning:** Device handling comes with many security implications. Please make sure you carefully read and understand the :doc:`security considerations </user/security-in-qubes/device-handling-security>`.
@@ -10,160 +9,173 @@ This is an overview of device handling in Qubes OS. For specific devices (:doc:`
 Introduction
 ------------
 
-
 The interface to deal with devices of all sorts was unified in Qubes 4.0 with the ``qvm-device`` command and the Qubes Devices Widget. In Qubes 3.X, the Qubes VM Manager dealt with attachment as well. This functionality was moved to the Qubes Device Widget, the tool tray icon with a yellow square located in the top right of your screen by default.
 
 There are currently four categories of devices Qubes understands:
 
 - Microphones
-
 - Block devices
-
 - USB devices
-
 - PCI devices
 
-
-
 Microphones, block devices and USB devices can be attached with the GUI-tool. PCI devices can be attached using the Qube Settings, but require a VM reboot.
 
 General Qubes Device Widget Behavior And Handling
 -------------------------------------------------
 
+.. figure:: /attachment/doc/qubes-devices.svg
+   :alt:
+   :align: center
 
-When clicking on the tray icon (which looks similar to this): |SD card and thumbdrive| several device-classes separated by lines are displayed as tooltip. Block devices are displayed on top, microphones one below and USB-devices at the bottom.
+   Qubes Devices Widget tray icon 
+
+When clicking on the tray icon, several device-classes separated by lines are displayed as tooltip. Block devices are displayed on top, microphones one below and USB-devices at the bottom.
 
 On most laptops, integrated hardware such as cameras and fingerprint-readers are implemented as USB-devices and can be found here.
 
 Attaching Using The Widget
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-
 Click the tray icon. Hover on a device you want to attach to a VM. A list of running VMs (except dom0) appears. Click on one and your device will be attached!
 
 Detaching Using The Widget
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-
 To detach a device, click the Qubes Devices Widget icon again. Attached devices are displayed in bold. Hover the one you want to detach. A list of VMs appears, one showing the eject symbol: |eject icon|
 
 Attaching a Device to Several VMs
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-
+Only ``mic`` should be attached to more than one running VM. You may *assign* a device to more than one VM (using the :option:`--persistent <qvm-device attach --persistent>` option), however, only one of them can be started at the same time.
-Only ``mic`` should be attached to more than one running VM. You may *assign* a device to more than one VM (using the ``--persistent`` option), however, only one of them can be started at the same time.
-
-But be careful: There is a `bug in <https://github.com/QubesOS/qubes-issues/issues/4692>`__ ``qvm-device block`` or ``qvm-block`` which will allow you to *attach* a block device to two running VMs. Don’t do that!
 
 General ``qvm-device`` Command Line Tool Behavior
 -------------------------------------------------
 
-
+All devices, including PCI-devices, may be attached from the commandline using the ``qvm-device`` tools.
-All devices, including PCI-devices, may be attached from the commandline using the ``qvm-device``-tools.
 
 Device Classes
 ^^^^^^^^^^^^^^
 
+.. program:: qvm-device
 
-``qvm-device`` expects DEVICE_CLASS as first argument. DEVICE_CLASS can be one of
+``qvm-device`` expects :option:`DEVICE_CLASS` as first argument. 
 
-- ``pci``
+.. option:: DEVICE_CLASS
 
-- ``usb``
+   can be one of the following
 
-- ``block``
+.. option:: pci
-
+.. option:: usb
-- ``mic``
+.. option:: block
-
+.. option:: mic
-
-
-Actions
-^^^^^^^
 
+Actions overview
+^^^^^^^^^^^^^^^^
 
 ``qvm-device`` supports three actions:
 
-- ``list`` (ls, l) - list all devices of DEVICE_CLASS
+.. option:: list, ls, l
 
-- ``attach`` (at, a) - attach a specific device of DEVICE_CLASS
+   list all devices of :option:`DEVICE_CLASS`
 
-- ``detach`` (dt, d) - detach a specific device of DEVICE_CLASS
+.. option:: attach, at, a
 
+   attach a specific device of :option:`DEVICE_CLASS`
 
+.. option:: detach, dt, d
+
+   detach a specific device of :option:`DEVICE_CLASS`
 
 Global Options
 ^^^^^^^^^^^^^^
 
-
 These three options are always available:
 
-- ``--help``, ``-h`` - show help message and exit
+.. option:: --help, -h
 
-- ``--verbose``, ``-v`` - increase verbosity
+   show help message and exit
 
-- ``--quiet``, ``-q`` - decrease verbosity
+.. option:: --verbose, -v
+
+   increase verbosity
+
+.. option:: --quiet, -q
+
+   decrease verbosity
 
 
+A full command consists of one :option:`DEVICE_CLASS` and one action. If no action is given, list is implied. :option:`DEVICE_CLASS` however is required.
 
-A full command consists of one DEVICE_CLASS and one action. If no action is given, list is implied. DEVICE_CLASS however is required.
+**SYNOPSIS**::
 
-**SYNOPSIS**: ``qvm-device DEVICE_CLASS {action} [action-specific arguments] [options]``
+   qvm-device DEVICE_CLASS {action} [action-specific arguments] [options]
-
-.. _actions-1:
 
 
 Actions
 -------
 
-
+Actions are applicable to every :option:`DEVICE_CLASS` and expose some additional options.
-
-
-Actions are applicable to every DEVICE_CLASS and expose some additional options.
 
 Listing Devices
 ^^^^^^^^^^^^^^^
 
+The :option:`list` action lists known devices in the system. :option:`list` accepts VM-names to narrow down listed devices. Devices available in, as well as attached to the named VMs will be listed.
 
-The ``list`` action lists known devices in the system. ``list`` accepts VM-names to narrow down listed devices. Devices available in, as well as attached to the named VMs will be listed.
+:option:`qvm-device list` takes two options:
 
-``list`` accepts two options:
+.. program:: qvm-device list
 
-- ``--all`` - equivalent to specifying every VM name after ``list``. No VM-name implies ``--all``.
+.. option:: --all
 
-- ``--exclude`` - exclude VMs from ``--all``. Requires ``--all``.
+   equivalent to specifying every VM name after :option:`qvm-device list`. No VM-name implies :option:`--all`.
 
+.. option::  --exclude
+   
+   exclude VMs from :option:`--all`. Requires :option:`--all`.
 
+**SYNOPSIS**::
 
-**SYNOPSIS** ``qvm-device DEVICE_CLASS {list|ls|l} [--all [--exclude VM [VM [...]]] | VM [VM [...]]]``
+        qvm-device DEVICE_CLASS {list|ls|l} [--all [--exclude VM [VM [...]]] | VM [VM [...]]]
 
 Attaching Devices
 ^^^^^^^^^^^^^^^^^
 
+The :option:`qvm-device attach` action assigns an exposed device to a VM. This makes the device available in the VM it’s attached to. **Required argument are**:
 
-The ``attach`` action assigns an exposed device to a VM. This makes the device available in the VM it’s attached to. Required argument are targetVM and sourceVM:deviceID. (sourceVM:deviceID can be determined from ``list`` output)
+.. program:: qvm-device attach
 
-``attach`` accepts two options:
+.. option:: targetVM
 
-- ``--persistent`` - attach device on targetVM-boot. If the device is unavailable (physically missing or sourceVM not started), booting the targetVM fails.
+.. option:: sourceVM:deviceID
 
-- ``--option``, ``-o`` - set additional options specific to DEVICE_CLASS.
+   :option:`sourceVM:deviceID` can be determined from :option:`qvm-device list` output
+
+:option:`qvm-device attach` accepts two options:
+
+.. option:: --persistent 
+
+   attach device on :option:`targetVM`-boot. If the device is unavailable (physically missing or ``sourceVM`` not started), booting the :option:`targetVM` fails.
+
+.. option:: --option, -o
+
+   set additional options specific to :option:`DEVICE_CLASS <qvm-device DEVICE_CLASS>`.
 
 
+**SYNOPSIS**::
 
-**SYNOPSIS** ``qvm-device DEVICE_CLASS {attach|at|a} targetVM sourceVM:deviceID [options]``
+   qvm-device DEVICE_CLASS {attach|at|a} targetVM sourceVM:deviceID [options]
 
 Detaching Devices
 ^^^^^^^^^^^^^^^^^
 
+The :option:`qvm-device detach` action removes an assigned device from a :option:`targetVM`. It won’t be available afterwards anymore. Though it tries to do so gracefully, beware that data-connections might be broken unexpectedly, so close any transaction before detaching a device!
 
-The ``detach`` action removes an assigned device from a targetVM. It won’t be available afterwards anymore. Though it tries to do so gracefully, beware that data-connections might be broken unexpectedly, so close any transaction before detaching a device!
+If no specific :option:`sourceVM:deviceID` combination is given, *all devices of that* `DEVICE_CLASS <qvm-device DEVICE_CLASS>` will be detached.
 
-If no specific ``sourceVM:deviceID`` combination is given, *all devices of that DEVICE_CLASS will be detached.*
+:option:`qvm-device detach` accepts no options.
 
-``detach`` accepts no options.
+**SYNOPSIS**::
 
-**SYNOPSIS** ``qvm-device DEVICE_CLASS {detach|dt|d} targetVM [sourceVM:deviceID]``
+   qvm-device DEVICE_CLASS {detach|dt|d} targetVM [sourceVM:deviceID]
-
-.. |SD card and thumbdrive| image:: /attachment/doc/media-removable.png
 
 .. |eject icon| image:: /attachment/doc/media-eject.png

user/how-to-guides/how-to-use-pci-devices.rst

@@ -49,7 +49,7 @@ The qube settings for a VM offers the “Devices”-tab. There you can attach PC
 -----------------
 
 
-The ``qvm-pci`` tool allows PCI attachment and detachment. It’s a shortcut for :ref:`qvm-device pci <user/how-to-guides/how-to-use-devices:general qubes device widget behavior and handling>`
+The ``qvm-pci`` tool allows PCI attachment and detachment. It’s a shortcut for :option:`qvm-device pci`.
 
 To figure out what device to attach, first list the available PCI devices by running (as user) in dom0:
 

user/how-to-guides/how-to-use-usb-devices.rst

@@ -27,11 +27,16 @@ Attaching and detaching a USB device
 ------------------------------------
 
 
-With Qubes device manager
+With Qubes Device Widget
-^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^
 
+.. figure:: /attachment/doc/qubes-devices.svg
+   :alt:
+   :align: center
 
-Click the device-manager-icon: |device manager icon| A list of available devices appears. USB-devices have a USB-icon to their right: |usb icon|
+   Qubes Devices Widget tray icon 
+
+Click the Device Widget: a list of available devices appears. USB-devices have a USB-icon to their right: |usb icon|
 
 Hover on one device to display a list of qubes you may attach it to.
 
@@ -204,8 +209,6 @@ If, for example, you have 2 USB controllers in your system because you added one
 
 Now you should be able to tell which is the BDF address of the mainboard USB controller or the added USB controller.
 
-.. |device manager icon| image:: /attachment/doc/media-removable.png
-
 .. |usb icon| image:: /attachment/doc/generic-usb.png
 
 .. |eject icon| image:: /attachment/doc/media-eject.png