docs: update device directory documentation

docs/devices.md

@@ -12,46 +12,30 @@ Solaar supports some Lightspeed receivers.
 See the receiver table below for the list of currently supported receivers.
 
 Solaar supports most recent and many older Logitech devices
-(keyboards, mice, trackballs, and touchpads)
+(keyboards, mice, trackballs, touchpads, and headsets)
 that can connect to supported receivers.
 Solaar supports many recent Logitech devices that can connect via a USB cable,
 but some such Logitech devices are not suited for use in Solaar because they do not use the HID++ protocol.
 One example is the MX518 Gaming Mouse.
 Solaar supports most recent Logitech devices that can connect via Bluetooth.
 
-The device tables below provide a list of some of the devices that Solaar supports,
-giving their product name, WPID product number, and HID++ protocol information..
-The tables concentrate on older devices that have explicit support information in Solaar.
-
 The best way to determine whether Solaar supports a device is to run Solaar while the device is connected.
 If the device is supported, it will show up in the Solaar main window.
 If it is not, and there is no issue about the device in the Solaar GitHub repository,
 open an enhancement issue requesting that it be supported.
 
-## Adding new receivers and devices
+The directory https://github.com/pwr-Solaar/Solaar/tree/master/docs/devices contains
+
+
+## Adding new receivers
 
 Adding a new receiver requires knowing whether the receiver is a regular
-Unifying receiver, a Nano receiver, a Bolt receiver, or a Lightspeed receiver. Add a line to
+Unifying receiver, a Nano receiver, a Bolt receiver, or a Lightspeed receiver.
-`../lib/logitech_receiver/base_usb.py` defining the receiver as one of these.
+Add a line to `../lib/logitech_receiver/base_usb.py` defining the receiver as one of these.
 If the receiver has an unusual number of pairing slots, then this also needs
 to be specified. Then add the receiver to the tuple of receivers (ALL).
 
-Most new devices do not need to be known to Solaar to work.
+## Supported Receivers
-The _D function in `../lib/logitech_receiver/descriptors.py` makes a device known to Solaar.
-The usual arguments to the _D function are the device's long name, its short name
-(codename), and its HID++ protocol version.
-Devices that use HID++ 1.0 need a tuple of known registers (registers) and settings (settings).
-Settings can be provided for Devices that use HID++ 2.0 or later,
-but Solaar can determine these from the device.
-If the device can connect to a receiver, provide its wireless product ID (wpid),
-If the device can connect via Bluetooth, provide its Bluetooth product ID (btid).
-If the device can connect via a USB cable, provide its USB product ID (usbid),
-and the interface it uses to send and receiver HID++ messages (interface - default 2).
-The use of a non-default USB interface is the main reason for requiring information about
-modern devices to be added to Solaar.
-
-
-### Supported Receivers
 
 | USB ID    | Kind       | Max Paired Devices |
 ------------|------------|--------------------|
@@ -89,6 +73,33 @@ The receiver with USB ID 046d:c517 is an old 27 MHz receiver, supporting only
 subset of HID++ 1.0 protocol. Only hardware pairing is supported.
 
 
+## Adding new devices
+
+Most new devices do not need to be known to Solaar to work.
+
+
+The _D function in `../lib/logitech_receiver/descriptors.py` makes a device known to Solaar.
+The usual arguments to the _D function are the device's long name, its short name
+(codename), and its HID++ protocol version.
+Devices that use HID++ 1.0 need a tuple of known registers (registers) and settings (settings).
+Settings can be provided for Devices that use HID++ 2.0 or later,
+but Solaar can determine these from the device.
+If the device can connect to a receiver, provide its wireless product ID (wpid),
+If the device can connect via Bluetooth, provide its Bluetooth product ID (btid).
+If the device can connect via a USB cable, provide its USB product ID (usbid),
+and the interface it uses to send and receiver HID++ messages (interface - default 2).
+The use of a non-default USB interface is the main reason for requiring information about
+modern devices to be added to Solaar.
+
+
+
+## Supported Devices
+
+The device tables below  provide a list of some of the devices that Solaar supports,
+giving their product name, WPID product number, and HID++ protocol information.
+The tables concentrate on older devices that have explicit support information in Solaar
+and are not being updated for new devices that are supported by Solaar.
+
 ### Keyboards (Unifying)
 
 | Device           | WPID | HID++ |

docs/devices/00README.txt

@@ -29,17 +29,23 @@ Files that do not follow this naming convention are retained for historical purp
 
 File Contents
 
-Each file should start with the Solaar version as given in the first line of
+Each file should contain the output of `solaar show NAME` where NAME
-output from `solaar show` and a blank line.  Next is the output of `solaar
+is enough of the full name of a device or receiver to identify it.
-show` for the device or receiver. The output of `solaar show` can be edited
+The output of `solaar show` will provide information on all connnected
+devices and receivers including their names.
+The output of `solaar show NAME` can be edited
 to remove serial numbers and variable information such as the current values
-of settings.  For older devices probes of the device registers should be
+of settings.
-included but for newer devices this should not be necessary.
+Passing the style requirements for Solaar documentation may require removing
+trailing white space on lines.
+
+For older devices probes of the device registers should be
+included but for newer devices this is not necessary.
 
 Unifying receivers can pair with any device that has the Unifying logo.
 Bolt receivers can pair with any device that has the Bolt logo.
 Nano and Lightspeed receivers can only pair with certain devices,
-so the end of their files should contain device WPIDs that they have
+so the end of their files should state the devices that they have
 been seen to be paired with or are part of.
 
 
@@ -47,4 +53,4 @@ Updating Files
 
 Newer versions of Solaar add support for more settings so it is useful to
 provide updated versions of these files if there is information from the
-current version of `solaar show` that is not in the existing file.
+current version of `solaar show NAME` that is not in the existing file.