#+TITLE: Org critical incompatible changes between >=8.3 and <=9.0.8 * Overview ** Properties drawers syntax changes : Properties drawers are now required to be located right after a : headline and its planning line, when applicable. This change has caused many questions when it happened, it is widely accepted now and I fully support it. ** New syntax for export blocks : Export blocks are explicitly marked as such at the syntax level to : disambiguate their parsing from special blocks. The new syntax is : : #+BEGIN_SRC org : ,#+BEGIN_EXPORT backend : ... : ,#+END_EXPORT : #+END_SRC : : instead of : : #+BEGIN_SRC org : ,#+BEGIN_backend : ... : ,#+END_backend : #+END_SRC This change caused some headaches because it involves semi-manual migration. Below is `org-repair-export-blocks', a function to ease the transition. The rationale behind this change is to make the parser more robust. ** Old Babel header properties are no longer supported : Using header arguments as property names is no longer possible. As : such, the following : : #+BEGIN_EXAMPLE : ,* Headline : :PROPERTIES: : :exports: code : :var: a=1 b=2 : :var+: c=3 : :END: : #+END_EXAMPLE : : should be written instead : : #+BEGIN_EXAMPLE : ,* Headline : :PROPERTIES: : :header-args: :exports code : :header-args: :var a=1 b=2 : :header-args+: :var c=3 : :END: : #+END_EXAMPLE This makes the parser more robust by clearly separating custom property names from Babel header arguments. ** Footnotes : [1]-like constructs are not valid footnotes Here again, Org parser is more robust with a dedicated syntax for footnotes. This change has not cause any trouble, since footnotes are generally added through an Org command. ** Using "COMMENT" is now equivalent to commenting with "#" : If you used "COMMENT" in headlines to prevent a subtree from being : exported, you can still do it but all information within the subtree : is now commented out, i.e. no #+OPTIONS line will be parsed or taken : into account when exporting. : : If you want to exclude a headline from export while using its contents : for setting options, use =:noexport:= (see =org-export-exclude-tags=.) Org used to allow both methods to prevent a subtree from being exported but one method is enough, and this change also makes the behavior of the COMMENT special keyword more consistent. ** =#+CATEGORY= keywords no longer apply partially to document : It was possible to use several such keywords and have them apply to : the text below until the next one, but strongly deprecated since Org : 5.14 (2008). This change brought no problem at all and is a welcome enhancement. * Details ** 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 docustrings 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))) **** 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 #+BEGIN_SRC elisp (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))) #+END_SRC **** 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. ** Version 9.0 *** Incompatible changes **** Emacs 23 support has been dropped From now on, Org expects at least Emacs 24.3, although Emacs 24.4 or above is suggested. **** XEmacs support has been dropped Incomplete compatibility layer with XEmacs has been removed. If you want to take over maintainance of this compatibility, please contact our mailing list. **** New syntax for export blocks Export blocks are explicitly marked as such at the syntax level to disambiguate their parsing from special blocks. The new syntax is #+BEGIN_SRC org ,#+BEGIN_EXPORT backend ... ,#+END_EXPORT #+END_SRC instead of #+BEGIN_SRC org ,#+BEGIN_backend ... ,#+END_backend #+END_SRC As a consequence, =INCLUDE= keywords syntax is modified, e.g., #+BEGIN_SRC org ,#+INCLUDE: "file.org" HTML #+END_SRC becomes #+BEGIN_SRC org ,#+INCLUDE: "file.org" export html #+END_SRC The following function repairs export blocks and =INCLUDE= keywords using previous syntax: #+BEGIN_SRC emacs-lisp (defun org-repair-export-blocks () "Repair export blocks and INCLUDE keywords in current buffer." (interactive) (when (eq major-mode 'org-mode) (let ((case-fold-search t) (back-end-re (regexp-opt '("HTML" "ASCII" "LATEX" "ODT" "MARKDOWN" "MD" "ORG" "MAN" "BEAMER" "TEXINFO" "GROFF" "KOMA-LETTER") t))) (org-with-wide-buffer (goto-char (point-min)) (let ((block-re (concat "^[ \t]*#\\+BEGIN_" back-end-re))) (save-excursion (while (re-search-forward block-re nil t) (let ((element (save-match-data (org-element-at-point)))) (when (eq (org-element-type element) 'special-block) (save-excursion (goto-char (org-element-property :end element)) (save-match-data (search-backward "_")) (forward-char) (insert "EXPORT") (delete-region (point) (line-end-position))) (replace-match "EXPORT \\1" nil nil nil 1)))))) (let ((include-re (format "^[ \t]*#\\+INCLUDE: .*?%s[ \t]*$" back-end-re))) (while (re-search-forward include-re nil t) (let ((element (save-match-data (org-element-at-point)))) (when (and (eq (org-element-type element) 'keyword) (string= (org-element-property :key element) "INCLUDE")) (replace-match "EXPORT \\1" nil nil nil 1))))))))) #+END_SRC Moreover, ~:export-block~ keyword used in ~org-export-define-backend~ and ~org-export-define-derived-backend~ is no longer used and needs to be removed. **** Footnotes ***** [1]-like constructs are not valid footnotes Using =[1]= as a footnote was already discouraged in the manual, since it introduced too many false-positives in many Org documents. These constructs are now unsupported. If you used =[N]= in some of your documents, consider turning them into =[fn:N]=. ***** /Org Footnote/ library doesn't handle non-Org buffers Commands for footnotes in an Org document no longer try to do something in non-Org ones. If you need to have footnotes there, consider using the =footnote.el= library, shipped with Emacs. In particular, ~org-footnote-tag-for-non-org-mode-files~ no longer exists. **** ~org-file-apps~ no longer accepts S-expressions as commands The variable now accepts functions of two arguments instead of plain S-expressions. Replacing a S-expresion with an appropriate function is straightforward. For example : ("pdf" . (foo)) becomes : ("pdf" . (lambda (file link) (foo))) **** The ~{{{modification-time}}}~ macro can get time via =vc= The modification time will be determined via =vc.el= if the second argument is non-nil. See the manual for details. **** Preparation and completion functions in publishing projects change signature Preparation and completion functions are now called with an argument, which is the project property list. It used to be dynamically scoped through the ~project-plist~ variable. **** Old Babel header properties are no longer supported Using header arguments as property names is no longer possible. As such, the following #+BEGIN_EXAMPLE ,* Headline :PROPERTIES: :exports: code :var: a=1 b=2 :var+: c=3 :END: #+END_EXAMPLE should be written instead #+BEGIN_EXAMPLE ,* Headline :PROPERTIES: :header-args: :exports code :header-args: :var a=1 b=2 :header-args+: :var c=3 :END: #+END_EXAMPLE Please note that, however, old properties were defined at the source block definition. Current ones are defined where the block is called. ** Version 8.3 *** Incompatible changes **** Properties drawers syntax changes Properties drawers are now required to be located right after a headline and its planning line, when applicable. It will break some documents as TODO states changes were sometimes logged before the property drawer. The following function will repair them: #+BEGIN_SRC emacs-lisp (defun org-repair-property-drawers () "Fix properties drawers in current buffer. Ignore non Org buffers." (when (eq major-mode 'org-mode) (org-with-wide-buffer (goto-char (point-min)) (let ((case-fold-search t) (inline-re (and (featurep 'org-inlinetask) (concat (org-inlinetask-outline-regexp) "END[ \t]*$")))) (org-map-entries (lambda () (unless (and inline-re (org-looking-at-p inline-re)) (save-excursion (let ((end (save-excursion (outline-next-heading) (point)))) (forward-line) (when (org-looking-at-p org-planning-line-re) (forward-line)) (when (and (< (point) end) (not (org-looking-at-p org-property-drawer-re)) (save-excursion (and (re-search-forward org-property-drawer-re end t) (eq (org-element-type (save-match-data (org-element-at-point))) 'drawer)))) (insert (delete-and-extract-region (match-beginning 0) (min (1+ (match-end 0)) end))) (unless (bolp) (insert "\n")))))))))))) #+END_SRC **** Using "COMMENT" is now equivalent to commenting with "#" If you used "COMMENT" in headlines to prevent a subtree from being exported, you can still do it but all information within the subtree is now commented out, i.e. no #+OPTIONS line will be parsed or taken into account when exporting. If you want to exclude a headline from export while using its contents for setting options, use =:noexport:= (see =org-export-exclude-tags=.) **** =#+CATEGORY= keywords no longer apply partially to document It was possible to use several such keywords and have them apply to the text below until the next one, but strongly deprecated since Org 5.14 (2008). =#+CATEGORY= keywords are now global to the document. You can use node properties to set category for a subtree, e.g., #+BEGIN_SRC org ,* Headline :PROPERTIES: :CATEGORY: some category :END: #+END_SRC **** New variable to control visibility when revealing a location ~org-show-following-heading~, ~org-show-siblings~, ~org-show-entry-below~ and ~org-show-hierarchy-above~ no longer exist. Instead, visibility is controlled through a single variable: ~org-show-context-detail~, which see. **** Replace disputed keys again when reading a date ~org-replace-disputed-keys~ has been ignored when reading date since version 8.1, but the former behavior is restored again. Keybinding for reading date can be customized with a new variable ~org-read-date-minibuffer-local-map~. **** No default title is provided when =TITLE= keyword is missing Skipping =TITLE= keyword no longer provides the current file name, or buffer name, as the title. Instead, simply ignore the title. **** Default bindings of =C-c C-n= and =C-c C-p= changed The key sequences =C-c C-n= and =C-c C-p= are now bound to ~org-next-visible-heading~ and ~org-previous-visible-heading~ respectively, rather than the =outline-mode= versions of these functions. The Org version of these functions skips over inline tasks (and even-level headlines when ~org-odd-levels-only~ is set). **** ~org-element-context~ no longer return objects in keywords ~org-element-context~ used to return objects on some keywords, i.e., =TITLE=, =DATE= and =AUTHOR=. It now returns only the keyword. **** ~org-timer-default-timer~ type changed from number to string If you have, in your configuration, something like =(setq org-timer-default-timer 10)= replace it with =(setq org-timer-default-timer "10")=. **** Functions signature changes The following functions require an additional argument. See their docstring for more information. - ~org-export-collect-footnote-definitions~ - ~org-html-format-headline-function~ - ~org-html-format-inlinetask-function~ - ~org-latex-format-headline-function~ - ~org-latex-format-inlinetask-function~ - ~org-link-search~