From bf9ec3d91a79414deac039f7bf83352a9b0a9a85 Mon Sep 17 00:00:00 2001 From: Kyle Meyer Date: Wed, 29 Sep 2021 18:48:59 -0400 Subject: [PATCH] Update to Org 9.5 --- doc/misc/org.org | 899 +++++++++++++------- etc/ORG-NEWS | 691 ++++++++++++++-- etc/refcards/orgcard.tex | 4 +- lisp/org/ob-C.el | 116 ++- lisp/org/ob-J.el | 189 ----- lisp/org/ob-R.el | 122 ++- lisp/org/ob-abc.el | 90 -- lisp/org/ob-asymptote.el | 137 --- lisp/org/ob-awk.el | 13 +- lisp/org/ob-calc.el | 3 +- lisp/org/ob-clojure.el | 1 + lisp/org/ob-comint.el | 174 +++- lisp/org/ob-coq.el | 80 -- lisp/org/ob-core.el | 162 ++-- lisp/org/ob-dot.el | 3 +- lisp/org/ob-ebnf.el | 81 -- lisp/org/ob-eshell.el | 3 +- lisp/org/ob-eval.el | 87 +- lisp/org/ob-exp.el | 30 +- lisp/org/ob-forth.el | 4 +- lisp/org/ob-fortran.el | 10 +- lisp/org/ob-gnuplot.el | 24 +- lisp/org/ob-groovy.el | 3 +- lisp/org/ob-haskell.el | 11 +- lisp/org/ob-hledger.el | 69 -- lisp/org/ob-io.el | 105 --- lisp/org/ob-java.el | 480 ++++++++++- lisp/org/ob-js.el | 4 +- lisp/org/ob-julia.el | 344 ++++++++ lisp/org/ob-latex.el | 63 +- lisp/org/ob-ledger.el | 68 -- lisp/org/ob-lilypond.el | 26 +- lisp/org/ob-lisp.el | 2 +- lisp/org/ob-lua.el | 6 +- lisp/org/ob-makefile.el | 3 +- lisp/org/ob-mscgen.el | 81 -- lisp/org/ob-ocaml.el | 6 +- lisp/org/ob-octave.el | 18 +- lisp/org/ob-perl.el | 1 + lisp/org/ob-picolisp.el | 185 ----- lisp/org/ob-plantuml.el | 15 +- lisp/org/ob-processing.el | 2 +- lisp/org/ob-python.el | 69 +- lisp/org/ob-ruby.el | 2 +- lisp/org/ob-sass.el | 2 +- lisp/org/ob-scheme.el | 2 +- lisp/org/ob-screen.el | 5 +- lisp/org/ob-sed.el | 12 +- lisp/org/ob-shen.el | 79 -- lisp/org/ob-sql.el | 78 +- lisp/org/ob-sqlite.el | 30 +- lisp/org/ob-stan.el | 86 -- lisp/org/ob-tangle.el | 202 +++-- lisp/org/ob-vala.el | 116 --- lisp/org/oc-basic.el | 770 +++++++++++++++++ lisp/org/oc-biblatex.el | 319 +++++++ lisp/org/oc-csl.el | 612 ++++++++++++++ lisp/org/oc-natbib.el | 196 +++++ lisp/org/oc.el | 1608 ++++++++++++++++++++++++++++++++++++ lisp/org/ol-bbdb.el | 4 +- lisp/org/ol-bibtex.el | 38 +- lisp/org/ol-doi.el | 70 ++ lisp/org/ol-eshell.el | 8 +- lisp/org/ol-gnus.el | 4 +- lisp/org/ol-info.el | 6 +- lisp/org/ol-rmail.el | 2 +- lisp/org/ol-w3m.el | 105 ++- lisp/org/ol.el | 154 ++-- lisp/org/org-agenda.el | 1225 +++++++++++++++------------ lisp/org/org-archive.el | 2 +- lisp/org/org-attach-git.el | 33 +- lisp/org/org-attach.el | 93 ++- lisp/org/org-capture.el | 327 ++++---- lisp/org/org-clock.el | 151 ++-- lisp/org/org-colview.el | 38 +- lisp/org/org-compat.el | 343 ++++---- lisp/org/org-crypt.el | 8 +- lisp/org/org-ctags.el | 6 +- lisp/org/org-datetree.el | 6 +- lisp/org/org-duration.el | 6 +- lisp/org/org-element.el | 268 ++++-- lisp/org/org-entities.el | 4 +- lisp/org/org-faces.el | 74 +- lisp/org/org-feed.el | 2 +- lisp/org/org-footnote.el | 10 +- lisp/org/org-goto.el | 10 +- lisp/org/org-habit.el | 2 +- lisp/org/org-id.el | 174 ++-- lisp/org/org-indent.el | 51 +- lisp/org/org-inlinetask.el | 26 +- lisp/org/org-keys.el | 106 ++- lisp/org/org-lint.el | 102 ++- lisp/org/org-list.el | 335 ++++---- lisp/org/org-macro.el | 131 +-- lisp/org/org-macs.el | 78 +- lisp/org/org-mobile.el | 2 +- lisp/org/org-mouse.el | 170 ++-- lisp/org/org-num.el | 7 +- lisp/org/org-pcomplete.el | 7 +- lisp/org/org-plot.el | 624 +++++++++++--- lisp/org/org-protocol.el | 58 +- lisp/org/org-refile.el | 42 +- lisp/org/org-src.el | 89 +- lisp/org/org-table.el | 317 ++++--- lisp/org/org-timer.el | 2 +- lisp/org/org-version.el | 4 +- lisp/org/org.el | 1372 +++++++++++++++++------------- lisp/org/ox-ascii.el | 65 +- lisp/org/ox-beamer.el | 65 +- lisp/org/ox-html.el | 371 +++++---- lisp/org/ox-icalendar.el | 10 +- lisp/org/ox-koma-letter.el | 1013 +++++++++++++++++++++++ lisp/org/ox-latex.el | 257 +++--- lisp/org/ox-man.el | 32 +- lisp/org/ox-md.el | 53 +- lisp/org/ox-odt.el | 80 +- lisp/org/ox-org.el | 19 +- lisp/org/ox-publish.el | 60 +- lisp/org/ox-texinfo.el | 111 ++- lisp/org/ox.el | 474 ++++++----- 120 files changed, 12488 insertions(+), 5421 deletions(-) delete mode 100644 lisp/org/ob-J.el delete mode 100644 lisp/org/ob-abc.el delete mode 100644 lisp/org/ob-asymptote.el delete mode 100644 lisp/org/ob-coq.el delete mode 100644 lisp/org/ob-ebnf.el delete mode 100644 lisp/org/ob-hledger.el delete mode 100644 lisp/org/ob-io.el create mode 100644 lisp/org/ob-julia.el delete mode 100644 lisp/org/ob-ledger.el delete mode 100644 lisp/org/ob-mscgen.el delete mode 100644 lisp/org/ob-picolisp.el delete mode 100644 lisp/org/ob-shen.el delete mode 100644 lisp/org/ob-stan.el delete mode 100644 lisp/org/ob-vala.el create mode 100644 lisp/org/oc-basic.el create mode 100644 lisp/org/oc-biblatex.el create mode 100644 lisp/org/oc-csl.el create mode 100644 lisp/org/oc-natbib.el create mode 100644 lisp/org/oc.el create mode 100644 lisp/org/ol-doi.el create mode 100644 lisp/org/ox-koma-letter.el diff --git a/doc/misc/org.org b/doc/misc/org.org index f072b5e00e0..7b1277c7a2e 100644 --- a/doc/misc/org.org +++ b/doc/misc/org.org @@ -82,11 +82,8 @@ probably do not need to install it. Most users will simply activate Org and begin exploring its many features. If, for one reason or another, you want to install Org on top of this -pre-packaged version, there are three ways to do it: - -- by using the Emacs package system; -- by downloading Org as an archive; or -- by using Org's git repository. +pre-packaged version, you can use the Emacs package system or clone +Org's git repository. We *strongly recommend* sticking to a single installation method. @@ -106,32 +103,6 @@ visited, i.e., where no Org built-in function have been loaded. Otherwise autoload Org functions will mess up the installation. #+end_quote -If you want to use Org's package repository, check out the [[https://orgmode.org/elpa.html][Org ELPA -page]]. - -*** Downloading Org as an archive -:PROPERTIES: -:UNNUMBERED: notoc -:END: - -You can download Org latest release from [[https://orgmode.org/][Org's website]]. In this case, -make sure you set the load path correctly in your Emacs init file: - -#+begin_src emacs-lisp -(add-to-list 'load-path "~/path/to/orgdir/lisp") -#+end_src - -The downloaded archive contains contributed libraries that are not -included in Emacs. If you want to use them, add the =contrib/= -directory to your load path: - -#+begin_src emacs-lisp -(add-to-list 'load-path "~/path/to/orgdir/contrib/lisp" t) -#+end_src - -Optionally, you can compile the files and/or install them in your -system. Run =make help= to list compilation and installation options. - *** Using Org's git repository :PROPERTIES: :UNNUMBERED: notoc @@ -141,7 +112,7 @@ You can clone Org's repository and install Org like this: #+begin_example $ cd ~/src/ -$ git clone https://code.orgmode.org/bzg/org-mode.git +$ git clone https://git.savannah.gnu.org/git/emacs/org-mode.git $ cd org-mode/ $ make autoloads #+end_example @@ -161,6 +132,16 @@ list of compilation/installation options. For more detailed explanations on Org's build system, please check the Org Build System page on [[https://orgmode.org/worg/dev/org-build-system.html][Worg]]. +*** Installing Org's contributed packages +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +Org's repository used to contain =contrib/= directory for add-ons +contributed by others. As of Org 9.5, the directory has bee moved to +this new dedicated [[https://git.sr.ht/~bzg/org-contrib][org-contrib]] repository, which you can install +separately. + ** Activation :PROPERTIES: :DESCRIPTION: How to activate Org for certain buffers. @@ -189,9 +170,9 @@ to globally available keys, like the ones reserved for users (see please modify the keys to your own liking. #+begin_src emacs-lisp -(global-set-key (kbd "C-c l") 'org-store-link) -(global-set-key (kbd "C-c a") 'org-agenda) -(global-set-key (kbd "C-c c") 'org-capture) +(global-set-key (kbd "C-c l") #'org-store-link) +(global-set-key (kbd "C-c a") #'org-agenda) +(global-set-key (kbd "C-c c") #'org-capture) #+end_src #+cindex: Org mode, turning on @@ -273,7 +254,6 @@ shown below. ;; Add latest Org mode to load path. (add-to-list 'load-path (expand-file-name "/path/to/org-mode/lisp")) -(add-to-list 'load-path (expand-file-name "/path/to/org-mode/contrib/lisp" t)) #+end_src If an error occurs, a "backtrace" can be very useful---see below on @@ -344,7 +324,7 @@ conventions: - =boss=, =ARCHIVE= :: - Tags are case-sensitive. User-defined tags are written in + Tags are case-sensitive. User-defined tags are usually written in lowercase; built-in tags with special meaning are written as they should appear in the document, usually with all capitals. @@ -577,6 +557,10 @@ buffer: ,#+STARTUP: overview ,#+STARTUP: content ,#+STARTUP: showall +,#+STARTUP: show2levels +,#+STARTUP: show3levels +,#+STARTUP: show4levels +,#+STARTUP: show5levels ,#+STARTUP: showeverything #+end_example @@ -656,10 +640,10 @@ The following commands jump to other headlines in the buffer. where you can use the following keys to find your destination: #+attr_texinfo: :columns 0.3 0.7 - | {{{kbd(TAB)}}} | Cycle visibility. | + | {{{kbd(TAB)}}} | Cycle visibility. | | {{{kbd(DOWN)}}} / {{{kbd(UP)}}} | Next/previous visible headline. | - | {{{kbd(RET)}}} | Select this location. | - | {{{kbd(/)}}} | Do a Sparse-tree search | + | {{{kbd(RET)}}} | Select this location. | + | {{{kbd(/)}}} | Do a Sparse-tree search | #+texinfo: @noindent The following keys work if you turn off ~org-goto-auto-isearch~ @@ -667,9 +651,9 @@ The following commands jump to other headlines in the buffer. #+attr_texinfo: :columns 0.3 0.7 | {{{kbd(n)}}} / {{{kbd(p)}}} | Next/previous visible headline. | | {{{kbd(f)}}} / {{{kbd(b)}}} | Next/previous headline same level. | - | {{{kbd(u)}}} | One level up. | + | {{{kbd(u)}}} | One level up. | | {{{kbd(0)}}} ... {{{kbd(9)}}} | Digit argument. | - | {{{kbd(q)}}} | Quit. | + | {{{kbd(q)}}} | Quit. | #+vindex: org-goto-interface #+texinfo: @noindent @@ -932,16 +916,16 @@ commands can be accessed through a dispatcher: #+kindex: C-c / / #+findex: org-occur #+vindex: org-remove-highlights-with-change - Prompts for a regexp and shows a sparse tree with all matches. If - the match is in a headline, the headline is made visible. If the - match is in the body of an entry, headline and body are made - visible. In order to provide minimal context, also the full - hierarchy of headlines above the match is shown, as well as the - headline following the match. Each match is also highlighted; the - highlights disappear when the buffer is changed by an editing - command, or by pressing {{{kbd(C-c C-c)}}}[fn:8]. When called with - a {{{kbd(C-u)}}} prefix argument, previous highlights are kept, so - several calls to this command can be stacked. + Prompts for a regexp (see [[*Regular Expressions]]) and shows a sparse + tree with all matches. If the match is in a headline, the headline + is made visible. If the match is in the body of an entry, headline + and body are made visible. In order to provide minimal context, + also the full hierarchy of headlines above the match is shown, as + well as the headline following the match. Each match is also + highlighted; the highlights disappear when the buffer is changed by + an editing command, or by pressing {{{kbd(C-c C-c)}}}[fn:8]. When + called with a {{{kbd(C-u)}}} prefix argument, previous highlights + are kept, so several calls to this command can be stacked. - {{{kbd(M-g n)}}} or {{{kbd(M-g M-n)}}} (~next-error~) :: @@ -1805,7 +1789,7 @@ mode with {{{kbd(M-x orgtbl-mode)}}}. To turn it on by default, for example in Message mode, use #+begin_src emacs-lisp -(add-hook 'message-mode-hook 'turn-on-orgtbl) +(add-hook 'message-mode-hook #'turn-on-orgtbl) #+end_src Furthermore, with some special setup, it is possible to maintain @@ -2074,6 +2058,14 @@ variable ~org-calc-default-modes~. Fraction and symbolic modes of Calc. +- =u= :: + + Units simplification mode of Calc. Calc is also a symbolic + calculator and is capable of working with values having a unit, + represented with numerals followed by a unit string in Org table + cells. This mode instructs Calc to simplify the units in the + computed expression before returning the result. + - =T=, =t=, =U= :: Duration computations in Calc or Lisp, [[*Durations and time values]]. @@ -2169,38 +2161,54 @@ It is also possible to write a formula in Emacs Lisp. This can be useful for string manipulation and control structures, if Calc's functionality is not enough. -If a formula starts with a single-quote followed by an opening -parenthesis, then it is evaluated as a Lisp form. The evaluation -should return either a string or a number. Just as with Calc -formulas, you can specify modes and a ~printf~ format after -a semicolon. +A formula is evaluated as a Lisp form when it starts with a +single-quote followed by an opening parenthesis. Cell table +references are interpolated into the Lisp form before execution. The +evaluation should return either a string or a number. Evaluation +modes and a ~printf~ format used to render the returned values can be +specified after a semicolon. -With Emacs Lisp forms, you need to be conscious about the way field -references are interpolated into the form. By default, a reference is -interpolated as a Lisp string (in double-quotes) containing the field. -If you provide the =N= mode switch, all referenced elements are -numbers---non-number fields will be zero---and interpolated as Lisp -numbers, without quotes. If you provide the =L= flag, all fields are -interpolated literally, without quotes. For example, if you want a -reference to be interpreted as a string by the Lisp form, enclose the -reference operator itself in double-quotes, like ="$3"=. Ranges are -inserted as space-separated fields, so you can embed them in list or -vector syntax. +By default, references are interpolated as literal Lisp strings: the +field content is replaced in the Lisp form stripped of leading and +trailing white space and surrounded in double-quotes. For example: -Here are a few examples---note how the =N= mode is used when we do -computations in Lisp: +: '(concat $1 $2) -- ='(concat (substring $1 1 2) (substring $1 0 1) (substring $1 2))= :: +#+texinfo: @noindent +concatenates the content of columns 1 and column 2. + +When the =N= flag is used, all referenced elements are parsed as +numbers and interpolated as Lisp numbers, without quotes. Fields that +cannot be parsed as numbers are interpolated as zeros. For example: - Swap the first two characters of the content of column 1. +: '(+ $1 $2);N -- ='(+ $1 $2);N= :: +#+texinfo: @noindent +adds columns 1 and 2, equivalent to Calc's =$1+$2=. Ranges are +inserted as space-separated fields, so they can be embedded in list or +vector syntax. For example: - Add columns 1 and 2, equivalent to Calc's =$1+$2=. +: '(apply '+ '($1..$4));N -- ='(apply '+ '($1..$4));N= :: +#+texinfo: @noindent +computes the sum of columns 1 to 4, like Calc's =vsum($1..$4)=. + +When the =L= flag is used, all fields are interpolated literally: the +cell content is replaced in the Lisp form stripped of leading and +trailing white space and without quotes. If a reference is intended +to be interpreted as a string by the Lisp form, the reference operator +itself should be enclosed in double-quotes, like ="$3"=. The =L= flag +is useful when strings and numbers are used in the same Lisp form. For +example: - Compute the sum of columns 1 to 4, like Calc's =vsum($1..$4)=. +: '(substring "$1" $2 $3);L + +#+texinfo: @noindent +extracts the part of the string in column 1 between the character +positions specified in the integers in column 2 and 3 and it is easier +to read than the equivalent: + +: '(substring $1 (string-to-number $2) (string-to-number $3)) *** Durations and time values :PROPERTIES: @@ -2797,7 +2805,7 @@ either graphically or in ASCII art. #+cindex: @samp{PLOT}, keyword Org Plot can produce 2D and 3D graphs of information stored in Org -tables using [[http://www.gnuplot.info/][Gnuplot]] and [[http://cars9.uchicago.edu/~ravel/software/gnuplot-mode.html][Gnuplot mode]]. To see this in action, ensure +tables using [[https://www.gnuplot.info/][Gnuplot]] and [[http://cars9.uchicago.edu/~ravel/software/gnuplot-mode.html][Gnuplot mode]]. To see this in action, ensure that you have both Gnuplot and Gnuplot mode installed on your system, then call {{{kbd(C-c \quot g)}}} or {{{kbd(M-x org-plot/gnuplot)}}} on the following table. @@ -2813,6 +2821,19 @@ following table. | Morelia | 257.56 | 17.67 | #+end_example +Org Plot supports a range of plot types, and provides the ability to add more. +For example, a radar plot can be generated like so: +#+begin_example +,#+PLOT: title:"An evaluation of plaintext document formats" transpose:yes type:radar min:0 max:4 +| Format | Fine-grained-control | Initial Effort | Syntax simplicity | Editor Support | Integrations | Ease-of-referencing | Versatility | +|-------------------+----------------------+----------------+-------------------+----------------+--------------+---------------------+-------------| +| Word | 2 | 4 | 4 | 2 | 3 | 2 | 2 | +| LaTeX | 4 | 1 | 1 | 3 | 2 | 4 | 3 | +| Org Mode | 4 | 2 | 3.5 | 1 | 4 | 4 | 4 | +| Markdown | 1 | 3 | 3 | 4 | 3 | 3 | 1 | +| Markdown + Pandoc | 2.5 | 2.5 | 2.5 | 3 | 3 | 3 | 2 | +#+end_example + Notice that Org Plot is smart enough to apply the table's headers as labels. Further control over the labels, type, content, and appearance of plots can be exercised through the =PLOT= keyword @@ -2843,9 +2864,15 @@ For more information and examples see the [[https://orgmode.org/worg/org-tutoria the third and fourth columns. Defaults to graphing all other columns aside from the =ind= column. +- transpose :: + + When =y=, =yes=, or =t= attempt to transpose the table data before + plotting. Also recognises the shorthand option =trans=. + - =type= :: - Specify whether the plot is =2d=, =3d=, or =grid=. + Specify the type of the plot, by default one of =2d=, =3d=, =radar=, or =grid=. + Available types can be customised with ~org-plot/preset-plot-types~. - =with= :: @@ -2872,6 +2899,27 @@ For more information and examples see the [[https://orgmode.org/worg/org-tutoria When plotting =3d= or =grid= types, set this to =t= to graph a flat mapping rather than a =3d= slope. +- min :: + + Provides a minimum axis value that may be used by a plot type. + Implicitly assumes the =y= axis is being referred to. Can + explicitly provide a value for a either the =x= or =y= axis with + =xmin= and =ymin=. + +- max :: + + Provides a maximum axis value that may be used by a plot type. + Implicitly assumes the =y= axis is being referred to. Can + explicitly provide a value for a either the =x= or =y= axis with + =xmax= and =ymax=. + +- ticks :: + + Provides a desired number of axis ticks to display, that may be used + by a plot type. If none is given a plot type that requires ticks + will use ~org--plot/sensible-tick-num~ to try to determine a good + value. + - =timefmt= :: Specify format of Org mode timestamps as they will be parsed by @@ -3113,14 +3161,14 @@ Here is the full set of built-in link types: - =file= :: - File links. File name may be remote, absolute, or relative. + File links. File name may be remote, absolute, or relative. - Additionally, you can specify a line number, or a text search. - In Org files, you may link to a headline name, a custom ID, or a - code reference instead. + Additionally, you can specify a line number, or a text search. + In Org files, you may link to a headline name, a custom ID, or a + code reference instead. - As a special case, "file" prefix may be omitted if the file name - is complete, e.g., it starts with =./=, or =/=. + As a special case, "file" prefix may be omitted if the file name + is complete, e.g., it starts with =./=, or =/=. - =attachment= :: @@ -3224,9 +3272,10 @@ options: #+cindex: VM links #+cindex: Wanderlust links On top of these built-in link types, additional ones are available -through the =contrib/= directory (see [[*Installation]]). For example, -these links to VM or Wanderlust messages are available when you load -the corresponding libraries from the =contrib/= directory: +through the =org-contrib= repository (see [[*Installation]]). For +example, these links to VM or Wanderlust messages are available when +you load the corresponding libraries from the =org-contrib= +repository: | =vm:folder= | VM folder link | | =vm:folder#id= | VM message link | @@ -3291,8 +3340,9 @@ current buffer: =ID= property for the link[fn:29]. So using this command in Org buffers potentially creates two links: a human-readable link from the custom ID, and one that is globally unique and works even if the - entry is moved from file to file. Later, when inserting the link, - you need to decide which one to use. + entry is moved from file to file. The =ID= property can be either a + UUID (default) or a timestamp, depending on ~org-id-method~. Later, + when inserting the link, you need to decide which one to use. - /Email/News clients: VM, Rmail, Wanderlust, MH-E, Gnus/ :: @@ -3474,8 +3524,8 @@ generally, act on links. #+begin_src emacs-lisp (with-eval-after-load 'org - (define-key org-mode-map (kbd "M-n") 'org-next-link) - (define-key org-mode-map (kbd "M-p") 'org-previous-link)) + (define-key org-mode-map (kbd "M-n") #'org-next-link) + (define-key org-mode-map (kbd "M-p") #'org-previous-link)) #+end_src ** Using Links Outside Org @@ -3516,7 +3566,7 @@ replacement text. Here is an example: #+begin_src emacs-lisp (setq org-link-abbrev-alist '(("bugzilla" . "http://10.1.2.9/bugzilla/show_bug.cgi?id=") - ("Nu Html Checker" . "https://validator.w3.org/nu/?doc=%h") + ("Nu Html Checker" . "https://validator.w3.org/nu/?doc=%h") ("duckduckgo" . "https://duckduckgo.com/?q=%s") ("omap" . "http://nominatim.openstreetmap.org/search?q=%s&polygon=1") ("ads" . "https://ui.adsabs.harvard.edu/search/q=%20author%3A\"%s\""))) @@ -3616,10 +3666,10 @@ link, together with explanations for each: - =/REGEXP/= :: - Do a regular expression search for {{{var(REGEXP)}}}. This uses the - Emacs command ~occur~ to list all matches in a separate window. If - the target file is in Org mode, ~org-occur~ is used to create - a sparse tree with the matches. + Do a regular expression search for {{{var(REGEXP)}}} (see [[*Regular + Expressions]]). This uses the Emacs command ~occur~ to list all + matches in a separate window. If the target file is in Org mode, + ~org-occur~ is used to create a sparse tree with the matches. As a degenerate case, a file link with an empty file name can be used to search the current file. For example, =[[file:::find me]]= does @@ -3944,9 +3994,9 @@ interpretation, but it means the same as =#+TODO=, or A setup for using several sets in parallel would be: #+begin_example -,#+TODO: TODO | DONE -,#+TODO: REPORT BUG KNOWNCAUSE | FIXED -,#+TODO: | CANCELED +,#+TODO: TODO(t) | DONE(d) +,#+TODO: REPORT(r) BUG(b) KNOWNCAUSE(k) | FIXED(f) +,#+TODO: | CANCELED(c) #+end_example #+cindex: completion, of option keywords @@ -4070,7 +4120,7 @@ checkboxes is blocked from switching to DONE. If you need more complex dependency structures, for example dependencies between entries in different trees or files, check out -the contributed module =org-depend.el=. +the module =org-depend.el= in the =org-contrib= repository. ** Progress Logging :PROPERTIES: @@ -4158,10 +4208,6 @@ example, with the setting '((sequence "TODO(t)" "WAIT(w@/!)" "|" "DONE(d!)" "CANCELED(c@)"))) #+end_src -#+texinfo: @noindent -To record a timestamp without a note for TODO keywords configured with -=@=, just type {{{kbd(C-c C-c)}}} to enter a blank note when prompted. - #+vindex: org-log-done You not only define global TODO keywords and fast access keys, but also request that a time is recorded when the entry is set to =DONE=, @@ -4181,6 +4227,9 @@ to a buffer: : #+TODO: TODO(t) WAIT(w@/!) | DONE(d!) CANCELED(c@) +To record a timestamp without a note for TODO keywords configured with +=@=, just type {{{kbd(C-c C-c)}}} to enter a blank note when prompted. + #+cindex: @samp{LOGGING}, property In order to define logging settings that are local to a subtree or a single item, define a =LOGGING= property in this entry. Any @@ -4443,7 +4492,7 @@ all children are done, you can use the following setup: (let (org-log-done org-log-states) ; turn off logging (org-todo (if (= n-not-done 0) "DONE" "TODO")))) -(add-hook 'org-after-todo-statistics-hook 'org-summary-todo) +(add-hook 'org-after-todo-statistics-hook #'org-summary-todo) #+end_src Another possibility is the use of checkboxes to identify (a hierarchy @@ -4794,9 +4843,10 @@ In this interface, you can also use the following special keys: #+kindex: TAB Enter a tag in the minibuffer, even if the tag is not in the - predefined list. You can complete on all tags present in the - buffer. You can also add several tags: just separate them with - a comma. + predefined list. You can complete on all tags present in the buffer + and globally pre-defined tags from ~org-tag-alist~ and + ~org-tag-persistent-alist~. You can also add several tags: just + separate them with a comma. - {{{kbd(SPC)}}} :: @@ -4931,8 +4981,9 @@ mutually exclusive. Furthermore, the members of a group tag can also be regular expressions, creating the possibility of a more dynamic and rule-based -tag structure. The regular expressions in the group must be specified -within curly brackets. Here is an expanded example: +tag structure (see [[*Regular Expressions]]). The regular expressions in +the group must be specified within curly brackets. Here is an +expanded example: #+begin_example ,#+TAGS: [ Vision : {V@.+} ] @@ -5274,7 +5325,7 @@ single property: tree is created with all entries that define this property with the given value. If you enclose the value in curly braces, it is interpreted as a regular expression and matched against the property - values. + values (see [[*Regular Expressions]]). ** Property Inheritance :PROPERTIES: @@ -5737,8 +5788,8 @@ block. If there is a =TBLFM= keyword after the table, the table is recalculated automatically after an update. An alternative way to capture and process property values into a table -is provided by Eric Schulte's =org-collector.el=, which is -a contributed package[fn:58]. It provides a general API to collect +is provided by Eric Schulte's =org-collector.el=, which is a package +in =org-contrib=[fn:58]. It provides a general API to collect properties from entries in a certain scope, and arbitrary Lisp expressions to process these values before inserting them into a table or a dynamic block. @@ -6022,6 +6073,7 @@ dash(es) as the separator in the former case and use =+= as the separator in the latter case, e.g.: | =11am-1:15pm= | \rArr{} 11:00-13:15 | +| =11h-13h15= | \rArr{} same as above | | =11am--1:15pm= | \rArr{} same as above | | =11am+2:15= | \rArr{} same as above | @@ -7197,6 +7249,16 @@ special command: Copying works like refiling, except that the original note is not deleted. +- {{{kbd(C-c C-M-w)}}} (~org-refile-reverse~) :: + + #+kindex: C-c C-M-w + #+findex: org-refile-reverse + Works like refiling, except that it temporarily toggles how the + value of ~org-reverse-note-order~ applies to the current buffer. So + if ~org-refile~ would append the entry as the last entry under the + target header, ~org-refile-reverse~ will prepend it as the first + entry, and vice-versa. + ** Archiving :PROPERTIES: :DESCRIPTION: What to do with finished products. @@ -7746,6 +7808,9 @@ Now lets look at the elements of a template definition. Each entry in Do not save the target file after finishing the capture. + - ~:refile-targets :: Temporarily set ~org-refile-targets~ to the + value of this property. + **** Template expansion :PROPERTIES: :DESCRIPTION: Filling in information about time and context. @@ -7804,6 +7869,10 @@ here: Like =%a=, but only insert the literal link. +- =%L= :: + + Like =%l=, but without brackets (the link content itself). + - =%c= :: Current kill ring head. @@ -7859,7 +7928,8 @@ here: - =%^{PROP}p= :: - Prompt the user for a value for property {{{var(PROP)}}}. + Prompt the user for a value for property {{{var(PROP)}}}. You may + specify a default value with =%^{PROP|default}=. - =%^{PROMPT}= :: @@ -8199,7 +8269,7 @@ To make Org mode take care of versioning of attachments for you, add the following to your Emacs config: #+begin_src emacs-lisp - (require 'org-attach-git) +(require 'org-attach-git) #+end_src *** Attach from Dired @@ -8259,7 +8329,7 @@ variable has detailed information. With the following #+begin_src emacs-lisp (setq org-feed-alist '(("Slashdot" - "http://rss.slashdot.org/Slashdot/slashdot" + "https://rss.slashdot.org/Slashdot/slashdot" "~/txt/org/feeds.org" "Slashdot Entries"))) #+end_src @@ -8847,8 +8917,9 @@ only tags. #+cindex: regular expressions, with tags search Instead of a tag, you may also specify a regular expression enclosed -in curly braces. For example, =work+{^boss.*}= matches headlines that -contain the tag =:work:= and any tag /starting/ with =boss=. +in curly braces (see [[*Regular Expressions]]). For example, +=work+{^boss.*}= matches headlines that contain the tag =:work:= and +any tag /starting/ with =boss=. #+cindex: group tags, as regular expressions Group tags (see [[*Tag Hierarchy]]) are expanded as regular expressions. @@ -8888,7 +8959,7 @@ to test the value of a property. Here is a complex example: #+begin_example +work-boss+PRIORITY="A"+Coffee="unlimited"+Effort<2 - +With={Sarah|Denny}+SCHEDULED>="<2008-10-11>" + +With={Sarah\|Denny}+SCHEDULED>="<2008-10-11>" #+end_example #+texinfo: @noindent @@ -8918,7 +8989,7 @@ So the search string in the example finds entries tagged =work= but not =boss=, which also have a priority value =A=, a =Coffee= property with the value =unlimited=, an =EFFORT= property that is numerically smaller than 2, a =With= property that is matched by the regular -expression =Sarah|Denny=, and that are scheduled on or after October +expression =Sarah\|Denny=, and that are scheduled on or after October 11, 2008. You can configure Org mode to use property inheritance during @@ -9296,16 +9367,16 @@ filter elements are accumulated. selects entries with category =work= and effort estimates below 10 minutes, and deselects entries with tag =John= or matching the - regexp =plot=. You can leave =+= out if that does not lead to - ambiguities. The sequence of elements is arbitrary. The filter - syntax assumes that there is no overlap between categories and tags. - Otherwise, tags take priority. If you reply to the prompt with the - empty string, all filtering is removed. If a filter is specified, - it replaces all current filters. But if you call the command with - a double prefix argument, or if you add an additional =+= (e.g., - =++work=) to the front of the string, the new filter elements are - added to the active ones. A single prefix argument applies the - entire filter in a negative sense. + regexp =plot= (see [[*Regular Expressions]]). You can leave =+= out if + that does not lead to ambiguities. The sequence of elements is + arbitrary. The filter syntax assumes that there is no overlap + between categories and tags. Otherwise, tags take priority. If you + reply to the prompt with the empty string, all filtering is removed. + If a filter is specified, it replaces all current filters. But if + you call the command with a double prefix argument, or if you add an + additional =+= (e.g., =++work=) to the front of the string, the new + filter elements are added to the active ones. A single prefix + argument applies the entire filter in a negative sense. - {{{kbd(|)}}} (~org-agenda-filter-remove-all~) :: @@ -10863,7 +10934,7 @@ pretty output for a number of export back-ends. Org mode can contain LaTeX math fragments, and it supports ways to process these for several export back-ends. When exporting to LaTeX, the code is left as it is. When exporting to HTML, Org can use either -[[http://www.mathjax.org][MathJax]] (see [[*Math formatting in HTML export]]) or transcode the math +[[https://www.mathjax.org][MathJax]] (see [[*Math formatting in HTML export]]) or transcode the math into images (see [[*Previewing LaTeX fragments]]). LaTeX fragments do not need any special marking at all. The following @@ -10968,7 +11039,7 @@ current buffer with {{{kbd(M-x org-cdlatex-mode)}}}, or for all Org files with #+begin_src emacs-lisp -(add-hook 'org-mode-hook 'turn-on-org-cdlatex) +(add-hook 'org-mode-hook #'turn-on-org-cdlatex) #+end_src When this mode is enabled, the following features are present (for @@ -11304,7 +11375,7 @@ The following command handles footnotes: #+attr_texinfo: :columns 0.1 0.9 | {{{kbd(s)}}} | Sort the footnote definitions by reference sequence. | | {{{kbd(r)}}} | Renumber the simple =fn:N= footnotes. | - | {{{kbd(S)}}} | Short for first {{{kbd(r)}}}, then {{{kbd(s)}}} action. | + | {{{kbd(S)}}} | Short for first {{{kbd(r)}}}, then {{{kbd(s)}}} action. | | {{{kbd(n)}}} | Rename all footnotes into a =fn:1= ... =fn:n= sequence. | | {{{kbd(d)}}} | Delete the footnote at point, including definition and references. | @@ -11361,7 +11432,7 @@ Users can install libraries for additional formats from the Emacs packaging system. For easy discovery, these packages have a common naming scheme: ~ox-NAME~, where {{{var(NAME)}}} is a format. For example, ~ox-koma-letter~ for /koma-letter/ back-end. More libraries -can be found in the =contrib/= directory (see [[*Installation]]). +can be found in the =org-contrib= repository (see [[*Installation]]). #+vindex: org-export-backends Org only loads back-ends for the following formats by default: ASCII, @@ -11452,7 +11523,7 @@ further alter what is exported, and how. Toggle visible-only export. This is useful for exporting only certain parts of an Org document by adjusting the visibility of - particular headings. + particular headings. See also [[*Sparse Trees]]. ** Export Settings :PROPERTIES: @@ -11961,7 +12032,7 @@ example #+texinfo: @noindent becomes -: Rose is red, violet's blue. Life's ordered: Org assists you. +: Rose is red, violet's blue. Life's ordered: Org assists you. As a special case, Org parses any replacement text starting with =(eval= as an Emacs Lisp expression and evaluates it accordingly. @@ -12527,7 +12598,7 @@ compatible with XHTML 1.0 strict standard. #+findex: org-html-export-to-html Export as HTML file with a =.html= extension. For =myfile.org=, Org - exports to =myfile.html=, overwriting without warning. {{{kbd{C-c + exports to =myfile.html=, overwriting without warning. {{{kbd(C-c C-e h o)}}} exports to HTML and opens it in a web browser. - {{{kbd(C-c C-e h H)}}} (~org-html-export-as-html~) :: @@ -12552,6 +12623,9 @@ settings described in [[*Export Settings]]. multiple =DESCRIPTION= lines. The exporter takes care of wrapping the lines properly. + The exporter includes a number of other meta tags, which can be customized + by modifying ~org-html-meta-tags~. + - =HTML_DOCTYPE= :: #+cindex: @samp{HTML_DOCTYPE}, keyword @@ -12693,8 +12767,8 @@ exports to: #+begin_src html #+end_src @@ -12925,7 +12999,7 @@ as-is. #+vindex: org-html-mathjax-options~ LaTeX math snippets (see [[*LaTeX fragments]]) can be displayed in two -different ways on HTML pages. The default is to use the [[http://www.mathjax.org][MathJax]], +different ways on HTML pages. The default is to use the [[https://www.mathjax.org][MathJax]], which should work out of the box with Org[fn:129][fn:130]. Some MathJax display options can be configured via ~org-html-mathjax-options~, or in the buffer. For example, with the following settings, @@ -13621,7 +13695,7 @@ placement. #+cindex: image, centering in LaTeX export The LaTeX export back-end centers all images by default. Setting =:center= to =nil= disables centering. To disable centering globally, -set ~org-latex-images-centered~ to =t=. +set ~org-latex-images-centered~ to =nil=. Set the =:comment-include= attribute to non-~nil~ value for the LaTeX export back-end to comment out the =\includegraphics= macro. @@ -13698,7 +13772,7 @@ objects through the attributes =:float= and =:options=. For =:float=: The LaTeX export back-end passes string values in =:options= to LaTeX packages for customization of that specific source block. In the example below, the =:options= are set for Minted. Minted is a source -code highlighting LaTeX package with many configurable options. +code highlighting LaTeX package with many configurable options[fn:134]. #+begin_example ,#+ATTR_LATEX: :options commentstyle=\bfseries @@ -13801,6 +13875,95 @@ The LaTeX export back-end converts horizontal rules by the specified ----- #+end_example +*** Verse blocks in LaTeX export +:PROPERTIES: +:DESCRIPTION: Attributes specific to special blocks. +:END: + +#+cindex: verse blocks, in @LaTeX{} export +#+cindex: @samp{ATTR_LATEX}, keyword + +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. + +- =:lines= :: To add marginal verse numbering. Its value is an + integer, the sequence in which the verses should be numbered. +- =:center= :: With value =t= all the verses on the page are optically + centered (a typographic convention for poetry), taking as a + reference the longest verse, which must be indicated by the + attribute =:versewidth=. +- =:versewidth= :: Its value is a literal text string with the longest + verse. +- =:latexcode= :: It accepts any arbitrary LaTeX code that can be + included within a LaTeX =verse= environment. + +A complete example with Shakespeare's first sonnet: + +#+begin_src org +,#+ATTR_LATEX: :center t :latexcode \color{red} :lines 5 +,#+ATTR_LATEX: :versewidth Feed’st thy light’s flame with self-substantial fuel, +,#+BEGIN_VERSE +From fairest creatures we desire increase, +That thereby beauty’s rose might never die, +But as the riper should by time decease +His tender heir might bear his memory +But thou, contracted to thine own bright eyes, +Feed’st thy light’s flame with self-substantial fuel, +Making a famine where abundance lies, +Thyself thy foe, to thy sweet self too cruel. +Thou that art now the world’s fresh ornament, +And only herald to the gaudy spring, +Within thine own bud buriest thy content, +And, tender churl, mak’st waste in niggardly. +Pity the world, or else this glutton be, +To eat the world’s due, by the grave and thee. +,#+END_VERSE +#+end_src + +*** Quote blocks in LaTeX export +:PROPERTIES: +:DESCRIPTION: Attributes specific to quote blocks. +:END: + +#+cindex: quote blocks, in @LaTeX{} export +#+cindex: @samp{ATTR_LATEX}, keyword +#+cindex: org-latex-default-quote-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=. For example, to choose the environment =quotation=, +included as an alternative to =quote= in standard LaTeX classes: + +#+begin_example +,#+ATTR_LATEX: :environment quotation +,#+BEGIN_QUOTE +some text... +,#+END_QUOTE +#+end_example + +To choose the =foreigndisplayquote= environment, included in the LaTeX +package =csquotes=, with the =german= option, use this syntax: + +#+begin_example +,#+LATEX_HEADER:\usepackage[autostyle=true]{csquotes} +,#+ATTR_LATEX: :environment foreigndisplayquote :options {german} +,#+BEGIN_QUOTE +some text in German... +,#+END_QUOTE +#+end_example + +#+texinfo: @noindent +which is exported to LaTeX as + +#+begin_example +\begin{foreigndisplayquote}{german} +some text in German... +\end{foreigndisplayquote} +#+end_example + ** Markdown Export :PROPERTIES: :DESCRIPTION: Exporting to Markdown. @@ -13860,7 +14023,7 @@ a limit to a level before the absolute limit (see [[*Export Settings]]). The ODT export back-end handles creating of OpenDocument Text (ODT) format. Documents created by this exporter use the -{{{cite(OpenDocument-v1.2 specification)}}}[fn:134] and are compatible +{{{cite(OpenDocument-v1.2 specification)}}}[fn:135] and are compatible with LibreOffice 3.4. *** Pre-requisites for ODT export @@ -14261,7 +14424,7 @@ document in one of the following ways: variables ~org-latex-to-mathml-convert-command~ and ~org-latex-to-mathml-jar-file~. - If you prefer to use MathToWeb[fn:135] as your converter, you can + If you prefer to use MathToWeb[fn:136] as your converter, you can configure the above variables as shown below. #+begin_src emacs-lisp @@ -14272,7 +14435,7 @@ document in one of the following ways: #+end_src #+texinfo: @noindent - or, to use LaTeX​ML[fn:136] instead, + or, to use LaTeX​ML[fn:137] instead, #+begin_src emacs-lisp (setq org-latex-to-mathml-convert-command @@ -14591,7 +14754,7 @@ with the =#+ATTR_ODT= line. For a discussion on default formatting of tables, see [[*Tables in ODT export]]. This feature closely mimics the way table templates are defined in the -OpenDocument-v1.2 specification[fn:137]. +OpenDocument-v1.2 specification[fn:138]. #+vindex: org-odt-table-styles For quick preview of this feature, install the settings below and export the @@ -14625,7 +14788,7 @@ templates, define new styles there. To use this feature proceed as follows: -1. Create a table template[fn:138]. +1. Create a table template[fn:139]. A table template is set of =table-cell= and =paragraph= styles for each of the following table cell categories: @@ -14664,7 +14827,7 @@ To use this feature proceed as follows: == element of the content template file (see [[x-orgodtcontenttemplate-xml][Factory styles]]). -2. Define a table style[fn:139]. +2. Define a table style[fn:140]. #+vindex: org-odt-table-styles To define a table style, create an entry for the style in the @@ -15159,7 +15322,7 @@ To specify the author of the quotation, use the =:author= attribute. ,#+BEGIN_QUOTE The Lady of the Lake, her arm clad in the purest shimmering samite, held aloft Excalibur from the bosom of the water, signifying by divine -providence that I, Arthur, was to carry Excalibur. That is why I am +providence that I, Arthur, was to carry Excalibur. That is why I am your king. ,#+END_QUOTE #+end_example @@ -15422,7 +15585,7 @@ BACKEND is the export back-end being used, as a symbol." (org-map-entries (lambda () (delete-region (point) (line-beginning-position 2))))) -(add-hook 'org-export-before-parsing-hook 'my-headline-removal) +(add-hook 'org-export-before-parsing-hook #'my-headline-removal) #+end_src *** Filters @@ -15768,17 +15931,17 @@ following properties Publishing means that a file is copied to the destination directory and possibly transformed in the process. The default transformation is to export Org files as HTML files, and this is done by the function -~org-publish-org-to-html~ which calls the HTML exporter (see [[*HTML +~org-html-publish-to-html~ which calls the HTML exporter (see [[*HTML Export]]). But you can also publish your content as PDF files using -~org-publish-org-to-pdf~, or as ASCII, Texinfo, etc., using the +~org-latex-publish-to-pdf~, or as ASCII, Texinfo, etc., using the corresponding functions. If you want to publish the Org file as an =.org= file but with /archived/, /commented/, and /tag-excluded/ trees removed, use -~org-publish-org-to-org~. This produces =file.org= and put it in the +~org-org-publish-to-org~. This produces =file.org= and puts it in the publishing directory. If you want a htmlized version of this file, set the parameter ~:htmlized-source~ to ~t~. It produces -=file.org.html= in the publishing directory[fn:140]. +=file.org.html= in the publishing directory[fn:141]. Other files like images only need to be copied to the publishing destination; for this you can use ~org-publish-attachment~. For @@ -16247,12 +16410,13 @@ directory on the local machine. (setq org-publish-project-alist '(("org" :base-directory "~/org/" + :publishing-function org-html-publish-to-html :publishing-directory "~/public_html" :section-numbers nil - :table-of-contents nil - :style ""))) + :with-toc nil + :html-head ""))) #+end_src *** Example: complex publishing configuration @@ -16347,6 +16511,129 @@ of the commands above, or by customizing the variable particular if files include other files via =SETUPFILE= or =INCLUDE= keywords. +* Citation handling +:PROPERTIES: +:DESCRIPTION: create, follow and export citations. +:END: +#+cindex: citation + +As of Org 9.5, a new library =oc.el= provides tooling to handle +citations in Org via "citation processors" that offer some or all of +the following capabilities: + +- "activate" :: Fontification, tooltip preview, etc. +- "follow" :: At-point actions on citations via ~org-open-at-point~. +- "insert" :: Add and edit citations via ~org-cite-insert~. +- "export" :: Via different libraries for different target formats. + +The user can configure these with ~org-cite-active-processor~, +~org-cite-follow-processor~, ~org-cite-insert-processor~, and +~org-cite-export-processors~ respectively. + +The included "basic" processor provides all four capabilities. + +** Citations + +Before adding citations, first set one-or-more bibliographies, either +globally with ~org-cite-global-bibliography~, or locally using one or +more "bibliography" keywords. + +#+begin_example +#+bibliography: SomeFile.bib +#+bibliography: /some/other/file.json +#+bibliography: "/some/file/with spaces/in its name.bib" +#+end_example + +One can then insert and edit citations using ~org-cite-insert~, called +with {{{kbd(M-x org-cite-insert)}}}. + +A /citation/ requires one or more citation /key(s)/, elements +identifying a reference in the bibliography. + +- Each citation is surrounded by brackets and uses the =cite= type. + +- Each key starts with the character =@=. + +- Each key can be qualified by a /prefix/ (e.g. "see ") and/or a + /suffix/ (e.g. "p. 123"), giving informations useful or necessary fo + the comprehension of the citation but not included in the reference. + +- A single citation can cite more than one reference ; the keys are + separated by semicolons ; the formatting of such citation groups is + specified by the style. + +- One can also specify a stylistic variation for the citations by + inserting a =/= and a style name between the =cite= keyword and the + colon ; this usially makes sense only for the author-year styles. + +#+begin_example +[cite/style:common prefix ;prefix @key suffix; ... ; common suffix] +#+end_example + +The only mandatory elements are: + +- The =cite= keyword and the colon. +- The =@= character immediately preceding each key. +- The brackets surrounding the citation(s) (group). + +** Citation export processors + +Org currently includes the following export processors: + +- Two processors can export to a variety of formats, including =latex= + (and therefore =pdf=), =html=, =odt= and plain (UTF8) text: + + - basic :: a basic export processors, well adapted to situations + where backward compatibility is not a requirement and formatting + needs are minimal; + + - csl :: this export processor uses format files written in [[https://en.wikipedia.org/wiki/Citation_Style_Language][Citation + Style Language]] via [[https://github.com/andras-simonyi/citeproc-el][citeproc-el]]; + +- In contrast, two other processors target LaTeX and LaTeX-derived + formats exclusively: + + - natbib :: this export processor uses =bibtex=, the historical + bibliographic processor used with LaTeX, thus allowing the use of + data and style files compatible with this processor (including a + large number of publishers' styles). It uses citation commands + implemented in the LaTeX package =natbib=, allowing more stylistic + variants that LaTeX's =\cite= command. + + - biblatex :: this backend allows the use of data and formats + prepared for =biblatex=, an alternate bibliographic processor used + with LaTeX, which overcomes some serious =bibtex= limitations, but + has not (yet?) been widely adopted by publishers. + +The =#+cite_export:= keyword specifies the export processor and the +citation (and possibly reference) style(s); for example (all arguments +are optional) + +#+begin_example +#+cite_export: basic author author-year +#+end_example + +specifies the "basic" export processor with citations inserted as +author's name and references indexed by author's names and year; + +#+begin_example +#+cite_export: csl /some/path/to/vancouver-brackets.csl +#+end_example + +specifies the "csl" processor and CSL style, which in this case +defines numeric citations and numeric references according to the +=Vancouver= specification (as style used in many medical journals), +following a typesetting variation putting citations between brackets; + +#+begin_example +#+cite_export: natbib kluwer +#+end_example + +specifies the "natbib" export processor with a label citation style +conformant to the Harvard style and the specification of the +Wolkers-Kluwer publisher; since it relies on the =bibtex= processor of +your LaTeX installation, it won't export to anything but PDF. + * Working with Source Code :PROPERTIES: :DESCRIPTION: Export, evaluate, and tangle code blocks. @@ -16393,7 +16680,7 @@ extract, export, and publish source code blocks. Org can also compile and execute a source code block, then capture the results. The Org mode literature sometimes refers to source code blocks as /live code/ blocks because they can alter the content of the Org document or the -material that it exports. Users can control how live they want each +material that it exports. Users can control the "liveliness" of each source code block by tweaking the header arguments (see [[*Using Header Arguments]]) for compiling, execution, extraction, and exporting. @@ -16736,7 +17023,11 @@ the =var= header argument. body. {{{var(ASSIGN)}}} is a literal value, such as a string, a number, a reference to a table, a list, a literal example, another code block---with or without arguments---or the results of evaluating -a code block. +a code block. {{{var(ASSIGN)}}} may specify a filename for references +to elements in a different file, using a =:= to separate the filename +from the reference. + +: :var NAME=FILE:REFERENCE Here are examples of passing values by reference: @@ -16815,6 +17106,9 @@ Here are examples of passing values by reference: | two | 16 | 17 | 18 | 19 | 20 | #+end_example +To refer to a table in another file, join the filename and table name with +a colon, for example: =:var table=other-file.org:example-table=. + - list :: A simple named list. @@ -17156,13 +17450,13 @@ See [[*Languages]] to enable other languages. #+kindex: C-c C-v e #+findex: org-babel-execute-src-block Org provides many ways to execute code blocks. {{{kbd(C-c C-c)}}} or -{{{kbd(C-c C-v e)}}} with the point on a code block[fn:141] calls the +{{{kbd(C-c C-v e)}}} with the point on a code block[fn:142] calls the ~org-babel-execute-src-block~ function, which executes the code in the block, collects the results, and inserts them in the buffer. #+cindex: @samp{CALL}, keyword #+vindex: org-babel-inline-result-wrap -By calling a named code block[fn:142] from an Org mode buffer or +By calling a named code block[fn:143] from an Org mode buffer or a table. Org can call the named code blocks from the current Org mode buffer or from the "Library of Babel" (see [[*Library of Babel]]). @@ -17363,7 +17657,7 @@ they are mutually exclusive. - =value= :: - Default for most Babel libraries[fn:142]. Functional mode. Org + Default for most Babel libraries[fn:143]. Functional mode. Org gets the value by wrapping the code in a function definition in the language of the source block. That is why when using =:results value=, code should execute like a function and return a value. For @@ -17488,10 +17782,12 @@ default behavior is to automatically determine the result type. #+end_example #+cindex: @samp{file-desc}, header argument - The =file-desc= header argument defines the description (see - [[*Link Format]]) for the link. If =file-desc= is present but has no value, + The =file-desc= header argument defines the description (see [[*Link + Format]]) for the link. If =file-desc= is present but has no value, the =file= value is used as the link description. When this - argument is not present, the description is omitted. + argument is not present, the description is omitted. If you want to + provide the =file-desc= argument but omit the description, you can + provide it with an empty vector (i.e., :file-desc []). #+cindex: @samp{sep}, header argument By default, Org assumes that a table written to a file has @@ -17549,7 +17845,7 @@ follows from the type specified above. #+begin_example ,#+begin_src shell :results file link :file "download.tar.gz" - wget -c "http://example.com/download.tar.gz" + wget -c "https://example.com/download.tar.gz" ,#+end_src #+end_example @@ -17595,15 +17891,20 @@ value listed above. E.g., Handling options after collecting the results. +- =replace= :: + + Default. Insert results in the Org buffer. Remove previous + results. Usage example: =:results output replace=. + - =silent= :: Do not insert results in the Org mode buffer, but echo them in the minibuffer. Usage example: =:results output silent=. -- =replace= :: +- =none= :: - Default. Insert results in the Org buffer. Remove previous - results. Usage example: =:results output replace=. + Do not process results at all. No inserting in the Org mode buffer + nor echo them in the minibuffer. Usage example: =:results none=. - =append= :: @@ -17929,35 +18230,8 @@ code block header arguments: #+cindex: source code, languages #+cindex: code block, languages -Code blocks in the following languages are supported. - -#+attr_texinfo: :columns 0.25 0.25 0.25 0.20 -| Language | Identifier | Language | Identifier | -|------------+---------------+----------------+--------------| -| Asymptote | =asymptote= | Lisp | =lisp= | -| Awk | =awk= | Lua | =lua= | -| C | =C= | MATLAB | =matlab= | -| C++ | =C++=[fn:143] | Mscgen | =mscgen= | -| Clojure | =clojure= | Objective Caml | =ocaml= | -| CSS | =css= | Octave | =octave= | -| D | =D=[fn:144] | Org mode | =org= | -| ditaa | =ditaa= | Oz | =oz= | -| Emacs Calc | =calc= | Perl | =perl= | -| Emacs Lisp | =emacs-lisp= | Plantuml | =plantuml= | -| Eshell | =eshell= | Processing.js | =processing= | -| Fortran | =fortran= | Python | =python= | -| Gnuplot | =gnuplot= | R | =R= | -| GNU Screen | =screen= | Ruby | =ruby= | -| Graphviz | =dot= | Sass | =sass= | -| Haskell | =haskell= | Scheme | =scheme= | -| Java | =java= | Sed | =sed= | -| Javascript | =js= | shell | =sh= | -| LaTeX | =latex= | SQL | =sql= | -| Ledger | =ledger= | SQLite | =sqlite= | -| Lilypond | =lilypond= | Vala | =vala= | - -Additional documentation for some languages is at -https://orgmode.org/worg/org-contrib/babel/languages.html. +Code blocks in dozens of languages are supported. See Worg for +[[https://orgmode.org/worg/org-contrib/babel/languages/index.html][language specific documentation]]. #+vindex: org-babel-load-languages By default, only Emacs Lisp is enabled for evaluation. To enable or @@ -18071,7 +18345,7 @@ for Python and Emacs Lisp languages. #+cindex: @samp{noweb-ref}, header argument Source code blocks can include references to other source code blocks, -using a noweb[fn:145] style syntax: +using a noweb[fn:144] style syntax: : <> @@ -18582,14 +18856,14 @@ Org Tempo expands snippets to structures defined in ~org-structure-template-alist~ and ~org-tempo-keywords-alist~. For example, {{{kbd(< s TAB)}}} creates a code block. Enable it by customizing ~org-modules~ or add =(require 'org-tempo)= to your Emacs -init file[fn:146]. +init file[fn:145]. #+attr_texinfo: :columns 0.1 0.9 | {{{kbd(a)}}} | =#+BEGIN_EXPORT ascii= ... =#+END_EXPORT= | | {{{kbd(c)}}} | =#+BEGIN_CENTER= ... =#+END_CENTER= | | {{{kbd(C)}}} | =#+BEGIN_COMMENT= ... =#+END_COMMENT= | | {{{kbd(e)}}} | =#+BEGIN_EXAMPLE= ... =#+END_EXAMPLE= | -| {{{kbd(E)}}} | =#+BEGIN_EXPORT= ... =#+END_EXPORT= | +| {{{kbd(E)}}} | =#+BEGIN_EXPORT= ... =#+END_EXPORT= | | {{{kbd(h)}}} | =#+BEGIN_EXPORT html= ... =#+END_EXPORT= | | {{{kbd(l)}}} | =#+BEGIN_EXPORT latex= ... =#+END_EXPORT= | | {{{kbd(q)}}} | =#+BEGIN_QUOTE= ... =#+END_QUOTE= | @@ -18616,14 +18890,14 @@ the variable ~org-use-speed-commands~ to a non-~nil~ value. To trigger a Speed Key, point must be at the beginning of an Org headline, before any of the stars. -#+vindex: org-speed-commands-user +#+vindex: org-speed-commands #+findex: org-speed-command-help Org comes with a pre-defined list of Speed Keys. To add or modify -Speed Keys, customize the variable, ~org-speed-commands-user~. For -more details, see the variable's docstring. With Speed Keys -activated, {{{kbd(M-x org-speed-command-help)}}}, or {{{kbd(?)}}} when -point is at the beginning of an Org headline, shows currently active -Speed Keys, including the user-defined ones. +Speed Keys, customize the option ~org-speed-commands~. For more +details, see the variable's docstring. With Speed Keys activated, +{{{kbd(M-x org-speed-command-help)}}}, or {{{kbd(?)}}} when point is at the +beginning of an Org headline, shows currently active Speed Keys, +including the user-defined ones. ** A Cleaner Outline View :PROPERTIES: @@ -18662,7 +18936,7 @@ in the desired amount with hard spaces and hiding leading stars. To display the buffer in the indented view, activate Org Indent minor mode, using {{{kbd(M-x org-indent-mode)}}}. Text lines that are not headlines are prefixed with virtual spaces to vertically align with -the headline text[fn:147]. +the headline text[fn:146]. #+vindex: org-indent-indentation-per-level To make more horizontal space, the headlines are shifted by two @@ -18690,15 +18964,15 @@ use =STARTUP= keyword as follows: It is possible to use hard spaces to achieve the indentation instead, if the bare ASCII file should have the indented look also outside -Emacs[fn:148]. With Org's support, you have to indent all lines to +Emacs[fn:147]. With Org's support, you have to indent all lines to line up with the outline headers. You would use these -settings[fn:149]: +settings[fn:148]: - #+begin_src emacs-lisp - (setq org-adapt-indentation t - org-hide-leading-stars t - org-odd-levels-only t) - #+end_src +#+begin_src emacs-lisp +(setq org-adapt-indentation t + org-hide-leading-stars t + org-odd-levels-only t) +#+end_src - /Indentation of text below headlines/ (~org-adapt-indentation~) :: @@ -18955,11 +19229,15 @@ changes. | =overview= | Top-level headlines only. | | =content= | All headlines. | | =showall= | No folding on any entry. | + | =show2levels= | Headline levels 1-2. | + | =show3levels= | Headline levels 1-3. | + | =show4levels= | Headline levels 1-4. | + | =show5levels= | Headline levels 1-5. | | =showeverything= | Show even drawer contents. | #+vindex: org-startup-indented Dynamic virtual indentation is controlled by the variable - ~org-startup-indented~[fn:150]. + ~org-startup-indented~[fn:149]. | =indent= | Start with Org Indent mode turned on. | | =noindent= | Start with Org Indent mode turned off. | @@ -19095,6 +19373,22 @@ changes. These lines set the TODO keywords and their interpretation in the current file. The corresponding variable is ~org-todo-keywords~. +** Regular Expressions +:PROPERTIES: +:DESCRIPTION: Elisp regular expressions. +:END: +#+cindex: regular expressions syntax +#+cindex: regular expressions, in searches + +Org, as an Emacs mode, makes use of Elisp regular expressions for +searching, matching and filtering. Elisp regular expressions have a +somewhat different syntax then some common standards. Most notably, +alternation is indicated using =\|= and matching groups are denoted by +=\(...\)=. For example the string =home\|work= matches either =home= +or =work=. + +For more information, see [[info:emacs::Regexps][Regular Expressions in Emacs]]. + ** Org Syntax :PROPERTIES: :DESCRIPTION: Formal description of Org's syntax. @@ -19533,7 +19827,7 @@ passed to Emacs through the =emacsclient= command, so you also need to ensure an Emacs server is running. More precisely, when the application calls -: emacsclient org-protocol://PROTOCOL?key1=val1&key2=val2 +: emacsclient "org-protocol://PROTOCOL?key1=val1&key2=val2" #+texinfo: @noindent Emacs calls the handler associated to {{{var(PROTOCOL)}}} with @@ -19556,7 +19850,7 @@ Using the ~store-link~ handler, you can copy links, to that they can be inserted using {{{kbd(M-x org-insert-link)}}} or yanking. More precisely, the command -: emacsclient org-protocol://store-link?url=URL&title=TITLE +: emacsclient "org-protocol://store-link?url=URL&title=TITLE" #+texinfo: @noindent stores the following link: @@ -19570,11 +19864,20 @@ slashes, and probably quote those for the shell. To use this feature from a browser, add a bookmark with an arbitrary name, e.g., =Org: store-link= and enter this as /Location/: +#+begin_example +javascript:location.href='org-protocol://store-link?' + + new URLSearchParams({url:location.href, title:document.title}); +#+end_example + +Title is an optional parameter. Another expression was recommended earlier: + #+begin_example javascript:location.href='org-protocol://store-link?url='+ encodeURIComponent(location.href); #+end_example +The latter form is compatible with older Org versions from 9.0 to 9.4. + *** The ~capture~ protocol :PROPERTIES: :DESCRIPTION: Fill a buffer with external information. @@ -19585,11 +19888,20 @@ javascript:location.href='org-protocol://store-link?url='+ Activating the "capture" handler pops up a =Capture= buffer in Emacs, using acapture template. -: emacsclient org-protocol://capture?template=X?url=URL?title=TITLE?body=BODY +: emacsclient "org-protocol://capture?template=X&url=URL&title=TITLE&body=BODY" To use this feature, add a bookmark with an arbitrary name, e.g., =Org: capture=, and enter this as =Location=: +#+begin_example +javascript:location.href='org-protocol://capture?' + + new URLSearchParams({ + template: 'x', url: window.location.href, + title: document.title, body: window.getSelection()}); +#+end_example + +You might have seen another expression: + #+begin_example javascript:location.href='org-protocol://capture?template=x'+ '&url='+encodeURIComponent(window.location.href)+ @@ -19597,6 +19909,10 @@ javascript:location.href='org-protocol://capture?template=x'+ '&body='+encodeURIComponent(window.getSelection()); #+end_example +It is a bit more cluttered than the former one, but it is compatible +with previous Org versions 9.0-9.4. In these versions encoding of +space as "+" character was not supported by URI decoder. + #+vindex: org-protocol-default-template-key The capture template to be used can be specified in the bookmark (like =X= above). If unspecified, the template key is set in the variable @@ -19652,13 +19968,13 @@ click the bookmark and start editing. #+cindex: rewritten URL in open-source protocol #+cindex: protocol, open-source rewritten URL However, such mapping may not always yield the desired results. -Suppose you maintain an online store located at =http://example.com/=. +Suppose you maintain an online store located at =https://example.com/=. The local sources reside in =/home/user/example/=. It is common practice to serve all products in such a store through one file and rewrite URLs that do not match an existing file on the server. That -way, a request to =http://example.com/print/posters.html= might be +way, a request to =https://example.com/print/posters.html= might be rewritten on the server to something like -=http://example.com/shop/products.php/posters.html.php=. The +=https://example.com/shop/products.php/posters.html.php=. The ~open-source~ handler probably cannot find a file named =/home/user/example/print/posters.html.php= and fails. @@ -19673,7 +19989,7 @@ adding ~:rewrites~ rules like this: #+begin_src emacs-lisp (setq org-protocol-project-alist '(("example.com" - :base-url "http://example.com/" + :base-url "https://example.com/" :working-directory "/home/user/example/" :online-suffix ".php" :working-suffix ".php" @@ -19704,8 +20020,8 @@ an Org file that is part of a publishing project. :END: Org Crypt encrypts the text of an entry, but not the headline, or -properties. Behind the scene, it uses the Emacs EasyPG library to -encrypt and decrypt files. +properties. Behind the scene, it uses the [[info:epa][Emacs EasyPG Library]] to +encrypt and decrypt files, and EasyPG needs a correct [[info:gnupg][GnuPG]] setup. #+vindex: org-crypt-tag-matcher Any text below a headline that has a =crypt= tag is automatically @@ -19778,7 +20094,7 @@ Tags]]) only for those set in these variables. #+vindex: org-mobile-directory The mobile application needs access to a file directory on -a server[fn:151] to interact with Emacs. Pass its location through +a server[fn:150] to interact with Emacs. Pass its location through the ~org-mobile-directory~ variable. If you can mount that directory locally just set the variable to point to that directory: @@ -19799,7 +20115,7 @@ With a public server, consider encrypting the files. Org also requires OpenSSL installed on the local computer. To turn on encryption, set the same password in the mobile application and in Emacs. Set the password in the variable -~org-mobile-use-encryption~[fn:152]. Note that even after the mobile +~org-mobile-use-encryption~[fn:151]. Note that even after the mobile application encrypts the file contents, the file name remains visible on the file systems of the local computer, the server, and the mobile device. @@ -19815,15 +20131,15 @@ The command ~org-mobile-push~ copies files listed in ~org-mobile-files~ into the staging area. Files include agenda files (as listed in ~org-agenda-files~). Customize ~org-mobile-files~ to add other files. File names are staged with paths relative to -~org-directory~, so all files should be inside this directory[fn:153]. +~org-directory~, so all files should be inside this directory[fn:152]. Push creates a special Org file =agendas.org= with custom agenda views -defined by the user[fn:154]. +defined by the user[fn:153]. Finally, Org writes the file =index.org=, containing links to other files. The mobile application reads this file first from the server to determine what other files to download for agendas. For faster -downloads, it is expected to only read files whose checksums[fn:155] +downloads, it is expected to only read files whose checksums[fn:154] have changed. *** Pulling from the mobile application @@ -19840,7 +20156,7 @@ data in an inbox file format, through the following steps: 1. #+vindex: org-mobile-inbox-for-pull - Org moves all entries found in =mobileorg.org=[fn:156] and appends + Org moves all entries found in =mobileorg.org=[fn:155] and appends them to the file pointed to by the variable ~org-mobile-inbox-for-pull~. It should reside neither in the staging area nor on the server. Each captured entry and each @@ -19904,12 +20220,10 @@ https://orgmode.org/worg/doc.html#hooks. :END: #+cindex: add-on packages -Various authors wrote a large number of add-on packages for Org. - -These packages are not part of Emacs, but they are distributed as -contributed packages with the separate release available at -https://orgmode.org. See the =contrib/README= file in the source code -directory for a list of contributed files. Worg page with more +Various authors wrote a large number of add-on packages for Org. Some +of these packages used to be part of the =org-mode= repository but are +now hosted in a separate =org-contrib= repository +[[https://git.sr.ht/~bzg/org-contrib][here]]. A Worg page with more information is at: https://orgmode.org/worg/org-contrib/. ** Adding Hyperlink Types @@ -20136,9 +20450,9 @@ of these strategies: #+cindex: @LaTeX{}, and Orgtbl mode To wrap a source table in LaTeX, use the =comment= environment -provided by =comment.sty=[fn:157]. To activate it, put +provided by =comment.sty=[fn:156]. To activate it, put ~\usepackage{comment}~ in the document header. Orgtbl mode inserts -a radio table skeleton[fn:158] with the command {{{kbd(M-x +a radio table skeleton[fn:157] with the command {{{kbd(M-x orgtbl-insert-radio-table)}}}, which prompts for a table name. For example, if =salesfigures= is the name, the template inserts: @@ -20157,7 +20471,7 @@ The line =#+ORGTBL: SEND= tells Orgtbl mode to use the function ~orgtbl-to-latex~ to convert the table to LaTeX format, then insert the table at the target (receive) location named =salesfigures=. Now the table is ready for data entry. It can even use spreadsheet -features[fn:159]: +features[fn:158]: #+begin_example % BEGIN RECEIVE ORGTBL salesfigures @@ -20373,7 +20687,7 @@ Dynamic blocks, like any other block, can be narrowed with #+vindex: org-agenda-skip-function #+vindex: org-agenda-skip-function-global Org provides a special hook to further limit items in agenda views: -~agenda~, ~agenda*~[fn:160], ~todo~, ~alltodo~, ~tags~, ~tags-todo~, +~agenda~, ~agenda*~[fn:159], ~todo~, ~alltodo~, ~tags~, ~tags-todo~, ~tags-tree~. Specify a custom function that tests inclusion of every matched item in the view. This function can also skip as much as is needed. @@ -20416,7 +20730,7 @@ meaningful string suitable for the agenda view. #+vindex: org-agenda-skip-function Search for entries with a limit set on levels for the custom search. This is a general approach to creating custom searches in Org. To -include all levels, use =LEVEL>0=[fn:161]. Then to selectively pick +include all levels, use =LEVEL>0=[fn:160]. Then to selectively pick the matched entries, use ~org-agenda-skip-function~, which also accepts Lisp forms, such as ~org-agenda-skip-entry-if~ and ~org-agenda-skip-subtree-if~. For example: @@ -21017,6 +21331,9 @@ be complete if the ones above were not mentioned in this manual. - Charles Cave's suggestion sparked the implementation of templates for Remember, which are now templates for capture. +- Timothy E Chapman worked on a complete overhaul of the orgmode.org + website in 2020 and helped fixing various bugs. + - Pavel Chalmoviansky influenced the agenda treatment of items with specified time. @@ -21106,6 +21423,9 @@ be complete if the ones above were not mentioned in this manual. - Jason\nbsp{}F.\nbsp{}McBrayer suggested agenda export to CSV format. +- Kyle Meyer helped setting up the [[https://public-inbox.org/][public-inbox]] archive of the [[https://orgmode.org/list/][Org + mailing list]] and has been fixing many bugs. + - Max Mikhanosha came up with the idea of refiling. - Dmitri Minaev sent a patch to set priority limits on a per-file @@ -21143,6 +21463,9 @@ be complete if the ones above were not mentioned in this manual. - Martin Pohlack provided the code snippet to bundle character insertion into bundles of 20 for undo. +- Ihor Radchenko helped with fixing bugs and improving the user + experience regarding Org's speed. + - T.\nbsp{}V.\nbsp{}Raman reported bugs and suggested improvements. - Matthias Rempe (Oelde) provided ideas, Windows support, and quality @@ -21173,7 +21496,7 @@ be complete if the ones above were not mentioned in this manual. literal examples, and remote highlighting for referenced code lines. - Stathis Sideris wrote the =ditaa.jar= ASCII to PNG converter that is - now packaged into Org's =contrib/= directory. + now packaged into the [[https://git.sr.ht/~bzg/org-contrib][org-contrib]] repository. - Daniel Sinder came up with the idea of internal archiving by locking subtrees. @@ -21296,7 +21619,7 @@ modify this GNU manual." * Footnotes [fn:1] If you do not use Font Lock globally turn it on in Org buffer -with =(add-hook 'org-mode-hook 'turn-on-font-lock)=. +with =(add-hook 'org-mode-hook #'turn-on-font-lock)=. [fn:2] Please consider subscribing to the mailing list in order to minimize the work the mailing list moderators have to do. @@ -21597,12 +21920,12 @@ lognoteclock-out=. line---the line is broken here only to fit it into the manual. [fn:81] On computers using macOS, idleness is based on actual user -idleness, not just Emacs' idle time. For X11, you can install -a utility program =x11idle.c=, available in the =contrib/scripts/= -directory of the Org Git distribution, or install the xprintidle -package and set it to the variable ~org-clock-x11idle-program-name~ if -you are running Debian, to get the same general treatment of idleness. -On other systems, idle time refers to Emacs idle time only. +idleness, not just Emacs' idle time. For X11, you can install a +utility program =x11idle.c=, available in the =org-contrib/= +repository, or install the xprintidle package and set it to the +variable ~org-clock-x11idle-program-name~ if you are running Debian, +to get the same general treatment of idleness. On other systems, idle +time refers to Emacs idle time only. [fn:82] Please note the pitfalls of summing hierarchical data in a flat list (see [[*Using Column View in the Agenda]]). @@ -21733,7 +22056,7 @@ a fragment, see the documentation of the function version 1.34 of the =htmlize.el= package, which you need to install). Fontified code chunks in LaTeX can be achieved using either the [[https://www.ctan.org/pkg/listings][listings]] package or the [[https://www.ctan.org/pkg/minted][minted]] package. Refer to -~org-export-latex-listings~ for details. +~org-latex-listings~ for details. [fn:115] Source code in code blocks may also be evaluated either interactively or on export. See [[*Working with Source Code]] for more @@ -21762,7 +22085,9 @@ and =#+STARTUP: nofnadjust=. [fn:122] The variable ~org-export-date-timestamp-format~ defines how this timestamp are exported. -[fn:123] DEFINITION NOT FOUND. +[fn:123] For export to LaTeX format---or LaTeX-related formats such as +Beamer---, the =org-latex-package-alist= variable needs further +configuration. See [[LaTeX specific export settings]]. [fn:124] At the moment, some export back-ends do not obey this specification. For example, LaTeX export excludes every unnumbered @@ -21785,7 +22110,7 @@ to make it visible. The tag serves as a visual aid and has no semantic relevance. [fn:129] By default Org loads MathJax from [[https://cdnjs.com][cdnjs.com]] as recommended by -[[http://www.mathjax.org][MathJax]]. +[[https://www.mathjax.org][MathJax]]. [fn:130] Please note that exported formulas are part of an HTML document, and that signs such as =<=, =>=, or =&= have special @@ -21802,93 +22127,89 @@ use the variables ~org-html-todo-kwd-class-prefix~ and for different files. However, "smart" LaTeX compilation systems, such as latexmk, can select the correct bibliography compiler. -[fn:134] See [[http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html][Open Document Format for Office Applications +[fn:134] Minted uses an external Python package for code highlighting, +which requires the flag =-shell-escape= to be added to +~org-latex-pdf-process~. + +[fn:135] See [[http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html][Open Document Format for Office Applications (OpenDocument) Version 1.2]]. -[fn:135] See [[http://www.mathtoweb.com/cgi-bin/mathtoweb_home.pl][MathToWeb]]. +[fn:136] See [[http://www.mathtoweb.com/cgi-bin/mathtoweb_home.pl][MathToWeb]]. -[fn:136] See [[http://dlmf.nist.gov/LaTeXML/]]. +[fn:137] See [[http://dlmf.nist.gov/LaTeXML/]]. -[fn:137] [[http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html][OpenDocument-v1.2 Specification]] +[fn:138] [[http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html][OpenDocument-v1.2 Specification]] -[fn:138] See the == element of the +[fn:139] See the == element of the OpenDocument-v1.2 specification. -[fn:139] See the attributes =table:template-name=, +[fn:140] See the attributes =table:template-name=, =table:use-first-row-styles=, =table:use-last-row-styles=, =table:use-first-column-styles=, =table:use-last-column-styles=, =table:use-banding-rows-styles=, and =table:use-banding-column-styles= of the == element in the OpenDocument-v1.2 specification. -[fn:140] If the publishing directory is the same as the source +[fn:141] If the publishing directory is the same as the source directory, =file.org= is exported as =file.org.org=, so you probably do not want to do this. -[fn:141] The option ~org-babel-no-eval-on-ctrl-c-ctrl-c~ can be used +[fn:142] The option ~org-babel-no-eval-on-ctrl-c-ctrl-c~ can be used to remove code evaluation from the {{{kbd(C-c C-c)}}} key binding. -[fn:142] Actually, the constructs =call_()= and =src_{}= +[fn:143] Actually, the constructs =call_()= and =src_{}= are not evaluated when they appear in a keyword (see [[*Summary of In-Buffer Settings]]). -[fn:143] C++ language is handled in =ob-C.el=. Even though the -identifier for such source blocks is =C++=, you activate it by loading -the C language. - -[fn:144] D language is handled in =ob-C.el=. Even though the -identifier for such source blocks is =D=, you activate it by loading -the C language. - -[fn:145] For noweb literate programming details, see +[fn:144] For noweb literate programming details, see http://www.cs.tufts.edu/~nr/noweb/. -[fn:146] For more information, please refer to the commentary section +[fn:145] For more information, please refer to the commentary section in =org-tempo.el=. -[fn:147] Org Indent mode also sets ~wrap-prefix~ correctly for +[fn:146] Org Indent mode also sets ~wrap-prefix~ correctly for indenting and wrapping long lines of headlines or text. This minor mode also handles Visual Line mode and directly applied settings through ~word-wrap~. -[fn:148] This works, but requires extra effort. Org Indent mode is +[fn:147] This works, but requires extra effort. Org Indent mode is more convenient for most applications. -[fn:149] ~org-adapt-indentation~ can also be set to ='headline-data=, +[fn:148] ~org-adapt-indentation~ can also be set to ='headline-data=, in which case only data lines below the headline will be indented. -[fn:150] Note that Org Indent mode also sets the ~wrap-prefix~ +[fn:149] Note that Org Indent mode also sets the ~wrap-prefix~ property, such that Visual Line mode (or purely setting ~word-wrap~) wraps long lines, including headlines, correctly indented. -[fn:151] For a server to host files, consider using a WebDAV server, +[fn:150] For a server to host files, consider using a WebDAV server, such as [[https://nextcloud.com][Nextcloud]]. Additional help is at this [[https://orgmode.org/worg/org-faq.html#mobileorg_webdav][FAQ entry]]. -[fn:152] If Emacs is configured for safe storing of passwords, then +[fn:151] If Emacs is configured for safe storing of passwords, then configure the variable ~org-mobile-encryption-password~; please read the docstring of that variable. -[fn:153] Symbolic links in ~org-directory~ need to have the same name +[fn:152] Symbolic links in ~org-directory~ need to have the same name as their targets. -[fn:154] While creating the agendas, Org mode forces =ID= properties +[fn:153] While creating the agendas, Org mode forces =ID= properties on all referenced entries, so that these entries can be uniquely identified if Org Mobile flags them for further action. To avoid setting properties configure the variable ~org-mobile-force-id-on-agenda-items~ to ~nil~. Org mode then relies on outline paths, assuming they are unique. -[fn:155] Checksums are stored automatically in the file +[fn:154] Checksums are stored automatically in the file =checksums.dat=. -[fn:156] The file will be empty after this operation. +[fn:155] The file will be empty after this operation. -[fn:157] https://www.ctan.org/pkg/comment +[fn:156] https://www.ctan.org/pkg/comment -[fn:158] By default this works only for LaTeX, HTML, and Texinfo. +[fn:157] By default this works only for LaTeX, HTML, and Texinfo. Configure the variable ~orgtbl-radio-table-templates~ to install templates for other modes. -[fn:159] If the =TBLFM= keyword contains an odd number of dollar +[fn:158] If the =TBLFM= keyword contains an odd number of dollar characters, this may cause problems with Font Lock in LaTeX mode. As shown in the example you can fix this by adding an extra line inside the =comment= environment that is used to balance the dollar @@ -21896,9 +22217,9 @@ expressions. If you are using AUCTeX with the font-latex library, a much better solution is to add the =comment= environment to the variable ~LaTeX-verbatim-environments~. -[fn:160] The ~agenda*~ view is the same as ~agenda~ except that it +[fn:159] The ~agenda*~ view is the same as ~agenda~ except that it only considers /appointments/, i.e., scheduled and deadline items that have a time specification =[h]h:mm= in their time-stamps. -[fn:161] Note that, for ~org-odd-levels-only~, a level number +[fn:160] Note that, for ~org-odd-levels-only~, a level number corresponds to order in the hierarchy, not to the number of stars. diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS index 2b9cbf37c45..cbb0d38a2ad 100644 --- a/etc/ORG-NEWS +++ b/etc/ORG-NEWS @@ -3,13 +3,574 @@ ORG NEWS -- history of user-visible changes. -*- mode: org; coding: utf-8 -*- #+STARTUP: overview #+LINK: doc https://orgmode.org/worg/doc.html#%s -#+LINK: git https://code.orgmode.org/bzg/org-mode/commit/%s +#+LINK: msg https://list.orgmode.org/%s/ +#+LINK: git https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=%s Copyright (C) 2012-2021 Free Software Foundation, Inc. See the end of the file for license conditions. Please send Org bug reports to mailto:emacs-orgmode@gnu.org. +* 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: showlevels= + +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 +== 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 [[https://lists.gnu.org/archive/html/emacs-orgmode/2020-09/msg00331.html][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~ (==) 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. + * Version 9.4 ** Incompatible changes *** Possibly broken internal file links: please check and fix @@ -101,6 +662,40 @@ Also, ~org-startup-folded~ now defaults to ~showeverything~. ** New features +*** =RET= and =C-j= now obey ~electric-indent-mode~ + +Since Emacs 24.4, ~electric-indent-mode~ is enabled by default. In +most major modes, this causes =RET= to reindent the current line and +indent the new line, and =C-j= to insert a newline without indenting. + +Org mode now obeys this minor mode: when ~electric-indent-mode~ is +enabled, and point is neither in a table nor on a timestamp or a link: + +- =RET= (bound to ~org-return~) reindents the current line and indents + the new line; +- =C-j= (bound to the new command ~org-return-and-maybe-indent~) + merely inserts a newline. + +To get the previous behaviour back, disable ~electric-indent-mode~ +explicitly: + +#+begin_src emacs-lisp +(add-hook 'org-mode-hook (lambda () (electric-indent-local-mode -1))) +#+end_src + +Alternatively, if you wish to keep =RET= as the "smart-return" key, +but dislike Org's default indentation of sections, you may prefer to +customize ~org-adapt-indentation~ to either nil or =headline-data=. + +*** New allowed value for ~org-adapt-indentation~ + +~org-adapt-indentation~ now accepts a new value, =headline-data=. + +When set to this value, Org will only adapt indentation of headline +data lines, such as planning/clock lines and property/logbook drawers. +Also, with this setting, =org-indent-mode= will keep these data lines +correctly aligned with the headline above. + *** Looping agenda commands over headlines ~org-agenda-loop-over-headlines-in-active-region~ allows you to loop @@ -134,15 +729,6 @@ call ~org-toggle-radio-button~. You can also add =#+ATTR_ORG: :radio t= right before the list to tell Org to use radio buttons for this list only. -*** New allowed value for ~org-adapt-indentation~ - -~org-adapt-indentation~ now accepts a new value, ='headline-data=. - -When set to this value, Org will only adapt indentation of headline -data lines, such as planning/clock lines and property/logbook drawers. -Also, with this setting, =org-indent-mode= will keep these data lines -correctly aligned with the headline above. - *** Numeric priorities are now allowed (up to 65) You can now set ~org-priority-highest/lowest/default~ to integers to @@ -212,31 +798,6 @@ can now be inserted with this prefix argument. Source code block header argument =:file-mode= can set file permissions if =:file= argument is provided. -*** =RET= and =C-j= now obey ~electric-indent-mode~ - -Since Emacs 24.4, ~electric-indent-mode~ is enabled by default. In -most major modes, this causes =RET= to reindent the current line and -indent the new line, and =C-j= to insert a newline without indenting. - -Org mode now obeys this minor mode: when ~electric-indent-mode~ is -enabled, and point is neither in a table nor on a timestamp or a link: - -- =RET= (bound to ~org-return~) reindents the current line and indents - the new line; -- =C-j= (bound to the new command ~org-return-and-maybe-indent~) - merely inserts a newline. - -To get the previous behaviour back, disable ~electric-indent-mode~ -explicitly: - -#+begin_src emacs-lisp -(add-hook 'org-mode-hook (lambda () (electric-indent-local-mode -1))) -#+end_src - -Alternatively, if you wish to keep =RET= as the "smart-return" key, -but dislike Org's default indentation of sections, you may prefer to -customize ~org-adapt-indentation~ to either =nil= or ='headline-data=. - *** =ob-C.el= allows the inclusion of non-system header files In C and C++ blocks, ~:includes~ arguments that do not start with a @@ -353,7 +914,7 @@ source buffers are displayed by modifying ~display-buffer-alist~ or *** New option ~org-archive-subtree-save-file-p~ Archiving a subtree used to always save the target archive buffer. -Commit [[https://code.orgmode.org/bzg/org-mode/commit/b186d1d7][b186d1d7]] changed this behavior by always not saving the target +Commit [[git::b186d1d7][b186d1d7]] changed this behavior by always not saving the target buffer, because batch archiving from agenda could take too much time. This new option ~org-archive-subtree-save-file-p~ defaults to the @@ -380,14 +941,14 @@ The value of a shell script's execution is its exit code. But most users expect the results of executing a shell script to be its output, not its exit code. -So we introduced this option, that you can set to =nil= if you want -to stick using ~:results value~ as the implicit header. +So we introduced this option, that you can set to nil if you want to +stick using ~:results value~ as the implicit header. In all Babel libraries, the absence of a ~:results~ header should produce the same result than setting ~:results value~, unless there is an option to explicitly create an exception. -See [[https://orgmode.org/list/CA+A2iZaziAfMeGpBqL6qGrzrWEVvLvC0DUw++T4gCF3NGuW-DQ@mail.gmail.com/][this thread]] for more context. +See [[msg:CA+A2iZaziAfMeGpBqL6qGrzrWEVvLvC0DUw++T4gCF3NGuW-DQ@mail.gmail.com][this thread]] for more context. *** New option in ~org-attach-store-link-p~ @@ -1197,7 +1758,7 @@ With this output format, create a link to the file specified in #+begin_example ,#+begin_src shell :dir "data/tmp" :results link :file "crackzor_1.0.c.gz" -wget -c "http://ben.akrin.com/crackzor/crackzor_1.0.c.gz" +wget -c "https://ben.akrin.com/crackzor/crackzor_1.0.c.gz" ,#+end_src ,#+results: @@ -1537,7 +2098,9 @@ Use "/!" markup when filtering TODO keywords to get only not-done TODO keywords. *** ~org-split-string~ returns ~("")~ when called on an empty string + It used to return nil. + *** Removal of =ob-scala.el= See [[https://github.com/ensime/emacs-scala-mode/issues/114][this github issue]]. @@ -1605,7 +2168,8 @@ before this let form. 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. +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 @@ -1648,7 +2212,7 @@ this ~:prologue "fpprintprec: 2; linel: 50;"~ for presenting Maxima results in a beamer presentation. **** PlantUML: add support for header arguments -[[http://plantuml.com/][Plantuml]] source blocks now support the [[https://orgmode.org/manual/prologue.html#prologue][~:prologue~]], [[https://orgmode.org/manual/epilogue.html#epilogue][~:epilogue~]] and +[[https://plantuml.com/][Plantuml]] source blocks now support the [[https://orgmode.org/manual/prologue.html#prologue][~:prologue~]], [[https://orgmode.org/manual/epilogue.html#epilogue][~:epilogue~]] and [[https://orgmode.org/manual/var.html#var][~:var~]] header arguments. **** SQL: new engine added ~sqsh~ @@ -1821,9 +2385,8 @@ removed from Gnus circa September 2010. *** ~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=. +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. @@ -1841,7 +2404,7 @@ 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 +Setting it to a nil value broke some other features (e.g., speed keys). *** ~org-export-use-babel~ cannot be set to ~inline-only~ @@ -2284,7 +2847,7 @@ The postgresql engine in a sql code block supports now ~:dbport~ nd **** Support for additional plantuml output formats -The support for output formats of [[http://plantuml.com/][plantuml]] has been extended to now +The support for output formats of [[https://plantuml.com/][plantuml]] has been extended to now include: All Diagrams: @@ -2317,7 +2880,7 @@ Alice <-- Bob: another authentication Response #+end_src Please note that *pdf* *does not work out of the box* and needs additional -setup in addition to plantuml. See [[http://plantuml.com/pdf.html]] for +setup in addition to plantuml. See [[https://plantuml.com/pdf.html]] for details and setup information. *** Rewrite of radio lists @@ -3447,11 +4010,11 @@ then inline code snippets will be wrapped into the formatting string. ** New contributed packages - =ox-bibtex.el= by Nicolas Goaziou :: an utility to handle BibTeX - export to both LaTeX and HTML exports. It uses the [[http://www.lri.fr/~filliatr/bibtex2html/][bibtex2html]] + export to both LaTeX and HTML exports. It uses the [[https://www.lri.fr/~filliatr/bibtex2html/][bibtex2html]] software. - =org-screenshot.el= by Max Mikhanosha :: an utility to handle - screenshots easily from Org, using the external tool [[http://freecode.com/projects/scrot][scrot]]. + screenshots easily from Org, using the external tool [[https://freecode.com/projects/scrot][scrot]]. ** Miscellaneous @@ -3602,7 +4165,7 @@ manual for details and check [[https://orgmode.org/worg/org-8.0.html][this Worg *** ~ox-md.el~ by Nicolas Goaziou =ox-md.el= allows you to export Org files to Markdown files, using the - vanilla [[http://daringfireball.net/projects/markdown/][Markdown syntax]]. + vanilla [[https://daringfireball.net/projects/markdown/][Markdown syntax]]. *** ~ox-texinfo.el~ by Jonathan Leech-Pepin @@ -3612,14 +4175,14 @@ manual for details and check [[https://orgmode.org/worg/org-8.0.html][this Worg *** ~ob-julia.el~ by G. Jay Kerns - [[http://julialang.org/][Julia]] is a new programming language. + [[https://julialang.org/][Julia]] is a new programming language. =ob-julia.el= provides Org Babel support for evaluating Julia source code. *** ~ob-mathomatic.el~ by Luis Anaya - [[http://www.mathomatic.org/][mathomatic]] a portable, command-line, educational CAS and calculator + [[https://www.mathomatic.org/][mathomatic]] a portable, command-line, educational CAS and calculator software, written entirely in the C programming language. ~ob-mathomatic.el~ provides Org Babel support for evaluating mathomatic @@ -3627,7 +4190,7 @@ manual for details and check [[https://orgmode.org/worg/org-8.0.html][this Worg *** ~ob-tcl.el~ by Luis Anaya - ~ob-tcl.el~ provides Org Babel support for evaluating [[http://www.tcl.tk/][Tcl]] source code. + ~ob-tcl.el~ provides Org Babel support for evaluating [[https://www.tcl.tk/][Tcl]] source code. *** ~org-bullets.el~ by Evgeni Sabof @@ -3653,7 +4216,7 @@ manual for details and check [[https://orgmode.org/worg/org-8.0.html][this Worg presentations. ~ox-deck.el~ exports Org files to HTML presentations using =deck.js=. - [[http://meyerweb.com/eric/tools/s5/][s5]] is a set of scripts which also allows to display HTML pages as + [[https://meyerweb.com/eric/tools/s5/][s5]] is a set of scripts which also allows to display HTML pages as presentations. ~ox-s5.el~ exports Org files to HTML presentations using =s5=. @@ -3760,13 +4323,13 @@ forward and backward. Now Org will sort this list -: - [[http://abc.org][B]] -: - [[http://def.org][A]] +: - [[https://abc.org][B]] +: - [[https://def.org][A]] like this: -: - [[http://def.org][A]] -: - [[http://abc.org][B]] +: - [[https://def.org][A]] +: - [[https://abc.org][B]] by comparing the descriptions, not the links. Same when sorting headlines instead of list items. @@ -4270,8 +4833,8 @@ found here: https://orgmode.org/worg/org-tutorials/org-outside-org.html Here are two screencasts demonstrating Thorsten's tools: -- [[http://youtu.be/nqE6YxlY0rw]["Modern conventions for Emacs Lisp files"]] -- [[http://www.youtube.com/watch?v%3DII-xYw5VGFM][Exploring Bernt Hansen's Org-mode tutorial with 'navi-mode']] +- [[https://youtu.be/nqE6YxlY0rw]["Modern conventions for Emacs Lisp files"]] +- [[https://www.youtube.com/watch?v%3DII-xYw5VGFM][Exploring Bernt Hansen's Org-mode tutorial with 'navi-mode']] *** MobileOrg for iOS @@ -4301,7 +4864,7 @@ lines even if `org-use-tag-inheritance' was nil. The default is now to *never* display inherited tags in agenda lines, but to /know/ about them when the agenda type is listed in [[doc::org-agenda-use-tag-inheritance][org-agenda-use-tag-inheritance]]. -** New default value nil for [[doc::org-agenda-dim-blocked-tasks][org-agenda-dim-blocked-tasks]] +** New default value =nil= for [[doc::org-agenda-dim-blocked-tasks][org-agenda-dim-blocked-tasks]] Using `nil' as the default value speeds up the agenda generation. You can hit `#' (or `C-u #') in agenda buffers to temporarily dim (or turn @@ -5130,7 +5693,7 @@ that Calc formulas can operate on them. The new system has a technically cleaner implementation and more possibilities for capturing different types of data. See - [[https://orgmode.org/list/C46F10DC-DE51-43D4-AFFE-F71E440D1E1F@gmail.com][Carsten's announcement]] for more details. + [[msg:C46F10DC-DE51-43D4-AFFE-F71E440D1E1F@gmail.com][Carsten's announcement]] for more details. To switch over to the new system: @@ -5261,7 +5824,7 @@ that Calc formulas can operate on them. **** Modified link escaping - David Maus worked on `org-link-escape'. See [[https://orgmode.org/list/87k4gysacq.wl%dmaus@ictsoc.de][his message]]: + David Maus worked on `org-link-escape'. See [[msg:87k4gysacq.wl%dmaus@ictsoc.de][his message]]: : Percent escaping is used in Org mode to escape certain characters : in links that would either break the parser (e.g. square brackets diff --git a/etc/refcards/orgcard.tex b/etc/refcards/orgcard.tex index dc28587b47d..d3715948d65 100644 --- a/etc/refcards/orgcard.tex +++ b/etc/refcards/orgcard.tex @@ -1,6 +1,6 @@ % Reference Card for Org Mode -\def\orgversionnumber{9.4.2} -\def\versionyear{2019} % latest update +\def\orgversionnumber{9.5} +\def\versionyear{2021} % latest update \input emacsver.tex %**start of header diff --git a/lisp/org/ob-C.el b/lisp/org/ob-C.el index 6e339017931..842e0d3e8ec 100644 --- a/lisp/org/ob-C.el +++ b/lisp/org/ob-C.el @@ -4,6 +4,7 @@ ;; Author: Eric Schulte ;; Thierry Banel +;; Maintainer: Thierry Banel ;; Keywords: literate programming, reproducible research ;; Homepage: https://orgmode.org @@ -94,8 +95,7 @@ This function calls `org-babel-execute:C++'." (org-babel-execute:C++ body params)) (defun org-babel-expand-body:cpp (body params) - "Expand a block of C++ code with org-babel according to its -header arguments." + "Expand a block of C++ code with org-babel according to its header arguments." (org-babel-expand-body:C++ body params)) (defun org-babel-execute:C++ (body params) @@ -104,8 +104,7 @@ This function is called by `org-babel-execute-src-block'." (let ((org-babel-c-variant 'cpp)) (org-babel-C-execute body params))) (defun org-babel-expand-body:C++ (body params) - "Expand a block of C++ code with org-babel according to its -header arguments." + "Expand a block of C++ code with org-babel according to its header arguments." (let ((org-babel-c-variant 'cpp)) (org-babel-C-expand-C++ body params))) (defun org-babel-execute:D (body params) @@ -114,8 +113,7 @@ This function is called by `org-babel-execute-src-block'." (let ((org-babel-c-variant 'd)) (org-babel-C-execute body params))) (defun org-babel-expand-body:D (body params) - "Expand a block of D code with org-babel according to its -header arguments." + "Expand a block of D code with org-babel according to its header arguments." (let ((org-babel-c-variant 'd)) (org-babel-C-expand-D body params))) (defun org-babel-execute:C (body params) @@ -124,8 +122,7 @@ This function is called by `org-babel-execute-src-block'." (let ((org-babel-c-variant 'c)) (org-babel-C-execute body params))) (defun org-babel-expand-body:C (body params) - "Expand a block of C code with org-babel according to its -header arguments." + "Expand a block of C code with org-babel according to its header arguments." (let ((org-babel-c-variant 'c)) (org-babel-C-expand-C body params))) (defun org-babel-C-execute (body params) @@ -196,13 +193,11 @@ or `org-babel-execute:C++' or `org-babel-execute:D'." ))) (defun org-babel-C-expand-C++ (body params) - "Expand a block of C or C++ code with org-babel according to -its header arguments." + "Expand a block of C/C++ code with org-babel according to its header arguments." (org-babel-C-expand-C body params)) (defun org-babel-C-expand-C (body params) - "Expand a block of C or C++ code with org-babel according to -its header arguments." + "Expand a block of C/C++ code with org-babel according to its header arguments." (let ((vars (org-babel--get-vars params)) (colnames (cdr (assq :colname-names params))) (main-p (not (string= (cdr (assq :main params)) "no"))) @@ -257,15 +252,21 @@ its header arguments." (when colnames (org-babel-C-utility-header-to-C)) ;; tables headers - (mapconcat 'org-babel-C-header-to-C colnames "\n") + (mapconcat (lambda (head) + (let* ((tblnm (car head)) + (tbl (cdr (car (let* ((el vars)) + (while (not (or (equal tblnm (caar el)) (not el))) + (setq el (cdr el))) + el)))) + (type (org-babel-C-val-to-base-type tbl))) + (org-babel-C-header-to-C head type))) colnames "\n") ;; body (if main-p (org-babel-C-ensure-main-wrap body) body) "\n") "\n"))) (defun org-babel-C-expand-D (body params) - "Expand a block of D code with org-babel according to -its header arguments." + "Expand a block of D code with org-babel according to its header arguments." (let ((vars (org-babel--get-vars params)) (colnames (cdr (assq :colname-names params))) (main-p (not (string= (cdr (assq :main params)) "no"))) @@ -289,7 +290,14 @@ its header arguments." (when colnames (org-babel-C-utility-header-to-C)) ;; tables headers - (mapconcat 'org-babel-C-header-to-C colnames "\n") + (mapconcat (lambda (head) + (let* ((tblnm (car head)) + (tbl (cdr (car (let* ((el vars)) + (while (not (or (equal tblnm (caar el)) (not el))) + (setq el (cdr el))) + el)))) + (type (org-babel-C-val-to-base-type tbl))) + (org-babel-C-header-to-C head type))) colnames "\n") ;; body (if main-p (org-babel-C-ensure-main-wrap body) @@ -333,7 +341,7 @@ FORMAT can be either a format string or a function which is called with VAL." (list (if (eq org-babel-c-variant 'd) "string" "const char*") "\"%s\"")) - (_ (error "unknown type %S" basetype))))) + (_ (error "Unknown type %S" basetype))))) (cond ((integerp val) type) ;; an integer declared in the #+begin_src line ((floatp val) type) ;; a numeric declared in the #+begin_src line @@ -341,7 +349,9 @@ FORMAT can be either a format string or a function which is called with VAL." `(,(car type) (lambda (val) (cons - (format "[%d][%d]" (length val) (length (car val))) + (pcase org-babel-c-variant + ((or `c `cpp) (format "[%d][%d]" (length val) (length (car val)))) + (`d (format "[%d][%d]" (length (car val)) (length val)))) (concat (if (eq org-babel-c-variant 'd) "[\n" "{\n") (mapconcat @@ -388,8 +398,7 @@ FORMAT can be either a format string or a function which is called with VAL." (t 'stringp))) (defun org-babel-C-var-to-C (pair) - "Convert an elisp val into a string of C code specifying a var -of the same value." + "Convert an elisp val into a string of C code specifying a var of the same value." ;; TODO list support (let ((var (car pair)) (val (cdr pair))) @@ -402,11 +411,19 @@ of the same value." (formatted (org-babel-C-format-val type-data val)) (suffix (car formatted)) (data (cdr formatted))) - (format "%s %s%s = %s;" - type - var - suffix - data)))) + (pcase org-babel-c-variant + ((or `c `cpp) + (format "%s %s%s = %s;" + type + var + suffix + data)) + (`d + (format "%s%s %s = %s;" + type + suffix + var + data)))))) (defun org-babel-C-table-sizes-to-C (pair) "Create constants of table dimensions, if PAIR is a table." @@ -421,11 +438,15 @@ of the same value." (format "const int %s_cols = %d;" (car pair) (length (cdr pair))))))) (defun org-babel-C-utility-header-to-C () - "Generate a utility function to convert a column name -into a column number." + "Generate a utility function to convert a column name into a column number." (pcase org-babel-c-variant ((or `c `cpp) - "int get_column_num (int nbcols, const char** header, const char* column) + (concat + " +#ifndef _STRING_H +#include +#endif +int get_column_num (int nbcols, const char** header, const char* column) { int c; for (c=0; c -;; Keywords: literate programming, reproducible research -;; Homepage: https://orgmode.org - -;; This file is part of GNU Emacs. - -;; GNU Emacs is free software: you can redistribute it and/or modify -;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation, either version 3 of the License, or -;; (at your option) any later version. - -;; GNU Emacs is distributed in the hope that it will be useful, -;; but WITHOUT ANY WARRANTY; without even the implied warranty of -;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -;; GNU General Public License for more details. - -;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs. If not, see . - -;;; Commentary: - -;; Org-Babel support for evaluating J code. -;; -;; Session interaction depends on `j-console' from package `j-mode' -;; (available in MELPA). - -;;; Code: - -(require 'ob) -(require 'org-macs) - -(declare-function j-console-ensure-session "ext:j-console" ()) - -(defcustom org-babel-J-command "jconsole" - "Command to call J." - :group 'org-babel - :version "26.1" - :package-version '(Org . "9.0") - :type 'string) - -(defun org-babel-expand-body:J (body _params &optional _processed-params) - "Expand BODY according to PARAMS, return the expanded body. -PROCESSED-PARAMS isn't used yet." - (org-babel-J-interleave-echos-except-functions body)) - -(defun org-babel-J-interleave-echos (body) - "Interleave echo',' between each source line of BODY." - (mapconcat #'identity (split-string body "\n") "\necho','\n")) - -(defun org-babel-J-interleave-echos-except-functions (body) - "Interleave echo',' between source lines of BODY that aren't functions." - (if (obj-string-match-m "\\(?:^\\|\n\\)[^\n]*\\(?:0\\|1\\|2\\|3\\|4\\|dyad\\) : 0\n.*\n)\\(?:\n\\|$\\)" body) - (let ((s1 (substring body 0 (match-beginning 0))) - (s2 (match-string 0 body)) - (s3 (substring body (match-end 0)))) - (concat - (if (string= s1 "") - "" - (concat (org-babel-J-interleave-echos s1) - "\necho','\n")) - s2 - "\necho','\n" - (org-babel-J-interleave-echos-except-functions s3))) - (org-babel-J-interleave-echos body))) - -(defalias 'org-babel-execute:j 'org-babel-execute:J) - -(defun org-babel-execute:J (body params) - "Execute a block of J code BODY. -PARAMS are given by org-babel. -This function is called by `org-babel-execute-src-block'." - (message "executing J source code block") - (let* ((processed-params (org-babel-process-params params)) - (sessionp (cdr (assq :session params))) - (sit-time (let ((sit (assq :sit params))) - (if sit (cdr sit) .1))) - (full-body (org-babel-expand-body:J - body params processed-params)) - (tmp-script-file (org-babel-temp-file "J-src"))) - (org-babel-j-initiate-session sessionp) - (org-babel-J-strip-whitespace - (if (string= sessionp "none") - (progn - (with-temp-file tmp-script-file - (insert full-body)) - (org-babel-eval (format "%s < %s" org-babel-J-command tmp-script-file) "")) - (org-babel-J-eval-string full-body sit-time))))) - -(defun org-babel-J-eval-string (str sit-time) - "Sends STR to the `j-console-cmd' session and executes it." - (let ((session (j-console-ensure-session))) - (with-current-buffer (process-buffer session) - (goto-char (point-max)) - (insert (format "\n%s\n" str)) - (let ((beg (point))) - (comint-send-input) - (sit-for sit-time) - (buffer-substring-no-properties - beg (point-max)))))) - -(defun org-babel-J-strip-whitespace (str) - "Remove whitespace from jconsole output STR." - (mapconcat - #'identity - (delete "" (mapcar - #'org-babel-J-print-block - (split-string str "^ *,\n" t))) - "\n\n")) - -(defun obj-get-string-alignment (str) - "Return a number to describe STR alignment. -STR represents a table. -Positive/negative/zero result means right/left/undetermined. -Don't trust first line." - (let* ((str (org-trim str)) - (lines (split-string str "\n" t)) - n1 n2) - (cond ((<= (length lines) 1) - 0) - ((= (length lines) 2) - ;; numbers are right-aligned - (if (and - (numberp (read (car lines))) - (numberp (read (cadr lines))) - (setq n1 (obj-match-second-space-right (nth 0 lines))) - (setq n2 (obj-match-second-space-right (nth 1 lines)))) - n2 - 0)) - ((not (obj-match-second-space-left (nth 0 lines))) - 0) - ((and - (setq n1 (obj-match-second-space-left (nth 1 lines))) - (setq n2 (obj-match-second-space-left (nth 2 lines))) - (= n1 n2)) - n1) - ((and - (setq n1 (obj-match-second-space-right (nth 1 lines))) - (setq n2 (obj-match-second-space-right (nth 2 lines))) - (= n1 n2)) - (- n1)) - (t 0)))) - -(defun org-babel-J-print-block (x) - "Prettify jconsole output X." - (let* ((x (org-trim x)) - (a (obj-get-string-alignment x)) - (lines (split-string x "\n" t)) - b) - (cond ((< a 0) - (setq b (obj-match-second-space-right (nth 0 lines))) - (concat (make-string (+ a b) ? ) x)) - ((> a 0) - (setq b (obj-match-second-space-left (nth 0 lines))) - (concat (make-string (- a b) ? ) x)) - (t x)))) - -(defun obj-match-second-space-left (s) - "Return position of leftmost space in second space block of S or nil." - (and (string-match "^ *[^ ]+\\( \\)" s) - (match-beginning 1))) - -(defun obj-match-second-space-right (s) - "Return position of rightmost space in second space block of S or nil." - (and (string-match "^ *[^ ]+ *\\( \\)[^ ]" s) - (match-beginning 1))) - -(defun obj-string-match-m (regexp string &optional start) - "Call (string-match REGEXP STRING START). -REGEXP is modified so that .* matches newlines as well." - (string-match - (replace-regexp-in-string "\\.\\*" "[\0-\377[:nonascii:]]*" regexp) - string - start)) - -(defun org-babel-j-initiate-session (&optional session) - "Initiate a J session. -SESSION is a parameter given by org-babel." - (unless (string= session "none") - (require 'j-console) - (j-console-ensure-session))) - -(provide 'ob-J) - -;;; ob-J.el ends here diff --git a/lisp/org/ob-R.el b/lisp/org/ob-R.el index 309a0acf7e7..169e1d6d6ce 100644 --- a/lisp/org/ob-R.el +++ b/lisp/org/ob-R.el @@ -4,6 +4,7 @@ ;; Author: Eric Schulte ;; Dan Davison +;; Maintainer: Jeremie Juste ;; Keywords: literate programming, reproducible research, R, statistics ;; Homepage: https://orgmode.org @@ -39,6 +40,13 @@ (declare-function ess-wait-for-process "ext:ess-inf" (&optional proc sec-prompt wait force-redisplay)) +;; FIXME: Temporary declaration to silence the byte-compiler +(defvar user-inject-src-param) +(defvar ess-eval-visibly-tmp) +(defvar ess-eval-visibly) +(defvar ess-inject-source) +(defvar user-inject-src-param) + (defconst org-babel-header-args:R '((width . :any) (height . :any) @@ -157,6 +165,7 @@ This function is called by `org-babel-execute-src-block'." (save-excursion (let* ((result-params (cdr (assq :result-params params))) (result-type (cdr (assq :result-type params))) + (async (org-babel-comint-use-async params)) (session (org-babel-R-initiate-session (cdr (assq :session params)) params)) (graphics-file (and (member "graphics" (assq :result-params params)) @@ -183,7 +192,8 @@ This function is called by `org-babel-execute-src-block'." (cdr (assq :colname-names params)) colnames-p)) (or (equal "yes" rownames-p) (org-babel-pick-name - (cdr (assq :rowname-names params)) rownames-p))))) + (cdr (assq :rowname-names params)) rownames-p)) + async))) (if graphics-file nil result)))) (defun org-babel-prep-session:R (session params) @@ -321,7 +331,7 @@ Each member of this list is a list with three members: (device-info (or (assq (intern (concat ":" device)) org-babel-R-graphics-devices) (assq :png org-babel-R-graphics-devices))) - (extra-args (cdr (assq :R-dev-args params))) filearg args) + (extra-args (cdr (assq :R-dev-args params))) filearg args) (setq device (nth 1 device-info)) (setq filearg (nth 2 device-info)) (setq args (mapconcat @@ -348,7 +358,7 @@ Each member of this list is a list with three members: { tfile<-tempfile() write.table(object, file=tfile, sep=\"\\t\", - na=\"nil\",row.names=%s,col.names=%s, + na=\"\",row.names=%s,col.names=%s, quote=FALSE) file.rename(tfile,transfer.file) }, @@ -370,11 +380,14 @@ Has four %s escapes to be filled in: 4. The name of the file to write to") (defun org-babel-R-evaluate - (session body result-type result-params column-names-p row-names-p) + (session body result-type result-params column-names-p row-names-p async) "Evaluate R code in BODY." (if session - (org-babel-R-evaluate-session - session body result-type result-params column-names-p row-names-p) + (if async + (ob-session-async-org-babel-R-evaluate-session + session body result-type result-params column-names-p row-names-p) + (org-babel-R-evaluate-session + session body result-type result-params column-names-p row-names-p)) (org-babel-R-evaluate-external-process body result-type result-params column-names-p row-names-p))) @@ -450,11 +463,13 @@ last statement in BODY, as elisp." (car (split-string line "\n"))) (substring line (match-end 1)) line)) - (org-babel-comint-with-output (session org-babel-R-eoe-output) - (insert (mapconcat 'org-babel-chomp - (list body org-babel-R-eoe-indicator) - "\n")) - (inferior-ess-send-input)))))) "\n")))) + (with-current-buffer session + (let ((comint-prompt-regexp (concat "^" comint-prompt-regexp))) + (org-babel-comint-with-output (session org-babel-R-eoe-output) + (insert (mapconcat 'org-babel-chomp + (list body org-babel-R-eoe-indicator) + "\n")) + (inferior-ess-send-input)))))))) "\n")))) (defun org-babel-R-process-value-result (result column-names-p) "R-specific processing of return value. @@ -465,6 +480,91 @@ Insert hline if column names in output have been requested." (error "Could not parse R result")) result)) + +;;; async evaluation + +(defconst ob-session-async-R-indicator "'ob_comint_async_R_%s_%s'") + +(defun ob-session-async-org-babel-R-evaluate-session + (session body result-type _ column-names-p row-names-p) + "Asynchronously evaluate BODY in SESSION. +Returns a placeholder string for insertion, to later be replaced +by `org-babel-comint-async-filter'." + (org-babel-comint-async-register + session (current-buffer) + "^\\(?:[>.+] \\)*\\[1\\] \"ob_comint_async_R_\\(.+?\\)_\\(.+\\)\"$" + 'org-babel-chomp + 'ob-session-async-R-value-callback) + (cl-case result-type + (value + (let ((tmp-file (org-babel-temp-file "R-"))) + (with-temp-buffer + (insert + (org-babel-chomp body)) + (let ((ess-local-process-name + (process-name (get-buffer-process session)))) + (ess-eval-buffer nil))) + (with-temp-buffer + (insert + (mapconcat + 'org-babel-chomp + (list (format org-babel-R-write-object-command + (if row-names-p "TRUE" "FALSE") + (if column-names-p + (if row-names-p "NA" "TRUE") + "FALSE") + ".Last.value" + (org-babel-process-file-name tmp-file 'noquote)) + (format ob-session-async-R-indicator + "file" tmp-file)) + "\n")) + (let ((ess-local-process-name + (process-name (get-buffer-process session)))) + (ess-eval-buffer nil))) + tmp-file)) + (output + (let ((uuid (md5 (number-to-string (random 100000000)))) + (ess-local-process-name + (process-name (get-buffer-process session)))) + (with-temp-buffer + (insert (format ob-session-async-R-indicator + "start" uuid)) + (insert "\n") + (insert body) + (insert "\n") + (insert (format ob-session-async-R-indicator + "end" uuid)) + (setq ess-eval-visibly-tmp ess-eval-visibly) + (setq user-inject-src-param ess-inject-source) + (setq ess-eval-visibly nil) + (setq ess-inject-source 'function-and-buffer) + (ess-eval-buffer nil)) + (setq ess-eval-visibly ess-eval-visibly-tmp) + (setq ess-inject-source user-inject-src-param) + uuid)))) + +(defun ob-session-async-R-value-callback (params tmp-file) + "Callback for async value results. +Assigned locally to `ob-session-async-file-callback' in R +comint buffers used for asynchronous Babel evaluation." + (let* ((graphics-file (and (member "graphics" (assq :result-params params)) + (org-babel-graphical-output-file params))) + (colnames-p (unless graphics-file (cdr (assq :colnames params))))) + (org-babel-R-process-value-result + (org-babel-result-cond (assq :result-params params) + (with-temp-buffer + (insert-file-contents tmp-file) + (org-babel-chomp (buffer-string) "\n")) + (org-babel-import-elisp-from-file tmp-file '(16))) + (or (equal "yes" colnames-p) + (org-babel-pick-name + (cdr (assq :colname-names params)) colnames-p))))) + + + +;;; ob-session-async-R.el ends here + + (provide 'ob-R) ;;; ob-R.el ends here diff --git a/lisp/org/ob-abc.el b/lisp/org/ob-abc.el deleted file mode 100644 index 404e39fc27c..00000000000 --- a/lisp/org/ob-abc.el +++ /dev/null @@ -1,90 +0,0 @@ -;;; ob-abc.el --- Org Babel Functions for ABC -*- lexical-binding: t; -*- - -;; Copyright (C) 2013-2021 Free Software Foundation, Inc. - -;; Author: William Waites -;; Keywords: literate programming, music -;; Homepage: https://www.tardis.ed.ac.uk/~wwaites - -;; This file is part of GNU Emacs. - -;; GNU Emacs is free software: you can redistribute it and/or modify -;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation, either version 3 of the License, or -;; (at your option) any later version. - -;; GNU Emacs is distributed in the hope that it will be useful, -;; but WITHOUT ANY WARRANTY; without even the implied warranty of -;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -;; GNU General Public License for more details. - -;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs. If not, see . - -;;; Commentary: - -;;; This file adds support to Org Babel for music in ABC notation. -;;; It requires that the abcm2ps program is installed. -;;; See http://moinejf.free.fr/ - -(require 'ob) - -;; optionally define a file extension for this language -(add-to-list 'org-babel-tangle-lang-exts '("abc" . "abc")) - -;; optionally declare default header arguments for this language -(defvar org-babel-default-header-args:abc - '((:results . "file") (:exports . "results")) - "Default arguments to use when evaluating an ABC source block.") - -(defun org-babel-expand-body:abc (body params) - "Expand BODY according to PARAMS, return the expanded body." - (let ((vars (org-babel--get-vars params))) - (mapc - (lambda (pair) - (let ((name (symbol-name (car pair))) - (value (cdr pair))) - (setq body - (replace-regexp-in-string - (concat "\\$" (regexp-quote name)) - (if (stringp value) value (format "%S" value)) - body)))) - vars) - body)) - -(defun org-babel-execute:abc (body params) - "Execute a block of ABC code with org-babel. This function is - called by `org-babel-execute-src-block'" - (message "executing Abc source code block") - (let* ((cmdline (cdr (assq :cmdline params))) - (out-file (let ((file (cdr (assq :file params)))) - (if file (replace-regexp-in-string "\\.pdf$" ".ps" file) - (error "abc code block requires :file header argument")))) - (in-file (org-babel-temp-file "abc-")) - (render (concat "abcm2ps" " " cmdline - " -O " (org-babel-process-file-name out-file) - " " (org-babel-process-file-name in-file)))) - (with-temp-file in-file (insert (org-babel-expand-body:abc body params))) - (org-babel-eval render "") - ;;; handle where abcm2ps changes the file name (to support multiple files - (when (or (string= (file-name-extension out-file) "eps") - (string= (file-name-extension out-file) "svg")) - (rename-file (concat - (file-name-sans-extension out-file) "001." - (file-name-extension out-file)) - out-file t)) - ;;; if we were asked for a pdf... - (when (string= (file-name-extension (cdr (assq :file params))) "pdf") - (org-babel-eval (concat "ps2pdf" " " out-file " " (cdr (assq :file params))) "")) - ;;; indicate that the file has been written - nil)) - -;; This function should be used to assign any variables in params in -;; the context of the session environment. -(defun org-babel-prep-session:abc (_session _params) - "Return an error because abc does not support sessions." - (error "ABC does not support sessions")) - -(provide 'ob-abc) - -;;; ob-abc.el ends here diff --git a/lisp/org/ob-asymptote.el b/lisp/org/ob-asymptote.el deleted file mode 100644 index bfb5b79145e..00000000000 --- a/lisp/org/ob-asymptote.el +++ /dev/null @@ -1,137 +0,0 @@ -;;; ob-asymptote.el --- Babel Functions for Asymptote -*- lexical-binding: t; -*- - -;; Copyright (C) 2009-2021 Free Software Foundation, Inc. - -;; Author: Eric Schulte -;; Keywords: literate programming, reproducible research -;; Homepage: https://orgmode.org - -;; This file is part of GNU Emacs. - -;; GNU Emacs is free software: you can redistribute it and/or modify -;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation, either version 3 of the License, or -;; (at your option) any later version. - -;; GNU Emacs is distributed in the hope that it will be useful, -;; but WITHOUT ANY WARRANTY; without even the implied warranty of -;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -;; GNU General Public License for more details. - -;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs. If not, see . - -;;; Commentary: - -;; Org-Babel support for evaluating asymptote source code. -;; -;; This differs from most standard languages in that -;; -;; 1) there is no such thing as a "session" in asymptote -;; -;; 2) we are generally only going to return results of type "file" -;; -;; 3) we are adding the "file" and "cmdline" header arguments, if file -;; is omitted then the -V option is passed to the asy command for -;; interactive viewing - -;;; Requirements: - -;; - The asymptote program :: http://asymptote.sourceforge.net/ -;; -;; - asy-mode :: Major mode for editing asymptote files - -;;; Code: -(require 'ob) - -(defvar org-babel-tangle-lang-exts) -(add-to-list 'org-babel-tangle-lang-exts '("asymptote" . "asy")) - -(defvar org-babel-default-header-args:asymptote - '((:results . "file") (:exports . "results")) - "Default arguments when evaluating an Asymptote source block.") - -(defun org-babel-execute:asymptote (body params) - "Execute a block of Asymptote code. -This function is called by `org-babel-execute-src-block'." - (let* ((out-file (cdr (assq :file params))) - (format (or (file-name-extension out-file) - "pdf")) - (cmdline (cdr (assq :cmdline params))) - (in-file (org-babel-temp-file "asymptote-")) - (cmd - (concat "asy " - (if out-file - (concat - "-globalwrite -f " format - " -o " (org-babel-process-file-name out-file)) - "-V") - " " cmdline - " " (org-babel-process-file-name in-file)))) - (with-temp-file in-file - (insert (org-babel-expand-body:generic - body params - (org-babel-variable-assignments:asymptote params)))) - (message cmd) (shell-command cmd) - nil)) ;; signal that output has already been written to file - -(defun org-babel-prep-session:asymptote (_session _params) - "Return an error if the :session header argument is set. -Asymptote does not support sessions." - (error "Asymptote does not support sessions")) - -(defun org-babel-variable-assignments:asymptote (params) - "Return list of asymptote statements assigning the block's variables." - (mapcar #'org-babel-asymptote-var-to-asymptote - (org-babel--get-vars params))) - -(defun org-babel-asymptote-var-to-asymptote (pair) - "Convert an elisp value into an Asymptote variable. -The elisp value PAIR is converted into Asymptote code specifying -a variable of the same value." - (let ((var (car pair)) - (val (let ((v (cdr pair))) - (if (symbolp v) (symbol-name v) v)))) - (cond - ((integerp val) - (format "int %S=%S;" var val)) - ((floatp val) - (format "real %S=%S;" var val)) - ((stringp val) - (format "string %S=\"%s\";" var val)) - ((and (listp val) (not (listp (car val)))) - (let* ((type (org-babel-asymptote-define-type val)) - (fmt (if (eq 'string type) "\"%s\"" "%s")) - (vect (mapconcat (lambda (e) (format fmt e)) val ", "))) - (format "%s[] %S={%s};" type var vect))) - ((listp val) - (let* ((type (org-babel-asymptote-define-type val)) - (fmt (if (eq 'string type) "\"%s\"" "%s")) - (array (mapconcat (lambda (row) - (concat "{" - (mapconcat (lambda (e) (format fmt e)) - row ", ") - "}")) - val ","))) - (format "%S[][] %S={%s};" type var array)))))) - -(defun org-babel-asymptote-define-type (data) - "Determine type of DATA. - -DATA is a list. Return type as a symbol. - -The type is `string' if any element in DATA is a string. -Otherwise, it is either `real', if some elements are floats, or -`int'." - (letrec ((type 'int) - (find-type - (lambda (row) - (dolist (e row type) - (cond ((listp e) (setq type (funcall find-type e))) - ((stringp e) (throw 'exit 'string)) - ((floatp e) (setq type 'real))))))) - (catch 'exit (funcall find-type data)) type)) - -(provide 'ob-asymptote) - -;;; ob-asymptote.el ends here diff --git a/lisp/org/ob-awk.el b/lisp/org/ob-awk.el index b41d70f12ca..28e9d327576 100644 --- a/lisp/org/ob-awk.el +++ b/lisp/org/ob-awk.el @@ -3,6 +3,7 @@ ;; Copyright (C) 2011-2021 Free Software Foundation, Inc. ;; Author: Eric Schulte +;; Maintainer: Tyler Smith ;; Keywords: literate programming, reproducible research ;; Homepage: https://orgmode.org @@ -58,12 +59,12 @@ This function is called by `org-babel-execute-src-block'." (code-file (let ((file (org-babel-temp-file "awk-"))) (with-temp-file file (insert full-body)) file)) (stdin (let ((stdin (cdr (assq :stdin params)))) - (when stdin - (let ((tmp (org-babel-temp-file "awk-stdin-")) - (res (org-babel-ref-resolve stdin))) - (with-temp-file tmp - (insert (org-babel-awk-var-to-awk res))) - tmp)))) + (when stdin + (let ((tmp (org-babel-temp-file "awk-stdin-")) + (res (org-babel-ref-resolve stdin))) + (with-temp-file tmp + (insert (org-babel-awk-var-to-awk res))) + tmp)))) (cmd (mapconcat #'identity (append (list org-babel-awk-command diff --git a/lisp/org/ob-calc.el b/lisp/org/ob-calc.el index 39ebce10020..5962d387614 100644 --- a/lisp/org/ob-calc.el +++ b/lisp/org/ob-calc.el @@ -3,6 +3,7 @@ ;; Copyright (C) 2010-2021 Free Software Foundation, Inc. ;; Author: Eric Schulte +;; Maintainer: Tom Gillespie ;; Keywords: literate programming, reproducible research ;; Homepage: https://orgmode.org @@ -90,7 +91,7 @@ (save-excursion (with-current-buffer (get-buffer "*Calculator*") (prog1 - (calc-eval (calc-top 1)) + (calc-eval (calc-top 1)) (calc-pop 1))))) (defun org-babel-calc-maybe-resolve-var (el) diff --git a/lisp/org/ob-clojure.el b/lisp/org/ob-clojure.el index 9834509fb03..3b995d94ce8 100644 --- a/lisp/org/ob-clojure.el +++ b/lisp/org/ob-clojure.el @@ -3,6 +3,7 @@ ;; Copyright (C) 2009-2021 Free Software Foundation, Inc. ;; Author: Joel Boehland, Eric Schulte, Oleh Krehel, Frederick Giasson +;; Maintainer: Bastien Guerry ;; ;; Keywords: literate programming, reproducible research ;; Homepage: https://orgmode.org diff --git a/lisp/org/ob-comint.el b/lisp/org/ob-comint.el index b14849df691..20ae76fadc6 100644 --- a/lisp/org/ob-comint.el +++ b/lisp/org/ob-comint.el @@ -93,12 +93,7 @@ or user `keyboard-quit' during execution of body." (regexp-quote ,eoe-indicator) nil t) (re-search-forward comint-prompt-regexp nil t))))) - (accept-process-output (get-buffer-process (current-buffer))) - ;; thought the following this would allow async - ;; background running, but I was wrong... - ;; (run-with-timer .5 .5 'accept-process-output - ;; (get-buffer-process (current-buffer))) - ) + (accept-process-output (get-buffer-process (current-buffer)))) ;; replace cut dangling text (goto-char (process-mark (get-buffer-process (current-buffer)))) (insert dangling-text) @@ -135,7 +130,7 @@ statement (not large blocks of code)." (accept-process-output (get-buffer-process buffer))))) (defun org-babel-comint-eval-invisibly-and-wait-for-file - (buffer file string &optional period) + (buffer file string &optional period) "Evaluate STRING in BUFFER invisibly. Don't return until FILE exists. Code in STRING must ensure that FILE exists at end of evaluation." @@ -147,6 +142,171 @@ FILE exists at end of evaluation." (if (= (aref string (1- (length string))) ?\n) string (concat string "\n"))) (while (not (file-exists-p file)) (sit-for (or period 0.25)))) + +;;; Async evaluation + +(defvar-local org-babel-comint-async-indicator nil + "Regular expression that `org-babel-comint-async-filter' scans for. +It should have 2 parenthesized expressions, +e.g. \"org_babel_async_\\(start\\|end\\|file\\)_\\(.*\\)\". The +first parenthesized expression determines whether the token is +delimiting a result block, or whether the result is in a file. +If delimiting a block, the second expression gives a UUID for the +location to insert the result. Otherwise, the result is in a tmp +file, and the second expression gives the file name.") + +(defvar-local org-babel-comint-async-buffers nil + "List of Org mode buffers to check for Babel async output results.") + +(defvar-local org-babel-comint-async-file-callback nil + "Callback to clean and insert Babel async results from a temp file. +The callback function takes two arguments: the alist of params of the Babel +source block, and the name of the temp file.") + +(defvar-local org-babel-comint-async-chunk-callback nil + "Callback function to clean Babel async output results before insertion. +Its single argument is a string consisting of output from the +comint process. It should return a string that will be be passed +to `org-babel-insert-result'.") + +(defvar-local org-babel-comint-async-dangling nil + "Dangling piece of the last process output, in case +`org-babel-comint-async-indicator' is spread across multiple +comint outputs due to buffering.") + +(defun org-babel-comint-use-async (params) + "Determine whether to use session async evaluation. +PARAMS are the header arguments as passed to +`org-babel-execute:lang'." + (let ((async (assq :async params)) + (session (assq :session params))) + (and async + (not org-babel-exp-reference-buffer) + (not (equal (cdr async) "no")) + (not (equal (cdr session) "none"))))) + +(defun org-babel-comint-async-filter (string) + "Captures Babel async output from comint buffer back to Org mode buffers. +This function is added as a hook to `comint-output-filter-functions'. +STRING contains the output originally inserted into the comint buffer." + ;; Remove outdated Org mode buffers + (setq org-babel-comint-async-buffers + (cl-loop for buf in org-babel-comint-async-buffers + if (buffer-live-p buf) + collect buf)) + (let* ((indicator org-babel-comint-async-indicator) + (org-buffers org-babel-comint-async-buffers) + (file-callback org-babel-comint-async-file-callback) + (combined-string (concat org-babel-comint-async-dangling string)) + (new-dangling combined-string) + ;; list of UUID's matched by `org-babel-comint-async-indicator' + uuid-list) + (with-temp-buffer + (insert combined-string) + (goto-char (point-min)) + (while (re-search-forward indicator nil t) + ;; update dangling + (setq new-dangling (buffer-substring (point) (point-max))) + (cond ((equal (match-string 1) "end") + ;; save UUID for insertion later + (push (match-string 2) uuid-list)) + ((equal (match-string 1) "file") + ;; insert results from tmp-file + (let ((tmp-file (match-string 2))) + (cl-loop for buf in org-buffers + until + (with-current-buffer buf + (save-excursion + (goto-char (point-min)) + (when (search-forward tmp-file nil t) + (org-babel-previous-src-block) + (let* ((info (org-babel-get-src-block-info)) + (params (nth 2 info)) + (result-params + (cdr (assq :result-params params)))) + (org-babel-insert-result + (funcall file-callback + (nth + 2 (org-babel-get-src-block-info)) + tmp-file) + result-params info)) + t)))))))) + ;; Truncate dangling to only the most recent output + (when (> (length new-dangling) (length string)) + (setq new-dangling string))) + (setq-local org-babel-comint-async-dangling new-dangling) + (when uuid-list + ;; Search for results in the comint buffer + (save-excursion + (goto-char (point-max)) + (while uuid-list + (re-search-backward indicator) + (when (equal (match-string 1) "end") + (let* ((uuid (match-string-no-properties 2)) + (res-str-raw + (buffer-substring + ;; move point to beginning of indicator + (- (match-beginning 0) 1) + ;; find the matching start indicator + (cl-loop + do (re-search-backward indicator) + until (and (equal (match-string 1) "start") + (equal (match-string 2) uuid)) + finally return (+ 1 (match-end 0))))) + ;; Apply callback to clean up the result + (res-str (funcall org-babel-comint-async-chunk-callback + res-str-raw))) + ;; Search for uuid in associated org-buffers to insert results + (cl-loop for buf in org-buffers + until (with-current-buffer buf + (save-excursion + (goto-char (point-min)) + (when (search-forward uuid nil t) + (org-babel-previous-src-block) + (let* ((info (org-babel-get-src-block-info)) + (params (nth 2 info)) + (result-params + (cdr (assq :result-params params)))) + (org-babel-insert-result + res-str result-params info)) + t)))) + ;; Remove uuid from the list to search for + (setq uuid-list (delete uuid uuid-list))))))))) + +(defun org-babel-comint-async-register + (session-buffer org-buffer indicator-regexp + chunk-callback file-callback) + "Set local org-babel-comint-async variables in SESSION-BUFFER. +ORG-BUFFER is added to `org-babel-comint-async-buffers' if not +present. `org-babel-comint-async-indicator', +`org-babel-comint-async-chunk-callback', and +`org-babel-comint-async-file-callback' are set to +INDICATOR-REGEXP, CHUNK-CALLBACK, and FILE-CALLBACK +respectively." + (org-babel-comint-in-buffer session-buffer + (setq org-babel-comint-async-indicator indicator-regexp + org-babel-comint-async-chunk-callback chunk-callback + org-babel-comint-async-file-callback file-callback) + (unless (memq org-buffer org-babel-comint-async-buffers) + (setq org-babel-comint-async-buffers + (cons org-buffer org-babel-comint-async-buffers))) + (add-hook 'comint-output-filter-functions + 'org-babel-comint-async-filter nil t))) + +(defmacro org-babel-comint-async-delete-dangling-and-eval + (session-buffer &rest body) + "Remove dangling text in SESSION-BUFFER and evaluate BODY. +This is analogous to `org-babel-comint-with-output', but meant +for asynchronous output, and much shorter because inserting the +result is delegated to `org-babel-comint-async-filter'." + (declare (indent 1) (debug t)) + `(org-babel-comint-in-buffer ,session-buffer + (goto-char (process-mark (get-buffer-process (current-buffer)))) + (delete-region (point) (point-max)) + ,@body)) + (provide 'ob-comint) + + ;;; ob-comint.el ends here diff --git a/lisp/org/ob-coq.el b/lisp/org/ob-coq.el deleted file mode 100644 index c77e8c9af69..00000000000 --- a/lisp/org/ob-coq.el +++ /dev/null @@ -1,80 +0,0 @@ -;;; ob-coq.el --- Babel Functions for Coq -*- lexical-binding: t; -*- - -;; Copyright (C) 2010-2021 Free Software Foundation, Inc. - -;; Author: Eric Schulte -;; Keywords: literate programming, reproducible research -;; Homepage: https://orgmode.org - -;; This file is part of GNU Emacs. - -;; GNU Emacs is free software: you can redistribute it and/or modify -;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation, either version 3 of the License, or -;; (at your option) any later version. - -;; GNU Emacs is distributed in the hope that it will be useful, -;; but WITHOUT ANY WARRANTY; without even the implied warranty of -;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -;; GNU General Public License for more details. - -;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs. If not, see . - -;;; Commentary: - -;; Rudimentary support for evaluating Coq code blocks. Currently only -;; session evaluation is supported. Requires both coq.el and -;; coq-inferior.el, both of which are distributed with Coq. -;; -;; https://coq.inria.fr/ - -;;; Code: -(require 'ob) - -(declare-function run-coq "ext:coq-inferior.el" (cmd)) -(declare-function coq-proc "ext:coq-inferior.el" ()) - -(defvar coq-program-name "coqtop" - "Name of the coq toplevel to run.") - -(defvar org-babel-coq-buffer "*coq*" - "Buffer in which to evaluate coq code blocks.") - -(defun org-babel-coq-clean-prompt (string) - (if (string-match "^[^[:space:]]+ < " string) - (substring string 0 (match-beginning 0)) - string)) - -(defun org-babel-execute:coq (body params) - (let ((full-body (org-babel-expand-body:generic body params)) - (session (org-babel-coq-initiate-session)) - (pt (lambda () - (marker-position - (process-mark (get-buffer-process (current-buffer))))))) - (org-babel-coq-clean-prompt - (org-babel-comint-in-buffer session - (let ((start (funcall pt))) - (with-temp-buffer - (insert full-body) - (comint-send-region (coq-proc) (point-min) (point-max)) - (comint-send-string (coq-proc) - (if (string= (buffer-substring (- (point-max) 1) (point-max)) ".") - "\n" - ".\n"))) - (while (equal start (funcall pt)) (sleep-for 0.1)) - (buffer-substring start (funcall pt))))))) - -(defun org-babel-coq-initiate-session () - "Initiate a coq session. -If there is not a current inferior-process-buffer in SESSION then -create one. Return the initialized session." - (unless (fboundp 'run-coq) - (error "`run-coq' not defined, load coq-inferior.el")) - (save-window-excursion (run-coq coq-program-name)) - (sit-for 0.1) - (get-buffer org-babel-coq-buffer)) - -(provide 'ob-coq) - -;;; ob-coq.el ends here diff --git a/lisp/org/ob-core.el b/lisp/org/ob-core.el index b1fd6943716..06a2a88cd49 100644 --- a/lisp/org/ob-core.el +++ b/lisp/org/ob-core.el @@ -290,9 +290,9 @@ environment, to override this check." (format "Evaluate this %s code block%son your system? " lang name-string))) (progn - (message "Evaluation of this %s code block%sis aborted." - lang name-string) - nil))) + (message "Evaluation of this %s code block%sis aborted." + lang name-string) + nil))) (x (error "Unexpected value `%s' from `org-babel-check-confirm-evaluate'" x))))) ;;;###autoload @@ -472,7 +472,35 @@ For the format of SAFE-LIST, see `org-babel-safe-header-args'." (defvar org-babel-default-header-args '((:session . "none") (:results . "replace") (:exports . "code") (:cache . "no") (:noweb . "no") (:hlines . "no") (:tangle . "no")) - "Default arguments to use when evaluating a source block.") + "Default arguments to use when evaluating a source block. + +This is a list in which each element is an alist. Each key +corresponds to a header argument, and each value to that header's +value. The value can either be a string or a closure that +evaluates to a string. The closure is evaluated when the source +block is being evaluated (e.g. during execution or export), with +point at the source block. It is not possible to use an +arbitrary function symbol (e.g. 'some-func), since org uses +lexical binding. To achieve the same functionality, call the +function within a closure (e.g. (lambda () (some-func))). + +To understand how closures can be used as default header +arguments, imagine you'd like to set the file name output of a +latex source block to a sha1 of its contents. We could achieve +this with: + +(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))))) + +Because the closure is evaluated with point at the source block, +the call to `org-element-at-point' above will always retrieve +information about the current source block.") + (put 'org-babel-default-header-args 'safe-local-variable (org-babel-header-args-safe-fn org-babel-safe-header-args)) @@ -538,7 +566,7 @@ to raise errors for all languages.") "Number of initial characters to show of a hidden results hash.") (defvar org-babel-after-execute-hook nil - "Hook for functions to be called after `org-babel-execute-src-block'") + "Hook for functions to be called after `org-babel-execute-src-block'.") (defun org-babel-named-src-block-regexp-for-name (&optional name) "Generate a regexp used to match a source block named NAME. @@ -581,7 +609,17 @@ multiple blocks are being executed (e.g., in chained execution through use of the :var header argument) this marker points to the outer-most code block.") -(defvar *this*) +(defun org-babel-eval-headers (headers) + "Compute header list set with HEADERS. + +Evaluate all header arguments set to functions prior to returning +the list of header arguments." + (let ((lst nil)) + (dolist (elem headers) + (if (and (cdr elem) (functionp (cdr elem))) + (push `(,(car elem) . ,(funcall (cdr elem))) lst) + (push elem lst))) + (reverse lst))) (defun org-babel-get-src-block-info (&optional light datum) "Extract information from a source block or inline source block. @@ -646,6 +684,16 @@ a list with the following pattern: (replace-regexp-in-string (org-src-coderef-regexp coderef) "" expand nil nil 1)))) +(defun org-babel--file-desc (params result) + "Retrieve file description." + (pcase (assq :file-desc params) + (`nil nil) + (`(:file-desc) result) + (`(:file-desc . ,(and (pred stringp) val)) val))) + +(defvar *this*) ; Dynamically bound in `org-babel-execute-src-block' + ; and `org-babel-read' + ;;;###autoload (defun org-babel-execute-src-block (&optional arg info params) "Execute the current source code block. @@ -749,8 +797,7 @@ block." (let ((*this* (if (not file) result (org-babel-result-to-file file - (let ((desc (assq :file-desc params))) - (and desc (or (cdr desc) result))))))) + (org-babel--file-desc params result))))) (setq result (org-babel-ref-resolve post)) (when file (setq result-params (remove "file" result-params)))))) @@ -802,27 +849,6 @@ arguments and pop open the results in a preview buffer." expanded (concat "*Org-Babel Preview " (buffer-name) "[ " lang " ]*")) expanded))) -(defun org-babel-edit-distance (s1 s2) - "Return the edit (levenshtein) distance between strings S1 S2." - (let* ((l1 (length s1)) - (l2 (length s2)) - (dist (vconcat (mapcar (lambda (_) (make-vector (1+ l2) nil)) - (number-sequence 1 (1+ l1))))) - (in (lambda (i j) (aref (aref dist i) j)))) - (setf (aref (aref dist 0) 0) 0) - (dolist (j (number-sequence 1 l2)) - (setf (aref (aref dist 0) j) j)) - (dolist (i (number-sequence 1 l1)) - (setf (aref (aref dist i) 0) i) - (dolist (j (number-sequence 1 l2)) - (setf (aref (aref dist i) j) - (min - (1+ (funcall in (1- i) j)) - (1+ (funcall in i (1- j))) - (+ (if (equal (aref s1 (1- i)) (aref s2 (1- j))) 0 1) - (funcall in (1- i) (1- j))))))) - (funcall in l1 l2))) - (defun org-babel-combine-header-arg-lists (original &rest others) "Combine a number of lists of header argument names and arguments." (let ((results (copy-sequence original))) @@ -851,7 +877,7 @@ arguments and pop open the results in a preview buffer." (match-string 4)))))) (dolist (name names) (when (and (not (string= header name)) - (<= (org-babel-edit-distance header name) too-close) + (<= (org-string-distance header name) too-close) (not (member header names))) (error "Supplied header \"%S\" is suspiciously close to \"%S\"" header name)))) @@ -1446,7 +1472,7 @@ portions of results lines." ;; Remove overlays when changing major mode (add-hook 'org-mode-hook (lambda () (add-hook 'change-major-mode-hook - #'org-babel-show-result-all 'append 'local))) + #'org-babel-show-result-all 'append 'local))) (defun org-babel-params-from-properties (&optional lang no-eval) "Retrieve source block parameters specified as properties. @@ -1550,11 +1576,11 @@ balanced instances of \"[ \t]:\", set ALTS to ((32 9) . 58)." (first= (lambda (str) (= ch (aref str 0))))) (reverse (cl-reduce (lambda (acc el) - (let ((head (car acc))) - (if (and head (or (funcall last= head) (funcall first= el))) - (cons (concat head el) (cdr acc)) - (cons el acc)))) - list :initial-value nil)))) + (let ((head (car acc))) + (if (and head (or (funcall last= head) (funcall first= el))) + (cons (concat head el) (cdr acc)) + (cons el acc)))) + list :initial-value nil)))) (defun org-babel-parse-header-arguments (string &optional no-eval) "Parse header arguments in STRING. @@ -1628,7 +1654,7 @@ shown below. (t 'value)))) (cl-remove-if (lambda (x) (memq (car x) '(:colname-names :rowname-names :result-params - :result-type :var))) + :result-type :var))) params)))) ;; row and column names @@ -1698,9 +1724,12 @@ of the vars, cnames and rnames." (list (mapcar (lambda (var) - (when (listp (cdr var)) + (when (proper-list-p (cdr var)) (when (and (not (equal colnames "no")) - (or colnames (and (eq (nth 1 (cdr var)) 'hline) + ;; Compatibility note: avoid `length>', which + ;; isn't available until Emacs 28. + (or colnames (and (> (length (cdr var)) 1) + (eq (nth 1 (cdr var)) 'hline) (not (member 'hline (cddr (cdr var))))))) (let ((both (org-babel-get-colnames (cdr var)))) (setq cnames (cons (cons (car var) (cdr both)) @@ -1720,7 +1749,7 @@ of the vars, cnames and rnames." (defun org-babel-reassemble-table (table colnames rownames) "Add column and row names to a table. Given a TABLE and set of COLNAMES and ROWNAMES add the names -to the table for reinsertion to org-mode." +to the table for reinsertion to `org-mode'." (if (listp table) (let ((table (if (and rownames (= (length table) (length rownames))) (org-babel-put-rownames table rownames) table))) @@ -1755,7 +1784,7 @@ If the point is not on a source block then return nil." "Go to the beginning of the current code block." (interactive) (let ((head (org-babel-where-is-src-block-head))) - (if head (goto-char head) (error "Not currently in a code block")))) + (if head (goto-char head) (error "Not currently in a code block")))) ;;;###autoload (defun org-babel-goto-named-src-block (name) @@ -2199,6 +2228,10 @@ silent -- no results are inserted into the Org buffer but ingested by Emacs (a potentially time consuming process). +none ---- no results are inserted into the Org buffer nor + echoed to the minibuffer. they are not processed into + Emacs-lisp objects at all. + file ---- the results are interpreted as a file path, and are inserted into the buffer using the Org file syntax. @@ -2256,9 +2289,8 @@ INFO may provide the values of these header arguments (in the (setq result (org-no-properties result)) (when (member "file" result-params) (setq result (org-babel-result-to-file - result (when (assq :file-desc (nth 2 info)) - (or (cdr (assq :file-desc (nth 2 info))) - result)))))) + result + (org-babel--file-desc (nth 2 info) result))))) ((listp result)) (t (setq result (format "%S" result)))) (if (and result-params (member "silent" result-params)) @@ -2324,7 +2356,7 @@ INFO may provide the values of these header arguments (in the (if results-switches (concat " " results-switches) "")) (let ((wrap (lambda (start finish &optional no-escape no-newlines - inline-start inline-finish) + inline-start inline-finish) (when inline (setq start inline-start) (setq finish inline-finish) @@ -2553,8 +2585,9 @@ in the buffer." (let ((element (org-element-at-point))) (if (memq (org-element-type element) ;; Possible results types. - '(drawer example-block export-block fixed-width item - plain-list special-block src-block table)) + '(drawer example-block export-block fixed-width + special-block src-block item plain-list table + latex-environment)) (save-excursion (goto-char (min (point-max) ;for narrowed buffers (org-element-property :end element))) @@ -2570,9 +2603,9 @@ file's directory then expand relative links." (let ((same-directory? (and (buffer-file-name (buffer-base-buffer)) (not (string= (expand-file-name default-directory) - (expand-file-name - (file-name-directory - (buffer-file-name (buffer-base-buffer))))))))) + (expand-file-name + (file-name-directory + (buffer-file-name (buffer-base-buffer))))))))) (format "[[file:%s]%s]" (if (and default-directory (buffer-file-name (buffer-base-buffer)) same-directory?) @@ -2706,12 +2739,17 @@ parameters when merging lists." results-exclusive-groups results (split-string - (if (stringp value) value (eval value t)))))) + (cond ((stringp value) value) + ((functionp value) (funcall value)) + (t (eval value t))))))) (`(:exports . ,value) (setq exports (funcall merge exports-exclusive-groups exports - (split-string (or value ""))))) + (split-string + (cond ((and value (functionp value)) (funcall value)) + (value value) + (t "")))))) ;; Regular keywords: any value overwrites the previous one. (_ (setq params (cons pair (assq-delete-all (car pair) params))))))) ;; Handle `:var' and clear out colnames and rownames for replaced @@ -2726,14 +2764,14 @@ parameters when merging lists." (cdr (assq param params)))) (setq params (cl-remove-if (lambda (pair) (and (equal (car pair) param) - (null (cdr pair)))) + (null (cdr pair)))) params))))) ;; Handle other special keywords, which accept multiple values. (setq params (nconc (list (cons :results (mapconcat #'identity results " ")) (cons :exports (mapconcat #'identity exports " "))) params)) ;; Return merged params. - params)) + (org-babel-eval-headers params))) (defun org-babel-noweb-p (params context) "Check if PARAMS require expansion in CONTEXT. @@ -2842,8 +2880,6 @@ block but are passed literally to the \"example-block\"." (setq cache nil) (let ((raw (org-babel-ref-resolve id))) (if (stringp raw) raw (format "%S" raw)))) - ;; Retrieve from the Library of Babel. - ((nth 2 (assoc-string id org-babel-library-of-babel))) ;; Return the contents of headlines literally. ((org-babel-ref-goto-headline-id id) (org-babel-ref-headline-body)) @@ -2856,6 +2892,8 @@ block but are passed literally to the \"example-block\"." (not (org-in-commented-heading-p)) (funcall expand-body (org-babel-get-src-block-info t)))))) + ;; Retrieve from the Library of Babel. + ((nth 2 (assoc-string id org-babel-library-of-babel))) ;; All Noweb references were cached in a previous ;; run. Extract the information from the cache. ((hash-table-p cache) @@ -2976,7 +3014,7 @@ block but are passed literally to the \"example-block\"." (defun org-babel-read (cell &optional inhibit-lisp-eval) "Convert the string value of CELL to a number if appropriate. -Otherwise if CELL looks like lisp (meaning it starts with a +Otherwise if CELL looks like Lisp (meaning it starts with a \"(\", \"\\='\", \"\\=`\" or a \"[\") then read and evaluate it as lisp, otherwise return it unmodified as a string. Optional argument INHIBIT-LISP-EVAL inhibits lisp evaluation for @@ -3148,7 +3186,7 @@ For the format of SAFE-LIST, see `org-babel-safe-header-args'." (and entry (consp entry) (cond ((functionp (cdr entry)) - (funcall (cdr entry) (cdr pair))) + (funcall (cdr entry) (cdr pair))) ((listp (cdr entry)) (member (cdr pair) (cdr entry))) (t nil))))))) @@ -3168,10 +3206,10 @@ Otherwise, the :file parameter is treated as a full file name, and the output file name is the directory (as calculated above) plus the parameter value." (let* ((file-cons (assq :file params)) - (file-ext-cons (assq :file-ext params)) - (file-ext (cdr-safe file-ext-cons)) - (dir (cdr-safe (assq :output-dir params))) - fname) + (file-ext-cons (assq :file-ext params)) + (file-ext (cdr-safe file-ext-cons)) + (dir (cdr-safe (assq :output-dir params))) + fname) ;; create the output-dir if it does not exist (when dir (make-directory dir t)) diff --git a/lisp/org/ob-dot.el b/lisp/org/ob-dot.el index d13261b340e..8e05a59f207 100644 --- a/lisp/org/ob-dot.el +++ b/lisp/org/ob-dot.el @@ -3,6 +3,7 @@ ;; Copyright (C) 2009-2021 Free Software Foundation, Inc. ;; Author: Eric Schulte +;; Maintainer: Justin Abrahms ;; Keywords: literate programming, reproducible research ;; Homepage: https://orgmode.org @@ -25,7 +26,7 @@ ;; Org-Babel support for evaluating dot source code. ;; -;; For information on dot see http://www.graphviz.org/ +;; For information on dot see https://www.graphviz.org/ ;; ;; This differs from most standard languages in that ;; diff --git a/lisp/org/ob-ebnf.el b/lisp/org/ob-ebnf.el deleted file mode 100644 index 58666a4ded0..00000000000 --- a/lisp/org/ob-ebnf.el +++ /dev/null @@ -1,81 +0,0 @@ -;;; ob-ebnf.el --- Babel Functions for EBNF -*- lexical-binding: t; -*- - -;; Copyright (C) 2013-2021 Free Software Foundation, Inc. - -;; Author: Michael Gauland -;; Keywords: literate programming, reproducible research -;; Homepage: https://orgmode.org - -;; This file is part of GNU Emacs. - -;; GNU Emacs is free software: you can redistribute it and/or modify -;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation, either version 3 of the License, or -;; (at your option) any later version. - -;; GNU Emacs is distributed in the hope that it will be useful, -;; but WITHOUT ANY WARRANTY; without even the implied warranty of -;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -;; GNU General Public License for more details. - -;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs. If not, see . - -;;; Commentary: - -;; Org-Babel support for using ebnf2ps to generate encapsulated postscript -;; railroad diagrams. It recognizes these arguments: -;; -;; :file is required; it must include the extension '.eps.' All the rules -;; in the block will be drawn in the same file. This is done by -;; inserting a '[' comment at the start of the block (see the -;; documentation for ebnf-eps-buffer for more information). -;; -;; :style specifies a value in ebnf-style-database. This provides the -;; ability to customize the output. The style can also specify the -;; grammar syntax (by setting ebnf-syntax); note that only ebnf, -;; iso-ebnf, and yacc are supported by this file. - -;;; Requirements: - -;;; Code: -(require 'ob) -(require 'ebnf2ps) - -;; optionally declare default header arguments for this language -(defvar org-babel-default-header-args:ebnf '((:style . nil))) - -;; Use ebnf-eps-buffer to produce an encapsulated postscript file. -;; -(defun org-babel-execute:ebnf (body params) - "Execute a block of Ebnf code with org-babel. -This function is called by `org-babel-execute-src-block'." - (save-excursion - (let* ((dest-file (cdr (assq :file params))) - (dest-dir (file-name-directory dest-file)) - (dest-root (file-name-sans-extension - (file-name-nondirectory dest-file))) - (style (cdr (assq :style params))) - (result nil)) - (with-temp-buffer - (when style (ebnf-push-style style)) - (let ((comment-format - (cond ((string= ebnf-syntax 'yacc) "/*%s*/") - ((string= ebnf-syntax 'ebnf) ";%s") - ((string= ebnf-syntax 'iso-ebnf) "(*%s*)") - (t (setq result - (format "EBNF error: format %s not supported." - ebnf-syntax)))))) - (setq ebnf-eps-prefix dest-dir) - (insert (format comment-format (format "[%s" dest-root))) - (newline) - (insert body) - (newline) - (insert (format comment-format (format "]%s" dest-root))) - (ebnf-eps-buffer) - (when style (ebnf-pop-style)))) - result))) - -(provide 'ob-ebnf) - -;;; ob-ebnf.el ends here diff --git a/lisp/org/ob-eshell.el b/lisp/org/ob-eshell.el index 6ae0fc613dd..d74c4fc43f9 100644 --- a/lisp/org/ob-eshell.el +++ b/lisp/org/ob-eshell.el @@ -3,8 +3,9 @@ ;; Copyright (C) 2018-2021 Free Software Foundation, Inc. ;; Author: stardiviner +;; Maintainer: stardiviner +;; Homepage: https://github.com/stardiviner/ob-eshell ;; Keywords: literate programming, reproducible research -;; Homepage: https://orgmode.org ;; This file is part of GNU Emacs. diff --git a/lisp/org/ob-eval.el b/lisp/org/ob-eval.el index b0fca7bd95b..cfd80222550 100644 --- a/lisp/org/ob-eval.el +++ b/lisp/org/ob-eval.el @@ -41,20 +41,22 @@ (display-buffer buf)) (message "Babel evaluation exited with code %S" exit-code)) -(defun org-babel-eval (cmd body) - "Run CMD on BODY. -If CMD succeeds then return its results, otherwise display -STDERR with `org-babel-eval-error-notify'." - (let ((err-buff (get-buffer-create " *Org-Babel Error*")) exit-code) - (with-current-buffer err-buff (erase-buffer)) +(defun org-babel-eval (command query) + "Run COMMAND on QUERY. +Writes QUERY into a temp-buffer that is processed with +`org-babel--shell-command-on-region'. If COMMAND succeeds then return +its results, otherwise display STDERR with +`org-babel-eval-error-notify'." + (let ((error-buffer (get-buffer-create " *Org-Babel Error*")) exit-code) + (with-current-buffer error-buffer (erase-buffer)) (with-temp-buffer - (insert body) + (insert query) (setq exit-code (org-babel--shell-command-on-region - (point-min) (point-max) cmd err-buff)) + command error-buffer)) (if (or (not (numberp exit-code)) (> exit-code 0)) (progn - (with-current-buffer err-buff + (with-current-buffer error-buffer (org-babel-eval-error-notify exit-code (buffer-string))) (save-excursion (when (get-buffer org-babel-error-buffer-name) @@ -71,26 +73,19 @@ STDERR with `org-babel-eval-error-notify'." (with-temp-buffer (insert-file-contents file) (buffer-string))) -(defun org-babel--shell-command-on-region (start end command error-buffer) +(defun org-babel--shell-command-on-region (command error-buffer) "Execute COMMAND in an inferior shell with region as input. +Stripped down version of `shell-command-on-region' for internal use in +Babel only. This lets us work around errors in the original function +in various versions of Emacs. This expects the query to be run to be +in the current temp buffer. This is written into +input-file. ERROR-BUFFER is the name of the file which +`org-babel-eval' has created to use for any error messages that are +returned." -Stripped down version of shell-command-on-region for internal use -in Babel only. This lets us work around errors in the original -function in various versions of Emacs. -" (let ((input-file (org-babel-temp-file "ob-input-")) (error-file (if error-buffer (org-babel-temp-file "ob-error-") nil)) - ;; Unfortunately, `executable-find' does not support file name - ;; handlers. Therefore, we could use it in the local case - ;; only. - (shell-file-name - (cond ((and (not (file-remote-p default-directory)) - (executable-find shell-file-name)) - shell-file-name) - ((file-executable-p - (concat (file-remote-p default-directory) shell-file-name)) - shell-file-name) - ("/bin/sh"))) + (shell-file-name (org-babel--get-shell-file-name)) exit-status) ;; There is an error in `process-file' when `error-file' exists. ;; This is fixed in Emacs trunk as of 2012-12-21; let's use this @@ -99,18 +94,13 @@ function in various versions of Emacs. (delete-file error-file)) ;; we always call this with 'replace, remove conditional ;; Replace specified region with output from command. - (let ((swap (< start end))) - (goto-char start) - (push-mark (point) 'nomsg) - (write-region start end input-file) - (delete-region start end) - (setq exit-status - (process-file shell-file-name input-file - (if error-file - (list t error-file) - t) - nil shell-command-switch command)) - (when swap (exchange-point-and-mark))) + (org-babel--write-temp-buffer-input-file input-file) + (setq exit-status + (process-file shell-file-name input-file + (if error-file + (list t error-file) + t) + nil shell-command-switch command)) (when (and input-file (file-exists-p input-file) ;; bind org-babel--debug-input around the call to keep @@ -135,6 +125,16 @@ function in various versions of Emacs. (delete-file error-file)) exit-status)) +(defun org-babel--write-temp-buffer-input-file (input-file) + "Write the contents of the current temp buffer into INPUT-FILE." + (let ((start (point-min)) + (end (point-max))) + (goto-char start) + (push-mark (point) 'nomsg) + (write-region start end input-file) + (delete-region start end) + (exchange-point-and-mark))) + (defun org-babel-eval-wipe-error-buffer () "Delete the contents of the Org code block error buffer. This buffer is named by `org-babel-error-buffer-name'." @@ -142,6 +142,19 @@ This buffer is named by `org-babel-error-buffer-name'." (with-current-buffer org-babel-error-buffer-name (delete-region (point-min) (point-max))))) +(defun org-babel--get-shell-file-name () + "Return system `shell-file-name', defaulting to /bin/sh. +Unfortunately, `executable-find' does not support file name +handlers. Therefore, we could use it in the local case only." + ;; FIXME: This is generic enough that it should probably be in emacs, not org-mode + (cond ((and (not (file-remote-p default-directory)) + (executable-find shell-file-name)) + shell-file-name) + ((file-executable-p + (concat (file-remote-p default-directory) shell-file-name)) + shell-file-name) + ("/bin/sh"))) + (provide 'ob-eval) ;;; ob-eval.el ends here diff --git a/lisp/org/ob-exp.el b/lisp/org/ob-exp.el index e851ff624a7..d10d228eba8 100644 --- a/lisp/org/ob-exp.el +++ b/lisp/org/ob-exp.el @@ -216,8 +216,11 @@ this template." (delete-region begin end) (insert replacement))))) ((or `babel-call `inline-babel-call) - (org-babel-exp-do-export (org-babel-lob-get-info element) - 'lob) + (org-babel-exp-do-export + (or (org-babel-lob-get-info element) + (user-error "Unknown Babel reference: %s" + (org-element-property :call element))) + 'lob) (let ((rep (org-fill-template org-babel-exp-call-line-template @@ -289,11 +292,11 @@ this template." "Return a string with the exported content of a code block. The function respects the value of the :exports header argument." (let ((silently (lambda () (let ((session (cdr (assq :session (nth 2 info))))) - (unless (equal "none" session) - (org-babel-exp-results info type 'silent))))) + (unless (equal "none" session) + (org-babel-exp-results info type 'silent))))) (clean (lambda () (if (eq type 'inline) - (org-babel-remove-inline-result) - (org-babel-remove-result info))))) + (org-babel-remove-inline-result) + (org-babel-remove-result info))))) (pcase (or (cdr (assq :exports (nth 2 info))) "code") ("none" (funcall silently) (funcall clean) "") ("code" (funcall silently) (funcall clean) (org-babel-exp-code info type)) @@ -357,9 +360,12 @@ replaced with its value." (org-fill-template (if (eq type 'inline) org-babel-exp-inline-code-template - org-babel-exp-code-template) + org-babel-exp-code-template) `(("lang" . ,(nth 0 info)) - ("body" . ,(org-escape-code-in-string (nth 1 info))) + ;; Inline source code should not be escaped. + ("body" . ,(let ((body (nth 1 info))) + (if (eq type 'inline) body + (org-escape-code-in-string body)))) ("switches" . ,(let ((f (nth 3 info))) (and (org-string-nw-p f) (concat " " f)))) ("flags" . ,(let ((f (assq :flags (nth 2 info)))) @@ -390,10 +396,10 @@ inhibit insertion of results into the buffer." (setf (nth 1 info) body) (setf (nth 2 info) (org-babel-exp--at-source - (org-babel-process-params - (org-babel-merge-params - (nth 2 info) - `((:results . ,(if silent "silent" "replace"))))))) + (org-babel-process-params + (org-babel-merge-params + (nth 2 info) + `((:results . ,(if silent "silent" "replace"))))))) (pcase type (`block (org-babel-execute-src-block nil info)) (`inline diff --git a/lisp/org/ob-forth.el b/lisp/org/ob-forth.el index 3b521bc4d95..74dbc021700 100644 --- a/lisp/org/ob-forth.el +++ b/lisp/org/ob-forth.el @@ -75,8 +75,8 @@ This function is called by `org-babel-execute-src-block'." ((string= "\n:" case) ;; Report errors. (org-babel-eval-error-notify 1 - (buffer-substring - (+ (match-beginning 0) 1) (point-max))) + (buffer-substring + (+ (match-beginning 0) 1) (point-max))) nil)))) (split-string (org-trim (org-babel-expand-body:generic body params)) diff --git a/lisp/org/ob-fortran.el b/lisp/org/ob-fortran.el index 99afa0d963d..2e55498003b 100644 --- a/lisp/org/ob-fortran.el +++ b/lisp/org/ob-fortran.el @@ -40,9 +40,11 @@ (defvar org-babel-default-header-args:fortran '()) -(defvar org-babel-fortran-compiler "gfortran" - "fortran command used to compile a fortran source code file into an - executable.") +(defcustom org-babel-fortran-compiler "gfortran" + "Fortran command used to compile Fortran source code file." + :group 'org-babel + :package-version '(Org . "9.5") + :type 'string) (defun org-babel-execute:fortran (body params) "This function should only be called by `org-babel-execute:fortran'." @@ -155,7 +157,7 @@ of the same value." (format "real, parameter :: %S(%d) = %s\n" var (length val) (org-babel-fortran-transform-list val))) (t - (error "the type of parameter %s is not supported by ob-fortran" var))))) + (error "The type of parameter %s is not supported by ob-fortran" var))))) (defun org-babel-fortran-transform-list (val) "Return a fortran representation of enclose syntactic lists." diff --git a/lisp/org/ob-gnuplot.el b/lisp/org/ob-gnuplot.el index 6489c23f570..3c84e4da14f 100644 --- a/lisp/org/ob-gnuplot.el +++ b/lisp/org/ob-gnuplot.el @@ -3,6 +3,7 @@ ;; Copyright (C) 2009-2021 Free Software Foundation, Inc. ;; Author: Eric Schulte +;; Maintainer: Ihor Radchenko ;; Keywords: literate programming, reproducible research ;; Homepage: https://orgmode.org @@ -33,7 +34,7 @@ ;;; Requirements: -;; - gnuplot :: http://www.gnuplot.info/ +;; - gnuplot :: https://www.gnuplot.info/ ;; ;; - gnuplot-mode :: you can search the web for the latest active one. @@ -47,6 +48,8 @@ (declare-function gnuplot-send-string-to-gnuplot "ext:gnuplot-mode" (str txt)) (declare-function gnuplot-send-buffer-to-gnuplot "ext:gnuplot-mode" ()) +(defvar org-babel-temporary-directory) + (defvar org-babel-default-header-args:gnuplot '((:results . "file") (:exports . "results") (:session . nil)) "Default arguments to use when evaluating a gnuplot source block.") @@ -85,14 +88,29 @@ code." (cons (car pair) ;; variable name (let* ((val (cdr pair)) ;; variable value - (lp (listp val))) + (lp (proper-list-p val))) (if lp (org-babel-gnuplot-table-to-data (let* ((first (car val)) (tablep (or (listp first) (symbolp first)))) (if tablep val (mapcar 'list val))) (org-babel-temp-file "gnuplot-") params) - val)))) + (if (and (stringp val) + (file-remote-p val) ;; check if val is a remote file + (file-exists-p val)) ;; call to file-exists-p is slow, maybe remove it + (let* ((local-name (concat ;; create a unique filename to avoid multiple downloads + org-babel-temporary-directory + "/gnuplot/" + (file-remote-p val 'host) + (org-babel-local-file-name val)))) + (if (and (file-exists-p local-name) ;; only download file if remote is newer + (file-newer-than-file-p local-name val)) + local-name + (make-directory (file-name-directory local-name) t) + (copy-file val local-name t) + )) + val + ))))) (org-babel--get-vars params)))) (defun org-babel-expand-body:gnuplot (body params) diff --git a/lisp/org/ob-groovy.el b/lisp/org/ob-groovy.el index fa847dd0a2b..b3ff34aac3e 100644 --- a/lisp/org/ob-groovy.el +++ b/lisp/org/ob-groovy.el @@ -3,6 +3,7 @@ ;; Copyright (C) 2013-2021 Free Software Foundation, Inc. ;; Author: Miro Bezjak +;; Maintainer: Palak Mathur ;; Keywords: literate programming, reproducible research ;; Homepage: https://orgmode.org @@ -25,7 +26,7 @@ ;; Currently only supports the external execution. No session support yet. ;;; Requirements: -;; - Groovy language :: http://groovy.codehaus.org +;; - Groovy language :: https://groovy-lang.org ;; - Groovy major mode :: Can be installed from MELPA or ;; https://github.com/russel/Emacs-Groovy-Mode diff --git a/lisp/org/ob-haskell.el b/lisp/org/ob-haskell.el index d7ac1b04b36..971e1ce6af8 100644 --- a/lisp/org/ob-haskell.el +++ b/lisp/org/ob-haskell.el @@ -3,6 +3,7 @@ ;; Copyright (C) 2009-2021 Free Software Foundation, Inc. ;; Author: Eric Schulte +;; Maintainer: Lawrence Bottorff ;; Keywords: literate programming, reproducible research ;; Homepage: https://orgmode.org @@ -33,9 +34,9 @@ ;;; Requirements: -;; - haskell-mode: http://www.iro.umontreal.ca/~monnier/elisp/#haskell-mode -;; - inf-haskell: http://www.iro.umontreal.ca/~monnier/elisp/#haskell-mode -;; - (optionally) lhs2tex: http://people.cs.uu.nl/andres/lhs2tex/ +;; - haskell-mode: https://www.iro.umontreal.ca/~monnier/elisp/#haskell-mode +;; - inf-haskell: https://www.iro.umontreal.ca/~monnier/elisp/#haskell-mode +;; - (optionally) lhs2tex: https://people.cs.uu.nl/andres/lhs2tex/ ;;; Code: (require 'ob) @@ -69,11 +70,11 @@ a parameter, such as \"ghc -v\"." :package-version '(Org "9.4") :type 'string) -(defconst org-babel-header-args:haskell '(compile . :any) +(defconst org-babel-header-args:haskell '((compile . :any)) "Haskell-specific header arguments.") (defun org-babel-haskell-execute (body params) - "This function should only be called by `org-babel-execute:haskell'" + "This function should only be called by `org-babel-execute:haskell'." (let* ((tmp-src-file (org-babel-temp-file "Haskell-src-" ".hs")) (tmp-bin-file (org-babel-process-file-name diff --git a/lisp/org/ob-hledger.el b/lisp/org/ob-hledger.el deleted file mode 100644 index 48dcb8cea1a..00000000000 --- a/lisp/org/ob-hledger.el +++ /dev/null @@ -1,69 +0,0 @@ -;;; ob-hledger.el --- Babel Functions for hledger -*- lexical-binding: t; -*- - -;; Copyright (C) 2010-2021 Free Software Foundation, Inc. - -;; Author: Simon Michael -;; Keywords: literate programming, reproducible research, plain text accounting -;; Homepage: https://orgmode.org - -;; This file is part of GNU Emacs. - -;; GNU Emacs is free software: you can redistribute it and/or modify -;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation, either version 3 of the License, or -;; (at your option) any later version. - -;; GNU Emacs is distributed in the hope that it will be useful, -;; but WITHOUT ANY WARRANTY; without even the implied warranty of -;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -;; GNU General Public License for more details. - -;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs. If not, see . - -;;; Commentary: - -;; Babel support for evaluating hledger entries. -;; -;; Based on ob-ledger.el. -;; If the source block is empty, hledger will use a default journal file, -;; probably ~/.hledger.journal (it may not notice your $LEDGER_FILE env var). -;; So make ~/.hledger.journal a symbolic link to the real file if necessary. - -;; TODO Unit tests are more than welcome, too. - -;;; Code: -(require 'ob) - -(defvar org-babel-default-header-args:hledger - '((:results . "output") (:exports . "results") (:cmdline . "bal")) - "Default arguments to use when evaluating a hledger source block.") - -(defun org-babel-execute:hledger (body params) - "Execute a block of hledger entries with org-babel. -This function is called by `org-babel-execute-src-block'." - (message "executing hledger source code block") - (letrec ( ;(result-params (split-string (or (cdr (assq :results params)) ""))) - (cmdline (cdr (assq :cmdline params))) - (in-file (org-babel-temp-file "hledger-")) - (out-file (org-babel-temp-file "hledger-output-")) - (hledgercmd (concat "hledger" - (if (> (length body) 0) - (concat " -f " (org-babel-process-file-name in-file)) - "") - " " cmdline))) - (with-temp-file in-file (insert body)) -;; TODO This is calling for some refactoring: -;; (concat "hledger" (if ...) " " cmdline) -;; could be built only once and bound to a symbol. - (message "%s" hledgercmd) - (with-output-to-string - (shell-command (concat hledgercmd " > " (org-babel-process-file-name out-file)))) - (with-temp-buffer (insert-file-contents out-file) (buffer-string)))) - -(defun org-babel-prep-session:hledger (_session _params) - (error "hledger does not support sessions")) - -(provide 'ob-hledger) - -;;; ob-hledger.el ends here diff --git a/lisp/org/ob-io.el b/lisp/org/ob-io.el deleted file mode 100644 index 63d2b6cf35e..00000000000 --- a/lisp/org/ob-io.el +++ /dev/null @@ -1,105 +0,0 @@ -;;; ob-io.el --- Babel Functions for Io -*- lexical-binding: t; -*- - -;; Copyright (C) 2012-2021 Free Software Foundation, Inc. - -;; Author: Andrzej Lichnerowicz -;; Keywords: literate programming, reproducible research -;; Homepage: https://orgmode.org - -;; This file is part of GNU Emacs. - -;; GNU Emacs is free software: you can redistribute it and/or modify -;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation, either version 3 of the License, or -;; (at your option) any later version. - -;; GNU Emacs is distributed in the hope that it will be useful, -;; but WITHOUT ANY WARRANTY; without even the implied warranty of -;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -;; GNU General Public License for more details. - -;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs. If not, see . - -;;; Commentary: -;; Currently only supports the external execution. No session support yet. -;; :results output -- runs in scripting mode -;; :results output repl -- runs in repl mode - -;;; Requirements: -;; - Io language :: http://iolanguage.org/ -;; - Io major mode :: Can be installed from Io sources -;; https://github.com/stevedekorte/io/blob/master/extras/SyntaxHighlighters/Emacs/io-mode.el - -;;; Code: -(require 'ob) - -(defvar org-babel-tangle-lang-exts) ;; Autoloaded -(add-to-list 'org-babel-tangle-lang-exts '("io" . "io")) -(defvar org-babel-default-header-args:io '()) -(defvar org-babel-io-command "io" - "Name of the command to use for executing Io code.") - -(defun org-babel-execute:io (body params) - "Execute a block of Io code with org-babel. -This function is called by `org-babel-execute-src-block'." - (message "executing Io source code block") - (let* ((processed-params (org-babel-process-params params)) - (session (org-babel-io-initiate-session (nth 0 processed-params))) - (result-params (nth 2 processed-params)) - (result-type (cdr (assq :result-type params))) - (full-body (org-babel-expand-body:generic - body params)) - (result (org-babel-io-evaluate - session full-body result-type result-params))) - - (org-babel-reassemble-table - result - (org-babel-pick-name - (cdr (assq :colname-names params)) (cdr (assq :colnames params))) - (org-babel-pick-name - (cdr (assq :rowname-names params)) (cdr (assq :rownames params)))))) - -(defvar org-babel-io-wrapper-method - "( -%s -) asString print -") - - -(defun org-babel-io-evaluate (session body &optional result-type result-params) - "Evaluate BODY in external Io process. -If RESULT-TYPE equals `output' then return standard output as a string. -If RESULT-TYPE equals `value' then return the value of the last statement -in BODY as elisp." - (when session (error "Sessions are not (yet) supported for Io")) - (pcase result-type - (`output - (if (member "repl" result-params) - (org-babel-eval org-babel-io-command body) - (let ((src-file (org-babel-temp-file "io-"))) - (progn (with-temp-file src-file (insert body)) - (org-babel-eval - (concat org-babel-io-command " " src-file) ""))))) - (`value (let* ((src-file (org-babel-temp-file "io-")) - (wrapper (format org-babel-io-wrapper-method body))) - (with-temp-file src-file (insert wrapper)) - (let ((raw (org-babel-eval - (concat org-babel-io-command " " src-file) ""))) - (org-babel-result-cond result-params - raw - (org-babel-script-escape raw))))))) - -(defun org-babel-prep-session:io (_session _params) - "Prepare SESSION according to the header arguments specified in PARAMS." - (error "Sessions are not (yet) supported for Io")) - -(defun org-babel-io-initiate-session (&optional _session) - "If there is not a current inferior-process-buffer in SESSION -then create. Return the initialized session. Sessions are not -supported in Io." - nil) - -(provide 'ob-io) - -;;; ob-io.el ends here diff --git a/lisp/org/ob-java.el b/lisp/org/ob-java.el index b1d517e94aa..60ef33bc6e4 100644 --- a/lisp/org/ob-java.el +++ b/lisp/org/ob-java.el @@ -1,8 +1,10 @@ -;;; ob-java.el --- Babel Functions for Java -*- lexical-binding: t; -*- +;;; ob-java.el --- org-babel functions for java evaluation -*- lexical-binding: t -*- ;; Copyright (C) 2011-2021 Free Software Foundation, Inc. -;; Author: Eric Schulte +;; Authors: Eric Schulte +;; Dan Davison +;; Maintainer: Ian Martins ;; Keywords: literate programming, reproducible research ;; Homepage: https://orgmode.org @@ -23,8 +25,7 @@ ;;; Commentary: -;; Currently this only supports the external compilation and execution -;; of java code blocks (i.e., no session support). +;; Org-Babel support for evaluating java source code. ;;; Code: (require 'ob) @@ -32,52 +33,455 @@ (defvar org-babel-tangle-lang-exts) (add-to-list 'org-babel-tangle-lang-exts '("java" . "java")) +(defvar org-babel-temporary-directory) ; from ob-core + +(defvar org-babel-default-header-args:java '((:results . "output") + (:dir . ".")) + "Default header args for java source blocks. +The docs say functional mode should be the default [1], but +ob-java didn't originally support functional mode, so we keep +scripting mode as the default for now to maintain previous +behavior. + +Most languages write tempfiles to babel's temporary directory, +but ob-java originally had to write them to the current +directory, so we keep that as the default behavior. + +[1] https://orgmode.org/manual/Results-of-Evaluation.html") + +(defconst org-babel-header-args:java '((imports . :any)) + "Java-specific header arguments.") + (defcustom org-babel-java-command "java" "Name of the java command. -May be either a command in the path, like java -or an absolute path name, like /usr/local/bin/java -parameters may be used, like java -verbose" +May be either a command in the path, like java or an absolute +path name, like /usr/local/bin/java. Parameters may be used, +like java -verbose." :group 'org-babel - :version "24.3" + :package-version '(Org . "9.5") :type 'string) (defcustom org-babel-java-compiler "javac" "Name of the java compiler. -May be either a command in the path, like javac -or an absolute path name, like /usr/local/bin/javac -parameters may be used, like javac -verbose" +May be either a command in the path, like javac or an absolute +path name, like /usr/local/bin/javac. Parameters may be used, +like javac -verbose." + :group 'org-babel + :package-version '(Org . "9.5") + :type 'string) + +(defcustom org-babel-java-hline-to "null" + "Replace hlines in incoming tables with this when translating to java." :group 'org-babel - :version "24.3" + :package-version '(Org . "9.5") :type 'string) +(defcustom org-babel-java-null-to 'hline + "Replace `null' in java tables with this before returning." + :group 'org-babel + :package-version '(Org . "9.5") + :type 'symbol) + +(defconst org-babel-java--package-re (rx line-start (0+ space) "package" + (1+ space) (group (1+ (in alnum ?_ ?.))) ; capture the package name + (0+ space) ?\; line-end) + "Regexp for the package statement.") +(defconst org-babel-java--imports-re (rx line-start (0+ space) "import" + (opt (1+ space) "static") + (1+ space) (group (1+ (in alnum ?_ ?. ?*))) ; capture the fully qualified class name + (0+ space) ?\; line-end) + "Regexp for import statements.") +(defconst org-babel-java--class-re (rx line-start (0+ space) (opt (seq "public" (1+ space))) + "class" (1+ space) + (group (1+ (in alnum ?_))) ; capture the class name + (0+ space) ?{) + "Regexp for the class declaration.") +(defconst org-babel-java--main-re (rx line-start (0+ space) "public" + (1+ space) "static" + (1+ space) "void" + (1+ space) "main" + (0+ space) ?\( + (0+ space) "String" + (0+ space) (1+ (in alnum ?_ ?\[ ?\] space)) ; "[] args" or "args[]" + (0+ space) ?\) + (0+ space) (opt "throws" (1+ (in alnum ?_ ?, ?. space))) + ?{) + "Regexp for the main method declaration.") +(defconst org-babel-java--any-method-re (rx line-start + (0+ space) (opt (seq (1+ alnum) (1+ space))) ; visibility + (opt (seq "static" (1+ space))) ; binding + (1+ (in alnum ?_ ?\[ ?\])) ; return type + (1+ space) (1+ (in alnum ?_)) ; method name + (0+ space) ?\( + (0+ space) (0+ (in alnum ?_ ?\[ ?\] ?, space)) ; params + (0+ space) ?\) + (0+ space) (opt "throws" (1+ (in alnum ?_ ?, ?. space))) + ?{) + "Regexp for any method.") +(defconst org-babel-java--result-wrapper "\n public static String __toString(Object val) { + if (val instanceof String) { + return \"\\\"\" + val + \"\\\"\"; + } else if (val == null) { + return \"null\"; + } else if (val.getClass().isArray()) { + StringBuffer sb = new StringBuffer(); + Object[] vals = (Object[])val; + sb.append(\"[\"); + for (int ii=0; ii