Straight to an example:
=for head1 :image<ulteriorepicure-328651980.jpg>
Steaming hot C<for> loops
As far as parsing goes, that's valid Perl 6 Pod. You're perhaps more
used to seeing it as '=head1', but S26 asserts the equivalence of
these two forms. The reason I'm using the paragraph block form here is
that the abbreviated block form doesn't take config options, and my
question is about those.
S26 doesn't mention the config option :image in connection with
'=head1'. (As it shouldn't, I'm using it for my own nefarious
purposes.)
I went looking for whether this is allowed or not. Is this allowed?
S26 only tells me this about config options:
"Pod predefines a small number of standard configuration options that
can be applied uniformly to any built-in block type."
To me, "predefines" could mean either "we made these for you; use only
those" or "we made these for you; go wild and invent your own too if
you wish".
It also has this to say about block types:
"Typenames that are entirely lowercase (for example: C<=begin head1>)
or entirely uppercase (for example: C<=begin SYNOPSIS>) are reserved."
But it's clear from the context of that sentence that this only
pertains to blocks. There's no indication that this goes for the
config options as well.
Unless I missed the place, S26 simply doesn't specify whether
unrecognized config options to built-in blocks should cause the parser
to blow up or not. Should it?
I guess one could make this question really interesting by throwing in
issues of forward-compatibility and such. Should we expect to be able
to parse Pod "from the future", i.e. using versions of the Perl 6 spec
with more Pod options defined for the built-in blocks?
I'm not savvy enough to attack that last question, but apart from
that, I think allowing/ignoring unrecognized config options seems
reasonable.
The other path that seems reasonable to me would be to use the same
naming scheme as for the block types, i.e. reserve all-upper and
all-lower forms (and die if an unrecognized one of this form is
encountered), and let the custom ones live in the namespace of
mixed-case identifiers. That sounds sane to me as well; the only
question is whether that much structure is needed for config options.
// Carl
