[ Adding Org ML back to CC; Please use Reply-All or wide reply to include the mailing list in the discussion ]
pva-outd...@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>
