While the original documentation you were referring to called them Pod comments, that's not really accurate. The full documentation (to which I referred you) calls them "Pod documents" which is much more descriptive. The Pod document is parsed by Rakudo, and the contents can be used. Pod documents are structured, and need to be consistent. Unless you do something to explicitly refer to the pod, it is ignored by the running program, and is a comment in that sense.
To further confuse you, Pod documents can contain comments in a couple of ways. Note that the documentation at docs.raku.org is written in Pod (in this case in files containing no normal raku code). On Sun, 31 May 2020 at 13:50, ToddAndMargo via perl6-users < perl6-us...@perl.org> wrote: > >> On Sun, 31 May 2020 at 13:30, ToddAndMargo via perl6-users > >> <perl6-us...@perl.org <mailto:perl6-us...@perl.org>> wrote: > >> > >> >> On Sun, 31 May 2020 at 12:43, ToddAndMargo via perl6-users > >> >> <perl6-us...@perl.org <mailto:perl6-us...@perl.org> > >> <mailto:perl6-us...@perl.org <mailto:perl6-us...@perl.org>>> wrote: > >> >> > >> >> Hi All, > >> >> > >> >> I am somewhat confused about pod comments: > >> >> > >> >> https://docs.raku.org/language/syntax#Pod_comments > >> >> > >> >> Seems pretty straight forward. But when I look at > >> >> > >> >> > >> > https://github.com/tadzik/perl6-Config-INI/blob/master/lib/Config/INI.pm > >> >> > >> >> starting line 45, I see > >> >> > >> >> =begin pod > >> >> =head1 NAME > >> >> =head1 SYNOPSIS > >> >> =head1 DESCRIPTION > >> >> =end pod > >> >> > >> >> I see no "=end xxx" > >> >> > >> >> =end head1 NAME > >> >> =end head1 SYNOPSIS > >> >> =end head1 DESCRIPTION > >> >> > >> >> What am I missing? > >> >> > >> >> Many thanks, > >> >> -T > >> >> > >> > >> On 2020-05-30 20:20, Kevin Pye wrote: > >> > They're not Pod comments, they're Pod abbreviated blocks: > >> > > >> > https://docs.raku.org/language/pod > >> > > >> > Kevin. > >> > > >> > >> I see that: > >> > >> https://docs.raku.org/language/pod#Delimited_blocks > >> =begin head1 > >> Top Level Heading > >> =end head1 > >> > >> So back to my original question, where are the "=end xxxx" for > >> the other blocks? > >> > >> I am confused. > >> -T > >> > > On 2020-05-30 20:37, Kevin Pye wrote: > > As I said, they're abbreviated blocks. Keep reading. > > > > > https://docs.raku.org/language/pod#Abbreviated_blocks > Abbreviated blocks > > Abbreviated blocks begin by an '=' sign, which is followed immediately > by the typename of the block. All following data are part of the > contents of the block, thus configuration data cannot be specified for > an abbreviated block. The block ends at the next Pod6 directive or the > first blank line. > > =head1 Top level heading > > > So basically, since they did not contain a "begin", > `=begin xxxx`, they do not use and `=end xxxx` and > the terminate themselves after the first blank line. > > Do I FINALLY have it down? > > Also, in > > https://github.com/tadzik/perl6-Config-INI/blob/master/lib/Config/INI.pm > > since these Abbreviated Block were inside his > > =begin pod > =end pod > > He was just being fancy since they would have no > effect anyway as they were inside a comment already? > > -T >
