feed1160caad9ea347e5eca9bfd22d635aae15fe — Bastien 1 year, 6 months ago 8e0dd45
Changes.org: Update release notes
1 files changed, 530 insertions(+), 409 deletions(-)

M Changes.org
M Changes.org => Changes.org +530 -409
@@ 14,573 14,694 @@ You can keep up with upcoming changes, requests for help, bug reports
and submitted patch by checking [[https://updates.orgmode.org][updates.orgmode.org]] and by subscribing
to the RSS feeds there.

* Version 9.5
* Version 9.6

** Important announcements and breaking changes
*** =python-mode.el (MELPA)= support in =ob-python.el= is deprecated

*** The =contrib/= now lives in a separate repository
We no longer aim to support third-party =python-mode.el= implementation of Python REPL.
Only the built-in =python.el= will be supported from now on.

Org's repository has been trimmed from the =contrib/= directory.
We still keep the old, partially broken, code in =ob-python.el= for
the time being.  It will be removed in the next release.

The old contents of the =contrib/= directory now lives in a separate
repository at https://git.sr.ht/~bzg/org-contrib.
See https://orgmode.org/list/87r0yk7bx8.fsf@localhost for more details.

You can install this repository by cloning it and updating your
~load-path~ accordingly.  You can also install =org-contrib= as a
[[https://elpa.nongnu.org/nongnu/][NonGNU ELPA]] package.
*** Element cache is enabled by default and work for headings

*** Org ELPA and Org archives won't be available for Org > 9.5
The old element cache code has been refactored.  Emacs does not hang
anymore when the cache is enabled.

[[https://orgmode.org/elpa.html][Org ELPA]] is still available for installing Org 9.5, either with or
without contributed packages, but future versions won't be available
via Org ELPA, as we are deprecating this installation method.
When cache is enabled, ~org-element-at-point~ for headings is
guaranteed to return valid =:parent= property.  The highest-level
headings contain new =org-data= element as their parent.

Also, Org 9.5 is available as =tar.gz= and =zip= archives, but this
installation method is also deprecated.
The new =org-data= element provides properties from top-level property
drawer, buffer-global category, and =:path= property containing file
path for file Org buffers.

If you want to install the latest stable versions of Org, please use
the GNU ELPA package.  If you want to install the contributed files,
please use the NonGNU ELPA package.  If you want to keep up with the
latest unstable Org, please install from the Git repository.
The new cache still need to be tested extensively.  Please, report any
warning coming from element cache.  If you see warnings regularly, it
would be helpful to set ~org-element--cache-self-verify~ to
='backtrace= and provide the backtrace to Org mailing list.

See https://orgmode.org/org.html#Installation for the details.
*** Element cache persists across Emacs sessions

*** =ditaa.jar= is not bundled with Org anymore
The cache state is saved between Emacs sessions.  Enabled by default.

=ditaa.jar= used to be bundled with Org but it is not anymore.
See [[https://github.com/stathissideris/ditaa][the ditaa repository]] on how to install it.
The cache persistence can be controlled via

*** ~org-adapt-indentation~ now defaults to =nil=
*** Users experiencing performance issues can use new folding backend

If you want to automatically indent headlines' metadata, set it to
The old folding backend used in Org is poorly scalable when the file
size increases beyond few Mbs.  The symptoms usually include slow
cursor motion, especially in long-running Emacs sessions.

If you want to automatically indent every line to the headline's
current indentation, set it to =t=.
A new optimised folding backend is now available, and enabled by
default.  To disable it, put the following to the Emacs config *before*
loading Org:

Indent added by =RET= and =C-j= also depends on the value of
~electric-indent-mode~.  Enabling this mode by default in 9.4 revealed
some bugs caused confusing behavior.  If you disabled
~electric-indent-mode~ for this reason, it is time to try it again.
Hopefully problems have been fixed.  See [[https://orgmode.org/worg/org-faq.html#indentation][this FAQ]] for more details.
#+begin_src emacs-lisp
(setq org-fold-core-style 'overlays)

Even more performance optimisation can be enabled by customising
=org-fold-core--optimise-for-huge-buffers=.  However, this option may
be dangerous.  Please, read the variable docstring carefully to
understand the possible consequences.

When =org-fold-core-style= is set to =text-properties=, several new
features will become available and several notable changes will happen
to the Org behaviour.  The new features and changes are listed below.

**** Hidden parts of the links can now be searched and revealed during isearch

In the past, hidden parts of the links could not be searched using
isearch (=C-s=).  Now, they are searchable by default.  The hidden
match is also revealed temporarily during isearch.

To restore the old behaviour add the following core to your Emacs

#+begin_src emacs-lisp
(defun org-hidden-link-ignore-isearch ()
  "Do not match hidden parts of links during isearch."
  (org-fold-core-set-folding-spec-property 'org-link :isearch-open nil)
  (org-fold-core-set-folding-spec-property 'org-link :isearch-ignore t))
(add-hook 'org-mode-hook #'org-hidden-link-ignore-isearch)

See docstring of =org-fold-core--specs= to see more details about
=:isearch-open= and =:isearch-ignore= properties.

**** =org-catch-invisible-edits= now works for hidden parts of the links and for emphasis markers

*** ~org-speed-commands-user~ is obsolete, use ~org-speed-commands~
In the past, user could edit invisible parts of the links and emphasis markers.  Now, the editing is respecting the value of =org-catch-invisible-edits=.

Setting ~org-speed-commands-user~ in your configuration won't have any
effect.  Please set ~org-speed-commands~ instead, which see.
Note that hidden parts of sub-/super-scripts are still not handled.

*** Some =ob-*.el= files have been moved to the org-contrib repo
**** Breaking structure of folded elements automatically reveals the folded text

These files have been moved to https://git.sr.ht/~bzg/org-contrib:
In the past, the user could be left with unfoldable text after breaking the org structure.

- ob-abc.el
- ob-asymptote.el
- ob-coq.el
- ob-ebnf.el
- ob-hledger.el
- ob-io.el
- ob-J.el
- ob-ledger.el
- ob-mscgen.el
- ob-picolisp.el
- ob-shen.el
- ob-stan.el
- ob-vala.el
For example, if

See the discussion [[msg::87bl9rq29m.fsf@gnu.org][here]].
#+begin_src org
like this

*** Compatibility with Emacs versions
is folded and then edited into

We made it explicit that we aim at keeping the latest stable version
of Org compatible with at least Emacs V, V-1 and V-2, where V is the
stable major version of Emacs.
#+begin_src org
like this
The hidden text would not be revealed.

For example, if the current major version of Emacs is 28.x, then the
latest stable version of Org should be compatible with Emacs 28.x,
27.x and 26.x – but not with Emacs 25.x.
Now, breaking structure of drawers, blocks, and headings automatically
reveals the folded text.

See [[https://orgmode.org/worg/org-maintenance.html#emacs-compatibility][this note on Worg]] and [[git::519947e508e081e71bf67db99e27b1c171ba4dfe][this commit]].
**** Folding state of the drawers is now preserved when cycling headline visibility

*** The keybinding for ~org-table-blank-field~ has been removed
In the past drawers were folded every time a headline is unfolded.

If you prefer to keep the keybinding, you can add it back to
~org-mode-map~ like so:
Now, it is not the case anymore.  The drawer folding state is
preserved.  The initial folding state of all the drawers in buffer is
set according to the startup visibility settings.

To restore the old behaviour, add the following code to Emacs config:

#+begin_src emacs-lisp
(define-key org-mode-map (kbd "C-c SPC") #'org-table-blank-field)
(add-hook 'org-cycle-hook #'org-cycle-hide-drawers)

** New features
Note that old behaviour may cause performance issues when cycling
headline visibility in large buffers.

*** New citation engine
**** =outline-*= functions may no longer work correctly in Org mode

Org 9.5 provides a new library =oc.el= which provides tooling to
handle citations in Org, e.g., activate, follow, insert, and export
them, respectively called "activate", "follow", "insert" and "export"
capabilities.  Libraries responsible for providing some, or all, of
these capabilities are called "citation processors".
The new folding backend breaks some of the =outline-*= functions that
rely on the details of visibility state implementation in
=outline.el=.  The old Org folding backend was compatible with the
=outline.el= folding, but it is not the case anymore with the new
backend.  From now on, using =outline-*= functions is strongly
discouraged when working with Org files.

The manual contains a few pointers to let you start and you may want
to check [[https://blog.tecosaur.com/tmio/2021-07-31-citations.html][this blog post]].  If you need help using this new features,
please ask on the mailing list.
*** HTML export uses MathJax 3+ instead of MathJax 2

Thanks to Nicolas Goaziou for implementing this, to Bruce D’Arcus for
helping him and to John Kitchin for paving the way with =org-ref.el=.
Org now uses MathJax 3 by default instead of MathJax 2.  During HTML
exports, Org automatically converts all legacy MathJax 2 options to
the corresponding MathJax 3+ options, except for the ~path~ option in
which now /must/ point to a file containing MathJax version 3 or
later.  The new Org does /not/ work with the legacy MathJax 2.

*** Async session evaluation
Further, if you need to use a non-default ~font~ or ~linebreaks~ (now
~overflow~), then the ~path~ must point to MathJax 4 or later.

The =:async= header argument can be used for asynchronous evaluation
in session blocks for certain languages.
See the updated ~org-html-mathjax-options~ for more details.

Currently, async evaluation is supported in Python.  There is also
functionality to implement async evaluation in other languages that
use comint, but this needs to be done on a per-language basis.
MathJax 3, a ground-up rewrite of MathJax 2 came out in 2019.  The new
version brings modularity, better and faster rendering, improved LaTeX
support, and more.

By default, async evaluation is disabled unless the =:async= header
argument is present.  You can also set =:async no= to force it off
(for example if you've set =:async= in a property drawer).
For more information about new features, see:

Async evaluation is disabled during export.
*** ~ox-koma-letter.el~ is now part of Org's core

~ox-koma-letter.el~ provides a KOMA scrlttr2 back-end for the Org
export engine.  It used to be in the =contrib/= directory but it is
now part of Org's core.
MathJax 3 comes with useful extensions.  For instance, you can typeset
calculus with the ~physics~ extension or chemistry with the ~mhchem~
extension, like in LaTeX.

*** Support exporting DOI links
Note that the Org manual does not discuss loading of MathJax
extensions via ~+HTML_MATHJAX~ anymore.  It has never worked anyway.
To actually load extensions, consult the official documentation:

Org now supports export for DOI links, through its new =ol-doi.el=
library.  For backward compatibility, it is loaded by default.

*** Add a new ~:refile-targets~ template option
Lastly, MathJax 3 changed the default JavaScript content delivery
network (CDN) provider from CloudFlare to jsDelivr.  You can find the
new terms of service, including the privacy policy, at

** New features
*** Clock table can now produce quarterly reports

When exiting capture mode via ~org-capture-refile~, the variable
~org-refile-targets~ will be temporarily bound to the value of this
template option.
=:step= clock table parameter can now be set to =quarter=.
*** Publishing now supports links to encrypted Org files

*** New startup options =#+startup: show<n>levels=
Links to other published Org files are automatically converted to the
corresponding html links.  Now, this feature is also available when
links point to encrypted Org files, like

These startup options complement the existing =overview=, =content=,
=showall=, =showeverything= with a way to start the document with n
levels shown, where n goes from 2 to 5.
*** Interactive commands now support escaping text inside comment blocks

~org-edit-special~ and ~org-insert-structure-template~ now handle
comment blocks.

: #+startup: show3levels
See [[*New command ~org-edit-comment-block~ to edit comment block at

*** New =u= table formula flag to enable Calc units simplification mode
*** New customization option =org-property-separators=
A new alist variable to control how properties are combined.

A new =u= mode flag for Calc formulas in Org tables has been added to
enable Calc units simplification mode.
If a property is specified multiple times with a =+=, like

*** Support fontification of inline export snippets
#+begin_src org
:EXPORT_FILE_NAME: some/path

See [[msg:87im57fh8j.fsf@gmail.com][this thread]].
the old behavior was to always combine them with a single space
(=some/path to/file=).  For the new variable, the car of each item in
the alist should be either a list of property names or a regular
expression, while the cdr should be the separator to use when
combining that property.

*** New command =org-refile-reverse= bound to =C-c C-M-w=
The default value for the separator is a single space, if none of the
provided items in the alist match a given property.

You can now use =C-c C-M-w= to run ~org-refile-reverse~.
For example, in order to combine =EXPORT_FILE_NAME= properties with a
forward slash =/=, one can use

It is almost identical to ~org-refile~, except that it temporarily
toggles how ~org-reverse-note-order~ applies to the current buffer.
So if ~org-refile~ would append the entry as the last entry under the
target heading, ~org-refile-reverse~ will prepend it as the first
entry, and vice-versa.
#+begin_src emacs-lisp
(setq org-property-separators '((("EXPORT_FILE_NAME") . "/")))

*** LaTeX attribute ~:float~ now passes through arbitrary values
The example above would then produce the property value

LaTeX users are able to define arbitrary float types, e.g. with the
float package.  The Org mode LaTeX exporter is now able to process and
export arbitrary float types.  The user is responsible for ensuring
that Org mode configures LaTeX to process any new float type.
*** New library =org-persist.el= implements variable persistence across Emacs sessions

*** Support verse and quote blocks in LaTeX export
The library stores variable data in ~org-persist-directory~ (set to XDG
cache dir by default).

The LaTeX export back-end accepts four attributes for verse blocks:
=:lines=, =:center=, =:versewidth= and =:latexcode=. The three first
require the external LaTeX package =verse.sty=, which is an extension
of the standard LaTeX environment.
The entry points are ~org-persist-register~, ~org-persist-unregister~,
~org-persist-read~, and ~org-persist-read-all~.  Storing circular
structures is supported.  Storing references between different
variables is also supported (see =:inherit= key in

The LaTeX export back-end accepts two attributes for quote blocks:
=:environment=, for an arbitrary quoting environment (the default
value is that of =org-latex-default-quote-environment=: ="quote"=) and
The library permits storing buffer-local variables.  Such variables
are linked to the buffer text, file =inode=, and file path.

*** =org-set-tags-command= selects tags from ~org-global-tags-completion-table~
*** New =:options= attribute when exporting tables to LaTeX

Let ~org-set-tags-command~ TAB fast tag completion interface complete
tags including from both buffer local and user defined persistent
global list (~org-tag-alist~ and ~org-tag-persistent-alist~).  Now
option ~org-complete-tags-always-offer-all-agenda-tags~ is honored.
The =:options= attribute allows adding an optional argument with a
list of various table options (between brackets in LaTeX export),
since certain tabular environments, such as longtblr of the
tabularray LaTeX package, provides this structure.

*** Clocktable option =:formula %= now shows the per-file time percentages
*** New =:compact= attribute when exporting lists to Texinfo

This change only has an effect when multiple files are contributing to
a given clocktable (such as when =:scope agenda= has been specified).
The existing behavior is that such tables have an extra 'File' column,
and each individual file that contributes has its own summary line
with the headline value '*File time*'.  Those summary rows also
produce a rollup time value for the file in the 'Time' column.
The =:compact= attribute allows exporting multiple description list
items to one =@item= command and one or more =@itemx= commands.  This
feature can also be enabled for all description lists in a file using
the =compact-itemx= export option, or globally using the
~org-texinfo-compact-itemx~ variable.

Prior to this change, the built-in =%= formula did not produce a
calculation for those per-file times in the '%' column (the relevant
cells in the '%' column were blank).  With this change, the percentage
contribution of each individual file time to the total time is shown.
*** New shorthands recognized when exporting to Texinfo

The more agenda files you have, the more useful this behavior becomes.
Items in a description list that begin with =Function:=, =Variable:=
or certain related prefixes are converted using Texinfo definition
*** New =:noweb-prefix= babel header argument

*** =ob-python.el= improvements to =:return= header argument
=:noweb-prefix= can be set to =no= to prevent the prefix characters
from being repeated when expanding a multiline noweb reference.

The =:return= header argument in =ob-python= now works for session
blocks as well as non-session blocks.  Also, it now works with the
=:epilogue= header argument -- previously, setting the =:return=
header would cause the =:epilogue= to be ignored.
*** New =:noweb= babel header argument value =strip-tangle=

This change allows more easily moving boilerplate out of the main code
block and into the header. For example, for plotting, we need to add
boilerplate to save the figure to a file and return the
filename. Instead of doing this within the code block, we can now
handle it through the header arguments as follows:
=:noweb= can be set to =strip-tangle= to strip the noweb syntax references
before tangling.

,#+header: :var fname="/home/jack/tmp/plot.svg"
,#+header: :epilogue plt.savefig(fname)
,#+header: :return fname
,#+begin_src python :results value file
  import matplotlib, numpy
  import matplotlib.pyplot as plt
*** New LaTeX source block backend using =engraved-faces-latex=

When ~org-latex-src-block-backend~ is set to ~engraved~,
=engrave-faces-latex= from [[http://elpa.gnu.org/packages/engrave-faces.html][engrave-faces]] is used to transcode source
blocks to LaTeX. This requires the =fvextra=, =float=, and (by
default, but not necessarily) =tcolorbox= LaTeX packages be
installed. It uses Emacs' font-lock information, and so tends to
produce results superior to Minted or Listings.
*** Support for =#+include=-ing URLs

As another example, we can use =:return= with the external [[https://pypi.org/project/tabulate/][tabulate]]
package, to convert pandas Dataframes into orgmode tables:
=#+include: FILE= will now accept URLs as the file.
*** Structure templates now respect case used in ~org-structure-template-alist~

The block type in ~org-structure-template-alist~ is not case-sensitive.
When the block type starts from the upper case, structure template
will now insert =#+BEGIN_TYPE=.  Previously, lower-case =#+begin_type= was inserted unconditionally.
*** New ox-latex tabbing support for tables.

Latex tables can now be exported to the latex tabbing environment
tabbing environment]].
This is done by adding =#+ATTR_LATEX: :mode tabbing= at the top
of the table.
The default column width is set to 1/n times the latex textwidth,
where n is the number of columns.
This behaviour can be changed by supplying a =:align= parameter.

The tabbing environment can be useful when generating simple tables which
can be span multiple pages and when table cells are allowed to overflow.
*** Support for =nocite= citations and sub-bibliographies in the "csl" export processor

The "csl" citation export processor now supports =nocite= style
citations that add items to the printed bibliography without visible
references in the text. Using the key =*= in a nocite citation, for

#+begin_src org
,#+header: :prologue from tabulate import tabulate
,#+header: :return tabulate(table, headers=table.columns, tablefmt="orgtbl")
,#+begin_src python :results value raw :session
  import pandas as pd
  table = pd.DataFrame({
      "a": [1,2,3],
      "b": [4,5,6]

|   | a | b |
| 0 | 1 | 4 |
| 1 | 2 | 5 |
| 2 | 3 | 6 |

*** Display images with width proportional to the buffer text width
includes all available items in the printed bibliography.

Previously, if you used a =:width= attribute like =#+attr_html: :width 70%= or
=#+attr_latex: :width 0.7\linewidth= this would be interpreted as a 70px wide and
0.7px wide width specification respectively.
The "csl" export processor now also supports sub-bibliographies that
show only a subset of the references based on some criterion.  For

Now, percentages are transformed into floats (i.e. 70% becomes 0.7),
and float width specifications between 0.0 and 2.0 are now interpreted
as that portion of the text width in the buffer. For instance, the
above examples of =70%= and =0.7\linewidth= will result in an image
with width equal to the pixel-width of the buffer text multiplied by 0.7.
#+begin_src org
#+print_bibliography: :type book :keyword ai

This functionality is implemented in a new function,
~org-display-inline-image--width~ which contains the width
determination logic previously in ~org-display-inline-images~ and the
new behaviour.
prints a sub-bibliography containing the book entries with =ai= among
their keywords.
*** New =:filetitle= option for clock table

** New options
*** Option ~org-hidden-keywords~ now also applies to #+SUBTITLE:
The =:filetitle= option for clock tables can be set to ~t~ to show org
file title (set by =#+title:=) in the File column instead of the
file name.  For example:

The option ~org-hidden-keywords~ previously applied
to #+TITLE:, #+AUTHOR:, #+DATE:, and #+EMAIL:.  Now it can also be
used to hide the #+SUBTITLE: keyword.
#+begin_src org
,#+BEGIN: clocktable :scope agenda :maxlevel 2 :block thisweek :filetitle t

*** New formatting directive ~%L~ for org-capture
If a file does not have a title, the table will show the file name
*** New =org-md-toplevel-hlevel= variable for Markdown export

The new ~%L~ formatting directive contains the bare link target, and
may be used to create links with programmatically generated
The =org-md-toplevel-hlevel= customization variable sets the heading
level used for top level headings, much like how
=org-html-toplevel-hlevel= sets the heading level used for top level
headings in HTML export.
*** Babel: new syntax to pass the contents of a src block as argument

*** New option ~org-id-ts-format~
Use the header argument =:var x=code-block[]= or
: #+CALL: fn(x=code-block[])
to pass the contents of a named code block as a string argument.
*** New property =ORG-IMAGE-ACTUAL-WIDTH= for overriding global ~org-image-actual-width~

Earlier, IDs generated using =ts= method had a hard-coded format (i.e. =20200923T160237.891616=).
The new option allows user to customise the format.
Defaults are unchanged.
The new property =ORG-IMAGE-ACTUAL-WIDTH= can override the global
variable ~org-image-actual-width~ value for inline images display width.

*** New argument for ~file-desc~ babel header
*** Outline cycling can now include inline image visibility

It is now possible to provide the =file-desc= header argument for a
babel source block but omit the description by passing an empty vector
as an argument (i.e., :file-desc []).  This can be useful because
providing =file-desc= without an argument results in the result of
=file= being used in the description.  Previously, the only way to
omit a file description was to omit the header argument entirely,
which made it difficult/impossible to provide a default value for
New ~org-cycle-hook~ function ~org-cycle-display-inline-images~ for
auto-displaying inline images in the visible parts of the subtree.
This behavior is controlled by new custom option

*** New option to set ~org-link-file-path-type~ to a function
*** New ~org-babel-tangle-finished-hook~ hook run at the very end of ~org-babel-tangle~

~org-link-file-path-type~ can now be set to a function that takes the
full filename as an argument and returns the path to link to.
This provides a proper counterpart to ~org-babel-pre-tangle-hook~, as
~org-babel-post-tangle-hook~ is run
per-tangle-destination. ~org-babel-tangle-finished-hook~ is just run
once after the post tangle hooks.

For example, if you use ~project.el~, you can set this function to use
relative links within a project as follows:
*** New =:backend= header argument for clojure code blocks

#+begin_src emacs-lisp
(setq (org-link-file-path-type
       (lambda (path)
         (let* ((proj (project-current))
                (root (if proj (project-root proj) default-directory)))
           (if (string-prefix-p (expand-file-name root) path)
               (file-relative-name path)
             (abbreviate-file-name path))))))
The =:backend= header argument on clojure code blocks can override the
value of ~org-babel-clojure-backend~. For example:

#+begin_src clojure :backend babashka
(range 2)

*** New options and new behavior for babel LaTeX SVG image files
*** New =:results discard= header argument

Org babel now uses a two-stage process for converting latex source
blocks to SVG image files (when the extension of the output file is
~.svg~).  The first stage in the process converts the latex block into
a PDF file, which is then converted into an SVG file in the second
stage.  The TeX->PDF part uses the existing infrastructure for
~org-babel-latex-tex-to-pdf~.  The PDF->SVG part uses a command
specified in a new customization,
~org-babel-latex-pdf-svg-process~. By default, this uses inkscape for
conversion, but since it is fully customizable, any other command can
be used in its place. For instance, dvisvgm might be used here. This
two-part processing replaces the previous use of htlatex to process
LaTeX directly to SVG (htlatex is still used for HTML conversion).
Unlike =:results none=, the return value of code blocks called with
=:results discard= header argument is always ~nil~.  Org does not
attempt to analyze the results and simply returns nil.  This can be
useful when the code block is used for side effects only but generates
large outputs that may be slow to analyze for Org.

Conversion to SVG exposes a number of additional customizations that
give the user full control over the contents of the latex source
block. ~org-babel-latex-preamble~, ~org-babel-latex-begin-env~ and
~org-babel-latex-end-env~ are new customization options added to allow
the user to specify the preamble and code that preceedes and proceeds
the contents of the source block.
** New options
*** A new option for custom setting ~org-refile-use-outline-path~ to show document title in refile targets

*** New option ~org-html-meta-tags~ allows for HTML meta tags customization
Setting ~org-refile-use-outline-path~ to ~'title~ will show title
instead of the file name in refile targets.  If the document do not have
a title, the filename will be used, similar to ~'file~ option.

New variable ~org-html-meta-tags~ makes it possible to customize the
=<meta>= tags used in an HTML export.  Accepts either a static list of
values, or a function that generates such a list (see
~org-html-meta-tags-default~ as an example of the latter).
*** A new option for custom setting ~org-agenda-show-outline-path~ to show document title

*** Option ~org-agenda-bulk-custom-functions~ now supports collecting bulk arguments
Setting ~org-agenda-show-outline-path~ to ~'title~ will show title
instead of the file name at the beginning of the outline.  The title of
the document can be set by special keyword =#+title:=.

When specifying a custom agenda bulk option, you can now also specify
a function which collects the arguments to be used with each call to
the custom function.
*** New custom settings =org-icalendar-scheduled-summary-prefix= and =org-icalendar-deadline-summary-prefix=

*** New faces to improve the contextuality of Org agenda views
These settings allow users to define prefixes for exported summary
lines in ICS exports.  The customization can be used to disable
the prefixes completely or make them a little bit more verbose
(e.g. "Deadline: " instead of the default "DL: ").

Four new faces improve certain styles and offer more flexibility for
some Org agenda views: ~org-agenda-date-weekend-today~,
~org-imminent-deadline~, ~org-agenda-structure-secondary~,
~org-agenda-structure-filter~.  They inherit from existing faces in
order to remain backward-compatible.
The same settings can also be applied via corresponding exporter

Quoting from [[https://list.orgmode.org/87lf7q7gpq.fsf@protesilaos.com/][this thread]]:
*** A new custom setting =org-hide-drawer-startup= to control initial folding state of drawers

+ The 'org-imminent-deadline' is useful to disambiguate generic
  warnings from deadlines.  For example, a warning could be rendered
  in a yellow colored text and have a bold weight, whereas a deadline
  might be red and styled with italics.
Previously, all the drawers were always folded when opening an Org
file.  This only had an effect on the drawers outside folded
headlines.  The drawers inside folded headlines were re-folded because
=org-cycle-hide-drawers= was present inside =org-cycle-hook=.

+ The 'org-agenda-structure-filter' applies to all tag/term filters
  in agenda views that search for keywords or patterns.  It is
  designed to inherit from 'org-agenda-structure' in addition to the
  'org-warning' face that was present before (and removes the
  generic 'warning' face from one place).  This offers the benefit
  of consistency, as, say, an increase in font height or a change in
  font family in 'org-agenda-structure' will propagate to the filter
  as well.  The whole header line thus looks part of a singular
With the new folding backend, running =org-cycle-hide-drawers= is no
longer needed if all the drawers are truly folded on startup: [[*Folding
state of the drawers is now preserved when cycling headline
visibility]].  However, this has an unwanted effect when a user does
not want the drawers to be folded (see [[https://orgmode.org/list/m2r14f407q.fsf@ntnu.no][this bug report]]).

+ The 'org-agenda-structure-secondary' complements the above for those
  same views where a description follows the header.  For instance, the
  tags view provides information to "Press N r" to filter by a
  numbered tag.  Themes/users may prefer to disambiguate this line
  from the header above it, such as by using a less intense color or by
  reducing its height relative to the 'org-agenda-structure'.
The new custom setting gives more control over initial folding state
of the drawers.  When set to =nil= (default is =t=), the drawers are
not folded on startup.

+ The 'org-agenda-date-weekend-today' provides the option to
  differentiate the current date on a weekend from the current date on
The folding state can also be controlled on per-file basis using
=STARTUP= keyword:

*** New option ~org-clock-ask-before-exiting~
: #+startup: hidedrawers
: #+startup: nohidedrawers

By default, a function is now added to ~kill-emacs-query-functions~
that asks whether to clock out and save when there's a running clock.
Customize ~org-clock-ask-before-exiting~~ to nil to disable this new
*** New custom setting ~org-icalendar-force-alarm~

*** Option ~org-html-inline-image-rules~ now includes .webp
The new setting, when set to non-nil, makes Org create alarm at the
event time when the alarm time is set to 0.  The default value is
nil -- do not create alarms at the event time.

By default ox-html now inlines webp images.
** New functions and changes in function arguments
*** New function ~org-get-title~ to get =#+TITLE:= property from buffers

*** ~org-html-head-include-scripts~ is now =nil= by default
A function to collect the document title from the org-mode buffer.

See [[msg:498dbe2e-0cd2-c81e-7960-4a26c566a1f7@memebeam.org][this thread]].
*** ~org-fold-show-entry~ does not fold drawers by default anymore

*** New option ~org-html-content-class~
~org-fold-show-entry~ now accepts an optional argument HIDE-DRAWERS.
When the argument is non-nil, the function folds all the drawers
inside entry.  This was the default previously.

This is the CSS class name to use for the top level content wrapper.
Now, ~org-fold-show-entry~ does not fold drawers by default.

*** New option ~org-babel-plantuml-svg-text-to-path~
*** New command ~org-edit-comment-block~ to edit comment block at point

** New features
*** =ob-python= improvements to =:return= header argument
As the contents of comments blocks is not parsed as Org markup, the
headlines and keywords inside should be escaped, similar to src
blocks, example blocks, and export blocks.  This in inconvenient to do
manually and ~org-edit-special~ is usually advised to edit text in
such kind of blocks.

This option, nil by default, allows to add a SVG-specific post-export
step that runs inkscape text-to-path replacement over the output file.
Now, comment block editing is also supported via this new function.

*** You can now configure ~org-html-scripts~ and ~org-html-style-default~
*** New function ~org-element-cache-map~ for quick mapping across Org elements

~org-html-scripts~ and ~org-html-style-default~ used to be constants,
you can now configure them.
When element cache is enabled, the new function provides the best
possible performance to map across large Org buffers.

*** New option ~org-attach-git-dir~
It is recommended to provide =:next-re= and =:fail-re= parameters for
best speed.

~org-attach-git-dir~ will decide whether to use ~org-attach-git-dir~
(the default) or use the attachment directory of the current node, if
it is correctly configured as a Git repository.
Diagnostic information about execution speed can be provided according
to ~org-element--cache-map-statistics~ and

*** New option ~org-attach-sync-delete-empty-dir~
~org-scan-tags~ and tag views in agenda utilise the new function.
*** New function ~org-element-at-point-no-context~

~org-attach-sync-delete-empty-dir~ controls the deletion of an empty
attachment directory at calls of ~org-attach-sync~.  There is
Never delete, Always delete and Query the user (default).
This function is like ~org-element-at-point~, but it does not try to
update the cache and does not guarantee correct =:parent= properties
for =headline= elements.

*** ~org-babel-default-header-args~ can now be specified as closures or strings
This function is faster than ~org-element-at-point~ when used together
with frequent buffer edits.
*** Various Org API functions now use cache and accept Org elements as optional arguments

~org-babel-default-header-args~ now also accepts closures that
evaluate to a string. Previously, only direct strings were
supported. These closures are evaluated when point is at the source
block, which allows them to make use of contextual information at the
relevant source block. One example that illustrates the usefulness of
this addition (also given in the documentation for
~org-babel-default-header-args~) is:
~org-in-archived-heading-p~, ~org-in-commented-heading-p~,
~org-up-heading-safe~, ~org-end-of-subtree~, ~org-goto-first-child~,
~org-back-to-heading~, ~org-entry-get-with-inheritance~, and
~org-narrow-to-subtree~ all accept Org element as an extra optional

#+begin_src elisp
(defun org-src-sha ()
  (let ((elem (org-element-at-point)))
    (concat (sha1 (org-element-property :value elem)) \".svg\")))
~org-get-tags~ now accepts Org element or buffer position as first

(setq org-babel-default-header-args:latex
      `((:results . \"file link replace\")
        (:file . (lambda () (org-src-sha)))))
*** New function ~org-texinfo-kbd-macro~

This function is intended for us in the definition of a ~kbd~ macro in
files that are exported to Texinfo.

*** =org-at-heading-p= now recognises optional argument. Its meaning is inverted.

=org-at-heading-p= now returns t by default on headings inside folds.
Passing optional argument will produce the old behaviour.

*** =org-babel-execute:plantuml= can output ASCII graphs in the buffer

Previously, executing PlantUML src blocks always exported to a file.  Now, if
:results is set to a value which does not include "file", no file will be
exported and an ASCII graph will be inserted below the src block.

** Removed or renamed functions and variables
*** =org-plantump-executable-args= is renamed and applies to jar as well

The new variable name is =org-plantuml-args=.  It now applies to both
jar PlantUML file and executable.
*** Default values and interpretations of ~org-time-stamp-formats~ and ~org-time-stamp-custom-formats~ are changed

Leading =<= and trailing =>= in the default values of
~org-time-stamp-formats~ and ~org-time-stamp-custom-formats~ are

This will set the ~:file~ header argument to the sha1 checksum of the
contents of the current latex source block.
The Org functions that are using these variables also ignore leading
and trailing brackets (=<...>= and =[...]=, if present).

Finally, the closures are only evaluated if they're not overridden for
a source block. This improves efficiency in cases where the result of
a compute-expensive closure would otherwise be discarded.
This change makes the Org code more consistent and also makes the
docstring for ~org-time-stamp-custom-formats~ accurate.

No changes on the user side are needed if
~org-time-stamp-custom-formats~ was customized.
*** ~org-timestamp-format~ is renamed to ~org-format-timestamp~

The old function name is similar to other ~org-time-stamp-format~
function.  The new name emphasizes that ~org-format-timestamp~ works
on =timestamp= objects.

*** Updated argument list in ~org-time-stamp-format~

New =custom= argument in ~org-time-stamp-format~ makes the function
use ~org-time-stamp-custom-formats~ instead of
~org-time-stamp-formats~ to determine the format.

Optional argument =long= is renamed to =with-time=, emphasizing that it refers to time stamp format with time specification.

Optional argument =inactive= can now have a value =no-brackets= to
return format string with brackets stripped.

** Miscellaneous
*** =org-bibtex= includes =doi= and =url= entries when exporting to BiBTeX
=doi= and =url= entries have been made optional for some publication
types and will be exported if present for those types.
*** Missing or empty placeholders in "eval" macros are now =nil=
They used to be the empty string.
*** =org-goto-first-child= now works before first heading
*** SQL Babel ~:dbconnection~ parameter can be mixed with other SQL Babel parameters

When point is before first heading =org-goto-first-child= will move
point to the first child heading, or return nil if no heading exist
in buffer.  This is in line with the fact that everything before first
heading is regarded as outline level 0, i.e. the parent level of all
headings in the buffer.
Before you could either specify SQL parameters like ~:dbhost~,
~:dbuser~, ~:database~, etc or a ~:dbconnection~ parameter which looks
up all other parameters from the ~sql-connection-alist~ variable.  Now
it's possible to specify a ~:dbconnection~ and additionally other
parameters that will add or overwrite the parameters coming from

Previously =org-goto-first-child= would do nothing before first
heading, except return nil.
E.g. if you have a connection in your ~sql-connection-alist~ to a
server that has many databases, you don't need an entry for every
database but instead can just specify ~:database~ next to your
~:dbconnection~ parameter.

*** Faces of all the heading text elements now conform to the headline face
*** Post-processing code blocks can return an empty list

In the past, faces of todo keywords, emphasised text, tags, and
priority cookies inherited =default= face.  The resulting headline
fontification was not always consistent, as discussed in [[msg::87h7sawubl.fsf@protesilaos.com][this bug
report]].  Now, the relevant faces adapt to face used to fontify the
current headline level.
When the result of a regular code block is nil, then that was already
treated as an empty list.  Now that is also the case for code blocks
that post-process the result of another block.

Users who prefer to keep the old behaviour should change their face
customisation explicitly stating that =default= face is inherited.
*** Styles are customizable in ~biblatex~ citation processor

Example of old face customisation:
It is now possible to add new styles or modify old ones in ~biblatex~
citation processor.  See ~org-cite-biblatex-styles~ for more

#+begin_src emacs-lisp
(setq org-todo-keyword-faces '(("TODO"
                                :background "chocolate"
                                :height 0.75)))
*** Citation processors can declare styles dynamically

To preserve the old behaviour the above customisation should be
changed to
When a citation processor is registered, it is now possible to set
~:cite-styles~ key to a function, which will be called whenever the
list of styles is required.

#+begin_src emacs-lisp
(setq org-todo-keyword-faces '(("TODO"
                                :inherit default
                                :background "chocolate"
                                :height 0.75)))
*** Org also searches for CSL style files in default directory

*** Storing ID-links before first heading uses title as description
When CSL style file name is relative, Org first looks into
default-directory before trying ~org-cite-csl-styles-dir~.

Storing links to files using ~org-store-link~ (=<C-c l>=) when
~org-id-link-to-org-use-id~ is not nil will now store the title as
description of the link, if available.  If no title exists it falls
back to the filename as before.
*** Users can add checkers to the linting process

*** Change in =org-tags-expand= signature
The function ~org-lint-add-checker~ allows one to add personal checks
when calling ~org-lint~.   See its docstring for more information.

The function does not allow for a third optional parameter anymore.
*** LaTeX environment =#+results= are now removed
*** New =transparent-image-converter= property for =dvipng=

If a babel src block produces a raw LaTeX environment, it will now be
recognised as a result, and so replaced when re-evaluated.
The =dvipng= option in ~org-preview-latex-process-alist~ has a new
property =transparent-image-converter= which is used instead of
=image-converter= when producing transparent images.

*** Tag completion now uses =completing-read-multiple=
*** =:tangle-mode= now accepts more permissions formats

Tag completion now uses =completing-read-multiple= with a simple
completion table, which should allow better interoperability with
custom completion functions.
Previously =:tangle-mode (identity #o755)= was the only reasonable way
to set the file mode. ~org-babel-interpret-file-mode~ has been
introduced which will accept three new formats:
+ Short octals, e.g. =:tangle-mode o755=
+ ls-style, e.g. =:tangle-mode rwxrw-rw-=
+ chmod-style, e.g. =:tangle-mode u+x=

*** Providing =directory-empty-p= from Emacs 28 as =org-directory-empty-p=
Chmod-style permissions are based on the new variable

*** =org-get-last-sibling= marked as obsolete
*** A new custom setting =org-agenda-clock-report-header= to add a header to org agenda clock report

Use =org-get-previous-sibling= instead.  This is just a rename to have
a more consistent naming.  E.g. recall the pair of funtctions
=next-line= / =previous-line=.
*** ~org-latex-listings~ has been replaced with ~org-latex-src-block-backend~

*** Make org-protocol compatible with =URLSearchParams= JavaScript class
~org-latex-listings~ has been renamed to better reflect the current
purpose of the variable.  The replacement variable
~org-latex-src-block-backend~ acts in exactly the same way, however it
accepts =listings= and =verbatim= in place of =t= and =nil= (which
still work, but are no longer listed as valid options).

Decoder of query part of org-protocol URI recognizes "+" as an encoded
space characters now, so it is possible to avoid call to =encodeURIComponent=
for each parameter and use more readable expression in bookmarklet:
*** ~org-link-parameters~ has a new ~:insert-description~ parameter

'org-protocol://store-link?' + new URLSearchParams({
      url: location.href, title: document.title})
The value of ~:insert-description~ is used as the initial input when
prompting for a link description.  It can be a string (used as-is) or
a function (called with the same arguments as
~org-make-link-description-function~ to return a string to use).

An example of a such function for =info:= links is
~org-info-description-as-command~.  To access a manual section outside
of Org, description may be pasted to shell prompt or evaluated withing
Emacs using =M-:= (wrapped into parenthesis).  For example,
description of the =info:org#Tags= link is =info "(org) Tags"=.  To
restore earlier behavior add to your Emacs init file the following:
#+begin_src elisp :results silent :eval never-export
  (with-eval-after-load 'ol-info
    (org-link-set-parameters "info" :insert-description nil))

*** Remove obsolete LaTeX packages from ~org-latex-default-packages-alist~
*** New list of languages for LaTeX export: ~org-latex-language-alist~

~org-latex-language-alist~ unifies into a single list the old language
lists for the =babel= and =polyglossia= LaTeX packages:
~org-latex-babel-language-alist~ and
~org-latex-polyglossia-language-alist~, respectively, which are
declared obsolete.

This new list captures the current state of art regarding language
support in LaTeX.  The new =babel= syntax for loading languages via
=ini= files and the new command =\babelprovide= (see:
are also supported.
*** Texinfo exports include LaTeX

With the new customization option ~org-texinfo-with-latex~ set to (its
default value) ~'detect~, if the system runs Texinfo 6.8 (3 July 2021)
or newer, Org will export all LaTeX fragments and environments using
Texinfo ~@math~ and ~@displaymath~ commands respectively.
*** More flexible ~org-attach-id-to-path-function-list~

List entries may return nil if they are unable to handle the passed
ID.  So, responsibility is passed to the next item in the list.
Default entries ~org-attach-id-uuid-folder-format~ and
~org-attach-id-ts-folder-format~ now return nil for too short IDs.
Earlier an obscure error has been thrown.

After the change, error text suggests adjusting
~org-attach-id-to-path-function-list~ value.  The
~org-attach-dir-from-id~ function is adapted to ignore nil values and
to take first non-nil value instead of the value returned by first
~org-attach-id-to-path-function-list~ item.

New policy allows mixing different ID styles while keeping subfolder
layout suited best for each one.  For example, one can use the
following snippet to allow multiple different ID formats in Org files.

#+begin_src emacs-lisp
(setq org-attach-id-to-path-function-list
      '(;; When ID looks like an UUIDs or Org internal ID, use
        ;; `org-attach-id-uuid-folder-format'.
        (lambda (id)
          (and (or (org-uuidgen-p id)
	           (string-match-p "[0-9a-z]\\{12\\}" id))
	       (org-attach-id-uuid-folder-format id)))
        ;; When ID looks like a timestap-based ID. Group by year-month
        ;; folders.
        (lambda (id)
          (and (string-match-p "[0-9]\\{8\\}T[0-9]\\{6\\}\.[0-9]\\{6\\}" id)
               (org-attach-id-ts-folder-format id)))
        ;; Any other ID goes into "important" folder.
        (lambda (id) (format "important/%s/%s" (substring id 0 1) id))
        ;; Fallback to detect existing attachments for old defaults.
        ;; All the above functions, even when return non-nil, would
        ;; point to non-existing folders.

The LaTeX packages =grffile= and =textcomp= are redundant, with their
capabilities being merged into =graphicx= and the LaTeX core
respectively a while ago.
* Older changes

For older Changes, see [[https://orgmode.org/worg/org-release-notes.html][the full release notes]].