Try to make sysctl options slightly more orthogonal:

 - introduce a -o option that displays opaque variables.
 - introduce a -x option that displays opaque variables in full.
 - deprecate -A in favor of -ao and -X in favor of -ax.
 - remove -A and -X from usage() and SYNOPSIS (but not from DESCRIPTION).
 - ignore -a if one or more variables were listed on the command line.
 - deprecate -w, it is not needed to determine the user's intentions.
 - some language and style cleanup in the man page.

This commit should not break any existing scripts.

MFC after:	4 weeks

1 files changed, 45 insertions, 41 deletions

diff --git a/sbin/sysctl/sysctl.8 b/sbin/sysctl/sysctl.8
index 9868eba..c5ca4b7 100644
--- a/sbin/sysctl/sysctl.8
+++ b/sbin/sysctl/sysctl.8
@@ -40,64 +40,68 @@
 .Nd get or set kernel state
 .Sh SYNOPSIS
 .Nm
-.Op Fl bNn
-.Ar name ...
+.Op Fl bNnox
+.Ar name Ns Op = Ns Ar value
+.Ar ...
 .Nm
-.Op Fl bNn
-.Fl w
-.Ar name Ns = Ns Ar value ...
-.Nm
-.Op Fl bNn
-.Fl aAX
+.Op Fl bNnox
+.Fl a
 .Sh DESCRIPTION
 The
 .Nm
-utility retrieves kernel state and allows processes with
-appropriate privilege to set kernel state.
-The state to be retrieved or set is described using a
-``Management Information Base'' (``MIB'') style name,
-described as a dotted set of components.
+utility retrieves kernel state and allows processes with appropriate
+privilege to set kernel state.
+The state to be retrieved or set is described using a ``Management
+Information Base'' (``MIB'') style name, described as a dotted set of
+components.
 .Pp
 The following options are available:
 .Bl -tag -width indent
-.It Fl a
-List all the currently available string or integer values.
 .It Fl A
-List all the known MIB names including opaques.
-Those with string or integer values will be printed as with the
+Equivalent to
+.Fl o
 .Fl a
-flag; for the opaque values,
-information about the format and the length is printed in addition the first
-few bytes is dumped in hex.
-.It Fl X 
-Same as
-.Fl A
-except the entire value of opaque variables is hexdumped.
+(for compatibility).
+.It Fl a
+List all the currently available non-opaque values.
+This option is ignored if one or more variable names are specified on
+the command line.
 .It Fl N
 Show only variable names, not their values.
+This is particularly useful with shells that offer programmable
+completion.
+To enable completion of variable names in
+.Nm zsh ,
+use the following code:
+.Bd -literal -offset indent -compact
+listsysctls () { set -A reply $(sysctl -AN ${1%.*}) }
+compctl -K listsysctls sysctl
+.Ed
 .It Fl n
-Specify that the printing of the field name should be
-suppressed and that only its value should be output.
-This flag is useful for setting shell variables.
-For example, to save the pagesize in variable psize, use:
+Show only variable values, not their names.
+This option is useful for setting shell variables.
+For instance, to save the pagesize in variable psize, use:
 .Bd -literal -offset indent -compact
 set psize=`sysctl -n hw.pagesize`
 .Ed
 .It Fl b
-Force the value of the variable(s) to be output in raw, binary
-format.  No names are printed and no terminating newlines are output.
+Force the value of the variable(s) to be output in raw, binary format.
+No names are printed and no terminating newlines are output.
 This is mostly useful with a single variable.
-.It Fl w Xo
-.Ar name Ns = Ns Ar value ...
-.Xc
-Set the MIB
-.Ar name
-to the new
-.Ar value .
-If just a MIB style
-.Ar name
-is given,
-the corresponding value is retrieved.
+.Fl o
+Show opaque variables (which are normally suppressed).
+The format and length are printed, as well as a hex dump of the first
+sixteen bytes of the value.
+.It Fl X
+Equivalent to
+.Fl x
+.Fl a
+(for compatibility).
+.It Fl x
+As
+.Fl o ,
+but prints a hex dump of the entire value instead of just the first
+few bytes.
 .El
 .Pp
 The information available from