Hi Perl300,

Since the specification says not to begin a POD block with =cut, don't do it! :-) You never know if it might start breaking in a future version of Perl or with a different POD parser.

Update: Also, podchecker complains if you start a POD block with =cut.

Personally I'd use =begin comment with =end comment, or =for comment ..., since those are self-documenting.

Hope this helps,
-- Hauke D

For instance, I once had to edit code where =h1 (and so on) was used instead of =head1 , guess how well the syntax highlighting reacted with an not so forgiving editor?

And last but not least many (all?) podparser should fail, do you really want to rule out any documentation?

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.

For something that I expect to "live" as part of the code, I sometimes do this:

use constant DEBUG => 0;
if (DEBUG){  # block is optimized away at compile time
....         # but I can turn in "on" again easily
}            # very readable and effective
[download]

I felt pairs of "=cut" is easier to remember than "=pod" or "=begin/end comment"

Your question is more of "how do I disable code" rather than permanent multi-line textual comments which I think is a different subject.

YAW (AKA 'TIMTOWTDI" and cousins)

active code blah blah;

=head

This is a comment.  Note the blank lines.

=cut

...more code
[download]