POD and DATA question

[ajt]

Sorry if this is a stupid question, but I'll ask it anyway...

If you put pod at the end of a file, it's customary to preceed the first =head1 My title with a __END__

I have been storing stuff at the end of my scripts in a __DATA__ area for some time. I added pod to one file recently and noticed that it tried to use the pod section as my data. This is not what I want it to do...!

I assume there is more than one way to fix this, but which is best?

• When I read the DATA file handle skip until I find a magic marker - I tried this and it works, but I feel silly doing it.
• Use =cut and keep the pod in the code and out of the way, but keep it at the end in one place
• Stop storing values in my files, and read them from somewhere else
• Stop using EOF pod and use inline, see Inline POD vs. EOF POD

Naturally I want to include pod in as many of my scripts as possible, and it is convient to have values in the script it's self...

[idnopheq]

IMHO, drop option one - too confusing. Decide whether or not you want inline POD or plop it all at the end ( I prefer inline myself, especially with long code. Going inline can mean no duplication between normal comments and pod. ).

For the stored data, I think it is a toss-up on a seperate data file or making use of __DATA__ - unless others are modifying the stored values. If they will, a seperate data file is best.

YMMV
--
idnopheq
Apply yourself to new problems without preparation, develop confidence in your ability to to meet situations as they arrise.

~ Shunryu Suzuki

[demerphq]

Well, the answer is in simple terms, ignore the customary practice. POD directives and snippets can be interspersed throughout your whole code. When using POD I often intersperse code and POD so that when I change a function the POD is right there to change as well. But even if you dont like that approach you can still put it after your last statement and BEFORE the __END__ or __DATA__ tags (same thing...) like so:

package Module;
sub subroutine{}
1;

=pod

=cut

__DATA__

Incidentally if you do mix your code and pod its not necessary to use '=pod' to start pod blocks. As far as I can tell all of the =PODCOMMAND that start a pod block stop the parser. But it IS vital that you put blank lines before and after _every_ pod directive, or they will be ignored. This is one of things that IMO make inline pod less than desirable in terms of code cohesion. But the advantages of easily documenting my code *usually* override that :-)..

package Module;

=head1 Methods

=head2 subroutine1 

=cut

sub subroutine1{}

=head2 subroutine2 

=cut

sub subroutine2{}

# more code

=head1 copyright.....

=cut

1;

=pod

Blah blah

=cut

__DATA__

Yves
--
You are not ready to use symrefs unless you already know why they are bad. -- tadmc (CLPM)

[tye]

No drastic change is required. I don't think I like any of the options you have presented as much as two others. Consider:

code
pod
__DATA__
data

The only "problem" with this approach is that Perl will take the time to read the POD and parse it to the extent that is required to find an "=end" tag. If the pod is really huge or you feel the script is taking too long to start up, you could also consider:

code
__DATA__
data
__END_OF_DATA__
pod

where you have to pick an "end of data" delimiter that is unambiguous for your particular data and fix your <DATA>-reading code to recognize it.
        - tye (but my friends call me "Tye")