Document pass-through behavior (#3242)

Adds documentation to help and man pages for legacy pass-through behavior
when force is set and destination is stdout. Documents --pass-through in
man pages

diff --git a/programs/zstd.1 b/programs/zstd.1
index 3ac7f0f3c369ad91b4a1f27fe8c8235af5923df6..a2bf7fd2f50f6d6ddaf7da85399c23f5e223195b 100644 (file)
--- a/programs/zstd.1
+++ b/programs/zstd.1
@@ -1,5 +1,5 @@
 .
-.TH "ZSTD" "1" "June 2022" "zstd 1.5.3" "User Commands"
+.TH "ZSTD" "1" "August 2022" "zstd 1.5.3" "User Commands"
 .
 .SH "NAME"
 \fBzstd\fR \- zstd, zstdmt, unzstd, zstdcat \- Compress or decompress \.zst files
@@ -162,7 +162,7 @@ Additionally, this can be used to limit memory for dictionary training\. This pa
 \fB\-o FILE\fR: save result into \fBFILE\fR
 .
 .IP "\(bu" 4
-\fB\-f\fR, \fB\-\-force\fR: disable input and output checks\. Allows overwriting existing files, input from console, output to stdout, operating on links, block devices, etc\.
+\fB\-f\fR, \fB\-\-force\fR: disable input and output checks\. Allows overwriting existing files, input from console, output to stdout, operating on links, block devices, etc\. During decompression and when the output destination is stdout, pass\-through unrecognized formats as\-is\.
 .
 .IP "\(bu" 4
 \fB\-c\fR, \fB\-\-stdout\fR: write to standard output (even if it is the console); keep original files unchanged\.
@@ -171,6 +171,9 @@ Additionally, this can be used to limit memory for dictionary training\. This pa
 \fB\-\-[no\-]sparse\fR: enable / disable sparse FS support, to make files with many zeroes smaller on disk\. Creating sparse files may save disk space and speed up decompression by reducing the amount of disk I/O\. default: enabled when output is into a file, and disabled when output is stdout\. This setting overrides default and can force sparse mode over stdout\.
 .
 .IP "\(bu" 4
+\fB\-\-[no\-]pass\-through\fR enable / disable passing through uncompressed files as\-is\. During decompression when pass\-through is enabled, unrecognized formats will be copied as\-is from the input to the output\. By default, pass\-through will occur when the output destination is stdout and the force (\-f) option is set\.
+.
+.IP "\(bu" 4
 \fB\-\-rm\fR: remove source file(s) after successful compression or decompression\. If used in combination with \-o, will trigger a confirmation prompt (which can be silenced with \-f), as this is a destructive operation\.
 .
 .IP "\(bu" 4

diff --git a/programs/zstd.1.md b/programs/zstd.1.md
index af18586ab20e9b37fb2a8d76f047c70a7125fb34..3ab8404ee65f86199f85fc2b67c742ac5853f869 100644 (file)
--- a/programs/zstd.1.md
+++ b/programs/zstd.1.md
@@ -211,6 +211,8 @@ the last one takes effect.
 * `-f`, `--force`:
     disable input and output checks. Allows overwriting existing files, input
     from console, output to stdout, operating on links, block devices, etc.
+    During decompression and when the output destination is stdout, pass-through
+    unrecognized formats as-is.
 * `-c`, `--stdout`:
     write to standard output (even if it is the console); keep original files unchanged.
 * `--[no-]sparse`:
@@ -221,6 +223,12 @@ the last one takes effect.
     default: enabled when output is into a file,
     and disabled when output is stdout.
     This setting overrides default and can force sparse mode over stdout.
+* `--[no-]pass-through`
+    enable / disable passing through uncompressed files as-is. During
+    decompression when pass-through is enabled, unrecognized formats will be
+    copied as-is from the input to the output. By default, pass-through will
+    occur when the output destination is stdout and the force (-f) option is
+    set.
 * `--rm`:
     remove source file(s) after successful compression or decompression. If used in combination with
     -o, will trigger a confirmation prompt (which can be silenced with -f), as this is a destructive operation.

diff --git a/programs/zstdcli.c b/programs/zstdcli.c
index 47ef388fe652f5931bedad31790a8dc0f955addd..e93d192060f3573e44325942b0fbc518b0b7756a 100644 (file)
--- a/programs/zstdcli.c
+++ b/programs/zstdcli.c
@@ -154,7 +154,8 @@ static void usage(FILE* f, const char* programName)
 #endif
     DISPLAY_F(f, "  -f, --force          disable input and output checks. Allows overwriting existing files,\n");
     DISPLAY_F(f, "                       input from console, output to stdout, operating on links,\n");
-    DISPLAY_F(f, "                       block devices, etc.\n");
+    DISPLAY_F(f, "                       block devices, etc. During decompression and when the output\n");
+    DISPLAY_F(f, "                       destination is stdout, pass-through unrecognized formats as-is.\n");
     DISPLAY_F(f, "      --rm             remove source file(s) after successful de/compression\n");
     DISPLAY_F(f, "  -k, --keep           preserve source file(s) (default) \n");
 #ifdef ZSTD_GZCOMPRESS
@@ -271,7 +272,7 @@ static void usage_advanced(const char* programName)
             exeNameMatch(programName, ZSTD_GZCAT)) {
             passThroughDefault = "enabled";
         }
-        DISPLAYOUT("     --[no-]pass-through : passes through uncompressed files as-is (default: %s\n)", passThroughDefault);
+        DISPLAYOUT("     --[no-]pass-through : passes through uncompressed files as-is (default: %s)\n", passThroughDefault);
     }
 #endif  /* ZSTD_NODECOMPRESS */
 

diff --git a/programs/zstdgrep.1 b/programs/zstdgrep.1
index 4ece2ae50113602c01986ddbe09f073d7742054a..8c7cf5edaae47eb2ddaca107eb04342b7013095a 100644 (file)
--- a/programs/zstdgrep.1
+++ b/programs/zstdgrep.1
@@ -1,17 +1,26 @@
-.TH "ZSTDGREP" "1" "April 2022" "zstd 1.5.2" "User Commands"
+.
+.TH "ZSTDGREP" "1" "August 2022" "zstd 1.5.3" "User Commands"
+.
 .SH "NAME"
 \fBzstdgrep\fR \- print lines matching a pattern in zstandard\-compressed files
+.
 .SH "SYNOPSIS"
-\fBzstdgrep\fR [\fIgrep\-flags\fR] [\-\-] \fIpattern\fR [\fIfiles\fR \|\.\|\.\|\.]
+\fBzstdgrep\fR [\fIgrep\-flags\fR] [\-\-] \fIpattern\fR [\fIfiles\fR \.\.\.]
+.
 .SH "DESCRIPTION"
 \fBzstdgrep\fR runs \fBgrep (1)\fR on files, or \fBstdin\fR if no files argument is given, after decompressing them with \fBzstdcat (1)\fR\.
+.
 .P
 The grep\-flags and pattern arguments are passed on to \fBgrep (1)\fR\. If an \fB\-e\fR flag is found in the \fBgrep\-flags\fR, \fBzstdgrep\fR will not look for a pattern argument\.
+.
 .P
 Note that modern \fBgrep\fR alternatives such as \fBripgrep\fR (\fBrg\fR) support \fBzstd\fR\-compressed files out of the box, and can prove better alternatives than \fBzstdgrep\fR notably for unsupported complex pattern searches\. Note though that such alternatives may also feature some minor command line differences\.
+.
 .SH "EXIT STATUS"
 In case of missing arguments or missing pattern, 1 will be returned, otherwise 0\.
+.
 .SH "SEE ALSO"
 \fBzstd (1)\fR
+.
 .SH "AUTHORS"
 Thomas Klausner \fIwiz@NetBSD\.org\fR

diff --git a/programs/zstdless.1 b/programs/zstdless.1
index 36f21494d080ad3c30a93548736c0b3cc576e149..a1414946e9b99fd69424a19fee17c5521728ad9d 100644 (file)
--- a/programs/zstdless.1
+++ b/programs/zstdless.1
@@ -1,9 +1,14 @@
-.TH "ZSTDLESS" "1" "April 2022" "zstd 1.5.2" "User Commands"
+.
+.TH "ZSTDLESS" "1" "August 2022" "zstd 1.5.3" "User Commands"
+.
 .SH "NAME"
 \fBzstdless\fR \- view zstandard\-compressed files
+.
 .SH "SYNOPSIS"
-\fBzstdless\fR [\fIflags\fR] [\fIfile\fR \|\.\|\.\|\.]
+\fBzstdless\fR [\fIflags\fR] [\fIfile\fR \.\.\.]
+.
 .SH "DESCRIPTION"
 \fBzstdless\fR runs \fBless (1)\fR on files or stdin, if no files argument is given, after decompressing them with \fBzstdcat (1)\fR\.
+.
 .SH "SEE ALSO"
 \fBzstd (1)\fR

diff --git a/tests/cli-tests/basic/help.sh.stdout.glob b/tests/cli-tests/basic/help.sh.stdout.glob
index be3f15400c7b29479306b9e631a06e610c64c1aa..bfb0f77533144f690dccf30beabcc053694d236e 100644 (file)
--- a/tests/cli-tests/basic/help.sh.stdout.glob
+++ b/tests/cli-tests/basic/help.sh.stdout.glob
@@ -7,7 +7,8 @@ Compress or uncompress FILEs (with no FILE or when FILE is `-`, read from standa
   -d, --decompress     decompression
   -f, --force          disable input and output checks. Allows overwriting existing files,
                        input from console, output to stdout, operating on links,
-                       block devices, etc.
+                       block devices, etc. During decompression and when the output
+                       destination is stdout, pass-through unrecognized formats as-is.
       --rm             remove source file(s) after successful de/compression
   -k, --keep           preserve source file(s) (default)
   -D DICT              use DICT as Dictionary for compression or decompression