develooper Front page | perl.perl6.users | Postings from December 2021

Implementation of documented POD6 behaviour

Thread Next
From:
Richard Hainsworth
Date:
December 30, 2021 12:17
Subject:
Implementation of documented POD6 behaviour
Message ID:
2cc5b91c-8701-fc1b-3146-d81117c81bf5@gmail.com
I plan to use the POD6 metadata functionality a lot in a new module. It 
would be far better to separate out the meta data into lines.

In https://docs.raku.org/language/pod I find

"In the future, the configuration section may be extended over 
subsequent lines by starting those lines with an |=| in the first 
(virtual) column followed by a whitespace character."

with a footnote that it is not implemented.

Is there some indication when it will be implemented?

I am willing to look at the the Rakudo code and create a PR to implement 
this functionality. Is there any reason not to do this, eg., planned 
changes such as changing to RakuAST.

Similar to the above, there are implied POD6 behaviours that do not 
work, in particular embedded POD6.

Two examples:

- Pod6 tables. A cell of a POD6 table may not contain a POD6 table. Thus 
a table of tables is not possible.

Note that there is a test in the Pod::To::HTML test suite that tests for 
this behaviour. It is TODO'd because it does not work, but it is 
expected it should work.

The current behaviour is to treat the embedded table as an unknown block 
type.

- Definition lists.

It is not possible to include embedded POD6 in the contents part of a 
definition.

More detail on these.

The following program:

=begin pod

=for head1 :attr('key') :battr<key2>
This is a working header

=for head1
= attr('key) :battr<key2>
This is what is being tested

=defn Bad boy
When you B<try>to include formating.

Outside a definition list B<formating>is treated differently.

=end pod
say $=pod;

Produces the following output:

[Pod::Block::Named{:name("pod")}
   Pod::Heading{:config("\$\{:attr(\"key\"), :battr(\"key2\")}"), :level("1")}
     Pod::Block::Para
       This is a working header
   Pod::Heading{:level("1")}
     Pod::Block::Para
       = attr('key) :battr<key2> This is what is being tested
   Pod::Defn{:term("Bad boy")}
     Pod::Block::Para
       When you B<try> to include formating.
   Pod::Block::Para
     Outside a definition list
     Pod::FormattingCode{:type("B")}
       formating
      is treated differently.
]

 From the above, it can be seen that
(1) the config part of the second header does not contain extra key/value pairs.
This is consistent with the footnote in the documentation.
(2) the contents part (which is shown by say as being indented from the Pod:Block line) of a Pod::Defn
is treated differently from the contents part of a Pod::Block::Para. This is not documented and is unexpected.

I have not shown the POD6 table behaviour, but its similar to the Pod::Defn behaviour.


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