branch: externals-release/org
commit 5b8159228a44ff4aeb4a9f547c01094a9591c181
Author: Ihor Radchenko <yanta...@posteo.net>
Commit: Ihor Radchenko <yanta...@posteo.net>
etc/ORG-NEWS: Move user-facing changes near the top
---
etc/ORG-NEWS | 824 +++++++++++++++++++++++++++++------------------------------
1 file changed, 412 insertions(+), 412 deletions(-)
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 76f8298c2d..809f8834c3 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -240,274 +240,308 @@ would overwrite itself.
Now, an error is thrown.
-** Major changes and additions to Org element API and Org syntax
-*** Diary type timestamps now support optional time/timerange
+** New features
-Previously, diary type timestamps could not specify time.
-Now, it is allowed to add a time or time range:
+# We list the most important features, and the features that may
+# require user action to be used.
-: <%%(diary-float t 4 2) 22:00-23:00>
-: <%%(diary-float t 4 2) 10:30>
+*** Images and files in clipboard can be pasted
-The parsed representation of such timestamps will have ~:hour-start~,
-~:minute-start~, ~:hour-end~, ~:minute-end~, and ~:range-type~
-properties set appropriately. In addition, a new ~:diary-sexp~
-property will store the diary sexp value.
+Org asks the user what must be done when pasting images and files
+copied to the clipboard from a file manager using the ~yank-media~
+command. The default action can be set by customizing
+~org-yank-dnd-method~. The ~yank-media~ command was added in Emacs
+29.
-For example,
+Images can be saved to a separate directory instead of being attached,
+customize ~org-yank-image-save-method~.
-: <%%(diary-float t 4 2) 22:00-23:00>
+Image filename chosen can be customized by setting
+~org-yank-image-file-name-function~ which by default autogenerates a
+filename based on the current time.
-will have the following properties
+*** Files and images can be attached by dropping onto Emacs
-#+begin_src emacs-lisp
-:type: diary
-:range-type: timerange
-:raw-value: "<%%(diary-float t 4 2) 22:00-23:00>"
-:year-start: nil
-:month-start: nil
-:day-start: nil
-:hour-start: 22
-:minute-start: 0
-:year-end: nil
-:month-end: nil
-:day-end: nil
-:hour-end: 23
-:minute-end: 0
-:diary-sexp: "(diary-float t 4 2)"
-#+end_src
+By default, Org asks the user what to do with the dropped file like
+for pasted files. The same user option ~org-yank-dnd-method~ is
+respected.
-*** Underline syntax now takes priority over subscript when both are applicable
+Images dropped also respect the value of ~org-yank-image-save-method~
+when ~org-yank-dnd-method~ is =attach=.
-Previously, Org mode interpreted =(_text_)= as subscript.
-Now, the interpretation is changed to underline.
+*** =id:= links support search options; ~org-id-store-link~ adds search option
by default
-=(_text_)= matches both subscript and underline markup. The
-interpretation is changed to keep consistency with other emphasis like
-=(*bold*)=.
+Adding search option by ~org-id-store-link~ can be disabled by setting
+~org-id-link-use-context~ to ~nil~, or toggled for a single call by
+passing universal argument.
-Most of the users should not be affected by this change - it only applies when
character immediately preceding =_= is one of =-=, =(=, ='=, and ={=.
+When using this feature, IDs should not include =::=, which is used in
+links to indicate the start of the search string. For backwards
+compability, existing IDs including =::= will still be matched (but
+cannot be used together with search option). A new org-lint checker
+has been added to warn about this.
-*** New term: "syntax node"
+*** Org mode no longer disallows configuring ~display-buffer-alist~ to open
Org popups in other frame
-To reduce confusion with "element" referring to both "syntax element"
-and "element/object" class, we now prefer using "syntax node" when
-referring to generic Org syntax elements. "Elements" and "objects"
-now refer to different syntax node classes of paragraph-like nodes and
-markup-like nodes.
+Previously, Org mode disallowed pop-up frames when displaying dispatch buffers.
+This is no longer the case. ~display-buffer-alist~ is fully obeyed.
-*** New element type ~anonymous~
+~org-switch-to-buffer-other-window~ and ~org-no-popups~ are now deprecated.
-Secondary strings can now be recognized as ~anonymous~ type to
-distinguish from non-elements. With a new optional argument,
-~org-element-type~ will return ~anonymous~ for secondary strings
-instead of nil.
+*** Asynchronous code evaluatation in ~ob-shell~
-The new element type can be used in ~org-element-lineage~,
-~org-element-map~, and other functions that filter by element type.
+Running shell blocks with the ~:session~ header freezes Emacs until
+execution completes. The new ~:async~ header allows users to continue
+editing with Emacs while a ~:session~ block executes.
-*** Internal structure of Org parse tree has been changed
+*** Add support for repeating tasks in iCalendar export
-The code relying upon the previously used =(TYPE PROPERTIES-PLIST
CONTENTS-LIST)=
-structure may no longer work. Please use ~org-element-create~,
-~org-element-property~, and other Org element API functions to work
-with Org syntax trees.
+Repeating Scheduled and Deadline timestamps in TODOs are now exported
+as recurring tasks in iCalendar export.
-Some syntax node properties are no longer stored as property list elements.
-Instead, they are kept in a special vector value of a new
-=:standard-properties= property. This is done to improve performance.
+In case the TODO has just a single planning timestamp (Scheduled or
+Deadline, but not both), its repeater is used as the iCalendar
+recurrence rule (RRULE).
-If there is a need to traverse all the node properties, a new API
-function ~org-element-properties-map~ can be used.
+If the TODO has both Scheduled and Deadline planning timestamps, then
+the following cases are implemented:
-Properties and their values can now be deferred to avoid overheads
-when parsing. They are calculated lazily, when the value/property is
-requested by ~org-element-property~ and other getter functions. Using
-~plist-get~ to retrieve values of =PROPERTIES-PLIST= is not
-recommended as deferred properties will not be resolved in such
-scenario.
+- If both have the same repeater, then it is used as the RRULE.
+- Scheduled has repeater but Deadline does not: the Scheduled repeater
+ is used as RRULE, and Deadline is used as UNTIL (the end date for
+ the repeater). This is similar to ~repeated-after-deadline~ in
+ ~org-agenda-skip-scheduled-if-deadline-is-shown~.
-New special property =:secondary= is used internally to record which
-properties store secondary objects.
+The following 2 cases are not yet implemented, and the repeater is
+skipped (with a warning) if the ox-icalendar export encounters them:
-New special property =:deferred= is used to keep information how to
-calculate property names lazily.
+- Deadline has a repeater but Scheduled does not.
+- Scheduled and Deadline have different repeaters.
-See the commentary in =lisp/org-element-ast.el= for more details.
+Also note that only vanilla repeaters are currently exported; the
+special repeaters ~++~ and ~.+~ are skipped.
-*** Multiple affiliated keyword values are now stored in the order they appear
in buffer
+*** Babel references =FILE:REFERENCE= now search current buffer when =FILE=
does not exist
-Previously,
+When =FILE= does not exist, the reference is searched in the current
+file, using the verbatim reference. This way,
+=:var table=tbl:example= will be searched inside the current buffer.
-: #+caption: foo
-: #+caption: bar
-: Paragraph
+*** Folded lines can now extend their face beyond ellipsis
-would have its =:caption= property set to ~(("bar") ("foo"))~ in reverse order.
+Previously, ~:extend t~ face attribute did not make folded headlines,
+blocks, and drawers extend their face beyond end of line.
-Now, the order is not reversed: ~(("foo") ("bar"))~.
+Now, the ellipsis and trailing newline use the same face as the last
+character before the fold.
-*** Some property values may now be calculated lazily and require original Org
buffer to be live
+*** iCalendar export now supports multiline =SUMMARY=, =LOCATION=, and
=DESCRIPTION= properties
-~org-element-at-point~, ~org-element-context~, and
-~org-element-at-point-no-context~ may now not calculate all the
-property values at the call time. Instead, the calculation will be
-deferred until ~org-element-property~ or the equivalent getter
-function is called. The property names may not all be calculated as
-well.
+Previously, it was not possible to specify multi-line location,
+summary, or description when exporting to iCalendar.
-It may often be necessary to have the original Org buffer open when
-resolving the deferred values.
+In the following example, =LOCATION= was exported as "Someplace",
+ignoring the other lines.
-One can ensure that all the deferred values are resolved using new
-function ~org-element-resolve-deferred~ and new optional argument for
-~org-element-property~.
+#+begin_src org
+,* heading with multi-line property
+:PROPERTIES:
+:LOCATION: Someplace
+:LOCATION+: Some Street 5
+:LOCATION+: 12345 Small Town
+:END:
+#+end_src
-~org-element-parse-buffer~ and ~org-element-parse-secondary-string~
-will resolve all the deferred values by default. No adjustment is
-needed for their users.
+Now, =SUMMARY+=, =LOCATION+=, and =DESCRIPTION+= properties can be
+used to create multi-line values.
-*** New API functions and macros
-**** New property accessors and setters
+In the above example, =LOCATION= is now exported as
-New functions to retrieve and set (via ~setf~) commonly used element
properties:
-- =:begin= :: ~org-element-begin~
-- =:end= :: ~org-element-end~
-- =:contents-begin= :: ~org-element-contents-begin~
-- =:contents-end= :: ~org-element-contents-end~
-- =:post-affiliated= :: ~org-element-post-affiliated~
-- =:post-blank= :: ~org-element-post-blank~
-- =:parent= :: ~org-element-parent~
+: Someplace
+: Some Street 5
+: 12345 Small Town
-**** New macro ~org-element-with-enabled-cache~
+*** Org export backends can now disable citation processors
-The macro arranges the element cache to be active during =BODY= execution.
-When cache is enabled, the macro is identical to ~progn~. When cache
-is disabled, the macro arranges a new fresh cache that is discarded
-upon completion of =BODY=.
+A new global export option ~:with-cite-processors~, when set to nil,
+disables citation processors completely. This option is available to
+export backends via ~:options-alist~ when defining the backend.
-**** New function ~org-element-property-raw~
+The backends disabling citation processors must take care about
+exporting citation objects and =print_bibliography= keywords via
+transcoders.
-This function is like ~org-element-property~ but does not try to
-resolve deferred properties.
+Users can disable citations processors by customizing new
+~org-export-process-citations~ option.
-~org-element-property-raw~ can be used with ~setf~.
+*** Org babel backends are now expected to define an additional API function
~org-babel-session-buffer:<lang>~
-**** New function ~org-element-put-property-2~
+Org babel now uses session buffer (if it exists) to retrieve
+~default-directory~ environment during src block evaluation.
-Like ~org-element-put-property~, but the argument list is changed to have
-=NODE= as the last argument. Useful with threading macros like
-~thread-last~.
+By default, buffer named like session is checked. All the backends
+that create sessions inside buffers named differently should provide a
+function ~org-babel-session-buffer:<lang>~. The function must accept
+two arguments - session name and info list (as returned by
+~org-babel-get-src-block-info~); and return the session buffer name.
-**** New function ~org-element-properties-resolve~
+*** ~org-paste-subtree~ now handles =C-u= and =C-u C-u= prefix arguments
specially
-This function resolves all the deferred values in a =NODE=, modifying
-the =NODE= for side effect.
+With =C-u= prefix argument, force inserting a sibling heading below.
+With =C-u C-u= prefix argument, force inserting a child heading.
-**** New functions ~org-element-properties-map~ and
~org-element-properties-mapc~
+*** ~org-metaup~ and ~org-metadown~ now act on headings in region
-New functions to map over =NODE= properties.
+When region is active and starts at a heading, ~org-metaup~ and
+~org-metadown~ will move all the selected subtrees.
-**** New function ~org-element-ast-map~
+*** Many structure editing commands now do not deactivate region
-This is a more general equivalent of ~org-element-map~. It allows
-more precise control over recursion into secondary strings.
+Moving, promoting, and demoting of headings and items in region now do
+not deactivate Transient mark mode.
-**** New function ~org-element-lineage-map~
+Users can thus conveniently select multiple headings/items and use,
+for example, =M-<down>=/=M-<up>= repeatedly without losing the
+selection.
-Traverse syntax tree ancestor list, applying arbitrary function to
-each ancestor.
+*** Capture templates now support ~(here)~ as a target
-**** New function ~org-element-property-inherited~
+A capture template can target ~(here)~ which is the equivalent of
+invoking a capture template with a zero prefix.
-Like ~org-element-property~, but can be used to retrieve and combine
-multiple different properties for a given =NODE= and its parents.
+*** =colview= dynamic block supports custom formatting function
-*** ~org-element-cache-map~ can now be used even when element cache is disabled
+The =colview= dynamic block understands a new ~:formatter~ parameter,
+which specifies a user-supplied function to format and insert the data
+in the dynamic block.
-*** =org-element= API functions and macros can now accept syntax nodes as
=POM= argument
+A global default formatting function for =colview= dynamic blocks can
+be set via the new option ~org-columns-dblock-formatter~ which
+defaults to the new function ~org-columns-dblock-write-default~, that
+implements the previous (fixed) formatting behaviour. Hence, the
+default behaviour is identical to previous versions.
-The following functions are updated:
-- ~org-agenda-entry-get-agenda-timestamp~
-- ~org-element-at-point~
-- ~org-is-habit-p~
-- ~org-id-get~
-- ~org-with-point-at~
-- ~org-entry-properties~
-- ~org-entry-get~
-- ~org-entry-delete~
-- ~org-entry-add-to-multivalued-property~
-- ~org-entry-remove-from-multivalued-property~
-- ~org-entry-member-in-multivalued-property~
-- ~org-entry-put-multivalued-property~
-- ~org-entry-get-with-inheritance~
-- ~org-entry-put~
-- ~org-read-property-value~
-- ~org-property-get-allowed-values~
+The global default function can be overridden for any given =colview=
+dynamic block individually by specifying a custom formatter function
+using the new ~:formatter~ parameter on the block's =BEGIN= line.
+
+This new feature replicates the ~:formatter~ option already available
+for =clocktable= dynamic blocks.
+
+*** =colview= dynamic block can link to headlines
+
+The =colview= dynamic block understands a new ~:link~ parameter, which
+when non-~nil~ causes =ITEM= headlines in the table to be linked to
+their origins.
+
+*** =ob-tangle.el=: New flag to remove tangle targets before writing
+
+When ~org-babel-tangle-remove-file-before-write~ is set to ~t~ the
+tangle target is removed before writing. This will allow overwriting
+read-only tangle targets. However, when tangle target is a symlink,
+this will convert the tangle target into an ordinary file.
+
+The default value is ~auto~ -- overwrite tangle targets when they are
+read-only.
+
+*** ~org-bibtex-yank~ accepts a prefix argument
+
+When called with a prefix argument, ~org-bibtex-yank~ adds data to the
+headline of the entry at point instead of creating a new one.
+
+*** =ob-plantuml.el=: Support tikz file format output
+
+=ob-plantuml.el= now output =tikz= :file format via
+=-tlatex:nopreamble= option. So that the output tikz file can be an
+input into the exported latex correctly.
+
+For example, exporting the following to LaTeX
+
+#+begin_src plantuml :file test.tikz :exports results
+Bob -> Alice : Hello World!
+#+end_src
-*** ~org-element-map~ now traverses main value in dual keywords before the
secondary value
+will include the generated =.tikz= into the exported LaTeX source.
-The traverse order for dual keywords is reversed. The main value is
-now traversed first, followed by the secondary value.
+*** =UNNUMBERED= property inheritance is now honored by ~org-num-mode~
-*** Org parse tree is now non-printable
+When ~org-num-skip-unnumbered~ is non-nil, ~org-num-mode~ now honors
+~org-use-property-inheritance~ for =UNNUMBERED= property (see manual
+section "Property Inheritance"). Previously, only local =UNNUMBERED=
+property was taken into account.
-Org parser now assigns a new property =:buffer= that holds
-non-printable buffer object. This makes syntax tree non-printable.
-Using ~print~/~read~ is no longer safe.
+Users can add ="UNNUMBERED"= to ~org-use-property-inheritance~ and set
+~org-numb-skip-unnumbered~ to ~t~ to make ~org-num-mode~ skip
+numbering of all the sub-headings with non-nil =UNNUMBERED= property.
-*** Some Org API functions no longer preserve match data
+*** ~org-insert-todo-heading-respect-content~ now accepts prefix arguments
-~org-element-at-point~, ~org-element-context~, ~org-get-category~, and
-~org-get-tags~ may modify the match data.
+The prefix arguments are passed to ~org-insert-todo-heading~.
-The relevant function docstrings now explicitly mention that match
-data may be modified.
+*** Make ~ob-sqlite~ use in-memory databases by default
-*** ~org-element-create~ now treats a single ~anonymous~ =CHILDREN= argument
as a list of child nodes
+~sqlite~ source blocks with no ~:db~ header argument now make SQLite
+use a temporary in-memory database instead of throwing an error,
+matching the behavior of the official ~sqlite3~ shell. As a result,
+~sqlite~ source blocks are now usable out of the box, that is with no
+header arguments.
-When =CHILDREN= is a single anonymous node, use its contents as children
-nodes. This way,
+*** ~org-return~ now acts on citations at point
-: (org-element-create 'section nil (org-element-contents node))
+When ~org-return-follows-link~ is non-nil and cursor is over an
+org-cite citation, ~org-return~ will call ~org-open-at-point~.
-will yield expected results with contents of another node adopted into
-a newly created one.
+*** ~org-tags-view~ supports more property operators
-Previously, one had to use
+It supports inequality operators ~!=~ and ~/=~ in addition to the less
+common (BASIC? Pascal? SQL?) ~<>~. And it supports starred versions
+of all relational operators (~<*~, ~=*~, ~!=*~, etc.) that work like
+the regular, unstarred operators but match a headline only if the
+tested property is actually present.
-: (apply #'org-element-create 'section nil (org-element-contents node))
-*** New property ~:range-type~ for org-element timestamp object
+*** =ob-python.el=: Support for more result types and plotting
-~org-element-timestamp-parser~ now adds =:range-type= property to each
-timestamp object. Possible values: ~timerange~, ~daterange~, ~nil~.
+=ob-python= now converts the following objects to org-mode tables when
+":results table" header arg is set:
-~org-element-timestamp-interpreter~ takes into account this property
-and returns an appropriate timestamp string.
+- Dictionaries
+- Numpy arrays
+- Pandas DataFrames
+- Pandas Series
-*** New properties =:repeater-deadline-value= and =:repeater-deadline-unit=
for org-element timestamp object
+When the header argument =:results graphics= is set, =ob-python= will
+use matplotlib to save graphics. The behavior depends on whether value
+or output results are used. For value results, the last line should
+return a matplotlib Figure object to plot. For output results, the
+current figure (as returned by =pyplot.gcf()=) is cleared before
+evaluation, and then plotted afterwards.
-~org-element-timestamp-parser~ now adds =:repeater-deadline-value= and
-=:repeater-deadline-unit= properties to each timestamp object that has
-a repeater deadline. For example, in =<2012-03-29 Thu ++1y/2y>=, =2y=
-is the repeater deadline with a value of =2= and unit of =y=. See
-"5.3.3 Tracking your habits" section in the manual.
+*** =ob-maxima.el=: Support for ~batch~ and ~draw~
-Possible values for =:repeater-deadline-value=: ~positive integer~, ~nil~.
+=ob-maxima= has two new header arguments: ~:batch~ and
+~:graphics-pkg~.
-Possible values for =:repeater-deadline-unit=: ~hour~, ~day~, ~week~,
-~month~, ~year~.
+The ~:batch~ header argument can be set to one of Maxima's file
+loaders (~batch~, ~load~ or ~batchload~); the default remains
+~batchload~. The ~:graphics-pkg~ header argument can be set to one of
+Maxima's graphics packages (~draw~ or ~plot~); the default remains
+~plot~. The graphics terminal is now determined from the file-ending
+of the file-name set in the ~:file~ header argument.
-~org-element-timestamp-interpreter~ takes into account these properties
-and returns an appropriate timestamp string.
+*** =ob-calc.el=: Support for tables in ~:var~
-*** =org-link= store functions are passed an ~interactive?~ argument
+=ob-calc= now supports tables in ~:var~. They are converted to a
+matrix or a vector depending on the dimensionality of the table. A
+table with a single row is converted to a vector, the rest are
+converted to a matrix.
-The ~:store:~ functions set for link types using
-~org-link-set-parameters~ are now passed an ~interactive?~ argument,
-indicating whether ~org-store-link~ was called interactively.
+*** ox-texinfo always generates a ~@direntry~
-Existing store functions will continue to work.
+We use defaults based on the file name and title of the document, and
+place the entry in the ~Misc~ category if ~TEXINFO_DIR_CATEGORY~ is missing.
+
+=TEXINFO_DIR_TITLE= is renamed to =TEXINFO_DIR_NAME=.
+The old name is obsolete.
** New and changed options
@@ -1025,308 +1059,274 @@ Final hooks are added to the following commands:
- ~org-shiftmetadown-final-hook~ to ~org-shiftmetadown~ (bound to
=M-S-<down>=).
-** New features
-
-# We list the most important features, and the features that may
-# require user action to be used.
-
-*** Images and files in clipboard can be pasted
-
-Org asks the user what must be done when pasting images and files
-copied to the clipboard from a file manager using the ~yank-media~
-command. The default action can be set by customizing
-~org-yank-dnd-method~. The ~yank-media~ command was added in Emacs
-29.
-
-Images can be saved to a separate directory instead of being attached,
-customize ~org-yank-image-save-method~.
-
-Image filename chosen can be customized by setting
-~org-yank-image-file-name-function~ which by default autogenerates a
-filename based on the current time.
-
-*** Files and images can be attached by dropping onto Emacs
-
-By default, Org asks the user what to do with the dropped file like
-for pasted files. The same user option ~org-yank-dnd-method~ is
-respected.
-
-Images dropped also respect the value of ~org-yank-image-save-method~
-when ~org-yank-dnd-method~ is =attach=.
-
-*** =id:= links support search options; ~org-id-store-link~ adds search option
by default
-
-Adding search option by ~org-id-store-link~ can be disabled by setting
-~org-id-link-use-context~ to ~nil~, or toggled for a single call by
-passing universal argument.
-
-When using this feature, IDs should not include =::=, which is used in
-links to indicate the start of the search string. For backwards
-compability, existing IDs including =::= will still be matched (but
-cannot be used together with search option). A new org-lint checker
-has been added to warn about this.
-
-*** Org mode no longer disallows configuring ~display-buffer-alist~ to open
Org popups in other frame
-
-Previously, Org mode disallowed pop-up frames when displaying dispatch buffers.
-This is no longer the case. ~display-buffer-alist~ is fully obeyed.
+** Major changes and additions to Org element API and Org syntax
+*** Diary type timestamps now support optional time/timerange
-~org-switch-to-buffer-other-window~ and ~org-no-popups~ are now deprecated.
+Previously, diary type timestamps could not specify time.
+Now, it is allowed to add a time or time range:
-*** Asynchronous code evaluatation in ~ob-shell~
+: <%%(diary-float t 4 2) 22:00-23:00>
+: <%%(diary-float t 4 2) 10:30>
-Running shell blocks with the ~:session~ header freezes Emacs until
-execution completes. The new ~:async~ header allows users to continue
-editing with Emacs while a ~:session~ block executes.
+The parsed representation of such timestamps will have ~:hour-start~,
+~:minute-start~, ~:hour-end~, ~:minute-end~, and ~:range-type~
+properties set appropriately. In addition, a new ~:diary-sexp~
+property will store the diary sexp value.
-*** Add support for repeating tasks in iCalendar export
+For example,
-Repeating Scheduled and Deadline timestamps in TODOs are now exported
-as recurring tasks in iCalendar export.
+: <%%(diary-float t 4 2) 22:00-23:00>
-In case the TODO has just a single planning timestamp (Scheduled or
-Deadline, but not both), its repeater is used as the iCalendar
-recurrence rule (RRULE).
+will have the following properties
-If the TODO has both Scheduled and Deadline planning timestamps, then
-the following cases are implemented:
+#+begin_src emacs-lisp
+:type: diary
+:range-type: timerange
+:raw-value: "<%%(diary-float t 4 2) 22:00-23:00>"
+:year-start: nil
+:month-start: nil
+:day-start: nil
+:hour-start: 22
+:minute-start: 0
+:year-end: nil
+:month-end: nil
+:day-end: nil
+:hour-end: 23
+:minute-end: 0
+:diary-sexp: "(diary-float t 4 2)"
+#+end_src
-- If both have the same repeater, then it is used as the RRULE.
-- Scheduled has repeater but Deadline does not: the Scheduled repeater
- is used as RRULE, and Deadline is used as UNTIL (the end date for
- the repeater). This is similar to ~repeated-after-deadline~ in
- ~org-agenda-skip-scheduled-if-deadline-is-shown~.
+*** Underline syntax now takes priority over subscript when both are applicable
-The following 2 cases are not yet implemented, and the repeater is
-skipped (with a warning) if the ox-icalendar export encounters them:
+Previously, Org mode interpreted =(_text_)= as subscript.
+Now, the interpretation is changed to underline.
-- Deadline has a repeater but Scheduled does not.
-- Scheduled and Deadline have different repeaters.
+=(_text_)= matches both subscript and underline markup. The
+interpretation is changed to keep consistency with other emphasis like
+=(*bold*)=.
-Also note that only vanilla repeaters are currently exported; the
-special repeaters ~++~ and ~.+~ are skipped.
+Most of the users should not be affected by this change - it only applies when
character immediately preceding =_= is one of =-=, =(=, ='=, and ={=.
-*** Babel references =FILE:REFERENCE= now search current buffer when =FILE=
does not exist
+*** New term: "syntax node"
-When =FILE= does not exist, the reference is searched in the current
-file, using the verbatim reference. This way,
-=:var table=tbl:example= will be searched inside the current buffer.
+To reduce confusion with "element" referring to both "syntax element"
+and "element/object" class, we now prefer using "syntax node" when
+referring to generic Org syntax elements. "Elements" and "objects"
+now refer to different syntax node classes of paragraph-like nodes and
+markup-like nodes.
-*** Folded lines can now extend their face beyond ellipsis
+*** New element type ~anonymous~
-Previously, ~:extend t~ face attribute did not make folded headlines,
-blocks, and drawers extend their face beyond end of line.
+Secondary strings can now be recognized as ~anonymous~ type to
+distinguish from non-elements. With a new optional argument,
+~org-element-type~ will return ~anonymous~ for secondary strings
+instead of nil.
-Now, the ellipsis and trailing newline use the same face as the last
-character before the fold.
+The new element type can be used in ~org-element-lineage~,
+~org-element-map~, and other functions that filter by element type.
-*** iCalendar export now supports multiline =SUMMARY=, =LOCATION=, and
=DESCRIPTION= properties
+*** Internal structure of Org parse tree has been changed
-Previously, it was not possible to specify multi-line location,
-summary, or description when exporting to iCalendar.
+The code relying upon the previously used =(TYPE PROPERTIES-PLIST
CONTENTS-LIST)=
+structure may no longer work. Please use ~org-element-create~,
+~org-element-property~, and other Org element API functions to work
+with Org syntax trees.
-In the following example, =LOCATION= was exported as "Someplace",
-ignoring the other lines.
+Some syntax node properties are no longer stored as property list elements.
+Instead, they are kept in a special vector value of a new
+=:standard-properties= property. This is done to improve performance.
-#+begin_src org
-,* heading with multi-line property
-:PROPERTIES:
-:LOCATION: Someplace
-:LOCATION+: Some Street 5
-:LOCATION+: 12345 Small Town
-:END:
-#+end_src
+If there is a need to traverse all the node properties, a new API
+function ~org-element-properties-map~ can be used.
-Now, =SUMMARY+=, =LOCATION+=, and =DESCRIPTION+= properties can be
-used to create multi-line values.
+Properties and their values can now be deferred to avoid overheads
+when parsing. They are calculated lazily, when the value/property is
+requested by ~org-element-property~ and other getter functions. Using
+~plist-get~ to retrieve values of =PROPERTIES-PLIST= is not
+recommended as deferred properties will not be resolved in such
+scenario.
-In the above example, =LOCATION= is now exported as
+New special property =:secondary= is used internally to record which
+properties store secondary objects.
-: Someplace
-: Some Street 5
-: 12345 Small Town
+New special property =:deferred= is used to keep information how to
+calculate property names lazily.
-*** Org export backends can now disable citation processors
+See the commentary in =lisp/org-element-ast.el= for more details.
-A new global export option ~:with-cite-processors~, when set to nil,
-disables citation processors completely. This option is available to
-export backends via ~:options-alist~ when defining the backend.
+*** Multiple affiliated keyword values are now stored in the order they appear
in buffer
-The backends disabling citation processors must take care about
-exporting citation objects and =print_bibliography= keywords via
-transcoders.
+Previously,
-Users can disable citations processors by customizing new
-~org-export-process-citations~ option.
+: #+caption: foo
+: #+caption: bar
+: Paragraph
-*** Org babel backends are now expected to define an additional API function
~org-babel-session-buffer:<lang>~
+would have its =:caption= property set to ~(("bar") ("foo"))~ in reverse order.
-Org babel now uses session buffer (if it exists) to retrieve
-~default-directory~ environment during src block evaluation.
+Now, the order is not reversed: ~(("foo") ("bar"))~.
-By default, buffer named like session is checked. All the backends
-that create sessions inside buffers named differently should provide a
-function ~org-babel-session-buffer:<lang>~. The function must accept
-two arguments - session name and info list (as returned by
-~org-babel-get-src-block-info~); and return the session buffer name.
+*** Some property values may now be calculated lazily and require original Org
buffer to be live
-*** ~org-paste-subtree~ now handles =C-u= and =C-u C-u= prefix arguments
specially
+~org-element-at-point~, ~org-element-context~, and
+~org-element-at-point-no-context~ may now not calculate all the
+property values at the call time. Instead, the calculation will be
+deferred until ~org-element-property~ or the equivalent getter
+function is called. The property names may not all be calculated as
+well.
-With =C-u= prefix argument, force inserting a sibling heading below.
-With =C-u C-u= prefix argument, force inserting a child heading.
+It may often be necessary to have the original Org buffer open when
+resolving the deferred values.
-*** ~org-metaup~ and ~org-metadown~ now act on headings in region
+One can ensure that all the deferred values are resolved using new
+function ~org-element-resolve-deferred~ and new optional argument for
+~org-element-property~.
-When region is active and starts at a heading, ~org-metaup~ and
-~org-metadown~ will move all the selected subtrees.
+~org-element-parse-buffer~ and ~org-element-parse-secondary-string~
+will resolve all the deferred values by default. No adjustment is
+needed for their users.
-*** Many structure editing commands now do not deactivate region
+*** New API functions and macros
+**** New property accessors and setters
-Moving, promoting, and demoting of headings and items in region now do
-not deactivate Transient mark mode.
+New functions to retrieve and set (via ~setf~) commonly used element
properties:
+- =:begin= :: ~org-element-begin~
+- =:end= :: ~org-element-end~
+- =:contents-begin= :: ~org-element-contents-begin~
+- =:contents-end= :: ~org-element-contents-end~
+- =:post-affiliated= :: ~org-element-post-affiliated~
+- =:post-blank= :: ~org-element-post-blank~
+- =:parent= :: ~org-element-parent~
-Users can thus conveniently select multiple headings/items and use,
-for example, =M-<down>=/=M-<up>= repeatedly without losing the
-selection.
+**** New macro ~org-element-with-enabled-cache~
-*** Capture templates now support ~(here)~ as a target
+The macro arranges the element cache to be active during =BODY= execution.
+When cache is enabled, the macro is identical to ~progn~. When cache
+is disabled, the macro arranges a new fresh cache that is discarded
+upon completion of =BODY=.
-A capture template can target ~(here)~ which is the equivalent of
-invoking a capture template with a zero prefix.
+**** New function ~org-element-property-raw~
-*** =colview= dynamic block supports custom formatting function
+This function is like ~org-element-property~ but does not try to
+resolve deferred properties.
-The =colview= dynamic block understands a new ~:formatter~ parameter,
-which specifies a user-supplied function to format and insert the data
-in the dynamic block.
+~org-element-property-raw~ can be used with ~setf~.
-A global default formatting function for =colview= dynamic blocks can
-be set via the new option ~org-columns-dblock-formatter~ which
-defaults to the new function ~org-columns-dblock-write-default~, that
-implements the previous (fixed) formatting behaviour. Hence, the
-default behaviour is identical to previous versions.
+**** New function ~org-element-put-property-2~
-The global default function can be overridden for any given =colview=
-dynamic block individually by specifying a custom formatter function
-using the new ~:formatter~ parameter on the block's =BEGIN= line.
+Like ~org-element-put-property~, but the argument list is changed to have
+=NODE= as the last argument. Useful with threading macros like
+~thread-last~.
-This new feature replicates the ~:formatter~ option already available
-for =clocktable= dynamic blocks.
+**** New function ~org-element-properties-resolve~
-*** =colview= dynamic block can link to headlines
+This function resolves all the deferred values in a =NODE=, modifying
+the =NODE= for side effect.
-The =colview= dynamic block understands a new ~:link~ parameter, which
-when non-~nil~ causes =ITEM= headlines in the table to be linked to
-their origins.
+**** New functions ~org-element-properties-map~ and
~org-element-properties-mapc~
-*** =ob-tangle.el=: New flag to remove tangle targets before writing
+New functions to map over =NODE= properties.
-When ~org-babel-tangle-remove-file-before-write~ is set to ~t~ the
-tangle target is removed before writing. This will allow overwriting
-read-only tangle targets. However, when tangle target is a symlink,
-this will convert the tangle target into an ordinary file.
+**** New function ~org-element-ast-map~
-The default value is ~auto~ -- overwrite tangle targets when they are
-read-only.
+This is a more general equivalent of ~org-element-map~. It allows
+more precise control over recursion into secondary strings.
-*** ~org-bibtex-yank~ accepts a prefix argument
+**** New function ~org-element-lineage-map~
-When called with a prefix argument, ~org-bibtex-yank~ adds data to the
-headline of the entry at point instead of creating a new one.
+Traverse syntax tree ancestor list, applying arbitrary function to
+each ancestor.
-*** =ob-plantuml.el=: Support tikz file format output
+**** New function ~org-element-property-inherited~
-=ob-plantuml.el= now output =tikz= :file format via
-=-tlatex:nopreamble= option. So that the output tikz file can be an
-input into the exported latex correctly.
+Like ~org-element-property~, but can be used to retrieve and combine
+multiple different properties for a given =NODE= and its parents.
-For example, exporting the following to LaTeX
+*** ~org-element-cache-map~ can now be used even when element cache is disabled
-#+begin_src plantuml :file test.tikz :exports results
-Bob -> Alice : Hello World!
-#+end_src
+*** =org-element= API functions and macros can now accept syntax nodes as
=POM= argument
-will include the generated =.tikz= into the exported LaTeX source.
+The following functions are updated:
+- ~org-agenda-entry-get-agenda-timestamp~
+- ~org-element-at-point~
+- ~org-is-habit-p~
+- ~org-id-get~
+- ~org-with-point-at~
+- ~org-entry-properties~
+- ~org-entry-get~
+- ~org-entry-delete~
+- ~org-entry-add-to-multivalued-property~
+- ~org-entry-remove-from-multivalued-property~
+- ~org-entry-member-in-multivalued-property~
+- ~org-entry-put-multivalued-property~
+- ~org-entry-get-with-inheritance~
+- ~org-entry-put~
+- ~org-read-property-value~
+- ~org-property-get-allowed-values~
-*** =UNNUMBERED= property inheritance is now honored by ~org-num-mode~
+*** ~org-element-map~ now traverses main value in dual keywords before the
secondary value
-When ~org-num-skip-unnumbered~ is non-nil, ~org-num-mode~ now honors
-~org-use-property-inheritance~ for =UNNUMBERED= property (see manual
-section "Property Inheritance"). Previously, only local =UNNUMBERED=
-property was taken into account.
+The traverse order for dual keywords is reversed. The main value is
+now traversed first, followed by the secondary value.
-Users can add ="UNNUMBERED"= to ~org-use-property-inheritance~ and set
-~org-numb-skip-unnumbered~ to ~t~ to make ~org-num-mode~ skip
-numbering of all the sub-headings with non-nil =UNNUMBERED= property.
+*** Org parse tree is now non-printable
-*** ~org-insert-todo-heading-respect-content~ now accepts prefix arguments
+Org parser now assigns a new property =:buffer= that holds
+non-printable buffer object. This makes syntax tree non-printable.
+Using ~print~/~read~ is no longer safe.
-The prefix arguments are passed to ~org-insert-todo-heading~.
+*** Some Org API functions no longer preserve match data
-*** Make ~ob-sqlite~ use in-memory databases by default
+~org-element-at-point~, ~org-element-context~, ~org-get-category~, and
+~org-get-tags~ may modify the match data.
-~sqlite~ source blocks with no ~:db~ header argument now make SQLite
-use a temporary in-memory database instead of throwing an error,
-matching the behavior of the official ~sqlite3~ shell. As a result,
-~sqlite~ source blocks are now usable out of the box, that is with no
-header arguments.
+The relevant function docstrings now explicitly mention that match
+data may be modified.
-*** ~org-return~ now acts on citations at point
+*** ~org-element-create~ now treats a single ~anonymous~ =CHILDREN= argument
as a list of child nodes
-When ~org-return-follows-link~ is non-nil and cursor is over an
-org-cite citation, ~org-return~ will call ~org-open-at-point~.
+When =CHILDREN= is a single anonymous node, use its contents as children
+nodes. This way,
-*** ~org-tags-view~ supports more property operators
+: (org-element-create 'section nil (org-element-contents node))
-It supports inequality operators ~!=~ and ~/=~ in addition to the less
-common (BASIC? Pascal? SQL?) ~<>~. And it supports starred versions
-of all relational operators (~<*~, ~=*~, ~!=*~, etc.) that work like
-the regular, unstarred operators but match a headline only if the
-tested property is actually present.
+will yield expected results with contents of another node adopted into
+a newly created one.
-*** =ob-python.el=: Support for more result types and plotting
+Previously, one had to use
-=ob-python= now converts the following objects to org-mode tables when
-":results table" header arg is set:
+: (apply #'org-element-create 'section nil (org-element-contents node))
+*** New property ~:range-type~ for org-element timestamp object
-- Dictionaries
-- Numpy arrays
-- Pandas DataFrames
-- Pandas Series
+~org-element-timestamp-parser~ now adds =:range-type= property to each
+timestamp object. Possible values: ~timerange~, ~daterange~, ~nil~.
-When the header argument =:results graphics= is set, =ob-python= will
-use matplotlib to save graphics. The behavior depends on whether value
-or output results are used. For value results, the last line should
-return a matplotlib Figure object to plot. For output results, the
-current figure (as returned by =pyplot.gcf()=) is cleared before
-evaluation, and then plotted afterwards.
+~org-element-timestamp-interpreter~ takes into account this property
+and returns an appropriate timestamp string.
-*** =ob-maxima.el=: Support for ~batch~ and ~draw~
+*** New properties =:repeater-deadline-value= and =:repeater-deadline-unit=
for org-element timestamp object
-=ob-maxima= has two new header arguments: ~:batch~ and
-~:graphics-pkg~.
+~org-element-timestamp-parser~ now adds =:repeater-deadline-value= and
+=:repeater-deadline-unit= properties to each timestamp object that has
+a repeater deadline. For example, in =<2012-03-29 Thu ++1y/2y>=, =2y=
+is the repeater deadline with a value of =2= and unit of =y=. See
+"5.3.3 Tracking your habits" section in the manual.
-The ~:batch~ header argument can be set to one of Maxima's file
-loaders (~batch~, ~load~ or ~batchload~); the default remains
-~batchload~. The ~:graphics-pkg~ header argument can be set to one of
-Maxima's graphics packages (~draw~ or ~plot~); the default remains
-~plot~. The graphics terminal is now determined from the file-ending
-of the file-name set in the ~:file~ header argument.
+Possible values for =:repeater-deadline-value=: ~positive integer~, ~nil~.
-*** =ob-calc.el=: Support for tables in ~:var~
+Possible values for =:repeater-deadline-unit=: ~hour~, ~day~, ~week~,
+~month~, ~year~.
-=ob-calc= now supports tables in ~:var~. They are converted to a
-matrix or a vector depending on the dimensionality of the table. A
-table with a single row is converted to a vector, the rest are
-converted to a matrix.
+~org-element-timestamp-interpreter~ takes into account these properties
+and returns an appropriate timestamp string.
-*** ox-texinfo always generates a ~@direntry~
+*** =org-link= store functions are passed an ~interactive?~ argument
-We use defaults based on the file name and title of the document, and
-place the entry in the ~Misc~ category if ~TEXINFO_DIR_CATEGORY~ is missing.
+The ~:store:~ functions set for link types using
+~org-link-set-parameters~ are now passed an ~interactive?~ argument,
+indicating whether ~org-store-link~ was called interactively.
-=TEXINFO_DIR_TITLE= is renamed to =TEXINFO_DIR_NAME=.
-The old name is obsolete.
+Existing store functions will continue to work.
** New functions and changes in function arguments
