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
