git.cworth.org Git - tar/blob - debian/tarman

   1 #
   2 # tarman - make tar man page from src/tar.c
   3 # some text cribbed from debian tar man page
   4 #
   5
   6 use strict;
   7
   8 my $t = "".localtime(time);
   9 my $datestr = substr($t,4,3)." ".substr($t,8,2).", ".substr($t,20,4);
  10
  11 @ARGV=qw(src/tar.c);
  12 my $mode;
  13 my @operations;
  14 my $lastoperation;
  15 my @options;
  16 my @formats;
  17 my @short;
  18 my $examples;
  19 my $saw_format;
  20 my @env_vars;
  21 while (<>) {
  22         my $nflag = 0;
  23         chomp;
  24 # print "$mode: $_\n";
  25         if (/getenv.*"/) {
  26                 next if defined($mode);
  27                 my @c1 = split('"');
  28                 if ($#c1 > 0) {
  29                         push @env_vars, $c1[1];
  30                 }
  31         }
  32         if (/Main operation mode:/) {
  33                 $mode = 1;
  34                 next;
  35         }
  36         if (/Operation modifiers:/) {
  37                 $mode = 2;
  38                 next;
  39         }
  40         if (/Examples:/) {
  41                 $mode = 3;
  42                 next;
  43         }
  44         if (/define GRID/) {
  45                 $mode = 2;
  46         }
  47         if (/undef GRID/) {
  48                 undef $lastoperation;
  49                 undef $mode;
  50                 next;
  51         }
  52         if ($mode == 1 || $mode == 2) {
  53                 if (/{"/) {     # }
  54                         my @j = split(',');
  55                         my @c1 = split('"', $j[0]);
  56                         if (/OPTION_ALIAS/) {
  57                                 next unless defined($lastoperation);
  58                                 push @{$$lastoperation{'alias'} }, $c1[1];
  59                                 next;
  60                         }
  61                         my %newhash = ();
  62                         $lastoperation = \%newhash;
  63                         my $name = $c1[1];
  64                         if ($name =~ /^  /) {
  65                                 $name =~ s/^  */format=/;
  66                                 push @formats, $lastoperation;
  67                         } elsif ($mode == 1) {
  68                                 push @operations, $lastoperation;
  69                         } else {
  70                                 push @options, $lastoperation;
  71                         }
  72                         $newhash{'name'} = $name;
  73                         if ($mode == 2 && $name eq 'format') {
  74                                 $saw_format = $lastoperation;
  75                         }
  76                         my @c2 = split("'", $j[1]);
  77                         if ($#c2 > 0) {
  78                                 $newhash{'short'} = $c2[1];
  79                                 push @short, $c2[1] if ($mode == 1);
  80                         }
  81                         if ($j[2] =~ /N_/) {
  82                                 $nflag = 1;
  83                         }
  84                 }
  85                 if (/N_/) {
  86                         next unless defined($lastoperation);
  87                         my $nrest = $_;
  88                         $nrest =~ s/.*N_//;
  89                         my @c3 = split('"', $nrest);
  90                         if ($#c3 > 0) {
  91                                 if ($nflag) {
  92                                         $$lastoperation{'operand'} .= $c3[1];
  93                                 } else {
  94                                         $$lastoperation{'description'} .= $c3[1];
  95                                 }
  96                         }
  97                 }
  98         }
  99         if ($mode == 3 ) {
 100                 my $j = $_;
 101                 $j =~ s/\\n.*//;
 102                 my ($c1, $c2) = split('#', $j, 2);
 103                 $c1 =~ s/  *$//;
 104                 $c1 =~ s/^  *//;
 105 $c1 =~ s/-/\\-/g;
 106                 $c2 =~ s/^  *//;
 107 $examples .= <<".";
 108 $c2
 109 .Bd -literal -offset indent -compact
 110 $c1
 111 .Ed
 112 .
 113                 # (
 114                 if (/"\)/) {
 115                         undef $mode;
 116                 }
 117         }
 118 }
 119
 120 # for my $q ( @operations) {
 121 #       print "\nshort=".$$q{'short'}."\n";
 122 #       print "name=".$$q{'name'}."\n";
 123 #       print "desc=".$$q{'description'}."\n";
 124 #       if (defined($$q{'alias'})) {
 125 #               print "alias=".join(',',@{ $$q{'alias'}})."\n";
 126 #       }
 127 # }
 128
 129 sub long2nroff {
 130         my $f = shift;
 131         if ($f !~ /^-/) {
 132                 $f = "Fl -$f";
 133         }
 134         $f =~ s/-/\\-/g;
 135         return $f;
 136 }
 137
 138 sub format_options
 139 {
 140         my $h = shift;
 141         my $r;
 142         for my $q ( @$h ) {
 143                 $r .= ".It";
 144                 my @functions;
 145                 push @functions, " Fl ".$$q{'short'} if defined($$q{'short'});
 146                 push @functions, " ".long2nroff($$q{'name'});
 147                 push @functions, join(' ', '', map {long2nroff $_} @{ $$q{'alias'} })
 148                         if defined($$q{'alias'});
 149                 $r .= join(' ,', @functions);
 150                 if (defined($$q{'operand'})) {
 151                         if ($#functions > 0) {
 152                                 $r .= " ";
 153                         } else {
 154                                 $r .= " Ns \\= Ns ";
 155                         }
 156                         $r .= "Ar ".$$q{'operand'};
 157                 }
 158                 $r .= "\n".$$q{'description'}."\n";
 159                 $r .= $$q{'extra'};
 160         }
 161         return $r;
 162 }
 163
 164 sub optionkeyword
 165 {
 166         my $h = shift;
 167         my $k = $$h{'short'};
 168         $k = $$h{'name'} if !defined($k);
 169         my $l = $k;
 170         if ($l =~ s/^no-//) {
 171                 $l .= "-no";
 172         }
 173         return ($l,$k);
 174 }
 175
 176 sub optioncmp
 177 {
 178         my ($x1, $x2) = optionkeyword($a);
 179         my ($y1, $y2) = optionkeyword($b);
 180         my $r = lc($x1) cmp lc($y1);
 181         return $r if $r;
 182         $r = $y1 cmp $x1;
 183         return $r if $r;
 184         return $x2 cmp $y2;
 185 }
 186
 187 @operations = sort optioncmp @operations;
 188 @operations = sort optioncmp @operations;
 189 @options = sort optioncmp @options;
 190 @formats = sort optioncmp @formats;
 191
 192 if ($#formats >= 0 && !$saw_format) {
 193         print STDERR "FIXME: saw --format=X but no root --format!\n";
 194         exit(1);
 195 }
 196
 197 my $function_letters;
 198 my $short_letters = join('', sort @short);
 199 my $option_letters;
 200 my $format_letters;
 201 my $command_string = <<".";
 202 .Nm tar
 203 .
 204 $command_string .= ".Oo Fl Oc";
 205 my $env_variables;
 206 my %env_description = (
 207 'SIMPLE_BACKUP_SUFFIX' => <<".",
 208 Backup prefix to use when extracting, if
 209 .Fl \\-suffix
 210 is not specified.
 211 The backup suffix defaults to `~' if neither is specified.
 212 .
 213 'TAPE' => <<".",
 214 Device or file to use for the archive if
 215 .Fl \\-file
 216 is not specified.
 217 If this environment variable is unset, use stdin or stdout instead.
 218 .
 219 'TAR_OPTIONS' => <<".",
 220 Options to prepend to those specified on the command line, separated by
 221 whitespace.  Embedded backslashes may be used to escape whitespace or
 222 backslashes within an option.
 223 .
 224 );
 225 my $sep = "";
 226 for my $q ( @operations) {
 227         $command_string .= " Cm";
 228         $command_string .= $sep;
 229         $command_string .= " ".$$q{'short'} if defined($$q{'short'});
 230         $command_string .= " ".long2nroff($$q{'name'});
 231         if (defined($$q{'alias'})) {
 232                 my $t = join(' ', '', map{long2nroff $_} @{ $$q{'alias'} });
 233                 $t =~ s/ Fl / /g;
 234                 $command_string .= $t;
 235         }
 236         $sep = " \\||\\|";
 237 }
 238 $function_letters = ".Bl -tag -width flag\n";
 239 $function_letters .= format_options(\@operations);
 240 $function_letters .= ".El";
 241 if ($#formats >= 0) {
 242         $format_letters = ".Bl -tag -width flag\n";
 243         $format_letters .= format_options(\@formats);
 244         $format_letters .= ".El\n";
 245         $$saw_format{'extra'} = $format_letters;
 246 }
 247 ### Ar Cm Ic Li Nm Op Pa Va
 248 $option_letters = ".Bl -tag -width flag\n";
 249 $option_letters .= format_options(\@options);
 250 $option_letters .= ".El";
 251 $env_variables .= ".Bl -tag -width Ds\n";
 252 for my $q ( @env_vars) {
 253         $env_variables .= ".It Ev $q\n";
 254         $env_variables .= $env_description{$q};
 255 }
 256 $env_variables .= ".El";
 257
 258 $examples =~ s/\n$//;
 259 $function_letters =~ s/\n$//;
 260 $option_letters =~ s/\n$//;
 261 $env_variables =~ s/\n$//;
 262 print <<".";
 263 .\\" generated by script on $t
 264 .Dd $datestr
 265 .Dt TAR 1
 266 .Sh NAME
 267 .Nm tar
 268 .Nd The GNU version of the tar archiving utility
 269 .Sh SYNOPSIS
 270 $command_string
 271 .Op Ar options
 272 .Op Ar pathname ...
 273 .Sh DESCRIPTION
 274 .Nm Tar
 275 stores and extracts files from a tape or disk archive.
 276 .Pp
 277 The first argument to
 278 tar
 279 should be a function; either one of the letters
 280 .Cm $short_letters ,
 281 or one of the long function names.
 282 A function letter need not be prefixed with ``\\-'', and may be combined
 283 with other single-letter options.
 284 A long function name must be prefixed with
 285 .Cm \\\\-\\\\- .
 286 Some options take a parameter; with the single-letter form
 287 these must be given as separate arguments.
 288 With the long form, they may be given by appending
 289 .Cm = Ns Ar value
 290 to the option.
 291 .Sh FUNCTION LETTERS
 292 Main operation mode:
 293 $function_letters
 294 .Sh OTHER OPTIONS
 295 Operation modifiers:
 296 $option_letters
 297 .Sh ENVIRONMENT
 298 The behavior of tar is controlled by the following environment variables,
 299 among others:
 300 $env_variables
 301 .Sh EXAMPLES
 302 $examples
 303 .Sh SEE ALSO
 304 .\\" libarchive
 305 .Xr tar 5 ,
 306 .\\" man-pages
 307 .Xr symlink 7 ,
 308 .Xr rmt 8
 309 .Sh HISTORY
 310 The
 311 .Nm tar
 312 command appeared in
 313 .At v7 .
 314 .Sh BUGS
 315 The GNU folks, in general, abhor man pages, and create info documents instead.
 316 Unfortunately, the info document describing tar is licensed under the GFDL with
 317 invariant cover texts, which makes it impossible to include any text
 318 from that document in this man page.
 319 Most of the text in this document was automatically extracted from the usage
 320 text in the source.
 321 It may not completely describe all features of the program.
 322 .
 323 __END__