git: 5eafaf9e6889 - main - usbconfig.8: Improve style and fix examples

The branch main has been updated by 0mp (doc, ports committer):

URL: https://cgit.FreeBSD.org/src/commit/?id=5eafaf9e68894cda4e8dca5f363be0b4f15b5cd6

commit 5eafaf9e68894cda4e8dca5f363be0b4f15b5cd6
Author:     Mateusz Piotrowski <0mp@FreeBSD.org>
AuthorDate: 2022-01-29 20:59:29 +0000
Commit:     Mateusz Piotrowski <0mp@FreeBSD.org>
CommitDate: 2022-01-29 21:05:22 +0000

    usbconfig.8: Improve style and fix examples
    
    - Use Ar macros for arguments
    - Stylize the argument synopsis to the -d flag
    - Change the width of the list to one of the actual tags in the list
    - Stylize "ugen" and "/dev/ugen" with Cm as those are constant strings,
      which are usually treated as command modifiers.
    - Break long lines to reduce the number of warnings from linters
    - Fix examples; the -d flag is now required when specifying the unit and
      the address with the "dot notation".
    
    MFC after:      2 weeks
---
 usr.sbin/usbconfig/usbconfig.8 | 36 +++++++++++++++++++++++-------------
 1 file changed, 23 insertions(+), 13 deletions(-)

diff --git a/usr.sbin/usbconfig/usbconfig.8 b/usr.sbin/usbconfig/usbconfig.8
index e34cf7cfd5d0..0644199bdca7 100644
--- a/usr.sbin/usbconfig/usbconfig.8
+++ b/usr.sbin/usbconfig/usbconfig.8
@@ -23,7 +23,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd December 21, 2021
+.Dd January 29, 2022
 .Dt USBCONFIG 8
 .Os
 .Sh NAME
@@ -35,36 +35,46 @@
 .Op Fl a Ar addr
 .Op Fl i Ar interface_index
 .Op Fl v
-.Op cmds...
+.Op Ar cmds ...
 .Nm
-.Fl d Ar [[/dev/]ugen]<unit>.<addr>
+.Fl d
+.Sm off
+.Oo Oo Cm /dev/ Oc Cm ugen Oc Ar unit Cm \&. Ar addr
+.Sm on
 .Op Fl i Ar interface_index
 .Op Fl v
-.Op cmds...
+.Op Ar cmds ...
 .Sh DESCRIPTION
 The
 .Nm
 utility is used to configure and dump information about the USB subsystem.
 .Pp
 The options are as follows:
-.Bl -tag -width "        "
+.Bl -tag -width "-u unit"
 .It Fl u Ar unit
 Limit device range to USB devices connected to the given USBUS unit.
 .It Fl a Ar addr
 Limit device range to the given USB device index.
 Should only be used in conjunction with the unit argument.
-.It Fl d Ar [[/dev/]ugen]<unit>.<addr>
+.It Xo
+.Fl d
+.Sm off
+.Oo Oo Cm /dev/ Oc Cm ugen Oc Ar unit Cm \&. Ar addr
+.Sm on
+.Xc
 Limit device range to USB devices connected to the given unit and address.
-The unit and address coordinates may be prefixed by the lowercased word "ugen",
+The unit and address coordinates may be prefixed by the lowercased word
+.Cm ugen ,
 or the full path name
-.Pa /dev/ugen .
+.Cm /dev/ugen .
 .It Fl h
 Show help and available commands.
 .It Fl i Ar interface_index
 Specify interface index as indicated by the command description.
-If this argument is not specified a value of zero will be used for the interface index.
+If this argument is not specified
+a value of zero will be used for the interface index.
 .It Fl v
-Shortcut to activate the
+Activate the
 .Cm dump_device_desc ,
 .Cm dump_curr_config_desc ,
 and
@@ -179,15 +189,15 @@ List all connected USB devices and their attached interface drivers:
 .Pp
 Dump device and configuration descriptors for device on USB bus 1 at address 2:
 .Pp
-.Dl usbconfig ugen1.2 dump_all_desc
+.Dl usbconfig -d ugen1.2 dump_all_desc
 .Pp
 Dump HID descriptor for device on USB bus 1 at address 2:
 .Pp
-.Dl usbconfig ugen1.2 do_request 0x81 0x06 0x2200 0 0x100
+.Dl usbconfig -d ugen1.2 do_request 0x81 0x06 0x2200 0 0x100
 .Pp
 Power off the device on USB bus 1 at address 2:
 .Pp
-.Dl usbconfig ugen1.2 power_off
+.Dl usbconfig -d ugen1.2 power_off
 .Sh SEE ALSO
 .Xr usb 4 ,
 .Xr usb_quirk 4 ,