docs: promote common CLI options

programs/README.md

@@ -101,7 +101,7 @@ CLI supports aggregation of parameters i.e. `-b1`, `-e18`, and `-i1` can be join
 ### Symlink shortcuts
 It's possible to invoke `zstd` through a symlink.
 When the name of the symlink has a specific value, it triggers an associated behavior.
-- `zstdmt` : compress using all cores available on local system.
+- `zstdmt` : equivalent to `zstd -T0`; prefer this form for multithreaded compression.
 - `zcat` : will decompress and output target file using any of the supported formats. `gzcat` and `zstdcat` are also equivalent.
 - `gzip` : if zlib support is enabled, will mimic `gzip` by compressing file using `.gz` format, removing source file by default (use `--keep` to preserve). If zlib is not supported, triggers an error.
 - `xz` : if lzma support is enabled, will mimic `xz` by compressing file using `.xz` format, removing source file by default (use `--keep` to preserve). If xz is not supported, triggers an error.
@@ -159,8 +159,10 @@ Usage: zstd [OPTIONS...] [INPUT... | -] [-o OUTPUT]
 
 Options:
   -o OUTPUT                     Write output to a single file, OUTPUT.
+  -c, --stdout                  Write to STDOUT (even if it is a console) and keep the INPUT file(s).
   -k, --keep                    Preserve INPUT file(s). [Default]
   --rm                          Remove INPUT file(s) after successful (de)compression to file.
+  -q, --quiet                   Suppress warnings; pass twice to suppress errors.
 
   -#                            Desired compression level, where `#` is a number between 1 and 19;
                                 lower numbers provide faster compression, higher numbers yield
@@ -179,10 +181,7 @@ Options:
   -V, --version                 Display the program version and exit.
 
 Advanced options:
-  -c, --stdout                  Write to STDOUT (even if it is a console) and keep the INPUT file(s).
-
   -v, --verbose                 Enable verbose output; pass multiple times to increase verbosity.
-  -q, --quiet                   Suppress warnings; pass twice to suppress errors.
   --trace LOG                   Log tracing information to LOG.
 
   --[no-]progress               Forcibly show/hide the progress counter. NOTE: Any (de)compressed

programs/zstd.1.md

@@ -6,7 +6,7 @@ SYNOPSIS
 
 `zstd` [<OPTIONS>] [-|<INPUT-FILE>] [-o <OUTPUT-FILE>]
 
-`zstdmt` is equivalent to `zstd -T0`
+`zstdmt` is equivalent to `zstd -T0`; prefer this form for multithreaded compression.
 
 `unzstd` is equivalent to `zstd -d`
 
@@ -114,6 +114,8 @@ the last one takes effect.
 * `--ultra`:
     unlocks high compression levels 20+ (maximum 22), using a lot more memory.
     Decompression will also need more memory when using these levels.
+    Data compressed at these levels may be rejected by third-party decoders
+    and is recommended primarily for archival purposes.
 * `--max`:
     set advanced parameters to reach maximum compression.
     warning: this setting is very slow and uses a lot of resources.
@@ -123,6 +125,7 @@ the last one takes effect.
     If `=#` is not present, it defaults to `1`.
     The higher the value, the faster the compression speed,
     at the cost of some compression ratio.
+    These are the negative compression levels exposed by the library.
     This setting overwrites compression level if one was set previously.
     Similarly, if a compression level is set after `--fast`, it overrides it.
 * `-T#`, `--threads=#`:

programs/zstdcli.c

@@ -152,6 +152,7 @@ static void usage(FILE* f, const char* programName)
     DISPLAY_F(f, "  -c, --stdout                  Write to STDOUT (even if it is a console) and keep the INPUT file(s).\n");
     DISPLAY_F(f, "  -k, --keep                    Preserve INPUT file(s). [Default] \n");
     DISPLAY_F(f, "  --rm                          Remove INPUT file(s) after successful (de)compression to file.\n");
+    DISPLAY_F(f, "  -q, --quiet                   Suppress warnings; pass twice to suppress errors.\n");
 #ifdef ZSTD_GZCOMPRESS
     if (exeNameMatch(programName, ZSTD_GZ)) {     /* behave like gzip */
         DISPLAY_F(f, "  -n, --no-name                 Do not store original filename when compressing.\n\n");
@@ -186,7 +187,6 @@ static void usageAdvanced(const char* programName)
     DISPLAYOUT("Advanced options:\n");
 
     DISPLAYOUT("  -v, --verbose                 Enable verbose output; pass multiple times to increase verbosity.\n");
-    DISPLAYOUT("  -q, --quiet                   Suppress warnings; pass twice to suppress errors.\n");
 #ifndef ZSTD_NOTRACE
     DISPLAYOUT("  --trace LOG                   Log tracing information to LOG.\n");
 #endif