The following result is expected behavior. We iterate through all
headlines starting at headline =* 1=.
#+HEADER: :results value
#+HEADER: :results verbatim
#+begin_src elisp
(with-temp-buffer
(org-mode)
(insert
"* 1
,** 1.1
,** 1.2
,** 1.3
,* 2
,** 2.1
,** 2.2
,** 2.3
")
(goto-char (point-min))
(org-map-entries
(lambda ()
(org-entry-get nil "ITEM"))
nil
'tree))
#+end_src
#+RESULTS:
#+begin_example
("1" "1.1" "1.2" "1.3")
#+end_example
To me, the following result is unexpected behavior, because we are
iterating through headlines that are outside =* 1=, the tree in which
=org-map-entries= was called.
#+begin_quote
SCOPE determines the scope of this command. It can be any of:
nil The current buffer, respecting the restriction if any
tree The subtree started with the entry at point
region The entries within the active region, if any
region-start-level
The entries within the active region, but only those at
the same level than the first one.
#+end_quote
#+HEADER: :results value
#+HEADER: :results verbatim
#+HEADER: :results value
#+begin_src elisp
(with-temp-buffer
(org-mode)
(insert
"* 1
,** 1.1
,** 1.2
,** 1.3
,* 2
,** 2.1
,** 2.2
,** 2.3
")
(goto-char (point-min))
(org-map-entries
(lambda ()
(widen)
(org-entry-get nil "ITEM"))
nil
'tree))
#+end_src
#+RESULTS:
#+begin_example
("1" "1.1" "1.2" "1.3" "2" "2.1" "2.2" "2.3")
#+end_example
According to the docstring of =org-map-entries=, when SCOPE is =tree=,
we only iterate to the entries under the subtree starting with the
entry at point (relevant part of docstring =org-map-entries= shown
below).
#+begin_quote
SCOPE determines the scope of this command. It can be any of:
nil The current buffer, respecting the restriction if any
tree The subtree started with the entry at point
region The entries within the active region, if any
region-start-level
The entries within the active region, but only those at
the same level than the first one.
#+end_quote
The second result shown above proved this wrong.
* Personal thoughts
I have come up with two possible solutions to handle this scenario.
Solution no. 1: Update the description of =tree= in the docstring of
=org-map-entries= to indicate the user that =widen= shouldn't be used
in FUNC, since otherwise, =org-map-entries= will iterate through
headlines outside the tree at point.
Solution no. 2: Execute the parameter =FUNC=, which is passed to
=org-map-entries=, inside =save-restriction= to ensure that in every
iteration the restriction is not affected, thus only moving forward to
the proper headlines only.
