double captions with :hidden

[finanalyst]

When :hidden is used with a semantic block, the block is not rendered in place, but the rendered text is stored and then placed using either P<> or =place. Both a semantic block and a =place directive use the block name or :caption to label the block with a heading, and to add to the ToC. This creates ambiguity.

I have found the ability to specify a block in one place, but render in another particularly useful with =AUTHOR and =VERSION, which I prefer to have at the top of the Rakudoc source, where they can be easily changed, but for the rendered text to be towards the bottom of the rendered output.

My proposal is that when :hidden is used, the =place caption attribute overrides the original block name. Also, =place is a directive, and not a block, and RakuDoc does not actually specify what should be used if a place is used without a caption attribute.

Take for example:

=for AUTHOR :hidden
Some author's name

Text continues
.. later ...
=place semantic:AUTHOR :caption<Credits>

Currently, the rendered version of the AUTHOR block is stored, and includes AUTHOR as the block name & the title of the rendered text. Nothing is included in the ToC at the position where it is defined.

Later, the block is embedded into the text with AUTHOR as the title of the rendered text. The ToC, however, contains the text 'Credits`.

I think this looks wrong because the ToC and the heading of the section to which it refers have different values. My preference would be for a place directive to use the caption attribute for both the ToC and the heading of the section, and if caption is not given, to use the

[thoughtstream]

I think this looks wrong because the ToC and the heading of the section to which it refers have different values.

I agree that this is suboptimal.

My preference would be for a place directive to use the caption attribute for both the ToC and the heading of the section,

Agreed.

and if caption is not given, to use the

...block name (I presume).

If so, agreed.

[finanalyst]

@thoughtstream thank you. Don't know how the text got snipped, but who cares when you can read my mind so easily :)

[thoughtstream]

Don't know how the text got snipped, but who cares when you can read my mind so easily :)

I suspect I can only do that because the mind is so clear and well organized.

Actually, out of interest, I asked ChatGPT to fill in the missing end of the sentence. It came back with:

and if caption is not given, to use the original block name for both.

Then I tried the same request on Ollama 3, which suggested:

and if caption is not given, to use the block name for both the ToC and the heading of the section.

So you shouldn't give me too much credit. The implication was obviously so well conveyed that even a mere text-completion mechanism could correctly infer your intent.

Or, to put it another way, I am indeed "the LLM of Perl". :-)