On Wed, Aug 4, 2010 at 6:00 PM, Carl Mäsak <cma...@gmail.com> wrote:

> Straight to an example:
>    =for head1 :image<ulteriorepicure-328651980.jpg>
>        Steaming hot C<for> loops

Interesting that this comes up right as I was composing my "help" email ;)

> 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".

I see no reason for it to not simply store any additional values away for
potential future use.

> 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.

I dislike "reserved" in this context, but understand why the namespace has
to be shared. For config options, I'd say anything should go, but people
inventing their own config options should be aware that across N release
cycles, new options may be introduced.

THAT in turn means that we need a way to add config options in a point
release in order to push out new features in reasonable time, and that means
they need their own namespace.

I'd suggest:

=for head1 :reserved('image=foo.jpg')

which is identical to:

=for head1 :image('foo.jpg')

except for the fact that any unrecognized option of the first form is an
error and any unrecognized option of the second form is allowed. That way,
new features can be added to :reserved and migrated over time to stand-alone
options after being listed in the release notes for a couple of cycles.

Aaron Sherman
Email or GTalk: a...@ajs.com

Reply via email to