From @jidanni

$ man perlop
  A common mistake is to try to separate the words with comma or
  to put comments into a multi-line "qw"-string. For this rea-
  son, the "use warnings" pragma and the -w switch (that is, the
  $^W variable) produces warnings if the STRING contains the ","
  or the "#" character.

OK, well if these are so common mistakes, remedies should be
mentioned. E.g., say "superfluous commas", and say the best way to
still do comments in this case.

I mean otherwise the only alternative you imply is dropping comments.

The user wants to do %table=qw(
#group 1
bla pla
#group 2
mla fla
) etc.

And perhaps even have the warnings tell the user to see perlop.

From @nwc10

On Sun, Oct 31, 2004 at 07​:14​:07AM -0000, Dan Jacobson wrote​:

# New Ticket Created by Dan Jacobson
# Please include the string​: [perl #32233]
# in the subject line of all future correspondence about this issue.
# <URL​: http​://rt.perl.org​:80/rt3/Ticket/Display.html?id=32233 >

$ man perlop
A common mistake is to try to separate the words with comma or
to put comments into a multi-line "qw"-string. For this rea-
son, the "use warnings" pragma and the -w switch (that is, the
$^W variable) produces warnings if the STRING contains the ","
or the "#" character.

OK, well if these are so common mistakes, remedies should be
mentioned. E.g., say "superfluous commas", and say the best way to
still do comments in this case.

I mean otherwise the only alternative you imply is dropping comments.

The user wants to do %table=qw(
#group 1
bla pla
#group 2
mla fla
) etc.

And perhaps even have the warnings tell the user to see perlop.

I don't think that any of this is necessary. perlop is attempting to be
a reference, not a tutorial. What you are suggesting increases the
verbosity and length, whilst (in my opinion) giving insufficient gain.

The following is not a personal criticism, but a general observation​:

The perl documentation is already too large. Nearly every change anyone
suggests adds to it, and is self contained, considering only that part
of the documentation, rather than the entire documentation as a whole.
Unsurprisingly the documentation is getting larger and less coherent.
It's already too large for people to actually bother reading most of it
before asking questions, and so I'm not convinced that wholesale increasing
the detail in localised regions benefits the documentation as a whole.

Nicholas Clark

The RT System itself - Status changed from 'new' to 'open'

From @ysth

On Sun, Oct 31, 2004 at 07​:14​:07AM -0000, Dan Jacobson wrote​:

$ man perlop
A common mistake is to try to separate the words with comma or
to put comments into a multi-line "qw"-string. For this rea-
son, the "use warnings" pragma and the -w switch (that is, the
$^W variable) produces warnings if the STRING contains the ","
or the "#" character.

OK, well if these are so common mistakes, remedies should be
mentioned. E.g., say "superfluous commas", and say the best way to
still do comments in this case.

The warning is given whether the comma is superfluous or not
(i.e. for qw/a, b/ whether you intended ("a", "b") or ("a,", "b")).

There is no "best way" to do comments in a quoted string. Are the
remedies suggested in the perldiag entries for the warnings sufficient?

$ perl -e'use diagnostics; 0&&qw/ # /'
Possible attempt to put comments in qw() list at -e line 1 (#1)
  (W qw) qw() lists contain items separated by whitespace; as with literal
  strings, comment characters are not ignored, but are instead treated as
  literal data. (You may have used different delimiters than the
  parentheses shown here; braces are also frequently used.)

  You probably wrote something like this​:

  @​list = qw(
  a # a comment
  b # another comment
  );

  when you should have written this​:

  @​list = qw(
  a
  b
  );

  If you really want comments, build your list the
  old-fashioned way, with quotes and commas​:

  @​list = (
  'a', # a comment
  'b', # another comment
  );

$ perl -e'use diagnostics; 0&&qw/ , /'
Possible attempt to separate words with commas at -e line 1 (#1)
  (W qw) qw() lists contain items separated by whitespace; therefore
  commas aren't needed to separate the items. (You may have used
  different delimiters than the parentheses shown here; braces are also
  frequently used.)

  You probably wrote something like this​:

  qw! a, b, c !;

  which puts literal commas into some of the list items. Write it without
  commas if you don't want them to appear in your data​:

  qw! a b c !;

(The 0&& suppresses a void context warning.)

@rgs - Status changed from 'open' to 'rejected'

From @jidanni

D> remedies suggested in the perldiag entries for the warnings sufficient?

Well, OK, but if the solution were mentioned on perlop, it wouldn't
"encourage Johnny to pull the fire alarm to learn about
firemen". I.e., triggering errors to learn the answer.

Also there is the case when qw would be great for 10000 lines, except
we want to put one comment in the middle. If perldiag is to be
verbose it might mention how to do that too.

< The perl documentation is already too large.

I'm just pointing out what dark areas new users encounter when
equipped with just the tree starting at 'man perl', perldoc, and
sometimes accessing the llama book.

From @schwern

On Mon, Nov 01, 2004 at 09​:05​:56AM +0800, Dan Jacobson wrote​:

D> remedies suggested in the perldiag entries for the warnings sufficient?

Well, OK, but if the solution were mentioned on perlop, it wouldn't
"encourage Johnny to pull the fire alarm to learn about
firemen". I.e., triggering errors to learn the answer.

The common mode of failure is for a user to put comments and commas into a
qw without really thinking about whether they knew they don't do what they
think they do or not. Mentioning the work arounds in perlop isn't really
going to help that.

Besides, the "solutions" in perldiag really amount to "don't do that" which,
while accurate, aren't particularly enlightening. About all I can see adding
to perlop is perhaps "If you want comments or commas use a normal list" which
sums up the perldiag recommendations succinctly.

Also there is the case when qw would be great for 10000 lines, except
we want to put one comment in the middle. If perldiag is to be
verbose it might mention how to do that too.

If you're using qw for 10,000 lines of data you're in more trouble than
perldiag can really help you with. Hell, you're in trouble at 100. Its
really not suited for that sort of thing. Its well out of the scope of
perldiag or even the core language documentation to explain why you don't
type out and hard-code a 10,000 element list, qw or not.

--
Michael G Schwern schwern@​pobox.com http​://www.pobox.com/~schwern/
Do you have a map? Because I keep getting lost in your armpits.

From @jidanni

D> If you're using qw for 10,000 lines of data you're in more trouble than
D> perldiag can really help you with. Hell, you're in trouble at 100.

Hmm, then perlop should mention that. Otherwise we might just think
$ cat top giant_table_of_pairs bottom > program.pl
is OK.

I'll got a mail telling me the perl-documentation list is a better
place to post these. OK, I'll try that next time.