Re: question on pod comments

[ToddAndMargo via perl6-users]

On 2020-05-30 21:28, Kevin Pye wrote:
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.


Thank you for the help!



To further confuse you, Pod documents can contain comments in a couple 
of ways.


You get use to it.

Re: question on pod comments

[Kevin Pye]

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
> >> mailto:perl6-us...@perl.org>> wrote:
> >>
> >>  >> On Sun, 31 May 2020 at 12:43, ToddAndMargo via perl6-users
> >>  >> 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 " 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 `, they do not use and `=end ` 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
>

Re: question on pod comments

[ToddAndMargo via perl6-users]

On Sun, 31 May 2020 at 13:30, ToddAndMargo via perl6-users 
mailto:perl6-us...@perl.org>> wrote:


 >> On Sun, 31 May 2020 at 12:43, ToddAndMargo via perl6-users
 >> 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 " 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 `, they do not use and `=end ` 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

Re: question on pod comments

[Kevin Pye]

As I said, they're abbreviated blocks. Keep reading.

On Sun, 31 May 2020 at 13:30, ToddAndMargo via perl6-users <
perl6-us...@perl.org> wrote:

> >> On Sun, 31 May 2020 at 12:43, ToddAndMargo via perl6-users
> >> 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 " for
> the other blocks?
>
> I am confused.
> -T
>

Re: question on pod comments

[ToddAndMargo via perl6-users]

On Sun, 31 May 2020 at 12:43, ToddAndMargo via perl6-users 
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 " for
the other blocks?

I am confused.
-T

Re: question on pod comments

[Kevin Pye]

They're not Pod comments, they're Pod abbreviated blocks:

https://docs.raku.org/language/pod

Kevin.

On Sun, 31 May 2020 at 12:43, ToddAndMargo via perl6-users <
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
>