From 5f3b898d07cc9b7160c7c88b3120b7edabb8a5b0 Mon Sep 17 00:00:00 2001
From: Jia Tan <jiat0218@gmail.com>
Date: Fri, 6 Jan 2023 00:03:06 +0800
Subject: [PATCH] xz: Update --long-help and man page for new --filters option.

---
 src/xz/message.c |  6 ++++++
 src/xz/xz.1      | 41 ++++++++++++++++++++++++++++++++++++-----
 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