From 8b97e97548bdc74cf3b4939a0b21cfdd27d8c11c Mon Sep 17 00:00:00 2001
From: Mateusz Piotrowski <0mp@FreeBSD.org>
Date: Mon, 19 Apr 2021 00:59:44 +0200
Subject: [PATCH] bhyve.8: Improve framebuffer backends description

- Use appropriate mdoc macros
- Document that tcp= is a synonym to rfb= (tcp is used in the examples,
  but never mentioned)
- Clarify the IP address specification

MFC after:	2 weeks
---
 usr.sbin/bhyve/bhyve.8 | 62 ++++++++++++++++++++++++++----------------
 1 file changed, 39 insertions(+), 23 deletions(-)

diff --git a/usr.sbin/bhyve/bhyve.8 b/usr.sbin/bhyve/bhyve.8
index 88be882039c4..afc3a5c615c8 100644
--- a/usr.sbin/bhyve/bhyve.8
+++ b/usr.sbin/bhyve/bhyve.8
@@ -540,35 +540,52 @@ resize at present.
 Emergency write is advertised, but no-op at present.
 .El
 .Pp
-Framebuffer devices:
+Framebuffer devices backends:
+.Bl -bullet
+.Sm off
+.It
+.Op Cm rfb= Ar ip-and-port
+.Op Cm ,w= Ar width
+.Op Cm ,h= Ar height
+.Op Cm ,vga= Ar vgaconf
+.Op Cm ,wait
+.Op Cm ,password= Ar password
+.Sm on
+.El
+.Pp
+Configuration options are defined as follows:
 .Bl -tag -width 10n
-.It Xo
-.Oo rfb= Ns Oo Ar IP\&: Oc Ns Ar port Oc Ns Oo ,w= Ns Ar width Oc Ns Oo ,h= Ns
-.Ar height Oc Ns Oo ,vga= Ns Ar vgaconf Oc Ns Oo Ns ,wait Oc Ns Oo ,password= Ns
-.Ar password Oc
-.Xc
-.Bl -tag -width 8n
-.It Ar IPv4:port No or Ar [IPv6%zone]:port
-An
-.Ar IP
-address and a
+.It Cm rfb= Ns Ar ip-and-port Pq or Cm tcp= Ns Ar ip-and-port
+An IP address and a port VNC should listen on.
+There are two formats:
+.Pp
+.Bl -bullet -compact
+.It IPv4
+.Sm off
+.Op Ar IPv4 Cm \&:
 .Ar port
-VNC should listen on.
+.Sm on
+.It IPv6
+.Sm off
+.Cm \&[ Ar IPv6%zone Cm \&] Cm \&: Ar port
+.Sm on
+.El
+.Pp
 The default is to listen on localhost IPv4 address and default VNC port 5900.
 An IPv6 address must be enclosed in square brackets and may contain an
 optional zone identifier.
-.It Ar width No and Ar height
+.It Cm w= Ns Ar width No and Cm h= Ns Ar height
 A display resolution, width and height, respectively.
 If not specified, a default resolution of 1024x768 pixels will be used.
 Minimal supported resolution is 640x480 pixels,
 and maximum is 1920x1200 pixels.
-.It Ar vgaconf
+.It Cm vga= Ns Ar vgaconf
 Possible values for this option are
-.Dq io
+.Cm io
 (default),
-.Dq on
+.Cm on
 , and
-.Dq off .
+.Cm off .
 PCI graphics cards have a dual personality in that they are
 standard PCI devices with BAR addressing, but may also
 implicitly decode legacy VGA I/O space
@@ -576,18 +593,18 @@ implicitly decode legacy VGA I/O space
 and memory space
 .Pq 64KB at Ad 0xA0000 .
 The default
-.Dq io
+.Cm io
 option should be used for guests that attempt to issue BIOS calls which result
 in I/O port queries, and fail to boot if I/O decode is disabled.
 .Pp
 The
-.Dq on
+.Cm on
 option should be used along with the CSM BIOS capability in UEFI
 to boot traditional BIOS guests that require the legacy VGA I/O and
 memory regions to be available.
 .Pp
 The
-.Dq off
+.Cm off
 option should be used for the UEFI guests that assume that
 VGA adapter is present if they detect the I/O ports.
 An example of such a guest is
@@ -600,19 +617,18 @@ Please refer to the
 wiki page
 .Pq Lk https://wiki.freebsd.org/bhyve
 for configuration notes of particular guests.
-.It wait
+.It Cm wait
 Instruct
 .Nm
 to only boot upon the initiation of a VNC connection, simplifying the
 installation of operating systems that require immediate keyboard input.
 This can be removed for post-installation use.
-.It password
+.It Cm password= Ns Ar password
 This type of authentication is known to be cryptographically weak and is not
 intended for use on untrusted networks.
 Many implementations will want to use stronger security, such as running
 the session over an encrypted channel provided by IPsec or SSH.
 .El
-.El
 .Pp
 xHCI USB devices:
 .Bl -tag -width 10n