crosvm: improve crosvm run --help output

The specifiers and descriptions for crosvm options are just too long
to fit into a table.  Options were already eclipsing the widths of the
table cells, and sizing them correctly just made the table infeasibly
wide.

So, instead, just print out paragraphs for each option, and stop
trying to fit things into a table.  Use this opportunity to add some
spacing and make key value lists within option descriptions more
readable.

Also, make formatting consistent.  Consistent spacing between
sentences, consistent default output, etc.

1 files changed, 213 insertions, 88 deletions

diff --git a/src/main.rs b/src/main.rs
index fb1be25..a9ceff6 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -1076,118 +1076,243 @@ fn set_argument(cfg: &mut Config, name: &str, value: Option<&str>) -> argument::
 
 fn run_vm(args: std::env::Args) -> std::result::Result<(), ()> {
     let arguments =
-        &[Argument::positional("KERNEL", "bzImage of kernel to run"),
-          Argument::value("android-fstab", "PATH", "Path to Android fstab"),
+        &[Argument::positional("KERNEL", "bzImage of kernel to run."),
+          Argument::value("android-fstab", "PATH", "Path to Android fstab."),
           Argument::short_value('i', "initrd", "PATH", "Initial ramdisk to load."),
-          Argument::short_value('p',
-                                "params",
-                                "PARAMS",
-                                "Extra kernel or plugin command line arguments. Can be given more than once."),
-          Argument::short_value('c', "cpus", "N", "Number of VCPUs. (default: 1)"),
-          Argument::value("cpu-affinity", "CPUSET", "Comma-separated list of CPUs or CPU ranges to run VCPUs on. (e.g. 0,1-3,5) (default: no mask)"),
-          Argument::short_value('m',
-                                "mem",
-                                "N",
-                                "Amount of guest memory in MiB. (default: 256)"),
-          Argument::short_value('r',
-                                "root",
-                                "PATH[,key=value[,key=value[,...]]",
-                                "Path to a root disk image followed by optional comma-separated options.
-                              Like `--disk` but adds appropriate kernel command line option.
-                              See --disk for valid options."),
-          Argument::value("rwroot", "PATH[,key=value[,key=value[,...]]", "Path to a writable root disk image followed by optional comma-separated options.
-                              See --disk for valid options."),
-          Argument::short_value('d', "disk", "PATH[,key=value[,key=value[,...]]", "Path to a disk image followed by optional comma-separated options.
-                              Valid keys:
-                              sparse=BOOL - Indicates whether the disk should support the discard operation (default: true)
-                              block_size=BYTES - Set the reported block size of the disk (default: 512)"),
-          Argument::value("qcow", "PATH", "Path to a qcow2 disk image. (Deprecated; use --disk instead.)"),
-          Argument::value("rwdisk", "PATH[,key=value[,key=value[,...]]", "Path to a writable disk image followed by optional comma-separated options.
-                              See --disk for valid options."),
-          Argument::value("rwqcow", "PATH", "Path to a writable qcow2 disk image. (Deprecated; use --rwdisk instead.)"),
+          Argument::short_value('p', "params", "PARAMS", "\
+Extra kernel or plugin command line arguments.  Can be given more than once.
+"),
+          Argument::short_value('c', "cpus", "N", "Number of VCPUs.  (default: 1)"),
+          Argument::value("cpu-affinity", "CPUSET", "\
+Comma-separated list of CPUs or CPU ranges to run VCPUs on (e.g. 0,1-3,5).
+(default: no mask)
+"),
+          Argument::short_value('m', "mem", "N", "Amount of guest memory in MiB.  (default: 256)"),
+          Argument::short_value('r', "root", "PATH[,key=value[,key=value[,...]]", "\
+Path to a root disk image followed by optional comma-separated options.
+Like --disk but adds appropriate kernel command line option.  See --disk for
+valid options.
+"),
+          Argument::value("rwroot", "PATH[,key=value[,key=value[,...]]", "\
+Path to a writable root disk image followed by optional comma-separated
+options.  See --disk for valid options.
+"),
+          Argument::short_value('d', "disk", "PATH[,key=value[,key=value[,...]]", "\
+Path to a disk image followed by optional comma-separated options.
+
+Valid keys:
+
+  sparse=BOOL
+    Indicates whether the disk should support the discard operation.
+    (default: true)
+
+  block_size=BYTES
+    Set the reported block size of the disk.
+    (default: 512)
+"),
+          Argument::value("qcow", "PATH", "\
+Path to a qcow2 disk image.  (Deprecated; use --disk instead.)
+"),
+          Argument::value("rwdisk", "PATH[,key=value[,key=value[,...]]", "\
+Path to a writable disk image followed by optional comma-separated options.
+See --disk for valid options.
+"),
+          Argument::value("rwqcow", "PATH", "\
+Path to a writable qcow2 disk image.  (Deprecated; use --rwdisk instead.)
+"),
           Argument::value("rw-pmem-device", "PATH", "Path to a writable disk image."),
           Argument::value("pmem-device", "PATH", "Path to a disk image."),
-          Argument::value("pstore", "path=PATH,size=SIZE", "Path to pstore buffer backend file follewed by size."),
-          Argument::value("host_ip",
-                          "IP",
-                          "IP address to assign to host tap interface."),
+          Argument::value("pstore", "path=PATH,size=SIZE", "\
+Path to pstore buffer backend file follewed by size.
+"),
+          Argument::value("host_ip", "IP", "IP address to assign to host tap interface."),
           Argument::value("netmask", "NETMASK", "Netmask for VM subnet."),
           Argument::value("mac", "MAC", "MAC address for VM."),
-          Argument::flag("cras-audio", "Add an audio device to the VM that plays samples through CRAS server"),
-          Argument::flag("cras-capture", "Enable capturing audio from CRAS server to the cras-audio device"),
-          Argument::flag("null-audio", "Add an audio device to the VM that plays samples to /dev/null"),
-          Argument::value("serial",
-                          "type=TYPE,[num=NUM,path=PATH,console,stdin]",
-                          "Comma separated key=value pairs for setting up serial devices. Can be given more than once.
-                          Possible key values:
-                          type=(stdout,syslog,sink,file) - Where to route the serial device
-                          num=(1,2,3,4) - Serial Device Number. If not provided, num will default to 1.
-                          path=PATH - The path to the file to write to when type=file
-                          console - Use this serial device as the guest console. Can only be given once. Will default to first serial port if not provided.
-                          stdin - Direct standard input to this serial device. Can only be given once. Will default to first serial port if not provided.
-                          "),
+          Argument::flag("cras-audio", "\
+Add an audio device to the VM that plays samples through CRAS server.
+"),
+          Argument::flag("cras-capture", "\
+Enable capturing audio from CRAS server to the cras-audio device.
+"),
+          Argument::flag("null-audio", "\
+Add an audio device to the VM that plays samples to /dev/null.
+"),
+          Argument::value("serial", "type=TYPE,[num=NUM,path=PATH,console,stdin]", "\
+Comma separated key=value pairs for setting up serial devices. Can be given
+more than once.
+
+Possible key values:
+
+  type=(stdout,syslog,sink,file)
+    Where to route the serial device.
+
+  num=(1,2,3,4)
+    Serial Device Number.  If not provided, num will default to 1.
+
+  path=PATH
+    The path to the file to write to when type=file.
+
+  console
+    Use this serial device as the guest console.  Can only be given once.
+    Will default to first serial port if not provided.
+
+  stdin
+    Direct standard input to this serial device.  Can only be given once.
+    Will default to first serial port if not provided.
+"),
           Argument::value("syslog-tag", "TAG", "When logging to syslog, use the provided tag."),
           Argument::value("x-display", "DISPLAY", "X11 display name to use."),
-          Argument::flag("display-window-keyboard", "Capture keyboard input from the display window."),
+          Argument::flag("display-window-keyboard", "\
+Capture keyboard input from the display window.
+"),
           Argument::flag("display-window-mouse", "Capture keyboard input from the display window."),
-          Argument::value("wayland-sock", "PATH[,name=NAME]", "Path to the Wayland socket to use. The unnamed one is used for displaying virtual screens. Named ones are only for IPC."),
+          Argument::value("wayland-sock", "PATH[,name=NAME]", "\
+Path to the Wayland socket to use.  The unnamed one is used for displaying
+virtual screens.  Named ones are only for IPC.
+"),
           #[cfg(feature = "wl-dmabuf")]
           Argument::flag("wayland-dmabuf", "Enable support for DMABufs in Wayland device."),
-          Argument::short_value('s',
-                                "socket",
-                                "PATH",
-                                "Path to put the control socket. If PATH is a directory, a name will be generated."),
+          Argument::short_value('s', "socket", "PATH", "\
+Path to put the control socket.  If PATH is a directory, a name will be
+generated.
+"),
           Argument::flag("disable-sandbox", "Run all devices in one, non-sandboxed process."),
           Argument::value("cid", "CID", "Context ID for virtual sockets."),
-          Argument::value("shared-dir", "PATH:TAG[:type=TYPE:writeback=BOOL:timeout=SECONDS:uidmap=UIDMAP:gidmap=GIDMAP:cache=CACHE]",
-                          "Colon-separated options for configuring a directory to be shared with the VM.
-The first field is the directory to be shared and the second field is the tag that the VM can use to identify the device.
-The remaining fields are key=value pairs that may appear in any order.  Valid keys are:
-type=(p9, fs) - Indicates whether the directory should be shared via virtio-9p or virtio-fs (default: p9).
-uidmap=UIDMAP - The uid map to use for the device's jail in the format \"inner outer count[,inner outer count]\" (default: 0 <current euid> 1).
-gidmap=GIDMAP - The gid map to use for the device's jail in the format \"inner outer count[,inner outer count]\" (default: 0 <current egid> 1).
-cache=(never, auto, always) - Indicates whether the VM can cache the contents of the shared directory (default: auto).  When set to \"auto\" and the type is \"fs\", the VM will use close-to-open consistency for file contents.
-timeout=SECONDS - How long the VM should consider file attributes and directory entries to be valid (default: 5).  If the VM has exclusive access to the directory, then this should be a large value.  If the directory can be modified by other processes, then this should be 0.
-writeback=BOOL - Indicates whether the VM can use writeback caching (default: false).  This is only safe to do when the VM has exclusive access to the files in a directory.  Additionally, the server should have read permission for all files as the VM may issue read requests even for files that are opened write-only.
-"),
+          Argument::value("shared-dir", "\
+PATH:TAG[:type=TYPE:writeback=BOOL:timeout=SECONDS:uidmap=UIDMAP:gidmap=GIDMAP:cache=CACHE]",
+r#"Colon-separated options for configuring a directory to be shared with the
+VM.
+
+The first field is the directory to be shared and the second field is the
+tag that the VM can use to identify the device.  The remaining fields are
+key=value pairs that may appear in any order.  Valid keys are:
+
+  type=(p9, fs)
+    Indicates whether the directory should be shared via virtio-9p or
+    virtio-fs.
+    (default: p9)
+
+  uidmap=UIDMAP
+    The uid map to use for the device's jail in the format
+    "inner outer count[,inner outer count]".
+    (default: 0 <current euid> 1).
+
+  gidmap=GIDMAP
+    The gid map to use for the device's jail in the format
+    "inner outer count[,inner outer count]".
+    (default: 0 <current egid> 1)
+
+  cache=(never, auto, always)
+    Indicates whether the VM can cache the contents of the shared directory.
+    When set to "auto" and the type is "fs", the VM will use
+    close-to-open consistency for file contents.
+    (default: auto)
+
+  timeout=SECONDS
+    How long the VM should consider file attributes and directory entries to
+    be valid.  If the VM has exclusive access to the directory, then this
+    should be a large value.  If the directory can be modified by other
+    processes, then this should be 0.
+    (default: 5)
+
+  writeback=BOOL
+    Indicates whether the VM can use writeback caching.  This is only safe
+    to do when the VM has exclusive access to the files in a directory.
+    Additionally, the server should have read permission for all files as
+    the VM may issue read requests even for files that are opened
+    write-only.
+    (default: false)
+"#),
           Argument::value("seccomp-policy-dir", "PATH", "Path to seccomp .policy files."),
-          Argument::flag("seccomp-log-failures", "Instead of seccomp filter failures being fatal, they will be logged instead."),
+          Argument::flag("seccomp-log-failures", "\
+Instead of seccomp filter failures being fatal, they will be logged instead."),
           #[cfg(feature = "plugin")]
           Argument::value("plugin", "PATH", "Absolute path to plugin process to run under crosvm."),
           #[cfg(feature = "plugin")]
-          Argument::value("plugin-root", "PATH", "Absolute path to a directory that will become root filesystem for the plugin process."),
+          Argument::value("plugin-root", "PATH", "\
+Absolute path to a directory that will become root filesystem for the plugin
+process.
+"),
           #[cfg(feature = "plugin")]
-          Argument::value("plugin-mount", "PATH:PATH:BOOL", "Path to be mounted into the plugin's root filesystem.  Can be given more than once."),
+          Argument::value("plugin-mount", "PATH:PATH:BOOL", "\
+Path to be mounted into the plugin's root filesystem.  Can be given more
+than once.
+"),
           #[cfg(feature = "plugin")]
-          Argument::value("plugin-mount-file", "PATH", "Path to the file listing paths be mounted into the plugin's root filesystem.  Can be given more than once."),
+          Argument::value("plugin-mount-file", "PATH", "\
+Path to the file listing paths be mounted into the plugin's root filesystem.
+Can be given more than once.
+"),
           #[cfg(feature = "plugin")]
-          Argument::value("plugin-gid-map", "GID:GID:INT", "Supplemental GIDs that should be mapped in plugin jail.  Can be given more than once."),
+          Argument::value("plugin-gid-map", "GID:GID:INT", "\
+Supplemental GIDs that should be mapped in plugin jail.  Can be given more
+than once.
+"),
           #[cfg(feature = "plugin")]
-          Argument::value("plugin-gid-map-file", "PATH", "Path to the file listing supplemental GIDs that should be mapped in plugin jail.  Can be given more than once."),
+          Argument::value("plugin-gid-map-file", "PATH", "\
+Path to the file listing supplemental GIDs that should be mapped in plugin
+jail.  Can be given more than once.
+"),
           Argument::flag("vhost-net", "Use vhost for networking."),
-          Argument::value("tap-fd",
-                          "fd",
-                          "File descriptor for configured tap device. A different virtual network card will be added each time this argument is given."),
+          Argument::value("tap-fd", "fd", "\
+File descriptor for configured tap device.  A different virtual network card
+will be added each time this argument is given.
+"),
           #[cfg(feature = "gpu")]
-          Argument::flag_or_value("gpu",
-                                  "[width=INT,height=INT]",
-                                  "(EXPERIMENTAL) Comma separated key=value pairs for setting up a virtio-gpu device
-                                  Possible key values:
-                                  width=INT - The width of the virtual display connected to the virtio-gpu.
-                                  height=INT - The height of the virtual display connected to the virtio-gpu.
-                                  egl[=true|=false] - If the virtio-gpu backend should use a EGL context for rendering.
-                                  glx[=true|=false] - If the virtio-gpu backend should use a GLX context for rendering.
-                                  surfaceless[=true|=false] - If the virtio-gpu backend should use a surfaceless context for rendering.
-                                  "),
+          Argument::flag_or_value("gpu", "[width=INT,height=INT]", "\
+(EXPERIMENTAL)
+Comma separated key=value pairs for setting up a virtio-gpu device.
+
+Possible key values:
+
+  width=INT
+    The width of the virtual display connected to the virtio-gpu.
+
+  height=INT
+    The height of the virtual display connected to the virtio-gpu.
+
+  egl[=true|=false]
+    If the virtio-gpu backend should use a EGL context for rendering.
+
+  glx[=true|=false]
+    If the virtio-gpu backend should use a GLX context for rendering.
+
+  surfaceless[=true|=false]
+    If the virtio-gpu backend should use a surfaceless context for rendering.
+"),
           #[cfg(feature = "tpm")]
-          Argument::flag("software-tpm", "enable a software emulated trusted platform module device"),
-          Argument::value("evdev", "PATH", "Path to an event device node. The device will be grabbed (unusable from the host) and made available to the guest with the same configuration it shows on the host"),
-          Argument::value("single-touch", "PATH:WIDTH:HEIGHT", "Path to a socket from where to read single touch input events (such as those from a touchscreen) and write status updates to, optionally followed by width and height (defaults to 800x1280)."),
-          Argument::value("trackpad", "PATH:WIDTH:HEIGHT", "Path to a socket from where to read trackpad input events and write status updates to, optionally followed by screen width and height (defaults to 800x1280)."),
-          Argument::value("mouse", "PATH", "Path to a socket from where to read mouse input events and write status updates to."),
-          Argument::value("keyboard", "PATH", "Path to a socket from where to read keyboard input events and write status updates to."),
+          Argument::flag("software-tpm", "\
+Enable a software emulated trusted platform module device.
+"),
+          Argument::value("evdev", "PATH", "\
+Path to an event device node. The device will be grabbed (unusable from the
+host) and made available to the guest with the same configuration it shows
+on the host.
+"),
+          Argument::value("single-touch", "PATH:WIDTH:HEIGHT", "\
+Path to a socket from where to read single touch input events (such as those
+from a touchscreen) and write status updates to, optionally followed by
+width and height.
+(default: 800x1280)
+"),
+          Argument::value("trackpad", "PATH:WIDTH:HEIGHT", "\
+Path to a socket from where to read trackpad input events and write status
+updates to, optionally followed by screen width and height.
+(default: 800x1280)
+"),
+          Argument::value("mouse", "PATH", "\
+Path to a socket from where to read mouse input events and write status
+updates to.
+"),
+          Argument::value("keyboard", "PATH", "\
+Path to a socket from where to read keyboard input events and write status
+updates to.
+"),
           #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
-          Argument::flag("split-irqchip", "(EXPERIMENTAL) enable split-irqchip support"),
+          Argument::flag("split-irqchip", "\
+(EXPERIMENTAL)
+Enable split-irqchip support.
+"),
           Argument::value("bios", "PATH", "Path to BIOS/firmware ROM"),
           Argument::value("vfio", "PATH", "Path to sysfs of pass through or mdev device"),
           Argument::short_flag('h', "help", "Print help message.")];