@@ 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-element-cache-persistent~.
-*** ~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
-=headline-data=.
+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)
+#+end_src
+
+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
+config:
+
+#+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)
+#+end_src
+
+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
+:DRAWER:
+like this
+:END:
+#+end_src
-*** 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
+DRAWER:
+like this
+:END:
+#+end_src
+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)
#+end_src
-** 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
+https://docs.mathjax.org/en/latest/upgrading/whats-new-3.0.html
+https://docs.mathjax.org/en/latest/upgrading/whats-new-3.1.html
+https://docs.mathjax.org/en/latest/upgrading/whats-new-3.2.html
-~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.
+https://docs.mathjax.org/en/latest/input/tex/extensions.html
-*** 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
+https://www.jsdelivr.com/terms.
+
+** 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
+=[[file:foo.org.gpg::Heading]]=.
-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
-Example:
+~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
+point]].
-*** 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
+:PROPERTIES:
+:EXPORT_FILE_NAME: some/path
+:EXPORT_FILE_NAME+: to/file
+:END:
+#+end_src
-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") . "/")))
+#+end_src
-*** LaTeX attribute ~:float~ now passes through arbitrary values
+The example above would then produce the property value
+=some/path/to/file=.
-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
+~org-persist-register~).
-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
-=:options=.
+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
+commands.
+*** 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.
-#+BEGIN_SRC org
-,#+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
- fig=plt.figure(figsize=(4,2))
- x=numpy.linspace(-15,15)
- plt.plot(numpy.sin(x)/x)
- fig.tight_layout()
-,#+end_src
+*** New LaTeX source block backend using =engraved-faces-latex=
-,#+RESULTS:
-[[file:/home/jack/tmp/plot.svg]]
-#+END_SRC
+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
+instance,
#+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]
- })
-,#+end_src
-
-,#+RESULTS:
-| | a | b |
-|---+---+---|
-| 0 | 1 | 4 |
-| 1 | 2 | 5 |
-| 2 | 3 | 6 |
+[cite/n:@*]
#+end_src
-*** 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
+example,
-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
+#+end_src
-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
+#+end_src
-*** New formatting directive ~%L~ for org-capture
+If a file does not have a title, the table will show the file name
+instead.
+*** 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
-descriptions.
+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
-=file-desc=.
+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
+~org-cycle-inline-images-display~.
-*** 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)
#+end_src
-*** 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
+options:
+=:icalendar-scheduled-summary-prefix=,
+=:icalendar-deadline-summary-prefix=
-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
-#+begin_quote
-+ 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
- design.
+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
- weekdays.
-#+end_quote
+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
-behavior.
+*** 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
+~org-element--cache-map-statistics-threshold~.
-*** 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
+argument.
-#+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
+argument.
-(setq org-babel-default-header-args:latex
- `((:results . \"file link replace\")
- (:file . (lambda () (org-src-sha)))))
-#+end_src
+*** 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
+stripped.
-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
+~sql-connection-alist~.
-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
+information.
-#+begin_src emacs-lisp
-(setq org-todo-keyword-faces '(("TODO"
- :background "chocolate"
- :height 0.75)))
-#+end_src
+*** 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)))
-#+end_src
+*** 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-babel-tangle-default-file-mode~.
-*** =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
-#+begin_example
-'org-protocol://store-link?' + new URLSearchParams({
- url: location.href, title: document.title})
-#+end_example
+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))
+#+end_src
-*** 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:
+https://mirrors.ctan.org/macros/latex/required/babel/base/babel.pdf)
+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.
+ org-attach-id-uuid-folder-format
+ org-attach-id-ts-folder-format))
+#+end_src
-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]].