bectl.8: Clean up & clarify the create subcommand

- Improve formatting
- Use consistent variable names
- Improve the description of the create subcommand (1)

PR:		235850 (1)
Submitted by:	kevans (1)
Reported by:	ler (1)
Reviewed by:	kevans
Approved by:	src (kevans)
Differential Revision:	https://reviews.freebsd.org/D19666

1 files changed, 79 insertions, 60 deletions

diff --git a/sbin/bectl/bectl.8 b/sbin/bectl/bectl.8
index fce3d606b366..5be50ebf5b51 100644
--- a/sbin/bectl/bectl.8
+++ b/sbin/bectl/bectl.8
@@ -18,12 +18,12 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd February 10, 2019
+.Dd March 21, 2019
 .Dt BECTL 8
 .Os
 .Sh NAME
 .Nm bectl
-.Nd Utility to manage Boot Environments on ZFS
+.Nd Utility to manage boot environments on ZFS
 .Sh SYNOPSIS
 .Nm
 .Cm activate
@@ -32,16 +32,12 @@
 .Nm
 .Cm create
 .Op Fl r
-.Op Fl e Brq Ar nonActiveBe | beName@snapshot
-.Ar beName
-.Nm
-.Cm create
-.Op Fl r
-.Ar beName@snapshot
+.Op Fl e Brq Ar nonActiveBe | Ar beName Ns Cm @ Ns Ar snapshot
+.Ar newBeName
 .Nm
 .Cm destroy
 .Op Fl \&Fo
-.Brq Ar beName | beName@snapshot
+.Ar beName Ns Op Cm @ Ns Ar snapshot
 .Nm
 .Cm export
 .Ar sourceBe
@@ -50,39 +46,42 @@
 .Ar targetBe
 .Nm
 .Cm jail
-.Brq Fl b | Fl U
-.Oo Bro Fl o Ar key Ns = Ns Ar value | Fl u Ar key Brc Oc Ns ...
-.Ar bootenv
+.Op Fl bU
+.Oo Bro Fl o Ar key Ns Cm = Ns Ar value | Fl u Ar key Brc Oc Ns ...
+.Ar beName
 .Op Ar utility Op Ar argument ...
 .Nm
 .Cm list
-.Op Fl DHas
+.Op Fl aDHs
 .Nm
 .Cm mount
 .Ar beName
-.Op mountpoint
+.Op Ar mountpoint
 .Nm
 .Cm rename
 .Ar origBeName
 .Ar newBeName
 .Nm
 .Brq Cm ujail | unjail
-.Brq Ar jailID | jailName
-.Ar bootenv
+.Brq Ar jailId | jailName
+.Ar beName
 .Nm
 .Brq Cm umount | unmount
 .Op Fl f
 .Ar beName
+.Pp
+.Nm
+.Op Fl h\&?
 .Sh DESCRIPTION
 The
 .Nm
 command is used to setup and interact with ZFS boot environments, which are
 bootable clones of datasets.
 .Pp
-.Em Boot Environments
-allows the system to be upgraded, while preserving the old system environment in
+Boot environments
+allow the system to be upgraded, while preserving the old system environment in
 a separate ZFS dataset.
-.Sh COMMANDS
+.Pp
 The following commands are supported by
 .Nm :
 .Bl -tag -width activate
@@ -100,39 +99,38 @@ flag is given, this takes effect only for the next boot.
 .It Xo
 .Cm create
 .Op Fl r
-.Op Fl e Brq Ar nonActiveBe | beName@snapshot
-.Ar beName
+.Op Fl e Brq Ar nonActiveBe | Ar beName Ns Cm @ Ns Ar snapshot
+.Ar newBeName
 .Xc
-Creates a new boot environment named
-.Ar beName .
-If the
-.Fl e
-argument is specified, the new environment will be cloned from the given
-.Brq Ar nonActiveBe | Ar beName@snapshot .
+Create a new boot environment named
+.Ar newBeName .
+.Pp
 If the
 .Fl r
 flag is given, a recursive boot environment will be made.
-.It Xo
-.Cm create
-.Op Fl r
-.Ar beName@snapshot
-.Xc
-Creates a snapshot of the existing boot environment named
-.Ar beName .
+.Pp
 If the
-.Fl r
-flag is given, a recursive boot environment will be made.
+.Fl e
+flag is specified, the new environment will be cloned from the given
+.Ar nonActiveBe
+or
+.Ar beName Ns Cm @ Ns Ar snapshot .
+Otherwise, the new environment will be created from the currently booted environment.
+.Pp
+If
+.Nm
+is creating from another boot environment, a snapshot of that boot environment will be created to clone from.
 .It Xo
 .Cm destroy
 .Op Fl \&Fo
-.Brq Ar beName | beName@snapshot
+.Ar beName Ns Op Cm @ Ns Ar snapshot
 .Xc
-Destroys the given
+Destroy the given
 .Ar beName
 boot environment or
-.Ar beName@snapshot
+.Ar beName Ns Cm @ Ns Ar snapshot
 snapshot without confirmation, unlike in
-.Nm beadm .
+.Xr beadm 1 .
 Specifying
 .Fl F
 will automatically unmount without confirmation.
@@ -148,22 +146,22 @@ flag may be specified to destroy the origin as well.
 Export
 .Ar sourceBe
 to
-.Dv stdout .
-.Dv stdout
+.Xr stdout 4 .
+.Xr stdout 4
 must be piped or redirected to a file.
 .It Cm import Ar targetBe
 Import
 .Ar targetBe
 from
-.Dv stdin .
+.Xr stdin 4 .
 .It Xo
 .Cm jail
-.Brq Fl b | Fl U
-.Oo Bro Fl o Ar key Ns = Ns Ar value | Fl u Ar key Brc Oc Ns ...
-.Ao Ar bootenv Ac
+.Op Fl bU
+.Oo Bro Fl o Ar key Ns Cm = Ns Ar value | Fl u Ar key Brc Oc Ns ...
+.Ar beName
 .Op Ar utility Op Ar argument ...
 .Xc
-Creates a jail of the given boot environment.
+Create a jail of the given boot environment.
 Multiple
 .Fl o
 and
@@ -202,7 +200,7 @@ and
 must be set, the default values are specified below.
 .Pp
 All
-.Ar key Ns = Ns Ar value
+.Ar key Ns Cm = Ns Ar value
 pairs are interpreted as jail parameters as described in
 .Xr jail 8 .
 The following default parameters are provided:
@@ -210,17 +208,24 @@ The following default parameters are provided:
 .It Va allow.mount Ta Cm true
 .It Va allow.mount.devfs Ta Cm true
 .It Va enforce_statfs Ta Cm 1
-.It Va name Ta jail id
+.It Va name Ta Set to jail ID.
 .It Va host.hostname Ta Va bootenv
-.It Va path Ta Set to a path in /tmp generated by
+.It Va path Ta Set to a path in Pa /tmp
+generated by
 .Xr libbe 3 .
 .El
 .Pp
 All default parameters may be overwritten.
-.It Cm list Op Fl DHas
-Displays all boot environments.
-The Active field indicates whether the boot environment is active now (N);
-active on reboot (R); or both (NR).
+.It Cm list Op Fl aDHs
+Display all boot environments.
+The
+.Em Active
+field indicates whether the boot environment is active now
+.Pq Em \&N ;
+active on reboot
+.Pq Em \&R ;
+or both
+.Pq Em \&NR .
 .Pp
 If
 .Fl a
@@ -243,13 +248,19 @@ Mount at the specified
 .Ar mountpoint
 if provided.
 .It Cm rename Ar origBeName newBeName
-Renames the given
+Rename the given
 .Ar origBeName
 to the given
 .Ar newBeName .
 The boot environment will not be unmounted in order for this rename to occur.
-.It Cm unjail Brq Ar jailID | jailName | beName
-Destroys the jail created from the given boot environment.
+.It Cm ujail Bro Ar jailId | jailName Brc Ar beName
+.It Cm unjail Bro Ar jailId | jailName Brc Ar beName
+Destroy the jail created from the given boot environment.
+.It Xo
+.Cm umount
+.Op Fl f
+.Ar beName
+.Xc
 .It Xo
 .Cm unmount
 .Op Fl f
@@ -260,12 +271,20 @@ Specifying
 .Fl f
 will force the unmount if busy.
 .El
+.Pp
+.Nm
+prints usage information if
+.Fl h
+or
+.Fl \&?
+is specified.
 .Sh EXAMPLES
 .Bl -bullet
 .It
 To fill in with jail upgrade example when behavior is firm.
 .El
 .Sh SEE ALSO
+.Xr beinstall.sh 1 ,
 .Xr libbe 3 ,
 .Xr jail 8 ,
 .Xr zfs 8 ,
@@ -273,7 +292,7 @@ To fill in with jail upgrade example when behavior is firm.
 .Sh HISTORY
 .Nm
 is based on
-.Nm beadm
+.Xr beadm 1
 and was implemented as a project for the 2017 Summer of Code, along with
 .Xr libbe 3 .
 .Sh AUTHORS
@@ -281,11 +300,11 @@ and was implemented as a project for the 2017 Summer of Code, along with
 was written by
 .An Kyle Kneitinger (kneitinger) Aq Mt kyle@kneit.in .
 .Pp
-.Nm beadm
+.Xr beadm 1
 was written and is maintained by
 .An Slawomir Wojciech Wojtczak (vermaden) Aq Mt vermaden@interia.pl .
 .Pp
 .An Bryan Drewery (bdrewery) Aq Mt bryan@shatow.net
 wrote the original
-.Nm beadm
+.Xr beadm 1
 manual page that this one is derived from.