[perl #68706] problem with pod inside function arguments

On Wed Mar 20 14:07:40 2013, brad wrote:
> On Wed, Mar 20, 2013 at 3:01 PM, Aaron Trevena
> <aaron.trevena@gmail.com> wrote:
> > First stab at a patch, not sure about the phrasing, somebody more
> > familiar with the parser could probably add the type of error, but
> > that could just make it overly verbose.
> >
> > You do have to actually know what you're looking for to find where
> it
> > mentions that perl only expects pod as a new statement, so maybe it
> > could do with more explanation for beginners writing their first
> pod.
> >
> > index 9ea7935..60ebb06 100644
> > --- a/pod/perlpod.pod
> > +++ b/pod/perlpod.pod
> > @@ -645,6 +645,9 @@ empty line there before the first Pod command.
> >  Without that empty line before the "=head1", many translators
> wouldn't
> >  have recognized the "=head1" as starting a Pod block.
> >
> > +You can place a pod statement where perl expects the beginning of a
> new
> > + statement, but not within a statement, which will result in an
> error.
> > +
> >  =head2 Hints for Writing Pod
> >
> >  =over
> >
> 
> I like the text.
> 
> I think it could be included in an earlier paragraph though.
> ( about 15 lines earlier )
> 
>  You can embed Pod documentation in your Perl modules and scripts.
>  Start your documentation with an empty line, a "=head1" command at
> the
>  beginning, and end it with a "=cut" command and an empty line.  Perl
> -will ignore the Pod text.  See any of the supplied library modules
> for
> +will ignore the Pod text.  You can place a pod statement where perl
> +expects the beginning of a new statement, but not within a statement,
> +which will result in an error.  See any of the supplied library
> modules for
>  examples.  If you're going to put your Pod at the end of the file,
> and
>  you're using an __END__ or __DATA__ cut mark, make sure to put an
>  empty line there before the first Pod command
> 
> ( I'm not going to debate the Perl/perl distinction )
> 


In commit 13d0d101a48a328c651a6ca3c89e392bc65f9e1f, I applied a revision
based largely on Aaron's and Brad's suggestions.

Marking ticket resolved.

Thank you very much.
Jim Keenan

---
via perlbug:  queue: perl5 status: open
https://rt.perl.org:443/rt3/Ticket/Display.html?id=68706

• [perl #68706] problem with pod inside function arguments by James E Keenan via RT