btrfs-progs: docs: update receive help and manual page

Reword several option descriptions, add missing short option -E,
formatting adjustments.

Visual bug fix: the first line is printed in short help, the second line
is long description, thus alternative calling syntax must be printed on
one line.

Signed-off-by: David Sterba <dsterba@suse.com>

diff --git a/Documentation/btrfs-receive.asciidoc b/Documentation/btrfs-receive.asciidoc
index f12e949..a6838e5 100644 (file)
--- a/Documentation/btrfs-receive.asciidoc
+++ b/Documentation/btrfs-receive.asciidoc
@@ -17,31 +17,29 @@ DESCRIPTION
 -----------
 
 Receive a stream of changes and replicate one or more subvolumes that were
-previously used with *btrfs send* The received subvolumes are stored to
-'path', if '--dump' option is not given.
+previously generated by *btrfs send*. The received subvolumes are stored to
+'path', unless '--dump' option is given.
 
-If '--dump' option is given, *btrfs receive* will only do the validation of
-the stream, and print the stream metadata.
+If '--dump' option is specified, *btrfs receive* will only do the validation of
+the stream, and print the stream metadata, one operation per line.
 
 *btrfs receive* will fail int the following cases:
 
 1. receiving subvolume already exists
 
-2. previously received subvolume was changed after it was received
+2. previously received subvolume has been changed after it was received
 
-3. default subvolume has changed or you didn't mount BTRFS filesystem at the toplevel subvolume
+3. default subvolume has changed or you didn't mount the filesystem at the toplevel subvolume
 
 A subvolume is made read-only after the receiving process finishes succesfully.
 
 `Options`
 
 -v::
-enable verbose debug output, print each operation (each occurrence of this
-option increases the verbosity level)
+increase verbosity about performed actions, print details about each operation
 
--f <infile>::
-by default, btrfs receive uses standard input to receive the stream,
-use this option to read from a file instead
+-f <FILE>::
+read the stream from <FILE> instead of stdin,
 
 -C|--chroot::
 confine the process to 'path' using `chroot`(1)
@@ -49,25 +47,26 @@ confine the process to 'path' using `chroot`(1)
 -e::
 terminate after receiving an 'end cmd' marker in the stream.
 +
-Without this option, the receiver terminates only if an error is encountered
-or at end of file
+Without this option the receiver side terminates only in case
+of an error on end of file.
 
---max-errors <N>::
-terminate as soon as N errors happened while processing commands from the send
-stream, default value is 1, 0 means no limit
+-E|--max-errors <NERR>::
+terminate as soon as NERR errors occur while stream processing commands from
+the stream
++
+Default value is 1. A value of 0 means no limit.
 
--m <mountpoint>::
+-m <ROOTMOUNT>::
 the root mount point of the destination filesystem
 +
 By default the mountpoint is searched in '/proc/self/mounts'.
-If you do not have '/proc', eg. in a chroot environment, use this option to tell
-us where this filesystem is mounted.
+If '/proc' is not accessible, eg. in a chroot environment, use this option to
+tell us where this filesystem is mounted.
 
 --dump::
-print the stream metadata
+dump the stream metadata, one line per operation
 +
-Does not accept the 'path' parameter. So with this option, *btrfs receive* won't
-modify your filesystem, and can be run by non-privileged users.
+Does not require the 'path' parameter. The filesystem chanded.
 
 EXIT STATUS
 -----------

diff --git a/cmds-receive.c b/cmds-receive.c
index 68950b4..6f54c2e 100644 (file)
--- a/cmds-receive.c
+++ b/cmds-receive.c
@@ -1330,36 +1330,32 @@ out:
 }
 
 const char * const cmd_receive_usage[] = {
-       "btrfs receive [options] <mount>",
-       "or",
+       "btrfs receive [options] <mount>\n"
        "btrfs receive --dump [options]",
-       "Receive subvolumes from stdin.",
+       "Receive subvolumes from a stream",
        "Receives one or more subvolumes that were previously",
        "sent with btrfs send. The received subvolumes are stored",
-       "into <mount>.",
-       "btrfs receive will fail in case a receiving subvolume",
+       "into MOUNT.",
+       "The receive will fail in case the receiving subvolume",
        "already exists. It will also fail in case a previously",
-       "received subvolume was changed after it was received.",
+       "received subvolume has been changed after it was received.",
        "After receiving a subvolume, it is immediately set to",
-       "read only.\n",
-       "-v               Enable verbose debug output. Each",
-       "                 occurrence of this option increases the",
-       "                 verbose level more.",
-       "-f <infile>      By default, btrfs receive uses stdin",
-       "                 to receive the subvolumes. Use this",
-       "                 option to specify a file to use instead.",
-       "-e               Terminate after receiving an <end cmd>",
-       "                 in the data stream. Without this option,",
-       "                 the receiver terminates only if an error",
-       "                 is recognized or on EOF.",
+       "read-only.",
+       "",
+       "-v               increase verbosity about performed actions",
+       "-f FILE          read the stream from FILE instead of stdin",
+       "-e               terminate after receiving an <end cmd> marker in the stream.",
+       "                 Without this option the receiver side terminates only in case",
+       "                 of an error on end of file.",
        "-C|--chroot      confine the process to <mount> using chroot",
-       "--max-errors <N> Terminate as soon as N errors happened while",
-       "                 processing commands from the send stream.",
+       "-E|--max-errors NERR",
+       "                 terminate as soon as NERR errors occur while",
+       "                 stream processing commands from the stream.",
        "                 Default value is 1. A value of 0 means no limit.",
-       "-m <mountpoint>  The root mount point of the destination fs.",
-       "                 If you do not have /proc use this to tell us where ",
+       "-m ROOTMOUNT     the root mount point of the destination filesystem.",
+       "                 If /proc is not accessible, use this to tell us where",
        "                 this file system is mounted.",
-       "--dump           Exam and output metadata info of send stream.",
-       "                 Don't need <mount> parameter.",
+       "--dump           dump stream metadata, one line per operation,",
+       "                 does not require the MOUNT parameter",
        NULL
 };