[PATCH 3/3] doc: document split's new --filter=CMD option

[Jim Meyering]

From: Jim Meyering <address@hidden>

* doc/coreutils.texi (split invocation): Describe --filter=CMD.
* NEWS (New feature): Mention it.
---
 NEWS               |   10 ++++++++++
 doc/coreutils.texi |   23 +++++++++++++++++++++--
 2 files changed, 31 insertions(+), 2 deletions(-)

diff --git a/NEWS b/NEWS
index c90e02f..82ce53c 100644
--- a/NEWS
+++ b/NEWS
@@ -2,6 +2,16 @@ GNU coreutils NEWS                                    -*- 
outline -*-

 * Noteworthy changes in release ?.? (????-??-??) [?]

+** New features
+
+  split accepts a new --filter=CMD option.  With it, split filters output
+  through CMD.  CMD may use the $FILE environment variable, which is set to
+  the nominal output file name for each invocation of CMD.  For example, to
+  split a file into 3 approximately equal parts, which are then compressed:
+    split -n3 --filter='xz > $FILE.xz' big
+  Note the use of single quotes, not double quotes.
+  That creates files named xaa.xz, xab.xz and xac.xz.
+

 * Noteworthy changes in release 8.12 (2011-04-26) [stable]

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index d2377f4..457ecab 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -2992,8 +2992,8 @@ split invocation
 Put @var{lines} lines of @var{input} into each output file.

 For compatibility @command{split} also supports an obsolete
-option syntax @option{-@var{lines}}.  New scripts should use @option{-l
-@var{lines}} instead.
+option syntax @option{-@var{lines}}.  New scripts should use
+@option{-l @var{lines}} instead.

 @item -b @var{size}
 @itemx --bytes=@var{size}
@@ -3011,6 +3011,25 @@ split invocation
 @var{size} bytes are broken into multiple files.
 @var{size} has the same format as for the @option{--bytes} option.

+@itemx --filter=@var{command}
+@opindex --filter
+With this option, rather than simply writing to each output file,
+write through a pipe to the specified shell @var{command} for each output file.
+@var{command} should use the $FILE environment variable, which is set
+to a different output file name for each invocation of the command.
+For example, imagine that you have a 1TiB compressed file
+that, if uncompressed, would be too large to reside on disk,
+yet you must split it into individually-compressed pieces
+of a more manageable size.
+To do that, you might run this command:
+
+@example
+xz -dc BIG.xz | split -b200G --filter='xz > $FILE.xz' - big-
+@end example
+
+Assuming a 10:1 compression ratio, that would create about fifty 20GiB files
+with names @file{big-xaa.xz}, @file{big-xab.xz}, @file{big-xac.xz}, etc.
+
 @item -n @var{chunks}
 @itemx --number=@var{chunks}
 @opindex -n
-- 
1.7.5.141.g791a