aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJia Tan <jiat0218@gmail.com>2023-01-06 00:03:06 +0800
committerJia Tan <jiat0218@gmail.com>2023-07-17 23:34:55 +0800
commit5f3b898d07cc9b7160c7c88b3120b7edabb8a5b0 (patch)
treec1783485d8461d1d1b5440a5898ca8e8f4a5616d
parentxz: Add --filters option to CLI. (diff)
downloadxz-5f3b898d07cc9b7160c7c88b3120b7edabb8a5b0.tar.xz
xz: Update --long-help and man page for new --filters option.
-rw-r--r--src/xz/message.c6
-rw-r--r--src/xz/xz.141
2 files changed, 42 insertions, 5 deletions
diff --git a/src/xz/message.c b/src/xz/message.c
index c54ebc5b..b9fdc510 100644
--- a/src/xz/message.c
+++ b/src/xz/message.c
@@ -1057,6 +1057,12 @@ message_help(bool long_help)
puts(_(
"\n Custom filter chain for compression (alternative for using presets):"));
+ puts(_(
+"\n"
+" --filters=FILTERS set the filter chain using the liblzma filter string\n"
+" syntax; use --filters-help for more information"
+ ));
+
#if defined(HAVE_ENCODER_LZMA1) || defined(HAVE_DECODER_LZMA1) \
|| defined(HAVE_ENCODER_LZMA2) || defined(HAVE_DECODER_LZMA2)
// TRANSLATORS: The word "literal" in "literal context bits"
diff --git a/src/xz/xz.1 b/src/xz/xz.1
index aefb79f2..004add7a 100644
--- a/src/xz/xz.1
+++ b/src/xz/xz.1
@@ -1295,15 +1295,24 @@ in the chain.
Depending on the filter, this limitation is either inherent to
the filter design or exists to prevent security issues.
.PP
-A custom filter chain is specified by using one or more
-filter options in the order they are wanted in the filter chain.
-That is, the order of filter options is significant!
+A custom filter chain is specified in two different ways.
+The option
+.BI \-\-filters= filters
+allows specifying the entire filter chain in one option.
+Alternatively, filter chains can be specified by using one or more
+individual filter options in the order they are wanted in the filter chain.
+That is, the order of individual filter options is significant!
When decoding raw streams
.RB ( \-\-format=raw ),
-the filter chain is specified in the same order as
+the filter chain must be specified in the same order as
it was specified when compressing.
+Any individual filters or presets specified before the full chain option
+(\fB\-\-filters=\fIfilters\fR)
+will be forgotten.
+Individual filters specified after the full chain option will reset the
+filter chain.
.PP
-Filters take filter-specific
+Both the full and individual filter options take filter-specific
.I options
as a comma-separated list.
Extra commas in
@@ -1321,6 +1330,28 @@ use
twice).
This works also for viewing the filter chain options used by presets.
.TP
+\fB\-\-filters\fR\fB=\fIfilters\fR
+.PD
+Specify the full filter chain or a preset in a single option.
+Each filter can be separated by spaces or two dashes
+.RB ( \-\- ).
+.I filters
+may need to be quoted on the shell command line so it is
+parsed as a single option.
+To denote
+.IR options ,
+use
+.B :
+or
+.BR = .
+A preset can be prefixed with a
+.B \-
+and followed with zero or more flags.
+The only supported flag is
+.B e
+to apply the same options as
+.BR \-\-extreme .
+.TP
\fB\-\-lzma1\fR[\fB=\fIoptions\fR]
.PD 0
.TP