Org mode for Emacs – Release notes

Version 9.1
Older changes

Org mode is for keeping notes, maintaining TODO lists, planning projects, and authoring documents with a fast and effective plain-text system.

Version 9.1

Incompatible changes

Variables relative to clocksum duration are obsolete

org-time-clocksum-format, org-time-clocksum-use-fractional and org-time-clocksum-fractional-format are obsolete. If you changed them, consider modifying org-duration-format instead.

Variable org-time-clocksum-use-effort-durations is also obsolete. Consider setting org-duration-units instead.

`org-at-timestamp-p` optional argument accepts different values

See docstrings for the allowed values. For backward compatibility, (org-at-timestamp-p t) is still supported, but should be updated accordingly.

`org-capture-templates` no longer accepts S-expressions as file names

Since functions are allowed there, a straightforward way to migrate is to turn, e.g.,

(file (sexp))

into

(file (lambda () (sexp)))

Deleted contributed packages

org-ebib.el, =org-bullets.el and org-mime.el have been deleted from the contrib/ directory.

You can now find them here :

Change `org-texinfo-classes` value

The value cannot support functions to create sectionning commands anymore. Also, the sectionning commands should include commands for appendices. See the docstring for more information.

Removal of `:sitemap-sans-extension`

The publishing property is no longer recognized, as a consequence of changes to site-map generation.

You can get the same functionality by setting :sitemap-format-entry to the following

(lambda (entry style project)
  (cond ((not (directory-name-p entry))
         (format "[[file:%s][%s]]"
                 (file-name-sans-extension entry)
                 (org-publish-find-title entry project)))
        ((eq style 'tree) (file-name-nondirectory (directory-file-name entry)))
        (t entry)))

Change signature for `:sitemap-function`

:sitemap-function now expects to be called with two arguments. See org-publish-project-alist for details.

Change signature for some properties in `org-list-to-generic`

:istart, :icount, :iend and :isep now expect the type of the list as their first argument.

Change signature for `org-get-repeater`

The optional argument is now a string to extract the repeater from. See docstring for details.

Change signature for `org-time-string-to-time`

See docstring for changes.

Change order of items in `org-agenda-time-grid`

org-agenda-time-grid gained an extra item to allow users to customize the string displayed after times in the agenda. See docstring for details.

`tags-todo` custom searches now include DONE keywords

Use "/!" markup when filtering TODO keywords to get only not-done TODO keywords.

Removal of `ob-scala.el`

See this github issue.

You can use ob-scala.el as packaged in scala-mode, available from the MELPA repository.

New features

iCalendar export uses inheritance for TIMEZONE and LOCATION properties

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

iCalendar export respects a TIMEZONE property

Set the TIMEZONE property on an entry to specify a time zone for that entry only during iCalendar export. The property value should be specified as in "Europe/London".

`org-attach` can move directory contents

When setting a new directory for an entry, org-attach offers to move files over from the old directory. Using a prefix arg will reset the directory to old, ID based one.

New Org duration library

This new library implements tools to read and print time durations in various formats (e.g., "H:MM", or "1d 2h 3min"…).

See org-duration-to-minutes and org-duration-from-minutes docstrings.

Agenda

New variable : org-agenda-show-future-repeats
New variable : org-agenda-prefer-last-repeat
New variable : org-deadline-past-days

See docstring for details.
Binding C-c C-x < for org-agenda-set-restriction-lock-from-agenda
New auto-align default setting for org-agenda-tags-column

org-agenda-tags-column can now be set to auto, which will automatically align tags to the right edge of the window. This is now the default setting.

New value for `org-publish-sitemap-sort-folders`

The new ignore value effectively allows toggling inclusion of directories in published site-maps.

Babel

Scheme: support for tables
Scheme: new variable: org-babel-scheme-null-to

This new custom option allows to use a empty list or null symbol to format the table output, initially assigned to hlines.
Scheme: new header :prologue

A new block code header has been created for Org Babel that enables developers to prepend code to the scheme block being processed.

Multiple :prologue headers can be added each of them using a string with the content to be added.

The scheme blocks are prepared by surronding the code in the block with a let form. The content of the :prologue headers are prepended before this let form.
Support for hledger accounting reports added
Clojure: new setting org-babel-clojure-sync-nrepl-timeout

Creation of a new setting to specify the Cider timeout. By setting the org-babel-clojure-sync-nrepl-timeout setting option. The value is in seconds and if set to nil then no timeout will occur.
Clojure: new header :show-process
A new block code header has been created for Org Babel that enables developers to output the process of an ongoing process into a new window/buffer.

You can tell Org Babel to output the process of a running code block.

To show that output you only have to specify the :show-process option in the code block's header like this:
```
#+BEGIN_SRC clojure :results output :show-process t
  (dotimes [n 10]
    (println n ".")
    (Thread/sleep 500))
#+END_SRC
```
If :show-process is specified that way, then when you will run the code using C-c C-c a new window will open in Emacs. Everything that is output by the REPL will immediately be added to that new window.

When the processing of the code is finished, then the window and its buffer will be closed and the results will be reported in the #+RESULTS section.

Note that the :results parameter's behavior is not changed. If silent is specified, then no result will be displayed. If output is specified then all the output from the window will appears in the results section. If value is specified, then only the last returned value of the code will be displayed in the results section.
Maxima: new headers :prologue and :epilogue

Babel options :prologue and :epilogue have been implemented for Maxima src blocks which prepend and append, respectively, the given code strings. This can be useful for specifying formatting settings which would add clutter to exported code. For instance, you can use this :prologue "fpprintprec: 2; linel: 50;" for presenting Maxima results in a beamer presentation.
PlantUML: add support for header arguments

Plantuml source blocks now support the :prologue, :epilogue and :var header arguments.
SQL: new engine added sqsh
A new engine was added to support sqsh command line utility for use against Microsoft SQL Server or Sybase SQL server.

More information on sqsh can be found here: sourceforge/sqsh

To use sqsh in an sql SRC_BLK set the :engine like this:
```
#+BEGIN_SRC sql :engine sqsh :dbhost my_host :dbuser master :dbpassword pass :database support
Select * From Users
Where clue > 0
#+END_SRC
```
SQL: new engine added vertica
A new engine was added to support vsql command line utility for use against HP Vertica.

More information on vsql can be found here: my.vertica.com

To use vertica in an sql SRC_BLK set the :engine like this:
```
#+BEGIN_SRC sql :engine vertica :dbhost my_host :dbuser dbadmin :dbpassword pw :database vmart
SELECT * FROM nodes;
#+END_SRC
```
C++: New header :namespaces
The new :namespaces export option can be used to specify namespaces to be used within a C++ org source block. Its usage is similar to :includes, in that it can accept multiple, space-separated namespaces to use. This header is equivalent to adding using namespace <name>; in the source block. Here is a "Hello World" in C++ using :namespaces:
```
#+BEGIN_SRC C++ :results output :namespaces std :includes <iostream>
  cout << "Hello World" << endl;
#+END_SRC
```
Support for Vala language
Vala language blocks support two special header arguments:
- :flags passes arguments to the compiler
- :cmdline passes commandline arguments to the generated executable
Support for :var does not exist yet, also there is no :session support because Vala is a compiled language.

The Vala compiler binary can be changed via the defcustom org-babel-vala-compiler.

New `function` scope argument for the Clock Table

Added a nullary function that returns a list of files as a possible argument for the scope of the clock table.

Export

Implement vernacular table of contents in Markdown exporter

Global table of contents are generated using vanilla Markdown syntax instead of HTML. Also #+TOC keyword, including local table of contents, are now supported.
Add Slovanian translations
Implement org-export-insert-image-links

This new function is meant to be used in back-ends supporting images as descriptions of links, a.k.a. image links. See its docstring for details.
New macro : {{{n}}}

This macro creates and increment multiple counters in a document. See manual for details.
Add global macros through org-export-global-macros

With this variable, one can define macros available for all documents.
New keyword #+EXPORT_FILE_NAME

Similarly to :EXPORT_FILE_NAME: property, this keyword allows the user to specify the name of the output file upon exporting the document. This also has an effect on publishing.
Horizontal rules are no longer ignored in LaTeX table math mode
Use compilation-mode for compilation output
Plain lists accept a new :separator attribute in Texinfo

The new :separator attribute splits a tag from a description list item into multiple parts. This allows to have two-column tables with multiple entries in the first column. See manual for more details.
latex-environment elements support caption keywords for LaTeX export

`org-edit-special` can edit LaTeX environments

Using C-c ' on a LaTeX environment opens a sub-editing buffer. By default, major mode in that buffer is latex-mode, but it can be changed by configuring org-src-lang-modes.

`org-list-to-generic` includes a new property: `:ifmt`

:ifmt is a function to be called on the body of each item. See org-list-to-generic documentation for details.

New variable : `org-bibtex-headline-format-function`

This allow to use a different title than entry title.

`org-attach` supports attaching files from URLs

Using C-c C-a u prompts for a URL pointing to a file to be attached to the document.

New option for `org-refile-use-outline-path`

org-refile-use-outline-path now supports the setting buffer-name, which causes refile targets to be prefixed with the buffer’s name. This is particularly useful when used in conjunction with uniquify.el.

`org-file-contents` now allows the FILE argument to be a URL.

This allows #+SETUPFILE: to accept a URL instead of a local file path. The URL contents are auto-downloaded and saved to a temporary cache org--file-cache. A new optional argument NOCACHE is added to org-file-contents.

`org-mode-restart` now resets the newly added `org--file-cache`.

Using C-c C-c on any keyword (like #+SETUPFILE) will reset the that file cache.

New option : `org-table-duration-hour-zero-padding`

This variable allow computed durations in tables to be zero-padded.

New mode switch for table formulas : `U`

This mode omits seconds in durations.

Removed functions

Org Timeline

This feature has been removed. Use a custom agenda view, possibly narrowed to current buffer to achieve a similar functionality.

`org-agenda-skip-entry-when-regexp-matches` is obsolete

Use org-agenda-skip-if instead.

`org-agenda-skip-subtree-when-regexp-matches` is obsolete

Use org-agenda-skip-if instead.

`org-agenda-skip-entry-when-regexp-matches-in-subtree` is obsolete

Use org-agenda-skip-if instead.

`org-minutes-to-clocksum-string` is obsolete

Use org-duration-from-minutes instead.

`org-hh:mm-string-to-minutes` is obsolete

Use org-duration-to-minutes instead.

`org-duration-string-to-minutes` is obsolete

Use org-duration-to-minutes instead.

`org-gnus-nnimap-cached-article-number` is removed.

This function relied on nnimap-group-overview-filename, which was removed from Gnus circa September 2010.

Removed options

`org-agenda-repeating-timestamp-show-all` is removed.

For an equivalent to a nil value, set org-agenda-show-future-repeats to nil and org-agenda-prefer-last-repeat to t.

`org-gnus-nnimap-query-article-no-from-file` is removed.

This variable has no effect, as it was relying on a function that was removed from Gnus circa September 2010.

`org-usenet-links-prefer-google` is obsolete.

Use org-gnus-prefer-web-links instead.

`org-publish-sitemap-file-entry-format` is deprecated

One can provide new :sitemap-format-entry property for a function equivalent to the removed format string.

`org-enable-table-editor` is removed.

Setting it to a nil value broke some other features (e.g., speed keys).

`org-export-use-babel` cannot be set to `inline-only`

The variable is now a boolean.

`org-texinfo-def-table-markup` is obsolete

Use org-texinfo-table-default-markup instead.

New functions

`org-publish-find-property`

This function can be used as a tool to format entries in a site-map, in addition to org-publish-find-title and org-publish-find-date.

`org-list-to-org`

It is the reciprocal of org-list-to-lisp, which see.

`org-agenda-set-restriction-lock-from-agenda`

Call org-agenda-set-restriction-lock from the agenda.

Miscellaneous

The Library of Babel now on Worg

The library-of-babel.org used to be accessible from the doc/ directory, distributed with Org’s core. It is now accessible from the Worg community-driven documentation here.

If you want to contribute to it, please see how to contribute.

Allow multiple columns view

Columns view is not limited to a single buffer anymore.

Org Attach obeys `dired-dwim-target`

When a Dired buffer is opened next to the Org document being edited, the prompt for file to attach can start in the Dired buffer's directory if `dired-dwim-target' in non-nil.

`org-fill-paragraph` can now fill a whole region

More specific anniversary descriptions

Anniversary descriptions (used in the agenda view, for instance) include the point in time, when the anniversary appears. This is, in its most general form, just the date of the anniversary. Or more specific terms, like "today", "tomorrow" or "in n days" are used to describe the time span.

This feature allows to automatically change the description of an anniversary, depending on if it occurs in the next few days or far away in the future.

Computed dates in tables appear as inactive time stamps

Save point before opening a file with an unknown search option

When following a file link with a search option (e.g., ::#custom-id) that doesn't exist in the target file, save positon before raising an error. As a consequence, it is possible to jump back to the original document with org-mark-ring-goto (default binding C-c &).

`org-get-heading` accepts two more optional arguments

See docstring for details.

New option `org-babel-uppercase-example-markers`

This variable is a defcustom and replaces the variable org-babel-capitalize-example-region-markers, which is a defvar and is now obselete.

`INCLUDE` keywords in commented trees are now ignored.

Default value for `org-texinfo-text-markup-alist` changed.

Now =...= markup uses @samp{} instead of @verb{}. You can use @verb{} again by customizing the variable.

Texinfo exports example blocks as `@example`

Texinfo exports inline src blocks as `@code{}`

Texinfo default table markup is `@asis`

It used to be @samp but @asis is neutral and, therefore, more suitable as a default value.

Texinfo default process includes `--no-split` option

New entities : `\dollar` and `\USD`

`org-parse-time-string` accepts a new optional argument

ZONE specifies the current time zone.

`org-time-string-to-seconds` now accepts an optional `ZONE` argument

Support for date style URLs in `org-protocol://open-source`

URLs like https://cool-blog.com/2017/05/20/cool-post/ are covered by rewrite rules.