doc/man1/flux-kvs: Update namespace usage

Remove global --namespace option and document --namespace
option in the sub-commands that it is supported in.

doc/man1/flux-kvs.adoc

@@ -40,20 +40,12 @@ their parent in the overlay network.
 Different KVS namespaces can be created in which kvs values can be
 read from/written to.  By default, all KVS operations operate on the
 default KVS namespace "primary".  An alternate namespace can be
-specified via the '--namespace' option, or by setting the namespace in
-the environment variable FLUX_KVS_NAMESPACE.
+specified in most kvs commands via the '--namespace' option, or by
+setting the namespace in the environment variable FLUX_KVS_NAMESPACE.
 
 flux-kvs(1) runs a KVS 'COMMAND'.  The possible commands and their
 arguments are described below.
 
-COMMON OPTIONS
---------------
-*-N, --namespace*='name'::
-Specify a namespace to be used in all KVS commands.  A namespace
-specified via this option overrides a namespace set in the environment
-variable FLUX_KVS_NAMESPACE.  This does not override the namespace
-specified via a prefix to a key.
-
 COMMANDS
 --------
 *namespace-create* [-o owner] 'name' ['name...']::
@@ -67,80 +59,88 @@ Remove a kvs namespace.
 *namespace-list*::
 List all current namespaces and info on each namespace.
 
-*get* [-j|-r|-t] [-a treeobj] [-l] [-W] [-w] [-u] [-f] [-c count] 'key' ['key...']::
-Retrieve the value stored under 'key'.  If nothing has been stored under
-'key', display an error message.  If no options, value is displayed with
-a newline appended (if value length is nonzero).  If '-l', a 'key=' prefix is
-added. If '-j', value is interpreted as encoded JSON and formatted accordingly.
-If '-r', value is displayed without a newline.  If '-t', the RFC 11 object
-is displayed.  '-a treeobj' causes the lookup to be relative to an RFC 11
-snapshot reference.  If '-W' is specified and a key does not exist, wait until
-the key has been created.  If '-w', after the initial value, display the
-new value each time the key is written to until interrupted, or if '-c count'
-is specified, until 'count' values have been displayed.  If '-u' is
+*get* [-N ns] [-j|-r|-t] [-a treeobj] [-l] [-W] [-w] [-u] [-f] [-c count] 'key' ['key...']::
+Retrieve the value stored under 'key'.  If nothing has been stored
+under 'key', display an error message.  Specify an alternate namespace
+to retrieve 'key' from via '-N'.  If no options, value is displayed
+with a newline appended (if value length is nonzero).  If '-l', a
+'key=' prefix is added. If '-j', value is interpreted as encoded JSON
+and formatted accordingly.  If '-r', value is displayed without a
+newline.  If '-t', the RFC 11 object is displayed.  '-a treeobj'
+causes the lookup to be relative to an RFC 11 snapshot reference.  If
+'-W' is specified and a key does not exist, wait until the key has
+been created.  If '-w', after the initial value, display the new value
+each time the key is written to until interrupted, or if '-c count' is
+specified, until 'count' values have been displayed.  If '-u' is
 specified, only writes that change the key value will be displayed.
 By default, only a direct write to a key is monitored, which may miss
 several unique situations, such as the replacement of an entire parent
 directory.  The '-f' option can be specified to monitor for many of
 these special situations.
 
-
-*put* [-j|-r|-t] [-n] [-A] 'key=value' ['key=value...']::
-Store 'value' under 'key' and commit it.  If it already has a value,
-overwrite it.  If no options, value is stored directly.  If '-j', it is
-first encoded as JSON, then stored.  If '-r' or '-t', the value may optionally
-be read from standard input if specified as "-".  If '-r', the value may
-include embedded NULL bytes.  If '-t', value is stored as a RFC 11 object.
-'-n' prevents the commit from being merged with with other contemporaneous
-commits.  '-A' appends the value to a key instead of overwriting the value.
-Append is incompatible with the -j option.
-
-*ls* [-R] [-d] [-F] [-w COLS] [-1] ['key' ...]::
+*put* [-N ns] [-j|-r|-t] [-n] [-A] 'key=value' ['key=value...']::
+Store 'value' under 'key' and commit it.  Specify an alternate
+namespace to commit value(s) via '-N'.  If it already has a value,
+overwrite it.  If no options, value is stored directly.  If '-j', it
+is first encoded as JSON, then stored.  If '-r' or '-t', the value may
+optionally be read from standard input if specified as "-".  If '-r',
+the value may include embedded NULL bytes.  If '-t', value is stored
+as a RFC 11 object.  '-n' prevents the commit from being merged with
+with other contemporaneous commits.  '-A' appends the value to a key
+instead of overwriting the value.  Append is incompatible with the -j
+option.
+
+*ls* [-N ns] [-R] [-d] [-F] [-w COLS] [-1] ['key' ...]::
 Display directory referred to by _key_, or "." (root) if unspecified.
-Options are roughly equivalent to a subset of ls(1) options.
-'-R' lists directory recursively.  '-d' displays directory not its contents.
-'-F' classifies files with one character suffix (. is directory, @ is symlink).
-'-w COLS' sets the terminal width in characters.  '-1' causes output to be
-displayed in one column.
-
-*dir* [-R] [-d] [-w COLS] [-a treeobj] ['key']::
-Display all keys and their values under the directory 'key'.
-If 'key' does not exist or is not a directory, display an error message.
-If 'key' is not provided, "." (root of the namespace) is assumed.  If '-R'
-is specified, recursively display keys under subdirectories.  If '-d' is
+Specify an alternate namespace to display via '-N'.  Remaining options are
+roughly equivalent to a subset of ls(1) options.  '-R' lists directory
+recursively.  '-d' displays directory not its contents.  '-F'
+classifies files with one character suffix (. is directory, @ is
+symlink).  '-w COLS' sets the terminal width in characters.  '-1'
+causes output to be displayed in one column.
+
+*dir* [-N ns] [-R] [-d] [-w COLS] [-a treeobj] ['key']::
+Display all keys and their values under the directory 'key'.  Specify
+an alternate namespace to display via '-N'.  If 'key' does not exist
+or is not a directory, display an error message.  If 'key' is not
+provided, "." (root of the namespace) is assumed.  If '-R' is
+specified, recursively display keys under subdirectories.  If '-d' is
 specified, do not output key values.  Output is truncated to fit the
-terminal width.  '-w COLS' sets the terminal width (0=unlimited).
-'-a treeobj' causes the lookup to be relative to an RFC 11 snapshot reference.
+terminal width.  '-w COLS' sets the terminal width (0=unlimited).  '-a
+treeobj' causes the lookup to be relative to an RFC 11 snapshot
+reference.
 
-*unlink* [-R] [-f] 'key' ['key...']::
-Remove 'key' from the KVS and commit the change.  If 'key' represents
-a directory, specify '-R' to remove all keys underneath it.  If '-f' is
-specified, ignore nonexistent files.
+*unlink* [-N ns] [-R] [-f] 'key' ['key...']::
+Remove 'key' from the KVS and commit the change.  Specify an alternate
+namespace to commit to via '-N'.  If 'key' represents a directory,
+specify '-R' to remove all keys underneath it.  If '-f' is specified,
+ignore nonexistent files.
 
-*link* [-T ns] 'target' 'linkname'::
+*link* [-N ns] [-T ns] 'target' 'linkname'::
 Create a new name for 'target', similar to a symbolic link, and commit
 the change.  'target' does not have to exist.  If 'linkname' exists,
-it is overwritten.  Optionally, specify a namespace the target is in.
-This namespace can be different that the one the linkname is being
-written to.
+it is overwritten.  Specify an alternate namespace to commit linkname
+to via '-N'.  Specify the target's namespace via '-T'.
 
-*readlink* [-a treeobj] [ -o | -k ] 'key' ['key...']::
+*readlink* [-N ns] [-a treeobj] [ -o | -k ] 'key' ['key...']::
 Retrieve the key a link refers to rather than its value, as would be
-returned by *get*.  '-a treeobj' causes the lookup to be relative to
-an RFC 11 snapshot reference.  If the link points to a namespace, the
-namespace and key will be output in the format '<namespace>::<key>'.
-The '-o' can be used to only output namespaces and the '-k' can be
-used to only output keys.
-
-*mkdir* 'key' ['key...']::
+returned by *get*.  Specify an alternate namespace to retrieve from
+via '-N'.  '-a treeobj' causes the lookup to be relative to an RFC 11
+snapshot reference.  If the link points to a namespace, the namespace
+and key will be output in the format '<namespace>::<key>'.  The '-o'
+can be used to only output namespaces and the '-k' can be used to only
+output keys.
+
+*mkdir* [-N ns] 'key' ['key...']::
 Create an empty directory and commit the change.  If 'key' exists,
-it is overwritten.
+it is overwritten.  Specify an alternate namespace to commit to via
+'-N'.
 
 *copy* [-S src-ns] [-D dst-ns] 'source' 'destination'::
 Copy 'source' key to 'destination' key.  Optionally, specify a source
-and/or destination namespace to override the one specified via 'N'.
-If a directory is copied, a new reference is created; it is
-unnecessary for *copy* to recurse into 'source'.
+and/or destination namespace for the 'source' and/or 'destination'
+respectively.  If a directory is copied, a new reference is created;
+it is unnecessary for *copy* to recurse into 'source'.
 
 *move* [-S src-ns] [-D dst-ns] 'source' 'destination'::
 Like *copy*, but 'source' is unlinked after the copy.
@@ -150,24 +150,26 @@ Tell the local KVS to drop any cache it is holding.  If '--all' is
 specified, send an event across the comms session instructing all KVS
 instances to drop their caches.
 
-*version*::
+*version* [-N ns]::
 Display the current KVS version, an integer value.  The version starts
 at zero and is incremented on each KVS commit.  Note that some commits
 may be aggregated for performance and the version will be incremented
 once for the aggregation, so it cannot be used as a direct count of
-commit requests.
+commit requests.  Specify an alternate namespace to retrieve the
+version from via '-N'.
 
-*wait* 'version'::
+*wait* [-N ns] 'version'::
 Block until the KVS version reaches 'version' or greater.  A simple form
 of synchronization between peers is:  node A puts a value, commits it,
 reads version, sends version to node B.  Node B waits for version, gets
 value.
 
-*getroot* [-s | -o | -b]::
+*getroot* [-N ns] [-s | -o | -b]::
 Retrieve the current KVS root, displaying it as an RFC 11 dirref object.
-If '-b' is specified, display it as a blobref.  If '-o' is specified,
-display the namespace owner.  If '-s' is specified, display the root
-sequence number.
+Specify an alternate namespace to retrieve from via '-N'.  If '-b' is
+specified, display it as a blobref.  If '-o' is specified, display the
+namespace owner.  If '-s' is specified, display the root sequence
+number.
 
 *eventlog get* [-w] [-c count] [-u] 'key'::
 Display the contents of an RFC 18 KVS eventlog referred to by 'key'.