* NEWS: Document --no-check-device and --check-device.

* doc/rendition.texi: Change the way FIXME-*refs are handled in !PROOF. * doc/intern.texi, doc/tar.texi: Update. * doc/untabify.el: New file. * doc/Makefile.am (EXTRA_DIST): Add untabify.el (untabify, final, check-format, check-refs, check-fixmes) (check-unrevised, all-check-docs, check-docs): New rules.
2008-03-27 10:11:05 +00:00
parent 71d2a66f42
commit 2a89f7a0a8
7 changed files with 166 additions and 39 deletions
--- a/9
+++ b/9
@@ -1,5 +1,14 @@
 2008-03-27  Sergey Poznyakoff  <gray@gnu.org.ua>

+	* NEWS: Document --no-check-device and --check-device.
+	* doc/rendition.texi: Change the way FIXME-*refs are handled in
+	!PROOF. 
+	* doc/intern.texi, doc/tar.texi: Update.
+	* doc/untabify.el: New file.
+	* doc/Makefile.am (EXTRA_DIST): Add untabify.el
+	(untabify, final, check-format, check-refs, check-fixmes)
+	(check-unrevised, all-check-docs, check-docs): New rules.
+	
 	* src/common.h (check_device_option): New global.
 	* src/incremen.c (procdir): Use boolean and instead of bitwise
 	one. Patch by Jean-Louis Martineau.
--- a/14
+++ b/14
@@ -1,4 +1,4 @@
-GNU tar NEWS - User visible changes. 2008-02-08
+GNU tar NEWS - User visible changes. 2008-03-27
 Please send GNU tar bug reports to <bug-tar@gnu.org>


@@ -27,6 +27,18 @@ of `--checkpoint-action' options can be specified, the actions will be
 executed in order of their appearance in the command line.  See
 chapter 3.8 "Checkpoints" for a complete description.

+* New options --no-check-device, --check-device.
+
+The `--no-check-device' option disables comparing device numbers during
+preparatory stage of an incremental dump.  This allows to avoid
+creating full dumps if the device numbers change (e.g. when using an
+LVM snapshot).
+
+The `--check-device' option enables comparing device numbers.  This is
+the default.  This option is provided to undo the effect of the previous
+`--no-check-device' option, e.g. if it was set in TAR_OPTIONS
+environment variable.
+
 * The --transform option.

 Any number of `--transform' options can be given in the command line.
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -31,7 +31,7 @@ tar_TEXINFOS = \
 snapshot.texi\
 sparse.texi\
 value.texi
-EXTRA_DIST = gendocs_template mastermenu.el texify.sed
+EXTRA_DIST = gendocs_template mastermenu.el texify.sed untabify.el

 # The rendering level is anyone of PUBLISH, DISTRIB or PROOF.
 # Just call `make RENDITION=PROOF [target]' if you want PROOF rendition.
@@ -46,6 +46,18 @@ header.texi: $(top_srcdir)/src/tar.h
 master-menu: $(tar_TEXINFOS)
 	emacs -batch -l mastermenu.el -f make-master-menu $(info_TEXINFOS)

+untabify:
+	emacs -batch -l untabify.el $(info_TEXINFOS) $(tar_TEXINFOS)
+
+final: untabify master-menu
+
+# Checking
+check-format:
+	@if test -n "`cat $(info_TEXINFOS) $(tar_TEXINFOS) | tr -d -c '\t'`"; then \
+		echo "Sources contain tabs; run make untabify"; \
+		false; \
+	fi
+
 check-options:
 	@ARGP_HELP_FMT='usage-indent=0,short-opt-col=0,long-opt-col=0,\
 doc-opt-col=0,opt-doc-col=0,header-col=0,rmargin=1' \
@@ -67,6 +79,52 @@ doc-opt-col=0,opt-doc-col=0,header-col=0,rmargin=1' \
 	 fi;\
 	 rm report.$$$$

+check-refs:
+	@for file in $(info_TEXINFOS) $(tar_TEXINFOS); \
+	do \
+	  sed -e = $$file | \
+           sed -n 'N;/@FIXME-.*ref/{s/\(^[0-9][0-9]*\).*@FIXME-.*ref{\([^}]*\).*/'$$file':\1: \2/gp}'; \
+	done > $@-t; \
+	if [ -s $@-t ]; then \
+	  echo "Unresolved cross-references:"; \
+	  cat $@-t;\
+	  rm $@-t; \
+	else \
+	  rm -f $@-t; \
+	fi
+
+check-fixmes:
+	@for file in $(info_TEXINFOS); \
+	do \
+	  sed -e = $$file | \
+           sed -n 'N;/@FIXME{/{s/\(^[0-9][0-9]*\).*@FIXME{\([^}]*\).*/'$$file':\1: \2/gp}'; \
+	done > $@-t; \
+	if [ -s $@-t ]; then \
+	  echo "Unresolved FIXMEs:"; \
+	  cat $@-t; \
+	  rm $@-t; \
+	  false; \
+	else \
+          rm -f $@-t; \
+	fi
+
+check-unrevised:
+	@grep -Hn @UNREVISED $(info_TEXINFOS) > $@-t; \
+	if [ -s $@-t ]; then \
+	  echo "Unrevised nodes:"; \
+	  cat $@-t; \
+	  rm $@-t; \
+	  false;\
+	else \
+          rm $@-t; \
+	fi
+
+all-check-docs: check-format check-options check-refs check-fixmes check-unrevised
+
+check-docs: 
+	$(MAKE) -k all-check-docs
+
+#

 clean-local:
 	rm -rf manual
--- a/doc/intern.texi
+++ b/doc/intern.texi
@@ -36,8 +36,6 @@ Archives are permitted to have more than one member with the same
 member name.  One way this situation can occur is if more than one
 version of a file has been stored in the archive.  For information
 about adding new versions of a file to an archive, see @ref{update}.
-@FIXME-xref{To learn more about having more than one archive member with the
-same name, see -backup node, when it's written.}

 In addition to entries describing archive members, an archive may
 contain entries which @command{tar} itself uses to store information.
@@ -108,11 +106,11 @@ group permission could be copied from the @emph{other} permission.

 The @code{uid} and @code{gid} fields are the numeric user and group
@acronym{ID} of the file owners, respectively.  If the operating system does
-not support numeric user or group @acronym{ID}s, these fields should be ignored.
+not support numeric user or group @acronym{ID}s, these fields should
+be ignored. 

 The @code{size} field is the size of the file in bytes; linked files
-are archived with this field specified as zero.  @FIXME-xref{Modifiers, in
-particular the @option{--incremental} (@option{-G}) option.}
+are archived with this field specified as zero. 

 The @code{mtime} field is the data modification time of the file at
 the time it was archived.  It is the ASCII representation of the octal
--- a/doc/rendition.texi
+++ b/doc/rendition.texi
@@ -72,19 +72,28 @@
@ifset PROOF
@strong{<REF>} \string\ @strong{</>}
@end ifset
+@ifclear PROOF
+@cite{\string\}
+@end ifclear
@end macro

@macro FIXME-pxref{string}
@ifset PROOF
-@strong{<PXREF>} \string\ @strong{</>}
+See @strong{<PXREF>} \string\ @strong{</>}
@end ifset
+@ifclear PROOF
+See @cite{\string\}
+@end ifclear

@end macro

@macro FIXME-xref{string}
@ifset PROOF
-@strong{<XREF>} \string\ @strong{</>}
+See @strong{<XREF>} \string\ @strong{</>}
@end ifset
+@ifclear PROOF
+See @cite{\string\}
+@end ifclear
@end macro

@c End of rendition.texi
--- a/doc/tar.texi
+++ b/doc/tar.texi
@@ -453,11 +453,8 @@ concepts of using a Unix-type operating system; @pxref{Tutorial}.)
 The third chapter presents the remaining five operations, and
 information about using @command{tar} options and option syntax.

-@FIXME{this sounds more like a @acronym{GNU} Project Manuals Concept [tm] more
-than the reality.  should think about whether this makes sense to say
-here, or not.}  The other chapters are meant to be used as a
-reference.  Each chapter presents everything that needs to be said
-about a specific topic.
+The other chapters are meant to be used as a reference.  Each chapter
+presents everything that needs to be said about a specific topic.

 One of the chapters (@pxref{Date input formats}) exists in its
 entirety in other @acronym{GNU} manuals, and is mostly self-contained.
@@ -687,7 +684,7 @@ change between directories; and how to figure out where you are in the
 file system.  You should have some basic understanding of directory
 structure and how files are named according to which directory they are
 in.  You should understand concepts such as standard output and standard
-input, what various definitions of the term ``argument'' mean, and the
+input, what various definitions of the term @samp{argument} mean, and the
 differences between relative and absolute file names.  @FIXME{and what
 else?}

@@ -752,10 +749,9 @@ You can write most of the @command{tar} operations and options in any
 of three forms: long (mnemonic) form, short form, and old style.  Some
 of the operations and options have no short or ``old'' forms; however,
 the operations and options which we will cover in this tutorial have
-corresponding abbreviations.  @FIXME{make sure this is still the case,
-at the end}We will indicate those abbreviations appropriately to get
-you used to seeing them.  (Note that the ``old style'' option forms
-exist in @GNUTAR{} for compatibility with Unix
+corresponding abbreviations.  We will indicate those abbreviations
+appropriately to get you used to seeing them.  (Note that the ``old
+style'' option forms exist in @GNUTAR{} for compatibility with Unix
@command{tar}.  In this book we present a full discussion of this way
 of writing options and operations (@pxref{Old Options}), and we discuss
 the other two styles of writing options (@xref{Long Options}, and
@@ -2441,6 +2437,12 @@ record.  @xref{Blocking Factor}.
 This option tells @command{tar} to read or write archives through
@code{bzip2}.  @xref{gzip}.

+@opsummary{check-device}
+@item --check-device
+Check device numbers when creating a list of modified files for
+incremental archiving.  This is the default.  @xref{device numbers},
+for a detailed description. 
+
@opsummary{checkpoint}
@item --checkpoint[=@var{number}]

@@ -2841,6 +2843,12 @@ changed).  @xref{after}.
 An exclude pattern can match any subsequence of the name's components.
@xref{controlling pattern-matching}.

+@opsummary{no-check-device}
+@item --no-check-device
+Do not check device numbers when creating a list of modified files
+for incremental archiving.  @xref{device numbers}, for
+a detailed description. 
+
@opsummary{no-delay-directory-restore}
@item --no-delay-directory-restore

@@ -5677,21 +5685,40 @@ unreliable if you modify a file's time stamps during dumping (e.g.,
 with the @option{--atime-preserve=replace} option), or if you set the clock
 backwards.

+@anchor{device numbers}
@cindex Device numbers, using in incremental backups
 Metadata stored in snapshot files include device numbers, which,
-obviously is supposed to be a non-volatile value.  However, it turns
-out that NFS devices have undependable values when an automounter
+obviously are supposed to be a non-volatile values.  However, it turns
+out that @acronym{NFS} devices have undependable values when an automounter
 gets in the picture.  This can lead to a great deal of spurious
 redumping in incremental dumps, so it is somewhat useless to compare
-two NFS devices numbers over time.  The solution implemented currently
-is to considers all NFS devices as being equal when it comes to
-comparing directories; this is fairly gross, but there does not seem
-to be a better way to go.
+two @acronym{NFS} devices numbers over time.  The solution implemented
+currently is to considers all @acronym{NFS} devices as being equal
+when it comes to comparing directories; this is fairly gross, but
+there does not seem to be a better way to go.

-If you are using the @i{Linux} kernel, the device numbers can also
-change when upgrading to some newer versions of the kernel.  This can
-cause the next backup to be full backup on the affected filesystems.
-@xref{Fixing Snapshot Files}, for the information on how to handle this case.
+Apart from using @acronym{NFS}, there are a number of cases where
+relying on device numbers can cause spurious redumping of unmodified
+files.  For example, this occurs when archiving @acronym{LVM} snapshot
+volumes.  To avoid this, use @option{--no-check-device} option:
+
+@table @option
+@xopindex{no-check-device, described}
+@item --no-check-device
+Do not rely on device numbers when preparing a list of changed files
+for an incremental dump.
+
+@xopindex{check-device, described}
+@item --check-device
+Use device numbers when preparing a list of changed files
+for an incremental dump.  This is the default behavior.  The purpose
+of this option is to undo the effect of the @option{--no-check-device}
+if it was given in @env{TAR_OPTIONS} environment variable
+(@pxref{TAR_OPTIONS}). 
+@end table
+
+There is also another way to cope with changing device numbers.  It is
+described in detail in @ref{Fixing Snapshot Files}.

 Note that incremental archives use @command{tar} extensions and may
 not be readable by non-@acronym{GNU} versions of the @command{tar} program.
@@ -5902,7 +5929,7 @@ their support files using the same file name that is used on the
 machine where the scripts are run (i.e., what @command{pwd} will print
 when in that directory on that machine).  If the host that contains
 the file system does not have this capability, you can specify another
-host as long as it can access the file system through NFS.
+host as long as it can access the file system through @acronym{NFS}.

 If the list of file systems is very long you may wish to put it
 in a separate file.  This file is usually named
@@ -7285,7 +7312,7 @@ $ @kbd{tar tf arch.tar --quoting-style=literal}
 ./a'single'quote
 ./a"double"quote
 ./a\backslash
-./a	tab
+./a     tab
 ./a
 newline
@end group
@@ -7307,7 +7334,7 @@ $ @kbd{tar tf arch.tar --quoting-style=shell}
 './a'\''single'\''quote'
 './a"double"quote'
 './a\backslash'
-'./a	tab'
+'./a    tab'
 './a
 newline'
@end group
@@ -7325,7 +7352,7 @@ $ @kbd{tar tf arch.tar --quoting-style=shell-always}
 './a'\''single'\''quote'
 './a"double"quote'
 './a\backslash'
-'./a	tab'
+'./a    tab'
 './a
 newline'
@end group
@@ -8289,11 +8316,12 @@ $ @kbd{cat archive.tar.gz | tar tfz -}

 Notice also, that there are several restrictions on operations on
 compressed archives.  First of all, compressed archives cannot be
-modified, i.e., you cannot update (@option{--update} (@option{-u})) them or delete
-(@option{--delete}) members from them.  Likewise, you cannot append
-another @command{tar} archive to a compressed archive using
-@option{--append} (@option{-r})).  Secondly, multi-volume archives cannot be
-compressed.
+modified, i.e., you cannot update (@option{--update} (@option{-u}))
+them or delete (@option{--delete}) members from them or
+add (@option{--append} (@option{-r})) members to them.  Likewise, you
+cannot append another @command{tar} archive to a compressed archive using
+@option{--concatenate} (@option{-A})).  Secondly, multi-volume
+archives cannot be compressed.

 The following table summarizes compression options used by @GNUTAR{}.

@@ -10732,7 +10760,7 @@ name=`expr $TAR_ARCHIVE : '\(.*\)-.*'`
 case $TAR_SUBCOMMAND in
 -c)       ;;
 -d|-x|-t) test -r $@{name:-$TAR_ARCHIVE@}-$TAR_VOLUME || exit 1
-	  ;;
+          ;;
 *)        exit 1
 esac

--- a/doc/untabify.el
+++ b/doc/untabify.el
@@ -0,0 +1,13 @@
+;;;; Untabify the sources.
+;;;; Usage: emacs -batch -l untabify.el [file ...]
+
+(defun global-untabify (buflist)
+  (mapcar
+   (lambda (bufname)
+     (set-buffer (find-file bufname))
+     (untabify (point-min) (point-max))
+     (save-buffer)
+     (kill-buffer (current-buffer)))
+   buflist))
+
+(global-untabify command-line-args-left)