[elpa] externals/org 0af8d7bf40 1/6: etc/ORG-NEWS: Move more impacting changes near the top for Org 9.7 release

[ELPA Syncer]

branch: externals/org
commit 0af8d7bf406b75accc59693ff32178a282ee9726
Author: Ihor Radchenko <yantar92@posteo.net>
Commit: Ihor Radchenko <yantar92@posteo.net>

    etc/ORG-NEWS: Move more impacting changes near the top for Org 9.7 release
---
 etc/ORG-NEWS | 1097 +++++++++++++++++++++++++++++-----------------------------
 1 file changed, 549 insertions(+), 548 deletions(-)

diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 6c6fdbe2c9..071e8a3fba 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -13,234 +13,367 @@ Please send Org bug reports to 
mailto:emacs-orgmode@gnu.org.
 
 * Version 9.7 (not released yet)
 ** Important announcements and breaking changes
-*** ~org-auto-align-tags~ is now respected universally
+*** =python-mode.el (MELPA)= support in =ob-python.el= is removed
 
-Previously, only a subset of Org editing commands respected
-~org-auto-align-tags~ option.  Now, it is no longer the case.  All the
-editing commands, including typing (~org-self-insert-command~) and
-deletion respect the option.
+=python-mode.el= support has been removed from =ob-python.el=.  The
+related customization =org-babel-python-mode= has been changed to a
+constant.
 
-~org-auto-align-tags~ is still enabled by default.  For users who
-customized ~org-auto-align-tags~ to nil, ~org-edit-headline~,
-~org-priority~, ~org-set-tags~, ~org-entry-put~, ~org-kill-line~, and
-typing/deleting in headlines will no longer unconditionally auto-align
-the tags.
+If you still want to use python-mode with ob-python, you might
+consider 
[[https://gitlab.com/jackkamm/ob-python-mode-mode][ob-python-mode-mode]], where 
the code to support python-mode
+has been ported to.
 
-*** ~org-create-file-search-functions~ can use ~org-list-store-props~ to 
suggest link description
+*** ~tab-width~ value is now assumed to be 8
 
-In Org <9.0, ~org-create-file-search-functions~ could set ~description~
-variable to suggest link description for the stored link.  However,
-this feature stopped working since Org 9.0 switched to lexical binding.
+Org mode now assumes tab width to be 8 characters, when calculating
+list and other indentation.  ~tab-width~ is also set to 8 when Org
+major mode is loaded.
 
-Now, it is again possible for ~org-create-file-search-functions~ to
-supply link descriptions using ~(org-list-store-props :description
-"suggested description")~ in the search function body.
+This is done to improve consistency of the markup for lists, where
+indentation affects list items.
 
-*** Inline image width value in =#+attr_org= is preferred over other 
=#+attr_...= keywords
+Users with non-default values of ~tab-width~ should avoid overriding
+the value of 8 set by Org mode.  If the custom ~tab-width~ value is
+_smaller_ than 8, the existing Org documents can be converted to the
+new standard tab width using the following helper command:
 
-Previously, when ~org-image-actual-width~ is a list or nil, Org used the
-first =#+attr_...= keyword containing =:width ...= to compute the inline
-image width.  Now, =#+attr_org=, if present, takes precedence.
-In the following example the image preview has width of 75%
-while earlier versions pick 33%.
+#+begin_src emacs-lisp
+(defun org-compat-adjust-tab-width-in-buffer (old-width)
+  "Adjust visual indentation from `tab-width' equal OLD-WIDTH to 8."
+  (interactive "nOld `tab-width': ")
+  (cl-assert (derived-mode-p 'org-mode))
+  (unless (= old-width 8)
+    (org-with-wide-buffer
+     (goto-char (point-min))
+     (let (bound
+          (repl (if (< old-width 8)
+                    (make-string old-width ?\s)
+                   (concat "\t" (make-string (- old-width 8) ?\s)))))
+       (while (re-search-forward "^ *\t" nil t)
+        (skip-chars-forward " \t")
+        (setq bound (point-marker))
+        (forward-line 0)
+        (while (search-forward "\t" bound t)
+          (replace-match repl)))))))
+#+end_src
 
-: #+attr_html: :width 33%
-: #+attr_org:  :width 0.75
-: [[image.png]]
+*** =id:= links support search options; ~org-id-store-link~ adds search option 
by default
 
-*** =ox-html=: When exporting footnotes with custom non-number names, the 
names are used as link anchors
+Adding search option by ~org-id-store-link~ can be disabled by setting
+~org-id-link-use-context~ to ~nil~, or toggled for a single call by
+passing universal argument.
 
-Previously, link anchors for footnote references and footnote
-definitions were based on the footnote number: =fn.1=, =fnr.15=, etc.
+When using this feature, IDs should not include =::=, which is used in
+links to indicate the start of the search string.  For backwards
+compability, existing IDs including =::= will still be matched (but
+cannot be used together with search option).  A new org-lint checker
+has been added to warn about this.
 
-Now, when the footnote has a non-number name, it is used as an anchor:
-=fn.name=, =fnr.name=.
+*** Major changes and additions to Org element API
+**** Diary type timestamps now support optional time/timerange
 
-*** Underline syntax now takes priority over subscript when both are applicable
+Previously, diary type timestamps could not specify time.
+Now, it is allowed to add a time or time range:
 
-Previously, Org mode interpreted =(_text_)= as subscript.
-Now, the interpretation is changed to underline.
+: <%%(diary-float t 4 2) 22:00-23:00>
+: <%%(diary-float t 4 2) 10:30>
 
-=(_text_)= matches both subscript and underline markup.  The
-interpretation is changed to keep consistency with other emphasis like
-=(*bold*)=.
+The parsed representation of such timestamps will have ~:hour-start~,
+~:minute-start~, ~:hour-end~, ~:minute-end~, and ~:range-type~
+properties set appropriately.  In addition, a new ~:diary-sexp~
+property will store the diary sexp value.
 
-Most of the users should not be affected by this change - it only applies when 
character immediately preceding =_= is one of =-=, =(=, ='=, and ={=.
+For example,
 
-*** ~org-latex-to-mathml-convert-command~ and 
~org-latex-to-html-convert-command~ may need to be adjusted
+: <%%(diary-float t 4 2) 22:00-23:00>
 
-Previously, =%i= placeholders in the
-~org-latex-to-mathml-convert-command~ and
-~org-latex-to-html-convert-command~ user options were replaced with
-raw LaTeX fragment text, potentially triggering shell-expansion and
-incorrect result.
+will have the following properties
 
-Now, the =%i= placeholders are shell-escaped to prevent shell
-expansion.
+#+begin_src emacs-lisp
+:type: diary
+:range-type: timerange
+:raw-value: "<%%(diary-float t 4 2) 22:00-23:00>"
+:year-start: nil
+:month-start: nil
+:day-start: nil
+:hour-start: 22
+:minute-start: 0
+:year-end: nil
+:month-end: nil
+:day-end: nil
+:hour-end: 23
+:minute-end: 0
+:diary-sexp: "(diary-float t 4 2)"
+#+end_src
 
-If you have single or double quotes around =%i= then update
-customizations and remove quotes.
+**** New term: "syntax node"
 
-*** Org mode faces are now consistently combined, with markup faces taking 
precedence over the containing element faces
+To reduce confusion with "element" referring to both "syntax element"
+and "element/object" class, we now prefer using "syntax node" when
+referring to generic Org syntax elements.  "Elements" and "objects"
+now refer to different syntax node classes of paragraph-like nodes and
+markup-like nodes.
 
-Previously, fontification of inline source blocks, macros, footnotes,
-target links, timestamps, radio targets, targets, inline export
-snippets, verbatim code, and COMMENT keyword in headings replaced the
-containing element fontification. Now, this is changed - the inner
-markup faces and the containing element faces are combined, with
-"inner" faces taking precedence; just as for all other markup.
+**** New element type ~anonymous~
 
-*** Built-in HTML, LaTeX, Man, Markdown, ODT, and Texinfo exporters preserve 
the link protocol during export
+Secondary strings can now be recognized as ~anonymous~ type to
+distinguish from non-elements.  With a new optional argument,
+~org-element-type~ will return ~anonymous~ for secondary strings
+instead of nil.
 
-Previously, some link types where not exported as =protocol:uri= but
-as bare =uri=. This is now changed.
+The new element type can be used in ~org-element-lineage~,
+~org-element-map~, and other functions that filter by element type.
 
-When a link is known by Org mode and does not have a custom ~:export~
-parameter (see A.3 Adding Hyperlink Types section of the manual), the
-link protocol is now not stripped.
+**** Internal structure of Org parse tree has been changed
 
-For example, if one adds a link type =tel=, but does not define
-~:export~ parameter
-: (org-link-set-parameters "tel")
-=[[tel:12345][John Doe]]= link will be correctly exported to LaTeX as
-=\href{tel:12345}{John Doe}=, not =\href{12345}{John Doe}=.
+The code relying upon the previously used =(TYPE PROPERTIES-PLIST 
CONTENTS-LIST)=
+structure may no longer work.  Please use ~org-element-create~,
+~org-element-property~, and other Org element API functions to work
+with Org syntax trees.
 
-However, links like =[[elisp:(+ 1 2)]]= will be exported as
-=\url{elisp:(+ 1 2)}=, which may be somewhat unexpected.
+Some syntax node properties are no longer stored as property list elements.
+Instead, they are kept in a special vector value of a new
+=:standard-properties= property.  This is done to improve performance.
 
-*** When ~org-link-file-path-type~ is a function, its argument is now a 
filename as it is read by ~org-insert-link~; not an absolute path
+If there is a need to traverse all the node properties, a new API
+function ~org-element-properties-map~ can be used.
 
-Previously, when ~org-link-file-path-type~ is set to a function, the
-function argument was the filename from the link expanded via
-~expand-file-name~.  Now, a bare filename is passed to the function.
+Properties and their values can now be deferred to avoid overheads
+when parsing.  They are calculated lazily, when the value/property is
+requested by ~org-element-property~ and other getter functions.  Using
+~plist-get~ to retrieve values of =PROPERTIES-PLIST= is not
+recommended as deferred properties will not be resolved in such
+scenario.
 
-*** Org export backends can now disable citation processors
+New special property =:secondary= is used internally to record which
+properties store secondary objects.
 
-A new global export option ~:with-cite-processors~, when set to nil,
-disables citation processors completely.  This option is available to
-export backends via ~:options-alist~ when defining the backend.
+New special property =:deferred= is used to keep information how to
+calculate property names lazily.
 
-The backends disabling citation processors must take care about
-exporting citation objects and =print_bibliography= keywords via
-transcoders.
+See the commentary in =lisp/org-element-ast.el= for more details.
 
-Users can disable citations processors by customizing new
-~org-export-process-citations~ option.
-*** =ox-org= preserves header non-default arguments in src blocks
+**** Multiple affiliated keyword values are now stored in the order they 
appear in buffer
 
-Previously, all the header arguments where stripped from src blocks
-during export.  Now, header arguments are preserved as long as their
-values are not equal to the default header argument values.
+Previously,
 
-*** =ox-org= disables citation processors by default
+: #+caption: foo
+: #+caption: bar
+: Paragraph
 
-Previously, when exporting to Org, all the citations and
-=print_bibliography= keywords, were transformed according to the
-chosen citation processor.
+would have its =:caption= property set to ~(("bar") ("foo"))~ in reverse order.
 
-This is no loner the case.  All the citation-related markup is now
-exported as is.
+Now, the order is not reversed: ~(("foo") ("bar"))~.
 
-The previous behavior can be reverted by setting new custom option
-~org-org-with-cite-processors~.
+**** Some property values may now be calculated lazily and require original 
Org buffer to be live
 
-*** =ox-org= now exports special table rows by default
+~org-element-at-point~, ~org-element-context~, and
+~org-element-at-point-no-context~ may now not calculate all the
+property values at the call time.  Instead, the calculation will be
+deferred until ~org-element-property~ or the equivalent getter
+function is called.  The property names may not all be calculated as
+well.
 
-Previously, when exporting to Org, special table rows (for example,
-width cookies) were not exported.   Now, they are exported by default.
+It may often be necessary to have the original Org buffer open when
+resolving the deferred values.
+
+One can ensure that all the deferred values are resolved using new
+function ~org-element-resolve-deferred~ and new optional argument for
+~org-element-property~.
+
+~org-element-parse-buffer~ and ~org-element-parse-secondary-string~
+will resolve all the deferred values by default.  No adjustment is
+needed for their users.
+
+**** New API functions and macros
+***** New property accessors and setters
+
+New functions to retrieve and set (via ~setf~) commonly used element 
properties:
+- =:begin= :: ~org-element-begin~
+- =:end= :: ~org-element-end~
+- =:contents-begin= :: ~org-element-contents-begin~
+- =:contents-end= :: ~org-element-contents-end~
+- =:post-affiliated= :: ~org-element-post-affiliated~
+- =:post-blank= :: ~org-element-post-blank~
+- =:parent= :: ~org-element-parent~
+
+***** New macro ~org-element-with-enabled-cache~
+
+The macro arranges the element cache to be active during =BODY= execution.
+When cache is enabled, the macro is identical to ~progn~.  When cache
+is disabled, the macro arranges a new fresh cache that is discarded
+upon completion of =BODY=.
+
+***** New function ~org-element-property-raw~
+
+This function is like ~org-element-property~ but does not try to
+resolve deferred properties.
+
+~org-element-property-raw~ can be used with ~setf~.
+
+***** New function ~org-element-put-property-2~
+
+Like ~org-element-put-property~, but the argument list is changed to have
+=NODE= as the last argument.  Useful with threading macros like
+~thread-last~.
+
+***** New function ~org-element-properties-resolve~
+
+This function resolves all the deferred values in a =NODE=, modifying
+the =NODE= for side effect.
+
+***** New functions ~org-element-properties-map~ and 
~org-element-properties-mapc~
+
+New functions to map over =NODE= properties.
+
+***** New function ~org-element-ast-map~
+
+This is a more general equivalent of ~org-element-map~.  It allows
+more precise control over recursion into secondary strings.
+
+***** New function ~org-element-lineage-map~
+
+Traverse syntax tree ancestor list, applying arbitrary function to
+each ancestor.
+
+***** New function ~org-element-property-inherited~
+
+Like ~org-element-property~, but can be used to retrieve and combine
+multiple different properties for a given =NODE= and its parents.
+
+**** ~org-element-cache-map~ can now be used even when element cache is 
disabled
+
+**** =org-element= API functions and macros can now accept syntax nodes as 
=POM= argument
+
+The following functions are updated:
+- ~org-agenda-entry-get-agenda-timestamp~
+- ~org-element-at-point~
+- ~org-is-habit-p~
+- ~org-id-get~
+- ~org-with-point-at~
+- ~org-entry-properties~
+- ~org-entry-get~
+- ~org-entry-delete~
+- ~org-entry-add-to-multivalued-property~
+- ~org-entry-remove-from-multivalued-property~
+- ~org-entry-member-in-multivalued-property~
+- ~org-entry-put-multivalued-property~
+- ~org-entry-get-with-inheritance~
+- ~org-entry-put~
+- ~org-read-property-value~
+- ~org-property-get-allowed-values~
+
+**** ~org-element-map~ now traverses main value in dual keywords before the 
secondary value
+
+The traverse order for dual keywords is reversed.  The main value is
+now traversed first, followed by the secondary value.
+
+**** Org parse tree is now non-printable
+
+Org parser now assigns a new property =:buffer= that holds
+non-printable buffer object.  This makes syntax tree non-printable.
+Using ~print~/~read~ is no longer safe.
+
+**** Some Org API functions no longer preserve match data
+
+~org-element-at-point~, ~org-element-context~, ~org-get-category~, and
+~org-get-tags~ may modify the match data.
+
+The relevant function docstrings now explicitly mention that match
+data may be modified.
+
+**** ~org-element-create~ now treats a single ~anonymous~ =CHILDREN= argument 
as a list of child nodes
+
+When =CHILDREN= is a single anonymous node, use its contents as children
+nodes.  This way,
 
-You can customize new option ~org-org-with-special-rows~ to fall back to 
previous behavior.
+: (org-element-create 'section nil (org-element-contents node))
 
-*** Org babel backends are now expected to define an additional API function 
~org-babel-session-buffer:<lang>~
+will yield expected results with contents of another node adopted into
+a newly created one.
 
-Org babel now uses session buffer (if it exists) to retrieve
-~default-directory~ environment during src block evaluation.
+Previously, one had to use
 
-By default, buffer named like session is checked.  All the backends
-that create sessions inside buffers named differently should provide a
-function ~org-babel-session-buffer:<lang>~.  The function must accept
-two arguments - session name and info list (as returned by
-~org-babel-get-src-block-info~); and return the session buffer name.
+: (apply #'org-element-create 'section nil (org-element-contents node))
+**** New property ~:range-type~ for org-element timestamp object
 
-*** ~org-insert-subheading~ no longer inserts a sub-heading above current when 
point is at the beginning of line
+~org-element-timestamp-parser~ now adds =:range-type= property to each
+timestamp object.  Possible values: ~timerange~, ~daterange~, ~nil~.
 
-Previously, calling ~org-insert-subheading~ on
+~org-element-timestamp-interpreter~ takes into account this property
+and returns an appropriate timestamp string.
 
-: * Heading 1
-: <point>* Heading 2
+**** New properties =:repeater-deadline-value= and =:repeater-deadline-unit= 
for org-element timestamp object
 
-yielded
+~org-element-timestamp-parser~ now adds =:repeater-deadline-value= and
+=:repeater-deadline-unit= properties to each timestamp object that has
+a repeater deadline.  For example, in =<2012-03-29 Thu ++1y/2y>=, =2y=
+is the repeater deadline with a value of =2= and unit of =y=.  See
+"5.3.3 Tracking your habits" section in the manual.
 
-: * Heading 1
-: ** <point>
-: * Heading 2
+Possible values for =:repeater-deadline-value=: ~positive integer~, ~nil~.
 
-This is no longer the case.  The sub-heading is always created below
-current heading (prefix arguments have the same meaning as in
-~org-insert-heading~):
+Possible values for =:repeater-deadline-unit=: ~hour~, ~day~, ~week~,
+~month~, ~year~.
 
-: * Heading 1
-: * Heading 2
-: ** <point>
+~org-element-timestamp-interpreter~ takes into account these properties
+and returns an appropriate timestamp string.
 
-*** Org mode now fontifies whole table lines (including newline) according to 
~org-table~ face
+**** =org-link= store functions are passed an ~interactive?~ argument
 
-Previously, leading indentation and trailing newline in table rows
-were not fontified using ~org-table~ face.  ~default~ face was used instead.
-This made it impossible to scale line height when ~org-table~ face has
-smaller height than default (Emacs calculates line height using the tallest 
face).
+The ~:store:~ functions set for link types using
+~org-link-set-parameters~ are now passed an ~interactive?~ argument,
+indicating whether ~org-store-link~ was called interactively.
 
-Now, new ~org-table-row~ face is used on the whole table row lines,
-including indentation and the final newline. This face, by default,
-inherits from ~org-table~ face.
+Existing store functions will continue to work.
 
-If the new behavior is not desired, ~org-table-row~ face can be
-changed to inherit from ~default~ face.  See "Customizing Faces"
-section of Emacs manual or "Face Attribute Functions" section of Elisp
-manual.
+*** Folded lines can now extend their face beyond ellipsis
 
-~org-table~ takes precedence over ~org-table-row~ for the parts of
-table rows without indentation and newline.
+Previously, ~:extend t~ face attribute did not make folded headlines,
+blocks, and drawers extend their face beyond end of line.
 
-*** =ox-latex=: ~org-latex-line-break-safe~ is deprecated
+Now, the ellipsis and trailing newline use the same face as the last
+character before the fold.
 
-~org-latex-line-break-safe~ constant was previously introduced to deal
-with edge cases when LaTeX interprets [...] as LaTeX command
-argument.  However, it caused a number of other issues and proved
-itself not to be as "safe" as it supposed to be.
+*** "Priority" used to sort items in agenda is renamed to "urgency"
 
-We now use a Pandoc's approach to deal with the same problem,
-utilizing ={[}= to escape =[...]= instances where needed.
+Previously, ~priority-up~ and ~priority-down~ in
+~org-agenda-sorting-strategy~ used a composite rank depending on
+item's priority (=[#A]=, =[#B]=, =[#C]=, etc) and overdue time to
+order agenda items (see "11.4.3 Sorting of agenda items" section of
+Org manual).
 
-*** ob-python now sets ~python-shell-buffer-name~ in Org edit buffers
+Now, this composite rank is renamed to =urgency= and the relevant
+sorting strategies are renamed to ~urgency-up~ and ~urgency-down~.
+~priority-up~ and ~priority-down~ sort by item's priority only.
 
-When editing a Python src block, the editing buffer is now associated
-with the Python shell specified by the src block's ~:session~ header,
-which means users can now send code directly from the edit buffer,
-e.g., using ~C-c C-c~, to the session specified in the Org buffer.
+Users relying on the previous composite ranking should adjust their
+agenda sorting settings.
 
-*** ~org-edit-special~ no longer force-starts session in R and Julia source 
blocks
+*** Org mode no longer disallows configuring ~display-buffer-alist~ to open 
Org popups in other frame
 
-Previously, when R/Julia source block had =:session= header argument
-set to a session name with "earmuffs" (like =*session-name*=),
-~org-edit-special~ always started a session, if it does not exist.
+Previously, Org mode disallowed pop-up frames when displaying dispatch buffers.
+This is no longer the case. ~display-buffer-alist~ is fully obeyed.
 
-Now, ~org-edit-special~ arranges that a new session with correct name
-is initiated only when user explicitly executes R/Julia-mode commands
-that trigger session interactions (requires ESS 24.01.0 or newer).
-The same session will remain available in the context of Org babel.
+~org-switch-to-buffer-other-window~ and ~org-no-popups~ are now deprecated.
 
-*** It is no longer allowed to tangle into the same file as Org source
+*** Built-in HTML, LaTeX, Man, Markdown, ODT, and Texinfo exporters preserve 
the link protocol during export
 
-Previously, =file.org= with the following contents
+Previously, some link types where not exported as =protocol:uri= but
+as bare =uri=. This is now changed.
 
-: #+begin_src org :tangle file.org
-: Text
-: #+end_src
+When a link is known by Org mode and does not have a custom ~:export~
+parameter (see A.3 Adding Hyperlink Types section of the manual), the
+link protocol is now not stripped.
 
-would overwrite itself.
+For example, if one adds a link type =tel=, but does not define
+~:export~ parameter
+: (org-link-set-parameters "tel")
+=[[tel:12345][John Doe]]= link will be correctly exported to LaTeX as
+=\href{tel:12345}{John Doe}=, not =\href{12345}{John Doe}=.
 
-Now, an error is thrown.
+However, links like =[[elisp:(+ 1 2)]]= will be exported as
+=\url{elisp:(+ 1 2)}=, which may be somewhat unexpected.
 
 *** iCalendar export now supports multiline =SUMMARY=, =LOCATION=, and 
=DESCRIPTION= properties
 
@@ -268,83 +401,35 @@ In the above example, =LOCATION= is now exported as
 : Some Street 5
 : 12345 Small Town
 
-*** Org mode no longer disallows configuring ~display-buffer-alist~ to open 
Org popups in other frame
-
-Previously, Org mode disallowed pop-up frames when displaying dispatch buffers.
-This is no longer the case. ~display-buffer-alist~ is fully obeyed.
-
-~org-switch-to-buffer-other-window~ and ~org-no-popups~ are now deprecated.
-
-*** Folded lines can now extend their face beyond ellipsis
-
-Previously, ~:extend t~ face attribute did not make folded headlines,
-blocks, and drawers extend their face beyond end of line.
-
-Now, the ellipsis and trailing newline use the same face as the last
-character before the fold.
-
-*** ~org-agenda-search-headline-for-time~ now ignores all the timestamp in 
headings
-
-Previously, ~org-agenda-search-headline-for-time~ made Org agenda
-match anything resembling time inside headings.  Even when the time
-was a part of a timestamp.
-
-Now, all the timestamps in headings are ignored when searching the time.
-
-*** ODT export no longer opens the exported file in the background
-
-ODT exporter used to open the exported file in ~archive-mode~ "for
-examination".  This was not documented, was done in the background,
-and is not consistent with all other export backends. Now, this
-feature is removed.
-
-*** ~org-print-speed-command~ is now an internal function
-
-The old name is marked obsolete and the new name is
-~org--print-speed-command~.
-
-This function was always aimed for internal use when building speed
-command help buffer.  Now, it is stated explicitly.
-
 *** Babel references =FILE:REFERENCE= now search current buffer when =FILE= 
does not exist
 
 When =FILE= does not exist, the reference is searched in the current
 file, using the verbatim reference.  This way,
 =:var table=tbl:example= will be searched inside the current buffer.
 
-*** ~tab-width~ value is now assumed to be 8
+*** Org export backends can now disable citation processors
 
-Org mode now assumes tab width to be 8 characters, when calculating
-list and other indentation.  ~tab-width~ is also set to 8 when Org
-major mode is loaded.
+A new global export option ~:with-cite-processors~, when set to nil,
+disables citation processors completely.  This option is available to
+export backends via ~:options-alist~ when defining the backend.
 
-This is done to improve consistency of the markup for lists, where
-indentation affects list items.
+The backends disabling citation processors must take care about
+exporting citation objects and =print_bibliography= keywords via
+transcoders.
 
-Users with non-default values of ~tab-width~ should avoid overriding
-the value of 8 set by Org mode.  If the custom ~tab-width~ value is
-_smaller_ than 8, the existing Org documents can be converted to the
-new standard tab width using the following helper command:
+Users can disable citations processors by customizing new
+~org-export-process-citations~ option.
 
-#+begin_src emacs-lisp
-(defun org-compat-adjust-tab-width-in-buffer (old-width)
-  "Adjust visual indentation from `tab-width' equal OLD-WIDTH to 8."
-  (interactive "nOld `tab-width': ")
-  (cl-assert (derived-mode-p 'org-mode))
-  (unless (= old-width 8)
-    (org-with-wide-buffer
-     (goto-char (point-min))
-     (let (bound
-          (repl (if (< old-width 8)
-                    (make-string old-width ?\s)
-                   (concat "\t" (make-string (- old-width 8) ?\s)))))
-       (while (re-search-forward "^ *\t" nil t)
-        (skip-chars-forward " \t")
-        (setq bound (point-marker))
-        (forward-line 0)
-        (while (search-forward "\t" bound t)
-          (replace-match repl)))))))
-#+end_src
+*** Org babel backends are now expected to define an additional API function 
~org-babel-session-buffer:<lang>~
+
+Org babel now uses session buffer (if it exists) to retrieve
+~default-directory~ environment during src block evaluation.
+
+By default, buffer named like session is checked.  All the backends
+that create sessions inside buffers named differently should provide a
+function ~org-babel-session-buffer:<lang>~.  The function must accept
+two arguments - session name and info list (as returned by
+~org-babel-get-src-block-info~); and return the session buffer name.
 
 *** New export option ~org-export-expand-links~
 
@@ -355,272 +440,225 @@ Users who do not want variable expansion can set
 ~org-export-expand-links~ variable to nil or provide
 =expand-links:nil= in-file export option.
 
-*** ~org-store-link~ now moves an already stored link to front of the 
~org-stored-links~
-
-Previously, when the link to be stored were stored already,
-~org-store-link~ displayed a message and did nothing.
-
-Now, ~org-store-link~ moves the stored link to front of the list of
-stored links.  This way, the link will show up first in the completion
-and when inserting all the stored links with ~org-insert-all-links~.
-
-*** Major changes and additions to Org element API
-**** Diary type timestamps now support optional time/timerange
-
-Previously, diary type timestamps could not specify time.
-Now, it is allowed to add a time or time range:
-
-: <%%(diary-float t 4 2) 22:00-23:00>
-: <%%(diary-float t 4 2) 10:30>
-
-The parsed representation of such timestamps will have ~:hour-start~,
-~:minute-start~, ~:hour-end~, ~:minute-end~, and ~:range-type~
-properties set appropriately.  In addition, a new ~:diary-sexp~
-property will store the diary sexp value.
-
-For example,
-
-: <%%(diary-float t 4 2) 22:00-23:00>
-
-will have the following properties
-
-#+begin_src emacs-lisp
-:type: diary
-:range-type: timerange
-:raw-value: "<%%(diary-float t 4 2) 22:00-23:00>"
-:year-start: nil
-:month-start: nil
-:day-start: nil
-:hour-start: 22
-:minute-start: 0
-:year-end: nil
-:month-end: nil
-:day-end: nil
-:hour-end: 23
-:minute-end: 0
-:diary-sexp: "(diary-float t 4 2)"
-#+end_src
+*** ~org-auto-align-tags~ is now respected universally
 
-**** New term: "syntax node"
+Previously, only a subset of Org editing commands respected
+~org-auto-align-tags~ option.  Now, it is no longer the case.  All the
+editing commands, including typing (~org-self-insert-command~) and
+deletion respect the option.
 
-To reduce confusion with "element" referring to both "syntax element"
-and "element/object" class, we now prefer using "syntax node" when
-referring to generic Org syntax elements.  "Elements" and "objects"
-now refer to different syntax node classes of paragraph-like nodes and
-markup-like nodes.
+~org-auto-align-tags~ is still enabled by default.  For users who
+customized ~org-auto-align-tags~ to nil, ~org-edit-headline~,
+~org-priority~, ~org-set-tags~, ~org-entry-put~, ~org-kill-line~, and
+typing/deleting in headlines will no longer unconditionally auto-align
+the tags.
 
-**** New element type ~anonymous~
+*** ~org-create-file-search-functions~ can use ~org-list-store-props~ to 
suggest link description
 
-Secondary strings can now be recognized as ~anonymous~ type to
-distinguish from non-elements.  With a new optional argument,
-~org-element-type~ will return ~anonymous~ for secondary strings
-instead of nil.
+In Org <9.0, ~org-create-file-search-functions~ could set ~description~
+variable to suggest link description for the stored link.  However,
+this feature stopped working since Org 9.0 switched to lexical binding.
 
-The new element type can be used in ~org-element-lineage~,
-~org-element-map~, and other functions that filter by element type.
+Now, it is again possible for ~org-create-file-search-functions~ to
+supply link descriptions using ~(org-list-store-props :description
+"suggested description")~ in the search function body.
 
-**** Internal structure of Org parse tree has been changed
+*** Inline image width value in =#+attr_org= is preferred over other 
=#+attr_...= keywords
 
-The code relying upon the previously used =(TYPE PROPERTIES-PLIST 
CONTENTS-LIST)=
-structure may no longer work.  Please use ~org-element-create~,
-~org-element-property~, and other Org element API functions to work
-with Org syntax trees.
+Previously, when ~org-image-actual-width~ is a list or nil, Org used the
+first =#+attr_...= keyword containing =:width ...= to compute the inline
+image width.  Now, =#+attr_org=, if present, takes precedence.
+In the following example the image preview has width of 75%
+while earlier versions pick 33%.
 
-Some syntax node properties are no longer stored as property list elements.
-Instead, they are kept in a special vector value of a new
-=:standard-properties= property.  This is done to improve performance.
+: #+attr_html: :width 33%
+: #+attr_org:  :width 0.75
+: [[image.png]]
 
-If there is a need to traverse all the node properties, a new API
-function ~org-element-properties-map~ can be used.
+*** ~org-store-link~ now moves an already stored link to front of the 
~org-stored-links~
 
-Properties and their values can now be deferred to avoid overheads
-when parsing.  They are calculated lazily, when the value/property is
-requested by ~org-element-property~ and other getter functions.  Using
-~plist-get~ to retrieve values of =PROPERTIES-PLIST= is not
-recommended as deferred properties will not be resolved in such
-scenario.
+Previously, when the link to be stored were stored already,
+~org-store-link~ displayed a message and did nothing.
 
-New special property =:secondary= is used internally to record which
-properties store secondary objects.
+Now, ~org-store-link~ moves the stored link to front of the list of
+stored links.  This way, the link will show up first in the completion
+and when inserting all the stored links with ~org-insert-all-links~.
 
-New special property =:deferred= is used to keep information how to
-calculate property names lazily.
+*** =ox-html=: When exporting footnotes with custom non-number names, the 
names are used as link anchors
 
-See the commentary in =lisp/org-element-ast.el= for more details.
+Previously, link anchors for footnote references and footnote
+definitions were based on the footnote number: =fn.1=, =fnr.15=, etc.
 
-**** Multiple affiliated keyword values are now stored in the order they 
appear in buffer
+Now, when the footnote has a non-number name, it is used as an anchor:
+=fn.name=, =fnr.name=.
 
-Previously,
+*** Underline syntax now takes priority over subscript when both are applicable
 
-: #+caption: foo
-: #+caption: bar
-: Paragraph
+Previously, Org mode interpreted =(_text_)= as subscript.
+Now, the interpretation is changed to underline.
 
-would have its =:caption= property set to ~(("bar") ("foo"))~ in reverse order.
+=(_text_)= matches both subscript and underline markup.  The
+interpretation is changed to keep consistency with other emphasis like
+=(*bold*)=.
 
-Now, the order is not reversed: ~(("foo") ("bar"))~.
+Most of the users should not be affected by this change - it only applies when 
character immediately preceding =_= is one of =-=, =(=, ='=, and ={=.
 
-**** Some property values may now be calculated lazily and require original 
Org buffer to be live
+*** ~org-latex-to-mathml-convert-command~ and 
~org-latex-to-html-convert-command~ may need to be adjusted
 
-~org-element-at-point~, ~org-element-context~, and
-~org-element-at-point-no-context~ may now not calculate all the
-property values at the call time.  Instead, the calculation will be
-deferred until ~org-element-property~ or the equivalent getter
-function is called.  The property names may not all be calculated as
-well.
+Previously, =%i= placeholders in the
+~org-latex-to-mathml-convert-command~ and
+~org-latex-to-html-convert-command~ user options were replaced with
+raw LaTeX fragment text, potentially triggering shell-expansion and
+incorrect result.
 
-It may often be necessary to have the original Org buffer open when
-resolving the deferred values.
+Now, the =%i= placeholders are shell-escaped to prevent shell
+expansion.
 
-One can ensure that all the deferred values are resolved using new
-function ~org-element-resolve-deferred~ and new optional argument for
-~org-element-property~.
+If you have single or double quotes around =%i= then update
+customizations and remove quotes.
 
-~org-element-parse-buffer~ and ~org-element-parse-secondary-string~
-will resolve all the deferred values by default.  No adjustment is
-needed for their users.
+*** Org mode faces are now consistently combined, with markup faces taking 
precedence over the containing element faces
 
-**** New API functions and macros
-***** New property accessors and setters
+Previously, fontification of inline source blocks, macros, footnotes,
+target links, timestamps, radio targets, targets, inline export
+snippets, verbatim code, and COMMENT keyword in headings replaced the
+containing element fontification. Now, this is changed - the inner
+markup faces and the containing element faces are combined, with
+"inner" faces taking precedence; just as for all other markup.
 
-New functions to retrieve and set (via ~setf~) commonly used element 
properties:
-- =:begin= :: ~org-element-begin~
-- =:end= :: ~org-element-end~
-- =:contents-begin= :: ~org-element-contents-begin~
-- =:contents-end= :: ~org-element-contents-end~
-- =:post-affiliated= :: ~org-element-post-affiliated~
-- =:post-blank= :: ~org-element-post-blank~
-- =:parent= :: ~org-element-parent~
+*** When ~org-link-file-path-type~ is a function, its argument is now a 
filename as it is read by ~org-insert-link~; not an absolute path
 
-***** New macro ~org-element-with-enabled-cache~
+Previously, when ~org-link-file-path-type~ is set to a function, the
+function argument was the filename from the link expanded via
+~expand-file-name~.  Now, a bare filename is passed to the function.
 
-The macro arranges the element cache to be active during =BODY= execution.
-When cache is enabled, the macro is identical to ~progn~.  When cache
-is disabled, the macro arranges a new fresh cache that is discarded
-upon completion of =BODY=.
+*** =ox-org= preserves header non-default arguments in src blocks
 
-***** New function ~org-element-property-raw~
+Previously, all the header arguments where stripped from src blocks
+during export.  Now, header arguments are preserved as long as their
+values are not equal to the default header argument values.
 
-This function is like ~org-element-property~ but does not try to
-resolve deferred properties.
+*** =ox-org= disables citation processors by default
 
-~org-element-property-raw~ can be used with ~setf~.
+Previously, when exporting to Org, all the citations and
+=print_bibliography= keywords, were transformed according to the
+chosen citation processor.
 
-***** New function ~org-element-put-property-2~
+This is no loner the case.  All the citation-related markup is now
+exported as is.
 
-Like ~org-element-put-property~, but the argument list is changed to have
-=NODE= as the last argument.  Useful with threading macros like
-~thread-last~.
+The previous behavior can be reverted by setting new custom option
+~org-org-with-cite-processors~.
 
-***** New function ~org-element-properties-resolve~
+*** =ox-org= now exports special table rows by default
 
-This function resolves all the deferred values in a =NODE=, modifying
-the =NODE= for side effect.
+Previously, when exporting to Org, special table rows (for example,
+width cookies) were not exported.   Now, they are exported by default.
 
-***** New functions ~org-element-properties-map~ and 
~org-element-properties-mapc~
+You can customize new option ~org-org-with-special-rows~ to fall back to 
previous behavior.
 
-New functions to map over =NODE= properties.
+*** ~org-insert-subheading~ no longer inserts a sub-heading above current when 
point is at the beginning of line
 
-***** New function ~org-element-ast-map~
+Previously, calling ~org-insert-subheading~ on
 
-This is a more general equivalent of ~org-element-map~.  It allows
-more precise control over recursion into secondary strings.
+: * Heading 1
+: <point>* Heading 2
 
-***** New function ~org-element-lineage-map~
+yielded
 
-Traverse syntax tree ancestor list, applying arbitrary function to
-each ancestor.
+: * Heading 1
+: ** <point>
+: * Heading 2
 
-***** New function ~org-element-property-inherited~
+This is no longer the case.  The sub-heading is always created below
+current heading (prefix arguments have the same meaning as in
+~org-insert-heading~):
 
-Like ~org-element-property~, but can be used to retrieve and combine
-multiple different properties for a given =NODE= and its parents.
+: * Heading 1
+: * Heading 2
+: ** <point>
 
-**** ~org-element-cache-map~ can now be used even when element cache is 
disabled
+*** Org mode now fontifies whole table lines (including newline) according to 
~org-table~ face
 
-**** =org-element= API functions and macros can now accept syntax nodes as 
=POM= argument
+Previously, leading indentation and trailing newline in table rows
+were not fontified using ~org-table~ face.  ~default~ face was used instead.
+This made it impossible to scale line height when ~org-table~ face has
+smaller height than default (Emacs calculates line height using the tallest 
face).
 
-The following functions are updated:
-- ~org-agenda-entry-get-agenda-timestamp~
-- ~org-element-at-point~
-- ~org-is-habit-p~
-- ~org-id-get~
-- ~org-with-point-at~
-- ~org-entry-properties~
-- ~org-entry-get~
-- ~org-entry-delete~
-- ~org-entry-add-to-multivalued-property~
-- ~org-entry-remove-from-multivalued-property~
-- ~org-entry-member-in-multivalued-property~
-- ~org-entry-put-multivalued-property~
-- ~org-entry-get-with-inheritance~
-- ~org-entry-put~
-- ~org-read-property-value~
-- ~org-property-get-allowed-values~
+Now, new ~org-table-row~ face is used on the whole table row lines,
+including indentation and the final newline. This face, by default,
+inherits from ~org-table~ face.
 
-**** ~org-element-map~ now traverses main value in dual keywords before the 
secondary value
+If the new behavior is not desired, ~org-table-row~ face can be
+changed to inherit from ~default~ face.  See "Customizing Faces"
+section of Emacs manual or "Face Attribute Functions" section of Elisp
+manual.
 
-The traverse order for dual keywords is reversed.  The main value is
-now traversed first, followed by the secondary value.
+~org-table~ takes precedence over ~org-table-row~ for the parts of
+table rows without indentation and newline.
 
-**** Org parse tree is now non-printable
+*** =ox-latex=: ~org-latex-line-break-safe~ is deprecated
 
-Org parser now assigns a new property =:buffer= that holds
-non-printable buffer object.  This makes syntax tree non-printable.
-Using ~print~/~read~ is no longer safe.
+~org-latex-line-break-safe~ constant was previously introduced to deal
+with edge cases when LaTeX interprets [...] as LaTeX command
+argument.  However, it caused a number of other issues and proved
+itself not to be as "safe" as it supposed to be.
 
-**** Some Org API functions no longer preserve match data
+We now use a Pandoc's approach to deal with the same problem,
+utilizing ={[}= to escape =[...]= instances where needed.
 
-~org-element-at-point~, ~org-element-context~, ~org-get-category~, and
-~org-get-tags~ may modify the match data.
+*** ob-python now sets ~python-shell-buffer-name~ in Org edit buffers
 
-The relevant function docstrings now explicitly mention that match
-data may be modified.
+When editing a Python src block, the editing buffer is now associated
+with the Python shell specified by the src block's ~:session~ header,
+which means users can now send code directly from the edit buffer,
+e.g., using ~C-c C-c~, to the session specified in the Org buffer.
 
-**** ~org-element-create~ now treats a single ~anonymous~ =CHILDREN= argument 
as a list of child nodes
+*** ~org-edit-special~ no longer force-starts session in R and Julia source 
blocks
 
-When =CHILDREN= is a single anonymous node, use its contents as children
-nodes.  This way,
+Previously, when R/Julia source block had =:session= header argument
+set to a session name with "earmuffs" (like =*session-name*=),
+~org-edit-special~ always started a session, if it does not exist.
 
-: (org-element-create 'section nil (org-element-contents node))
+Now, ~org-edit-special~ arranges that a new session with correct name
+is initiated only when user explicitly executes R/Julia-mode commands
+that trigger session interactions (requires ESS 24.01.0 or newer).
+The same session will remain available in the context of Org babel.
 
-will yield expected results with contents of another node adopted into
-a newly created one.
+*** It is no longer allowed to tangle into the same file as Org source
 
-Previously, one had to use
+Previously, =file.org= with the following contents
 
-: (apply #'org-element-create 'section nil (org-element-contents node))
-**** New property ~:range-type~ for org-element timestamp object
+: #+begin_src org :tangle file.org
+: Text
+: #+end_src
 
-~org-element-timestamp-parser~ now adds =:range-type= property to each
-timestamp object.  Possible values: ~timerange~, ~daterange~, ~nil~.
+would overwrite itself.
 
-~org-element-timestamp-interpreter~ takes into account this property
-and returns an appropriate timestamp string.
+Now, an error is thrown.
 
-**** New properties =:repeater-deadline-value= and =:repeater-deadline-unit= 
for org-element timestamp object
+*** ~org-agenda-search-headline-for-time~ now ignores all the timestamp in 
headings
 
-~org-element-timestamp-parser~ now adds =:repeater-deadline-value= and
-=:repeater-deadline-unit= properties to each timestamp object that has
-a repeater deadline.  For example, in =<2012-03-29 Thu ++1y/2y>=, =2y=
-is the repeater deadline with a value of =2= and unit of =y=.  See
-"5.3.3 Tracking your habits" section in the manual.
+Previously, ~org-agenda-search-headline-for-time~ made Org agenda
+match anything resembling time inside headings.  Even when the time
+was a part of a timestamp.
 
-Possible values for =:repeater-deadline-value=: ~positive integer~, ~nil~.
+Now, all the timestamps in headings are ignored when searching the time.
 
-Possible values for =:repeater-deadline-unit=: ~hour~, ~day~, ~week~,
-~month~, ~year~.
+*** ODT export no longer opens the exported file in the background
 
-~org-element-timestamp-interpreter~ takes into account these properties
-and returns an appropriate timestamp string.
+ODT exporter used to open the exported file in ~archive-mode~ "for
+examination".  This was not documented, was done in the background,
+and is not consistent with all other export backends. Now, this
+feature is removed.
 
-**** =org-link= store functions are passed an ~interactive?~ argument
+*** ~org-print-speed-command~ is now an internal function
 
-The ~:store:~ functions set for link types using
-~org-link-set-parameters~ are now passed an ~interactive?~ argument,
-indicating whether ~org-store-link~ was called interactively.
+The old name is marked obsolete and the new name is
+~org--print-speed-command~.
 
-Existing store functions will continue to work.
+This function was always aimed for internal use when building speed
+command help buffer.  Now, it is stated explicitly.
 
 *** ~org-priority-show~ command no longer adjusts for scheduled/deadline
 
@@ -631,31 +669,6 @@ the item priority now.
 
 The behavior in Org buffers is unchanged.
 
-*** "Priority" used to sort items in agenda is renamed to "urgency"
-
-Previously, ~priority-up~ and ~priority-down~ in
-~org-agenda-sorting-strategy~ used a composite rank depending on
-item's priority (=[#A]=, =[#B]=, =[#C]=, etc) and overdue time to
-order agenda items (see "11.4.3 Sorting of agenda items" section of
-Org manual).
-
-Now, this composite rank is renamed to =urgency= and the relevant
-sorting strategies are renamed to ~urgency-up~ and ~urgency-down~.
-~priority-up~ and ~priority-down~ sort by item's priority only.
-
-Users relying on the previous composite ranking should adjust their
-agenda sorting settings.
-
-*** =python-mode.el (MELPA)= support in =ob-python.el= is removed
-
-=python-mode.el= support has been removed from =ob-python.el=.  The
-related customization =org-babel-python-mode= has been changed to a
-constant.
-
-If you still want to use python-mode with ob-python, you might
-consider 
[[https://gitlab.com/jackkamm/ob-python-mode-mode][ob-python-mode-mode]], where 
the code to support python-mode
-has been ported to.
-
 *** =ox-icalendar.el= line ending fix may affect downstream packages
 
 iCalendar export now uses dos-style CRLF ("\r\n") line endings
@@ -701,18 +714,6 @@ The change is breaking when ~org-use-property-inheritance~ 
is set to ~t~.
 
 The =TEST= parameter is better served by Emacs debugging tools.
 
-*** =id:= links support search options; ~org-id-store-link~ adds search option 
by default
-
-Adding search option by ~org-id-store-link~ can be disabled by setting
-~org-id-link-use-context~ to ~nil~, or toggled for a single call by
-passing universal argument.
-
-When using this feature, IDs should not include =::=, which is used in
-links to indicate the start of the search string.  For backwards
-compability, existing IDs including =::= will still be matched (but
-cannot be used together with search option).  A new org-lint checker
-has been added to warn about this.
-
 *** ~org-store-link~ behaviour storing additional =CUSTOM_ID= links has changed
 
 Previously, when storing =id:= link, ~org-store-link~ stored an
@@ -1174,6 +1175,87 @@ levels one and two as Setext style headlines, and 
headline levels
 three through six will be exported as ATX style headlines.
 
 ** New features
+*** Images and files in clipboard can be pasted
+
+Org asks the user what must be done when pasting images and files
+copied to the clipboard from a file manager using the ~yank-media~
+command.  The default action can be set by customizing
+~org-yank-dnd-method~.  The ~yank-media~ command was added in Emacs
+29.
+
+Images can be saved to a separate directory instead of being attached,
+customize ~org-yank-image-save-method~.
+
+Image filename chosen can be customized by setting
+~org-yank-image-file-name-function~ which by default autogenerates a
+filename based on the current time.
+
+*** Files and images can be attached by dropping onto Emacs
+
+By default, Org asks the user what to do with the dropped file like
+for pasted files.  The same user option ~org-yank-dnd-method~ is
+respected.
+
+Images dropped also respect the value of ~org-yank-image-save-method~
+when ~org-yank-dnd-method~ is =attach=.
+
+*** ~org-paste-subtree~ now handles =C-u= and =C-u C-u= prefix arguments 
specially
+
+With =C-u= prefix argument, force inserting a sibling heading below.
+With =C-u C-u= prefix argument, force inserting a child heading.
+
+*** ~org-metaup~ and ~org-metadown~ now act on headings in region
+
+When region is active and starts at a heading, ~org-metaup~ and
+~org-metadown~ will move all the selected subtrees.
+
+*** Many structure editing commands now do not deactivate region
+
+Moving, promoting, and demoting of headings and items in region now do
+not deactivate Transient mark mode.
+
+Users can thus conveniently select multiple headings/items and use,
+for example, =M-<down>=/=M-<up>= repeatedly without losing the
+selection.
+
+*** Capture templates now support ~(here)~ as a target
+
+A capture template can target ~(here)~ which is the equivalent of
+invoking a capture template with a zero prefix.
+
+*** Asynchronous code evaluatation in ~ob-shell~
+
+Running shell blocks with the ~:session~ header freezes Emacs until
+execution completes.  The new ~:async~ header allows users to continue
+editing with Emacs while a ~:session~ block executes.
+
+*** Add support for repeating tasks in iCalendar export
+
+Repeating Scheduled and Deadline timestamps in TODOs are now exported
+as recurring tasks in iCalendar export.
+
+In case the TODO has just a single planning timestamp (Scheduled or
+Deadline, but not both), its repeater is used as the iCalendar
+recurrence rule (RRULE).
+
+If the TODO has both Scheduled and Deadline planning timestamps, then
+the following cases are implemented:
+
+- If both have the same repeater, then it is used as the RRULE.
+- Scheduled has repeater but Deadline does not: the Scheduled repeater
+  is used as RRULE, and Deadline is used as UNTIL (the end date for
+  the repeater). This is similar to ~repeated-after-deadline~ in
+  ~org-agenda-skip-scheduled-if-deadline-is-shown~.
+
+The following 2 cases are not yet implemented, and the repeater is
+skipped (with a warning) if the ox-icalendar export encounters them:
+
+- Deadline has a repeater but Scheduled does not.
+- Scheduled and Deadline have different repeaters.
+
+Also note that only vanilla repeaters are currently exported; the
+special repeaters ~++~ and ~.+~ are skipped.
+
 *** =ob-lua=: Support all types and multiple values in results
 
 Lua code blocks can now return values of any type and can also return
@@ -1186,11 +1268,6 @@ Multiple values are comma-separated by default, so that 
they work well
 with inline code blocks.  To change the string used as the separator,
 customize ~org-babel-lua-multiple-values-separator~.
 
-*** ~org-paste-subtree~ now handles =C-u= and =C-u C-u= prefix arguments 
specially
-
-With =C-u= prefix argument, force inserting a sibling heading below.
-With =C-u C-u= prefix argument, force inserting a child heading.
-
 *** =colview= dynamic block now writes column width specifications
 
 When column format contains width specifications, =colview= dynamic
@@ -1322,68 +1399,16 @@ the =org.freedesktop.login1= interface is available, 
fallback to
 checking the =IdleSinceHint= property when
 determining =org-user-idle-seconds= as the penultimate step.
 
-*** ~org-metaup~ and ~org-metadown~ now act on headings in region
-
-When region is active and starts at a heading, ~org-metaup~ and
-~org-metadown~ will move all the selected subtrees.
-
-*** Many structure editing commands now do not deactivate region
-
-Moving, promoting, and demoting of headings and items in region now do
-not deactivate Transient mark mode.
-
-Users can thus conveniently select multiple headings/items and use,
-for example, =M-<down>=/=M-<up>= repeatedly without losing the
-selection.
-
 *** Datetree structure headlines can now be complex
 
 TODO state, priority, tags, statistics cookies, and COMMENT keywords
 are allowed in the tree structure.
 
-*** Asynchronous code evaluatation in ~ob-shell~
-
-Running shell blocks with the ~:session~ header freezes Emacs until
-execution completes.  The new ~:async~ header allows users to continue
-editing with Emacs while a ~:session~ block executes.
-
 *** ~org-return~ now acts on citations at point
 
 When ~org-return-follows-link~ is non-nil and cursor is over an
 org-cite citation, ~org-return~ will call ~org-open-at-point~.
 
-*** Add support for repeating tasks in iCalendar export
-
-Repeating Scheduled and Deadline timestamps in TODOs are now exported
-as recurring tasks in iCalendar export.
-
-In case the TODO has just a single planning timestamp (Scheduled or
-Deadline, but not both), its repeater is used as the iCalendar
-recurrence rule (RRULE).
-
-If the TODO has both Scheduled and Deadline planning timestamps, then
-the following cases are implemented:
-
-- If both have the same repeater, then it is used as the RRULE.
-- Scheduled has repeater but Deadline does not: the Scheduled repeater
-  is used as RRULE, and Deadline is used as UNTIL (the end date for
-  the repeater). This is similar to ~repeated-after-deadline~ in
-  ~org-agenda-skip-scheduled-if-deadline-is-shown~.
-
-The following 2 cases are not yet implemented, and the repeater is
-skipped (with a warning) if the ox-icalendar export encounters them:
-
-- Deadline has a repeater but Scheduled does not.
-- Scheduled and Deadline have different repeaters.
-
-Also note that only vanilla repeaters are currently exported; the
-special repeaters ~++~ and ~.+~ are skipped.
-
-*** Capture templates now support ~(here)~ as a target
-
-A capture template can target ~(here)~ which is the equivalent of
-invoking a capture template with a zero prefix.
-
 *** ~org-tags-view~ supports more property operators
 
 It supports inequality operators ~!=~ and ~/=~ in addition to the less
@@ -1428,30 +1453,6 @@ matrix or a vector depending on the dimensionality of 
the table.  A
 table with a single row is converted to a vector, the rest are
 converted to a matrix.
 
-*** Images and files in clipboard can be pasted
-
-Org asks the user what must be done when pasting images and files
-copied to the clipboard from a file manager using the ~yank-media~
-command.  The default action can be set by customizing
-~org-yank-dnd-method~.  The ~yank-media~ command was added in Emacs
-29.
-
-Images can be saved to a separate directory instead of being attached,
-customize ~org-yank-image-save-method~.
-
-Image filename chosen can be customized by setting
-~org-yank-image-file-name-function~ which by default autogenerates a
-filename based on the current time.
-
-*** Files and images can be attached by dropping onto Emacs
-
-By default, Org asks the user what to do with the dropped file like
-for pasted files.  The same user option ~org-yank-dnd-method~ is
-respected.
-
-Images dropped also respect the value of ~org-yank-image-save-method~
-when ~org-yank-dnd-method~ is =attach=.
-
 *** Add completion for links to man pages
 
 Completion is enabled for links to man pages added using ~org-insert-link~:
@@ -1474,11 +1475,6 @@ place the entry in the ~Misc~ category if 
~TEXINFO_DIR_CATEGORY~ is missing.
 The old name is obsolete.
 
 ** New functions and changes in function arguments
-*** New optional argument =UPDATE-HEADING= for ~org-bibtex-yank~
-
-When the new argument is non-nil, add data to the headline of the
-entry at point.
-
 *** New API functions to store data within ~org-element-cache~
 
 Elisp programs can now store data inside Org element cache.
@@ -1496,6 +1492,11 @@ Two options are available:
 The new functions are: ~org-element-cache-store-key~ and
 ~org-element-cache-get-key~.
 
+*** New optional argument =UPDATE-HEADING= for ~org-bibtex-yank~
+
+When the new argument is non-nil, add data to the headline of the
+entry at point.
+
 *** ~org-fold-hide-drawer-all~ is now interactive
 
 ~org-fold-hide-drawer-all~ is now a command, accepting two optional