Release notes | Org mode

Version 9.3

Incompatible changes

Change bracket link escaping syntax

Org used to percent-encode sensitive characters in the URI part of the bracket links.

Now, escaping mechanism uses the usual backslash character, according to the following rules, applied in order:

  1. All consecutive \ characters at the end of the link must be escaped;
  2. Any ] character at the very end of the link must be escaped;
  3. All consecutive \ characters preceding ][ or ]] patterns must be escaped;
  4. Any ] character followed by either [ or ] must be escaped;
  5. Others ] and \ characters need not be escaped.

When in doubt, use the function org-link-escape in order to turn a link string into its properly escaped form.

The following function will help switching your links to the new syntax:

(defun org-update-link-syntax (&optional no-query)
  "Update syntax for links in current buffer.
Query before replacing a link, unless optional argument NO-QUERY
is non-nil."
  (interactive "P")
  (org-with-point-at 1
    (let ((case-fold-search t))
      (while (re-search-forward "\\[\\[[^]]*?%\\(?:2[05]\\|5[BD]\\)" nil t)
        (let ((object (save-match-data (org-element-context))))
          (when (and (eq 'link (org-element-type object))
                     (= (match-beginning 0)
                        (org-element-property :begin object)))
            (goto-char (org-element-property :end object))
            (let* ((uri-start (+ 2 (match-beginning 0)))
                   (uri-end (save-excursion
                              (goto-char uri-start)
                              (re-search-forward "\\][][]" nil t)
                              (match-beginning 0)))
                   (uri (buffer-substring-no-properties uri-start uri-end)))
              (when (or no-query
                        (y-or-n-p
                         (format "Possibly obsolete URI syntax: %S.  Fix? "
                                 uri)))
                (setf (buffer-substring uri-start uri-end)
                      (org-link-escape (org-link-decode uri)))))))))))

The old org-link-escape and org-link-unescape functions have been renamed into org-link-encode and org-link-decode.

Change match group number in org-link-bracket-re

Link description, if any, is located in match group 2 instead of match group 3.

ob-clojure does not auto prepend (ns ..) statement anymore

When tangling, user usually just wants to tangle literally code instead of prepend inserting a (ns ..) statement before source block code. Now, when you have no :ns header argument specified, this behavior will not happen automatically.

Change in behavior on exit from an Org edit buffer

Org will no longer attempt to restore the window configuration in the frame to which the user returns after editing a source block with org-edit-src-code. Instead, the window configuration will remain as it is.

Change default value for org-email-link-description-format

When linking from a mail buffer, Org used to truncate the subject of the message to 30 characters in order to build the description of the link. This behavior was considered as too surprising. As a consequence, Org no longer truncates subjects.

You can get the old behaviour back with the following:

(setq org-email-link-description-format "Email %c: %.30s")

:file header argument no longer assume "file" :results

The "file" :results value is now mandatory for a code block returning a link to a file. The :file or :file-ext header arguments no longer imply a "file" result is expected.

Plain numbers are hours in Column View mode

All LaTeX preview backends use now xcolor

The dvipng backend was previously relying on fg and bg parameters to be passed to the CLI. This didn't work when xcolor was directly or indirectly used in the document (e.g. tkiz is a user of xcolor). Since every other backend was already using xcolor to set fg and bg, the CLI alternative was removed and there is no more a :use-xcolor options since now it's implicitly always true.

Org-Attach Git commit

Refactoring of Org-Attach affected the Git commit functionality. Not much, but the following changes are required if you still need to auto-commit attachments to git:

  • Customization of org-attach-annex-auto-get needs to be renamed to org-attach-git-annex-auto-get.
  • Customization of org-attach-commit is no longer needed. Instead one need to require the org-attach-git module in the startup.

New features

New option to wrap source code lines in HTML export

When new option html-wrap-src-lines (with variable org-html-wrap-src-lines) is non-nil, HTML export wraps source code lines in HTML code elements.

New option to handle schedules and deadlines in iCalendar export

Export ignore done tasks with a deadline when org-icalendar-use-deadline contains event-if-todo-not-done. Likewise, scheduled done tasks are also ignored when org-icalendar-use-scheduled contains the same symbol.

Add split-window-right option for src block edit window placement

Given the increasing popularity of wide screen monitors, splitting horizontally may make more sense than splitting vertically. An option, split-window-right, to request horizontal splitting has been added to org-src-window-setup.

Org-Attach has been refactored and extended

Org attach has been refactored and the functionality extended. It should now be easier to understand how it works. A few improvements and extra options have been added as well.

From the initial comment in org-attach source-code:

  • Attachments are managed either by using a custom property DIR or by using property ID from org-id. When DIR is defined, a location in the filesystem is directly attached to the outline node. When org-id is used, attachments are stored in a folder named after the ID, in a location defined by org-attach-id-dir. DIR has precedence over ID when both parameters are defined for the current outline node (also when inherited parameters are taken into account).

From now on inheritance requires no extra property and will adhere to org-attach-use-inheritance by default. Inheritance can be customized to always be activated or never be activated in org-attach-use-inheritance.

The ATTACHDIR property is deprecated in favour of the shorter property DIR. Links to folders inside the DIR property can now be declared as relative links. This is not enabled by default, but can be set in org-attach-dir-relative.

When adding new attachment to the outline node the preferred way of doing so can be customized. Take a look at org-attach-preferred-new-method. It defaults to using ID since that was the behaviour before this change.

If both DIR and ID properties are set on the same node, DIR has precedence and will be used.

One can now also choose to build attachment-directory-paths in a customized way. This is an advanced topic, but in some case it makes sense to parse an ID in a different way than the default one. Create your own function and add it to the beginning of org-attach-id-to-path-function~list if you want to customize the ID based folder structure.

If you've used ATTACHDIR properties to manage attachments, use the following code to rename that property to DIR which supports the same functionality. ATTACHDIRINHERIT is no longer supported and is removed.

(defun org-update-attach-properties ()
    "Change properties for Org-Attach."
    (interactive)
    (org-with-point-at 1
      (while (outline-next-heading)
        (let ((DIR (org--property-local-values "ATTACH_DIR" nil)))
          (when DIR
            (org-set-property "DIR" (car DIR))
            (org-delete-property "ATTACH_DIR"))))
      (org-delete-property-globally "ATTACH_DIR_INHERIT")))

For those who hate breaking changes, even though the changes are made to clean things up; fear not. ATTACHDIR will still continue to work. It's just not documented any longer. When you get the chance, run the code above to clean things up anyways!

  • New hooks

    Two hooks are added to org-attach:

    • org-attach-after-change-hook
    • org-attach-open-hook

    They are added mostly for internal restructuring purposes, but can ofc. be used for other things as well.

New link-type: Attachment

Attachment-links are now first-class citizens. They mimic file-links in everything they do but use the existing attachment-folder as a base when expanding the links. Both DIR and ID properties are used to try to resolve the links, in exactly the same way as Org-Attach uses those properties.

Handle overlay specification for notes in Beamer export

This aligns Beamer notes with slide overlays.

Add support for lettered lists in Texinfo

Using :enum A or :enum a Texinfo attribute switches an otherwise numbered list to a lettered list.

Add a dispatcher command to insert dynamic blocks

You can add new dynamic blocks with function org-dynamic-block-define. All such dynamic blocks can be used by org-dynamic-block-insert-dblock command.

Babel

  • ob-emacs-lisp sets lexical-binding in Org edit buffers

    When editing an Elisp src block, the editing buffer's lexical-binding is set according to the src block's :lexical parameter.

  • Add LaTeX output support in PlantUML

New minor mode to display headline numbering

Use <M-x org-num-mode> to get a visual indication of the numbering in the outline. The numbering is also automatically updated upon changes in the buffer.

New property HTML_HEADLINE_CLASS in HTML export

The new property HTML_HEADLINE_CLASS assigns a class attribute to a headline.

Allow LaTeX attributes and captions for "table.el" tables

Supported LaTeX attributes are :float, :center, :font and :caption.

Attach buffer contents to headline

With <b> key from attachment dispatcher (<C-c C-a>), it is now possible to write the contents of a buffer to a file in the headline attachment directory.

iCalendar export respects a CLASS property

Set the CLASS property on an entry to specify a visibility class for that entry only during iCalendar export. The property can be set to anything the calendar server supports. The iCalendar standard defines the values PUBLIC, CONFIDENTIAL, PRIVATE, which can be interpreted as publicly visible, accessible to a specific group, and private respectively.

This property can be inherited during iCalendar export, depending on the value of org-use-property-inheritance.

New parameter for INCLUDE keyword

Add :coding CODING-SYSTEM to include files using a different coding system than the main Org document. For example:

#+INCLUDE: "myfile.cmd" src cmd :coding cp850-dos

New values in clock tables' step: month and year

ODT export handles numbers cookies in lists

New cell movement functions in tables

S-<UP>, S-<DOWN>, S-<RIGHT>, and S-<LEFT> now move cells in the corresponding direction by swapping with the adjacent cell.

New option to natively fontify LaTeX snippets and environments

A 'native option was added to org-highlight-latex-and-related. It matches the same structures than 'latex but it calls org-src-font-lock-fontify-block instead, thus bringing about full LaTeX font locking.

org-clone-subtree-with-time-shift learnt to shift backward in time

<C-c C-x c> (org-clone-subtree-with-time-shift) now takes a negative value as a valid repeater to shift time stamps in backward in cloned subtrees. You can give, for example, ‘-3d’ to shift three days in the past.

Toggle display of all vs. undone scheduled habits conveniently

<C-u K> (org-habit-toggle-display-in-agenda) in an agenda toggles the display of all habits to those which are undone and scheduled. This is a function for convenience.

New parameter for SQL Babel blocks: :dbconnection

The new parameter :dbconnection allows to specify a connection name in a SQL block header: this name is used to look up connection parameters in sql-connection-alist.

New :scale attribute supported by LaTeX exporters

The builtin "latex" exporters now accept and use a :scale attribute, which scales an image by a given factor.

This attribute is wrapped adound the scale parameter of LaTeX's \includegraphics (bitmap images) or a TiKZ's \scalebox. Therefore, its value should be some string palatable to LaTeX as a positive float Its default value is an empty string (i.e. disabled).

This attribute overrides the :width and :height attributes.

#+name: Beastie
#+caption: I think I saw this curious horse already, but where ?
#+LATEX_ATTR: :scale 2
[[https://orgmode.org/resources/img/org-mode-unicorn-logo.png]]

Allow specifying the target for a table of contents

The +TOC keyword now accepts a :target: attribute that specifies the headline to use for making the table of contents.

* Target
  :PROPERTIES:
  :CUSTOM_ID: TargetSection
  :END:
** Heading A
** Heading B
* Another section
#+TOC: headlines 1 :target "#TargetSection"

New functions

org-dynamic-block-insert-dblock

Use default keybinding <C-c C-x x> to run command org-dynamic-block-insert-dblock. It will prompt user to select dynamic block in org-dynamic-block-alist.

org-table-cell-up

org-table-cell-down

org-table-cell-left

org-table-cell-right

org-habit-toggle-display-in-agenda

Removed functions and variables

Removed Org Drill

You can install it back from MELPA.

org-babel-set-current-result-hash

org-capture-insert-template-here

org-attach-directory

It has been deprecated in favour of org-attach-id-dir which is less ambiguous given the restructured org-attach.

org-enable-fixed-width-editor

This variable was not used through the code base.

Miscellaneous

Change signature for org-list-to-subtree

The function now accepts the level of the subtree as an optional argument. It no longer deduces it from the current level.

LaTeX preview is simplified

Function org-latex-preview, formerly known as org-toggle-latex-fragment, has a hopefully simpler and more predictable behavior. See its docstring for details.

org-table-copy-down supports patterns

When org-table-copy-increment is non-nil, it is now possible to increment fields like A1, or 0A, i.e., any string prefixed or suffixed with a whole number.

No more special indentation for description items

Descriptions items are indented like regular ones, i.e., text starts after the bullet. Special indentation used to introduce bugs when inserting sub-items in a description list.

New hook: org-todo-repeat-hook

This hook was actually introduced in Org 9.2.1, but wasn't advertised.

Org Table reads numbers starting with 0 as strings

Disable fast tag selection interface via prefix arg

A call of org-set-tags-command with prefix argument C-u C-u avoids the fast tag selection interface and instead offers the plain interface.

:mkdirp now supports create directory for :dir path

The :mkdirp header argument used to only work for :tangle tangle files. Now :mkdirp works for :dir too. This is more convenient for specify default directory and with :file header argument.

New variable: org-agenda-breadcrumbs-separator

If breadcrumbs are showed in org-agenda with the help of "%b" format in org-agenda-prefix-format, user can customize breadcrumbs's separator using org-agenda-breadcrumbs-separator.

New variable org-attach-commands

This variable makes it possible to customize the list of commands for the attachment dispatcher.

New ID method based on timestamp

If one chooses, it is now possible to create ID's based on timestamp (ISO8601) instead of UUID by changing org-id-method to ts.

For an improved folder structure when using timestamp as ID, make sure to promote org-attach-id-ts-folder-format to the first element of org-attach-id-to-path-function-list in your configuration at the same time.

New customization: org-id-locations-relative

New customization to make the persisting of org-id-locations between sessions to store links to files as relative instead of absolute. The links will be stored as relative to the path of org-id-locations-file.

org-ctrl-c-tab is functional before the first headline

I.e. treat the whole file as if it was a subtree.

Also fold everything below the chosen level. Former behavior was to leave unfolded subtrees unfolded.

org-kill-note-or-show-branches is functional before the first headline

I.e. treat the whole file as if it was a subtree.

Respect narrowing when agenda command is restricted to buffer

Older changes

For older Changes, see old changes.

Created: 2020-10-24 Sat 22:09