emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed

* [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/)]
@ 2023-06-29  5:41 pva-outdoor
  2023-07-01 10:23 ` Ihor Radchenko
  0 siblings, 1 reply; 3+ messages in thread
From: pva-outdoor @ 2023-06-29  5:41 UTC (permalink / raw)
  To: emacs-orgmode



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.


^ permalink raw reply	[flat|nested] 3+ messages in thread

• * 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/)]
    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>
    0 siblings, 1 reply; 3+ messages in thread
  From: Ihor Radchenko @ 2023-07-01 10:23 UTC (permalink / raw)
    To: pva-outdoor; +Cc: emacs-orgmode
  
  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>
  
  
  ^ permalink raw reply	[flat|nested] 3+ messages in thread

• • [parent not found: <87wmzjxvoi.fsf@yandex.ru>]

  • • * 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/)]
             [not found]   ` <87wmzjxvoi.fsf@yandex.ru>
      @ 2023-07-01 20:18     ` Ihor Radchenko
        0 siblings, 0 replies; 3+ messages in thread
      From: Ihor Radchenko @ 2023-07-01 20:18 UTC (permalink / raw)
        To: pva-outdoor; +Cc: emacs-orgmode
      
      [ 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>
      
      
      ^ permalink raw reply	[flat|nested] 3+ messages in thread

end of thread, other threads:[~2023-07-01 20:19 UTC | newest]

Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
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

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