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 ...
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.
$ cat podchecker_test_4.txt
#!/usr/bin/env perl
use strict;
use warnings;
=head1 heading 1
=head2 heading 1.2
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.
cat podchecker_test_5.txt
#!/usr/bin/env perl
use strict;
use warnings;
=over 4
whatever
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.
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";
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.
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";
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.
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";
I believe the intention of the code examples in
perlpodspec: =cut:
=cut
=cut The documentation ends here.
...
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.
| 
