Add example inspired by "make dist" running gzip and lzma in sequence.

* doc/coreutils.texi (tee invocation): Show how to run tar just
once, compressing the tee'd output streams in parallel.

diff --git a/ChangeLog b/ChangeLog
index e39c84e3c16de5a0bae7962bf32fc242a218c02c..01e322a56c1dba1ede55ebf512df50f54f6be1e1 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,9 @@
 2007-11-01  Jim Meyering  <meyering@redhat.com>
 
+       Add example inspired by "make dist" running gzip and lzma in sequence.
+       * doc/coreutils.texi (tee invocation): Show how to run tar just
+       once, compressing the tee'd output streams in parallel.
+
        Say that the first process substitution example is contrived.
        * doc/coreutils.texi (tee invocation): ... and show how to do
        it properly.  Pointed out by James Antill.

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 9c960a57e0be82eac2594bab6ef7ce781d913734..4c08378cef4c4702691cc5580941a3ae16520f22 100644 (file)
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -11136,6 +11136,32 @@ right away and eliminate the decompression completely:
 du -ak | tee >(gzip -9 > /tmp/du.gz) | xdiskusage -a
 @end example
 
+Finally, if you regularly create more than one type of
+compressed tarball at once, for example when @code{make dist} creates
+both @command{gzip}-compressed and @command{bzip2}-compressed tarballs,
+there may be a better way.
+Typical @command{automake}-generated @file{Makefile} rules create
+the two compressed tar archives with commands in sequence, like this
+(slightly simplified):
+
+@example
+tardir=your-pkg-M.N
+tar chof - "$tardir" | gzip  -9 -c > your-pkg-M.N.tar.gz
+tar chof - "$tardir" | bzip2 -9 -c > your-pkg-M.N.tar.bz2
+@end example
+
+However, if the hierarchy you are archiving and compressing is larger
+than a couple megabytes, and especially if you are using a multi-processor
+system with plenty of memory, then you can do much better by reading the
+directory contents only once and running the compression programs in parallel:
+
+@example
+tardir=your-pkg-M.N
+tar chof - "$tardir" \
+  | tee >(gzip -9 -c > your-pkg-M.N.tar.gz) \
+  | bzip2 -9 -c > your-pkg-M.N.tar.bz2
+@end example
+
 @exitstatus