POD and DATA question

ajt has asked for the wisdom of the Perl Monks concerning the following question:

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...

Comment on POD and DATA question Select or Download Code

Replies are listed 'Best First'.
Re: POD and DATA question by demerphq (Chancellor) on Sep 26, 2001 at 16:34 UTC
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__` [download] 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__` [download] Yves -- You are not ready to use symrefs unless you already know why they are bad. -- tadmc (CLPM)	[reply] [d/l] [select]
Re: POD and DATA question by idnopheq (Chaplain) on Sep 26, 2001 at 15:30 UTC
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	[reply]
(tye)Re: POD and DATA question by tye (Sage) on Sep 26, 2001 at 20:28 UTC
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` [download] 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` [download] 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")	[reply] [d/l] [select]