~bzg/orgweb

ref: 56b3377a980d39271de8c6a89060ca776968213a orgweb/Changes.org -rw-r--r-- 22.4 KiB
56b3377aBastien .build.yml and publish.sh: Load org-contrib/ox-extra and use it 3 months ago
                                                                                
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
#+title:     Release notes | Org mode
#+setupfile: setup.org
#+link:      git https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=%s
#+link:      doc https://orgmode.org/worg/doc.html#%s
#+link:      msg https://list.orgmode.org/%s
#+description: Org Org-mode Emacs Changes ChangeLog release notes
#+include: "./resources/preamble.html" export html

#+include: "./resources/normal-outline-3.html" export html

@@html:<br/>@@

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

** Important announcements and breaking changes

*** The =contrib/= now lives in a separate repository

Org's repository has been trimmed from the =contrib/= directory.

The old contents of the =contrib/= directory now lives in a separate
repository at https://git.sr.ht/~bzg/org-contrib.

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.

*** Org ELPA and Org archives won't be available for Org > 9.5

[[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.

Also, Org 9.5 is available as =tar.gz= and =zip= archives, but this
installation method is also deprecated.

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.

See https://orgmode.org/org.html#Installation for the details.

*** =ditaa.jar= is not bundled with Org anymore

=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.

*** ~org-adapt-indentation~ now defaults to =nil=

If you want to automatically indent headlines' metadata, set it to
=headline-data=.

If you want to automatically indent every line to the headline's
current indentation, set it to =t=.

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.

*** ~org-speed-commands-user~ is obsolete, use ~org-speed-commands~

Setting ~org-speed-commands-user~ in your configuration won't have any
effect.  Please set ~org-speed-commands~ instead, which see.

*** Some =ob-*.el= files have been moved to the org-contrib repo

These files have been moved to https://git.sr.ht/~bzg/org-contrib:

- 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

See the discussion [[msg::87bl9rq29m.fsf@gnu.org][here]].

*** Compatibility with Emacs versions

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.

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.

See [[https://orgmode.org/worg/org-maintenance.html#emacs-compatibility][this note on Worg]] and [[git::519947e508e081e71bf67db99e27b1c171ba4dfe][this commit]].

** New features

*** New citation engine

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 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.

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=.

*** Async session evaluation

The =:async= header argument can be used for asynchronous evaluation
in session blocks for certain languages.

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.

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).

Async evaluation is disabled during export.
*** ~ox-koma-letter.el~ is now part of Org's core

~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.

*** Support exporting DOI links

Org now supports export for DOI links, through its new =ol-doi.el=
library.  For backward compatibility, it is loaded by default.

*** Add a new ~:refile-targets~ template option

When exiting capture mode via ~org-capture-refile~, the variable
~org-refile-targets~ will be temporarily bound to the value of this
template option.

*** New startup options =#+startup: show<n>levels=

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.

Example:

: #+startup: show3levels

*** New =u= table formula flag to enable Calc units simplification mode

A new =u= mode flag for Calc formulas in Org tables has been added to
enable Calc units simplification mode.

*** Support fontification of inline export snippets

See [[msg:87im57fh8j.fsf@gmail.com][this thread]].

*** New command =org-refile-reverse= bound to =C-c C-M-w=

You can now use =C-c C-M-w= to run ~org-refile-reverse~.

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.

*** LaTeX attribute ~:float~ now passes through arbitrary values

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.

*** Support verse and quote blocks in LaTeX export

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 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=.

*** =org-set-tags-command= selects tags from ~org-global-tags-completion-table~

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.

*** Clocktable option =:formula %= now shows the per-file time percentages

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.

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.

The more agenda files you have, the more useful this behavior becomes.

*** =ob-python.el= improvements to =:return= header argument

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.

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:

#+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

,#+RESULTS:
[[file:/home/jack/tmp/plot.svg]]
#+END_SRC

As another example, we can use =:return= with the external [[https://pypi.org/project/tabulate/][tabulate]]
package, to convert pandas Dataframes into orgmode tables:

#+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 |
#+end_src

*** Display images with width proportional to the buffer text width

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.

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.

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.

** New options
*** Option ~org-hidden-keywords~ now also applies to #+SUBTITLE:

The option ~org-hidden-keywords~ previously applied
to #+TITLE:, #+AUTHOR:, #+DATE:, and #+EMAIL:.  Now it can also be
used to hide the #+SUBTITLE: keyword.

*** New formatting directive ~%L~ for org-capture

The new ~%L~ formatting directive contains the bare link target, and
may be used to create links with programmatically generated
descriptions.

*** New option ~org-id-ts-format~

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.

*** New argument for ~file-desc~ babel header

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 option to set ~org-link-file-path-type~ to a function

~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.

For example, if you use ~project.el~, you can set this function to use
relative links within a project as follows:

#+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))))))
#+end_src

*** New options and new behavior for babel LaTeX SVG image files

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).

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 option ~org-html-meta-tags~ allows for HTML meta tags customization

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).

*** Option ~org-agenda-bulk-custom-functions~ now supports collecting bulk arguments

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 faces to improve the contextuality of Org agenda views

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.

Quoting from [[https://list.orgmode.org/87lf7q7gpq.fsf@protesilaos.com/][this thread]]:

#+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.

+ 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.

+ 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 'org-agenda-date-weekend-today' provides the option to
  differentiate the current date on a weekend from the current date on
  weekdays.
#+end_quote

*** New option ~org-clock-ask-before-exiting~

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.

*** Option ~org-html-inline-image-rules~ now includes .webp

By default ox-html now inlines webp images.

*** ~org-html-head-include-scripts~ is now =nil= by default

See [[msg:498dbe2e-0cd2-c81e-7960-4a26c566a1f7@memebeam.org][this thread]].

*** New option ~org-html-content-class~

This is the CSS class name to use for the top level content wrapper.

*** New option ~org-babel-plantuml-svg-text-to-path~

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.

*** You can now configure ~org-html-scripts~ and ~org-html-style-default~

~org-html-scripts~ and ~org-html-style-default~ used to be constants,
you can now configure them.

*** New option ~org-attach-git-dir~

~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.

*** Some faces now use fixed-pitch

See [[msg:875z8njaol.fsf@protesilaos.com][this thread]].

*** New option ~org-attach-sync-delete-empty-dir~

~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).

*** ~org-babel-default-header-args~ can now be specified as closures or strings

~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:

#+begin_src elisp
(defun org-src-sha ()
  (let ((elem (org-element-at-point)))
    (concat (sha1 (org-element-property :value elem)) \".svg\")))

(setq org-babel-default-header-args:latex
      `((:results . \"file link replace\")
        (:file . (lambda () (org-src-sha)))))
#+end_src

This will set the ~:file~ header argument to the sha1 checksum of the
contents of the current latex source block.

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.

** 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

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.

Previously =org-goto-first-child= would do nothing before first
heading, except return nil.

*** Faces of all the heading text elements now conform to the headline face

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.

Users who prefer to keep the old behaviour should change their face
customisation explicitly stating that =default= face is inherited.

Example of old face customisation:

#+begin_src emacs-lisp
(setq org-todo-keyword-faces '(("TODO"
                                :background "chocolate"
                                :height 0.75)))
#+end_src

To preserve the old behaviour the above customisation should be
changed to

#+begin_src emacs-lisp
(setq org-todo-keyword-faces '(("TODO"
                                :inherit default
                                :background "chocolate"
                                :height 0.75)))
#+end_src

*** Storing ID-links before first heading uses title as description

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.

*** Change in =org-tags-expand= signature

The function does not allow for a third optional parameter anymore.
*** LaTeX environment =#+results= are now removed

If a babel src block produces a raw LaTeX environment, it will now be
recognised as a result, and so replaced when re-evaluated.

*** Tag completion now uses =completing-read-multiple=

Tag completion now uses =completing-read-multiple= with a simple
completion table, which should allow better interoperability with
custom completion functions.

*** Providing =directory-empty-p= from Emacs 28 as =org-directory-empty-p=

*** =org-get-last-sibling= marked as obsolete

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=.

*** Make org-protocol compatible with =URLSearchParams= JavaScript class

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:

#+begin_example
'org-protocol://store-link?' + new URLSearchParams({
      url: location.href, title: document.title})
#+end_example

*** Remove obsolete LaTeX packages from ~org-latex-default-packages-alist~

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]].