G'day Perl300,

I would strongly recommend not using pairs of =cut commands. It raises pod syntax errors (which you've already identified in perlpodspec: =cut but also see below). A further issue, if you were ignoring the syntax errors, is that it makes your code very difficult to read. I'd probably choose something like:

# ... some code here ...

=for comment

... comments ...

=cut

# ... some more code here ...
[download]

Notice the blank lines. Most POD commands need blank lines before and/or after them. perlpod: =cut has:

"To end a Pod block, use a blank line, then a line beginning with "=cut", and a blank line after it. This lets Perl (and the Pod formatter) know that this is where Perl code is resuming. (The blank line before the "=cut" is not technically necessary, but many older Pod processors require it.)"

If you're not already familiar with it, take a look at the podchecker utility.

[podchecker is part of the core distribution and should already be installed. It's probably in the same directory as your perl executable.]

It will tell you about problems with blank lines, e.g.

$ podchecker podchecker_test_4.txt
*** ERROR: Apparent command =head2 not preceded by blank line at line 
+7 in file podchecker_test_4.txt
podchecker_test_4.txt has 1 pod syntax error.
[download]

$ cat podchecker_test_4.txt
#!/usr/bin/env perl

use strict;
use warnings;

=head1 heading 1
=head2 heading 1.2
[download]

And various other syntax errors, e.g.

$ podchecker podchecker_test_5.txt 
*** ERROR: =over on line 6 without closing =back at line EOF in file p
+odchecker_test_5.txt
podchecker_test_5.txt has 1 pod syntax error.
[download]

cat podchecker_test_5.txt
#!/usr/bin/env perl

use strict;
use warnings;

=over 4

whatever
[download]

I recommend you make liberal use of this utility while you're learning to code POD. Here's what I got with the code you posted:

$ podchecker podchecker_test_1.txt
podchecker_test_1.txt does not contain any pod commands.
[download]

cat podchecker_test_1.txt
#!/opt/apps/perl/perl5220/bin/perl

use strict;
use warnings;

print "Line1\n";

print "Line2\n";
=cut
print "Line3\n";
=cut
print "Line4\n";
=cut
print "Line5\n";
=cut
print "Line6\n";
[download]

I added blank lines around all the =cut commands (which are now recognised as POD):

$ podchecker podchecker_test_2.txt
*** ERROR: Spurious =cut command at line 9 in file podchecker_test_2.t
+xt
*** ERROR: Spurious =cut command at line 13 in file podchecker_test_2.
+txt
*** ERROR: Spurious =cut command at line 17 in file podchecker_test_2.
+txt
*** ERROR: Spurious =cut command at line 21 in file podchecker_test_2.
+txt
podchecker_test_2.txt has 4 pod syntax errors.
[download]

cat podchecker_test_2.txt
#!/usr/bin/env perl

use strict;
use warnings;

print "Line1\n";
print "Line2\n";

=cut

print "Line3\n";

=cut

print "Line4\n";

=cut

print "Line5\n";

=cut

print "Line6\n";
[download]

I then applied my =for comment suggestion from earlier (syntactically correct and improved readability):

$ podchecker podchecker_test_3.txt
podchecker_test_3.txt pod syntax OK.
[download]

cat podchecker_test_3.txt
#!/usr/bin/env perl

use strict;
use warnings;

print "Line1\n";
print "Line2\n";

=for comment

print "Line3\n";

=cut

print "Line4\n";

=for comment

print "Line5\n";

=cut

print "Line6\n";
[download]

I believe the intention of the code examples in perlpodspec: =cut:

=cut

=cut The documentation ends here.

...
[download]

is to show different, and entirely separate, examples of usage. It is not trying to suggest you should follow one =cut with another; indeed, the text immediately following the code indicates this would be syntactically incorrect and should cause a fatal error:

"... error to try to start a Pod block with a "=cut" command ... Pod processor must halt parsing ... emit a warning."

See also: perlpod, perlpodstyle, Test::Pod, and Test::Pod::Coverage.

---

---

Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!

Titles consisting of a single word are discouraged, and in most cases are disallowed outright.

Read Where should I post X? if you're not absolutely sure you're posting in the right place.

Please read these before you post! —

• How do I compose an effective node title?
• How do I post a question effectively?
• Markup in the Monastery

Posts may use any of the Perl Monks Approved HTML tags:

a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr

You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)

	For:		Use:
	&		&
	<		&lt;
	>		&gt;
	[		&#91;
	]		&#93;

Link using PerlMonks shortcuts! What shortcuts can I use for linking?

See Writeup Formatting Tips and other pages linked from there for more info.