svn commit: r338222 - head/sbin/bectl

Thu Aug 23 02:09:53 UTC 2018

Author: kevans
Date: Thu Aug 23 02:09:52 2018
New Revision: 338222
URL: https://svnweb.freebsd.org/changeset/base/338222

Log:
  bectl(8): Man page and usage cleanup
  
  - Some overly-long lines
  - Consistently using .Brq ({})
  - Consistently using .Cm
  - Not using .Ao/.Ac around .Ar
  
  PR:		230576
  Submitted by:	Yuri Pankov (with a fair amount of rebasing pre-commit)

Modified:
  head/sbin/bectl/bectl.8
  head/sbin/bectl/bectl.c

Modified: head/sbin/bectl/bectl.8
==============================================================================

--- head/sbin/bectl/bectl.8	Thu Aug 23 01:45:18 2018	(r338221)
+++ head/sbin/bectl/bectl.8	Thu Aug 23 02:09:52 2018	(r338222)
@@ -26,103 +26,108 @@
 .Nd Utility to manage Boot Environments on ZFS
 .Sh SYNOPSIS
 .Nm
-activate
+.Cm activate
 .Op Fl t
-.Ao Ar beName Ac
+.Ar beName
 .Nm
-create
+.Cm create
 .Op Fl r
-.Op Fl e Ar nonActiveBe | Fl e Ar beName at snapshot
-.Ao Ar beName Ac
+.Op Fl e Brq Ar nonActiveBe | beName at snapshot
+.Ar beName
 .Nm
-create
+.Cm create
 .Op Fl r
-.Ao Ar beName at snapshot Ac
+.Ar beName at snapshot
 .Nm
-destroy
+.Cm destroy
 .Op Fl F
-.Ao Ar beName | beName at snapshot Ac
+.Brq Ar beName | beName at snapshot
 .Nm
-export
-.Ao Ar sourceBe Ac
+.Cm export
+.Ar sourceBe
 .Nm
-import
-.Ao Ar targetBe Ac
+.Cm import
+.Ar targetBe
 .Nm
-jail
-.Op Fl b | Fl U
-.Oo Fl o Ar key Ns = Ns Ar value | Fl u Ar key Oc Ns ...
-.Ao Ar jailID | jailName Ac
-.Ao Ar bootenv Ac
+.Cm jail
+.Brq Fl b | Fl U
+.Oo Bro Fl o Ar key Ns = Ns Ar value | Fl u Ar key Brc Oc Ns ...
+.Brq Ar jailID | jailName
+.Ar bootenv
 .Op Ar utility Op Ar argument ...
 .Nm
-list
-.Op Fl a
-.Op Fl D
-.Op Fl H
-.Op Fl s
+.Cm list
+.Op Fl DHas
 .Nm
-mount
-.Ao Ar beName Ac
+.Cm mount
+.Ar beName
 .Op mountpoint
 .Nm
-rename
-.Ao Ar origBeName Ac
-.Ao Ar newBeName Ac
+.Cm rename
+.Ar origBeName
+.Ar newBeName
 .Nm
-{ ujail | unjail }
-.Ao Ar jailID | jailName Ac
-.Ao Ar bootenv Ac
+.Brq Cm ujail | unjail
+.Brq Ar jailID | jailName
+.Ar bootenv
 .Nm
-{ umount | unmount }
+.Brq Cm umount | unmount
 .Op Fl f
-.Ao Ar beName Ac
+.Ar beName
 .Sh DESCRIPTION
 The
 .Nm
-command is used to setup and interact with ZFS boot environments, which are bootable clones of datasets.
+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 a separate ZFS dataset.
+allows the system to be upgraded, while preserving the old system environment in
+a separate ZFS dataset.
 .Sh COMMANDS
 The following commands are supported by
 .Nm :
 .Bl -tag -width activate
-.It Ic activate
+.It Xo
+.Cm activate
 .Op Fl t
-.Ar <beName>
-.Pp
+.Ar beName
+.Xc
 Activate the given
 .Ar beName
 as the default boot filesystem.
 If the
 .Op Fl t
 flag is given, this takes effect only for the next boot.
-.It Ic create
+.It Xo
+.Cm create
 .Op Fl r
-.Op Fl e Ar nonActiveBe | Fl e Ar beName at snapshot
-.Ao Ar beName Ac
-.Pp
+.Op Fl e Brq Ar nonActiveBe | beName at snapshot
+.Ar beName
+.Xc
 Creates a new boot environment named
 .Ar beName .
-If the -e param is specified, the new environment will be cloned from the given
-.Ar nonActiveBe | Ar beName at snapshot .
 If the
-.Op Fl r
+.Fl e
+argument is specified, the new environment will be cloned from the given
+.Brq Ar nonActiveBe | Ar beName at snapshot .
+If the
+.Fl r
 flag is given, a recursive boot environment will be made.
-.It Ic create
+.It Xo
+.Cm create
 .Op Fl r
-.Ao Ar beName at snapshot Ac
-.Pp
+.Ar beName at snapshot
+.Xc
 Creates a snapshot of the existing boot environment named
 .Ar beName .
 If the
-.Op Fl r
+.Fl r
 flag is given, a recursive boot environment will be made.
-.It Ic destroy
+.It Xo
+.Cm destroy
 .Op Fl F
-.Ao Ar beName | beName at snapshot Ac
-.Pp
+.Brq Ar beName | beName at snapshot
+.Xc
 Destroys the given
 .Ar beName
 boot environment or
@@ -131,29 +136,26 @@ snapshot.
 Specifying
 .Fl F
 will automatically unmount without confirmation.
-.It Ic export
-.Ao Ar sourceBe Ac
-.Pp
+.It Cm export Ar sourceBe
 Export
 .Ar sourceBe
 to
 .Dv stdout .
 .Dv stdout
 must be piped or redirected to a file.
-.It Ic import
-.Ao Ar targetBe Ac
-.Pp
+.It Cm import Ar targetBe
 Import
 .Ar targetBe
 from
 .Dv stdin .
-.It Ic jail
-.Op Fl b | Fl U
-.Oo Fl o Ar key Ns = Ns Ar value | Fl u Ar key Oc Ns ...
-.Ao Ar jailID | jailName Ac
+.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 ...
+.Brq Ar jailID | jailName
 .Ao Ar bootenv Ac
 .Op Ar utility Op Ar argument ...
-.Pp
+.Xc
 Creates a jail of the given boot environment.
 Multiple
 .Fl o
@@ -196,66 +198,58 @@ below, if they have been overwritten by
 .Fl o .
 .Pp
 All
-.Ar key ,
-.Ar value
+.Ar key Ns = Ns Ar value
 pairs are interpreted as jail parameters as described in
 .Xr jail 8 .
 The following default parameters are provided:
-.Bl -tag -width -indent
-.It Va allow.mount Ns = Ns Ar true
-.It Va allow.mount.devfs Ns = Ns Ar true
-.It Va enforce_statfs Ns = Ns Ar 1
-.It Va name Ns = Ns Ar bootenv
-.It Va host.hostname Ns = Ns Ar bootenv
-.It Va path
-Set to a path in /tmp generated by
+.Bl -column "allow.mount.devfs" ""
+.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 Va bootenv
+.It Va host.hostname Ta Va bootenv
+.It Va path Ta Set to a path in /tmp generated by
 .Xr libbe 3 .
 .El
 .Pp
 All default parameters may be overwritten.
-.It Ic list
-.Op Fl a
-.Op Fl D
-.Op Fl H
-.Op Fl s
-.Pp
+.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).
+The Active field indicates whether the boot environment is active now (N);
+active on reboot (R); or both (NR).
 .Pp
 If
 .Fl a
 is used, display all datasets.
 If
 .Fl D
-is used, display the full space usage for each boot environment, assuming all other boot environments were destroyed.
+is used, display the full space usage for each boot environment, assuming all
+other boot environments were destroyed.
 The
 .Fl H
 option is used for scripting.
-It does not print headers and separate fields by a single tab instead of arbitrary white space.
+It does not print headers and separate fields by a single tab instead of
+arbitrary white space.
 If
 .Fl s
 is used, display all snapshots as well.
-.It Ic mount
-.Ao Ar beName Ac
-.Op mountpoint
-.Pp
+.It Cm mount Ar beName Op Ar mountpoint
 Temporarily mount the boot environment.
 Mount at the specified
 .Ar mountpoint
 if provided.
-.It Ic rename Ao Ar origBeName Ac Ao Ar newBeName Ac
-.Pp
+.It Cm rename Ar origBeName newBeName
 Renames the given nonactive
 .Ar origBeName
 to the given
-.Ar newBeName
-.It Ic unjail Ao Ar jailID | jailName | beName Ac
-.Pp
+.Ar newBeName .
+.It Cm unjail Brq Ar jailID | jailName | beName
 Destroys the jail created from the given boot environment.
-.It Ic unmount
+.It Xo
+.Cm unmount
 .Op Fl f
-.Ao Ar beName Ac
-.Pp
+.Ar beName
+.Xc
 Unmount the given boot environment, if it is mounted.
 Specifying
 .Fl f
@@ -273,25 +267,19 @@ To fill in with jail upgrade example when behavior is 
 .Sh HISTORY
 .Nm
 is based on
-.Xr beadm 1
+.Nm beadm
 and was implemented as a project for the 2017 Summer of Code, along with
 .Xr libbe 3 .
 .Sh AUTHORS
-.Bl -bullet
-.It
-.An Kyle Kneitinger (kneitinger) Aq Mt kyle at kneit.in
+.Nm
+was written by
+.An Kyle Kneitinger (kneitinger) Aq Mt kyle at kneit.in .
 .Pp
-Creator of
-.Nm .
-.It
-.An Slawomir Wojciech Wojtczak (vermaden) Aq Mt vermaden at interia.pl
+.Nm beadm
+was written and is maintained by
+.An Slawomir Wojciech Wojtczak (vermaden) Aq Mt vermaden at interia.pl .
 .Pp
-Creator and maintainer of
-.Xr beadm 1 .
-.It
 .An Bryan Drewery (bdrewery) Aq Mt bryan at shatow.net
-.Pp
-Wrote the original
-.Xr beadm 1
+wrote the original
+.Nm beadm
 manual page that this one is derived from.
-.El

Modified: head/sbin/bectl/bectl.c
==============================================================================
--- head/sbin/bectl/bectl.c	Thu Aug 23 01:45:18 2018	(r338221)
+++ head/sbin/bectl/bectl.c	Thu Aug 23 02:09:52 2018	(r338222)
@@ -67,22 +67,22 @@ usage(bool explicit)
 
 	fp =  explicit ? stdout : stderr;
 	fprintf(fp,
-	    "usage:\tbectl ( -h | -? | subcommand [args...] )\n"
+	    "usage:\tbectl {-h | -? | subcommand [args...]}\n"
 	    "\tbectl activate [-t] beName\n"
-	    "\tbectl create [-e nonActiveBe | -e beName at snapshot] beName\n"
+	    "\tbectl create [-e {nonActiveBe | -e beName at snapshot}] beName\n"
 	    "\tbectl create beName at snapshot\n"
-	    "\tbectl destroy [-F] beName | beName at snapshot⟩\n"
+	    "\tbectl destroy [-F] {beName | beName at snapshot}\n"
 	    "\tbectl export sourceBe\n"
 	    "\tbectl import targetBe\n"
 #if SOON
 	    "\tbectl add (path)*\n"
 #endif
-	    "\tbectl jail [-b | -U] [ -o key=value | -u key ]... bootenv [utility [argument ...]]\n"
+	    "\tbectl jail [{-b | -U}] [{-o key=value | -u key}]... bootenv [utility [argument ...]]\n"
 	    "\tbectl list [-a] [-D] [-H] [-s]\n"
 	    "\tbectl mount beName [mountpoint]\n"
 	    "\tbectl rename origBeName newBeName\n"
-	    "\tbectl { ujail | unjail } ⟨jailID | jailName | bootenv)\n"
-	    "\tbectl { umount | unmount } [-f] beName\n");
+	    "\tbectl {ujail | unjail} ⟨jailID | jailName | bootenv)\n"
+	    "\tbectl {umount | unmount} [-f] beName\n");
 
 	return (explicit ? 0 : EX_USAGE);
 }
