http://qs321.pair.com?node_id=87344

Welcome to the Monastery!

This node is being developed as a collaborative effort by Perl Monks to help people who may be unfamiliar with online forums in general, or sites based on the Everything engine which drives the site in particular. This is the 'Executive Summary' - for a more detailed version of this doc and its history click New Monks. New posters to Perl Monks may (in the fullness of time) be sent a link to here to provide a useful entry point to all things Monastery and Perl. This is our attempt to help newcomers get the most out of the monastery and a language we love.

We believe there are no stupid questions, so if you can't find an answer just ask.

1. Instant answers for common Perl problems

Perl Monks has its own extensive Question and Answer section which has a different focus from the standard Perl FAQ. Most common perl coding problems are addressed in these two documents, so if you need an answer yesterday...

2. Please, please, please use the following

#!/usr/bin/perl -w # "-w" turns on all sorts of warnings about probable errors. 

use diagnostics;   # optional; causes warnings to be explained in greater detail.
use strict;        # generates compile and run-time errors for certain unsafe constructs.

For a complete discussion of this see Use strict warnings and diagnostics or die

3. Getting Answers

To get the fastest, friendliest, most useful answer we recommend you read these:
How to get the most of your question from the monks | Before You Post ...

4. Finding help

There are a number of resources at the monastery for new users:
Guide to the Monastery | Perl Monks FAQ | New Monks | Tutorials

5. SuperSearch

Super Search is an online Perl Monks utility that allows you to comprehensively search the Monastery for answers.

6. Just who/what are Perl Monks?

Basically the Monks are a group of individuals from across the globe who share a common interest in Perl. All are welcome and experience levels range from novice to guru. Everyone gets a home node that they are free to decorate as they see fit. You may like to check out some of the home nodes of our resident gurus, they are as eclectic as Perl itself but contain a wealth of knowledge and experience. You will find them here: Saints in our Book.

7. Want more?

For extensive link lists try ybiC, merlyn, outside links, or new monks for starters.

Hope to see you back soon.

Cheers!

Credits

As of Jun 10, 2001 the following monks have all contributed to this document : tachyon, petdance, LD2, VSarkiss, jptxs, Vizjerai, Brovnik, ar0n , myocom, boo_radley, TStanley, perigeeV, converter, frag, ZZamboni, arhuman, mpolo, kudra, marcink, tilly, Abigail, Vynce, Lexicon, mpolo, Odud, da. Thank you all. Increasingly loosely based on a c.l.p.m. document by Nathan Torkington.

Replies are listed 'Best First'.
Re: New Monks Info Page
by Abigail (Deacon) on Jun 11, 2001 at 00:25 UTC
    Point 4, the "Please, please, please use the following" suggests to use use diagnostics. While this can be useful sometimes, it will never "find" any more (potential) problems that use strict or -w will.

    I stress people to use strictness and warnings. That will help them prevent making mistakes. use diagnostics doesn't belong in that class.

    -- Abigail

Re: New Monks Info Page
by Lexicon (Chaplain) on Jun 11, 2001 at 05:26 UTC
    "We believe there are no stupid questions, just stupid answers."

    Not to be overly critical, but I really don't like that line. The "just stupid answers" part might discourage people from answering questions, or give them the impression that we're a bunch of jerks who aren't really funny. I personally can't think of an ending that I really like on it, though I would like some really funny catch phrase.


    I would turn #4 into the following:

    4. Please, please, please use the following

    Study these these pragmas and try putting them in your code. They help pinpoint errors, and give explanations about what's wrong, and might even explain how to fix it.
    #!/usr/bin/perl -w # Equivalent to use warnings; see below.
    use strict;        # Enforces safer, clearer code.
    use warnings;      # Detects common programming errors 
    use diagnostics;   # Explains how to fix alerts from use warnings;
    

    use strict; is useful mostly because, like in C or Java, it forces you to declare all your variables before use. This eliminates errors from misspelled variables and encourages the programmer to structure his/her program clearly. It also prevents some tricky things with references and subroutines.

    use warnings; (or almost equivalently the -w command line switch) and use diagnostics; are closely related pragmas. use warnings; detects a ton of non-fatal errors caused by syntax mistakes, context misperceptions, etc... use diagnostics; can usually tell you how to fix these problems. These two pragmas especially benifit those new to Perl who are not yet familiar with Perl's idiosyncracies.


    Update: I would provide the basic definitions here because getting a new user to start reading Perl's massive amounts of not particularly intuitive documentation is asking quite a lot. Start them out slowly, while they're still feeling their way around.

      -w is not actually equivalent to use warnings. The most obvious difference is that the warnings pragma is only available in perl5.6.0 and later.

      The other, very important difference is that -w is global, while use warnings is lexical. -w will turn on warnings for all the code used by the script, including in other files. use warnings, on the other hand, will only enable warnings for the block in which it occurs. If you put use warnings in your main script, you won't get warnings from the modules that you use.

      It is probably sufficient to recommend -w for new programmers; it works in all versions of Perl, and is the most general way of getting warnings.

        Not so fast. What if beginner is facing some lazily written module/code which fails with -w? To avoid frustration, we should suggest that:
        1. -w is lazy, version-independent way to get warnings
        2. if it fails, and they are using perl above 5.6.0, then they should use warnings after failing module was used.

          Point 2 can be hidden in link, named "if -w fails", so only point 1 will be visible.

          I am sure somebody can write it in better english. : )

          Just my $0.02.

          I think we are going to another extreme: from not enough links for newbies, to spending too much time on dicussion about links for newbies....

          Let them to do some homework, to have some fun, too.

        pmas

        To make errors is human. But to make million errors per second, you need a computer.

      A link to my strict.pm for more information about why you should use strict might be appropriate.

              - tye (but my friends call me "Tye")
      The use or not use of strict module, depend at the platform and class at,whould you programing the script.
      For example :

      If you write a native service, whith Perl Dev Kit, and use the module "perlsvc" you can't use strict module, but if you write a console program, you can use it.

      Personality, I like use that 3 modules :
      strict, warnings and diagnostics
      , and make a simple "sub" called logdump, at that make a simple file whith all output, its simple remmember for first programmers.

      Enjoy.
Re: New Monks Info Page
by Vynce (Friar) on Jun 11, 2001 at 01:01 UTC

    the first five links seem to be written in the form

    [[node]]
    which parses assymetrically and ends up being
    <LINK>(literal [)NODE</LINK>(literal ])
    which, by some miracle, actually works as a link (because the engine removes the [ from the node name before searching); but it still looks silly.

    update: bizrrely, if you got to "comment on this node" that problem goes away. maybe it is an engine problem, after all. we shall pray to the patron saint of local undocumented features for guidance in this matter.

    also,

    s/Frequently Asked Questions/Frequently Asked Questions documents/;

      As you note they were written: [ [ node ] ] Have changed to | format to avoid problems, which is consistent with the top format but not the [Reply]. It seemed to work fine for me. I presumed it would parse \[ [node] \] but have never looked to see.

      do{ s/Frequently Asked Questions/Frequently Asked Questions documents/ }
      Done

      tachyon

Re: New Monks Info Page
by mpolo (Chaplain) on Jun 11, 2001 at 11:17 UTC
    Some of these comments are very picky... I worked as a text editor1 for some time. Your mileage may vary.

    I would modify the first sentence to "...may be unfamiliar with online forums in general, or sites based on the Everything engine in particular." (I think the number of people completely ignorant of online forums who would actually find us is probably low, but there are various differences particular to this site.)

    I agree that the "no stupid questions, just stupid answers" comes off wrong, but am at a loss how to correct it and keep the "feel".

    In #3, I would reword to "PerlMonks has its own Questions and Answers section, which has a slightly different focus than the official Perl FAQ. Most common perl coding problems are addressed in these two Frequently Asked Questions documents." (one reason for this is to avoid the confusion of so many different FAQs -- thanks for not mentioning the Perl Monks Site FAQ, which would have sent this completely overboard. Also, a document doesn't "contain" a slant, it "has" one. I changed to "focus", since "slant" is often seen as a negative term.)

    In #6, a tiny change: "...home nodes of our resident gurus. They are as eclectic..." and maybe add Outside Links to the extensive link lists.

    Notes:

    1. No, I wasn't vi or emacs in a previous life.

    Update: Fixed typo. Thanks, Vynce.

Re: New Monks Info Page
by Odud (Pilgrim) on Jun 11, 2001 at 15:17 UTC
    I think I would move points 3 and 4 up to the top of the list - I guess they are what you want anyone to do first. I'm not sure about use diagnostics; versus use warnings; I suppose it all depends on your level.
    General comments:
    The document asks rather than demands.. which is the polite thing to do. But if the purpose is to reduce the number of posts that ask questions that have well-known answers, and to reduce the number of posts that don't provide sufficient info in the first instance - then perhaps the document should be more authoritative. Human nature being what it is - people will probably not look at all the recommended links, they will skim the document and then post. Maybe start with something along the lines of:
    Before posting ask yourself the following questions
    - is the question already covered in the FAQs?
    - am I using strict and warnings?
    - have I supplied enough code and data so that it is clear what I'm doing?
    etc...
    Each question would have the appropriate links - I'm sure that others more skilled in this sort of thing could improve the phrasing - the aim being to be authoritative and friendly/encouraging at the same time.

    Update:
    Has the idea of having an example question and answer been discussed? The question would illustrate all the good practices discussed in the main document e.g. what was trying to be done, what happened, code snippet included, use of HTML tags etc. The answer would show the sort of helpful reply that you get back!
    *****Example:
    I'm trying to count the number of times a file has a line with "foo" in it. The program looks like this:
    while(<>) { $line = chomp; $count++ if ($line =~ /foo/); } print $count;
    But when I run it I get:
    Use of uninitialized value in print at ./test.pl line 8, <> line 3.
    Can someone tell me what's going on?
    *****End
    For the simplest questions perhaps it would be possible to design a form that could be used?
Re: New Monks Info Page
by da (Friar) on Jun 12, 2001 at 00:04 UTC
    This document rocks. I think it really embodies what perlmonks is to me. In the interests of providing a snappy, concise document, I have some suggestions for the intro.

    If you are an experienced Perl programmer who simply has not posted before, we apologise for inconveniencing you.

    I'd strike this sentence. The document is very good info for experienced perl coders who happen to be new to perlmonks. Item #2 definitely shouldn't be apologized for.

    If you are new to Perl you will often find the answer you seek is already available, so if you need it yesterday have a look through these links.

    IMHO, strike this too. This is addressed in item #1 just below.

    We believe there are no stupid questions, so if you can't find an answer just ask.

    This is an *excellent* sentence. I would move this into item 3, for when the reader is thinking about asking questions.

    And I would move the last two sentences to the end of the document, just before credits, otherwise we're saying goodbye to them in the middle of the document they're supposed to read all of.

    With these changes, the document would flow like this:

    -----------

    Welcome to the Monastery!

    This node is being developed as a collaborative effort by Perl Monks to help people who may be unfamiliar with online forums in general, or sites based on the Everything engine which drives the site in particular. This is the 'Executive Summary' - for a more detailed version of this doc and its history click New Monks. New posters to Perl Monks may (in the fullness of time) be sent a link to here to provide a useful entry point to all things Monastery and Perl. This is our attempt to help newcomers get the most out of the monastery and a language we love.

    1. Instant answers for common Perl problems

    Perl Monks has its own extensive Question and Answer section which has a different focus from the standard Perl FAQ. Most common perl coding problems are addressed in these two documents.

    2. Please, please, please use the following

    #!/usr/bin/perl -w # "-w" turns on all sorts of warnings about probable errors. 
    
    use diagnostics;   # optional; causes warnings to be explained in greater detail.
    use strict;        # generates compile and run-time errors for certain unsafe constructs.

    3. Getting Answers

    We believe there are no stupid questions, so if you can't find an answer just ask. To get the fastest, friendliest, most useful answer we recommend you read these:
    How to get the most of your question from the monks | Before You Post ...

    -----------
    then at the bottom:
    -----------

    7. Want more?

    For extensive link lists try ybiC, merlyn, outside links, or new monks for starters.
    Hope to see you back soon.

    Cheers!

    -----------

    ___
    -DA

Re: New Monks Info Page
by Anonymous Monk on Oct 25, 2001 at 06:30 UTC
    Please do something about this line:

    Most common perl coding problems are addressed in these two documents, so if you need and answer yesterday...

    Perhaps 'needed an answer yesterday'?

    Grammar errors are a poor way to greet new Monks.

      ...need an answer.....

      Thanks, cheers

      tachyon

      s&&rsenoyhcatreve&&&s&n.+t&"$'$`$\"$\&"&ee&&y&srve&&d&&print

Re: New Monks Info Page
by tachyon (Chancellor) on Jun 11, 2001 at 16:59 UTC

    Thanks to all who have contributed to date. All suggestions incorporated where possible whilst still keeping base doc short. I am writing a new node on the benefits of strict, warnings and diagnostics to provide a user friendly intro to their benefits, avoid the man pages, and give somewhere to link. Initial draft should be up for discussion in a few hours.

    tachyon

Re: New Monks Info Page
by princepawn (Parson) on Jun 23, 2001 at 06:49 UTC
    I need to know how to make links to the Perl manpages. I know how to make links to CPAN.

      For links within perlmonks, to link to say perlfunc, use [perlman:perlfunc] to give perlman:perlfunc

      If you want to link to other external manpages then use standard HTML <a href="http://foo.com">foo website</a>

      cheers

      tachyon