From: Ihor Radchenko <yantar92@posteo.net>
To: pva-outdoor@yandex.ru
Cc: emacs-orgmode@gnu.org
Subject: 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/)]
Date: Sat, 01 Jul 2023 20:18:16 +0000 [thread overview]
Message-ID: <874jmn5qt3.fsf@localhost> (raw)
In-Reply-To: <87wmzjxvoi.fsf@yandex.ru>
[ 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>
prev parent reply other threads:[~2023-07-01 20:19 UTC|newest]
Thread overview: 3+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-06-29 5:41 [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/)] pva-outdoor
2023-07-01 10:23 ` Ihor Radchenko
[not found] ` <87wmzjxvoi.fsf@yandex.ru>
2023-07-01 20:18 ` Ihor Radchenko [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=874jmn5qt3.fsf@localhost \
--to=yantar92@posteo.net \
--cc=emacs-orgmode@gnu.org \
--cc=pva-outdoor@yandex.ru \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).