develooper Front page | perl.perl5.porters | Postings from March 2013

Re: [perl #68706] problem with pod inside function arguments

Thread Previous | Thread Next
From:
Brad Gilbert
Date:
March 20, 2013 21:07
Subject:
Re: [perl #68706] problem with pod inside function arguments
Message ID:
CAD2L-T0T1QMNrnxmj3EuJ4OfOfJeYkstCC7zUjgJdC+0grvh1Q@mail.gmail.com
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 )

Thread Previous | Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About