does a =config overide metadata?

[finanalyst]

@thoughtstream We have eg =config code :allow< B C >, but then redefine explicitly. What happens? Take:

=config code :allow<B C>
# later first code section
=begin code
some code
=end code
# second code section
=begin code :allow<R K>
some code
=end code
# third code section
=begin code
some code
=end code

In the second code section, is the allow sequence

1. B C
2. R K
3. B C R K ?

I think it is clear that the sequence is B C in both the first and third sections.

My feeling is that if a =config directive provides a metadata option, such as :allow, explicitly providing it via the block definition over-rides the config directive. So, I think that the answer to the question above is R K. It should be made explicit in the specification, I think

[thoughtstream]

My orignal intention was that all metadata should be cumulative within its scope. That is, an explicit :allow on a =code block would be added to the implicit :allow from any up-scope =config directive(s). Which would mean that the second code section would allow: B C R K.

I can, however, see the argument for =config directives (e.g. =config code :allow<B C>) to specify default metadata that is only used in the absence of an explicit metadata (e.g. =for code :allow<R K>).

In other words, I agree that it probably makes more sense (and gives more power to the documentor) if =config values are overridden by explicit metadata. Otherwise, it's hard to see how we can turn off a configured default for a specific block. For example:

=comment All subsequent blocks allow B and C...
=config code :allow<B C>

=comment ...except this one, where we explicitly allow nothing...
=for code :allow<>
The B<> and C<> directives are usually ignored in code blocks

=comment ...or here, where we want B, but not C...
=for code :allow<B>
The B<C<>> directive is used to indicate code

Note, however, that this override only applies to metadata on a block, not to sequential (or nested) =config directives. I would expect all successive =config directives within a given lexical scope to accumulate, not override. For example:

=comment All subsequent blocks allow B and I...
=config code :allow<B I>

=code The B<return> statement I<returns> from a subroutine

=comment All subsequent blocks now also allow R..
=config code :allow<R>

=code The syntax is B<return R<EXPR>>

=begin section
=comment All subsequent blocks in this section now also allow T and K..
=config code :allow<T K>

=code Suppose the user types in: T<next value:> K<3.1415926>

=end section
=comment Now we're back to just allowing B, I, and R...

=code You can also append a I<modifier>:  return R<EXPR> B<if R<EXPR>>

To sum up: =config defaults progressively accumulate within a lexical scope, but are completely overridden by any explicit metadata on a block.

Or to put it another way, a =config specifies a set of default metadata values, which are applied when a block does not explicitly specify that particular kind of metadata.

Note that, if a =config specifies two or more kinds of metadata, those two or more kinds of default are applied independently to each subsequent block. For example:

=config code :allow<B I> :lang<Raku> :delta<v1.2.3>

=comment The following inherits the :lang and :delta defaults (because they're not explicitly overridden)
=comment So it is equivalent to:  =for code :allow<> :lang<Raku> :delta<v1.2.3>
=for code :allow<>
=code  $example = 1;

=comment The following is equivalent to:  =for code :allow<B I> :lang<Raku> :delta<v3.2.1>
=for code :delta<v3.2.1>
=code  $example = 2;

=comment The following is equivalent to:  =for code :allow<T K> :lang<Perl> :delta<v1.2.3>
=for code :lang<Perl> :allow<T K>
=code  $example = 3;

I am, of course, happy to discuss any aspect of this further, if you wish.

[finanalyst]

@thoughtstream tl;dr Agreed. I hadn't thought about the accumulation using =config and only over-riding explicit options. Though this falls out from the implementation approach I have adopted. I'll add some clarification to the spec. In addition, I noticed that creating a config for a Markup code is not cross-referenced in the section on Markup, so I'll add a cross-reference there.

[finanalyst]

@thoughtstream on "recursive" accumulation. Since :allow is a sequence, and could contain multiple values, would a =config :allow over-ride or add to the sequence? I thought first 'add', but now I think 'over-ride' Since :lang only makes sense for a single value, a subsequent =config :lang would over-write a previous one within the same scope.

In view of your observation about the need to be able to 'clear' a default, I would suggest the following:

=config code :allow< B K > :lang<Raku>
=code Here B<basis> and K<keyboard> are rendered, but R<> and V<> are verbatim, Raku reigns
=config code :allow< R V >
=code Now, B<> and K<> are verbatim, while R<replace> and V<verbatim> are active, Raku still reigns

[thoughtstream]

I can see your point, @finanalyst. And, after further thought, I agree with it. I'll address it in more detail in my review of #28.

[finanalyst]

closing as resolved