Tad McClellan said:
Experts at Perl or experts at posting to newsgroups?
At Perl. and thanks for starting a new thread.
Your entire followup is about the "examples" below.
Where is the "more clearly written" suggestions? (or was that it?)
That was it, otherwise its very nice.
I don't see that any of the below suggestions make it more
accessible to folks that are not experts with newsgroups.
So then, did you mean that you think they make it more
accessible to folks that are not experts with Perl?
Yes
The guidelines are not about Perl, they are about posting
to this Perl newsgroup.
Yes, but posting and Perl become tangled when you request that
posts contain a short, complete program with input data,
without showing an example of what that means..
Any form that serves as a starting point for the discussion.
Actual proposed wording, not should/coulda discussion stuff.
I agree.
I should have more clearly seperated my commentary from my
actual proposed wording.
Best would be copied, then edited, from the POD version.
That is the primary version, the other formats are generated
from the POD.
Plain old text, like you have below is good enough for the
discussion. If changes are agreed on, then I'll post the
changed portions in POD before publishing the new version.
Did you follow the link in the line above that? Yes
A bunch of examples there. What's wrong with them?
Nothing, they are fantastic.
And anyway, an example of "good" or "bad" without explanation
doesn't add much value.
I disagree. Examples have flavor and set tone without explanation.
By the time we add in explanation, it's gotten to two more paragraphs,
just because they couldn't follow the link on the line above?
Yes, I followed the link, and thought the examples were excellent.
But many people won't follow a link.
I think it is worth two lines to include those examples,
and keep the link for more examples and explanation.
On top of that, the guidelines are already "too big". If we add
two paragraphs we'll need to find 2 paragraphs to delete, or risk
growing it so large that nobody will even attempt to read it all.
I'm not seeing a benefit proportional to the cost on this one...
If my hypothesis (examples better/shorter than syntax) is true,
then these two example lines can replace the three text lines
starting "Do not spend..." which were already an explanation.
+2 lines - 6 lines saves 4 lines
I like that better than what's currently in there, except for
the diagnostics part, because it does not help you _find_
programming mistakes, it only explains ones that were found
by the "use warnings" one. Plus "use diagnostics" is down
a little further anyway (along _with_ explanation).
So, does anybody object to making it like this?
You can ask perl itself to help you find common programming mistakes
by doing two things:
use strict; # see perldoc strict
use warnings; # see perldoc warnings
Thats ok, but if you added
use diagnotics; # see perldoc diagnostics
you could cut the whole paragraph that explains why,
since it is more about perl than about writing a good post.
I see regulars requesting strict and warnings all the time,
but dont remember many requests for use diagnostics.
Or drop both the use diag, and the description paragraph,
if you want a shorter guideline.
....Example deleted... reposted below inside ## start new
That part is OKish.
Now, all we need to do is find about 20 lines of less valuable
advice to delete so we'll have room for it.
What should we cut in favor of adding an example post?
According to my hypothesis,
if we list and demonstrate good posting style with an example,
we don't have to explain it as well.
So here is a suggested cutdown to replace the 53 lines:
/Speak Perl/ .. /from what you are getting./
## start new, 49 lines: saves 4 lines overall
Ask perl to help you
You can ask perl itself to help you find and understand
common programming mistakes by doing three things:
use strict; # see perldoc strict
use warnings; # see perldoc warnings
use diagnostics; # see perldoc diagnostics
Provide enough information
If you post like the example below, you will have an Extremely Good
chance of getting people to try and help you with your problem!
These features help your question win out over all the other posts.
First make a short (less than 20-30 lines) and *complete* program
that illustrates the problem you are having. You will find that
this step often solves your problem or leads you to an answer
more reliably than posting to Usenet.
Do not re-type Perl code
Use copy/paste instead of re-typing Perl code, to avoid typos.
People should be able to run your program
by copy/pasting from your article.
The following article demonstrates at least 8 good guidelines:
* show incorrect output * show desired output
* short/complete * good subject line * Speak Perl
* input __DATA__ * use warnings/strict * cut/pasteable
Subject: How do I change all 'a' to 'b' with a regexp?
I want to change all 'a' to 'b' with a regexp.
but only the first 'a' is getting changed.
This is the incorrect output of my program:
First line of text dbta
What I wanted is this, note dbtb, not dbta.
First line of text dbtb
Here is my program you can copy/paste to run.
#!/usr/local/bin/perl
use warnings;
use strict;
while (<DATA>) {
$_ =~ s/a/b/;
print $_; }
__DATA__
First line of text data
However, the above may fail the faux pas "..cursory doc search",
since the answer, s/a/b/g; is in 'perldoc perlop' near 's/PATTERN/'
## end new
Are you being serious?
We have to update the Posting Guidelines everytime perlop.pod
changes line numbers?
That's easy for you to say.
The failure here is that the documentation for the s/// operator
answers the question, and you should be reading the docs for
the operators that you use.
OK, That part was a little tongue in cheek.
We say "read the docs", so I thought I'd try it.
perldoc -f s
returns "s/// The substitution operator. See perlop."
perldoc perlop, as read from the terminal was getting too long,
so I piped it to a file and found the appropriate spot.
Showing the line numbers demonstrates both the depth
of documentation, as well as points out the "too big" issue.
If the posting guidelines are too big,
then a reference "cursory doc search" which means perldoc,
which has a one-liner, pointing to a 2000-liner
may also be unrealistic behavior to expect.
But the organization of perldoc perlop is different topic,
so I won't mention it here.
Since the guidelines request a "cursory doc search",
I put in an example.
If there is a groundswell of support for adding an example post,
let's see it here.
I at least, do not feel that it is worth it.
I have substantially edited my suggestion to
make it less than zero cost in lines of 68 characters or less.
What do you think now?
Huh?
These are style guidelines for _posting_, not for programming.
saying s/// instead of tr/// is NOT _any_ kind of failure to
follow the guidelines.
Agreed. But I think the less specific replacement answer
above is a worthwhile addition.
ie dont given an example problem without an answer,
