develooper Front page | perl.beginners | Postings from February 2002

Re: UFO (Unidentified Formatting Observation) on the web....

Thread Previous
From:
Jeff 'japhy' Pinyan
Date:
February 1, 2002 07:49
Subject:
Re: UFO (Unidentified Formatting Observation) on the web....
Message ID:
Pine.GSO.4.21.0202011044570.27903-100000@crusoe.crusoe.net
On Feb 1, Ron Goral said:

>I have a very beginner's question.  I've just been looking at the code for a
>library file and noticed some, to me, very peculiar things.  First, there is
>text that is not commented, it is just typed in place.  Why does this not
>interfere with the script?  Second, there are expressions like "=pod" and
>"=cut" and "=head1".  What do these mean?  Third, there is a "1;" at the
>very end of the file.  I've seen that before, but what is the purpose?
>Fourth, there is text like "I<delete_cookie> blah blah" and "B<MUST>" (I
>assume that this last is a comment on text decoration).  Can anyone tell me
>what these mean?  Is there a difference in a library file and a regular
>script file that allows for this?   Is there some tutorial or documentation
>about the differences in writing a library/module versus a normal script
>file?

The text that "is not commented", you will find, is placed inbetween the
=XYZ statements.  The =XYZ statements are called Pod directives, and the
I<...> and B<...> statements are Pod markup.  Pod is "Plain Old
Documentation", a very simple markup language for documenting Perl
programs.

Read 'perldoc perlpod' for information on Pod.

The '1;' at the end of the file is there so that the file returns a true
value when Perl require()s it.  See 'perldoc -f require'.

As for how a library or module differs from a "normal" program, it's
basically how an encyclopedia differs from your term paper.  You READ your
term paper, and it makes references to places in the encyclopedia -- you
wouldn't use the entire encyclopedia as your term paper.

-- 
Jeff "japhy" Pinyan      japhy@pobox.com      http://www.pobox.com/~japhy/
RPI Acacia brother #734   http://www.perlmonks.org/   http://www.cpan.org/
** Look for "Regular Expressions in Perl" published by Manning, in 2002 **
<stu> what does y/// stand for?  <tenderpuss> why, yansliterate of course.


Thread Previous


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About