develooper Front page | perl.perl5.porters | Postings from June 2008

Re: [PATCH] perlbug prose patch (and some evals, too)

Thread Previous
From:
jesse
Date:
June 7, 2008 20:33
Subject:
Re: [PATCH] perlbug prose patch (and some evals, too)
Message ID:
20080608033341.GN15928@bestpractical.com


> Great!  Personally, I think the proposed text is much clearer.  A couple
> comments below...


Thanks very much for the copyedit. I'll attach a final roll-up patch of 
all these fixes to a message in a few minutes.

> > +Please do not use $0 to send test messages, test whether perl
> > +works, or use it to report bugs in external perl modules.
> 
> I think many users may not know exactly what is meant by "external perl
> modules".  On the other hand, we want to keep this text simple and concise.
> How about "modules that are not part of the core perl distribution"?
> Perhaps with a link to a document listing the core modules?

The prose got edited down to not overflow an 80x24 screen when
displayed. 

I've changed this to:

Please do not use $0 to send test messages, test whether perl
works, or to report bugs in perl modules from CPAN.





> 
> > -Your e-mail address will be useful if you need to be contacted. If the
> > -default shown is not your full internet e-mail address, please correct it.
> > +Perl's developers may need your email address to contact you for
> > +further information about your issue or to inform you when it is
> > +resolved.  If the default shown is not your e-mail address, please
> > +correct it.
> 
> Is it "email" or "e-mail"?  :)

Standardized to 'email'.  Is there a perldoc styleguide?

> 
> > -So that you may be contacted if necessary, please enter
> > -your full internet e-mail address here.
> > +Please enter your full internet e-mail addressaso that Perl's
> > +developers can contact you with questions about your issue or to
> > +inform you that it has been resolved.
> 
> s/addressaso/address so/
> 
> 
> > -A copy of this report can be sent to your local
> > -perl administrator. If the address is wrong, please
> > -correct it, or enter 'none' or 'yourself' to not send
> > -a copy.
> > +This tool can send a copy of this report to your local perl
> > +administrator.  If the address below is wrong, please correct it,
> > +or enter 'none' or 'yourself' to stop Perlbug from sending a copy.
> 
> The new paragraph sounds awkward to me.  How about:

Indeed, though a bit less awkward than the old paragraph

> Perlbug can send a copy of this report to your local perl
> administrator.  If the address below is wrong, please correct it,
> or enter 'none' or 'yourself' to not send a copy.

"to not send a copy" feels very awkward to me, but it's what was there 
before and you re-added it, so I'm happy to cave.  I've taken your text,
modulo: s/Perlbug/$0/ to be consistent with other messages

> 
> >  	chomp (my $common_end = <<"EOF");
> > -
> > -You will probably want to use an editor to enter
> > -the report. If "$ed" is the editor you want
> > -to use, then just press Enter, otherwise type in
> > -the name of the editor you would like to use.
> > -
> > -If you would like to use a prepared file, type
> > -"file", and you will be asked for the filename.
> > +You will probably want to use a text editor to enter the body of
> > +your report. If "$ed" is the editor you want to use, then just press
> > +Enter, otherwise type in the name of the editor you would like to
> > +use.
> > +
> > +If you have already composed the body of your report, you may enter
> > +"file" "file", and Perlbug will prompt you for to enter the name
> > +of the file containing your report.
> >  EOF
> 
> s/"file" "file"/"file"/
> s/for to/to/
> 

> > -Now you need to supply the bug report. Try to make
> > -the report concise but descriptive. Include any
> > -relevant detail. If you are reporting something
> > -that does not work as you think it should, please
> > -try to include example of both the actual
> > -result, and what you expected.
> > -
> > -Some information about your local
> > -perl configuration will automatically be included
> > -at the end of the report. If you are using any
> > -unusual version of perl, please try and confirm
> > -exactly which versions are relevant.
> > +It's now time to compose your bug report. Try to make the report
> > +concise but descriptive. Please include any detail which you think
> > +might be relevant or might help the volunteers working to improve
> > +perl. If you are reporting something that does not work as you think
> > +it should, please try to include example of both the actual result,
> > +and what you expected.
> 
> s/example/examples/ (or maybe s/example/an example/)
> 
> 
> > -Is your report about a Perl module? If yes, enter its name. If not, skip.
> > +If your bug is about a Perl module rather than a core language
> > +feature, please enter it's name here. If it's not, just hit Enter
> > +to skip this question.
> 
> s/it's name/its name/
> 
> 
> > +You have finished composing your message. At this point, you have 
> > +a few options. You can:
> > +
> > +    * [Se]end the message to $address$andcc, 
> > +    * [D]isplay the message on the screen,
> > +    * [R]e-edit the message
> > +    * Display or change the message's [su]bject
> > +    * [C]ancel your report without sending anything
> > +    * Save the message to a [f]ile to mail at another time
> > +
> 
> >  	    } elsif ($action =~ /^s/i) {
> >  		paraprint <<EOF;
> > -I'm sorry, but I didn't understand that. Please type "send" or "save".
> > +The command you entered was ambiguous. Please type "send" or "save".
> >  EOF
> 
> /^s/ could also be "subject".
> 
> 
> > +If you are unable to send your report using B<perlbug> (most likely 
> > +because your system doesn't have a way to send mail that perlbug recognizes), you may be able to use this tool to compose your report and save it to a file
> > +which you can then send to B<perlbug@perl.org> using your regular mail client.
> > +
> > +In extreme cases, B<perlbug> may not work well enough on your system to
> > +guide you through composing a bug report. In those cases, you may be able to
> > +use B<perlbug -d> to get system configuration information to include in a manually composed bug report to B<perlbug@perl.org>.
> > +
> 
> Need more line-wrapping in these paragraphs.

Fixed.
> 
> > +Note that bug reports about old versions of Perl, especially those
> > +tested only on versions of Perl prior to the current stable release,
> > +are likely to receive less attention from the volunteers who build
> > +and maintain Perl than bugs in the current release.
> 
> s/those/bugs/

Rewritten to:

Note that reports about bugs in old versions of Perl, especially
those which indicate you haven't also tested the current stable
release of Perl, are likely to receive less attention from the
volunteers who build and maintain Perl than reports about bugs in
the current release.



> 
> > +This tool isn't apropriate for reporting bugs in any version of
> > +prior to Perl 5.0.
> 
> s/ of//
> 
> 
> > +If you're unsure of them meaning of an error message you've run
> > +across, B<perldoc> L<perldiag> for an explanation.  If message isn't
> > +in perldiag, it probably isn't generated by Perl.  You may have
> > +luck consulting your operating system documentation instead.
> 
> s/them meaning/the meaning/
> s/If message/If the message/


tx
> 
> 
> >  =item Do you have a proper test case?
> >  
> >  The easier it is to reproduce your bug, the more likely it will be
> > -fixed, because if no one can duplicate the problem, no one can fix it.
> > -A good test case has most of these attributes: fewest possible number
> > -of lines; few dependencies on external commands, modules, or
> > -libraries; runs on most platforms unimpeded; and is self-documenting.
> > -
> > -A good test case is almost always a good candidate to be on the perl
> > -test suite.  If you have the time, consider making your test case so
> > -that it will readily fit into the standard test suite.
> > +fixed --  If nobody can duplicate your problem, it probably won't be 
> > +addressed.
> 
> s/--  If/-- if/

ok

> 
> >  Whether you use C<perlbug> or send the email manually, please make
> > -your Subject line informative.  "a bug" not informative.  Neither is
> > -"perl crashes" nor "HELP!!!".  These don't help.
> > -A compact description of what's wrong is fine.
> > +your Subject line informative.  "a bug" not informative.  Neither
> > +is "perl crashes" nor is "HELP!!!".  These don't help.  A compact
> > +description of what's wrong is fine.
> 
> s/"a bug" not informative/"a bug" is not informative/
> (that was carried over from the original)
> 
> 
> >  Having done your bit, please be prepared to wait, to be told the bug
> > -is in your code, or even to get no reply at all.  The Perl maintainers
> > -are busy folks, so if your problem is a small one or if it is difficult
> > -to understand or already known, they may not respond with a personal reply.
> > -If it is important to you that your bug be fixed, do monitor the
> > -C<Changes> file in any development releases since the time you submitted
> > -the bug, and encourage the maintainers with kind words (but never any
> > -flames!).  Feel free to resend your bug report if the next released
> > -version of perl comes out and your bug is still present.
> > +is in your code, or possibly to get no reply at all.  The volunteers who
> > +maintain Perl are busy folks, so if your problem is an obvious bug in your own code, is difficult to understand or is a duplicate of an existing report, you 
> > +may not receive a personal reply.
> > +
> > +If it is important to you that your bug be fixed, do monitor the perl5-porters@perl.org mailing list, the commit logs to development versions of Perl
> > +and encourage the maintainers with kind words or offers of frosty beverages. 
> > +(Please do be kind to the maintainers. Harassing or flaming them is likely to
> > +have the opposite effect of the one you want.)
> 
> That should be "...do monitor the perl5-porters@perl.org mailing list and
> the commit logs to development versions of Perl, and encourage the
> maintainers with kind words or offers of frosty beverages."  'Monitor A and
> B, and encourage C', rather than 'Monitor A, B, and encourage C'.
> 
> More line-wrapping, please.
> 

nod

> 
> > +
> > +Feel free update the ticket about your bug on http://rt.perl.org 
> > +if a new version of Perl is released and your bug is still present.
> 
> s/update/to update/
> 
> 
> 
> I hope that was helpful!

Thanks. update incoming
> 
> Ronald
> 

-- 

Thread Previous


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About