utils/perlbug.PL

   1 #!/usr/local/bin/perl
   2
   3 use Config;
   4 use File::Basename qw(&basename &dirname);
   5
   6 # List explicitly here the variables you want Configure to
   7 # generate.  Metaconfig only looks for shell variables, so you
   8 # have to mention them as if they were shell variables, not
   9 # %Config entries.  Thus you write
  10 #  $startperl
  11 # to ensure Configure will look for $Config{startperl}.
  12
  13 # This forces PL files to create target in same directory as PL file.
  14 # This is so that make depend always knows where to find PL derivatives.
  15 chdir dirname($0);
  16 $file = basename($0, '.PL');
  17 $file .= '.com' if $^O eq 'VMS';
  18
  19 open OUT,">$file" or die "Can't create $file: $!";
  20
  21 print "Extracting $file (with variable substitutions)\n";
  22
  23 # In this section, perl variables will be expanded during extraction.
  24 # You can use $Config{...} to use Configure variables.
  25
  26 print OUT <<"!GROK!THIS!";
  27 $Config{startperl}
  28     eval 'exec $Config{perlpath} -S \$0 \${1+"\$@"}'
  29         if \$running_under_some_shell;
  30 !GROK!THIS!
  31
  32 # In the following, perl variables are not expanded during extraction.
  33
  34 print OUT <<'!NO!SUBS!';
  35
  36 use Config;
  37 use Getopt::Std;
  38
  39 BEGIN {
  40         eval "use Mail::Send;";
  41         $::HaveSend = ($@ eq "");
  42         eval "use Mail::Util;";
  43         $::HaveUtil = ($@ eq "");
  44 };
  45
  46
  47 use strict;
  48
  49 sub paraprint;
  50
  51
  52 my($Version) = "1.16";
  53
  54 # Changed in 1.06 to skip Mail::Send and Mail::Util if not available.
  55 # Changed in 1.07 to see more sendmail execs, and added pipe output.
  56 # Changed in 1.08 to use correct address for sendmail.
  57 # Changed in 1.09 to close the REP file before calling it up in the editor.
  58 #                 Also removed some old comments duplicated elsewhere.
  59 # Changed in 1.10 to run under VMS without Mail::Send; also fixed
  60 #                 temp filename generation.
  61 # Changed in 1.11 to clean up some text and removed Mail::Send deactivator.
  62 # Changed in 1.12 to check for editor errors, make save/send distinction
  63 #                 clearer and add $ENV{REPLYTO}.
  64 # Changed in 1.13 to hopefully make it more difficult to accidentally
  65 #                 send mail
  66 # Changed in 1.14 to make the prompts a little more clear on providing
  67 #                 helpful information. Also let file read fail gracefully.
  68 # Changed in 1.15 to add warnings to stop people using perlbug for non-bugs.
  69 #                 Also report selected environment variables.
  70 # Changed in 1.16 to include @INC, and allow user to re-edit if no changes.
  71
  72 # TODO: Allow the user to re-name the file on mail failure, and
  73 #       make sure failure (transmission-wise) of Mail::Send is
  74 #       accounted for.
  75
  76 my( $file, $usefile, $cc, $address, $perlbug, $testaddress, $filename,
  77     $subject, $from, $verbose, $ed,
  78     $fh, $me, $Is_VMS, $msg, $body, $andcc, %REP);
  79
  80 Init();
  81
  82 if($::opt_h) { Help(); exit; }
  83
  84 if(!-t STDIN) {
  85         paraprint <<EOF;
  86 Please use perlbug interactively. If you want to
  87 include a file, you can use the -f switch.
  88 EOF
  89         die "\n";
  90 }
  91
  92 if($::opt_d or !-t STDOUT) { Dump(*STDOUT); exit; }
  93
  94 Query();
  95 Edit() unless $usefile;
  96 NowWhat();
  97 Send();
  98
  99 exit;
 100
 101 sub Init {
 102
 103         # -------- Setup --------
 104
 105         $Is_VMS = $^O eq 'VMS';
 106
 107         getopts("dhva:s:b:f:r:e:SCc:t");
 108
 109
 110         # This comment is needed to notify metaconfig that we are
 111         # using the $perladmin, $cf_by, and $cf_time definitions.
 112
 113
 114         # -------- Configuration ---------
 115
 116         # perlbug address
 117         $perlbug = 'perlbug@perl.com';
 118
 119         # Test address
 120         $testaddress = 'perlbug-test@perl.com';
 121
 122         # Target address
 123         $address = $::opt_a || ($::opt_t ? $testaddress : $perlbug);
 124
 125         # Possible administrator addresses, in order of confidence
 126         # (Note that cf_email is not mentioned to metaconfig, since
 127         # we don't really want it. We'll just take it if we have to.)
 128         $cc = ($::opt_C ? "" : (
 129                 $::opt_c || $::Config{perladmin} || $::Config{cf_email} || $::Config{cf_by}
 130                 ));
 131
 132         # Users address, used in message and in Reply-To header
 133         $from = $::opt_r || "";
 134
 135         # Include verbose configuration information
 136         $verbose = $::opt_v || 0;
 137
 138         # Subject of bug-report message
 139         $subject = $::opt_s || "";
 140
 141         # Send a file
 142         $usefile = ($::opt_f || 0);
 143
 144         # File to send as report
 145         $file = $::opt_f || "";
 146
 147         # Body of report
 148         $body = $::opt_b || "";
 149
 150         # Editor
 151         $ed = ( $::opt_e || $ENV{VISUAL} || $ENV{EDITOR} || $ENV{EDIT} ||
 152                       ($Is_VMS ? "edit/tpu" : "vi")
 153               );
 154
 155
 156         # My username
 157         $me = getpwuid($<);
 158
 159 }
 160
 161
 162 sub Query {
 163
 164         # Explain what perlbug is
 165
 166         paraprint <<EOF;
 167 This program provides an easy way to create a message reporting a bug
 168 in perl, and e-mail it to $address.  It is *NOT* intended for
 169 sending test messages or simply verifying that perl works.  It is *ONLY*
 170 a means of reporting verifiable problems with perl, and any solutions to
 171 such problems, to the people who maintain perl.
 172
 173 EOF
 174
 175
 176         # Prompt for subject of message, if needed
 177         if(! $subject) {
 178                 paraprint <<EOF;
 179 First of all, please provide a subject for the
 180 message. It should be a concise description of
 181 the bug or problem. "perl bug" or "perl problem"
 182 is not a concise description.
 183
 184 EOF
 185                 print "Subject: ";
 186
 187                 $subject = <>;
 188                 chop $subject;
 189
 190                 my($err)=0;
 191                 while( $subject =~ /^\s*$/ ) {
 192                         print "\nPlease enter a subject: ";
 193                         $subject = <>;
 194                         chop $subject;
 195                         if($err++>5) {
 196                                 die "Aborting.\n";
 197                         }
 198                 }
 199         }
 200
 201
 202         # Prompt for return address, if needed
 203         if( !$from) {
 204
 205                 # Try and guess return address
 206                 my($domain);
 207
 208                 if($::HaveUtil) {
 209                         $domain = Mail::Util::maildomain();
 210                 } elsif ($Is_VMS) {
 211                         require Sys::Hostname;
 212                         $domain = Sys::Hostname::hostname();
 213                 } else {
 214                         $domain = `hostname`.".".`domainname`;
 215                         $domain =~ s/[\r\n]+//g;
 216                 }
 217
 218             my($guess);
 219
 220                 if( !$domain) {
 221                         $guess = "";
 222                 } elsif ($Is_VMS && !$::Config{'d_socket'}) {
 223                         $guess = "$domain\:\:$me";
 224                 } else {
 225                         $guess = "$me\@$domain" if $domain;
 226                         $guess = "$me\@unknown.addresss" unless $domain;
 227                         }
 228
 229                 $guess = $ENV{'REPLYTO'} if defined($ENV{'REPLYTO'});
 230                 $guess = $ENV{"REPLY-TO"} if defined($ENV{'REPLY-TO'});
 231
 232                 if( $guess ) {
 233                         paraprint <<EOF;
 234
 235
 236 Your e-mail address will be useful if you need to be contacted. If the
 237 default shown is not your full internet e-mail address, please correct it.
 238
 239 EOF
 240                 } else {
 241                         paraprint <<EOF;
 242
 243 So that you may be contacted if necessary, please enter
 244 your full internet e-mail address here.
 245
 246 EOF
 247                 }
 248                 print "Your address [$guess]: ";
 249
 250                 $from = <>;
 251                 chop $from;
 252
 253                 if($from eq "") { $from = $guess }
 254
 255         }
 256
 257         #if( $from =~ /^(.*)\@(.*)$/ ) {
 258         #       $mailname = $1;
 259         #       $maildomain = $2;
 260         #}
 261
 262         if( $from eq $cc or $me eq $cc ) {
 263                 # Try not to copy ourselves
 264                 $cc = "yourself";
 265         }
 266
 267
 268         # Prompt for administrator address, unless an override was given
 269         if( !$::opt_C and !$::opt_c ) {
 270                 paraprint <<EOF;
 271
 272
 273 A copy of this report can be sent to your local
 274 perl administrator. If the address is wrong, please
 275 correct it, or enter 'none' or 'yourself' to not send
 276 a copy.
 277
 278 EOF
 279
 280                 print "Local perl administrator [$cc]: ";
 281
 282                 my($entry) = scalar(<>);
 283                 chop $entry;
 284
 285                 if($entry ne "") {
 286                         $cc = $entry;
 287                         if($me eq $cc) { $cc = "" }
 288                 }
 289
 290         }
 291
 292         if($cc =~ /^(none|yourself|me|myself|ourselves)$/i) { $cc = "" }
 293
 294         $andcc = " and $cc" if $cc;
 295
 296 editor:
 297
 298         # Prompt for editor, if no override is given
 299         if(! $::opt_e and ! $::opt_f and ! $::opt_b) {
 300                 paraprint <<EOF;
 301
 302
 303 Now you need to supply the bug report. Try to make
 304 the report concise but descriptive. Include any
 305 relevant detail. If you are reporting something
 306 that does not work as you think it should, please
 307 try to include example of both the actual
 308 result, and what you expected.
 309
 310 Some information about your local
 311 perl configuration will automatically be included
 312 at the end of the report. If you are using any
 313 unusual version of perl, please try and confirm
 314 exactly which versions are relevant.
 315
 316 You will probably want to use an editor to enter
 317 the report. If "$ed" is the editor you want
 318 to use, then just press Enter, otherwise type in
 319 the name of the editor you would like to use.
 320
 321 If you would like to use a prepared file, type
 322 "file", and you will be asked for the filename.
 323
 324 EOF
 325
 326                 print "Editor [$ed]: ";
 327
 328                 my($entry) =scalar(<>);
 329                 chop $entry;
 330
 331                 $usefile = 0;
 332                 if($entry eq "file") {
 333                         $usefile = 1;
 334                 } elsif($entry ne "") {
 335                         $ed = $entry;
 336                 }
 337         }
 338
 339
 340         # Generate scratch file to edit report in
 341
 342         {
 343         my($dir) = $Is_VMS ? 'sys$scratch:' : '/tmp/';
 344         $filename = "bugrep0$$";
 345         $filename++ while -e "$dir$filename";
 346         $filename = "$dir$filename";
 347         }
 348
 349
 350         # Prompt for file to read report from, if needed
 351
 352         if( $usefile and ! $file) {
 353 filename:
 354                 paraprint <<EOF;
 355
 356 What is the name of the file that contains your report?
 357
 358 EOF
 359
 360                 print "Filename: ";
 361
 362                 my($entry) = scalar(<>);
 363                 chop($entry);
 364
 365                 if($entry eq "") {
 366                         paraprint <<EOF;
 367
 368 No filename? I'll let you go back and choose an editor again.
 369
 370 EOF
 371                         goto editor;
 372                 }
 373
 374                 if(!-f $entry or !-r $entry) {
 375                         paraprint <<EOF;
 376
 377 I'm sorry, but I can't read from `$entry'. Maybe you mistyped the name of
 378 the file? If you don't want to send a file, just enter a blank line and you
 379 can get back to the editor selection.
 380
 381 EOF
 382                         goto filename;
 383                 }
 384                 $file = $entry;
 385
 386         }
 387
 388
 389         # Generate report
 390
 391         open(REP,">$filename");
 392
 393         print REP <<EOF;
 394 This is a bug report for perl from $from,
 395 generated with the help of perlbug $Version running under perl $].
 396
 397 EOF
 398
 399         if($body) {
 400                 print REP $body;
 401         } elsif($usefile) {
 402                 open(F,"<$file") or die "Unable to read report file from `$file': $!\n";
 403                 while(<F>) {
 404                 print REP $_
 405                 }
 406                 close(F);
 407         } else {
 408                 print REP <<EOF;
 409
 410 -----------------------------------------------------------------
 411 [Please enter your report here]
 412
 413
 414
 415 [Please do not change anything below this line]
 416 -----------------------------------------------------------------
 417 EOF
 418         }
 419
 420         Dump(*REP);
 421         close(REP);
 422
 423         # read in the report template once so that
 424         # we can track whether the user does any editing.
 425         # yes, *all* whitespace is ignored.
 426         open(REP, "<$filename");
 427         while (<REP>) {
 428                 s/\s+//g;
 429                 $REP{$_}++;
 430         }
 431         close(REP);
 432
 433 }
 434
 435 sub Dump {
 436         local(*OUT) = @_;
 437
 438         print OUT <<EOF;
 439
 440 ---
 441 Site configuration information for perl $]:
 442
 443 EOF
 444
 445         if( $::Config{cf_by} and $::Config{cf_time}) {
 446                 print OUT "Configured by $::Config{cf_by} at $::Config{cf_time}.\n\n";
 447         }
 448
 449         print OUT Config::myconfig;
 450
 451         if($verbose) {
 452                 print OUT "\nComplete configuration data for perl $]:\n\n";
 453                 my($value);
 454                 foreach (sort keys %::Config) {
 455                         $value = $::Config{$_};
 456                         $value =~ s/'/\\'/g;
 457                         print OUT "$_='$value'\n";
 458                 }
 459         }
 460         print OUT <<EOF;
 461
 462 ---
 463 \@INC for perl $]:
 464 EOF
 465         for my $i (@INC) {
 466             print OUT "\t$i\n";
 467         }
 468
 469         print OUT <<EOF;
 470
 471 ---
 472 Environment for perl $]:
 473 EOF
 474         for my $env (qw(PATH LD_LIBRARY_PATH
 475                     PERL5LIB PERLLIB PERL5DB
 476                     LC_ALL LC_COLLATE LC_CTYPE LC_MONETARY LC_NUMERIC LC_TIME
 477                     LANG PERL_BADLANG
 478                     SHELL HOME LOGDIR)) {
 479             print OUT "    $env",
 480                       exists $ENV{$env} ? "=$ENV{$env}" : ' (unset)',
 481                       "\n";
 482         }
 483 }
 484
 485 sub Edit {
 486         # Edit the report
 487
 488         if($usefile) {
 489                 $usefile = 0;
 490                 paraprint <<EOF;
 491
 492 Please make sure that the name of the editor you want to use is correct.
 493
 494 EOF
 495                 print "Editor [$ed]: ";
 496
 497                 my($entry) =scalar(<>);
 498                 chop $entry;
 499
 500                 if($entry ne "") {
 501                         $ed = $entry;
 502                 }
 503         }
 504
 505 tryagain:
 506         if(!$usefile and !$body) {
 507                 my($sts) = system("$ed $filename");
 508                 if( $sts ) {
 509                         #print "\nUnable to run editor!\n";
 510                         paraprint <<EOF;
 511
 512 The editor you chose (`$ed') could apparently not be run!
 513 Did you mistype the name of your editor? If so, please
 514 correct it here, otherwise just press Enter.
 515
 516 EOF
 517                         print "Editor [$ed]: ";
 518
 519                         my($entry) =scalar(<>);
 520                         chop $entry;
 521
 522                         if($entry ne "") {
 523                                 $ed = $entry;
 524                                 goto tryagain;
 525                         } else {
 526
 527                         paraprint <<EOF;
 528
 529 You may want to save your report to a file, so you can edit and mail it
 530 yourself.
 531 EOF
 532                         }
 533                 }
 534         }
 535
 536         # Check that we have a report that has some, eh, report in it.
 537
 538         my $unseen = 0;
 539
 540         open(REP, "<$filename");
 541         # a strange way to check whether any significant editing
 542         # have been done: check whether any new non-empty lines
 543         # have been added. Yes, the below code ignores *any* space
 544         # in *any* line.
 545         while (<REP>) {
 546             s/\s+//g;
 547             $unseen++ if ($_ ne '' and not exists $REP{$_});
 548         }
 549
 550         while ($unseen == 0) {
 551             paraprint <<EOF;
 552
 553 I am sorry but it looks like you did not report anything.
 554
 555 EOF
 556                 print "Action (Retry Edit/Cancel) ";
 557                 my ($action) = scalar(<>);
 558                 if ($action =~ /^[re]/i) { # <R>etry <E>dit
 559                         goto tryagain;
 560                 } elsif ($action =~ /^[cq]/i) { # <C>ancel, <Q>uit
 561                         Cancel();
 562                 }
 563         }
 564
 565 }
 566
 567 sub Cancel {
 568     1 while unlink($filename);  # remove all versions under VMS
 569     print "\nCancelling.\n";
 570     exit(0);
 571 }
 572
 573 sub NowWhat {
 574
 575         # Report is done, prompt for further action
 576         if( !$::opt_S ) {
 577                 while(1) {
 578
 579                         paraprint <<EOF;
 580
 581
 582 Now that you have completed your report, would you like to send
 583 the message to $address$andcc, display the message on
 584 the screen, re-edit it, or cancel without sending anything?
 585 You may also save the message as a file to mail at another time.
 586
 587 EOF
 588
 589                         print "Action (Send/Display/Edit/Cancel/Save to File): ";
 590                         my($action) = scalar(<>);
 591                         chop $action;
 592
 593                         if( $action =~ /^(f|sa)/i ) { # <F>ile/<Sa>ve
 594                                 print "\n\nName of file to save message in [perlbug.rep]: ";
 595                                 my($file) = scalar(<>);
 596                                 chop $file;
 597                                 if($file eq "") { $file = "perlbug.rep" }
 598
 599                                 open(FILE,">$file");
 600                                 open(REP,"<$filename");
 601                                 print FILE "To: $address\nSubject: $subject\n";
 602                                 print FILE "Cc: $cc\n" if $cc;
 603                                 print FILE "Reply-To: $from\n" if $from;
 604                                 print FILE "\n";
 605                                 while(<REP>) { print FILE }
 606                                 close(REP);
 607                                 close(FILE);
 608
 609                                 print "\nMessage saved in `$file'.\n";
 610                                 exit;
 611
 612                         } elsif( $action =~ /^(d|l|sh)/i ) { # <D>isplay, <L>ist, <Sh>ow
 613                                 # Display the message
 614                                 open(REP,"<$filename");
 615                                 while(<REP>) { print $_ }
 616                                 close(REP);
 617                         } elsif( $action =~ /^se/i ) { # <S>end
 618                                 # Send the message
 619                                 print "\
 620 Are you certain you want to send this message?
 621 Please type \"yes\" if you are: ";
 622                                 my($reply) = scalar(<STDIN>);
 623                                 chop($reply);
 624                                 if( $reply eq "yes" ) {
 625                                         last;
 626                                 } else {
 627                                         paraprint <<EOF;
 628
 629 That wasn't a clear "yes", so I won't send your message. If you are sure
 630 your message should be sent, type in "yes" (without the quotes) at the
 631 confirmation prompt.
 632
 633 EOF
 634
 635                                 }
 636                         } elsif( $action =~ /^[er]/i ) { # <E>dit, <R>e-edit
 637                                 # edit the message
 638                                 Edit();
 639                                 #system("$ed $filename");
 640                         } elsif( $action =~ /^[qc]/i ) { # <C>ancel, <Q>uit
 641                                 Cancel();
 642                         } elsif( $action =~ /^s/ ) {
 643                                 paraprint <<EOF;
 644
 645 I'm sorry, but I didn't understand that. Please type "send" or "save".
 646 EOF
 647                         }
 648
 649                 }
 650         }
 651 }
 652
 653
 654 sub Send {
 655
 656         # Message has been accepted for transmission -- Send the message
 657
 658         if($::HaveSend) {
 659
 660                 $msg = new Mail::Send Subject => $subject, To => $address;
 661
 662                 $msg->cc($cc) if $cc;
 663                 $msg->add("Reply-To",$from) if $from;
 664
 665                 $fh = $msg->open;
 666
 667                 open(REP,"<$filename");
 668                 while(<REP>) { print $fh $_ }
 669                 close(REP);
 670
 671                 $fh->close;
 672
 673         } else {
 674                 if ($Is_VMS) {
 675                         if ( ($address =~ /@/ and $address !~ /^\w+%"/) or
 676                              ($cc      =~ /@/ and $cc      !~ /^\w+%"/) ){
 677                                 my($prefix);
 678                                 foreach (qw[ IN MX SMTP UCX PONY WINS ],'') {
 679                                         $prefix = "$_%",last if $ENV{"MAIL\$PROTOCOL_$_"};
 680                                 }
 681                                 $address = qq[${prefix}"$address"] unless $address =~ /^\w+%"/;
 682                                 $cc = qq[${prefix}"$cc"] unless !$cc || $cc =~ /^\w+%"/;
 683                         }
 684                         $subject =~ s/"/""/g; $address =~ s/"/""/g; $cc =~ s/"/""/g;
 685                         my($sts) = system(qq[mail/Subject="$subject" $filename. "$address","$cc"]);
 686                         if ($sts) { die "Can't spawn off mail\n\t(leaving bug report in $filename): $sts\n;" }
 687                 } else {
 688                         my($sendmail) = "";
 689
 690                         foreach (qw(/usr/lib/sendmail /usr/sbin/sendmail /usr/ucblib/sendmail))
 691                         {
 692                                 $sendmail = $_, last if -e $_;
 693                         }
 694
 695                         paraprint <<"EOF" and die "\n" if $sendmail eq "";
 696
 697 I am terribly sorry, but I cannot find sendmail, or a close equivalent, and
 698 the perl package Mail::Send has not been installed, so I can't send your bug
 699 report. We apologize for the inconvenience.
 700
 701 So you may attempt to find some way of sending your message, it has
 702 been left in the file `$filename'.
 703
 704 EOF
 705
 706                         open(SENDMAIL,"|$sendmail -t");
 707                         print SENDMAIL "To: $address\n";
 708                         print SENDMAIL "Subject: $subject\n";
 709                         print SENDMAIL "Cc: $cc\n" if $cc;
 710                         print SENDMAIL "Reply-To: $from\n" if $from;
 711                         print SENDMAIL "\n\n";
 712                         open(REP,"<$filename");
 713                         while(<REP>) { print SENDMAIL $_ }
 714                         close(REP);
 715
 716                         close(SENDMAIL);
 717                 }
 718
 719         }
 720
 721         print "\nMessage sent.\n";
 722
 723         1 while unlink($filename);  # remove all versions under VMS
 724
 725 }
 726
 727 sub Help {
 728         print <<EOF;
 729
 730 A program to help generate bug reports about perl5, and mail them.
 731 It is designed to be used interactively. Normally no arguments will
 732 be needed.
 733
 734 Usage:
 735 $0  [-v] [-a address] [-s subject] [-b body | -f file ]
 736     [-r returnaddress] [-e editor] [-c adminaddress | -C] [-S] [-t] [-h]
 737
 738 Simplest usage:  run "$0", and follow the prompts.
 739
 740 Options:
 741
 742   -v    Include Verbose configuration data in the report
 743   -f    File containing the body of the report. Use this to
 744         quickly send a prepared message.
 745   -S    Send without asking for confirmation.
 746   -a    Address to send the report to. Defaults to `$address'.
 747   -c    Address to send copy of report to. Defaults to `$cc'.
 748   -C    Don't send copy to administrator.
 749   -s    Subject to include with the message. You will be prompted
 750         if you don't supply one on the command line.
 751   -b    Body of the report. If not included on the command line, or
 752         in a file with -f, you will get a chance to edit the message.
 753   -r    Your return address. The program will ask you to confirm
 754         this if you don't give it here.
 755   -e    Editor to use.
 756   -t    Test mode. The target address defaults to `$testaddress'.
 757   -d    Data mode (the default if you redirect or pipe output.)
 758         This prints out your configuration data, without mailing
 759         anything. You can use this with -v to get more complete data.
 760   -h    Print this help message.
 761
 762 EOF
 763 }
 764
 765 sub paraprint {
 766     my @paragraphs = split /\n{2,}/, "@_";
 767     print "\n\n";
 768     for (@paragraphs) {   # implicit local $_
 769         s/(\S)\s*\n/$1 /g;
 770             write;
 771             print "\n";
 772     }
 773
 774 }
 775
 776
 777 format STDOUT =
 778 ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ~~
 779 $_
 780 .
 781
 782 __END__
 783
 784 =head1 NAME
 785
 786 perlbug - how to submit bug reports on Perl
 787
 788 =head1 SYNOPSIS
 789
 790 B<perlbug> S<[ B<-v> ]> S<[ B<-a> I<address> ]> S<[ B<-s> I<subject> ]>
 791 S<[ B<-b> I<body> | B<-f> I<file> ]> S<[ B<-r> I<returnaddress> ]>
 792 S<[ B<-e> I<editor> ]> S<[ B<-c> I<adminaddress> | B<-C> ]>
 793 S<[ B<-S> ]> S<[ B<-t> ]>  S<[ B<-d> ]>  S<[ B<-h> ]>
 794
 795 =head1 DESCRIPTION
 796
 797 A program to help generate bug reports about perl or the modules that
 798 come with it, and mail them.
 799
 800 If you have found a bug with a non-standard port (one that was not part
 801 of the I<standard distribution>), a binary distribution, or a
 802 non-standard module (such as Tk, CGI, etc), then please see the
 803 documentation that came with that distribution to determine the correct
 804 place to report bugs.
 805
 806 C<perlbug> is designed to be used interactively. Normally no arguments
 807 will be needed.  Simply run it, and follow the prompts.
 808
 809 If you are unable to run B<perlbug> (most likely because you don't have
 810 a working setup to send mail that perlbug recognizes), you may have to
 811 compose your own report, and email it to B<perlbug@perl.com>.  You might
 812 find the B<-d> option useful to get summary information in that case.
 813
 814 In any case, when reporting a bug, please make sure you have run through
 815 this checklist:
 816
 817 =over 4
 818
 819 =item What version of perl you are running?
 820
 821 Type C<perl -v> at the command line to find out.
 822
 823 =item Are you running the latest released version of perl?
 824
 825 Look at http://www.perl.com/ to find out.  If it is not the latest
 826 released version, get that one and see whether your bug has been
 827 fixed.  Note that bug reports about old versions of perl, especially
 828 those prior to the 5.0 release, are likely to fall upon deaf ears.
 829 You are on your own if you continue to use perl1 .. perl4.
 830
 831 =item Are you sure what you have is a bug?
 832
 833 A significant number of the bug reports we get turn out to be documented
 834 features in perl.  Make sure the behavior you are witnessing doesn't fall
 835 under that category, by glancing through the documentation that comes
 836 with perl (we'll admit this is no mean task, given the sheer volume of
 837 it all, but at least have a look at the sections that I<seem> relevant).
 838
 839 Be aware of the familiar traps that perl programmers of various hues
 840 fall into.  See L<perltrap>.
 841
 842 Try to study the problem under the perl debugger, if necessary.
 843 See L<perldebug>.
 844
 845 =item Do you have a proper test case?
 846
 847 The easier it is to reproduce your bug, the more likely it will be
 848 fixed, because if no one can duplicate the problem, no one can fix it.
 849 A good test case has most of these attributes: fewest possible number
 850 of lines; few dependencies on external commands, modules, or
 851 libraries; runs on most platforms unimpeded; and is self-documenting.
 852
 853 A good test case is almost always a good candidate to be on the perl
 854 test suite.  If you have the time, consider making your test case so
 855 that it will readily fit into the standard test suite.
 856
 857 =item Can you describe the bug in plain English?
 858
 859 The easier it is to understand a reproducible bug, the more likely it
 860 will be fixed.  Anything you can provide by way of insight into the
 861 problem helps a great deal.  In other words, try to analyse the
 862 problem to the extent you feel qualified and report your discoveries.
 863
 864 =item Can you fix the bug yourself?
 865
 866 A bug report which I<includes a patch to fix it> will almost
 867 definitely be fixed.  Use the C<diff> program to generate your patches
 868 (C<diff> is being maintained by the GNU folks as part of the B<diffutils>
 869 package, so you should be able to get it from any of the GNU software
 870 repositories).  If you do submit a patch, the cool-dude counter at
 871 perlbug@perl.com will register you as a savior of the world.  Your
 872 patch may be returned with requests for changes, or requests for more
 873 detailed explanations about your fix.
 874
 875 Here are some clues for creating quality patches: Use the B<-c> or
 876 B<-u> switches to the diff program (to create a so-called context or
 877 unified diff).  Make sure the patch is not reversed (the first
 878 argument to diff is typically the original file, the second argument
 879 your changed file).  Make sure you test your patch by applying it with
 880 the C<patch> program before you send it on its way.  Try to follow the
 881 same style as the code you are trying to patch.  Make sure your patch
 882 really does work (C<make test>, if the thing you're patching supports
 883 it).
 884
 885 =item Can you use C<perlbug> to submit the report?
 886
 887 B<perlbug> will, amongst other things, ensure your report includes
 888 crucial information about your version of perl.  If C<perlbug> is unable
 889 to mail your report after you have typed it in, you may have to compose
 890 the message yourself, add the output produced by C<perlbug -d> and email
 891 it to B<perlbug@perl.com>.  If, for some reason, you cannot run
 892 C<perlbug> at all on your system, be sure to include the entire output
 893 produced by running C<perl -V> (note the uppercase V).
 894
 895 =back
 896
 897 Having done your bit, please be prepared to wait, to be told the bug
 898 is in your code, or even to get no reply at all.  The perl maintainers
 899 are busy folks, so if your problem is a small one or if it is
 900 difficult to understand, they may not respond with a personal reply.
 901 If it is important to you that your bug be fixed, do monitor the
 902 C<Changes> file in any development releases since the time you submitted
 903 the bug, and encourage the maintainers with kind words (but never any
 904 flames!).  Feel free to resend your bug report if the next released
 905 version of perl comes out and your bug is still present.
 906
 907 =head1 OPTIONS
 908
 909 =over 8
 910
 911 =item B<-a>
 912
 913 Address to send the report to.  Defaults to `perlbug@perl.com'.
 914
 915 =item B<-b>
 916
 917 Body of the report.  If not included on the command line, or
 918 in a file with B<-f>, you will get a chance to edit the message.
 919
 920 =item B<-C>
 921
 922 Don't send copy to administrator.
 923
 924 =item B<-c>
 925
 926 Address to send copy of report to.  Defaults to the address of the
 927 local perl administrator (recorded when perl was built).
 928
 929 =item B<-d>
 930
 931 Data mode (the default if you redirect or pipe output).  This prints out
 932 your configuration data, without mailing anything.  You can use this
 933 with B<-v> to get more complete data.
 934
 935 =item B<-e>
 936
 937 Editor to use.
 938
 939 =item B<-f>
 940
 941 File containing the body of the report.  Use this to quickly send a
 942 prepared message.
 943
 944 =item B<-h>
 945
 946 Prints a brief summary of the options.
 947
 948 =item B<-r>
 949
 950 Your return address.  The program will ask you to confirm its default
 951 if you don't use this option.
 952
 953 =item B<-S>
 954
 955 Send without asking for confirmation.
 956
 957 =item B<-s>
 958
 959 Subject to include with the message.  You will be prompted if you don't
 960 supply one on the command line.
 961
 962 =item B<-t>
 963
 964 Test mode.  The target address defaults to `perlbug-test@perl.com'.
 965
 966 =item B<-v>
 967
 968 Include verbose configuration data in the report.
 969
 970 =back
 971
 972 =head1 AUTHORS
 973
 974 Kenneth Albanowski (E<lt>kjahds@kjahds.comE<gt>), subsequently I<doc>tored
 975 by Gurusamy Sarathy (E<lt>gsar@umich.eduE<gt>), Tom Christiansen
 976 (E<lt>tchrist@perl.comE<gt>), and Nathan Torkington
 977 (E<lt>gnat@frii.comE<gt>).
 978
 979 =head1 SEE ALSO
 980
 981 perl(1), perldebug(1), perltrap(1), diff(1), patch(1)
 982
 983 =head1 BUGS
 984
 985 None known (guess what must have been used to report them?)
 986
 987 =cut
 988
 989 !NO!SUBS!
 990
 991 close OUT or die "Can't close $file: $!";
 992 chmod 0755, $file or die "Can't reset permissions for $file: $!\n";
 993 exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':';
 994