* doc/tar.texi: Update Back-Cover text to reflect new GNU wording.

[chaz/tar] / doc / tar.texi

diff --git a/doc/tar.texi b/doc/tar.texi
index 1084e47696f2dbb93508a914eba38510073558a5..1eb2fc2d1b671200677290c89c5f6039f0a0dfd6 100644 (file)
--- a/doc/tar.texi
+++ b/doc/tar.texi
@@ -45,9 +45,9 @@ Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
 and with the Back-Cover Texts as in (a) below.  A copy of the license
 is included in the section entitled "GNU Free Documentation License".
 
-(a) The FSF's Back-Cover Text is: ``You are free to copy and modify
-this GNU Manual.  Buying copies from GNU Press supports the FSF in
-developing GNU and promoting software freedom.''
+(a) The FSF's Back-Cover Text is: ``You have the freedom to
+copy and modify this GNU manual.  Buying copies from the FSF
+supports it in developing GNU and promoting software freedom.''
 @end quotation
 @end copying
 
@@ -2460,6 +2460,13 @@ for a complete description.
 The @var{action} argument can be one of the following:
 
 @table @asis
+@item bell
+Produce an audible bell on the console.
+
+@item dot
+@itemx .
+Print a single dot on the standard listing stream.
+
 @item echo
 Display a textual message on the standard error, with the status and
 number of the checkpoint.  This is the default.
@@ -2468,20 +2475,19 @@ number of the checkpoint.  This is the default.
 Display @var{string} on the standard error.  Before output, the string
 is subject to meta-character expansion.
 
-@item dot
-@itemx .
-Print a single dot on the standard listing stream.
+@item exec=@var{command}
+Execute the given @var{command}.
 
 @item sleep=@var{time}
 Wait for @var{time} seconds.
 
-@item exec=@var{command}
-Execute the given @var{command}.
+@item ttyout=@var{string}
+Output @var{string} on the current console (@file{/dev/tty}).
 @end table
 
 Several @option{--checkpoint-action} options can be specified.  The
 supplied actions will be executed in order of their appearance in the
-command line. 
+command line.
 
 Using @option{--checkpoint-action} without @option{--checkpoint}
 assumes default checkpoint frequency of one checkpoint per 10 records.
@@ -2587,7 +2593,7 @@ named @var{file}, but dump the directory node itself.  @xref{exclude}.
 @item --exclude-tag-all=@var{file}
 
 Exclude from dump any directory containing file named @var{file}.
-@xref{exclude}. 
+@xref{exclude}.
 
 @opsummary{exclude-vcs}
 @item --exclude-vcs
@@ -3805,6 +3811,26 @@ audible bell and the message described above at each checkpoint:
 --checkpoint-action='echo=\aHit %s checkpoint #%u'
 @end smallexample
 
+@cindex @code{bell}, checkpoint action
+There is also a special action which produces an audible signal:
+@samp{bell}.  It is not equivalent to @samp{echo='\a'}, because
+@samp{bell} sends the bell directly to the console (@file{/dev/tty}),
+whereas @samp{echo='\a'} sends it to the standard error.
+
+@cindex @code{ttyout}, checkpoint action
+The @samp{ttyout=@var{string}} action outputs @var{string} to
+@file{/dev/tty}, so it can be used even if the standard output is
+redirected elsewhere.  The @var{string} is subject to the same
+modifications as with @samp{echo} action.  In contrast to the latter,
+@samp{ttyout} does not prepend @command{tar} executable name to the
+string, nor does it output a newline after it.  For example, the
+following action will print the checkpoint message at the same screen
+line, overwriting any previous message:
+
+@smallexample
+--checkpoint-action="ttyout=\rHit %s checkpoint #%u"
+@end smallexample
+
 @cindex @code{dot}, checkpoint action
 Another available checkpoint action is @samp{dot} (or @samp{.}).  It
 instructs @command{tar} to print a single dot on the standard listing
@@ -3822,7 +3848,7 @@ as shown in the previous section.
 @cindex @code{sleep}, checkpoint action
 Yet another action, @samp{sleep}, pauses @command{tar} for a specified
 amount of seconds.  The following example will stop for 30 seconds at each
-checkpoint: 
+checkpoint:
 
 @smallexample
 $ @kbd{tar -c --checkpoint=1000 --checkpoint-action=sleep=30}
@@ -3849,6 +3875,10 @@ additional arguments.  Its exit code is ignored.  It gets a copy of
 @item TAR_ARCHIVE
 The name of the archive @command{tar} is processing.
 
+@vrindex TAR_BLOCKING_FACTOR, checkpoint script environment
+@item TAR_BLOCKING_FACTOR
+Current blocking factor (@pxref{Blocking}.
+
 @vrindex TAR_CHECKPOINT, checkpoint script environment
 @item TAR_CHECKPOINT
 The checkpoint number.
@@ -3883,7 +3913,7 @@ This example also illustrates the fact that
 @option{--checkpoint-action} can be used without
 @option{--checkpoint}.  In this case, the default checkpoint frequency
 (at each 10th record) is assumed.
-       
+
 @node interactive
 @section Asking for Confirmation During Operations
 @cindex Interactive operation
@@ -8209,7 +8239,7 @@ $ @kbd{tar cfa archive.tar.lzma .}
 @end smallexample
 
 For a complete list of file name suffixes recognized by @GNUTAR{},
-@ref{auto-compress}. 
+@ref{auto-compress}.
 
 Reading compressed archive is even simpler: you don't need to specify
 any additional options as @GNUTAR{} recognizes its format
@@ -8958,7 +8988,7 @@ from @var{string} after making the following substitutions:
 result of the @command{dirname} utility on the translated file name.
 @item %f @tab  The name of the file with the directory information
 stripped, equivalent to the result of the @command{basename} utility
-on the translated file name. 
+on the translated file name.
 @item %p @tab  The process @acronym{ID} of the @command{tar} process.
 @item %% @tab  A @samp{%} character.
 @end multitable
@@ -10621,6 +10651,10 @@ environment variables:
 @item TAR_ARCHIVE
 The name of the archive @command{tar} is processing.
 
+@vrindex TAR_BLOCKING_FACTOR, info script environment variable
+@item TAR_BLOCKING_FACTOR
+Current blocking factor (@pxref{Blocking}.
+
 @vrindex TAR_VOLUME, info script environment variable
 @item TAR_VOLUME
 Ordinal number of the volume @command{tar} is about to start.