From an email conversation between @thoughtstream and @finanalyst after identifying an error. This is to document the issue and its resolution.
From @thoughtstream
A nested code block within an item block is NOT rendered as code (as it should be).
For example:
=begin rakudoc :!toc
=TITLE Bug
=SUBTITLE code blocks inside item blocks
=begin item
B<=alias> specifies a text substitution available in subsequent C<A<...>> markup instructions.
The general syntax for an alias directive is:
=begin code :lang<RakuDoc> :allow<R>
=alias R<ALIAS_NAME> Text for substitution
= Optional extra text
=end code
=end item
=end rakudoc
Reply from @finanalyst:
The issue does raise a question about what may be the generic content of extended variants of item/defn/para/nested/head.
We discussed some of this question when considering acceptable content for enumerated extended blocks.
Each of these blocks are typically thought to have single strings, which may contain markup. FYI The implementation hitch is that the RakuAST parser explicitly generates a Paragraph when there is embedded markup, but leaves a bare string otherwise. Not creating a rendered paragraph when a string is expected was handled in an ad hoc manner, but now needs some thought.
When discussing embedded RakuDoc for a head block, we decided that RakuDoc markup codes are acceptable, but blocks are not.
However, in the Rakuast::RakuDoc::Render, this logic is extended to item/defn/para/nested. Code blocks, as opposed to C<> markup, are thus excluded from item.
More formally, perhaps this would be:
An extended paragraph-level block may contain embedded format codes, but may not contain another paragraph-level block, unless explicitly permitted.
@thoughtstream stated that an item should be able to contain a code block, and we also discussed what a paragraph embedded in a paragraph should look like when numbered (the counter is incremented for the first para, but not for subsequent ones).
This topic is more general that =code inside =item.
What about =item inside =item {=begin item\nITEM content\n=item inner item\n=end item}? Should this be the same as =item ITEM CONTENT\n=item inner item} or {=item ITEM content=item2 inner item\n} or something Renderer dependent?
@thoughtstream response:
The fact that we ran into this problem in RakuDoc source that we'd written ourselves
suggests to me that we need a more coherent answer to "what can be nested in what?"
When discussing embedded RakuDoc for a head block, we decided that
RakuDoc markup codes are acceptable, but blocks are not.
And I still think that is entirely reasonable.
More formally, perhaps this would be:
An extended paragraph-level block may contain embedded format codes, but
may not contain another paragraph-level block, unless explicitly permitted.
I can see why that would seem a reasonable position. I might even agree with it,
except that our own spec found reasons to embed code blocks inside item blocks. :-(
And I can already think of other combinations that might also be entirely reasonable.
This topic is more general that =code inside =item.
Agreed.
What about =item inside =item {=begin item\nITEM content\n=item inner
item\n=end item}? Should this be the same as =item ITEM CONTENT\n=item
inner item} or {=item ITEM content=item2 inner item\n} or something
Renderer dependent?
We actually address that particular case in the spec, and indicate that
it's an error. But the point stands: there are numerous types of blocks
and we need a consistent rule for which blocks can be nested in which other blocks.
So here's a first attempt at such a rule...
=item Abbreviated- and extended-form blocks can I<never> contain any other kind of block.
=item The delimited form of the following D<atomic blocks> may I<B<not>> contain any other kind of block:
C<citation>, C<code>, C<comment>, C<data>, C<formula>, C<head>, C<input>, C<output>, C<SEMANTIC>
=item The delimited form of the following D<paragraph-level blocks> may contain only atomic blocks:
C<defn>, C<item>, C<para>
=item The delimited form of the following D<container blocks> may contain I<any> other kind of block
(including other container blocks): C<cell>, C<nested>, C<pod>, C<rakudoc>, C<section>
=item The delimited form of the C<table> block may directly contain only C<cell> and/or C<comment> blocks.
I<(Note, however, that C<cell> blocks may themselves contain any other kind of block, which means
that C<table> blocks may B<indirectly> contain any other kind of block.)>
From an email conversation between @thoughtstream and @finanalyst after identifying an error. This is to document the issue and its resolution.
From @thoughtstream
A nested code block within an item block is NOT rendered as code (as it should be).
For example:
Reply from @finanalyst:
The issue does raise a question about what may be the generic content of extended variants of item/defn/para/nested/head.
We discussed some of this question when considering acceptable content for enumerated extended blocks.
Each of these blocks are typically thought to have single strings, which may contain markup. FYI The implementation hitch is that the RakuAST parser explicitly generates a Paragraph when there is embedded markup, but leaves a bare string otherwise. Not creating a rendered paragraph when a string is expected was handled in an ad hoc manner, but now needs some thought.
When discussing embedded RakuDoc for a head block, we decided that RakuDoc markup codes are acceptable, but blocks are not.
However, in the Rakuast::RakuDoc::Render, this logic is extended to item/defn/para/nested. Code blocks, as opposed to C<> markup, are thus excluded from item.
More formally, perhaps this would be:
An extended paragraph-level block may contain embedded format codes, but may not contain another paragraph-level block, unless explicitly permitted.
@thoughtstream stated that an item should be able to contain a code block, and we also discussed what a paragraph embedded in a paragraph should look like when numbered (the counter is incremented for the first para, but not for subsequent ones).
This topic is more general that =code inside =item.
What about =item inside =item {=begin item\nITEM content\n=item inner item\n=end item}? Should this be the same as =item ITEM CONTENT\n=item inner item} or {=item ITEM content=item2 inner item\n} or something Renderer dependent?
@thoughtstream response:
The fact that we ran into this problem in RakuDoc source that we'd written ourselves
suggests to me that we need a more coherent answer to "what can be nested in what?"
And I still think that is entirely reasonable.
I can see why that would seem a reasonable position. I might even agree with it,
except that our own spec found reasons to embed code blocks inside item blocks. :-(
And I can already think of other combinations that might also be entirely reasonable.
Agreed.
We actually address that particular case in the spec, and indicate that
it's an error. But the point stands: there are numerous types of blocks
and we need a consistent rule for which blocks can be nested in which other blocks.
So here's a first attempt at such a rule...