GNU-devel ELPA - org

ORG NEWS -- history of user-visible changes.   -*- mode: org; coding: utf-8 -*-

#+STARTUP: overview

#+LINK: doc https://orgmode.org/worg/doc.html#%s
#+LINK: msg https://list.orgmode.org/%s/
#+LINK: git https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=%s

Copyright (C) 2012-2023 Free Software Foundation, Inc.
See the end of the file for license conditions.

Please send Org bug reports to mailto:emacs-orgmode@gnu.org.

* Version 9.7 (not released yet)
** Important announcements and breaking changes
*** New export option ~org-export-expand-links~

The new option makes Org expand environment variables in link and INCLUDE paths.
The option is on by default.

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 API
**** New term: "syntax node"

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.

**** New element type ~anonymous~

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.

The new element type can be used in ~org-element-lineage~,
~org-element-map~, and other functions that filter by element type.

**** Internal structure of Org parse tree has been changed

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.

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.

If there is a need to traverse all the node properties, a new API
function ~org-element-properties-map~ can be used.

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.

New special property =:secondary= is used internally to record which
properties store secondary objects.

New special property =:deferred= is used to keep information how to
calculate property names lazily.

See the commentary in =lisp/org-element-ast.el= for more details.

**** Multiple affiliated keyword values are now stored in the order they appear in buffer

Previously,

: #+caption: foo
: #+caption: bar
: Paragraph

would have its =:caption= property set to ~(("bar") ("foo"))~ in reverse order.

Now, the order is not reversed: ~(("foo") ("bar"))~.

**** Some property values may now be calculated lazily and require original Org buffer to be live

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

It may often be necessary to have the original Org buffer open when
resolving the deferred values.
...
...