[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/)]

[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]

Remember to cover the basics, that is, what you expected to happen and
what in fact did happen.  You don't know how to make a good report?  See

     https://orgmode.org/manual/Feedback.html#Feedback

Your bug report will be posted to the Org mailing list.
------------------------------------------------------------------------
Hello, team!

Please check the following documentation (or implementation) of dynamic
blocks:

1. It seems that dynamic blocks can't have inner headlines (the
org-dblock-write:xxx should not produce them). Otherwise the block will
be parsed incorrectly (not mentioned in docs for org-mode).

Example: Create the following 1.org and export it to unicode text (press
C-c C-e t U). You will see "#+BEGIN: block2" as text.

  * Block2
  
  #+BEGIN: block2
  ** Section 1
  asdasdsad
  #+END:
  
2. Org-mode info file says:

     Dynamic blocks, like any other block, can be narrowed with
  ‘org-narrow-to-block’.

That would not work because of implementation of org-narrow-to-block:

(defun org-narrow-to-block ()
  "Narrow buffer to the current block."
  (interactive)
  (let* ((case-fold-search t)
	 (blockp (org-between-regexps-p "^[ \t]*#\\+begin_.*"  <----
					"^[ \t]*#\\+end_.*")))
    (if blockp
	(narrow-to-region (car blockp) (cdr blockp))
      (user-error "Not in a block"))))



There is also a minor bug in org-mode (sould I report it
in it's own mail?):

If you press C-c C-, [RET] [RET] You'll get:

#+begin_
#+end_nil

while one could expect either begin_nil or end_. 


Emacs  : GNU Emacs 29.0.50 (build 4, x86_64-pc-linux-gnu, GTK+ Version 3.24.34, cairo version 1.17.6)
 of 2022-07-15
Package: Org mode version 9.5.4 (release_9.5.4-3-g6dc785 @ /usr/local/share/emacs/29.0.50/lisp/org/)
-- 
Best regards,
Andrey Petrov.

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]

pva-outdoor@yandex.ru writes:

> 1. It seems that dynamic blocks can't have inner headlines (the
> org-dblock-write:xxx should not produce them). Otherwise the block will
> be parsed incorrectly (not mentioned in docs for org-mode).

That's Org markup. Headings have the top priority - any "*...* "
starting at the beginning of line is a heading that ends at the next
"*...* " or end of buffer.

> Example: Create the following 1.org and export it to unicode text (press
> C-c C-e t U). You will see "#+BEGIN: block2" as text.
>
>   * Block2
>   
>   #+BEGIN: block2
>   ** Section 1
>   asdasdsad
>   #+END:

There is no block in the above example.
What you have is

<Block2 heading start>
* Block2

<paragraph start>
#+BEGIN: block2
<paragraph end>
<Section 1 heading start>
** Section 1
<paragraph start>
asdasdsad
#+END:
<paragraph end>
<Section 1 heading end>
<Block2 heading end>

We intentionally do not prohibit such scenario for dynamic block
functions to keep flexibility.
   
> 2. Org-mode info file says:
>
>      Dynamic blocks, like any other block, can be narrowed with
>   ‘org-narrow-to-block’.
>
> That would not work because of implementation of org-narrow-to-block:
>
> (defun org-narrow-to-block ()
>   "Narrow buffer to the current block."
>   (interactive)
>   (let* ((case-fold-search t)
> 	 (blockp (org-between-regexps-p "^[ \t]*#\\+begin_.*"  <----
> 					"^[ \t]*#\\+end_.*")))
>     (if blockp
> 	(narrow-to-region (car blockp) (cdr blockp))
>       (user-error "Not in a block"))))

Agree.
Fixed, on main.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=85aa3c185

> There is also a minor bug in org-mode (sould I report it
> in it's own mail?):
>
> If you press C-c C-, [RET] [RET] You'll get:
>
> #+begin_
> #+end_nil
>
> while one could expect either begin_nil or end_. 

An error will be thrown now.
Fixed, on main.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=64a0a624d

-- 
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>

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]

[ 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>