From ac123ad6ace5a2030495a3e9943a834425282d03 Mon Sep 17 00:00:00 2001 From: Bdale Garbee Date: Thu, 18 Jun 2009 15:02:02 -0600 Subject: [PATCH] remaining changes missed in reconstruction --- debian/tar.1 | 396 -------------------------------------------------- debian/tarman | 323 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 323 insertions(+), 396 deletions(-) delete mode 100644 debian/tar.1 create mode 100644 debian/tarman diff --git a/debian/tar.1 b/debian/tar.1 deleted file mode 100644 index 4b5985e..0000000 --- a/debian/tar.1 +++ /dev/null @@ -1,396 +0,0 @@ -.\" @(#)tar.1 1.11.1 93/19/22 PJV; -.TH TAR 1 "24 Feb 2009" -.SH NAME -tar \- The GNU version of the tar archiving utility -.SH SYNOPSIS -.B tar -[ -.B \- -] -.B A \-\-catenate \-\-concatenate \||\| c \-\-create \||\| d \-\-diff \-\-compare \||\| \-\-delete \||\| r \-\-append \||\| t \-\-list \||\| u \-\-update \||\| x \-\-extract \-\-get -.I [ options ] -.I pathname [ pathname ... ] -.SH DESCRIPTION -.LP -This manual page documents the GNU version of -.B tar -, an archiving program designed to store and extract files from -an archive file known as a -.IR tarfile. -A -.IR tarfile -may be made on a tape drive, however, it is also common -to write a -.IR tarfile -to a normal file. -The first argument to -.B tar -must be one of the options: -.BR Acdrtux , -followed by any optional functions. -The final arguments to -.B tar -are the names of the files or directories which should be archived. The use -of a directory name always implies that the subdirectories below should be -included in the archive. -.SH EXAMPLES -.TP -.B tar \-xvvf foo.tar -extract foo.tar -.TP -.B tar \-xvvzf foo.tar.gz -extract gzipped foo.tar.gz -.TP -.B tar \-cvvf foo.tar foo/ -tar contents of folder foo in foo.tar -.SH "FUNCTION LETTERS" -.TP -.B One of the following options must be used: -.TP -.B \-A, \-\-catenate, \-\-concatenate -append tar files to an archive -.TP -.B \-c, \-\-create -create a new archive -.TP -.B \-d, \-\-diff, \-\-compare -find differences between archive and file system -.TP -.B \-\-delete -delete from the archive (not for use on mag tapes!) -.TP -.B \-r, \-\-append -append files to the end of an archive -.TP -.B \-t, \-\-list -list the contents of an archive -.TP -.B \-u, \-\-update -only append files that are newer than copy in archive -.TP -.B \-x, \-\-extract, \-\-get -extract files from an archive -.SH "OTHER OPTIONS" -.TP -.B \-\-allow\-name\-mangling -re-enable handling of GNUTYPE_NAMES which is now disabled by default -.TP -.B \-\-anchored -force exclusion patterns to match initial subsequences -.TP -.B \-\-atime\-preserve -don't change access times on dumped files -.TP -.B \-a, \-\-auto\-compress -with \-\-create, selects compression algorithm basing on the suffix -of the archive file name -.TP -.B \-b, \-\-blocking\-factor N -use record size of Nx512 bytes (default N=20) -.TP -.B \-B, \-\-read\-full\-records -reblock as we read (for reading 4.2BSD pipes) -.TP -.B \-\-backup[\=TYPE] -back up files instead of overwriting (TYPE=numbered, existing, simple) -.TP -.B \-C, \-\-directory DIR -change to directory DIR -.TP -.B \-\-checkpoint -print periodic checkpoints -.TP -.B \-\-checkpoint\-action -this action allows to specify an action to be executed upon hitting a -checkpoint. Recognized actions are: dot, echo (the default), -echo\=string, ttyout\=string, exec\=cmdline, and sleep\=value. Any number -of `\-\-checkpoint\-action' options can be specified, the actions will be -executed in order of their appearance in the command line. -.TP -.B \-\-check\-device -enables comparing device numbers. This is the default. -.TP -.B \-\-no\-check\-device -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) -.TP -.B \-\-exclude=PATTERN -exclude files matching PATTERN -.TP -.B \-f, \-\-file [HOSTNAME:]F -use archive file or device F (otherwise value of TAPE environment variable; if unset, "\-", meaning stdin/stdout) -.TP -.B \-F, \-\-info\-script F, \-\-new\-volume\-script F -run script at end of each tape (implies \-M) -.TP -.B \-\-force\-local -archive file is local even if it has a colon -.TP -.B \-G, \-\-incremental -create/list/extract old GNU-format incremental backup -.TP -.B \-g, \-\-listed\-incremental F -create/list/extract new GNU-format incremental backup -.TP -.B \-\-group G -set group to G while adding files -.TP -.B \-h, \-\-dereference -don't dump symlinks; dump the files they point to -.TP -.B \-\-hard\-dereference -during archive creation, dereferences hard links and stores the files -they refer to, instead of creating usual hard link members (type '1') -.TP -.B \-\-help -print help message -.TP -.B \-i, \-\-ignore\-zeros -ignore blocks of zeros in archive (normally mean EOF) -.TP -.B \-\-ignore\-case -ignore case when excluding files -.TP -.B \-\-ignore\-failed\-read -don't exit with non-zero status on unreadable files -.TP -.B \-j, \-\-bzip2 -filter archive through bzip2, use to decompress .bz2 files. -WARNING: some previous versions of tar used option \-I to -filter through bzip2. When writing scripts, use \-\-bzip2 -instead of \-j so that both older and newer tar versions -will work. -.TP -.B \-k, \-\-keep\-old\-files -keep existing files; don't overwrite them from archive -.TP -.B \-K, \-\-starting\-file F -begin at file F in the archive -.TP -.B \-J, \-\-lzma -selects LZMA compression algorithm -.TP -.B \-l, \-\-check\-links -print a message if not all links are dumped -.TP -.B \-L, \-\-tape\-length N -change tapes after writing N*1024 bytes -.TP -.B \-\-lzop -filter the archive through lzop -.TP -.B \-m, \-\-touch -don't extract file modified time -.TP -.BI \-\-transform " expr" -applies filename transformations. -The argument to this option can be a list of replace expressions, separated -by semicolon (as in `sed'). -Filename transformations are applied to symbolic link targets during both -creation and extraction. -This option may be specified any number of -times, the specified transofrmations will be applied in turn. -.TP -.B \-M, \-\-multi\-volume -create/list/extract multi-volume archive -.TP -.B \-\-mode M -set permissions to M while adding files -.TP -.B \-N, \-\-after\-date DATE, \-\-newer DATE -only store files newer than DATE -.TP -.B \-\-newer\-mtime DATE -only store files whose contents have changed after DATE -.TP -.B \-\-no\-anchored -allow exclusion patterns to match any substring (the default) -.TP -.B \-\-no\-auto\-compress -Cancels the effect of previous \-\-auto\-compress options -.TP -.B \-\-no\-ignore\-case -match patterns case sensitively (the default) -.TP -.B \-\-no\-null -cancels the effect of previous \-\-null option -.TP -.B \-\-no\-recursion -do not recurse into subdirectories -.TP -.B \-o, \-\-no\-same\-owner -extract files with owner set to current user (the default for non-root -users) -.TP -.B \-\-no\-same\-permissions -apply umask to extracted files (the default for non-root users) -.TP -.B \-\-no\-wildcards -do not use wildcards when excluding files -.TP -.B \-\-no\-wildcards\-match\-slash -don't let wildcards match "/" when excluding files -.TP -.B \-\-null -for \-T, use "NUL" instead of newline as filename terminator -.TP -.B \-\-numeric\-owner -always use numbers for user/group names -.TP -.B \-\-old\-archive, \-\-portability -write a V7 format archive, rather than ANSI format. These options are -deprecated, please use -.B \-\-format\=v7 -instead. -.TP -.B \-\-one\-file\-system -stay in local file system when creating an archive -.TP -.B \-\-owner O -set owner to O while adding files -.TP -.B \-O, \-\-to\-stdout -extract files to standard output -.TP -.B \-p, \-\-same\-permissions, \-\-preserve\-permissions -ignore umask when extracting files (the default for root) -.TP -.B \-P, \-\-absolute\-names -don't strip leading `/'s from file names -.TP -.B \-\-posix -create POSIX compliant archive. This option is deprecated, -please use -.B \-\-format\=posix -instead. -.TP -.B \-\-preserve -like \-p \-s -.TP -.B \-R, \-\-block\-number -show block number within archive with each message -.TP -.B \-\-record\-size SIZE -use SIZE bytes per record -.TP -.B \-\-recursion -recurse into directories (the default) -.TP -.B \-\-recursive\-unlink -remove existing directories before extracting directories of the same -name -.TP -.B \-\-remove\-files -remove files after adding them to the archive -.TP -.B \-\-rsh\-command=CMD -Use remote COMMAND instead of `rsh'. This option exists so that -people who use something other than the standard `rsh' (e.g., a -Kerberized `rsh') can access a remote device. -.TP -.B \-S, \-\-sparse -handle sparse files efficiently -.TP -.B \-s, \-\-same\-order, \-\-preserve\-order -list of names to extract is sorted to match archive -.TP -.B \-\-same\-owner -extract files with owner as specified in archive (the default for -root) -.TP -.B \-\-show\-omitted\-dirs -mention directories that are being skipped over -.TP -.BI \-\-strip\-components " n" -Strip the given number of leading directory components -.TP -.B \-\-strip, \-\-strip\-components N -Strips the first N components from archive members' pathnames when -unpacking. -.TP -.B \-\-suffix SUFFIX -append SUFFIX to make backup files (default ~) -.TP -.B \-T, \-\-files\-from F -get names to extract or archive from file F -.TP -.B \-\-totals -display total bytes written after creating an archive -.TP -.B \-U, \-\-unlink\-first -unlink & recreate files instead of overwriting -.TP -.B \-\-use\-compress\-program PROG -filter the archive through PROG (which must accept \-d) -.TP -.B \-v, \-\-verbose -verbosely list files processed -.TP -.B \-V, \-\-label NAME -create archive with volume name NAME -.TP -.B \-\-version -print tar program version number -.TP -.B \-\-volno\-file F -keep track of current volume (of a multi-volume archive) in F -.TP -.B \-w, \-\-interactive, \-\-confirmation -ask for confirmation for every action -.TP -.B \-W, \-\-verify -attempt to verify the archive after writing it -.TP -.B \-\-wildcards -use wildcards when excluding files (the default) -.TP -.B \-\-wildcards\-match\-slash -allow wildcards to match "/" (the default) -.TP -.B \-X, \-\-exclude\-from=FILE -exclude files matching patterns listed in FILE -.TP -.B \-Z, \-\-compress, \-\-uncompress -filter the archive through compress -.TP -.B \-z, \-\-gzip, \-\-gunzip, \-\-ungzip -filter the archive through gzip -.TP -.B \-[0\-7][lmh] -specify drive and density -.SH ENVIRONMENT -The behavior of tar is controlled by the following environment variables, -among others: -.TP -.B TAPE -Device or file to use for the archive if \fB--file\fR is not specified. -If this environment variable is unset, use stdin or stdout instead. -.TP -.B TAR_OPTIONS -Options to prepend to those specified on the command line, separated by -whitespace. Embedded backslashes may be used to escape whitespace or -backslashes within an option. -.LP -In addition, the value of the blocking factor is made available to info -and checkpoint scripts via environment variable -.B TAR_BLOCKING_FACTOR. -.SH BUGS -.LP -The GNU folks, in general, abhor man pages, and create info documents instead. -Unfortunately, the info document describing tar is licensed under the GFDL with -invariant cover texts, which violates the Debian Free Software Guidelines. As -a result, the info documentation for tar is not included in the Debian package. - -If you want to read the complete documentation for GNU tar, please refer to -the online version at -.PP -.ce 1 - -.PP -This man page was created for the Debian distribution. It does not describe -all of the functionality of tar, and it is often out of date. Patches to -improve the coverage and/or accuracy of this man page are appreciated, and -should be filed as wishlist severity bugs against the Debian tar package, -not submitted to the GNU tar maintainers. diff --git a/debian/tarman b/debian/tarman new file mode 100644 index 0000000..74df4ff --- /dev/null +++ b/debian/tarman @@ -0,0 +1,323 @@ +# +# tarman - make tar man page from src/tar.c +# some text cribbed from debian tar man page +# + +use strict; + +my $t = "".localtime(time); +my $datestr = substr($t,4,3)." ".substr($t,8,2).", ".substr($t,20,4); + +@ARGV=qw(src/tar.c); +my $mode; +my @operations; +my $lastoperation; +my @options; +my @formats; +my @short; +my $examples; +my $saw_format; +my @env_vars; +while (<>) { + my $nflag = 0; + chomp; +# print "$mode: $_\n"; + if (/getenv.*"/) { + next if defined($mode); + my @c1 = split('"'); + if ($#c1 > 0) { + push @env_vars, $c1[1]; + } + } + if (/Main operation mode:/) { + $mode = 1; + next; + } + if (/Operation modifiers:/) { + $mode = 2; + next; + } + if (/Examples:/) { + $mode = 3; + next; + } + if (/define GRID/) { + $mode = 2; + } + if (/undef GRID/) { + undef $lastoperation; + undef $mode; + next; + } + if ($mode == 1 || $mode == 2) { + if (/{"/) { # } + my @j = split(','); + my @c1 = split('"', $j[0]); + if (/OPTION_ALIAS/) { + next unless defined($lastoperation); + push @{$$lastoperation{'alias'} }, $c1[1]; + next; + } + my %newhash = (); + $lastoperation = \%newhash; + my $name = $c1[1]; + if ($name =~ /^ /) { + $name =~ s/^ */format=/; + push @formats, $lastoperation; + } elsif ($mode == 1) { + push @operations, $lastoperation; + } else { + push @options, $lastoperation; + } + $newhash{'name'} = $name; + if ($mode == 2 && $name eq 'format') { + $saw_format = $lastoperation; + } + my @c2 = split("'", $j[1]); + if ($#c2 > 0) { + $newhash{'short'} = $c2[1]; + push @short, $c2[1] if ($mode == 1); + } + if ($j[2] =~ /N_/) { + $nflag = 1; + } + } + if (/N_/) { + next unless defined($lastoperation); + my $nrest = $_; + $nrest =~ s/.*N_//; + my @c3 = split('"', $nrest); + if ($#c3 > 0) { + if ($nflag) { + $$lastoperation{'operand'} .= $c3[1]; + } else { + $$lastoperation{'description'} .= $c3[1]; + } + } + } + } + if ($mode == 3 ) { + my $j = $_; + $j =~ s/\\n.*//; + my ($c1, $c2) = split('#', $j, 2); + $c1 =~ s/ *$//; + $c1 =~ s/^ *//; +$c1 =~ s/-/\\-/g; + $c2 =~ s/^ *//; +$examples .= <<"."; +$c2 +.Bd -literal -offset indent -compact +$c1 +.Ed +. + # ( + if (/"\)/) { + undef $mode; + } + } +} + +# for my $q ( @operations) { +# print "\nshort=".$$q{'short'}."\n"; +# print "name=".$$q{'name'}."\n"; +# print "desc=".$$q{'description'}."\n"; +# if (defined($$q{'alias'})) { +# print "alias=".join(',',@{ $$q{'alias'}})."\n"; +# } +# } + +sub long2nroff { + my $f = shift; + if ($f !~ /^-/) { + $f = "Fl -$f"; + } + $f =~ s/-/\\-/g; + return $f; +} + +sub format_options +{ + my $h = shift; + my $r; + for my $q ( @$h ) { + $r .= ".It"; + my @functions; + push @functions, " Fl ".$$q{'short'} if defined($$q{'short'}); + push @functions, " ".long2nroff($$q{'name'}); + push @functions, join(' ', '', map {long2nroff $_} @{ $$q{'alias'} }) + if defined($$q{'alias'}); + $r .= join(' ,', @functions); + if (defined($$q{'operand'})) { + if ($#functions > 0) { + $r .= " "; + } else { + $r .= " Ns \\= Ns "; + } + $r .= "Ar ".$$q{'operand'}; + } + $r .= "\n".$$q{'description'}."\n"; + $r .= $$q{'extra'}; + } + return $r; +} + +sub optionkeyword +{ + my $h = shift; + my $k = $$h{'short'}; + $k = $$h{'name'} if !defined($k); + my $l = $k; + if ($l =~ s/^no-//) { + $l .= "-no"; + } + return ($l,$k); +} + +sub optioncmp +{ + my ($x1, $x2) = optionkeyword($a); + my ($y1, $y2) = optionkeyword($b); + my $r = lc($x1) cmp lc($y1); + return $r if $r; + $r = $y1 cmp $x1; + return $r if $r; + return $x2 cmp $y2; +} + +@operations = sort optioncmp @operations; +@operations = sort optioncmp @operations; +@options = sort optioncmp @options; +@formats = sort optioncmp @formats; + +if ($#formats >= 0 && !$saw_format) { + print STDERR "FIXME: saw --format=X but no root --format!\n"; + exit(1); +} + +my $function_letters; +my $short_letters = join('', sort @short); +my $option_letters; +my $format_letters; +my $command_string = <<"."; +.Nm tar +. +$command_string .= ".Oo Fl Oc"; +my $env_variables; +my %env_description = ( +'SIMPLE_BACKUP_SUFFIX' => <<".", +Backup prefix to use when extracting, if +.Fl \\-suffix +is not specified. +The backup suffix defaults to `~' if neither is specified. +. +'TAPE' => <<".", +Device or file to use for the archive if +.Fl \\-file +is not specified. +If this environment variable is unset, use stdin or stdout instead. +. +'TAR_OPTIONS' => <<".", +Options to prepend to those specified on the command line, separated by +whitespace. Embedded backslashes may be used to escape whitespace or +backslashes within an option. +. +); +my $sep = ""; +for my $q ( @operations) { + $command_string .= " Cm"; + $command_string .= $sep; + $command_string .= " ".$$q{'short'} if defined($$q{'short'}); + $command_string .= " ".long2nroff($$q{'name'}); + if (defined($$q{'alias'})) { + my $t = join(' ', '', map{long2nroff $_} @{ $$q{'alias'} }); + $t =~ s/ Fl / /g; + $command_string .= $t; + } + $sep = " \\||\\|"; +} +$function_letters = ".Bl -tag -width flag\n"; +$function_letters .= format_options(\@operations); +$function_letters .= ".El"; +if ($#formats >= 0) { + $format_letters = ".Bl -tag -width flag\n"; + $format_letters .= format_options(\@formats); + $format_letters .= ".El\n"; + $$saw_format{'extra'} = $format_letters; +} +### Ar Cm Ic Li Nm Op Pa Va +$option_letters = ".Bl -tag -width flag\n"; +$option_letters .= format_options(\@options); +$option_letters .= ".El"; +$env_variables .= ".Bl -tag -width Ds\n"; +for my $q ( @env_vars) { + $env_variables .= ".It Ev $q\n"; + $env_variables .= $env_description{$q}; +} +$env_variables .= ".El"; + +$examples =~ s/\n$//; +$function_letters =~ s/\n$//; +$option_letters =~ s/\n$//; +$env_variables =~ s/\n$//; +print <<"."; +.\\" generated by script on $t +.Dd $datestr +.Dt TAR 1 +.Sh NAME +.Nm tar +.Nd The GNU version of the tar archiving utility +.Sh SYNOPSIS +$command_string +.Op Ar options +.Op Ar pathname ... +.Sh DESCRIPTION +.Nm Tar +stores and extracts files from a tape or disk archive. +.Pp +The first argument to +.B tar +should be a function; either one of the letters +.Cm $short_letters , +or one of the long function names. +A function letter need not be prefixed with ``\\-'', and may be combined +with other single-letter options. +A long function name must be prefixed with +.Cm \\\\-\\\\- . +Some options take a parameter; with the single-letter form +these must be given as separate arguments. +With the long form, they may be given by appending +.Cm = Ns Ar value +to the option. +.Sh FUNCTION LETTERS +Main operation mode: +$function_letters +.Sh OTHER OPTIONS +Operation modifiers: +$option_letters +.Sh ENVIRONMENT +The behavior of tar is controlled by the following environment variables, +among others: +$env_variables +.Sh EXAMPLES +$examples +.Sh SEE ALSO +.\\" libarchive +.Xr tar 5 , +.\\" man-pages +.Xr symlink 7 , +.Xr rmt 8 +.Sh HISTORY +The +.Nm tar +command appeared in +.At v7 . +.Sh BUGS +The GNU folks, in general, abhor man pages, and create info documents instead. +Unfortunately, the info document describing tar is licensed under the GFDL with +invariant cover texts, which makes it impossible to include any text +from that document in this man page. +Most of the text in this document was automatically extracted from the usage +text in the source. +It may not completely describe all features of the program. +. +__END__ -- 2.43.0