Re: [BUG] incorrect org-mode dynamic blocks docs [9.5.4 (release_9.5.4-3-g6dc785 @ /usr/local/share/emacs/29.0.50/lisp/org/)]

[Ihor Radchenko <yantar92@posteo.net>]

[ Adding Org ML back to CC; Please use Reply-All or wide reply to
  include the mailing list in the discussion ]

pva-outdoor@yandex.ru writes:

> Try the following:
>
> 1. Create "1.org" buffer (C-x b 1.org [RET]) and make it org-mode (M-x
>    org-mode [RET]).
> ...
>    I believe it is the same as if you create a function:
>    
>    ----------EXAMPLE-HERE----------
>    (defun org-dblock-write:expands-some (params-map)
>      (insert "
>    ** Section 2
>    
>    With some text
>    "))
>    ----------END-OF-EXAMPLE----------
>    
>    And a org-mode buffer with the content:
> ...
> The "#+BEGIN: expands-some" will not appear if
> `org-dblock-write:expands-some` is not generating headings (i.e. lines
> maching regex "^[*]+ ").
>
> So I think either there is a bug in dynamic blocks expansion or it's
> documentation should have notice on including headings inside dynamic
> blocks.

It looks like you misunderstand Org syntax.
Headings in Org files are context-free.
It means that any appearance of a *** <heading> always starts a new
heading, breaking any other syntax element.
You may refer to https://orgmode.org/worg/org-syntax.html

You can similarly break Org syntax structure in many other ways. For
example, by putting #+END: in the block expansion.

All these are side effects of plain text nature of Org.
We could shield the dynamic block output from edge cases like what you
observe or like I provided in my example with #+END:, but we see this
behaviour as a feature. If necessary, you can wrap your dynamic block
output into `org-escape-code-in-string' to ensure that surrounding Org
markup is not affected.

> I found this behavior while implementing a template document which fills
> some sections depending on conditions (automatic documentation from
> OpenAPI). Thus ability to generate subheadings with dynamic blocks
> became a key feature here. That is why I recommend describing this
> restriction in documentation (probably "A.6 Dynamic Blocks" section) if
> this behavior is desired.

This restriction is not limited to dynamic blocks. Similar restriction
applies to example blocks, other blocks, drawers, etc.
I guess we can add documentation describing these gotchas about Org
syntax, though I am not sure if A.6 is the most suitable section.
Probably, we can add a dedicated Appending and then refer to it from
other places. Patches welcome!

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>