view release on metacpan or  search on metacpan

pod/perlpodspec.pod  view on Meta::CPAN

  =end html

  =begin :biblio

  =end :biblio

Incidentally, note that there's no easy way to express a data
paragraph starting with something that looks like a command.  Consider:

  =begin stuff

  =shazbot

  =end stuff

There, "=shazbot" will be parsed as a Pod command "shazbot", not as a data
paragraph "=shazbot\n".  However, you can express a data paragraph consisting
of "=shazbot\n" using this code:

  =for stuff =shazbot

The situation where this is necessary, is presumably quite rare.

Note that =end commands must match the currently open =begin command.  That
is, they must properly nest.  For example, this is valid:

  =begin outer

  X

  =begin inner

  Y

  =end inner

  Z

  =end outer

while this is invalid:

  =begin outer

  X

  =begin inner

  Y

  =end outer

  Z

  =end inner

This latter is improper because when the "=end outer" command is seen, the
currently open region has the formatname "inner", not "outer".  (It just
happens that "outer" is the format name of a higher-up region.)  This is
an error.  Processors must by default report this as an error, and may halt
processing the document containing that error.  A corollary of this is that
regions cannot "overlap". That is, the latter block above does not represent
a region called "outer" which contains X and Y, overlapping a region called
"inner" which contains Y and Z.  But because it is invalid (as all
apparently overlapping regions would be), it doesn't represent that, or
anything at all.

Similarly, this is invalid:

  =begin thing

  =end hting

This is an error because the region is opened by "thing", and the "=end"
tries to close "hting" [sic].

This is also invalid:

  =begin thing

  =end

This is invalid because every "=end" command must have a formatname
parameter.

=head1 SEE ALSO

L<perlpod>, L<perlsyn/"PODs: Embedded Documentation">,
L<podchecker>

=head1 AUTHOR

Sean M. Burke

=cut