On Fri, Jul 2, 2010 at 17:33, brian d foy <brian.d....@gmail.com> wrote: > In article > <aanlktimm-hiuf86ev9ykytsvpucpj1le7hatxbxnq...@mail.gmail.com>, Chas. > Owens <chas.ow...@gmail.com> wrote: > >> No, you understood me, it is just that the FAQ doesn't do a good job >> for those two questions. That is something we need to be doing >> better. > > The FAQ doesn't do a good job of teaching you Perl because it's not the > FAQs job to teach you Perl. The FAQ is not there to teach you syntax or > programming. snip
I think "How do I open a file?" and "How do I trim a string?" are frequently asked questions. Certainly they are asked more often than "How can I open a filehandle to a string?". snip > As for the particular comment that's started this long thread, the idea > that we should add 'use XXX' to every snippet, I have two rule > > * The documentation for a particular version of perl assumes that perl > is used for its examples. snip Yes an no. Between perldoc.perl.org defaulting to the latest version and many production versions lagging behind what may be installed on development machines, the version of Perl you are targeting might not be the same as the version of Perl you are running (e.g. I have Perl 5.12.1 on my machine, but production is 5.8.8). snip > * Never use features that distract the reader. Using 'use 5.010' just > to get say() is a distraction unless you are talking about say() > specifically. snip For the most part I agree with this. In fact, I dislike print statements in examples in general. snip > * Only note the version when it really matters. For instance, you have > to somehow pull in the Switch statement. snip This is pretty much what my amended position is (the fifth scenario in my earlier email). If the example needs a specific version, or the feature only works on a specific version, then the pragma that turns on the feature should be present. Similarly, if we are going to use a function from a module, we should use the module. snip > * Note that since 5.10, 'use 5.xxx' now has side effects. Using that > blindly may cause other things in a program to break, although the > readers may not know why. snip I am actually counting on those side effects being present. On this same topic, I have noticed that there doesn't seem to be an easily discoverable way to find out what "use <VERSION>;" does. We are training users to type "perldoc <thing after use>" to find out what "<thing after use>" does. Typing "perldoc 5.012" yields 'No documentation found for "5.012".'. Instead you have to type "perldoc -f use" and then "perldoc feature". Should we add a symlink to the delta for that version, or maybe a new document for each version that explains what the consequences of specifying that version are? snip > * Ignore any Perl released more than 10 years ago. snip I think we are in agreement here. -- Chas. Owens wonkden.net The most important skill a programmer can have is the ability to read.
