From 48c8858259c80a5ff12a24ad549949c217b7378e Mon Sep 17 00:00:00 2001 From: Andreas Gerler Date: Sun, 22 Dec 2024 12:51:44 +0100 Subject: [PATCH] update org Signed-off-by: Andreas Gerler --- bba.org | 4 +- elpa/org-9.6.7.signed | 1 - elpa/org-9.6.7/doc/org-version.inc | 3 - elpa/org-9.6.7/ob-maxima.el | 135 - elpa/org-9.6.7/ob-python.el | 464 -- elpa/org-9.6.7/org-pkg.el | 2 - elpa/org-9.7.17.signed | 1 + elpa/{org-9.6.7 => org-9.7.17}/.dir-locals.el | 2 +- elpa/{org-9.6.7 => org-9.7.17}/CONTRIBUTE.org | 4 +- elpa/{org-9.6.7 => org-9.7.17}/COPYING | 0 elpa/{org-9.6.7 => org-9.7.17}/Makefile | 40 +- elpa/{org-9.6.7 => org-9.7.17}/README-elpa | 8 +- elpa/{org-9.6.7 => org-9.7.17}/README.org | 5 +- elpa/{org-9.6.7 => org-9.7.17}/dir | 0 .../doc/.aspell.org.conf | 0 elpa/{org-9.6.7 => org-9.7.17}/doc/.nosearch | 0 .../doc/Documentation_Standards.org | 0 elpa/{org-9.6.7 => org-9.7.17}/doc/Makefile | 0 elpa/{org-9.6.7 => org-9.7.17}/doc/dir | 0 .../doc/doc-setup.org | 2 +- elpa/{org-9.6.7 => org-9.7.17}/doc/fdl.org | 0 .../doc/htmlxref.cnf | 0 .../doc/org-guide.org | 349 +- .../doc/org-manual.org | 2476 ++++--- elpa/org-9.7.17/doc/org-version.inc | 3 + elpa/{org-9.6.7 => org-9.7.17}/doc/org.texi | 2421 +++++-- .../{org-9.6.7 => org-9.7.17}/doc/orgcard.tex | 21 +- .../doc/orgguide.texi | 388 +- .../doc/pdflayout.sty | 0 .../{org-9.6.7 => org-9.7.17}/doc/texinfo.tex | 0 elpa/{org-9.6.7 => org-9.7.17}/etc/Makefile | 0 elpa/{org-9.6.7 => org-9.7.17}/etc/ORG-NEWS | 1744 ++++- elpa/{org-9.6.7 => org-9.7.17}/etc/csl/README | 0 .../etc/csl/chicago-author-date.csl | 0 .../etc/csl/locales-en-US.xml | 0 .../etc/styles/OrgOdtContentTemplate.xml | 0 .../etc/styles/OrgOdtStyles.xml | 0 .../etc/styles/README | 2 +- elpa/{org-9.6.7 => org-9.7.17}/local.mk | 2 +- elpa/{org-9.6.7 => org-9.7.17}/ob-C.el | 61 +- elpa/{org-9.6.7 => org-9.7.17}/ob-R.el | 58 +- elpa/{org-9.6.7 => org-9.7.17}/ob-awk.el | 20 +- elpa/{org-9.6.7 => org-9.7.17}/ob-calc.el | 36 +- elpa/{org-9.6.7 => org-9.7.17}/ob-clojure.el | 172 +- elpa/{org-9.6.7 => org-9.7.17}/ob-comint.el | 177 +- elpa/{org-9.6.7 => org-9.7.17}/ob-core.el | 790 +- elpa/{org-9.6.7 => org-9.7.17}/ob-css.el | 4 +- elpa/{org-9.6.7 => org-9.7.17}/ob-ditaa.el | 11 +- elpa/{org-9.6.7 => org-9.7.17}/ob-dot.el | 13 +- .../ob-emacs-lisp.el | 24 +- elpa/{org-9.6.7 => org-9.7.17}/ob-eshell.el | 16 +- elpa/{org-9.6.7 => org-9.7.17}/ob-eval.el | 19 +- elpa/{org-9.6.7 => org-9.7.17}/ob-exp.el | 448 +- elpa/{org-9.6.7 => org-9.7.17}/ob-forth.el | 7 +- elpa/{org-9.6.7 => org-9.7.17}/ob-fortran.el | 36 +- elpa/{org-9.6.7 => org-9.7.17}/ob-gnuplot.el | 44 +- elpa/{org-9.6.7 => org-9.7.17}/ob-groovy.el | 12 +- elpa/{org-9.6.7 => org-9.7.17}/ob-haskell.el | 226 +- elpa/{org-9.6.7 => org-9.7.17}/ob-java.el | 8 +- elpa/{org-9.6.7 => org-9.7.17}/ob-js.el | 17 +- elpa/{org-9.6.7 => org-9.7.17}/ob-julia.el | 37 +- elpa/{org-9.6.7 => org-9.7.17}/ob-latex.el | 36 +- elpa/{org-9.6.7 => org-9.7.17}/ob-lilypond.el | 125 +- elpa/{org-9.6.7 => org-9.7.17}/ob-lisp.el | 72 +- elpa/{org-9.6.7 => org-9.7.17}/ob-lob.el | 8 +- elpa/{org-9.6.7 => org-9.7.17}/ob-lua.el | 120 +- elpa/{org-9.6.7 => org-9.7.17}/ob-makefile.el | 5 +- elpa/{org-9.6.7 => org-9.7.17}/ob-matlab.el | 2 +- elpa/org-9.7.17/ob-maxima.el | 194 + elpa/{org-9.6.7 => org-9.7.17}/ob-ocaml.el | 9 +- elpa/{org-9.6.7 => org-9.7.17}/ob-octave.el | 43 +- elpa/{org-9.6.7 => org-9.7.17}/ob-org.el | 18 +- elpa/{org-9.6.7 => org-9.7.17}/ob-perl.el | 2 +- elpa/{org-9.6.7 => org-9.7.17}/ob-plantuml.el | 7 +- .../ob-processing.el | 9 +- elpa/org-9.7.17/ob-python.el | 577 ++ elpa/{org-9.6.7 => org-9.7.17}/ob-ref.el | 14 +- elpa/{org-9.6.7 => org-9.7.17}/ob-ruby.el | 58 +- elpa/{org-9.6.7 => org-9.7.17}/ob-sass.el | 2 +- elpa/{org-9.6.7 => org-9.7.17}/ob-scheme.el | 125 +- elpa/{org-9.6.7 => org-9.7.17}/ob-screen.el | 8 +- elpa/{org-9.6.7 => org-9.7.17}/ob-sed.el | 4 +- elpa/{org-9.6.7 => org-9.7.17}/ob-shell.el | 134 +- elpa/{org-9.6.7 => org-9.7.17}/ob-sql.el | 28 +- elpa/{org-9.6.7 => org-9.7.17}/ob-sqlite.el | 23 +- elpa/{org-9.6.7 => org-9.7.17}/ob-table.el | 26 +- elpa/{org-9.6.7 => org-9.7.17}/ob-tangle.el | 146 +- elpa/{org-9.6.7 => org-9.7.17}/ob.el | 4 +- elpa/{org-9.6.7 => org-9.7.17}/oc-basic.el | 192 +- elpa/{org-9.6.7 => org-9.7.17}/oc-biblatex.el | 40 +- elpa/{org-9.6.7 => org-9.7.17}/oc-bibtex.el | 4 +- elpa/{org-9.6.7 => org-9.7.17}/oc-csl.el | 188 +- elpa/{org-9.6.7 => org-9.7.17}/oc-natbib.el | 25 +- elpa/{org-9.6.7 => org-9.7.17}/oc.el | 226 +- elpa/{org-9.6.7 => org-9.7.17}/ol-bbdb.el | 14 +- elpa/{org-9.6.7 => org-9.7.17}/ol-bibtex.el | 70 +- elpa/{org-9.6.7 => org-9.7.17}/ol-docview.el | 17 +- elpa/{org-9.6.7 => org-9.7.17}/ol-doi.el | 5 +- elpa/{org-9.6.7 => org-9.7.17}/ol-eshell.el | 13 +- elpa/{org-9.6.7 => org-9.7.17}/ol-eww.el | 5 +- elpa/{org-9.6.7 => org-9.7.17}/ol-gnus.el | 40 +- elpa/{org-9.6.7 => org-9.7.17}/ol-info.el | 38 +- elpa/{org-9.6.7 => org-9.7.17}/ol-irc.el | 4 +- elpa/{org-9.6.7 => org-9.7.17}/ol-man.el | 54 +- elpa/{org-9.6.7 => org-9.7.17}/ol-mhe.el | 6 +- elpa/{org-9.6.7 => org-9.7.17}/ol-rmail.el | 6 +- elpa/{org-9.6.7 => org-9.7.17}/ol-w3m.el | 4 +- elpa/{org-9.6.7 => org-9.7.17}/ol.el | 711 +- elpa/{org-9.6.7 => org-9.7.17}/org-agenda.el | 2199 +++--- elpa/{org-9.6.7 => org-9.7.17}/org-archive.el | 34 +- .../org-attach-git.el | 2 +- elpa/{org-9.6.7 => org-9.7.17}/org-attach.el | 163 +- .../org-autoloads.el | 558 +- elpa/{org-9.6.7 => org-9.7.17}/org-capture.el | 118 +- elpa/{org-9.6.7 => org-9.7.17}/org-clock.el | 299 +- elpa/{org-9.6.7 => org-9.7.17}/org-colview.el | 255 +- elpa/{org-9.6.7 => org-9.7.17}/org-compat.el | 253 +- elpa/{org-9.6.7 => org-9.7.17}/org-crypt.el | 64 +- elpa/{org-9.6.7 => org-9.7.17}/org-ctags.el | 111 +- elpa/{org-9.6.7 => org-9.7.17}/org-cycle.el | 75 +- .../{org-9.6.7 => org-9.7.17}/org-datetree.el | 69 +- .../{org-9.6.7 => org-9.7.17}/org-duration.el | 211 +- elpa/org-9.7.17/org-element-ast.el | 1150 +++ elpa/{org-9.6.7 => org-9.7.17}/org-element.el | 6387 +++++++++-------- .../{org-9.6.7 => org-9.7.17}/org-entities.el | 33 +- elpa/{org-9.6.7 => org-9.7.17}/org-faces.el | 20 +- elpa/{org-9.6.7 => org-9.7.17}/org-feed.el | 16 +- .../org-fold-core.el | 360 +- elpa/{org-9.6.7 => org-9.7.17}/org-fold.el | 175 +- .../{org-9.6.7 => org-9.7.17}/org-footnote.el | 77 +- elpa/{org-9.6.7 => org-9.7.17}/org-goto.el | 30 +- elpa/{org-9.6.7 => org-9.7.17}/org-habit.el | 17 +- elpa/{org-9.6.7 => org-9.7.17}/org-id.el | 301 +- elpa/{org-9.6.7 => org-9.7.17}/org-indent.el | 19 +- .../org-inlinetask.el | 19 +- elpa/{org-9.6.7 => org-9.7.17}/org-keys.el | 162 +- elpa/{org-9.6.7 => org-9.7.17}/org-lint.el | 631 +- elpa/{org-9.6.7 => org-9.7.17}/org-list.el | 398 +- .../{org-9.6.7 => org-9.7.17}/org-loaddefs.el | 3154 ++------ elpa/{org-9.6.7 => org-9.7.17}/org-macro.el | 53 +- elpa/{org-9.6.7 => org-9.7.17}/org-macs.el | 585 +- elpa/{org-9.6.7 => org-9.7.17}/org-mobile.el | 20 +- elpa/{org-9.6.7 => org-9.7.17}/org-mouse.el | 49 +- elpa/{org-9.6.7 => org-9.7.17}/org-num.el | 17 +- .../org-pcomplete.el | 65 +- elpa/{org-9.6.7 => org-9.7.17}/org-persist.el | 675 +- elpa/org-9.7.17/org-pkg.el | 2 + elpa/{org-9.6.7 => org-9.7.17}/org-plot.el | 10 +- .../{org-9.6.7 => org-9.7.17}/org-protocol.el | 52 +- elpa/{org-9.6.7 => org-9.7.17}/org-refile.el | 207 +- elpa/{org-9.6.7 => org-9.7.17}/org-src.el | 358 +- elpa/{org-9.6.7 => org-9.7.17}/org-table.el | 616 +- elpa/{org-9.6.7 => org-9.7.17}/org-tempo.el | 10 +- elpa/{org-9.6.7 => org-9.7.17}/org-timer.el | 65 +- elpa/{org-9.6.7 => org-9.7.17}/org-version.el | 4 +- elpa/{org-9.6.7 => org-9.7.17}/org.el | 5511 ++++++++------ elpa/{org-9.6.7 => org-9.7.17}/org.info | 4590 +++++++----- elpa/{org-9.6.7 => org-9.7.17}/orgguide.info | 563 +- elpa/{org-9.6.7 => org-9.7.17}/ox-ascii.el | 138 +- elpa/{org-9.6.7 => org-9.7.17}/ox-beamer.el | 174 +- elpa/{org-9.6.7 => org-9.7.17}/ox-html.el | 325 +- .../{org-9.6.7 => org-9.7.17}/ox-icalendar.el | 429 +- .../ox-koma-letter.el | 30 +- elpa/{org-9.6.7 => org-9.7.17}/ox-latex.el | 684 +- elpa/{org-9.6.7 => org-9.7.17}/ox-man.el | 60 +- elpa/{org-9.6.7 => org-9.7.17}/ox-md.el | 72 +- elpa/{org-9.6.7 => org-9.7.17}/ox-odt.el | 324 +- elpa/{org-9.6.7 => org-9.7.17}/ox-org.el | 47 +- elpa/{org-9.6.7 => org-9.7.17}/ox-publish.el | 169 +- elpa/{org-9.6.7 => org-9.7.17}/ox-texinfo.el | 174 +- elpa/{org-9.6.7 => org-9.7.17}/ox.el | 1976 ++--- init.el | 4 +- 172 files changed, 29155 insertions(+), 20037 deletions(-) delete mode 100644 elpa/org-9.6.7.signed delete mode 100644 elpa/org-9.6.7/doc/org-version.inc delete mode 100644 elpa/org-9.6.7/ob-maxima.el delete mode 100644 elpa/org-9.6.7/ob-python.el delete mode 100644 elpa/org-9.6.7/org-pkg.el create mode 100644 elpa/org-9.7.17.signed rename elpa/{org-9.6.7 => org-9.7.17}/.dir-locals.el (87%) rename elpa/{org-9.6.7 => org-9.7.17}/CONTRIBUTE.org (94%) rename elpa/{org-9.6.7 => org-9.7.17}/COPYING (100%) rename elpa/{org-9.6.7 => org-9.7.17}/Makefile (72%) rename elpa/{org-9.6.7 => org-9.7.17}/README-elpa (91%) rename elpa/{org-9.6.7 => org-9.7.17}/README.org (91%) rename elpa/{org-9.6.7 => org-9.7.17}/dir (100%) rename elpa/{org-9.6.7 => org-9.7.17}/doc/.aspell.org.conf (100%) rename elpa/{org-9.6.7 => org-9.7.17}/doc/.nosearch (100%) rename elpa/{org-9.6.7 => org-9.7.17}/doc/Documentation_Standards.org (100%) rename elpa/{org-9.6.7 => org-9.7.17}/doc/Makefile (100%) rename elpa/{org-9.6.7 => org-9.7.17}/doc/dir (100%) rename elpa/{org-9.6.7 => org-9.7.17}/doc/doc-setup.org (97%) rename elpa/{org-9.6.7 => org-9.7.17}/doc/fdl.org (100%) rename elpa/{org-9.6.7 => org-9.7.17}/doc/htmlxref.cnf (100%) rename elpa/{org-9.6.7 => org-9.7.17}/doc/org-guide.org (88%) rename elpa/{org-9.6.7 => org-9.7.17}/doc/org-manual.org (91%) create mode 100644 elpa/org-9.7.17/doc/org-version.inc rename elpa/{org-9.6.7 => org-9.7.17}/doc/org.texi (92%) rename elpa/{org-9.6.7 => org-9.7.17}/doc/orgcard.tex (98%) rename elpa/{org-9.6.7 => org-9.7.17}/doc/orgguide.texi (89%) rename elpa/{org-9.6.7 => org-9.7.17}/doc/pdflayout.sty (100%) rename elpa/{org-9.6.7 => org-9.7.17}/doc/texinfo.tex (100%) rename elpa/{org-9.6.7 => org-9.7.17}/etc/Makefile (100%) rename elpa/{org-9.6.7 => org-9.7.17}/etc/ORG-NEWS (79%) rename elpa/{org-9.6.7 => org-9.7.17}/etc/csl/README (100%) rename elpa/{org-9.6.7 => org-9.7.17}/etc/csl/chicago-author-date.csl (100%) rename elpa/{org-9.6.7 => org-9.7.17}/etc/csl/locales-en-US.xml (100%) rename elpa/{org-9.6.7 => org-9.7.17}/etc/styles/OrgOdtContentTemplate.xml (100%) rename elpa/{org-9.6.7 => org-9.7.17}/etc/styles/OrgOdtStyles.xml (100%) rename elpa/{org-9.6.7 => org-9.7.17}/etc/styles/README (95%) rename elpa/{org-9.6.7 => org-9.7.17}/local.mk (98%) rename elpa/{org-9.6.7 => org-9.7.17}/ob-C.el (89%) rename elpa/{org-9.6.7 => org-9.7.17}/ob-R.el (94%) rename elpa/{org-9.6.7 => org-9.7.17}/ob-awk.el (85%) rename elpa/{org-9.6.7 => org-9.7.17}/ob-calc.el (74%) rename elpa/{org-9.6.7 => org-9.7.17}/ob-clojure.el (63%) rename elpa/{org-9.6.7 => org-9.7.17}/ob-comint.el (66%) rename elpa/{org-9.6.7 => org-9.7.17}/ob-core.el (83%) rename elpa/{org-9.6.7 => org-9.7.17}/ob-css.el (94%) rename elpa/{org-9.6.7 => org-9.7.17}/ob-ditaa.el (92%) rename elpa/{org-9.6.7 => org-9.7.17}/ob-dot.el (88%) rename elpa/{org-9.6.7 => org-9.7.17}/ob-emacs-lisp.el (81%) rename elpa/{org-9.6.7 => org-9.7.17}/ob-eshell.el (87%) rename elpa/{org-9.6.7 => org-9.7.17}/ob-eval.el (92%) rename elpa/{org-9.6.7 => org-9.7.17}/ob-exp.el (51%) rename elpa/{org-9.6.7 => org-9.7.17}/ob-forth.el (94%) rename elpa/{org-9.6.7 => org-9.7.17}/ob-fortran.el (83%) rename elpa/{org-9.6.7 => org-9.7.17}/ob-gnuplot.el (86%) rename elpa/{org-9.6.7 => org-9.7.17}/ob-groovy.el (92%) rename elpa/{org-9.6.7 => org-9.7.17}/ob-haskell.el (52%) rename elpa/{org-9.6.7 => org-9.7.17}/ob-java.el (98%) rename elpa/{org-9.6.7 => org-9.7.17}/ob-js.el (93%) rename elpa/{org-9.6.7 => org-9.7.17}/ob-julia.el (92%) rename elpa/{org-9.6.7 => org-9.7.17}/ob-latex.el (89%) rename elpa/{org-9.6.7 => org-9.7.17}/ob-lilypond.el (82%) rename elpa/{org-9.6.7 => org-9.7.17}/ob-lisp.el (59%) rename elpa/{org-9.6.7 => org-9.7.17}/ob-lob.el (96%) rename elpa/{org-9.6.7 => org-9.7.17}/ob-lua.el (83%) rename elpa/{org-9.6.7 => org-9.7.17}/ob-makefile.el (92%) rename elpa/{org-9.6.7 => org-9.7.17}/ob-matlab.el (95%) create mode 100644 elpa/org-9.7.17/ob-maxima.el rename elpa/{org-9.6.7 => org-9.7.17}/ob-ocaml.el (97%) rename elpa/{org-9.6.7 => org-9.7.17}/ob-octave.el (89%) rename elpa/{org-9.6.7 => org-9.7.17}/ob-org.el (81%) rename elpa/{org-9.6.7 => org-9.7.17}/ob-perl.el (98%) rename elpa/{org-9.6.7 => org-9.7.17}/ob-plantuml.el (96%) rename elpa/{org-9.6.7 => org-9.7.17}/ob-processing.el (97%) create mode 100644 elpa/org-9.7.17/ob-python.el rename elpa/{org-9.6.7 => org-9.7.17}/ob-ref.el (95%) rename elpa/{org-9.6.7 => org-9.7.17}/ob-ruby.el (85%) rename elpa/{org-9.6.7 => org-9.7.17}/ob-sass.el (97%) rename elpa/{org-9.6.7 => org-9.7.17}/ob-scheme.el (68%) rename elpa/{org-9.6.7 => org-9.7.17}/ob-screen.el (94%) rename elpa/{org-9.6.7 => org-9.7.17}/ob-sed.el (96%) rename elpa/{org-9.6.7 => org-9.7.17}/ob-shell.el (73%) rename elpa/{org-9.6.7 => org-9.7.17}/ob-sql.el (93%) rename elpa/{org-9.6.7 => org-9.7.17}/ob-sqlite.el (89%) rename elpa/{org-9.6.7 => org-9.7.17}/ob-table.el (86%) rename elpa/{org-9.6.7 => org-9.7.17}/ob-tangle.el (84%) rename elpa/{org-9.6.7 => org-9.7.17}/ob.el (94%) rename elpa/{org-9.6.7 => org-9.7.17}/oc-basic.el (85%) rename elpa/{org-9.6.7 => org-9.7.17}/oc-biblatex.el (92%) rename elpa/{org-9.6.7 => org-9.7.17}/oc-bibtex.el (95%) rename elpa/{org-9.6.7 => org-9.7.17}/oc-csl.el (80%) rename elpa/{org-9.6.7 => org-9.7.17}/oc-natbib.el (92%) rename elpa/{org-9.6.7 => org-9.7.17}/oc.el (90%) rename elpa/{org-9.6.7 => org-9.7.17}/ol-bbdb.el (98%) rename elpa/{org-9.6.7 => org-9.7.17}/ol-bibtex.el (94%) rename elpa/{org-9.6.7 => org-9.7.17}/ol-docview.el (86%) rename elpa/{org-9.6.7 => org-9.7.17}/ol-doi.el (94%) rename elpa/{org-9.6.7 => org-9.7.17}/ol-eshell.el (85%) rename elpa/{org-9.6.7 => org-9.7.17}/ol-eww.el (97%) rename elpa/{org-9.6.7 => org-9.7.17}/ol-gnus.el (91%) rename elpa/{org-9.6.7 => org-9.7.17}/ol-info.el (85%) rename elpa/{org-9.6.7 => org-9.7.17}/ol-irc.el (98%) rename elpa/{org-9.6.7 => org-9.7.17}/ol-man.el (60%) rename elpa/{org-9.6.7 => org-9.7.17}/ol-mhe.el (97%) rename elpa/{org-9.6.7 => org-9.7.17}/ol-rmail.el (96%) rename elpa/{org-9.6.7 => org-9.7.17}/ol-w3m.el (98%) rename elpa/{org-9.6.7 => org-9.7.17}/ol.el (76%) rename elpa/{org-9.6.7 => org-9.7.17}/org-agenda.el (88%) rename elpa/{org-9.6.7 => org-9.7.17}/org-archive.el (97%) rename elpa/{org-9.6.7 => org-9.7.17}/org-attach-git.el (98%) rename elpa/{org-9.6.7 => org-9.7.17}/org-attach.el (88%) rename elpa/{org-9.6.7 => org-9.7.17}/org-autoloads.el (77%) rename elpa/{org-9.6.7 => org-9.7.17}/org-capture.el (96%) rename elpa/{org-9.6.7 => org-9.7.17}/org-clock.el (91%) rename elpa/{org-9.6.7 => org-9.7.17}/org-colview.el (89%) rename elpa/{org-9.6.7 => org-9.7.17}/org-compat.el (86%) rename elpa/{org-9.6.7 => org-9.7.17}/org-crypt.el (82%) rename elpa/{org-9.6.7 => org-9.7.17}/org-ctags.el (85%) rename elpa/{org-9.6.7 => org-9.7.17}/org-cycle.el (93%) rename elpa/{org-9.6.7 => org-9.7.17}/org-datetree.el (84%) rename elpa/{org-9.6.7 => org-9.7.17}/org-duration.el (73%) create mode 100644 elpa/org-9.7.17/org-element-ast.el rename elpa/{org-9.6.7 => org-9.7.17}/org-element.el (57%) rename elpa/{org-9.6.7 => org-9.7.17}/org-entities.el (97%) rename elpa/{org-9.6.7 => org-9.7.17}/org-faces.el (97%) rename elpa/{org-9.6.7 => org-9.7.17}/org-feed.el (98%) rename elpa/{org-9.6.7 => org-9.7.17}/org-fold-core.el (84%) rename elpa/{org-9.6.7 => org-9.7.17}/org-fold.el (87%) rename elpa/{org-9.6.7 => org-9.7.17}/org-footnote.el (94%) rename elpa/{org-9.6.7 => org-9.7.17}/org-goto.el (93%) rename elpa/{org-9.6.7 => org-9.7.17}/org-habit.el (97%) rename elpa/{org-9.6.7 => org-9.7.17}/org-id.el (72%) rename elpa/{org-9.6.7 => org-9.7.17}/org-indent.el (96%) rename elpa/{org-9.6.7 => org-9.7.17}/org-inlinetask.el (96%) rename elpa/{org-9.6.7 => org-9.7.17}/org-keys.el (89%) rename elpa/{org-9.6.7 => org-9.7.17}/org-lint.el (67%) rename elpa/{org-9.6.7 => org-9.7.17}/org-list.el (93%) rename elpa/{org-9.6.7 => org-9.7.17}/org-loaddefs.el (53%) rename elpa/{org-9.6.7 => org-9.7.17}/org-macro.el (90%) rename elpa/{org-9.6.7 => org-9.7.17}/org-macs.el (75%) rename elpa/{org-9.6.7 => org-9.7.17}/org-mobile.el (99%) rename elpa/{org-9.6.7 => org-9.7.17}/org-mouse.el (96%) rename elpa/{org-9.6.7 => org-9.7.17}/org-num.el (98%) rename elpa/{org-9.6.7 => org-9.7.17}/org-pcomplete.el (91%) rename elpa/{org-9.6.7 => org-9.7.17}/org-persist.el (63%) create mode 100644 elpa/org-9.7.17/org-pkg.el rename elpa/{org-9.6.7 => org-9.7.17}/org-plot.el (98%) rename elpa/{org-9.6.7 => org-9.7.17}/org-protocol.el (95%) rename elpa/{org-9.6.7 => org-9.7.17}/org-refile.el (82%) rename elpa/{org-9.6.7 => org-9.7.17}/org-src.el (84%) rename elpa/{org-9.6.7 => org-9.7.17}/org-table.el (94%) rename elpa/{org-9.6.7 => org-9.7.17}/org-tempo.el (95%) rename elpa/{org-9.6.7 => org-9.7.17}/org-timer.el (90%) rename elpa/{org-9.6.7 => org-9.7.17}/org-version.el (87%) rename elpa/{org-9.6.7 => org-9.7.17}/org.el (83%) rename elpa/{org-9.6.7 => org-9.7.17}/org.info (90%) rename elpa/{org-9.6.7 => org-9.7.17}/orgguide.info (88%) rename elpa/{org-9.6.7 => org-9.7.17}/ox-ascii.el (95%) rename elpa/{org-9.6.7 => org-9.7.17}/ox-beamer.el (89%) rename elpa/{org-9.6.7 => org-9.7.17}/ox-html.el (94%) rename elpa/{org-9.6.7 => org-9.7.17}/ox-icalendar.el (71%) rename elpa/{org-9.6.7 => org-9.7.17}/ox-koma-letter.el (97%) rename elpa/{org-9.6.7 => org-9.7.17}/ox-latex.el (85%) rename elpa/{org-9.6.7 => org-9.7.17}/ox-man.el (95%) rename elpa/{org-9.6.7 => org-9.7.17}/ox-md.el (92%) rename elpa/{org-9.6.7 => org-9.7.17}/ox-odt.el (95%) rename elpa/{org-9.6.7 => org-9.7.17}/ox-org.el (91%) rename elpa/{org-9.6.7 => org-9.7.17}/ox-publish.el (92%) rename elpa/{org-9.6.7 => org-9.7.17}/ox-texinfo.el (94%) rename elpa/{org-9.6.7 => org-9.7.17}/ox.el (83%) diff --git a/bba.org b/bba.org index 66327c2b..52dc36c6 100644 --- a/bba.org +++ b/bba.org @@ -28,12 +28,12 @@ To be precise, this is what's in the first part of my =~/.emacs.d/init.el= (what (setq load-path (append - (list (expand-file-name "~/.emacs.d/") (expand-file-name "~/.emacs.d/elpa/org-9.6.7")) + (list (expand-file-name "~/.emacs.d/") (expand-file-name "~/.emacs.d/elpa/org-9.7.17")) ;; (expand-file-name "/usr/share/emacs/lisp/") load-path)) - (add-to-list 'load-path "~/.emacs/elpa/org-9.6.7") + (add-to-list 'load-path "~/.emacs/elpa/org-9.7.17") ;; (add-to-list 'load-path "~/elisp/org-mode/contrib/lisp") ;; Load the rest of the packages diff --git a/elpa/org-9.6.7.signed b/elpa/org-9.6.7.signed deleted file mode 100644 index c49bd23c..00000000 --- a/elpa/org-9.6.7.signed +++ /dev/null @@ -1 +0,0 @@ -Good signature from 066DAFCB81E42C40 GNU ELPA Signing Agent (2019) (trust undefined) created at 2023-06-26T23:10:03+0200 using RSA \ No newline at end of file diff --git a/elpa/org-9.6.7/doc/org-version.inc b/elpa/org-9.6.7/doc/org-version.inc deleted file mode 100644 index e07311b0..00000000 --- a/elpa/org-9.6.7/doc/org-version.inc +++ /dev/null @@ -1,3 +0,0 @@ -@c automatically generated, do not edit -@set VERSION 9.6.7 () -@set DATE 2023-06-26 diff --git a/elpa/org-9.6.7/ob-maxima.el b/elpa/org-9.6.7/ob-maxima.el deleted file mode 100644 index d1d7c742..00000000 --- a/elpa/org-9.6.7/ob-maxima.el +++ /dev/null @@ -1,135 +0,0 @@ -;;; ob-maxima.el --- Babel Functions for Maxima -*- lexical-binding: t; -*- - -;; Copyright (C) 2009-2023 Free Software Foundation, Inc. - -;; Author: Eric S Fraga -;; Eric Schulte -;; Keywords: literate programming, reproducible research, maxima -;; URL: 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 maxima entries. -;; -;; This differs from most standard languages in that -;; 1) there is no such thing as a "session" in maxima -;; 2) we are adding the "cmdline" header argument - -;;; Code: - -(require 'org-macs) -(org-assert-version) - -(require 'ob) - -(defvar org-babel-tangle-lang-exts) -(add-to-list 'org-babel-tangle-lang-exts '("maxima" . "max")) - -(defvar org-babel-default-header-args:maxima '()) - -(defcustom org-babel-maxima-command - (if (boundp 'maxima-command) maxima-command "maxima") - "Command used to call maxima on the shell." - :group 'org-babel - :type 'string) - -(defun org-babel-maxima-expand (body params) - "Expand a block of Maxima code according to its header arguments." - (let ((vars (org-babel--get-vars params)) - (epilogue (cdr (assq :epilogue params))) - (prologue (cdr (assq :prologue params)))) - (mapconcat 'identity - (list - ;; Any code from the specified prologue at the start. - prologue - ;; graphic output - (let ((graphic-file (ignore-errors (org-babel-graphical-output-file params)))) - (if graphic-file - (format - "set_plot_option ([gnuplot_term, png]); set_plot_option ([gnuplot_out_file, %S]);" - graphic-file) - "")) - ;; variables - (mapconcat 'org-babel-maxima-var-to-maxima vars "\n") - ;; body - body - ;; Any code from the specified epilogue at the end. - epilogue - "gnuplot_close ()$") - "\n"))) - -(defun org-babel-execute:maxima (body params) - "Execute a block of Maxima entries with org-babel. -This function is called by `org-babel-execute-src-block'." - (message "Executing Maxima source code block") - (let ((result-params (split-string (or (cdr (assq :results params)) ""))) - (result - (let* ((cmdline (or (cdr (assq :cmdline params)) "")) - (in-file (org-babel-temp-file "maxima-" ".max")) - (cmd (format "%s --very-quiet -r %s %s" - org-babel-maxima-command - (shell-quote-argument - (format "batchload(%S)$" in-file)) - cmdline))) - (with-temp-file in-file (insert (org-babel-maxima-expand body params))) - (message cmd) - ;; " | grep -v batch | grep -v 'replaced' | sed '/^$/d' " - (let ((raw (org-babel-eval cmd ""))) - (mapconcat - #'identity - (delq nil - (mapcar (lambda (line) - (unless (or (string-match "batch" line) - (string-match "^rat: replaced .*$" line) - (string-match "^;;; Loading #P" line) - (= 0 (length line))) - line)) - (split-string raw "[\r\n]"))) "\n"))))) - (if (ignore-errors (org-babel-graphical-output-file params)) - nil - (org-babel-result-cond result-params - result - (let ((tmp-file (org-babel-temp-file "maxima-res-"))) - (with-temp-file tmp-file (insert result)) - (org-babel-import-elisp-from-file tmp-file)))))) - - -(defun org-babel-prep-session:maxima (_session _params) - (error "Maxima does not support sessions")) - -(defun org-babel-maxima-var-to-maxima (pair) - "Convert an elisp val into a string of maxima code specifying a var -of the same value." - (let ((var (car pair)) - (val (cdr pair))) - (when (symbolp val) - (setq val (symbol-name val)) - (when (= (length val) 1) - (setq val (string-to-char val)))) - (format "%S: %s$" var - (org-babel-maxima-elisp-to-maxima val)))) - -(defun org-babel-maxima-elisp-to-maxima (val) - "Return a string of maxima code which evaluates to VAL." - (if (listp val) - (concat "[" (mapconcat #'org-babel-maxima-elisp-to-maxima val ", ") "]") - (format "%s" val))) - -(provide 'ob-maxima) - -;;; ob-maxima.el ends here diff --git a/elpa/org-9.6.7/ob-python.el b/elpa/org-9.6.7/ob-python.el deleted file mode 100644 index c19af0ab..00000000 --- a/elpa/org-9.6.7/ob-python.el +++ /dev/null @@ -1,464 +0,0 @@ -;;; ob-python.el --- Babel Functions for Python -*- lexical-binding: t; -*- - -;; Copyright (C) 2009-2023 Free Software Foundation, Inc. - -;; Authors: Eric Schulte -;; Dan Davison -;; Maintainer: Jack Kamm -;; Keywords: literate programming, reproducible research -;; URL: 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 python source code. - -;;; Code: - -(require 'org-macs) -(org-assert-version) - -(require 'ob) -(require 'org-macs) -(require 'python) - -(declare-function py-shell "ext:python-mode" (&rest args)) -(declare-function py-choose-shell "ext:python-mode" (&optional shell)) -(declare-function py-shell-send-string "ext:python-mode" (strg &optional process)) - -(defvar org-babel-tangle-lang-exts) -(add-to-list 'org-babel-tangle-lang-exts '("python" . "py")) - -(defvar org-babel-default-header-args:python '()) - -(defcustom org-babel-python-command "python" - "Name of the command for executing Python code." - :version "24.4" - :package-version '(Org . "8.0") - :group 'org-babel - :type 'string) - -(defcustom org-babel-python-mode - (if (featurep 'python-mode) 'python-mode 'python) - "Preferred python mode for use in running python interactively. -This will typically be either `python' or `python-mode'." - :group 'org-babel - :version "24.4" - :package-version '(Org . "8.0") - :type 'symbol) - -(defcustom org-babel-python-hline-to "None" - "Replace hlines in incoming tables with this when translating to python." - :group 'org-babel - :version "24.4" - :package-version '(Org . "8.0") - :type 'string) - -(defcustom org-babel-python-None-to 'hline - "Replace `None' in python tables with this before returning." - :group 'org-babel - :version "24.4" - :package-version '(Org . "8.0") - :type 'symbol) - -(defun org-babel-execute:python (body params) - "Execute a block of Python code with Babel. -This function is called by `org-babel-execute-src-block'." - (let* ((org-babel-python-command - (or (cdr (assq :python params)) - org-babel-python-command)) - (session (org-babel-python-initiate-session - (cdr (assq :session params)))) - (result-params (cdr (assq :result-params params))) - (result-type (cdr (assq :result-type params))) - (return-val (when (eq result-type 'value) - (cdr (assq :return params)))) - (preamble (cdr (assq :preamble params))) - (async (org-babel-comint-use-async params)) - (full-body - (concat - (org-babel-expand-body:generic - body params - (org-babel-variable-assignments:python params)) - (when return-val - (format (if session "\n%s" "\nreturn %s") return-val)))) - (result (org-babel-python-evaluate - session full-body result-type - result-params preamble async))) - (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)))))) - -(defun org-babel-prep-session:python (session params) - "Prepare SESSION according to the header arguments in PARAMS. -VARS contains resolved variable references." - (let* ((session (org-babel-python-initiate-session session)) - (var-lines - (org-babel-variable-assignments:python params))) - (org-babel-comint-in-buffer session - (mapc (lambda (var) - (end-of-line 1) (insert var) (comint-send-input) - (org-babel-comint-wait-for-output session)) - var-lines)) - session)) - -(defun org-babel-load-session:python (session body params) - "Load BODY into SESSION." - (save-window-excursion - (let ((buffer (org-babel-prep-session:python session params))) - (with-current-buffer buffer - (goto-char (process-mark (get-buffer-process (current-buffer)))) - (insert (org-babel-chomp body))) - buffer))) - -;; helper functions - -(defun org-babel-variable-assignments:python (params) - "Return a list of Python statements assigning the block's variables." - (mapcar - (lambda (pair) - (format "%s=%s" - (car pair) - (org-babel-python-var-to-python (cdr pair)))) - (org-babel--get-vars params))) - -(defun org-babel-python-var-to-python (var) - "Convert an elisp value to a python variable. -Convert an elisp value, VAR, into a string of python source code -specifying a variable of the same value." - (if (listp var) - (concat "[" (mapconcat #'org-babel-python-var-to-python var ", ") "]") - (if (eq var 'hline) - org-babel-python-hline-to - (format - (if (and (stringp var) (string-match "[\n\r]" var)) "\"\"%S\"\"" "%S") - (if (stringp var) (substring-no-properties var) var))))) - -(defun org-babel-python-table-or-string (results) - "Convert RESULTS into an appropriate elisp value. -If the results look like a list or tuple, then convert them into an -Emacs-lisp table, otherwise return the results as a string." - (let ((res (org-babel-script-escape results))) - (if (listp res) - (mapcar (lambda (el) (if (eq el 'None) - org-babel-python-None-to el)) - res) - res))) - -(defvar org-babel-python-buffers '((:default . "*Python*"))) - -(defun org-babel-python-session-buffer (session) - "Return the buffer associated with SESSION." - (cdr (assoc session org-babel-python-buffers))) - -(defun org-babel-python-with-earmuffs (session) - (let ((name (if (stringp session) session (format "%s" session)))) - (if (and (string= "*" (substring name 0 1)) - (string= "*" (substring name (- (length name) 1)))) - name - (format "*%s*" name)))) - -(defun org-babel-python-without-earmuffs (session) - (let ((name (if (stringp session) session (format "%s" session)))) - (if (and (string= "*" (substring name 0 1)) - (string= "*" (substring name (- (length name) 1)))) - (substring name 1 (- (length name) 1)) - name))) - -(defvar py-which-bufname) -(defvar python-shell-buffer-name) -(defvar-local org-babel-python--initialized nil - "Flag used to mark that python session has been initialized.") -(defun org-babel-python-initiate-session-by-key (&optional session) - "Initiate a python session. -If there is not a current inferior-process-buffer in SESSION -then create. Return the initialized session." - (save-window-excursion - (let* ((session (if session (intern session) :default)) - (py-buffer (org-babel-python-session-buffer session)) - (cmd (if (member system-type '(cygwin windows-nt ms-dos)) - (concat org-babel-python-command " -i") - org-babel-python-command))) - (cond - ((eq 'python org-babel-python-mode) ; python.el - (unless py-buffer - (setq py-buffer (org-babel-python-with-earmuffs session))) - (let ((python-shell-buffer-name - (org-babel-python-without-earmuffs py-buffer))) - (run-python cmd) - (with-current-buffer py-buffer - (add-hook - 'python-shell-first-prompt-hook - (lambda () - (setq-local org-babel-python--initialized t) - (message "I am running!!!")) - nil 'local)))) - ((and (eq 'python-mode org-babel-python-mode) - (fboundp 'py-shell)) ; python-mode.el - (require 'python-mode) - ;; Make sure that py-which-bufname is initialized, as otherwise - ;; it will be overwritten the first time a Python buffer is - ;; created. - (py-choose-shell) - ;; `py-shell' creates a buffer whose name is the value of - ;; `py-which-bufname' with '*'s at the beginning and end - (let* ((bufname (if (and py-buffer (buffer-live-p py-buffer)) - (replace-regexp-in-string ;; zap surrounding * - "^\\*\\([^*]+\\)\\*$" "\\1" py-buffer) - (concat "Python-" (symbol-name session)))) - (py-which-bufname bufname)) - (setq py-buffer (org-babel-python-with-earmuffs bufname)) - (py-shell nil nil t org-babel-python-command py-buffer nil nil t nil))) - (t - (error "No function available for running an inferior Python"))) - ;; Wait until Python initializes. - (if (eq 'python org-babel-python-mode) ; python.el - ;; This is more reliable compared to - ;; `org-babel-comint-wait-for-output' as python may emit - ;; multiple prompts during initialization. - (with-current-buffer py-buffer - (while (not org-babel-python--initialized) - (org-babel-comint-wait-for-output py-buffer))) - (org-babel-comint-wait-for-output py-buffer)) - (setq org-babel-python-buffers - (cons (cons session py-buffer) - (assq-delete-all session org-babel-python-buffers))) - session))) - -(defun org-babel-python-initiate-session (&optional session _params) - "Create a session named SESSION according to PARAMS." - (unless (string= session "none") - (org-babel-python-session-buffer - (org-babel-python-initiate-session-by-key session)))) - -(defvar org-babel-python-eoe-indicator "org_babel_python_eoe" - "A string to indicate that evaluation has completed.") - -(defconst org-babel-python-wrapper-method - " -def main(): -%s - -open('%s', 'w').write( str(main()) )") -(defconst org-babel-python-pp-wrapper-method - " -import pprint -def main(): -%s - -open('%s', 'w').write( pprint.pformat(main()) )") - -(defconst org-babel-python--exec-tmpfile "\ -with open('%s') as __org_babel_python_tmpfile: - exec(compile(__org_babel_python_tmpfile.read(), __org_babel_python_tmpfile.name, 'exec'))" - "Template for Python session command with output results. - -Has a single %s escape, the tempfile containing the source code -to evaluate.") - -(defun org-babel-python-format-session-value - (src-file result-file result-params) - "Return Python code to evaluate SRC-FILE and write result to RESULT-FILE." - (format "\ -import ast -with open('%s') as __org_babel_python_tmpfile: - __org_babel_python_ast = ast.parse(__org_babel_python_tmpfile.read()) -__org_babel_python_final = __org_babel_python_ast.body[-1] -if isinstance(__org_babel_python_final, ast.Expr): - __org_babel_python_ast.body = __org_babel_python_ast.body[:-1] - exec(compile(__org_babel_python_ast, '', 'exec')) - __org_babel_python_final = eval(compile(ast.Expression( - __org_babel_python_final.value), '', 'eval')) - with open('%s', 'w') as __org_babel_python_tmpfile: - if %s: - import pprint - __org_babel_python_tmpfile.write(pprint.pformat(__org_babel_python_final)) - else: - __org_babel_python_tmpfile.write(str(__org_babel_python_final)) -else: - exec(compile(__org_babel_python_ast, '', 'exec')) - __org_babel_python_final = None" - (org-babel-process-file-name src-file 'noquote) - (org-babel-process-file-name result-file 'noquote) - (if (member "pp" result-params) "True" "False"))) - -(defun org-babel-python-evaluate - (session body &optional result-type result-params preamble async) - "Evaluate BODY as Python code." - (if session - (if async - (org-babel-python-async-evaluate-session - session body result-type result-params) - (org-babel-python-evaluate-session - session body result-type result-params)) - (org-babel-python-evaluate-external-process - body result-type result-params preamble))) - -(defun org-babel-python--shift-right (body &optional count) - (with-temp-buffer - (python-mode) - (insert body) - (goto-char (point-min)) - (while (not (eobp)) - (unless (python-syntax-context 'string) - (python-indent-shift-right (line-beginning-position) - (line-end-position) - count)) - (forward-line 1)) - (buffer-string))) - -(defun org-babel-python-evaluate-external-process - (body &optional result-type result-params preamble) - "Evaluate BODY in external python 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." - (let ((raw - (pcase result-type - (`output (org-babel-eval org-babel-python-command - (concat preamble (and preamble "\n") - body))) - (`value (let ((tmp-file (org-babel-temp-file "python-"))) - (org-babel-eval - org-babel-python-command - (concat - preamble (and preamble "\n") - (format - (if (member "pp" result-params) - org-babel-python-pp-wrapper-method - org-babel-python-wrapper-method) - (org-babel-python--shift-right body) - (org-babel-process-file-name tmp-file 'noquote)))) - (org-babel-eval-read-file tmp-file)))))) - (org-babel-result-cond result-params - raw - (org-babel-python-table-or-string (org-trim raw))))) - -(defun org-babel-python--send-string (session body) - "Pass BODY to the Python process in SESSION. -Return output." - (with-current-buffer session - (let* ((string-buffer "") - (comint-output-filter-functions - (cons (lambda (text) (setq string-buffer - (concat string-buffer text))) - comint-output-filter-functions)) - (body (format "\ -try: -%s -except: - raise -finally: - print('%s')" - (org-babel-python--shift-right body 4) - org-babel-python-eoe-indicator))) - (if (not (eq 'python-mode org-babel-python-mode)) - (let ((python-shell-buffer-name - (org-babel-python-without-earmuffs session))) - (python-shell-send-string body)) - (require 'python-mode) - (py-shell-send-string body (get-buffer-process session))) - ;; same as `python-shell-comint-end-of-output-p' in emacs-25.1+ - (while (not (string-match - org-babel-python-eoe-indicator - string-buffer)) - (accept-process-output (get-buffer-process (current-buffer)))) - (org-babel-chomp (substring string-buffer 0 (match-beginning 0)))))) - -(defun org-babel-python-evaluate-session - (session body &optional result-type result-params) - "Pass BODY to the Python process in SESSION. -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." - (let* ((tmp-src-file (org-babel-temp-file "python-")) - (results - (progn - (with-temp-file tmp-src-file (insert body)) - (pcase result-type - (`output - (let ((body (format org-babel-python--exec-tmpfile - (org-babel-process-file-name - tmp-src-file 'noquote)))) - (org-babel-python--send-string session body))) - (`value - (let* ((tmp-results-file (org-babel-temp-file "python-")) - (body (org-babel-python-format-session-value - tmp-src-file tmp-results-file result-params))) - (org-babel-python--send-string session body) - (sleep-for 0 10) - (org-babel-eval-read-file tmp-results-file))))))) - (org-babel-result-cond result-params - results - (org-babel-python-table-or-string results)))) - -(defun org-babel-python-read-string (string) - "Strip \\='s from around Python string." - (if (and (string-prefix-p "'" string) - (string-suffix-p "'" string)) - (substring string 1 -1) - string)) - -;; Async session eval - -(defconst org-babel-python-async-indicator "print ('ob_comint_async_python_%s_%s')") - -(defun org-babel-python-async-value-callback (params tmp-file) - (let ((result-params (cdr (assq :result-params params))) - (results (org-babel-eval-read-file tmp-file))) - (org-babel-result-cond result-params - results - (org-babel-python-table-or-string results)))) - -(defun org-babel-python-async-evaluate-session - (session body &optional result-type result-params) - "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) - "ob_comint_async_python_\\(.+\\)_\\(.+\\)" - 'org-babel-chomp 'org-babel-python-async-value-callback) - (let ((python-shell-buffer-name (org-babel-python-without-earmuffs session))) - (pcase result-type - (`output - (let ((uuid (md5 (number-to-string (random 100000000))))) - (with-temp-buffer - (insert (format org-babel-python-async-indicator "start" uuid)) - (insert "\n") - (insert body) - (insert "\n") - (insert (format org-babel-python-async-indicator "end" uuid)) - (python-shell-send-buffer)) - uuid)) - (`value - (let ((tmp-results-file (org-babel-temp-file "python-")) - (tmp-src-file (org-babel-temp-file "python-"))) - (with-temp-file tmp-src-file (insert body)) - (with-temp-buffer - (insert (org-babel-python-format-session-value tmp-src-file tmp-results-file result-params)) - (insert "\n") - (insert (format org-babel-python-async-indicator "file" tmp-results-file)) - (python-shell-send-buffer)) - tmp-results-file))))) - -(provide 'ob-python) - -;;; ob-python.el ends here diff --git a/elpa/org-9.6.7/org-pkg.el b/elpa/org-9.6.7/org-pkg.el deleted file mode 100644 index a80483c7..00000000 --- a/elpa/org-9.6.7/org-pkg.el +++ /dev/null @@ -1,2 +0,0 @@ -;; Generated package description from org.el -*- no-byte-compile: t -*- -(define-package "org" "9.6.7" "Outline-based notes management and organizer" '((emacs "26.1")) :commit "ca873f7fe47546bca19821f1578a6ab95bf5351c" :authors '(("Carsten Dominik" . "carsten.dominik@gmail.com")) :maintainer '("Bastien Guerry" . "bzg@gnu.org") :keywords '("outlines" "hypermedia" "calendar" "wp") :url "https://orgmode.org") diff --git a/elpa/org-9.7.17.signed b/elpa/org-9.7.17.signed new file mode 100644 index 00000000..7ef9ef55 --- /dev/null +++ b/elpa/org-9.7.17.signed @@ -0,0 +1 @@ +Good signature from 645357D2883A0966 GNU ELPA Signing Agent (2023) (trust undefined) created at 2024-12-07T11:10:02+0100 using EDDSA \ No newline at end of file diff --git a/elpa/org-9.6.7/.dir-locals.el b/elpa/org-9.7.17/.dir-locals.el similarity index 87% rename from elpa/org-9.6.7/.dir-locals.el rename to elpa/org-9.7.17/.dir-locals.el index 9df10dfe..83e51000 100644 --- a/elpa/org-9.6.7/.dir-locals.el +++ b/elpa/org-9.7.17/.dir-locals.el @@ -1,4 +1,4 @@ -;;; Directory Local Variables +;;; Directory Local Variables -*- no-byte-compile: t; -*- ;;; For more information see (info "(emacs) Directory Variables") ((nil diff --git a/elpa/org-9.6.7/CONTRIBUTE.org b/elpa/org-9.7.17/CONTRIBUTE.org similarity index 94% rename from elpa/org-9.6.7/CONTRIBUTE.org rename to elpa/org-9.7.17/CONTRIBUTE.org index 00532f9a..8f94e875 100644 --- a/elpa/org-9.6.7/CONTRIBUTE.org +++ b/elpa/org-9.7.17/CONTRIBUTE.org @@ -4,7 +4,7 @@ effectively. We value a nice tone in our discussions: please check and respect the [[https://www.gnu.org/philosophy/kind-communication.en.html][GNU Kind Communications Guidelines]]. -* Contribute as a Org user +* Contribute as an Org user You can contribute by helping others in various channels. @@ -16,7 +16,7 @@ You can contribute with bug reports and patches. See these [[https://orgmode.org/worg/org-contribute.html#org069b83a][directions]]. -* As a Org maintainer +* As an Org maintainer We encourage you to volunteer to maintain one of the Org files. diff --git a/elpa/org-9.6.7/COPYING b/elpa/org-9.7.17/COPYING similarity index 100% rename from elpa/org-9.6.7/COPYING rename to elpa/org-9.7.17/COPYING diff --git a/elpa/org-9.6.7/Makefile b/elpa/org-9.7.17/Makefile similarity index 72% rename from elpa/org-9.6.7/Makefile rename to elpa/org-9.7.17/Makefile index f2a14b5d..c570d9cf 100644 --- a/elpa/org-9.6.7/Makefile +++ b/elpa/org-9.7.17/Makefile @@ -1,35 +1,25 @@ -.NOTPARALLEL: # always run this make serially .SUFFIXES: # we don't need default suffix rules ifeq ($(MAKELEVEL), 0) $(error This make needs to be started as a sub-make from the toplevel directory.) endif -ifneq ($(ORG_ADD_CONTRIB),) - _ORG_ADD_EL_ := \ - $(notdir \ - $(wildcard \ - $(addsuffix .el, \ - $(addprefix ../contrib/lisp/, \ - $(basename \ - $(notdir $(ORG_ADD_CONTRIB))))))) -endif - LISPV := org-version.el LISPI := org-loaddefs.el LISPA := $(LISPV) $(LISPI) LISPB := $(LISPA:%el=%elc) org-install.elc -LISPF := $(filter-out $(LISPA),$(sort $(wildcard *.el) $(_ORG_ADD_EL_))) +LISPF := $(filter-out $(LISPA),$(sort $(wildcard *.el))) LISPC := $(filter-out $(LISPB) $(LISPN:%el=%elc),$(LISPF:%el=%elc)) -_ORGCM_ := dirall single source slint1 slint2 +LISPN := $(filter-out $(LISPB) $(LISPN:%el=%eln),$(LISPF:%el=%eln)) +_ORGCM_ := dirall single native source slint1 slint2 -include local.mk .PHONY: all compile compile-dirty \ $(_ORGCM_) $(_ORGCM_:%=compile-%) \ - autoloads addcontrib \ + autoloads \ install clean cleanauto cleanall cleanelc clean-install # do not clean here, done in toplevel make -all compile compile-dirty:: autoloads +all compile compile-dirty:: | autoloads ifeq ($(filter-out $(_ORGCM_),$(ORGCM)),) $(MAKE) compile-$(ORGCM) else @@ -37,10 +27,11 @@ else endif compile-dirall: dirall -compile-single: single $(LISPC) -compile-source: source dirall -compile-slint1: dirall slint1 -compile-slint2: source dirall slint1 +compile-single: $(LISPC) | single +compile-native: $(LISPN) | native +compile-source: | source dirall +compile-slint1: | dirall slint1 +compile-slint2: | source dirall slint1 # internal dirall: @@ -48,6 +39,8 @@ dirall: @$(ELCDIR) single: @$(info ==================== $@ ====================) +native: + @$(info ==================== $@ ====================) source: cleanelc @$(info ==================== $@ ====================) @$(foreach elc,$(LISPC),$(MAKE) $(elc) && $(RM) $(elc);) @@ -59,12 +52,11 @@ slint1: @$(info Compiling single $(abspath $<)...) -@$(ELC) $< -addcontrib: -ifneq ($(ORG_ADD_CONTRIB),) - $(CP) $(addprefix ../contrib/lisp/,$(_ORG_ADD_EL_)) . -endif +%.eln: %.el + @$(info Native compiling single $(abspath $<)...) + -@$(ELN) $< -autoloads: cleanauto addcontrib $(LISPI) $(LISPV) +autoloads: cleanauto $(LISPI) $(LISPV) $(LISPV): $(LISPF) @echo "org-version: $(ORGVERSION) ($(GITVERSION))" diff --git a/elpa/org-9.6.7/README-elpa b/elpa/org-9.7.17/README-elpa similarity index 91% rename from elpa/org-9.6.7/README-elpa rename to elpa/org-9.7.17/README-elpa index d9569665..8305e848 100644 --- a/elpa/org-9.6.7/README-elpa +++ b/elpa/org-9.7.17/README-elpa @@ -14,11 +14,9 @@ Check the [Org Mode website] for more. Org is part of GNU Emacs: you probably don't need to install it. - To install a more recent version, please do it from [GNU ELPA] by - running this command: `M-x package-install RET org RET' - - -[GNU ELPA] + To install a more recent version, please use command: `M-x + list-packages', find "org" in the list, click on it, and click + "Install" in the popped up window. 2 Join the GNU Project diff --git a/elpa/org-9.6.7/README.org b/elpa/org-9.7.17/README.org similarity index 91% rename from elpa/org-9.6.7/README.org rename to elpa/org-9.7.17/README.org index bf930116..e72403b6 100644 --- a/elpa/org-9.6.7/README.org +++ b/elpa/org-9.7.17/README.org @@ -9,8 +9,9 @@ Check the [[https://orgmode.org][Org Mode website]] for more. Org is part of GNU Emacs: you probably don't need to install it. -To install a more recent version, please do it from [[https://elpa.gnu.org/packages/org.html][GNU ELPA]] by -running this command: =M-x package-install RET org RET= +To install a more recent version, please use command: =M-x +list-packages=, find "org" in the list, click on it, and click +"Install" in the popped up window. * Join the GNU Project diff --git a/elpa/org-9.6.7/dir b/elpa/org-9.7.17/dir similarity index 100% rename from elpa/org-9.6.7/dir rename to elpa/org-9.7.17/dir diff --git a/elpa/org-9.6.7/doc/.aspell.org.conf b/elpa/org-9.7.17/doc/.aspell.org.conf similarity index 100% rename from elpa/org-9.6.7/doc/.aspell.org.conf rename to elpa/org-9.7.17/doc/.aspell.org.conf diff --git a/elpa/org-9.6.7/doc/.nosearch b/elpa/org-9.7.17/doc/.nosearch similarity index 100% rename from elpa/org-9.6.7/doc/.nosearch rename to elpa/org-9.7.17/doc/.nosearch diff --git a/elpa/org-9.6.7/doc/Documentation_Standards.org b/elpa/org-9.7.17/doc/Documentation_Standards.org similarity index 100% rename from elpa/org-9.6.7/doc/Documentation_Standards.org rename to elpa/org-9.7.17/doc/Documentation_Standards.org diff --git a/elpa/org-9.6.7/doc/Makefile b/elpa/org-9.7.17/doc/Makefile similarity index 100% rename from elpa/org-9.6.7/doc/Makefile rename to elpa/org-9.7.17/doc/Makefile diff --git a/elpa/org-9.6.7/doc/dir b/elpa/org-9.7.17/doc/dir similarity index 100% rename from elpa/org-9.6.7/doc/dir rename to elpa/org-9.7.17/doc/dir diff --git a/elpa/org-9.6.7/doc/doc-setup.org b/elpa/org-9.7.17/doc/doc-setup.org similarity index 97% rename from elpa/org-9.6.7/doc/doc-setup.org rename to elpa/org-9.7.17/doc/doc-setup.org index 945e528d..ac3cdb82 100644 --- a/elpa/org-9.6.7/doc/doc-setup.org +++ b/elpa/org-9.7.17/doc/doc-setup.org @@ -1,6 +1,6 @@ # SETUPFILE for Org manual -# Copyright (C) 2021-2023 Free Software Foundation, Inc. +# Copyright (C) 2021-2024 Free Software Foundation, Inc. # # This file is part of GNU Emacs. # diff --git a/elpa/org-9.6.7/doc/fdl.org b/elpa/org-9.7.17/doc/fdl.org similarity index 100% rename from elpa/org-9.6.7/doc/fdl.org rename to elpa/org-9.7.17/doc/fdl.org diff --git a/elpa/org-9.6.7/doc/htmlxref.cnf b/elpa/org-9.7.17/doc/htmlxref.cnf similarity index 100% rename from elpa/org-9.6.7/doc/htmlxref.cnf rename to elpa/org-9.7.17/doc/htmlxref.cnf diff --git a/elpa/org-9.6.7/doc/org-guide.org b/elpa/org-9.7.17/doc/org-guide.org similarity index 88% rename from elpa/org-9.6.7/doc/org-guide.org rename to elpa/org-9.7.17/doc/org-guide.org index 1732b017..599707c1 100644 --- a/elpa/org-9.6.7/doc/org-guide.org +++ b/elpa/org-9.7.17/doc/org-guide.org @@ -10,7 +10,7 @@ :copying: t :END: -Copyright \copy 2004--2023 Free Software Foundation, Inc. +Copyright \copy 2004--2024 Free Software Foundation, Inc. #+begin_quote Permission is granted to copy, distribute and/or modify this document @@ -91,7 +91,7 @@ Files with extension =.org= will be put into Org mode automatically. If you find problems with Org, or if you have questions, remarks, or ideas about it, please mail to the Org mailing list mailto:emacs-orgmode@gnu.org. For information on how to submit bug -reports, see the main manual. +reports, see the [[info:org][main manual]]. * Document Structure :PROPERTIES: @@ -141,10 +141,11 @@ See [[*Miscellaneous]] for a setup to realize this. Outlines make it possible to hide parts of the text in the buffer. Org uses just two commands, bound to {{{kbd(TAB)}}} and -{{{kbd(S-TAB)}}} to change the visibility in the buffer. +{{{kbd(S-TAB)}}} (~org-cycle~ and ~org-shifttab~) to change the +visibility in the buffer. #+attr_texinfo: :sep , -- {{{kbd(TAB)}}} :: +- {{{kbd(TAB)}}} (~org-cycle~) :: /Subtree cycling/: Rotate current subtree among the states @@ -154,19 +155,19 @@ Org uses just two commands, bound to {{{kbd(TAB)}}} and When called with a prefix argument ({{{kbd(C-u TAB)}}}), or with the Shift key, global cycling is invoked. -- {{{kbd(S-TAB)}}}, {{{kbd(C-u TAB)}}} :: +- {{{kbd(S-TAB)}}} (~org-global-cycle~), {{{kbd(C-u TAB)}}} (~org-cycle~) :: /Global cycling/: Rotate the entire buffer among the states : ,-> OVERVIEW -> CONTENTS -> SHOW ALL --. : '--------------------------------------' -- {{{kbd(C-u C-u C-u TAB)}}} :: +- {{{kbd(C-u C-u C-u TAB)}}} (~org-show-all~) :: Show all, including drawers. When Emacs first visits an Org file, the global state is set to -OVERVIEW, i.e., only the top level headlines are visible. This can be +~showeverything~, i.e., all file content is visible. This can be configured through the variable ~org-startup-folded~, or on a per-file basis by adding a =STARTUP= keyword to =overview=, =content=, =showall=, =showeverything= or =showlevels= (n = 2..5) like this: @@ -180,15 +181,18 @@ basis by adding a =STARTUP= keyword to =overview=, =content=, The following commands jump to other headlines in the buffer. -- {{{kbd(C-c C-n)}}} :: Next heading. +- {{{kbd(C-c C-n)}}} (~org-next-visible-heading~) :: Next heading. +- {{{kbd(C-c C-p)}}} (~org-previous-visible-heading~) :: Previous + heading. -- {{{kbd(C-c C-p)}}} :: Previous heading. +- {{{kbd(C-c C-f)}}} (~org-backward-heading-same-level~) :: Next + heading same level. -- {{{kbd(C-c C-f)}}} :: Next heading same level. +- {{{kbd(C-c C-b)}}} (~outline-backward-same-level~) :: Previous + heading same level. -- {{{kbd(C-c C-b)}}} :: Previous heading same level. - -- {{{kbd(C-c C-u)}}} :: Backward to higher level heading. +- {{{kbd(C-c C-u)}}} (~outline-up-heading~) :: Backward to higher + level heading. ** Structure Editing :PROPERTIES: @@ -196,37 +200,37 @@ The following commands jump to other headlines in the buffer. :END: #+attr_texinfo: :sep , -- {{{kbd(M-RET)}}} :: +- {{{kbd(M-RET)}}} (~org-meta-return~) :: Insert new heading with same level as current. If point is in a plain list item, a new item is created (see [[Plain Lists]]). When this command is used in the middle of a line, the line is split and the rest of the line becomes the new headline[fn:2]. -- {{{kbd(M-S-RET)}}} :: +- {{{kbd(M-S-RET)}}} (~org-insert-todo-heading~) :: Insert new TODO entry with same level as current heading. -- {{{kbd(TAB)}}} in new, empty entry :: +- {{{kbd(TAB)}}} (~org-cycle~) in new, empty entry :: In a new entry with no text yet, {{{kbd(TAB)}}} cycles through reasonable levels. -- {{{kbd(M-LEFT)}}}, {{{kbd(M-RIGHT)}}} :: +- {{{kbd(M-LEFT)}}} (~org-metaleft~), {{{kbd(M-RIGHT)}}} (~org-metaright~) :: Promote or demote current heading by one level. -- {{{kbd(M-UP)}}}, {{{kbd(M-DOWN)}}} :: +- {{{kbd(M-UP)}}} (~org-move-subtree-up~), {{{kbd(M-DOWN)}}} (~org-move-subtree-down~) :: Move subtree up or down, i.e., swap with previous or next subtree of same level. -- {{{kbd(C-c C-w)}}} :: +- {{{kbd(C-c C-w)}}} (~org-refile~) :: Refile entry or region to a different location. See [[*Refile and Copy]]. -- {{{kbd(C-x n s)}}}, {{{kbd(C-x n w)}}} :: +- {{{kbd(C-x n s)}}} (~org-narrow-to-subtree~), {{{kbd(C-x n w)}}} (~widen~) :: Narrow buffer to current subtree and widen it again. @@ -247,12 +251,12 @@ Just try it out and you will see immediately how it works. Org mode contains several commands creating such trees, all these commands can be accessed through a dispatcher: -- {{{kbd(C-c /)}}} :: +- {{{kbd(C-c /)}}} (~org-sparse-tree~) :: This prompts for an extra key to select a sparse-tree creating command. -- {{{kbd(C-c / r)}}} :: +- {{{kbd(C-c / r)}}} (~org-occur~) :: Occur. Prompts for a regexp and shows a sparse tree with all matches. Each match is also highlighted; the highlights disappear @@ -303,41 +307,41 @@ The following commands act on items when point is in the first line of an item (the line with the bullet or number). #+attr_texinfo: :sep , -- {{{kbd(TAB)}}} :: +- {{{kbd(TAB)}}} (~org-cycle~) :: Items can be folded just like headline levels. -- {{{kbd(M-RET)}}} :: +- {{{kbd(M-RET)}}} (~org-insert-heading~) :: Insert new item at current level. With a prefix argument, force a new heading (see [[*Structure Editing]]). -- {{{kbd(M-S-RET)}}} :: +- {{{kbd(M-S-RET)}}} (~org-insert-todo-heading~) :: Insert a new item with a checkbox (see [[*Checkboxes]]). -- {{{kbd(M-S-UP)}}}, {{{kbd(M-S-DOWN)}}} :: +- {{{kbd(M-UP)}}} (~org-move-item-up~), {{{kbd(M-DOWN)}}} (~org-move-item-down~) :: Move the item including subitems up/down (swap with previous/next item of same indentation). If the list is ordered, renumbering is automatic. -- {{{kbd(M-LEFT)}}}, {{{kbd(M-RIGHT)}}} :: +- {{{kbd(M-LEFT)}}} (~org-do-promote~), {{{kbd(M-RIGHT)}}} (~org-do-demote~) :: Decrease/increase the indentation of an item, leaving children alone. -- {{{kbd(M-S-LEFT)}}}, {{{kbd(M-S-RIGHT)}}} :: +- {{{kbd(M-S-LEFT)}}} (~org-promote-subtree~), {{{kbd(M-S-RIGHT)}}} (~org-demote-subtree~) :: Decrease/increase the indentation of the item, including subitems. -- {{{kbd(C-c C-c)}}} :: +- {{{kbd(C-c C-c)}}} (~org-toggle-checkbox~) :: If there is a checkbox (see [[*Checkboxes]]) in the item line, toggle the state of the checkbox. Also verify bullets and indentation consistency in the whole list. -- {{{kbd(C-c -)}}} :: +- {{{kbd(C-c -)}}} (~org-cycle-list-bullet~) :: Cycle the entire list level through the different itemize/enumerate bullets (=-=, =+=, =*=, =1.=, =1)=). @@ -391,7 +395,7 @@ automatically made blank. :UNNUMBERED: notoc :END: -- {{{kbd(C-c |)}}} :: +- {{{kbd(C-c |)}}} (~org-table-create-or-convert-from-region~) :: Convert the active region to table. If every line contains at least one {{{kbd(TAB)}}} character, the function assumes that the material @@ -409,25 +413,25 @@ automatically made blank. :END: #+attr_texinfo: :sep , -- {{{kbd(C-c C-c)}}} :: +- {{{kbd(C-c C-c)}}} (~org-table-align~) :: Re-align the table without moving point. -- {{{kbd(TAB)}}} :: +- {{{kbd(TAB)}}} (~org-table-next-field~) :: Re-align the table, move to the next field. Creates a new row if necessary. -- {{{kbd(S-TAB)}}} :: +- {{{kbd(S-TAB)}}} (~org-table-previous-field~) :: Re-align, move to previous field. -- {{{kbd(RET)}}} :: +- {{{kbd(RET)}}} (~org-table-next-row~) :: Re-align the table and move down to next row. Creates a new row if necessary. -- {{{kbd(S-UP)}}}, {{{kbd(S-DOWN)}}}, {{{kbd(S-LEFT)}}}, {{{kbd(S-RIGHT)}}} :: +- {{{kbd(S-UP)}}} (~org-table-move-cell-up~), {{{kbd(S-DOWN)}}} (~org-table-move-cell-down~), {{{kbd(S-LEFT)}}} (~org-table-move-cell-left~), {{{kbd(S-RIGHT)}}} (~org-table-move-cell-right~) :: Move a cell up, down, left, and right by swapping with adjacent cell. @@ -437,42 +441,42 @@ automatically made blank. :UNNUMBERED: notoc :END: -- {{{kbd(M-LEFT)}}}, {{{kbd(M-RIGHT)}}} :: +- {{{kbd(M-LEFT)}}} (~org-table-move-column-left~), {{{kbd(M-RIGHT)}}} (~org-table-move-column-right~) :: Move the current column left/right. -- {{{kbd(M-S-LEFT)}}} :: +- {{{kbd(M-S-LEFT)}}} (~org-table-delete-column~) :: Kill the current column. -- {{{kbd(M-S-RIGHT)}}} :: +- {{{kbd(M-S-RIGHT)}}} (~org-table-insert-column~) :: Insert a new column to the left of point position. -- {{{kbd(M-UP)}}}, {{{kbd(M-DOWN)}}} :: +- {{{kbd(M-UP)}}} (~org-table-move-row-up~), {{{kbd(M-DOWN)}}} (~org-table-move-row-down~) :: Move the current row up/down. -- {{{kbd(M-S-UP)}}} :: +- {{{kbd(M-S-UP)}}} (~org-table-kill-row~) :: Kill the current row or horizontal line. -- {{{kbd(M-S-DOWN)}}} :: +- {{{kbd(M-S-DOWN)}}} (~org-table-insert-row~) :: Insert a new row above the current row. With a prefix argument, the line is created below the current one. -- {{{kbd(C-c -)}}} :: +- {{{kbd(C-c -)}}} (~org-table-insert-hline~) :: Insert a horizontal line below current row. With a prefix argument, the line is created above the current line. -- {{{kbd(C-c RET)}}} :: +- {{{kbd(C-c RET)}}} (~org-table-hline-and-move~) :: Insert a horizontal line below current row, and move the point into the row below that line. -- {{{kbd(C-c ^)}}} :: +- {{{kbd(C-c ^)}}} (~org-table-sort-lines~) :: Sort the table lines in the region. The position of point indicates the column to be used for sorting, and the range of lines is the @@ -573,7 +577,7 @@ From an Org buffer, the following commands create, navigate or, more generally, act on links. #+attr_texinfo: :sep , -- {{{kbd(C-c C-l)}}} :: +- {{{kbd(C-c C-l)}}} (~org-insert-link~) :: Insert a link. This prompts for a link to be inserted into the buffer. You can just type a link, or use history keys {{{kbd(UP)}}} @@ -583,16 +587,16 @@ generally, act on links. When called with a {{{kbd(C-u)}}} prefix argument, file name completion is used to link to a file. -- {{{kbd(C-c C-l)}}} (with point on existing link) :: +- {{{kbd(C-c C-l)}}} (with point on existing link) (~org-insert-link~) :: When point is on an existing link, {{{kbd(C-c C-l)}}} allows you to edit the link and description parts of the link. -- {{{kbd(C-c C-o)}}} :: +- {{{kbd(C-c C-o)}}} (~open-link-at-point~) :: Open link at point. -- {{{kbd(C-c &)}}} :: +- {{{kbd(C-c &)}}} (~org-mark-ring-goto~) :: Jump back to a recorded position. A position is recorded by the commands following internal links, and by {{{kbd(C-c %)}}}. Using @@ -628,7 +632,7 @@ for example: The most important commands to work with TODO entries are: #+attr_texinfo: :sep , -- {{{kbd(C-c C-t)}}} :: +- {{{kbd(C-c C-t)}}} (~org-todo~) :: Rotate the TODO state of the current item among @@ -639,23 +643,23 @@ The most important commands to work with TODO entries are: with the {{{kbd(t)}}} command key (see [[*Commands in the Agenda Buffer]]). -- {{{kbd(S-RIGHT)}}}, {{{kbd(S-LEFT)}}} :: +- {{{kbd(S-RIGHT)}}} (~org-shiftright~), {{{kbd(S-LEFT)}}} (~org-shiftleft~) :: Select the following/preceding TODO state, similar to cycling. -- {{{kbd(C-c / t)}}} :: +- {{{kbd(C-c / t)}}} (~org-show-todo-tree~) :: View TODO items in a /sparse tree/ (see [[*Sparse Trees]]). Folds the entire buffer, but shows all TODO items---with not-DONE state---and the headings hierarchy above them. -- {{{kbd(M-x org-agenda t)}}} :: +- {{{kbd(M-x org-agenda t)}}} (~org-todo-list~) :: Show the global TODO list. Collects the TODO items (with not-DONE states) from all agenda files (see [[*Agenda Views]]) into a single buffer. See [[*The Global TODO List]], for more information. -- {{{kbd(S-M-RET)}}} :: +- {{{kbd(S-M-RET)}}} (~org-insert-todo-heading~) :: Insert a new TODO entry below the current one. @@ -722,7 +726,7 @@ To record a timestamp and a note when changing a TODO state, call the command ~org-todo~ with a prefix argument. #+attr_texinfo: :sep , -- {{{kbd(C-u C-c C-t)}}} :: +- {{{kbd(C-u C-c C-t)}}} (~org-todo~) :: Prompt for a note and record a the time of the TODO state change. Org mode can also automatically record a timestamp and optionally a @@ -801,7 +805,7 @@ highest, =B= the default if none is given. Priorities make a difference only in the agenda. #+attr_texinfo: :sep ; -- {{{kbd(C-c \,)}}} :: +- {{{kbd(C-c \,)}}} (~org-priority~) :: Set the priority of the current headline. Press {{{kbd(A)}}}, {{{kbd(B)}}} or {{{kbd(C)}}} to select a priority, or {{{kbd(SPC)}}} @@ -861,12 +865,12 @@ checked. The following commands work with checkboxes: -- {{{kbd(C-c C-c)}}} :: +- {{{kbd(C-c C-c)}}}, {{{kbd(C-u C-c C-c)}}} (~org-toggle-checkbox~) :: Toggle checkbox status or---with prefix argument---checkbox presence at point. -- {{{kbd(M-S-RET)}}} :: +- {{{kbd(M-S-RET)}}} (~org-insert-todo-heading~) :: Insert a new item with a checkbox. This works only if point is already in a plain list item (see [[*Plain Lists]]). @@ -921,13 +925,13 @@ Tags can simply be typed into the buffer at the end of a headline. After a colon, {{{kbd(M-TAB)}}} offers completion on tags. There is also a special command for inserting tags: -- {{{kbd(C-c C-q)}}} :: +- {{{kbd(C-c C-q)}}} (~org-set-tags-command~) :: Enter new tags for the current headline. Org mode either offers completion or a special single-key interface for setting tags, see below. -- {{{kbd(C-c C-c)}}} :: +- {{{kbd(C-c C-c)}}} (~org-set-tags-command~) :: When point is in a headline, this does the same as {{{kbd(C-c C-q)}}}. @@ -991,22 +995,21 @@ support with ~org-toggle-tags-groups~, bound to {{{kbd(C-c C-x q)}}}. :UNNUMBERED: notoc :END: -- {{{kbd(C-c / m)}}} or {{{kbd(C-c \)}}} :: +- {{{kbd(C-c / m)}}} or {{{kbd(C-c \)}}} (~org-match-sparse-tree~) :: Create a sparse tree with all headlines matching a tags search. With a {{{kbd(C-u)}}} prefix argument, ignore headlines that are not a TODO line. -- {{{kbd(M-x org-agenda m)}}} :: +- {{{kbd(M-x org-agenda m)}}} (~org-tags-view~) :: Create a global list of tag matches from all agenda files. See [[*Matching Tags and Properties]]. -- {{{kbd(M-x org-agenda M)}}} :: +- {{{kbd(M-x org-agenda M)}}} (~org-tags-view~) :: Create a global list of tag matches from all agenda files, but check - only TODO items and force checking subitems (see the option - ~org-tags-match-list-sublevels~). + only TODO items. These commands all prompt for a match string which allows basic Boolean logic like =+boss+urgent-project1=, to find entries with tags @@ -1061,11 +1064,11 @@ a file, use a line like: The following commands help to work with properties: -- {{{kbd(C-c C-x p)}}} :: +- {{{kbd(C-c C-x p)}}} (~org-set-property~) :: Set a property. This prompts for a property name and a value. -- {{{kbd(C-c C-c d)}}} :: +- {{{kbd(C-c C-c d)}}} (~org-delete-property~) :: Remove a property from the current entry. @@ -1081,7 +1084,15 @@ Tags and Properties]]. To assist project planning, TODO items can be labeled with a date and/or a time. The specially formatted string carrying the date and -time information is called a /timestamp/ in Org mode. +time information is called a /timestamp/ in Org mode. This may be +a little confusing because timestamp is often used as indicating when +something was created or last changed. However, in Org mode this term +is used in a much wider sense. + +Timestamps can be used to plan appointments, schedule tasks, set +deadlines, track time, and more. The following sections describe +the timestamp format and tooling that Org mode provides for common +use cases dealing with time and time intervals. ** Timestamps :PROPERTIES: @@ -1099,12 +1110,16 @@ the agenda (see [[*The Weekly/Daily Agenda]]). We distinguish: A simple timestamp just assigns a date/time to an item. This is just like writing down an appointment or event in a paper agenda. + There can be multiple timestamps in an item. #+begin_example ,* Meet Peter at the movies <2006-11-01 Wed 19:15> ,* Discussion on climate change <2006-11-02 Thu 20:00-22:00> + ,* My days off + <2006-11-03 Fri> + <2006-11-06 Mon> #+end_example - Timestamp with repeater interval :: @@ -1121,8 +1136,6 @@ the agenda (see [[*The Weekly/Daily Agenda]]). We distinguish: - Diary-style expression entries :: - #+cindex: diary style timestamps - #+cindex: sexp timestamps For more complex date specifications, Org mode supports using the special expression diary entries implemented in the Emacs Calendar package. For example, with optional time: @@ -1132,13 +1145,28 @@ the agenda (see [[*The Weekly/Daily Agenda]]). We distinguish: <%%(diary-float t 4 2)> #+end_example +- Time range :: + + Time range is a timestamp having two time units connected by =-= + + #+begin_example + ,* Discussion on climate change + <2006-11-02 Thu 10:00-12:00> + #+end_example + - Time/Date range :: - Two timestamps connected by =--= denote a range. + Two timestamps connected by =--= denote a range. In the agenda, the + headline is shown on the first and last day of the range, and on any + dates that are displayed and fall in the range. The first example + specifies just the dates of the range while the second example + specifies a time range for each date. #+begin_example ,** Meeting in Amsterdam <2004-08-23 Mon>--<2004-08-26 Thu> + ,** This weeks committee meetings + <2004-08-23 Mon 10:00-11:00>--<2004-08-26 Thu 10:00-11:00> #+end_example - Inactive timestamp :: @@ -1162,7 +1190,7 @@ format. All commands listed below produce timestamps in the correct format. #+attr_texinfo: :sep , -- {{{kbd(C-c .)}}} :: +- {{{kbd(C-c .)}}} (~org-timestamp~) :: Prompt for a date and insert a corresponding timestamp. When point is at an existing timestamp in the buffer, the command is used to @@ -1170,16 +1198,16 @@ format. command is used twice in succession, a time range is inserted. With a prefix argument, it also adds the current time. -- {{{kbd(C-c !)}}} :: +- {{{kbd(C-c !)}}} (~org-timestamp-inactive~) :: Like {{{kbd(C-c .)}}}, but insert an inactive timestamp that does not cause an agenda entry. -- {{{kbd(S-LEFT)}}}, {{{kbd(S-RIGHT)}}} :: +- {{{kbd(S-LEFT)}}} (~org-timestamp-down-day~), {{{kbd(S-RIGHT)}}} (~org-timestamp-up-day~) :: Change date at point by one day. -- {{{kbd(S-UP)}}}, {{{kbd(S-DOWN)}}} :: +- {{{kbd(S-UP)}}} (~org-timestamp-up~), {{{kbd(S-DOWN)}}} (~org-timestamp-down~) :: On the beginning or enclosing bracket of a timestamp, change its type. Within a timestamp, change the item under point. Point can @@ -1193,7 +1221,7 @@ When Org mode prompts for a date/time, it accepts any string containing some date and/or time information, and intelligently interprets the string, deriving defaults for unspecified information from the current date and time. You can also select a date in the -pop-up calendar. See the manual for more information on how exactly +pop-up calendar. See the [[info:org][manual]] for more information on how exactly the date/time prompt works. ** Deadlines and Scheduling @@ -1204,7 +1232,7 @@ the date/time prompt works. A timestamp may be preceded by special keywords to facilitate planning: -- {{{kbd(C-c C-d)}}} :: +- {{{kbd(C-c C-d)}}} (~org-deadline~) :: Insert =DEADLINE= keyword along with a time stamp, in the line following the headline. @@ -1224,7 +1252,7 @@ planning: The editor in charge is [[bbdb:Ford Prefect]] #+end_example -- {{{kbd(C-c C-s)}}} :: +- {{{kbd(C-c C-s)}}} (~org-schedule~) :: Insert =SCHEDULED= keyword along with a stamp, in the line following the headline. @@ -1265,30 +1293,30 @@ Org mode allows you to clock the time you spend on specific tasks in a project. #+attr_texinfo: :sep , -- {{{kbd(C-c C-x C-i)}}} :: +- {{{kbd(C-c C-x C-i)}}} (~org-clock-in~) :: Start the clock on the current item (clock-in). This inserts the =CLOCK= keyword together with a timestamp. When called with a {{{kbd(C-u)}}} prefix argument, select the task from a list of recently clocked tasks. -- {{{kbd(C-c C-x C-o)}}} :: +- {{{kbd(C-c C-x C-o)}}} (~org-clock-out~) :: Stop the clock (clock-out). This inserts another timestamp at the same location where the clock was last started. It also directly computes the resulting time in inserts it after the time range as ==>HH:MM=. -- {{{kbd(C-c C-x C-e)}}} :: +- {{{kbd(C-c C-x C-e)}}} (~org-clock-modify-effort-estimate~) :: Update the effort estimate for the current clock task. -- {{{kbd(C-c C-x C-q)}}} :: +- {{{kbd(C-c C-x C-q)}}} (~org-clock-cancel~) :: Cancel the current clock. This is useful if a clock was started by mistake, or if you ended up working on something else. -- {{{kbd(C-c C-x C-j)}}} :: +- {{{kbd(C-c C-x C-j)}}} (~org-clock-goto~) :: Jump to the headline of the currently clocked in task. With a {{{kbd(C-u)}}} prefix argument, select the target task from a list @@ -1339,24 +1367,24 @@ You may also define a global key for capturing new material (see :UNNUMBERED: notoc :END: -- {{{kbd(M-x org-capture)}}} :: +- {{{kbd(M-x org-capture)}}} (~org-capture~) :: Start a capture process, placing you into a narrowed indirect buffer to edit. -- {{{kbd(C-c C-c)}}} :: +- {{{kbd(C-c C-c)}}} (~org-capture-finalize~) :: Once you have finished entering information into the capture buffer, {{{kbd(C-c C-c)}}} returns you to the window configuration before the capture process, so that you can resume your work without further distraction. -- {{{kbd(C-c C-w)}}} :: +- {{{kbd(C-c C-w)}}} (~org-capture-refile~) :: Finalize the capture process by refiling the note to a different place (see [[*Refile and Copy]]). -- {{{kbd(C-c C-k)}}} :: +- {{{kbd(C-c C-k)}}} (~org-capture-kill~) :: Abort the capture process and return to the previous state. @@ -1389,7 +1417,7 @@ the template for you like this: #+texinfo: @noindent During expansion of the template, special %-escapes[fn:10] allow dynamic insertion of content. Here is a small selection of the -possibilities, consult the manual for more. +possibilities, consult the [[info:org][manual]] for more. | =%a= | annotation, normally the link created with ~org-store-link~ | | =%i= | initial content, the region when capture is called with {{{kbd(C-u)}}} | @@ -1408,7 +1436,7 @@ Cutting, finding the right location, and then pasting the note is cumbersome. To simplify this process, you can use the following special command: -- {{{kbd(C-c C-w)}}} :: +- {{{kbd(C-c C-w)}}} (~org-agenda-refile~) :: Refile the entry or region at point. This command offers possible locations for refiling the entry and lets you select one with @@ -1420,15 +1448,15 @@ special command: across a number of files. See the variable ~org-refile-targets~ for details. -- {{{kbd(C-u C-c C-w)}}} :: +- {{{kbd(C-u C-c C-w)}}} (~org-agenda-refile~) :: Use the refile interface to jump to a heading. -- {{{kbd(C-u C-u C-c C-w)}}} :: +- {{{kbd(C-u C-u C-c C-w)}}} (~org-refile-goto-last-stored~) :: Jump to the location where ~org-refile~ last moved a tree to. -- {{{kbd(C-c M-w)}}} :: +- {{{kbd(C-c M-w)}}} (~org-refile-copy~) :: Copying works like refiling, except that the original note is not deleted. @@ -1446,12 +1474,12 @@ global searches like the construction of agenda views fast. The most common archiving action is to move a project tree to another file, the archive file. -- {{{kbd(C-c C-x C-a)}}} :: +- {{{kbd(C-c C-x C-a)}}} (~org-archive-subtree-default~) :: Archive the current entry using the command specified in the variable ~org-archive-default-command~. -- {{{kbd(C-c C-x C-s)}}} or short {{{kbd(C-c $)}}} :: +- {{{kbd(C-c C-x C-s)}}} or short {{{kbd(C-c $)}}} (~org-archive-subtree~) :: Archive the subtree starting at point position to the location given by ~org-archive-location~. @@ -1496,19 +1524,20 @@ Agenda buffer, see [[*Commands in the Agenda Buffer]]. The information to be shown is normally collected from all /agenda files/, the files listed in the variable ~org-agenda-files~. -#+attr_texinfo: :sep or -- {{{kbd(C-c [)}}} :: +# Use "/" separator because "," is in one of the bindings. +#+attr_texinfo: :sep / +- {{{kbd(C-c [)}}} (~org-agenda-file-to-front~) :: Add current file to the list of agenda files. The file is added to the front of the list. If it was already in the list, it is moved to the front. With a prefix argument, file is added/moved to the end. -- {{{kbd(C-c ])}}} :: +- {{{kbd(C-c ])}}} (~org-remove-file~) :: Remove current file from the list of agenda files. -- {{{kbd(C-')}}} or {{{kbd(C-\,)}}} :: +- {{{kbd(C-')}}} / {{{kbd(C-\,)}}} (~org-cycle-agenda-files~) :: Cycle through agenda file list, visiting one file after the other. @@ -1554,7 +1583,7 @@ commands: The purpose of the weekly/daily /agenda/ is to act like a page of a paper agenda, showing all the tasks for the current week or day. -- {{{kbd(M-x org-agenda a)}}} :: +- {{{kbd(M-x org-agenda a)}}} (~org-agenda-list~) :: Compile an agenda for the current week from a list of Org files. The agenda shows the entries for each day. @@ -1593,12 +1622,12 @@ can change the state of a TODO entry with a single key press. For commands available in the TODO list, see [[*Commands in the Agenda Buffer]]. -- {{{kbd(M-x org-agenda t)}}} :: +- {{{kbd(M-x org-agenda t)}}} (~org-todo-list~) :: Show the global TODO list. This collects the TODO items from all agenda files (see [[*Agenda Views]]) into a single buffer. -- {{{kbd(M-x org-agenda T)}}} :: +- {{{kbd(M-x org-agenda T)}}} (~org-todo-list~) :: Like the above, but allows selection of a specific TODO keyword. @@ -1613,7 +1642,7 @@ on this metadata and collect them into an agenda buffer. The match syntax described here also applies when creating sparse trees with {{{kbd(C-c / m)}}}. -- {{{kbd(M-x org-agenda m)}}} :: +- {{{kbd(M-x org-agenda m)}}} (~org-tags-view~) :: Produce a list of all headlines that match a given set of tags. The command prompts for a selection criterion, which is a boolean logic @@ -1621,7 +1650,7 @@ syntax described here also applies when creating sparse trees with (see [[*Tags]]). If you often need a specific search, define a custom command for it (see [[*The Agenda Dispatcher]]). -- {{{kbd(M-x org-agenda M)}}} :: +- {{{kbd(M-x org-agenda M)}}} (~org-tags-view~) :: Like {{{kbd(m)}}}, but only select headlines that are also TODO items. @@ -1651,7 +1680,7 @@ only tags. =night=. You may also test for properties at the same time as matching tags, -see the manual for more information. +see the [[info:org][manual]] for more information. ** Search View :PROPERTIES: @@ -1692,18 +1721,18 @@ file where they originate. You are not allowed to edit the agenda buffer itself, but commands are provided to show and jump to the original entry location, and to edit the Org files "remotely" from the agenda buffer. This is just a selection of the many commands, explore -the agenda menu and the manual for a complete list. +the agenda menu and the [[info:org][manual]] for a complete list. *** Motion :PROPERTIES: :UNNUMBERED: notoc :END: -- {{{kbd(n)}}} :: +- {{{kbd(n)}}} (~org-agenda-next-line~) :: Next line (same as {{{kbd(DOWN)}}} and {{{kbd(C-n)}}}). -- {{{kbd(p)}}} :: +- {{{kbd(p)}}} (~org-agenda-previous-line~) :: Previous line (same as {{{kbd(UP)}}} and {{{kbd(C-p)}}}). @@ -1712,16 +1741,16 @@ the agenda menu and the manual for a complete list. :UNNUMBERED: notoc :END: -- {{{kbd(SPC)}}} :: +- {{{kbd(SPC)}}} (~org-agenda-show-and-scroll-up~) :: Display the original location of the item in another window. With a prefix argument, make sure that drawers stay folded. -- {{{kbd(TAB)}}} :: +- {{{kbd(TAB)}}} (~org-agenda-goto~) :: Go to the original location of the item in another window. -- {{{kbd(RET)}}} :: +- {{{kbd(RET)}}} (~org-agenda-switch-to~) :: Go to the original location of the item and delete other windows. @@ -1730,37 +1759,37 @@ the agenda menu and the manual for a complete list. :UNNUMBERED: notoc :END: #+attr_texinfo: :sep , -- {{{kbd(o)}}} :: +- {{{kbd(o)}}} (~delete-other-windows~) :: Delete other windows. -- {{{kbd(v d)}}} or short {{{kbd(d)}}} :: +- {{{kbd(v d)}}} or short {{{kbd(d)}}} (~org-agenda-day-view~) :: Switch to day view. -- {{{kbd(v w)}}} or short {{{kbd(w)}}} :: +- {{{kbd(v w)}}} or short {{{kbd(w)}}} (~org-agenda-week-view~) :: Switch to week view. -- {{{kbd(f)}}} :: +- {{{kbd(f)}}} (~org-agenda-later~) :: Go forward in time to display the span following the current one. For example, if the display covers a week, switch to the following week. -- {{{kbd(b)}}} :: +- {{{kbd(b)}}} (~org-agenda-earlier~) :: Go backward in time to display earlier dates. -- {{{kbd(.)}}} :: +- {{{kbd(.)}}} (~org-agenda-goto-today~) :: Go to today. -- {{{kbd(j)}}} :: +- {{{kbd(j)}}} (~org-agenda-goto-date~) :: Prompt for a date and go there. -- {{{kbd(v l)}}} or {{{kbd(v L)}}} or short {{{kbd(l)}}} :: +- {{{kbd(v l)}}} or {{{kbd(v L)}}} or short {{{kbd(l)}}} (~org-agenda-log-mode~) :: Toggle Logbook mode. In Logbook mode, entries that were marked as done while logging was on (see the variable ~org-log-done~) are @@ -1768,12 +1797,12 @@ the agenda menu and the manual for a complete list. day. When called with a {{{kbd(C-u)}}} prefix argument, show all possible logbook entries, including state changes. -- {{{kbd(r)}}}, {{{kbd(g)}}} :: +- {{{kbd(r)}}}, {{{kbd(g)}}} (~org-agenda-redo~) :: Recreate the agenda buffer, for example to reflect the changes after modification of the timestamps of items. -- {{{kbd(s)}}} :: +- {{{kbd(s)}}} (~org-save-all-org-buffers~) :: #+kindex: C-x C-s #+findex: org-save-all-org-buffers @@ -1790,62 +1819,62 @@ the agenda menu and the manual for a complete list. Digit argument. -- {{{kbd(t)}}} :: +- {{{kbd(t)}}} (~org-agenda-todo~) :: Change the TODO state of the item, both in the agenda and in the original Org file. -- {{{kbd(C-k)}}} :: +- {{{kbd(C-k)}}} (~org-agenda-kill~) :: Delete the current agenda item along with the entire subtree belonging to it in the original Org file. -- {{{kbd(C-c C-w)}}} :: +- {{{kbd(C-c C-w)}}} (~org-agenda-refile~) :: Refile the entry at point. -- {{{kbd(a)}}} :: +- {{{kbd(a)}}} (~org-agenda-archive-default-with-confirmation~) :: Archive the subtree corresponding to the entry at point using the default archiving command set in ~org-archive-default-command~. -- {{{kbd($)}}} :: +- {{{kbd($)}}} (~org-agenda-archive~) :: Archive the subtree corresponding to the current headline. -- {{{kbd(C-c C-s)}}} :: +- {{{kbd(C-c C-s)}}} (~org-agenda-schedule~) :: Schedule this item. With a prefix argument, remove the scheduling timestamp -- {{{kbd(C-c C-d)}}} :: +- {{{kbd(C-c C-d)}}} (~org-agenda-deadline~) :: Set a deadline for this item. With a prefix argument, remove the deadline. -- {{{kbd(S-RIGHT)}}} :: +- {{{kbd(S-RIGHT)}}} (~org-agenda-do-date-later~) :: Change the timestamp associated with the current line by one day into the future. -- {{{kbd(S-LEFT)}}} :: +- {{{kbd(S-LEFT)}}} (~org-agenda-do-date-earlier~) :: Change the timestamp associated with the current line by one day into the past. -- {{{kbd(I)}}} :: +- {{{kbd(I)}}} (~org-agenda-clock-in~) :: Start the clock on the current item. -- {{{kbd(O)}}} :: +- {{{kbd(O)}}} (~org-agenda-clock-out~) :: Stop the previously started clock. -- {{{kbd(X)}}} :: +- {{{kbd(X)}}} (~org-agenda-clock-cancel~) :: Cancel the currently running clock. -- {{{kbd(J)}}} :: +- {{{kbd(J)}}} (~org-agenda-clock-goto~) :: Jump to the running clock in another window. @@ -1854,11 +1883,11 @@ the agenda menu and the manual for a complete list. :UNNUMBERED: notoc :END: -- {{{kbd(q)}}} :: +- {{{kbd(q)}}} (~org-agenda-quit~) :: Quit agenda, remove the agenda buffer. -- {{{kbd(x)}}} :: +- {{{kbd(x)}}} (~org-agenda-exit~) :: Exit agenda, remove the agenda buffer and all buffers loaded by Emacs for the compilation of the agenda. @@ -2073,7 +2102,7 @@ The Org website[fn:1] now looks a lot better than it used to. The following commands handle footnotes: -- {{{kbd(C-c C-x f)}}} :: +- {{{kbd(C-c C-x f)}}} (~org-footnote-action~) :: The footnote action command. When point is on a footnote reference, jump to the definition. When it is at a definition, jump to the @@ -2081,7 +2110,7 @@ The following commands handle footnotes: command is called with a prefix argument, a menu of additional options including renumbering is offered. -- {{{kbd(C-c C-c)}}} :: +- {{{kbd(C-c C-c)}}} (~org-ctrl-c-ctrl-c~) :: Jump between definition and reference. @@ -2103,7 +2132,7 @@ The export dispatcher is the main interface for Org's exports. A hierarchical menu presents the currently configured export formats. Options are shown as easy toggle switches on the same screen. -- {{{kbd(C-c C-e)}}} :: +- {{{kbd(C-c C-e)}}} (~org-export-dispatch~) :: Invokes the export dispatcher interface. @@ -2187,7 +2216,7 @@ Finally, a =COMMENT= keyword at the beginning of an entry, but after any other keyword or priority cookie, comments out the entire subtree. The command below helps changing the comment status of a headline. -- {{{kbd(C-c ;)}}} :: +- {{{kbd(C-c ;)}}} (~org-toggle-comment~) :: Toggle the =COMMENT= keyword at the beginning of an entry. @@ -2202,7 +2231,7 @@ does not contain any Org markup. UTF-8 export uses additional characters and symbols available in this encoding standards. #+attr_texinfo: :sep , -- {{{kbd(C-c C-e t a)}}}, {{{kbd(C-c C-e t u)}}} :: +- {{{kbd(C-c C-e t a)}}}, {{{kbd(C-c C-e t u)}}} (~org-ascii-export-to-ascii~) :: Export as an ASCII file with a =.txt= extension. For =myfile.org=, Org exports to =myfile.txt=, overwriting without warning. For @@ -2217,14 +2246,14 @@ characters and symbols available in this encoding standards. Org mode contains an HTML exporter with extensive HTML formatting compatible with XHTML 1.0 strict standard. -- {{{kbd(C-c C-e h h)}}} :: +- {{{kbd(C-c C-e h h)}}} (~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 C-e h o)}}} exports to HTML and opens it in a web browser. -The HTML export back-end transforms =<= and =>= to =<= and =>=. -To include raw HTML code in the Org file so the HTML export back-end +The HTML export backend transforms =<= and =>= to =<= and =>=. +To include raw HTML code in the Org file so the HTML export backend can insert that HTML code in the output, use this inline syntax: =@@html:...@@=. For example: @@ -2245,7 +2274,7 @@ For larger raw HTML code blocks, use these HTML export code blocks: :DESCRIPTION: Exporting to @LaTeX{} and processing to PDF. :END: -The LaTeX export back-end can handle complex documents, incorporate +The LaTeX export backend can handle complex documents, incorporate standard or custom LaTeX document classes, generate documents using alternate LaTeX engines, and produce fully linked PDF files with indexes, bibliographies, and tables of contents, destined for @@ -2255,21 +2284,21 @@ By default, the LaTeX output uses the /article/ class. You can change this by adding an option like =#+LATEX_CLASS: myclass= in your file. The class must be listed in ~org-latex-classes~. -- {{{kbd(C-c C-e l l)}}} :: +- {{{kbd(C-c C-e l l)}}} (~org-latex-export-to-latex~) :: Export to a LaTeX file with a =.tex= extension. For =myfile.org=, Org exports to =myfile.tex=, overwriting without warning. -- {{{kbd(C-c C-e l p)}}} :: +- {{{kbd(C-c C-e l p)}}} (~org-latex-export-to-pdf~) :: Export as LaTeX file and convert it to PDF file. -- {{{kbd(C-c C-e l o)}}} :: +- {{{kbd(C-c C-e l o)}}} (~~) :: Export as LaTeX file and convert it to PDF, then open the PDF using the default viewer. -The LaTeX export back-end can insert any arbitrary LaTeX code, see +The LaTeX export backend can insert any arbitrary LaTeX code, see [[*Embedded LaTeX]]. There are three ways to embed such code in the Org file and they all use different quoting syntax. @@ -2281,7 +2310,7 @@ Inserting as one or more keyword lines in the Org file: : #+LATEX: any arbitrary LaTeX code -Inserting as an export block in the Org file, where the back-end +Inserting as an export block in the Org file, where the backend exports any code between begin and end markers: #+begin_example @@ -2297,15 +2326,15 @@ exports any code between begin and end markers: A large part of Org mode's interoperability success is its ability to easily export to or import from external applications. The iCalendar -export back-end takes calendar data from Org files and exports to the +export backend takes calendar data from Org files and exports to the standard iCalendar format. -- {{{kbd(C-c C-e c f)}}} :: +- {{{kbd(C-c C-e c f)}}} (~org-icalendar-export-to-ics~) :: Create iCalendar entries from the current Org buffer and store them in the same directory, using a file extension =.ics=. -- {{{kbd(C-c C-e c c)}}} :: +- {{{kbd(C-c C-e c c)}}} (~org-icalendar-combine-agenda-files~) :: Create a combined iCalendar file from Org files in ~org-agenda-files~ and write it to @@ -2326,7 +2355,7 @@ You can also use Org to convert files into PDF, or even combine HTML and PDF conversion so that files are available in both formats on the server. -For detailed instructions about setup, see the manual. Here is an +For detailed instructions about setup, see the [[info:org][manual]]. Here is an example: #+begin_src emacs-lisp @@ -2342,20 +2371,20 @@ example: type=\"text/css\"/>"))) #+end_src -- {{{kbd(C-c C-e P x)}}} :: +- {{{kbd(C-c C-e P x)}}} (~org-publish~) :: Prompt for a specific project and publish all files that belong to it. -- {{{kbd(C-c C-e P p)}}} :: +- {{{kbd(C-c C-e P p)}}} (~org-publish-current-project~) :: Publish the project containing the current file. -- {{{kbd(C-c C-e P f)}}} :: +- {{{kbd(C-c C-e P f)}}} (~org-publish-current-file~) :: Publish only the current file. -- {{{kbd(C-c C-e P a)}}} :: +- {{{kbd(C-c C-e P a)}}} (~org-publish-all~) :: Publish every project. @@ -2452,7 +2481,7 @@ Use {{{kbd(C-c C-c)}}} to evaluate the current code block and insert its results in the Org document. By default, evaluation is only turned on for =emacs-lisp= code blocks, however support exists for evaluating blocks in many languages. For a complete list of supported -languages see the manual. The following shows a code block and its +languages see the [[info:org][manual]]. The following shows a code block and its results. #+begin_example @@ -2537,7 +2566,7 @@ referred to as "tangling"---a term adopted from the literate programming community. During tangling of code blocks their bodies are expanded using ~org-babel-expand-src-block~, which can expand both variable and "Noweb" style references. In order to tangle a code -block it must have a =tangle= header argument, see the manual for +block it must have a =tangle= header argument, see the [[info:org][manual]] for details. * Miscellaneous @@ -2567,7 +2596,7 @@ a headline. To quickly insert empty structural blocks, such as =#+BEGIN_SRC= ... =#+END_SRC=, or to wrap existing text in such a block, use -- {{{kbd(C-c C-\,)}}} :: +- {{{kbd(C-c C-\,)}}} (~org-insert-structure-template~) :: Prompt for a type of block structure, and insert the block at point. If the region is active, it is wrapped in the block. diff --git a/elpa/org-9.6.7/doc/org-manual.org b/elpa/org-9.7.17/doc/org-manual.org similarity index 91% rename from elpa/org-9.6.7/doc/org-manual.org rename to elpa/org-9.7.17/doc/org-manual.org index ea519ea3..8fbd2f2c 100644 --- a/elpa/org-9.6.7/doc/org-manual.org +++ b/elpa/org-9.7.17/doc/org-manual.org @@ -2,6 +2,7 @@ #+subtitle: Release {{{version}}} #+author: The Org Mode Developers #+language: en +#+startup: literallinks #+texinfo: @insertcopying @@ -22,8 +23,11 @@ Org Mode is an authoring tool and a TODO lists manager for GNU Emacs. It relies on a lightweight plain-text markup language used in files with the =.org= extension. +Authoring Org files is best supported by Emacs, but you can view, +understand, and change them with any text editor. + As an authoring tool, Org helps you write structured documents and -provides exporting facilities. Org files can also be used for literate +provides exporting facilities. Org files can also be used for literate programming and reproducible research. As a TODO lists manager, Org helps you organize your tasks in a flexible way, from daily needs to detailed project-planning, allowing logging, multiple views on your @@ -96,6 +100,10 @@ When installing Org on top of the pre-packaged version, please note that Org stable versions are meant to be fully compatible with the last three stable versions of Emacs but not with older Emacsen. +Some Org components also depend on third-party packages available +through package archives. Org is only guaranteed to be compatible +with the latest stable versions of these third-party packages. + *** Using Emacs packaging system :PROPERTIES: :UNNUMBERED: notoc @@ -112,6 +120,16 @@ visited, i.e., where no Org built-in function have been loaded. Otherwise autoload Org functions will mess up the installation. #+end_quote +To avoid interference with built-in Org mode, you can use command line: + +#+begin_src sh +emacs -Q -batch -eval "(progn (require 'package) (package-initialize) (package-refresh-contents) (package-upgrade 'org))" +#+end_src + +This approach has the advantage of isolating the upgrade process from +a running Emacs session, ensuring that version conflicts can not +arise. + *** Using Org's git repository :PROPERTIES: :UNNUMBERED: notoc @@ -184,7 +202,7 @@ For a better experience, the three Org commands ~org-store-link~, Emacs, not just in Org buffers. To that effect, you need to bind them to globally available keys, like the ones reserved for users (see [[info:elisp::Key Binding Conventions]]). Here are suggested bindings, -please modify the keys to your own liking. +please modify the keys to your own liking in your [[info:emacs#Init File][personal init file]]. #+begin_src emacs-lisp (global-set-key (kbd "C-c l") #'org-store-link) @@ -215,8 +233,12 @@ region by using the mouse to select a region, or pressing :DESCRIPTION: Bug reports, ideas, patches, etc. :END: #+cindex: feedback +#+cindex: contact #+cindex: bug reports #+cindex: reporting a bug +#+cindex: request a feature +#+cindex: feature requests +#+cindex: ideas #+cindex: maintainer #+cindex: author @@ -295,8 +317,17 @@ information about: 2. What did you expect to happen? 3. What happened instead? -Thank you for helping to improve this program. +#+cindex: performance +#+cindex: profile +#+cindex: slow +#+cindex: slowdown +#+cindex: laggy +#+cindex: not responsive +If you experience degraded performance, you can record a "profile" and +share it on the Org mailing list. See below for the instructions how +to record a useful profile. +Thank you for helping to improve this program. *** How to create a useful backtrace :PROPERTIES: :UNNUMBERED: notoc @@ -332,6 +363,67 @@ error occurred. Here is how to produce a useful backtrace: screen. Save this buffer to a file---for example using {{{kbd(C-x C-w)}}}---and attach it to your bug report. +*** How to profile Org performance +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +#+cindex: profiler +Sometimes, Org is becoming slow for no apparent reason. Such slowdown +is often caused by interaction between third-party packages and Org +mode. However, identifying the root cause is not always straightforward. + +Emacs is able to record performance statistics, which can then be used +to find out which functions are taking most of the time to execute. +To record the statistics, one can use so-called profiler. To use the +Emacs profiler, we recommend the following steps: + +1. Make sure that no profiler is currently active: + + : M-x profiler-stop + +2. Start a new CPU profiler session: + + : M-x profiler-start cpu + +3. Use Emacs as usual, performing the actions that are deemed slow. + +4. Display and examine the recorded performance statistics: + + : M-x profiler-report + + This command will display a summary of the commands and functions + that have been executed between ~profiler-start~ and + ~profiler-report~ invocations, with command taking most of the time + displayed on top. + + == key can be used to fold and unfold lines in the profiler + buffer. The child items revealed upon unfolding are the functions + and commands called by the unfolded parent. + + The root causes are often buried deep inside sub-children items in + the profiler. You can press =B= (~profiler-report-render-reversed-calltree~) + to quickly reveal the actual function/command that takes most of + the time to run. + + Pressing =C= ~profiler-report-render-calltree~ will recover the + original view. + +5. If you need further help, you can share the statistics data. + + Just save the data by issuing + + : M-x profiler-report-write-profile + : /path/to/profile-file-to-be-saved + + Then, you can attached the saved file to your email to the Org + mailing list, alongside with details about what you did to trigger + the slowdown. + + Note that the saved statistics will only contain the function names + and how long their execution takes. No private data will be + recorded. + ** Typesetting Conventions Used in this Manual :PROPERTIES: :DESCRIPTION: Typesetting conventions used in this manual. @@ -430,7 +522,7 @@ as a title for your own headings. Some people find the many stars too noisy and would prefer an outline that has whitespace followed by a single star as headline starters. -This can be achieved using a Org Indent minor mode. See [[*A Cleaner +This can be achieved using an Org Indent minor mode. See [[*A Cleaner Outline View]] for more information. Headlines are not numbered. However, you may want to dynamically @@ -512,11 +604,11 @@ Org uses just two commands, bound to {{{kbd(TAB)}}} and the very beginning of the buffer, but not on a headline, and ~org-cycle-global-at-bob~ is set to a non-~nil~ value. -- {{{kbd(C-u C-u TAB)}}} (~org-set-startup-visibility~) :: +- {{{kbd(C-u C-u TAB)}}} (~org-cycle-set-startup-visibility~) :: #+cindex: startup visibility #+kindex: C-u C-u TAB - #+findex: org-set-startup-visibility + #+findex: org-cycle-set-startup-visibility Switch back to the startup visibility of the buffer (see [[*Initial visibility]]). @@ -603,10 +695,10 @@ Furthermore, any entries with a =VISIBILITY= property (see [[*Properties and Columns]]) get their visibility adapted accordingly. Allowed values for this property are =folded=, =children=, =content=, and =all=. -- {{{kbd(C-u C-u TAB)}}} (~org-set-startup-visibility~) :: +- {{{kbd(C-u C-u TAB)}}} (~org-cycle-set-startup-visibility~) :: #+kindex: C-u C-u TAB - #+findex: org-set-startup-visibility + #+findex: org-cycle-set-startup-visibility Switch back to the startup visibility of the buffer, i.e., whatever is requested by startup options and =VISIBILITY= properties in individual entries. @@ -618,11 +710,17 @@ for this property are =folded=, =children=, =content=, and =all=. #+cindex: edits, catching invisible #+vindex: org-fold-catch-invisible-edits +#+vindex: org-fold-catch-invisible-edits-commands Sometimes you may inadvertently edit an invisible part of the buffer and be confused on what has been edited and how to undo the mistake. -Setting ~org-fold-catch-invisible-edits~ to non-~nil~ helps preventing -this. See the docstring of this option on how Org should catch -invisible edits and process them. +By default, Org prevents such edits for a limited set of user +commands. Users can control which commands are affected by +customizing ~org-fold-catch-invisible-edits-commands~. + +The strategy used to decide if a given edit is dangerous is controlled +by ~org-fold-catch-invisible-edits~. See the docstring of this option +on the available strategies. Set the option to ~nil~ to disable +catching invisible edits completely. ** Motion :PROPERTIES: @@ -833,7 +931,9 @@ The following commands jump to other headlines in the buffer. Yank subtree from kill ring. This does modify the level of the subtree to make sure the tree fits in nicely at the yank position. The yank level can also be specified with a numeric prefix argument, - or by yanking after a headline marker like =****=. + or by yanking after a headline marker like =****=. With + {{{kbd(C-u)}}} prefix, force inserting as a sibling. With + {{{kbd(C-u C-u)}}} prefix argument, force inserting as a child. - {{{kbd(C-y)}}} (~org-yank~) :: @@ -1062,6 +1162,7 @@ My favorite scenes are (in this order) 3. Peter Jackson being shot by Legolas - on DVD only He makes a really funny face when it happens. +8. [@8] But in the end, no individual scenes matter but the film as a whole. Important actors in this film are: - Elijah Wood :: He plays Frodo @@ -2255,6 +2356,17 @@ to read than the equivalent: : '(substring $1 (string-to-number $2) (string-to-number $3)) +When the formula itself contains =;= symbol, Org mode may incorrectly +interpret everything past =;= as format specifier: + +: '(concat $1 ";") + +#+texinfo: @noindent +You can put an extra tailing =;= to indicate that all the earlier +instances of =;= belong to the formula itself: + +: '(concat $1 ";"); + *** Durations and time values :PROPERTIES: :DESCRIPTION: How to compute durations and time values. @@ -2903,6 +3015,11 @@ For more information and examples see the [[https://orgmode.org/worg/org-tutoria Specify which column of the table to use as the =x= axis. +- =timeind= :: + + Specify which column of the table to use as the =x= axis as a time + value. + - =deps= :: Specify the columns to graph as a Lisp style list, surrounded by @@ -2910,7 +3027,7 @@ 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 :: +- =transpose= :: When =y=, =yes=, or =t= attempt to transpose the table data before plotting. Also recognizes the shorthand option =trans=. @@ -2945,21 +3062,21 @@ 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 :: +- =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 :: +- =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 :: +- =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 @@ -3088,7 +3205,8 @@ precise behavior depends on how point arrived there---see incomplete and the internals are again displayed as plain text. Inserting the missing bracket hides the link internals again. To show the internal structure of all links, use the menu: Org \rarr -Hyperlinks \rarr Literal links. +Hyperlinks \rarr Literal links, customize ~org-link-descriptive~, or use +=literallinks= [[*Summary of In-Buffer Settings][startup option]]. ** Internal Links :PROPERTIES: @@ -3212,10 +3330,6 @@ Here is the full set of built-in link types: 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. - As a special case, "file" prefix may be omitted if the file name is complete, e.g., it starts with =./=, or =/=. @@ -3245,7 +3359,7 @@ Here is the full set of built-in link types: - =gnus=, =rmail=, =mhe= :: - Link to messages or folders from a given Emacs' MUA. + Link to messages or folders from a given Emacs MUA. - =help= :: @@ -3279,44 +3393,50 @@ Here is the full set of built-in link types: Execute a shell command upon activation. + +For =file:= and =id:= links, you can additionally specify a line +number, or a text search string, separated by =::=. In Org files, you +may link to a headline name, a custom ID, or a code reference instead. + The following table illustrates the link types above, along with their options: -| Link Type | Example | -|------------+----------------------------------------------------------| -| http | =http://staff.science.uva.nl/c.dominik/= | -| https | =https://orgmode.org/= | -| doi | =doi:10.1000/182= | -| file | =file:/home/dominik/images/jupiter.jpg= | -| | =/home/dominik/images/jupiter.jpg= (same as above) | -| | =file:papers/last.pdf= | -| | =./papers/last.pdf= (same as above) | -| | =file:/ssh:me@some.where:papers/last.pdf= (remote) | -| | =/ssh:me@some.where:papers/last.pdf= (same as above) | -| | =file:sometextfile::NNN= (jump to line number) | -| | =file:projects.org= | -| | =file:projects.org::some words= (text search)[fn:12] | -| | =file:projects.org::*task title= (headline search) | -| | =file:projects.org::#custom-id= (headline search) | -| attachment | =attachment:projects.org= | -| | =attachment:projects.org::some words= (text search) | -| docview | =docview:papers/last.pdf::NNN= | -| id | =id:B7423F4D-2E8A-471B-8810-C40F074717E9= | -| news | =news:comp.emacs= | -| mailto | =mailto:adent@galaxy.net= | -| mhe | =mhe:folder= (folder link) | -| | =mhe:folder#id= (message link) | -| rmail | =rmail:folder= (folder link) | -| | =rmail:folder#id= (message link) | -| gnus | =gnus:group= (group link) | -| | =gnus:group#id= (article link) | -| bbdb | =bbdb:R.*Stallman= (record with regexp) | -| irc | =irc:/irc.com/#emacs/bob= | -| help | =help:org-store-link= | -| info | =info:org#External links= | -| shell | =shell:ls *.org= | -| elisp | =elisp:(find-file "Elisp.org")= (Elisp form to evaluate) | -| | =elisp:org-agenda= (interactive Elisp command) | +| Link Type | Example | +|------------+--------------------------------------------------------------------| +| http | =http://staff.science.uva.nl/c.dominik/= | +| https | =https://orgmode.org/= | +| doi | =doi:10.1000/182= | +| file | =file:/home/dominik/images/jupiter.jpg= | +| | =/home/dominik/images/jupiter.jpg= (same as above) | +| | =file:papers/last.pdf= | +| | =./papers/last.pdf= (same as above) | +| | =file:/ssh:me@some.where:papers/last.pdf= (remote) | +| | =/ssh:me@some.where:papers/last.pdf= (same as above) | +| | =file:sometextfile::NNN= (jump to line number) | +| | =file:projects.org= | +| | =file:projects.org::some words= (text search)[fn:12] | +| | =file:projects.org::*task title= (headline search) | +| | =file:projects.org::#custom-id= (headline search) | +| attachment | =attachment:projects.org= | +| | =attachment:projects.org::some words= (text search) | +| docview | =docview:papers/last.pdf::NNN= | +| id | =id:B7423F4D-2E8A-471B-8810-C40F074717E9= | +| | =id:B7423F4D-2E8A-471B-8810-C40F074717E9::*task= (headline search) | +| news | =news:comp.emacs= | +| mailto | =mailto:adent@galaxy.net= | +| mhe | =mhe:folder= (folder link) | +| | =mhe:folder#id= (message link) | +| rmail | =rmail:folder= (folder link) | +| | =rmail:folder#id= (message link) | +| gnus | =gnus:group= (group link) | +| | =gnus:group#id= (article link) | +| bbdb | =bbdb:R.*Stallman= (record with regexp) | +| irc | =irc:/irc.com/#emacs/bob= | +| help | =help:org-store-link= | +| info | =info:org#External links= | +| shell | =shell:ls *.org= | +| elisp | =elisp:(find-file "Elisp.org")= (Elisp form to evaluate) | +| | =elisp:org-agenda= (interactive Elisp command) | #+cindex: VM links #+cindex: Wanderlust links @@ -3377,8 +3497,9 @@ current buffer: - /Org mode buffers/ :: For Org files, if there is a =<>= at point, the link points - to the target. Otherwise it points to the current headline, which - is also the description. + to the target. If there is a named block (using =#+name:=) at + point, the link points to that name. Otherwise it points to the + current headline, which is also the description. #+vindex: org-id-link-to-org-use-id #+cindex: @samp{CUSTOM_ID}, property @@ -3396,6 +3517,32 @@ current buffer: timestamp, depending on ~org-id-method~. Later, when inserting the link, you need to decide which one to use. + #+vindex: org-id-link-consider-parent-id + #+vindex: org-id-link-use-context + #+vindex: org-link-context-for-files + When ~org-id-link-consider-parent-id~ is ~t~[fn:: Also, + ~org-link-context-for-files~ and ~org-id-link-use-context~ should be + both enabled (which they are, by default).], parent =ID= properties + are considered. This allows linking to specific targets, named + blocks, or headlines (which may not have a globally unique =ID= + themselves) within the context of a parent headline or file which + does. + + For example, given this org file: + + #+begin_src org + ,* Parent + :PROPERTIES: + :ID: abc + :END: + ,** Child 1 + ,** Child 2 + #+end_src + + Storing a link with point at "Child 1" will produce a link + ==, which precisely links to the "Child 1" + headline even though it does not have its own ID. + - /Email/News clients: VM, Rmail, Wanderlust, MH-E, Gnus/ :: #+vindex: org-link-email-description-format @@ -3619,7 +3766,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=") + '(("bugzilla" . "https://10.1.2.9/bugzilla/show_bug.cgi?id=") ("Nu Html Checker" . "https://validator.w3.org/nu/?doc=%h") ("duckduckgo" . "https://duckduckgo.com/?q=%s") ("omap" . "https://nominatim.openstreetmap.org/search?q=%s&polygon=1") @@ -3641,8 +3788,8 @@ argument. With the above setting, you could link to a specific bug with =[[bugzilla:129]]=, search the web for =OrgMode= with =[[duckduckgo:OrgMode]]=, -show the map location of the Free Software Foundation =[[gmap:51 -Franklin Street, Boston]]= or of Carsten office =[[omap:Science Park 904, +show the map location of the Free Software Foundation =[[omap:31 +Milk Street, Boston]]= or of Carsten's office =[[omap:Science Park 904, Amsterdam, The Netherlands]]= and find out what the Org author is doing besides Emacs hacking with =[[ads:Dominik,C]]=. @@ -3675,7 +3822,9 @@ the link completion function like this: :ALT_TITLE: Search Options :END: #+cindex: search option in file links +#+cindex: search option in id links #+cindex: file links, searching +#+cindex: id links, searching #+cindex: attachment links, searching File links can contain additional information to make Emacs jump to a @@ -3687,8 +3836,8 @@ example, when the command ~org-store-link~ creates a link (see line as a search string that can be used to find this line back later when following the link with {{{kbd(C-c C-o)}}}. -Note that all search options apply for Attachment links in the same -way that they apply for File links. +Note that all search options apply for Attachment and ID links in the +same way that they apply for File links. Here is the syntax of the different ways to attach a search to a file link, together with explanations for each: @@ -4023,10 +4172,9 @@ meaning here.]. For example: (sequence "|" "CANCELED(c)"))) #+end_src -#+vindex: org-fast-tag-selection-include-todo If you then press {{{kbd(C-c C-t)}}} followed by the selection key, the entry is switched to this state. {{{kbd(SPC)}}} can be used to -remove any TODO keyword from an entry[fn:15]. +remove any TODO keyword from an entry. *** Setting up keywords for individual files :PROPERTIES: @@ -4282,7 +4430,7 @@ example, with the setting 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=, and that a note is recorded when switching to =WAIT= or -=CANCELED=[fn:16]. The setting for =WAIT= is even more special: the +=CANCELED=[fn:15]. The setting for =WAIT= is even more special: the =!= after the slash means that in addition to the note taken when entering the state, a timestamp should be recorded when /leaving/ the =WAIT= state, if and only if the /target/ state does not configure @@ -4344,8 +4492,10 @@ A habit has the following properties: 3. The TODO has a scheduled date, usually with a =.+= style repeat interval. A =++= style may be appropriate for habits with time - constraints, e.g., must be done on weekends, or a =+= style for an - unusual habit that can have a backlog, e.g., weekly reports. + constraints, e.g., must be done on specific days of week (=++1w=), + or a =+= style for an unusual habit that can have a backlog, e.g., + weekly reports. See [[*Repeated tasks]] for more details about repeat + intervals. 4. The TODO may also have minimum and maximum ranges specified by using the syntax =.+2d/3d=, which says that you want to do the task @@ -4562,7 +4712,7 @@ all children are done, you can use the following setup: #+begin_src emacs-lisp (defun org-summary-todo (n-done n-not-done) "Switch entry to DONE when all subentries are done, to TODO otherwise." - (let (org-log-done org-log-states) ; turn off logging + (let (org-log-done org-todo-log-states) ; turn off logging (org-todo (if (= n-not-done 0) "DONE" "TODO")))) (add-hook 'org-after-todo-statistics-hook #'org-summary-todo) @@ -4578,7 +4728,7 @@ of) a large number of subtasks (see [[*Checkboxes]]). #+cindex: checkboxes #+vindex: org-list-automatic-rules -Every item in a plain list[fn:17] (see [[*Plain Lists]]) can be made into +Every item in a plain list[fn:16] (see [[*Plain Lists]]) can be made into a checkbox by starting it with the string =[ ]=. This feature is similar to TODO items (see [[*TODO Items]]), but is more lightweight. Checkboxes are not included into the global TODO list, so they are @@ -4598,15 +4748,10 @@ Here is an example of a checkbox list. - [X] talk to the neighbors #+end_example -Checkboxes work hierarchically, so if a checkbox item has children -that are checkboxes, toggling one of the children checkboxes makes the -parent checkbox reflect if none, some, or all of the children are -checked. - #+cindex: statistics, for checkboxes #+cindex: checkbox statistics #+cindex: @samp{COOKIE_DATA}, property -#+vindex: org-hierarchical-checkbox-statistics +#+vindex: org-checkbox-hierarchical-statistics The =[2/4]= and =[1/3]= in the first and second line are cookies indicating how many checkboxes present in this entry have been checked off, and the total number of checkboxes present. This can give you an @@ -4614,7 +4759,7 @@ idea on how many checkboxes remain, even without opening a folded entry. The cookies can be placed into a headline or into (the first line of) a plain list item. Each cookie covers checkboxes of direct children structurally below the headline/item on which the cookie -appears[fn:: Set the variable ~org-hierarchical-checkbox-statistics~ +appears[fn:: Set the variable ~org-checkbox-hierarchical-statistics~ if you want such cookies to count all checkboxes below the cookie, not just those belonging to direct children.]. You have to insert the cookie yourself by typing either =[/]= or =[%]=. With =[/]= you get @@ -4633,6 +4778,37 @@ If the current outline node has an =ORDERED= property, checkboxes must be checked off in sequence, and an error is thrown if you try to check off a box while there are unchecked boxes above it. +A checkbox can be in one of the three states: +1. not checked =[ ]= +2. partially checked =[-]= +3. checked =[X]= + +Checkboxes work hierarchically, so if a checkbox item has children +that are checkboxes, toggling one of the children checkboxes makes the +parent checkbox reflect if none, some, or all of the children are +checked. + +If all child checkboxes are not checked, the parent checkbox is also not checked. +#+begin_example +- [ ] call people + - [ ] Peter + - [ ] Sarah +#+end_example + +If some but not all child checkboxes are checked, the parent checkbox is partially checked. +#+begin_example +- [-] call people + - [X] Peter + - [ ] Sarah +#+end_example + +If all child checkboxes are checked, the parent checkbox is also checked. +#+begin_example +- [X] call people + - [X] Peter + - [X] Sarah +#+end_example + The following commands work with checkboxes: - {{{kbd(C-c C-c)}}} (~org-toggle-checkbox~) :: @@ -4769,15 +4945,6 @@ To limit tag inheritance to specific tags, or to turn it off entirely, use the variables ~org-use-tag-inheritance~ and ~org-tags-exclude-from-inheritance~. -#+vindex: org-tags-match-list-sublevels -When a headline matches during a tags search while tag inheritance is -turned on, all the sublevels in the same tree---for a simple match -form---match as well[fn:: This is only true if the search does not -involve more complex tests including properties (see [[*Property -Searches]]).]. The list of matches may then become very long. If you -only want to see the first tags match in a subtree, configure the -variable ~org-tags-match-list-sublevels~ (not recommended). - #+vindex: org-agenda-use-tag-inheritance Tag inheritance is relevant when the agenda search tries to match a tag, either in the ~tags~ or ~tags-todo~ agenda types. In other @@ -4987,6 +5154,11 @@ effect: start selection with {{{kbd(C-c C-c C-c)}}} instead of the special window is not even shown for single-key tag selection, it comes up only when you press an extra {{{kbd(C-c)}}}. +#+vindex: org-fast-tag-selection-maximum-tags +The number of tags displayed in the fast tag selection interface is +limited by ~org-fast-tag-selection-maximum-tags~ to avoid running out +of keyboard keys. You can customize this variable. + ** Tag Hierarchy :PROPERTIES: :DESCRIPTION: Create a hierarchy of tags. @@ -5120,10 +5292,8 @@ related information into special lists. - {{{kbd(M-x org-agenda M)}}} (~org-tags-view~) :: #+kindex: M @r{(Agenda dispatcher)} - #+vindex: org-tags-match-list-sublevels Create a global list of tag matches from all agenda files, but check - only TODO items and force checking subitems (see the option - ~org-tags-match-list-sublevels~). + only TODO items. These commands all prompt for a match string which allows basic Boolean logic like =+boss+urgent-project1=, to find entries with tags @@ -5205,10 +5375,10 @@ disks in a box like this: :END: #+end_example -Properties can be inserted on buffer level. That means they apply +Properties can be inserted at the buffer level. That means they apply before the first headline and can be inherited by all entries in a -file. Property blocks defined before first headline needs to be -located at the top of the buffer, allowing only comments above. +file. Property blocks defined before the first headline must be at +the top of the buffer with only comments above them. Properties can also be defined using lines like: @@ -5358,8 +5528,8 @@ not be used as keys in the properties drawer: | =PRIORITY= | The priority of the entry, a string with a single letter. | | =SCHEDULED= | The scheduling timestamp. | | =TAGS= | The tags defined directly in the headline. | -| =TIMESTAMP= | The first keyword-less timestamp in the entry. | -| =TIMESTAMP_IA= | The first inactive timestamp in the entry. | +| =TIMESTAMP= | The first active keyword-less timestamp in the entry.[fn:17] | +| =TIMESTAMP_IA= | The first inactive keyword-less timestamp in the entry. | | =TODO= | The TODO keyword of the entry. | ** Property Searches @@ -5391,10 +5561,8 @@ Searches]]). - {{{kbd(M-x org-agenda M)}}} (~org-tags-view~) :: #+kindex: M @r{(Agenda dispatcher)} - #+vindex: org-tags-match-list-sublevels Create a global list of tag matches from all agenda files, but check - only TODO items and force checking of subitems (see the option - ~org-tags-match-list-sublevels~). + only TODO items. The syntax for the search string is described in [[*Matching tags and properties]]. @@ -5757,6 +5925,30 @@ either for all clocks or just for today. #+findex: org-columns-delete Delete the current column. +- {{{kbd(M-LEFT)}}} (~org-columns-move-left~) :: + + #+kindex: M-LEFT + #+findex: org-columns-move-left + Move the current column left. + +- {{{kbd(M-RIGHT)}}} (~org-columns-move-right~) :: + + #+kindex: M-RIGHT + #+findex: org-columns-move-right + Move the current column right. + +- {{{kbd(M-UP)}}} (~org-columns-move-row-up~) :: + + #+kindex: M-UP + #+findex: org-columns-move-row-up + Move the current row up. + +- {{{kbd(M-DOWN)}}} (~org-columns-move-row-down~) :: + + #+kindex: M-DOWN + #+findex: org-columns-move-row-down + Move the current row down. + *** Capturing column view :PROPERTIES: :DESCRIPTION: A dynamic block for column view. @@ -5838,11 +6030,23 @@ This dynamic block has the following parameters: When non-~nil~, indent each =ITEM= field according to its level. +- =:link= :: + + When non-~nil~, link the =ITEM= headlines in the table to their + origins. + - =:format= :: Specify a column attribute (see [[*Column attributes]]) for the dynamic block. +- =:formatter= :: + + #+cindex: @samp{formatter}, dynamic block parameter + #+vindex: org-columns-dblock-formatter + A function to format column view data and insert it into the buffer. + See the option ~org-columns-dblock-formatter~. + The following commands insert or update the dynamic block: - ~org-columns-insert-dblock~ :: @@ -5861,7 +6065,7 @@ The following commands insert or update the dynamic block: #+kindex: C-c C-c #+kindex: C-c C-x C-u #+findex: org-dblock-update - Update dynamic block at point. point needs to be in the =#+BEGIN= + Update dynamic block at point. Point needs to be on the =#+BEGIN= line of the dynamic block. - {{{kbd(C-u C-c C-x C-u)}}} (~org-update-all-dblocks~) :: @@ -5901,6 +6105,11 @@ a little confusing because timestamp is often used as indicating when something was created or last changed. However, in Org mode this term is used in a much wider sense. +Timestamps can be used to plan appointments, schedule tasks, set +deadlines, track time, and more. The following sections describe +the timestamp format and tooling that Org mode provides for common +use cases dealing with time and time intervals. + ** Timestamps :PROPERTIES: :DESCRIPTION: Assigning a time to a tree entry. @@ -5911,8 +6120,8 @@ is used in a much wider sense. #+cindex: deadlines #+cindex: scheduling -A timestamp is a specification of a date (possibly with a time or -a range of times) in a special format, either =<2003-09-16 Tue>= or +A timestamp is a specification of a date---possibly with a time or +time range---in a special format, either =<2003-09-16 Tue>= or =<2003-09-16 Tue 09:39>= or =<2003-09-16 Tue 12:00-12:30>=[fn:19]. A timestamp can appear anywhere in the headline or body of an Org tree entry. Its presence causes entries to be shown on specific dates in @@ -5925,13 +6134,17 @@ the agenda (see [[*Weekly/daily agenda]]). We distinguish: A simple timestamp just assigns a date/time to an item. This is just like writing down an appointment or event in a paper agenda. In the agenda display, the headline of an entry associated with - a plain timestamp is shown exactly on that date. + a plain timestamp is shown exactly on that date. There can be + multiple timestamps in an item. #+begin_example ,* Meet Peter at the movies <2006-11-01 Wed 19:15> ,* Discussion on climate change - <2006-11-02 Thu 20:00-22:00> + <2006-11-02 Thu 10:00-12:00> + ,* My days off + <2006-11-03 Fri> + <2006-11-06 Mon> #+end_example - Timestamp with repeater interval :: @@ -5964,20 +6177,35 @@ the agenda (see [[*Weekly/daily agenda]]). We distinguish: #+begin_example ,* 22:00-23:00 The nerd meeting on every 2nd Thursday of the month - <%%(diary-float t 4 2)> + <%%(diary-float t 4 2) 22:00-23:00> + #+end_example + +- Time range :: + #+cindex: time range + + Time range is a timestamp having two time units connected by =-= + + #+begin_example +,* Discussion on climate change + <2006-11-02 Thu 10:00-12:00> #+end_example - Time/Date range :: + #+cindex: time range #+cindex: timerange #+cindex: date range - Two timestamps connected by =--= denote a range. The headline is - shown on the first and last day of the range, and on any dates that - are displayed and fall in the range. Here is an example: + Two timestamps connected by =--= denote a range. In the agenda, the + headline is shown on the first and last day of the range, and on any + dates that are displayed and fall in the range. The first example + specifies just the dates of the range while the second example + specifies a time range for each date. #+begin_example ,** Meeting in Amsterdam <2004-08-23 Mon>--<2004-08-26 Thu> + ,** This weeks committee meetings + <2004-08-23 Mon 10:00-11:00>--<2004-08-26 Thu 10:00-11:00> #+end_example - Inactive timestamp :: @@ -6003,10 +6231,11 @@ format. All commands listed below produce timestamps in the correct format. #+attr_texinfo: :sep , -- {{{kbd(C-c .)}}} (~org-time-stamp~) :: +- {{{kbd(C-c .)}}} (~org-timestamp~) :: #+kindex: C-c . #+findex: org-time-stamp + #+findex: org-timestamp Prompt for a date and insert a corresponding timestamp. When point is at an existing timestamp in the buffer, the command is used to modify this timestamp instead of inserting a new one. When this @@ -6014,21 +6243,23 @@ format. #+kindex: C-u C-c . #+vindex: org-time-stamp-rounding-minutes + #+vindex: org-timestamp-rounding-minutes When called with a prefix argument, use the alternative format which contains date and time. The default time can be rounded to multiples of 5 minutes. See the option - ~org-time-stamp-rounding-minutes~. + ~org-timestamp-rounding-minutes~. #+kindex: C-u C-u C-c . With two prefix arguments, insert an active timestamp with the current time without prompting. -- {{{kbd(C-c !)}}} (~org-time-stamp-inactive~) :: +- {{{kbd(C-c !)}}} (~org-timestamp-inactive~) :: #+kindex: C-c ! #+kindex: C-u C-c ! #+kindex: C-u C-u C-c ! #+findex: org-time-stamp-inactive + #+findex: org-timestamp-inactive Like {{{kbd(C-c .)}}}, but insert an inactive timestamp that does not cause an agenda entry. @@ -6232,16 +6463,18 @@ turn off the display with ~org-read-date-display-live~.]. #+vindex: org-display-custom-times #+vindex: org-time-stamp-custom-formats +#+vindex: org-timestamp-custom-formats Org mode uses the standard ISO notation for dates and times as it is defined in ISO 8601. If you cannot get used to this and require another representation of date and time to keep you happy, you can get it by customizing the variables ~org-display-custom-times~ and -~org-time-stamp-custom-formats~. +~org-timestamp-custom-formats~. -- {{{kbd(C-c C-x C-t)}}} (~org-toggle-time-stamp-overlays~) :: +- {{{kbd(C-c C-x C-t)}}} (~org-toggle-timestamp-overlays~) :: #+kindex: C-c C-x C-t #+findex: org-toggle-time-stamp-overlays + #+findex: org-toggle-timestamp-overlays Toggle the display of custom formats for dates and times. Org mode needs the default format for scanning, so the custom @@ -6470,6 +6703,9 @@ state to =DONE= would actually switch the date like this: DEADLINE: <2005-11-01 Tue +1m> #+end_example +When task contains multiple timestamps with repeater interval, all +these timestamps are shifted. + To mark a task with a repeater as DONE, use {{{kbd(C-- 1 C-c C-t)}}}, i.e., ~org-todo~ with a numeric prefix argument of =-1=. @@ -6516,16 +6752,16 @@ special repeaters =++= and =.+=. For example: Marking this DONE shifts the date to exactly one hour from now. #+end_example -#+vindex: org-agenda-skip-scheduled-if-deadline-is-shown +#+vindex: org-agenda-skip-scheduled-repeats-after-deadline You may have both scheduling and deadline information for a specific task. If the repeater is set for the scheduling information only, you probably want the repeater to be ignored after the deadline. If so, -set the variable ~org-agenda-skip-scheduled-if-deadline-is-shown~ to -~repeated-after-deadline~. However, any scheduling information -without a repeater is no longer relevant once the task is done, and -thus, removed upon repeating the task. If you want both scheduling -and deadline information to repeat after the same interval, set the -same repeater for both timestamps. +set the variable ~org-agenda-skip-scheduled-repeats-after-deadline~ to +~t~. However, any scheduling information without a repeater is no +longer relevant once the task is done, and thus, removed upon +repeating the task. If you want both scheduling and deadline +information to repeat after the same interval, set the same repeater +for both timestamps. An alternative to using a repeater is to create a number of copies of a task subtree, with dates shifted in each copy. The command @@ -6654,23 +6890,30 @@ about what to do with it. #+kindex: C-S-UP #+findex: org-clock-timestamps-up + #+findex: org-shiftcontrolup #+kindex: C-S-DOWN #+findex: org-clock-timestamps-down + #+findex: org-shiftcontroldown On CLOCK log lines, increase/decrease both timestamps so that the clock duration keeps the same value. - {{{kbd(S-M-UP)}}} (~org-timestamp-up~), {{{kbd(S-M-DOWN)}}} (~org-timestamp-down~) :: #+kindex: S-M-UP - #+findex: org-clock-timestamp-up + #+findex: org-timestamp-up + #+findex: org-shiftmetaup #+kindex: S-M-DOWN - #+findex: org-clock-timestamp-down + #+findex: org-timestamp-down + #+findex: org-shiftmetadown On =CLOCK= log lines, increase/decrease the timestamp at point and the one of the previous, or the next, clock timestamp by the same duration. For example, if you hit {{{kbd(S-M-UP)}}} to increase a clocked-out timestamp by five minutes, then the clocked-in timestamp of the next clock is increased by five minutes. + Only =CLOCK= logs created during current Emacs session are + considered when adjusting next/previous timestamp. + - {{{kbd(C-c C-t)}}} (~org-todo~) :: #+kindex: C-c C-t @@ -6802,16 +7045,16 @@ be selected: absolutely, or relative to the current time and may be any of these formats: - | =2007-12-31= | New year eve 2007 | - | =2007-12= | December 2007 | - | =2007-W50= | ISO-week 50 in 2007 | - | =2007-Q2= | 2nd quarter in 2007 | - | =2007= | the year 2007 | - | =today=, =yesterday=, =today-N= | a relative day | - | =thisweek=, =lastweek=, =thisweek-N= | a relative week | - | =thismonth=, =lastmonth=, =thismonth-N= | a relative month | - | =thisyear=, =lastyear=, =thisyear-N= | a relative year | - | =untilnow=[fn:: When using ~:step~, ~untilnow~ starts from the beginning of 2003, not the beginning of time.] | all clocked time ever | + | =2007-12-31= | New year eve 2007 | + | =2007-12= | December 2007 | + | =2007-W50= | ISO-week 50 in 2007 | + | =2007-Q2= | 2nd quarter in 2007 | + | =2007= | the year 2007 | + | =today=, =yesterday=, =today-N= | a relative day | + | =thisweek=, =lastweek=, =thisweek-N= | a relative week | + | =thismonth=, =lastmonth=, =thismonth-N= | a relative month | + | =thisyear=, =lastyear=, =thisyear-N= | a relative year | + | =untilnow=[fn:28] | all clocked time ever | #+vindex: org-clock-display-default-range When this option is not set, Org falls back to the value in @@ -7017,7 +7260,7 @@ current clock, or applying it to another one. #+vindex: org-clock-x11idle-program-name By customizing the variable ~org-clock-idle-time~ to some integer, such as 10 or 15, Emacs can alert you when you get back to your -computer after being idle for that many minutes[fn:28], and ask what +computer after being idle for that many minutes[fn:29], and ask what you want to do with the idle time. There will be a question waiting for you when you get back, indicating how much idle time has passed constantly updated with the current amount, as well as a set of @@ -7651,10 +7894,10 @@ with prefix commands: Visit the last stored capture item in its buffer. -#+vindex: org-capture-bookmark +#+vindex: org-bookmark-names-plist #+vindex: org-capture-last-stored You can also jump to the bookmark ~org-capture-last-stored~, which is -automatically created unless you set ~org-capture-bookmark~ to ~nil~. +automatically created unless you customize ~org-bookmark-names-plist~. To insert the capture at point in an Org buffer, call ~org-capture~ with a {{{kbd(C-0)}}} prefix argument. @@ -7810,7 +8053,7 @@ Now lets look at the elements of a template definition. Each entry in - =(file+olp+datetree "filename" [ "Level 1 heading" ...])= :: - This target[fn:29] creates a heading in a date tree[fn:30] for + This target[fn:30] creates a heading in a date tree[fn:31] for today's date. If the optional outline path is given, the tree will be built under the node it is pointing to, instead of at top level. Check out the ~:time-prompt~ and ~:tree-type~ properties @@ -7824,6 +8067,10 @@ Now lets look at the elements of a template definition. Each entry in File to the entry that is currently being clocked. + - =(here)= :: + + The position of =point=. + - =(function function-finding-location)= :: Most general way: write your own function which both visits the @@ -8076,6 +8323,12 @@ given here: Prompt the user for a value for property {{{var(PROP)}}}. You may specify a default value with =%^{PROP|default}=. +- =%^{PROMPT}X=, X is one of g,G,t,T,u,U,C,L :: + + Prompt the user as in =%^X=, but use the custom prompt string. You + may specify a default value and completions with + =%^{PROMPT|default|completion1|completion2|completion3...}X=. + - =%^{PROMPT}= :: Prompt the user for a string and replace this sequence with it. You @@ -8109,7 +8362,7 @@ capture templates in a similar way.]: | | =%:date= (message date header field) | | | =%:date-timestamp= (date as active timestamp) | | | =%:date-timestamp-inactive= (date as inactive timestamp) | -| | =%:fromto= (either "to NAME" or "from NAME")[fn:31] | +| | =%:fromto= (either "to NAME" or "from NAME")[fn:32] | | gnus | =%:group=, for messages also all email fields | | w3, w3m | =%:url= | | info | =%:file=, =%:node= | @@ -8724,10 +8977,9 @@ commands: #+kindex: < < @r{(Agenda dispatcher)} If there is an active region, restrict the following agenda command - to the region. Otherwise, restrict it to the current subtree[fn:: - For backward compatibility, you can also press {{{kbd(0)}}} to - restrict to the current region/subtree.]. After pressing {{{kbd(< - <)}}}, you still need to press the character selecting the command. + to the region. Otherwise, restrict it to the current subtree. + After pressing {{{kbd(< <)}}}, you still need to press the character + selecting the command. - {{{kbd(*)}}} :: @@ -8776,7 +9028,7 @@ a paper agenda, showing all the tasks for the current week or day. #+cindex: org-agenda, command Compile an agenda for the current week from a list of Org files. The agenda shows the entries for each day. With a numeric prefix - argument[fn:32]---like {{{kbd(C-u 2 1 M-x org-agenda a)}}}---you may + argument[fn:33]---like {{{kbd(C-u 2 1 M-x org-agenda a)}}}---you may set the number of days to be displayed. #+vindex: org-agenda-span @@ -9040,14 +9292,12 @@ sparse trees with {{{kbd(C-c / m)}}}. #+kindex: M @r{(Agenda dispatcher)} #+findex: org-tags-view - #+vindex: org-tags-match-list-sublevels #+vindex: org-agenda-tags-todo-honor-ignore-options Like {{{kbd(m)}}}, but only select headlines that are also TODO - items and force checking subitems (see the variable - ~org-tags-match-list-sublevels~). To exclude scheduled/deadline - items, see the variable ~org-agenda-tags-todo-honor-ignore-options~. - Matching specific TODO keywords together with a tags match is also - possible, see [[*Tag Searches]]. + items. To exclude scheduled/deadline items, see the variable + ~org-agenda-tags-todo-honor-ignore-options~. Matching specific TODO + keywords together with a tags match is also possible, see [[*Tag + Searches]]. The commands available in the tags list are described in [[*Commands in the Agenda Buffer]]. @@ -9120,16 +9370,18 @@ When matching properties, a number of different operators can be used to test the value of a property. Here is a complex example: #+begin_example -+work-boss+PRIORITY="A"+Coffee="unlimited"+Effort<2 ++work-boss+PRIORITY="A"+Coffee="unlimited"+Effort<*2 +With={Sarah\|Denny}+SCHEDULED>="<2008-10-11>" #+end_example +#+cindex: operator, for property search #+texinfo: @noindent The type of comparison depends on how the comparison value is written: - If the comparison value is a plain number, a numerical comparison is done, and the allowed operators are =<=, ===, =>=, =<==, =>==, and - =<>=. + =<>=. As a synonym for the equality operator ===, there is also + ====; =!== and =/== are synonyms of the inequality operator =<>=. - If the comparison value is enclosed in double-quotes, a string comparison is done, and the same operators are allowed. @@ -9147,6 +9399,13 @@ The type of comparison depends on how the comparison value is written: is performed, with === meaning that the regexp matches the property value, and =<>= meaning that it does not match. +- All operators may be optionally followed by an asterisk =*=, like in + =<*=, =!=*=, etc. Such /starred operators/ work like their regular, + unstarred counterparts except that they match only headlines where + the tested property is actually present. This is most useful for + search terms that logically exclude results, like the inequality + operator. + 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 @@ -9154,6 +9413,28 @@ smaller than 2, a =With= property that is matched by the regular expression =Sarah\|Denny=, and that are scheduled on or after October 11, 2008. +Note that the test on the =EFFORT= property uses operator =<*=, so +that the search result will include only entries that actually have an +=EFFORT= property defined and with numerical value smaller than 2. +With the regular =<= operator, the search would handle entries without +an =EFFORT= property as having a zero effort and would include them in +the result as well. + +You can use all characters valid in property names when matching +properties. However, you have to quote some characters in property +names with backslashes when using them in search strings, namely all +characters different from alphanumerics and underscores[fn:: If you +quote alphanumeric characters or underscores with a backslash, that +backslash is ignored.]. For example, to search for all entries having +a property =boss-prio=, =boss:prio=, or =boss\prio=, respectively, +with value =C=, use search strings + +#+begin_example +boss\-prio="C" +boss\:prio="C" +boss\\prio="C" +#+end_example + You can configure Org mode to use property inheritance during a search, but beware that this can slow down searches considerably. See [[*Property Inheritance]], for details. @@ -9402,16 +9683,16 @@ done depends on the type of view. time-of-day specification. These entries are shown at the beginning of the list, as a /schedule/ for the day. After that, items remain grouped in categories, in the sequence given by ~org-agenda-files~. - Within each category, items are sorted by priority (see - [[*Priorities]]), which is composed of the base priority (2000 for - priority =A=, 1000 for =B=, and 0 for =C=), plus additional - increments for overdue scheduled or deadline items. + Within each category, items are sorted by urgency, which is composed + of the base priority (see [[*Priorities]]; 2000 for priority =A=, 1000 + for =B=, and 0 for =C=), plus additional increments for overdue + scheduled or deadline items. - For the TODO list, items remain in the order of categories, but - within each category, sorting takes place according to priority (see - [[*Priorities]]). The priority used for sorting derives from the - priority cookie, with additions depending on how close an item is to - its due or scheduled date. + within each category, sorting takes place according to urgency. The + urgency used for sorting derives from the priority cookie, with + additions depending on how close an item is to its due or scheduled + date. - For tags matches, items are not sorted at all, but just appear in the sequence in which they are found in the agenda files. @@ -9431,11 +9712,11 @@ the estimated effort of an entry (see [[*Effort Estimates]]). #+vindex: org-agenda-effort-filter-preset #+vindex: org-agenda-regexp-filter-preset Agenda built-in or custom commands are statically defined. Agenda -filters and limits allow to flexibly narrow down the list of agenda +filters and limits allow flexibly narrowing down the list of agenda entries. /Filters/ only change the visibility of items, are very fast and are -mostly used interactively[fn:33]. You can switch quickly between +mostly used interactively[fn:34]. You can switch quickly between different filters without having to recreate the agenda. /Limits/ on the other hand take effect before the agenda buffer is populated, so they are mostly useful when defined as local variables within custom @@ -9877,9 +10158,13 @@ the other commands, point needs to be in the desired line. #+kindex: v a #+findex: org-agenda-archives-mode + #+vindex: org-agenda-start-with-archives-mode Toggle Archives mode. In Archives mode, trees that are archived (see [[*Internal archiving]]) are also scanned when producing the - agenda. To exit archives mode, press {{{kbd(v a)}}} again. + agenda. To exit archives mode, press {{{kbd(v a)}}} again. The + initial setting for this mode in new agenda buffers can set with the + variable ~org-agenda-start-with-archives-mode~, which can be set + with the same values as ~org-agenda-archives-mode~. - {{{kbd(v A)}}} :: @@ -10517,7 +10802,7 @@ used for the matching. The example above will therefore define: - {{{kbd(x)}}} :: - as a global search for agenda entries planned[fn:34] this week/day. + as a global search for agenda entries planned[fn:35] this week/day. - {{{kbd(y)}}} :: @@ -10703,7 +10988,7 @@ export custom agenda views as plain text, HTML[fn:: For HTML you need to install Hrvoje NikÅ¡ić's =htmlize.el= as an Emacs package from [[https://elpa.nongnu.org/][NonGNU ELPA]] or from [[https://github.com/hniksic/emacs-htmlize][Hrvoje NikÅ¡ić's repository]].], -Postscript, PDF[fn:35], and iCalendar files. If you +Postscript, PDF[fn:36], and iCalendar files. If you want to do this only occasionally, use the following command: - {{{kbd(C-x C-w)}}} (~org-agenda-write~) :: @@ -10981,12 +11266,28 @@ but not any simpler You can make words =*bold*=, =/italic/=, =_underlined_=, ==verbatim== and =~code~=, and, if you must, =+strike-through+=. Text in the code and verbatim string is not processed for Org specific syntax; it is -exported verbatim. +exported verbatim. Org provides a single command as entry point for +inserting the marker character. + +- {{{kbd(C-c C-x C-f)}}} (~org-emphasize~) :: + + #+kindex: C-c C-x C-f + #+findex: org-emphasize + Prompt for a marker character and insert or change an emphasis. If + there is an active region, change that region to a new emphasis. If + there is no region, just insert the marker characters and position + the cursor between them. #+vindex: org-fontify-emphasized-text To turn off fontification for marked up text, you can set ~org-fontify-emphasized-text~ to ~nil~. To narrow down the list of -available markup syntax, you can customize ~org-emphasis-alist~. +the fontified markup syntax, you can customize +~org-emphasis-alist~[fn:: The markup will still be recognized. Just +not highlighted visually in Emacs.]. + +#+vindex: org-hide-emphasis-markers +To hide the emphasis markup characters in your buffers, set +~org-hide-emphasis-markers~ to ~t~. Sometimes, when marked text also contains the marker character itself, the result may be unsettling. For example, @@ -11018,15 +11319,20 @@ the radius of Alpha Centauri is R_{Alpha Centauri} = 1.28 x R_{sun}. #+end_example #+vindex: org-use-sub-superscripts +#+vindex: org-export-with-sub-superscripts If you write a text where the underscore is often used in a different context, Org's convention to always interpret these as subscripts can -get in your way. Configure the variable ~org-use-sub-superscripts~ to -change this convention. For example, when setting this variable to -~{}~, =a_b= is not interpreted as a subscript, but =a_{b}= is. - -You can set ~org-use-sub-superscripts~ in a file using the export -option =^:= (see [[*Export Settings][Export Settings]]). For example, =#+OPTIONS: ^:{}= -sets ~org-use-sub-superscripts~ to ~{}~ and limits super- and +get in your way. Configure the variable ~org-use-sub-superscripts~ +and/or ~org-export-with-sub-superscripts~ to change this convention. +For example, when setting these variables to ~{}~, =a_b= is not +displayed/exported[fn::The underlying markup still remains a +sub/superscript. Only the visual display and export behavior +changes.] as a subscript, but =a_{b}= is. + +You can set both ~org-use-sub-superscripts~ +~org-export-with-sub-superscripts~ in a file using the export option +=^:= (see [[*Export Settings][Export Settings]]). For example, +=#+OPTIONS: ^:{}= sets the two options to ~{}~ and limits super- and subscripts to the curly bracket notation. You can also toggle the visual display of super- and subscripts: @@ -11073,7 +11379,7 @@ possible to provide your own special symbols in the variable ~org-entities-user~. During export, these symbols are transformed into the native format of -the exporter back-end. Strings like =\alpha= are exported as =α= in +the exporter backend. Strings like =\alpha= are exported as =α= in the HTML output, and as =\(\alpha\)= in the LaTeX output. Similarly, =\nbsp= becomes = = in HTML and =~= in LaTeX. @@ -11109,11 +11415,11 @@ converted into dashes, and =...= becomes a compact set of dots. Plain ASCII is normally sufficient for almost all note taking. Exceptions include scientific notes, which often require mathematical -symbols and the occasional formula. LaTeX[fn:36] is widely used to +symbols and the occasional formula. LaTeX[fn:37] is widely used to typeset scientific documents. Org mode supports embedding LaTeX code into its files, because many academics are used to writing and reading LaTeX source code, and because it can be readily processed to produce -pretty output for a number of export back-ends. +pretty output for a number of export backends. *** LaTeX fragments :PROPERTIES: @@ -11123,7 +11429,7 @@ pretty output for a number of export back-ends. #+vindex: org-format-latex-header Org mode can contain LaTeX math fragments, and it supports ways to -process these for several export back-ends. When exporting to LaTeX, +process these for several export backends. When exporting to LaTeX, the code is left as it is. When exporting to HTML, Org can use either [[https://www.mathjax.org][MathJax]] (see [[*Math formatting in HTML export]]) or transcode the math into images (see [[*Previewing LaTeX fragments]]). @@ -11131,26 +11437,31 @@ into images (see [[*Previewing LaTeX fragments]]). LaTeX fragments do not need any special marking at all. The following snippets are identified as LaTeX source code: -- Environments of any kind[fn:37]. The only requirement is that the +- Environments of any kind[fn:38]. The only requirement is that the =\begin= statement appears on a new line, preceded by only whitespace. -- Text within the usual LaTeX math delimiters. To avoid conflicts - with currency specifications, single =$= characters are only - recognized as math delimiters if the enclosed text contains at most - two line breaks, is directly attached to the =$= characters with no - whitespace in between, and if the closing =$= is followed by - whitespace, punctuation or a dash. For the other delimiters, there - is no such restriction, so when in doubt, use =\(...\)= as inline - math delimiters. +- Text within the usual LaTeX math delimiters. Prefer =\(...\)= for + inline fragments. The =$...$= alternative has some restrictions and + may be a source of confusion. To avoid conflicts with currency + specifications, single =$= characters are only recognized as math + delimiters if the enclosed text contains at most two line breaks, is + directly attached to the =$= characters with no whitespace in + between, and if the closing =$= is followed by whitespace or + punctuation (but not a dash). + + Sometimes, it may necessary to have a literal dollar symbol even + when it is recognized as LaTeX math delimiter. Org provides =\dollar= and + =\USD= entities (see [[*Special Symbols]]) that are rendered as =$= for + such scenarios. Also, see [[*Escape Character]]. #+texinfo: @noindent For example: #+begin_example \begin{equation} % arbitrary environments, -x=\sqrt{b} % even tables, figures -\end{equation} % etc +x=\sqrt{b} % even tables, figures, etc +\end{equation} If $a^2=b$ and \( b=2 \), then the solution must be either $$ a=+\sqrt{2} $$ or \[ a=-\sqrt{2} \]. @@ -11159,7 +11470,7 @@ either $$ a=+\sqrt{2} $$ or \[ a=-\sqrt{2} \]. #+vindex: org-export-with-latex LaTeX processing can be configured with the variable ~org-export-with-latex~. The default setting is ~t~ which means -MathJax for HTML, and no processing for ASCII and LaTeX back-ends. +MathJax for HTML, and no processing for ASCII and LaTeX backends. You can also set this variable on a per-file basis using one of these lines: @@ -11175,7 +11486,7 @@ lines: #+vindex: org-preview-latex-default-process If you have a working LaTeX installation and =dvipng=, =dvisvgm= or -=convert= installed[fn:38], LaTeX fragments can be processed to +=convert= installed[fn:39], LaTeX fragments can be processed to produce images of the typeset expressions to be used for inclusion while exporting to HTML (see [[*LaTeX fragments]]), or for inline previewing within Org mode. @@ -11331,9 +11642,9 @@ Here is an example #+vindex: org-latex-src-block-backend If the example is source code from a programming language, or any other text that can be marked up by Font Lock in Emacs, you can ask -for the example to look like the fontified Emacs buffer[fn:39]. This +for the example to look like the fontified Emacs buffer[fn:40]. This is done with the code block, where you also need to specify the name -of the major mode that should be used to fontify the example[fn:40], +of the major mode that should be used to fontify the example[fn:41], see [[*Structure Templates]] for shortcuts to easily insert code blocks. #+cindex: @samp{BEGIN_SRC} @@ -11343,17 +11654,19 @@ see [[*Structure Templates]] for shortcuts to easily insert code blocks. (defun org-xor (a b) "Exclusive or." (if a (not b) b)) - ,#+END_SRC +,#+END_SRC #+end_example Both in =example= and in =src= snippets, you can add a =-n= switch to -the end of the =#+BEGIN= line, to get the lines of the example -numbered. The =-n= takes an optional numeric argument specifying the -starting line number of the block. If you use a =+n= switch, the -numbering from the previous numbered snippet is continued in the -current one. The =+n= switch can also take a numeric argument. This -adds the value of the argument to the last line of the previous block -to determine the starting line number. +the =#+BEGIN= line[fn::In the =src= snippets, switches must be placed +right after the language name and before the [[*Structure of Code +Blocks][header arguments]]], to get the lines of the example numbered. +The =-n= takes an optional numeric argument specifying the starting +line number of the block. If you use a =+n= switch, the numbering +from the previous numbered snippet is continued in the current one. +The =+n= switch can also take a numeric argument. This adds the value +of the argument to the last line of the previous block to determine +the starting line number. #+begin_example ,#+BEGIN_SRC emacs-lisp -n 20 @@ -11369,9 +11682,12 @@ to determine the starting line number. In literal examples, Org interprets strings like =(ref:name)= as labels, and use them as targets for special hyperlinks like -=[[(name)]]=---i.e., the reference name enclosed in single parenthesis. -In HTML, hovering the mouse over such a link remote-highlights the -corresponding code line, which is kind of cool. +=[[(name)]]=---i.e., the reference name enclosed in single +parentheses. In HTML, hovering the mouse over such a link +remote-highlights the corresponding code line[fn:: This requires some +Javascript which is /not/ automatically included in the HTML output: +you have to customize the variable =org-html-head-include-scripts= to +~t~ to have it included (it is ~nil~ by default).], which is kind of cool. You can also add a =-r= switch which /removes/ the labels from the source code[fn:: Adding =-k= to =-n -r= /keeps/ the labels in the @@ -11450,7 +11766,7 @@ example : ./img/cat.jpg If you wish to define a caption for the image (see [[*Captions]]) and -maybe a label for internal cross references (see [[*Internal Links]]), +maybe a label for internal cross-references (see [[*Internal Links]]), make sure that the link is on a line by itself and precede it with =CAPTION= and =NAME= keywords as follows: @@ -11478,14 +11794,19 @@ command: #+vindex: org-image-actual-width + #+vindex: org-image-max-width #+cindex: @samp{ORG-IMAGE-ACTUAL-WIDTH}, property By default, Org mode displays inline images according to their - actual width. You can customize the displayed image width using + actual width, but no wider than ~fill-column~ characters. + + You can customize the displayed image width using ~org-image-actual-width~ variable (globally) or =ORG-IMAGE-ACTUAL-WIDTH= property (subtree-level)[fn:: The width can be customized in Emacs >= 24.1, built with imagemagick support.]. Their value can be the following: - - (default) Non-nil, use the actual width of images when inlining them. + - (default) Non-~nil~, use the actual width of images when inlining + them. If the actual width is too wide, limit it according to + ~org-image-max-width~. - When set to a number, use imagemagick (when available) to set the image's width to this value. - When set to a number in a list, try to get the width from any @@ -11494,9 +11815,51 @@ command: ,#+ATTR_HTML: :width 300px #+end_example and fall back on that number if none is found. - - When set to nil, try to get the width from an =#+ATTR.*= keyword - and fall back on the original width if none is found. + - When set to ~nil~, try to get the width from an =#+ATTR.*= keyword + and fall back on the original width or ~org-image-max-width~ if + none is found. + + ~org-image-max-width~ limits the maximum displayed image width, but + only when the image width is not set explicitly. Possible maximum + width can be set to: + - (default) ~fill-column~, limit width to ~fill-column~ number of + characters. + - ~window~, limit width to current window width. + - integer number, limit width to that specified number of pixels. + - ~nil~, do not limit the width. + + #+vindex: org-image-align + Org mode can left-align, center or right-align the display of inline + images. This setting is controlled (globally) by ~org-image-align~. + Only standalone images are affected, corresponding to links with no + surrounding text in their paragraph except for whitespace. Its + value can be the following: + - (default) The symbol ~left~, which inserts the image where the + link appears in the buffer. + - The symbol ~center~, which will preview links centered in the + Emacs window. + - The symbol ~right~, which will preview links right-aligned in the + Emacs window. + + Inline image alignment can be specified for each link using the + =#+ATTR.*= keyword if it matches an alignment specification like: + #+begin_example + ,#+ATTR_HTML: :align center + #+end_example + Org will use the alignment specification from any =#+ATTR.*= + keyword, such as =#+ATTR_HTML= or =#+ATTR_LATEX=, but =#+ATTR_ORG= + (if present) will override the others. For instance, this link + #+begin_example + ,#+ATTR_HTML: :align right + ,#+ATTR_ORG: :align center + [[/path/to/image/file.png]] + #+end_example + will be displayed centered in Emacs but exported right-aligned to + HTML. + When =#+ATTR_ORG= is not set, inline image alignment is also read + from the =:center= attribute supported by some export backends (like + HTML, LaTeX and Beamer.) #+vindex: org-cycle-inline-images-display Inline images can also be displayed when cycling the folding state. @@ -11526,7 +11889,7 @@ Optionally, the caption can take the form: Even though images and tables are prominent examples of captioned structures, the same caption mechanism can apply to many others---e.g., LaTeX equations, source code blocks. Depending on the -export back-end, those may or may not be handled. +export backend, those may or may not be handled. ** Horizontal Rules :PROPERTIES: @@ -11552,7 +11915,7 @@ text. Markers always start with =fn:=. For example: #+begin_example The Org website[fn:1] now looks a lot better than it used to. ... -[fn:55] The link is: https://orgmode.org +[fn:50] The link is: https://orgmode.org #+end_example Org mode extends the number-based syntax to /named/ footnotes and @@ -11643,10 +12006,11 @@ export documents to a variety of other formats while retaining as much structure (see [[*Document Structure]]) and markup (see [[*Markup for Rich Contents]]) as possible. +#+cindex: export backend #+cindex: export back-end The libraries responsible for translating Org files to other formats -are called /back-ends/. Org ships with support for the following -back-ends: +are called /backends/. Org ships with support for the following +backends: - /ascii/ (ASCII format) - /beamer/ (LaTeX Beamer format) @@ -11662,15 +12026,15 @@ back-ends: 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 +example, ~ox-koma-letter~ for /koma-letter/ backend. More libraries 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, -HTML, iCalendar, LaTeX, and ODT. Additional back-ends can be loaded +Org only loads backends for the following formats by default: ASCII, +HTML, iCalendar, LaTeX, and ODT. Additional backends can be loaded in either of two ways: by configuring the ~org-export-backends~ variable, or by requiring libraries in the Emacs init file. For -example, to load the Markdown back-end, add this to your Emacs config: +example, to load the Markdown backend, add this to your Emacs config: #+begin_src emacs-lisp (require 'ox-md) @@ -11732,9 +12096,27 @@ further alter what is exported, and how. #+kindex: C-c C-e C-b Toggle body-only export. Useful for excluding headers and footers - in the export. Affects only those back-end formats that have + in the export. Affects only those backend formats that have sections like =...= in HTML. + #+vindex: org-export-body-only + To make body-only export the default, customize the variable + ~org-export-body-only~. + +- {{{kbd(C-f)}}} :: + #+kindex: C-c C-e C-f + + Toggle force-publishing export. Publish functions normally only + publish changed files (see [[**Triggering Publication]]). Forced + publishing causes files to be published even if their timestamps do + not indicate the file has been changed. + + #+vindex: org-export-force-publishing + To make forced publishing the default, customize the variable + ~org-export-force-publishing~. (This is similar to + ~org-publish-use-timestamps-flag~, but only affects the export + dispatcher.) + - {{{kbd(C-s)}}} :: #+kindex: C-c C-e C-s @@ -11756,6 +12138,10 @@ further alter what is exported, and how. certain parts of an Org document by adjusting the visibility of particular headings. See also [[*Sparse Trees]]. + #+vindex: org-export-visible-only + To make visible-only export the default, customize the variable + ~org-export-visible-only~. + ** Export Settings :PROPERTIES: :DESCRIPTION: Common export settings. @@ -11774,14 +12160,14 @@ set at a specific level override options set at a more general level. #+cindex: @samp{SETUPFILE}, keyword In-buffer settings may appear anywhere in the file, either directly or indirectly through a file included using =#+SETUPFILE: filename or -URL= syntax. Option keyword sets tailored to a particular back-end +URL= syntax. Option keyword sets tailored to a particular backend can be inserted from the export dispatcher (see [[*The Export Dispatcher]]) using the =Insert template= command by pressing {{{kbd(#)}}}. To insert keywords individually, a good way to make sure the keyword is correct is to type =#+= and then to use {{{kbd(M-TAB)}}}[fn:6] for completion. -The export keywords available for every back-end, and their equivalent +The export keywords available for every backend, and their equivalent global variables, include: - =AUTHOR= :: @@ -11801,7 +12187,7 @@ global variables, include: #+cindex: @samp{DATE}, keyword #+vindex: org-export-date-timestamp-format - A date or a time-stamp[fn:: The variable + A date or a timestamp[fn:: The variable ~org-export-date-timestamp-format~ defines how this timestamp are exported.]. @@ -11818,28 +12204,44 @@ global variables, include: Language to use for translating certain strings (~org-export-default-language~). With =#+LANGUAGE: fr=, for example, Org translates =Table of contents= to the French =Table des - matières=[fn:41]. + matières=[fn:42]. - =SELECT_TAGS= :: #+cindex: @samp{SELECT_TAGS}, keyword #+vindex: org-export-select-tags - The default value is =("export")=. When a tree is tagged with - =export= (~org-export-select-tags~), Org selects that tree and its - subtrees for export. Org excludes trees with =noexport= tags, see - below. When selectively exporting files with =export= tags set, Org - does not export any text that appears before the first headline. + List of tags that will, if present, be selected for export. The + default value is ~org-export-select-tags~ =("export")=. When a tree + is tagged with =export=, Org selects that tree and its subtrees for + export, ignoring all the other sections that do not possess the + =export= tag. + + When selectively exporting files with =export= tags set, Org does + not export any text that appears before the first headline. + + Note that a file without the =export= tags will export all its + sections. + + To select non-default tags for export, customize + ~org-export-select-tags~ (globally) or add =#+SELECT_TAGS: tag1 + tag2= to the document. - =EXCLUDE_TAGS= :: #+cindex: @samp{EXCLUDE_TAGS}, keyword #+vindex: org-export-exclude-tags - The default value is =("noexport")=. When a tree is tagged with - =noexport= (~org-export-exclude-tags~), Org excludes that tree and - its subtrees from export. Entries tagged with =noexport= are - unconditionally excluded from the export, even if they have an - =export= tag. Even if a subtree is not exported, Org executes any - code blocks contained there. + List of tags that will be excluded from export. The default value is + ~org-export-exclude-tags~ =("noexport")=. When a tree is tagged + with =noexport=, Org excludes that tree and its subtrees from + export. + + Entries tagged with =noexport= are unconditionally excluded from the + export, even if they have an =export= tag. Even if a subtree is not + exported, Org executes any code blocks contained there. + + To select non-default tags for the exclusion, customize + ~org-export-exclude-tags~ (globally) or add =#+EXCLUDE_TAGS: tag1 + tag2= to the document. - =TITLE= :: @@ -11853,7 +12255,7 @@ global variables, include: #+cindex: @samp{EXPORT_FILE_NAME}, keyword The name of the output file to be generated. Otherwise, Org generates the file name based on the buffer name and the extension - based on the back-end format. + based on the backend format. The =OPTIONS= keyword is a compact form. To configure multiple options, use several =OPTIONS= lines. =OPTIONS= recognizes the @@ -11915,6 +12317,12 @@ following arguments. Toggle inclusion of author name into exported file (~org-export-with-author~). +- ~expand-links~ :: + + #+vindex: org-export-expand-links + Toggle expansion of environment variables in file paths + (~org-export-expand-links~). + - ~broken-links~ :: #+vindex: org-export-with-broken-links @@ -11966,7 +12374,7 @@ following arguments. #+vindex: org-export-headline-levels Set the number of headline levels for export (~org-export-headline-levels~). Below that level, headlines are - treated differently. In most back-ends, they become list items. + treated differently. In most backends, they become list items. - ~inline~ :: @@ -12032,8 +12440,9 @@ following arguments. - ~timestamp~ :: #+vindex: org-export-time-stamp-file + #+vindex: org-export-timestamp-file Toggle inclusion of the creation time in the exported file - (~org-export-time-stamp-file~). + (~org-export-timestamp-file~). - ~title~ :: @@ -12095,7 +12504,7 @@ keyword: #+cindex: excluding entries from table of contents #+cindex: table of contents, exclude entries Org includes both numbered and unnumbered headlines in the table of -contents[fn:42]. If you need to exclude an unnumbered headline, +contents[fn:43]. If you need to exclude an unnumbered headline, along with all its children, set the =UNNUMBERED= property to =notoc= value. @@ -12107,11 +12516,11 @@ value. #+end_example #+cindex: @samp{TOC}, keyword -Org normally inserts the table of contents directly before the first -headline of the file. To move the table of contents to a different -location, first turn off the default with ~org-export-with-toc~ -variable or with =#+OPTIONS: toc:nil=. Then insert =#+TOC: headlines -N= at the desired location(s). +Org normally inserts the table of contents in front of the exported +document. To move the table of contents to a different location, +first turn off the default with ~org-export-with-toc~ variable or with +=#+OPTIONS: toc:nil=. Then insert =#+TOC: headlines N= at the desired +location(s). #+begin_example ,#+OPTIONS: toc:nil @@ -12171,22 +12580,21 @@ the table of contents. #+cindex: export, include files #+cindex: @samp{INCLUDE}, keyword -During export, you can include the content of another file. For +[[*Summary of the export process][During export]], you can include the content of another file. For example, to include your =.emacs= file, you could use: : #+INCLUDE: "~/.emacs" src emacs-lisp #+texinfo: @noindent -The first parameter is the file name to include. The optional second -parameter specifies the block type: =example=, =export= or =src=. The -optional third parameter specifies the source code language to use for -formatting the contents. This is relevant to both =export= and =src= -block types. - -If an included file is specified as having a markup language, Org -neither checks for valid syntax nor changes the contents in any way. -For example and source blocks, Org code-escapes the contents before -inclusion. +There are three positional arguments after the include keyword, they are: +1. The file name, this is the sole mandatory argument. Org neither + checks for correctness or validates the content in any way. +2. The block name to wrap the file content in. When this is + =example=, =export=, or =src= the content is escaped by + ~org-escape-code-in-string~. Arbitrary block names may be given, + however block names starting with =:= must be quoted, i.e. =":name"=. +3. The source code language to use for formatting the contents. This is relevant + to both =export= and =src= block types. #+cindex: @samp{minlevel}, include If an included file is not specified as having any markup language, @@ -12214,11 +12622,11 @@ be omitted to use the obvious defaults. | =#+INCLUDE: "~/.emacs" :lines "10-"= | Include lines from 10 to EOF | Inclusions may specify a file-link to extract an object matched by -~org-link-search~[fn:43] (see [[*Search Options in File Links]]). The +~org-link-search~[fn:44] (see [[*Search Options in File Links]]). The ranges for =:lines= keyword are relative to the requested element. Therefore, -: #+INCLUDE: "./paper.org::*conclusion" :lines 1-20 +: #+INCLUDE: "./paper.org::*conclusion" :lines "1-20" #+texinfo: @noindent includes the first 20 lines of the headline named =conclusion=. @@ -12254,7 +12662,7 @@ following syntax: : #+MACRO: name replacement text; $1, $2 are arguments #+texinfo: @noindent -which can be referenced using ={{{name(arg1, arg2)}}}=[fn:44]. For +which can be referenced using ={{{name(arg1, arg2)}}}=[fn:45]. For example #+begin_example @@ -12280,7 +12688,7 @@ turns ={{{gnustamp(linux)}}}= into =GNU/Linux= during export. Org recognizes macro references in following Org markup areas: paragraphs, headlines, verse blocks, tables cells and lists. Org also recognizes macro references in keywords, such as =CAPTION=, =TITLE=, -=AUTHOR=, =DATE=, and for some back-end specific export options. +=AUTHOR=, =DATE=, and for some backend specific export options. Org comes with following pre-defined macros: @@ -12437,7 +12845,7 @@ See the variable ~org-ascii-links-to-notes~ for details. :UNNUMBERED: notoc :END: -The ASCII export back-end has one extra keyword for customizing ASCII +The ASCII export backend has one extra keyword for customizing ASCII output. Setting this keyword works similar to the general options (see [[*Export Settings]]). @@ -12462,7 +12870,7 @@ cut-off point where levels become lists, see [[*Export Settings]]. :UNNUMBERED: notoc :END: -To insert text within the Org file by the ASCII back-end, use one the +To insert text within the Org file by the ASCII backend, use one the following constructs, inline, keyword, or export block: #+cindex: @samp{ASCII}, keyword @@ -12473,7 +12881,7 @@ Inline text @@ascii:and additional text@@ within a paragraph. ,#+ASCII: Some text ,#+BEGIN_EXPORT ascii -Org exports text in this block only when using ASCII back-end. +Org exports text in this block only when using ASCII backend. ,#+END_EXPORT #+end_example @@ -12484,7 +12892,7 @@ Org exports text in this block only when using ASCII back-end. #+cindex: @samp{ATTR_ASCII}, keyword #+cindex: horizontal rules, in ASCII export -ASCII back-end recognizes only one attribute, =:width=, which +ASCII backend recognizes only one attribute, =:width=, which specifies the width of a horizontal rule in number of characters. The keyword and syntax for specifying widths is: @@ -12501,7 +12909,7 @@ keyword and syntax for specifying widths is: #+cindex: @samp{BEGIN_JUSTIFYLEFT} #+cindex: @samp{BEGIN_JUSTIFYRIGHT} -Besides =#+BEGIN_CENTER= blocks (see [[*Paragraphs]]), ASCII back-end has +Besides =#+BEGIN_CENTER= blocks (see [[*Paragraphs]]), ASCII backend has these two left and right justification blocks: #+begin_example @@ -12560,7 +12968,7 @@ popular display formats. :DESCRIPTION: For customizing Beamer export. :END: -Beamer export back-end has several additional keywords for customizing +Beamer export backend has several additional keywords for customizing Beamer output. These keywords work similar to the general options settings (see [[*Export Settings]]). @@ -12646,7 +13054,7 @@ should in principle be exportable as a Beamer presentation. - Org exports a Beamer frame's objects as block environments. Org can enforce wrapping in special block types when =BEAMER_ENV= property - is set[fn:45]. For valid values see + is set[fn:46]. For valid values see ~org-beamer-environments-default~. To add more values, see ~org-beamer-environments-extra~. #+vindex: org-beamer-environments-default @@ -12673,7 +13081,7 @@ should in principle be exportable as a Beamer presentation. headline as an overlay or action specification. When enclosed in square brackets, Org export makes the overlay specification a default. Use =BEAMER_OPT= to set any options applicable to the - current Beamer frame or block. The Beamer export back-end wraps + current Beamer frame or block. The Beamer export backend wraps with appropriate angular or square brackets. It also adds the =fragile= option for any code that may require a verbatim block. @@ -12695,8 +13103,8 @@ should in principle be exportable as a Beamer presentation. :DESCRIPTION: For using in Org documents. :END: -Since Org's Beamer export back-end is an extension of the LaTeX -back-end, it recognizes other LaTeX specific syntax---for example, +Since Org's Beamer export backend is an extension of the LaTeX +backend, it recognizes other LaTeX specific syntax---for example, =#+LATEX:= or =#+ATTR_LATEX:=. See [[*LaTeX Export]], for details. Beamer export wraps the table of contents generated with =toc:t= @@ -12714,7 +13122,7 @@ Insert Beamer-specific code using the following constructs: ,#+BEAMER: \pause ,#+BEGIN_EXPORT beamer - Only Beamer export back-end exports this. + Only Beamer export backend exports this. ,#+END_EXPORT Text @@beamer:some code@@ within a paragraph. @@ -12965,7 +13373,7 @@ introduced with the HTML5 standard. To enable them, set ~org-html-html5-fancy~ to non-~nil~. Or use an =OPTIONS= line in the file to set =html5-fancy=. -HTML5 documents can now have arbitrary =#+BEGIN= ... =#+END= blocks. +HTML5 documents can have arbitrary =#+BEGIN= ... =#+END= blocks. For example: #+begin_example @@ -13046,13 +13454,39 @@ a postamble from looking up author's name, email address, creator's name, and date. +*** Exporting to minimal HTML +:PROPERTIES: +:DESCRIPTION: Exporting HTML without CSS, Javascript, etc. +:ALT_TITLE: Bare HTML +:END: + +If you want to output a minimal HTML file, with no CSS, no Javascript, +no preamble or postamble, here are the variable you would need to set: + +#+vindex: org-html-head +#+vindex: org-html-head-extra +#+vindex: org-html-head-include-default-style +#+vindex: org-html-head-include-scripts +#+vindex: org-html-preamble +#+vindex: org-html-postamble +#+vindex: org-html-use-infojs +#+begin_src emacs-lisp +(setq org-html-head "" + org-html-head-extra "" + org-html-head-include-default-style nil + org-html-head-include-scripts nil + org-html-preamble nil + org-html-postamble nil + org-html-use-infojs nil) +#+end_src + *** Quoting HTML tags :PROPERTIES: :DESCRIPTION: Using direct HTML in Org files. :END: -The HTML export back-end transforms =<= and =>= to =<= and =>=. -To include raw HTML code in the Org file so the HTML export back-end +The HTML export backend transforms =<= and =>= to =<= and =>=. +To include raw HTML code in the Org file so the HTML export backend can insert that HTML code in the output, use this inline syntax: =@@html:...@@=. For example: @@ -13093,25 +13527,25 @@ a =href= attribute making the headlines link to themselves. #+cindex: internal links, in HTML export #+cindex: external links, in HTML export -The HTML export back-end transforms Org's internal links (see -[[*Internal Links]]) to equivalent HTML links in the output. The back-end +The HTML export backend transforms Org's internal links (see +[[*Internal Links]]) to equivalent HTML links in the output. The backend similarly handles Org's automatic links created by radio targets (see [[*Radio Targets]]) similarly. For Org links to external files, the -back-end transforms the links to /relative/ paths. +backend transforms the links to /relative/ paths. #+vindex: org-html-link-org-files-as-html -For Org links to other =.org= files, the back-end automatically +For Org links to other =.org= files, the backend automatically changes the file extension to =.html= and makes file paths relative. If the =.org= files have an equivalent =.html= version at the same location, then the converted links should work without any further manual intervention. However, to disable this automatic path translation, set ~org-html-link-org-files-as-html~ to ~nil~. When -disabled, the HTML export back-end substitutes the ID-based links in +disabled, the HTML export backend substitutes the ID-based links in the HTML output. For more about linking files when publishing to a directory, see [[*Publishing links]]. Org files can also have special directives to the HTML export -back-end. For example, by using =#+ATTR_HTML= lines to specify new +backend. For example, by using =#+ATTR_HTML= lines to specify new format attributes to ~~ or ~~ tags. This example shows changing the link's title and style: @@ -13128,7 +13562,7 @@ changing the link's title and style: #+cindex: tables, in HTML #+vindex: org-export-html-table-tag -The HTML export back-end uses ~org-html-table-default-attributes~ when +The HTML export backend uses ~org-html-table-default-attributes~ when exporting Org tables to HTML. By default, the exporter does not draw frames and cell borders. To change for this for a table, use the following lines before the table in the Org file: @@ -13140,7 +13574,7 @@ following lines before the table in the Org file: ,#+ATTR_HTML: :border 2 :rules all :frame border #+end_example -The HTML export back-end preserves column groupings in Org tables (see +The HTML export backend preserves column groupings in Org tables (see [[*Column Groups]]) when exporting to HTML. Additional options for customizing tables for HTML export. @@ -13188,20 +13622,20 @@ Additional options for customizing tables for HTML export. #+cindex: images, inline in HTML #+cindex: inlining images in HTML -The HTML export back-end has features to convert Org image links to +The HTML export backend has features to convert Org image links to HTML inline images and HTML clickable image links. #+vindex: org-html-inline-images When the link in the Org file has no description, the HTML export -back-end by default in-lines that image. For example: +backend by default in-lines that image. For example: =[[file:myimg.jpg]]= is in-lined, while =[[file:myimg.jpg][the image]]= links to the text, =the image=. For more details, see the variable ~org-html-inline-images~. On the other hand, if the description part of the Org link is itself another link, such as =file:= or =http:= URL pointing to an image, the -HTML export back-end in-lines this image and links to the main image. -This Org syntax enables the back-end to link low-resolution thumbnail +HTML export backend in-lines this image and links to the main image. +This Org syntax enables the backend to link low-resolution thumbnail to the high-resolution version of the image, as shown in this example: : [[file:highres.jpg][file:thumb.jpg]] @@ -13219,7 +13653,7 @@ accessibility standards. [[./img/a.jpg]] #+end_example -The HTML export back-end copies the =http= links from the Org file +The HTML export backend copies the =http= links from the Org file as-is. *** Math formatting in HTML export @@ -13238,7 +13672,7 @@ different ways on HTML pages. The default is to use the with Org[fn:: By default, Org loads MathJax from [[https://www.jsdelivr.com/][jsDelivr]], as recommended in [[https://docs.mathjax.org/en/latest/web/start.html][Getting Started -with MathJax Components]].][fn:46]. Some MathJax display options can +with MathJax Components]].][fn:47]. Some MathJax display options can be configured via ~org-html-mathjax-options~, or in the buffer. For example, with the following settings, @@ -13282,12 +13716,12 @@ HTML was by using =:textarea=. The advantage of this approach was that copying and pasting was built into browsers with simple JavaScript commands. Even editing before pasting was made simple. -The HTML export back-end can create such text areas. It requires an +The HTML export backend can create such text areas. It requires an =#+ATTR_HTML= line as shown in the example below with the =:textarea= option. This must be followed by either an example or a source code block. Other Org block types do not honor the =:textarea= option. -By default, the HTML export back-end creates a text area 80 characters +By default, the HTML export backend creates a text area 80 characters wide and height just enough to fit the content. Override these defaults with =:width= and =:height= options on the =#+ATTR_HTML= line. @@ -13354,7 +13788,7 @@ classes like for headlines, tables, etc. #+vindex: org-html-head #+vindex: org-html-head-extra #+cindex: @samp{HTML_INCLUDE_STYLE}, keyword -The HTML export back-end includes a compact default style in each +The HTML export backend includes a compact default style in each exported HTML file. To override the default style with another style, use these keywords in the Org file. They will replace the global defaults the HTML exporter uses. @@ -13483,7 +13917,7 @@ to your pages, configure the variable ~org-export-html-use-infojs~. #+cindex: @LaTeX{} export #+cindex: PDF export -The LaTeX export back-end can handle complex documents, incorporate +The LaTeX export backend can handle complex documents, incorporate standard or custom LaTeX document classes, generate documents using alternate LaTeX engines, and produce fully linked PDF files with indexes, bibliographies, and tables of contents, destined for @@ -13495,10 +13929,17 @@ quick references to variables for the impatient: for engines, see ~org-latex-pdf-process~; for packages, see ~org-latex-default-packages-alist~ and ~org-latex-packages-alist~. -An important note about the LaTeX export back-end: it is sensitive to +An important note about the LaTeX export backend: it is sensitive to blank lines in the Org document. That's because LaTeX itself depends on blank lines to tell apart syntactical elements, such as paragraphs. +The following sections expect users to be familiar with common LaTeX +terminology. You may refer to https://tug.org/begin.html to get +familiar with LaTeX basics. Users with LaTeX installed may also run +=texdoc latex= from terminal to open LaTeX introduction [fn:: The +command will open a PDF file, which is also available for download +from http://mirrors.ctan.org/info/latex-doc-ptr/latex-doc-ptr.pdf] + *** LaTeX/PDF export commands :PROPERTIES: :DESCRIPTION: For producing @LaTeX{} and PDF documents. @@ -13542,22 +13983,22 @@ on blank lines to tell apart syntactical elements, such as paragraphs. #+cindex: xelatex #+cindex: lualatex #+cindex: @samp{LATEX_COMPILER}, keyword -The LaTeX export back-end can use any of these LaTeX engines: +The LaTeX export backend can use any of these LaTeX engines: =pdflatex=, =xelatex=, and =lualatex=. These engines compile LaTeX files with different compilers, packages, and output options. The -LaTeX export back-end finds the compiler version to use from +LaTeX export backend finds the compiler version to use from ~org-latex-compiler~ variable or the =#+LATEX_COMPILER= keyword in the Org file. See the docstring for the ~org-latex-default-packages-alist~ for loading packages with certain compilers. Also see ~org-latex-bibtex-compiler~ to set the -bibliography compiler[fn:47]. +bibliography compiler[fn:48]. *** LaTeX specific export settings :PROPERTIES: -:DESCRIPTION: Unique to this @LaTeX{} back-end. +:DESCRIPTION: Unique to this @LaTeX{} backend. :END: -The LaTeX export back-end has several additional keywords for +The LaTeX export backend has several additional keywords for customizing LaTeX output. Setting these keywords works similar to the general options (see [[*Export Settings]]). @@ -13577,8 +14018,11 @@ general options (see [[*Export Settings]]). #+cindex: @samp{LANGUAGE}, keyword #+vindex: org-latex-packages-alist #+vindex: org-latex-language-alist + #+vindex: org-export-default-language - Language code of the primary document language. + Language code of the primary document language. When =LANGUAGE= + keyword is not not specified use the value of + ~org-export-default-language~ (by default - =en=, American English) The list of language codes supported by Org is stored in the variable ~org-latex-language-alist~. @@ -13604,7 +14048,7 @@ general options (see [[*Export Settings]]). #+vindex: org-latex-classes This is LaTeX document class, such as /article/, /report/, /book/, and so on, which contain predefined preamble and headline level - mapping that the LaTeX export back-end needs. The back-end reads + mapping that the LaTeX export backend needs. The backend reads the default class name from the ~org-latex-default-class~ variable. Org has /article/ as the default class. A valid default class must be an element of ~org-latex-classes~. @@ -13612,7 +14056,7 @@ general options (see [[*Export Settings]]). - =LATEX_CLASS_OPTIONS= :: #+cindex: @samp{LATEX_CLASS_OPTIONS}, keyword - Options the LaTeX export back-end uses when calling the LaTeX + Options the LaTeX export backend uses when calling the LaTeX document class. - =LATEX_COMPILER= :: @@ -13668,12 +14112,12 @@ The following sections have further details. #+cindex: header, for @LaTeX{} files #+cindex: sectioning structure, for @LaTeX{} export -The LaTeX export back-end converts the first three of Org's outline +The LaTeX export backend converts the first three of Org's outline levels into LaTeX headlines. The remaining Org levels are exported as lists. To change this globally for the cut-off point between levels and lists, (see [[*Export Settings]]). -By default, the LaTeX export back-end uses the /article/ class. +By default, the LaTeX export backend uses the /article/ class. #+vindex: org-latex-default-class #+vindex: org-latex-classes @@ -13693,7 +14137,7 @@ custom sectioning or custom classes. #+cindex: @samp{LATEX_CLASS_OPTIONS}, keyword #+cindex: @samp{EXPORT_LATEX_CLASS}, property #+cindex: @samp{EXPORT_LATEX_CLASS_OPTIONS}, property -The LaTeX export back-end sends the =LATEX_CLASS_OPTIONS= keyword and +The LaTeX export backend sends the =LATEX_CLASS_OPTIONS= keyword and =EXPORT_LATEX_CLASS_OPTIONS= property as options to the LaTeX ~\documentclass~ macro. The options and the syntax for specifying them, including enclosing them in square brackets, follow LaTeX @@ -13703,10 +14147,10 @@ conventions. #+cindex: @samp{LATEX_HEADER}, keyword #+cindex: @samp{LATEX_HEADER_EXTRA}, keyword -The LaTeX export back-end appends values from =LATEX_HEADER= and +The LaTeX export backend appends values from =LATEX_HEADER= and =LATEX_HEADER_EXTRA= keywords to the LaTeX header. The docstring for ~org-latex-classes~ explains in more detail. Also note that LaTeX -export back-end does not append =LATEX_HEADER_EXTRA= to the header +export backend does not append =LATEX_HEADER_EXTRA= to the header when previewing LaTeX snippets (see [[*Previewing LaTeX fragments]]). A sample Org file with the above headers: @@ -13775,9 +14219,10 @@ This would produce in LaTeX (with the actual =polyglossia= syntax): :DESCRIPTION: Incorporating literal @LaTeX{} code. :END: -The LaTeX export back-end can insert any arbitrary LaTeX code, see -[[*Embedded LaTeX]]. There are three ways to embed such code in the Org -file and they all use different quoting syntax. +When the available LaTeX export customizations are not sufficient to +fine-tune the desired output, it is possible to insert any arbitrary +LaTeX code (see [[*Embedded LaTeX]]). There are three ways to embed such +code in the Org file and they all use different quoting syntax. #+cindex: inline, in @LaTeX{} export Inserting in-line quoted with @ symbols: @@ -13790,7 +14235,7 @@ Inserting as one or more keyword lines in the Org file: : #+LATEX: any arbitrary LaTeX code #+cindex: @samp{BEGIN_EXPORT latex} -Inserting as an export block in the Org file, where the back-end +Inserting as an export block in the Org file, where the backend exports any code between begin and end markers: #+begin_example @@ -13805,7 +14250,7 @@ exports any code between begin and end markers: :END: #+cindex: tables, in @LaTeX{} export -The LaTeX export back-end can pass several LaTeX attributes for table +The LaTeX export backend can pass several LaTeX attributes for table contents and layout. Besides specifying a label (see [[*Internal Links]]) and a caption (see [[*Captions]]), the other valid LaTeX attributes include: @@ -13814,27 +14259,27 @@ include: - =:mode= :: #+vindex: org-latex-default-table-mode - The LaTeX export back-end wraps the table differently depending on + The LaTeX export backend wraps the table differently depending on the mode for accurate rendering of math symbols. Mode is either =table=, =math=, =inline-math=, =verbatim= or =tabbing=. - For =math= or =inline-math= mode, LaTeX export back-end wraps the + For =math= or =inline-math= mode, LaTeX export backend wraps the table in a math environment, but every cell in it is exported as-is. For =tabbing= the LaTeX tabbing environment is used and the correct tabbing delimiters =\>= are used. - The LaTeX export back-end determines the default mode from - ~org-latex-default-table-mode~. The LaTeX export back-end merges + The LaTeX export backend determines the default mode from + ~org-latex-default-table-mode~. The LaTeX export backend merges contiguous tables in the same mode into a single environment. - =:environment= :: #+vindex: org-latex-default-table-environment Set the default LaTeX table environment for the LaTeX export - back-end to use when exporting Org tables. Common LaTeX table + backend to use when exporting Org tables. Common LaTeX table environments are provided by these packages: tabularx, longtable, array, tabu, and bmatrix. For packages, such as tabularx and tabu, or any newer replacements, include them in the - ~org-latex-packages-alist~ variable so the LaTeX export back-end can + ~org-latex-packages-alist~ variable so the LaTeX export backend can insert the appropriate load package headers in the converted LaTeX file. Look in the docstring for the ~org-latex-packages-alist~ variable for configuring these packages for LaTeX snippet previews, @@ -13860,11 +14305,11 @@ include: LaTeX floats can also have additional layout =:placement= attributes. These are the usual =[h t b p ! H]= permissions specified in square brackets. Note that for =:float sideways= - tables, the LaTeX export back-end ignores =:placement= attributes. + tables, the LaTeX export backend ignores =:placement= attributes. - =:align=, =:font=, =:width= :: - The LaTeX export back-end uses these attributes for regular tables + The LaTeX export backend uses these attributes for regular tables to set their alignments, fonts, and widths. - =:options= :: @@ -13877,7 +14322,7 @@ include: - =:spread= :: - When =:spread= is non-~nil~, the LaTeX export back-end spreads or + When =:spread= is non-~nil~, the LaTeX export backend spreads or shrinks the table by the =:width= for tabu and longtabu environments. =:spread= has no effect if =:width= is not set. @@ -13894,10 +14339,10 @@ include: - =:math-prefix=, =:math-suffix=, =:math-arguments= :: - The LaTeX export back-end inserts =:math-prefix= string value in - a math environment before the table. The LaTeX export back-end + The LaTeX export backend inserts =:math-prefix= string value in + a math environment before the table. The LaTeX export backend inserts =:math-suffix= string value in a math environment after the - table. The LaTeX export back-end inserts =:math-arguments= string + table. The LaTeX export backend inserts =:math-arguments= string value between the macro name and the table's contents. =:math-arguments= comes in use for matrix macros that require more than one argument, such as =qbordermatrix=. @@ -13935,13 +14380,13 @@ Set the caption with the LaTeX command #+cindex: inlining images in LaTeX #+cindex: @samp{ATTR_LATEX}, keyword -The LaTeX export back-end processes image links in Org files that do +The LaTeX export backend processes image links in Org files that do not have descriptions, such as these links =[[file:img.jpg]]= or =[[./img.jpg]]=, as direct image insertions in the final PDF output. In the PDF, they are no longer links but actual images embedded on the -page. The LaTeX export back-end uses =\includegraphics= macro to +page. The LaTeX export backend uses =\includegraphics= macro to insert the image. But for TikZ (https://sourceforge.net/projects/pgf/) -images, the back-end uses an ~\input~ macro wrapped within +images, the backend uses an ~\input~ macro wrapped within a ~tikzpicture~ environment. For specifying image =:width=, =:height=, =:scale= and other =:options=, @@ -13963,7 +14408,7 @@ overrides the default =#+CAPTION= value: #+end_example When captions follow the method as described in [[*Captions]], the LaTeX -export back-end wraps the picture in a floating =figure= environment. +export backend wraps the picture in a floating =figure= environment. To float an image without specifying a caption, set the =:float= attribute to one of the following: @@ -13973,7 +14418,7 @@ attribute to one of the following: - =multicolumn= :: - To span the image across multiple columns of a page; the back-end + To span the image across multiple columns of a page; the backend wraps the image in a =figure*= environment. - =wrap= :: @@ -14007,12 +14452,12 @@ placement. #+vindex: org-latex-images-centered #+cindex: center image in LaTeX export #+cindex: image, centering in LaTeX export -The LaTeX export back-end centers all images by default. Setting +The LaTeX export backend centers all images by default. Setting =:center= to =nil= disables centering. To disable centering globally, 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. +export backend to comment out the =\includegraphics= macro. *** Plain lists in LaTeX export :PROPERTIES: @@ -14021,7 +14466,7 @@ export back-end to comment out the =\includegraphics= macro. #+cindex: plain lists, in @LaTeX{} export #+cindex: @samp{ATTR_LATEX}, keyword -The LaTeX export back-end accepts the =environment= and =options= +The LaTeX export backend accepts the =environment= and =options= attributes for plain lists. Both attributes work together for customizing lists, as shown in the examples: @@ -14057,7 +14502,16 @@ four: #+cindex: source blocks, in @LaTeX{} export #+cindex: @samp{ATTR_LATEX}, keyword -The LaTeX export back-end can make source code blocks into floating +#+vindex: org-latex-src-block-backend +LaTeX export backend provides multiple ways to render src blocks in +LaTeX, according to the value of ~org-latex-src-block-backend~. The +default value =verbatim= renders the src code verbatim, without any +extra styling. Alternative values allow more colorful styling, but +require additional LaTeX (=listings=, =minted=), system (=minted=), or +Emacs (=engraved=) packages. See the ~org-latex-src-block-backend~ +docstring for more details. + +The LaTeX export backend can make source code blocks into floating objects through the attributes =:float= and =:options=. For =:float=: - =t= :: @@ -14084,7 +14538,7 @@ objects through the attributes =:float= and =:options=. For =:float=: #+vindex: org-latex-listings-options #+vindex: org-latex-minted-options #+vindex: org-latex-engraved-options -The LaTeX export back-end passes string values in =:options= to LaTeX +The LaTeX export backend passes string values in =:options= to LaTeX packages for customization of that specific source block. In the example below, the =:options= are set for Engraved or Minted. Minted is a source code highlighting LaTeX package with many configurable @@ -14115,7 +14569,7 @@ variables. #+cindex: verbatim blocks, in @LaTeX{} export #+cindex: @samp{ATTR_LATEX}, keyword -The LaTeX export back-end wraps the contents of example blocks in +The LaTeX export backend wraps the contents of example blocks in a =verbatim= environment. To change this behavior to use another environment globally, specify an appropriate export filter (see [[*Advanced Export Configuration]]). To change this behavior to use @@ -14139,8 +14593,8 @@ to specify a custom environment. #+cindex: proof, in @LaTeX{} export #+cindex: @samp{ATTR_LATEX}, keyword -For other special blocks in the Org file, the LaTeX export back-end -makes a special environment of the same name. The back-end also takes +For other special blocks in the Org file, the LaTeX export backend +makes a special environment of the same name. The backend also takes =:options=, if any, and appends as-is to that environment's opening string. For example: @@ -14188,7 +14642,7 @@ example: #+cindex: horizontal rules, in @LaTeX{} export #+cindex: @samp{ATTR_LATEX}, keyword -The LaTeX export back-end converts horizontal rules by the specified +The LaTeX export backend converts horizontal rules by the specified =:width= and =:thickness= attributes. For example: #+begin_example @@ -14204,10 +14658,10 @@ The LaTeX export back-end converts horizontal rules by the specified #+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. +The LaTeX export backend accepts five attributes for verse blocks: +=:lines=, =:center=, =:versewidth=, =:latexcode= and =:literal=. 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. @@ -14219,6 +14673,16 @@ of the standard LaTeX environment. verse. - =:latexcode= :: It accepts any arbitrary LaTeX code that can be included within a LaTeX =verse= environment. +- =:literal= :: With value t, all blank lines are preserved and + exported as =\vspace*{\baselineskip}=, including the blank lines + before or after contents. Note that without the =:literal= + attribute, one or more blank lines between stanzas are exported as a + single blank line, and any blank lines before or after the content + are removed, which is more consistent with the syntax of the LaTeX + `verse' environment, and the one provided by the =verse= package. + If the =verse= package is loaded, the vertical spacing between all + stanzas can be controlled by the global length =\stanzaskip= (see + https://www.ctan.org/pkg/verse). A complete example with Shakespeare's first sonnet: @@ -14252,7 +14716,7 @@ To eat the world’s due, by the grave and thee. #+cindex: @samp{ATTR_LATEX}, keyword #+cindex: org-latex-default-quote-environment -The LaTeX export back-end accepts two attributes for quote blocks: +The LaTeX export backend 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=, @@ -14291,12 +14755,18 @@ some text in German... :END: #+cindex: Markdown export -The Markdown export back-end, "md", converts an Org file to Markdown +The Markdown export backend, "md", converts an Org file to Markdown format, as defined at https://daringfireball.net/projects/markdown/. +This is the original Markdown specification, developed by John Gruber +and Aaron Swartz. + +Since "md" backend is built on top of the HTML backend (see [[*HTML +Export]]), it converts every Org construct not defined in Markdown +syntax, such as tables, to HTML. -Since it is built on top of the HTML back-end (see [[*HTML Export]]), it -converts every Org construct not defined in Markdown syntax, such as -tables, to HTML. +Do note that the original markdown syntax has differences with other +commonly used Markdown flavors. See +https://en.wikipedia.org/wiki/Markdown for more details. *** Markdown export commands :PROPERTIES: @@ -14328,10 +14798,12 @@ tables, to HTML. #+vindex: org-md-headline-style Based on ~org-md-headline-style~, Markdown export can generate -headlines of both /atx/ and /setext/ types. /atx/ limits headline -levels to two whereas /setext/ limits headline levels to six. Beyond -these limits, the export back-end converts headlines to lists. To set -a limit to a level before the absolute limit (see [[*Export Settings]]). +headlines of both /atx/ and /setext/ types. /setext/ limits headline +levels to two whereas /atx/ limits headline levels to six. /mixed/ +exports headline levels one and two in /setext/-style, and headline +levels three through six as /atx/-style headlines. Beyond these +limits, the export backend converts headlines to lists. To set a +limit to a level before the absolute limit (see [[*Export Settings]]). ** OpenDocument Text Export :PROPERTIES: @@ -14342,7 +14814,7 @@ a limit to a level before the absolute limit (see [[*Export Settings]]). #+cindex: export, OpenDocument #+cindex: LibreOffice -The ODT export back-end handles creating of OpenDocument Text (ODT) +The ODT export backend handles creating of OpenDocument Text (ODT) format. Documents created by this exporter use the {{{cite(OpenDocument-v1.2 specification)}}}[fn:: See [[https://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html][Open @@ -14355,7 +14827,7 @@ and are compatible with LibreOffice 3.4. :END: #+cindex: zip -The ODT export back-end relies on the zip program to create the final +The ODT export backend relies on the zip program to create the final compressed ODT output. Check if =zip= is locally available and executable. Without it, export cannot finish. @@ -14374,16 +14846,16 @@ executable. Without it, export cannot finish. #+vindex: org-odt-preferred-output-format If ~org-odt-preferred-output-format~ is specified, the ODT export - back-end automatically converts the exported file to that format. + backend automatically converts the exported file to that format. For =myfile.org=, Org exports to =myfile.odt=, overwriting without - warning. The ODT export back-end exports a region only if a region + warning. The ODT export backend exports a region only if a region was active. - If the selected region is a single tree, the ODT export back-end + If the selected region is a single tree, the ODT export backend makes the tree head the document title. Incidentally, {{{kbd(C-c @)}}} selects the current subtree. If the tree head entry has, or - inherits, an =EXPORT_FILE_NAME= property, the ODT export back-end + inherits, an =EXPORT_FILE_NAME= property, the ODT export backend uses that for file name. - {{{kbd(C-c C-e o O)}}} :: @@ -14401,21 +14873,21 @@ executable. Without it, export cannot finish. :DESCRIPTION: Configuration options. :END: -The ODT export back-end has several additional keywords for +The ODT export backend has several additional keywords for customizing ODT output. Setting these keywords works similar to the general options (see [[*Export Settings]]). - =DESCRIPTION= :: #+cindex: @samp{DESCRIPTION}, keyword - This is the document's description, which the ODT export back-end + This is the document's description, which the ODT export backend inserts as document metadata. For long descriptions, use multiple lines, prefixed with =DESCRIPTION=. - =KEYWORDS= :: #+cindex: @samp{KEYWORDS}, keyword - The keywords for the document. The ODT export back-end inserts the + The keywords for the document. The ODT export backend inserts the description along with author name, keywords, and related file metadata as metadata in the output file. Use multiple =KEYWORDS= if necessary. @@ -14424,7 +14896,7 @@ general options (see [[*Export Settings]]). #+cindex: @samp{ODT_STYLES_FILE}, keyword #+vindex: org-odt-styles-file - The ODT export back-end uses the ~org-odt-styles-file~ by default. + The ODT export backend uses the ~org-odt-styles-file~ by default. See [[*Applying custom styles]] for details. - =SUBTITLE= :: @@ -14437,7 +14909,7 @@ general options (see [[*Export Settings]]). :DESCRIPTION: Producing DOC, PDF files. :END: -The ODT export back-end can produce documents in other formats besides +The ODT export backend can produce documents in other formats besides ODT using a specialized ODT converter process. Its common interface works with popular converters to produce formats such as =doc=, or convert a document from one format, say =csv=, to another format, say @@ -14459,7 +14931,7 @@ a document converter]]. #+vindex: org-odt-preferred-output-format If ODT format is just an intermediate step to get to other formats, such as =doc=, =docx=, =rtf=, or =pdf=, etc., then extend the ODT -export back-end to directly produce that format. Specify the final +export backend to directly produce that format. Specify the final format in the ~org-odt-preferred-output-format~ variable. This is one way to extend (see [[*ODT export commands]]). @@ -14468,7 +14940,7 @@ way to extend (see [[*ODT export commands]]). :UNNUMBERED: notoc :END: -The Org export back-end is made to be inter-operable with a wide range +The Org export backend is made to be inter-operable with a wide range of text document format converters. Newer generation converters, such as LibreOffice and Pandoc, can handle hundreds of formats at once. Org provides a consistent interaction with whatever converter is @@ -14487,7 +14959,7 @@ installed. Here are some generic commands: #+cindex: styles, custom #+cindex: template, custom -The ODT export back-end comes with many OpenDocument styles (see +The ODT export backend comes with many OpenDocument styles (see [[*Working with OpenDocument style files]]). To expand or further customize these built-in style sheets, either edit the style sheets directly or generate them using an application such as LibreOffice. @@ -14530,7 +15002,7 @@ The example here shows creating a style using LibreOffice. :UNNUMBERED: notoc :END: -The ODT export back-end relies on many templates and style names. +The ODT export backend relies on many templates and style names. Using third-party styles and templates can lead to mismatches. Templates derived from built-in ODT templates and styles seem to have fewer problems. @@ -14559,18 +15031,18 @@ with a cross-reference and sequence number of the labeled entity. See #+cindex: tables, in ODT export -The ODT export back-end handles native Org mode tables (see [[*Tables]]) +The ODT export backend handles native Org mode tables (see [[*Tables]]) and simple =table.el= tables. Complex =table.el= tables having column or row spans are not supported. Such tables are stripped from the exported document. -By default, the ODT export back-end exports a table with top and +By default, the ODT export backend exports a table with top and bottom frames and with ruled lines separating row and column groups (see [[*Column Groups]]). All tables are typeset to occupy the same -width. The ODT export back-end honors any table alignments and +width. The ODT export backend honors any table alignments and relative widths for columns (see [[*Column Width and Alignment]]). -Note that the ODT export back-end interprets column widths as weighted +Note that the ODT export backend interprets column widths as weighted ratios, the default weight being 1. #+cindex: @samp{ATTR_ODT}, keyword @@ -14612,7 +15084,7 @@ tables in ODT export]]. :UNNUMBERED: notoc :END: -The ODT export back-end processes image links in Org files that do not +The ODT export backend processes image links in Org files that do not have descriptions, such as these links =[[file:img.jpg]]= or =[[./img.jpg]]=, as direct image insertions in the final output. Either of these examples works: @@ -14645,13 +15117,13 @@ attribute. #+cindex: identify, ImageMagick #+vindex: org-odt-pixels-per-inch -The ODT export back-end starts with establishing the size of the image +The ODT export backend starts with establishing the size of the image in the final document. The dimensions of this size are measured in -centimeters. The back-end then queries the image file for its -dimensions measured in pixels. For this measurement, the back-end +centimeters. The backend then queries the image file for its +dimensions measured in pixels. For this measurement, the backend relies on ImageMagick's identify program or Emacs ~create-image~ and ~image-size~ API. ImageMagick is the preferred choice for large file -sizes or frequent batch operations. The back-end then converts the +sizes or frequent batch operations. The backend then converts the pixel dimensions using ~org-odt-pixels-per-inch~ into the familiar 72 dpi or 96 dpi. The default value for this is in ~display-pixels-per-inch~, which can be tweaked for better results @@ -14702,7 +15174,7 @@ image scaling operations: :END: #+cindex: @samp{ATTR_ODT}, keyword -The ODT export back-end can anchor images to =as-char=, =paragraph=, +The ODT export backend can anchor images to =as-char=, =paragraph=, or =page=. Set the preferred anchor using the =:anchor= property of the =ATTR_ODT= line. @@ -14765,7 +15237,7 @@ document in one of the following ways: #+begin_src emacs-lisp (setq org-latex-to-mathml-convert-command - "latexmlmath \"%i\" --presentationmathml=%o") + "latexmlmath %i --presentationmathml=%o") #+end_src To quickly verify the reliability of the LaTeX-to-MathML @@ -14863,9 +15335,9 @@ With the above modification, the previous example changes to: :DESCRIPTION: For source code and example blocks. :END: -The ODT export back-end supports literal examples (see [[*Literal +The ODT export backend supports literal examples (see [[*Literal Examples]]) with full fontification. Internally, the ODT export -back-end relies on =htmlfontify.el= to generate the style definitions +backend relies on =htmlfontify.el= to generate the style definitions needed for fancy listings. The auto-generated styles get =OrgSrc= prefix and inherit colors from the faces used by Emacs Font Lock library for that source language. @@ -14883,7 +15355,7 @@ To turn off fontification of literal examples, customize the :DESCRIPTION: For power users. :END: -The ODT export back-end has extensive features useful for power users +The ODT export backend has extensive features useful for power users and frequent uses of ODT formats. **** Configuring a document converter @@ -14895,7 +15367,7 @@ and frequent uses of ODT formats. #+cindex: doc, docx, rtf #+cindex: converter -The ODT export back-end works with popular converters with little or +The ODT export backend works with popular converters with little or no extra configuration. See [[*Extending ODT export]]. The following is for unsupported converters or tweaking existing defaults. @@ -14969,7 +15441,7 @@ factory styles used by the exporter. - ~org-odt-styles-file~ :: - The ODT export back-end uses the file pointed to by this variable, + The ODT export backend uses the file pointed to by this variable, such as =styles.xml=, for the final output. It can take one of the following values: @@ -15006,7 +15478,7 @@ factory styles used by the exporter. :UNNUMBERED: notoc :END: -The ODT export back-end can read embedded raw OpenDocument XML from +The ODT export backend can read embedded raw OpenDocument XML from the Org file. Such direct formatting is useful for one-off instances. - Embedding ODT tags as part of regular text :: @@ -15032,7 +15504,7 @@ the Org file. Such direct formatting is useful for one-off instances. - Embedding a one-line OpenDocument XML :: #+cindex: @samp{ODT}, keyword - The ODT export back-end can read one-liner options with =#+ODT:= in + The ODT export backend can read one-liner options with =#+ODT:= in the Org file. For example, to force a page break: #+begin_example @@ -15052,7 +15524,7 @@ the Org file. Such direct formatting is useful for one-off instances. - Embedding a block of OpenDocument XML :: - The ODT export back-end can also read ODT export blocks for + The ODT export backend can also read ODT export blocks for OpenDocument XML. Such blocks use the =#+BEGIN_EXPORT odt= ... =#+END_EXPORT= constructs. @@ -15216,7 +15688,7 @@ schema-sensitive editing---of XML files: [[info:nxml-mode::Introduction]]. #+vindex: org-export-odt-schema-dir Customize ~org-odt-schema-dir~ to point to a directory with OpenDocument RNC files and the needed schema-locating rules. The ODT -export back-end takes care of updating the +export backend takes care of updating the ~rng-schema-locating-files~. ** Org Export @@ -15225,9 +15697,9 @@ export back-end takes care of updating the :END: #+cindex: Org export -/org/ export back-end creates a normalized version of the Org document +/org/ export backend creates a normalized version of the Org document in current buffer. The exporter evaluates Babel code (see [[*Evaluating -Code Blocks]]) and removes content specific to other back-ends. +Code Blocks]]) and removes content specific to other backends. *** Org export commands :PROPERTIES: @@ -15277,7 +15749,7 @@ Code Blocks]]) and removes content specific to other back-ends. :DESCRIPTION: Setting the environment. :END: -The Texinfo export back-end has several additional keywords for +The Texinfo export backend has several additional keywords for customizing Texinfo output. Setting these keywords works similar to the general options (see [[*Export Settings]]). @@ -15316,17 +15788,26 @@ the general options (see [[*Export Settings]]). - =TEXINFO_DIR_CATEGORY= :: #+cindex: @samp{TEXINFO_DIR_CATEGORY}, keyword - The directory category of the document. + The directory category of the document. Defaults to ~Misc~. -- =TEXINFO_DIR_TITLE= :: +- =TEXINFO_DIR_NAME= :: - #+cindex: @samp{TEXINFO_DIR_TITLE}, keyword - The directory title of the document. + #+cindex: @samp{TEXINFO_DIR_NAME}, keyword + The directory name of the document. + This is the short name under which the ~m~ command will find your + manual in the main Info directory. It defaults to the base name of + the Texinfo file. + + The full form of the Texinfo entry is ~* DIRNAME: NODE.~ where ~NODE~ + is usually just ~(FILENAME)~. Normally this option only provides the + ~DIRNAME~ part, but if you need more control, it can also be the full + entry (recognized by the presence of parentheses or a leading ~* ~). - =TEXINFO_DIR_DESC= :: #+cindex: @samp{TEXINFO_DIR_DESC}, keyword The directory description of the document. + Defaults to the title of the document. - =TEXINFO_PRINTED_TITLE= :: @@ -15339,7 +15820,7 @@ the general options (see [[*Export Settings]]). :END: #+cindex: @samp{TEXINFO_FILENAME}, keyword -After creating the header for a Texinfo file, the Texinfo back-end +After creating the header for a Texinfo file, the Texinfo backend automatically generates a name and destination path for the Info file. To override this default with a more sensible path and name, specify the =TEXINFO_FILENAME= keyword. @@ -15383,7 +15864,7 @@ keywords. They have to be set in raw Texinfo code. #+cindex: @samp{COPYING}, property Copying material is defined in a dedicated headline with a non-~nil~ -=COPYING= property. The back-end inserts the contents within +=COPYING= property. The backend inserts the contents within a =@copying= command at the beginning of the document. The heading itself does not appear in the structure of the document. @@ -15410,11 +15891,11 @@ Copyright information is printed on the back of the title page. #+cindex: @code{install-info}, in Texinfo export #+cindex: @samp{TEXINFO_DIR_CATEGORY}, keyword -#+cindex: @samp{TEXINFO_DIR_TITLE}, keyword +#+cindex: @samp{TEXINFO_DIR_NAME}, keyword #+cindex: @samp{TEXINFO_DIR_DESC}, keyword The end result of the Texinfo export process is the creation of an Info file. This Info file's metadata has variables for category, -title, and description: =TEXINFO_DIR_CATEGORY=, =TEXINFO_DIR_TITLE=, +title, and description: =TEXINFO_DIR_CATEGORY=, =TEXINFO_DIR_NAME=, and =TEXINFO_DIR_DESC= keywords that establish where in the Info hierarchy the file fits. @@ -15422,7 +15903,7 @@ Here is an example that writes to the Info directory file: #+begin_example ,#+TEXINFO_DIR_CATEGORY: Emacs -,#+TEXINFO_DIR_TITLE: Org Mode: (org) +,#+TEXINFO_DIR_NAME: Org Mode ,#+TEXINFO_DIR_DESC: Outline-based notes management and organizer #+end_example @@ -15434,7 +15915,7 @@ Here is an example that writes to the Info directory file: #+vindex: org-texinfo-classes #+vindex: org-texinfo-default-class #+cindex: @samp{TEXINFO_CLASS}, keyword -The Texinfo export back-end uses a pre-defined scheme to convert Org +The Texinfo export backend uses a pre-defined scheme to convert Org headlines to equivalent Texinfo structuring commands. A scheme like this maps top-level headlines to numbered chapters tagged as ~@chapter~ and lower-level headlines to unnumbered chapters tagged as @@ -15442,21 +15923,21 @@ this maps top-level headlines to numbered chapters tagged as other Texinfo structuring commands, define a new class in ~org-texinfo-classes~. Activate the new class with the =TEXINFO_CLASS= keyword. When no new class is defined and activated, -the Texinfo export back-end defaults to the +the Texinfo export backend defaults to the ~org-texinfo-default-class~. If an Org headline's level has no associated Texinfo structuring command, or is below a certain threshold (see [[*Export Settings]]), then -the Texinfo export back-end makes it into a list item. +the Texinfo export backend makes it into a list item. #+cindex: @samp{APPENDIX}, property -The Texinfo export back-end makes any headline with a non-~nil~ +The Texinfo export backend makes any headline with a non-~nil~ =APPENDIX= property into an appendix. This happens independent of the Org headline level or the =TEXINFO_CLASS= keyword. #+cindex: @samp{ALT_TITLE}, property #+cindex: @samp{DESCRIPTION}, property -The Texinfo export back-end creates a menu entry after the Org +The Texinfo export backend creates a menu entry after the Org headline for each regular sectioning structure. To override this with a shorter menu entry, use the =ALT_TITLE= property (see [[*Table of Contents]]). Texinfo menu entries also have an option for a longer @@ -15494,7 +15975,7 @@ file. See [[info:texinfo::The Top Node]], for more information. #+cindex: data type index, in Texinfo export #+cindex: @samp{VINDEX}, keyword #+cindex: variable index, in Texinfo export -The Texinfo export back-end recognizes these indexing keywords if used +The Texinfo export backend recognizes these indexing keywords if used in the Org file: =CINDEX=, =FINDEX=, =KINDEX=, =PINDEX=, =TINDEX= and =VINDEX=. Write their value as verbatim Texinfo code; in particular, ={=, =}= and =@= characters need to be escaped with =@= if they do not @@ -15503,10 +15984,10 @@ belong to a Texinfo command. : #+CINDEX: Defining indexing entries #+cindex: @samp{INDEX}, property -For the back-end to generate an index entry for a headline, set the +For the backend to generate an index entry for a headline, set the =INDEX= property to =cp= or =vr=. These abbreviations come from Texinfo that stand for concept index and variable index. The Texinfo -manual has abbreviations for all other kinds of indexes. The back-end +manual has abbreviations for all other kinds of indexes. The backend exports the headline as an unnumbered chapter or section command, and then inserts the index after its contents. @@ -15546,7 +16027,7 @@ This paragraph is preceded by... #+cindex: lettered lists, in Texinfo export #+cindex: enum, Texinfo attribute -The Texinfo export back-end converts unordered and ordered lists in +The Texinfo export backend converts unordered and ordered lists in the Org file using the default command =@itemize=. Ordered lists are numbered when exported to Texinfo format. Such @@ -15564,7 +16045,7 @@ specific number, or switch to a lettered list, as illustrated here: #+cindex: @samp{ATTR_TEXINFO}, keyword #+cindex: two-column tables, in Texinfo export #+cindex: table-type, Texinfo attribute -The Texinfo export back-end by default converts description lists in +The Texinfo export backend by default converts description lists in the Org file using the default command =@table=, which results in a table with two columns. To change this behavior, set =:table-type= attribute to either =ftable= or =vtable= value. For more information, @@ -15572,7 +16053,7 @@ see [[info:texinfo::Two-column Tables]]. #+vindex: org-texinfo-table-default-markup #+cindex: indic, Texinfo attribute -The Texinfo export back-end by default also applies a text highlight +The Texinfo export backend by default also applies a text highlight based on the defaults stored in ~org-texinfo-table-default-markup~. To override the default highlight command, specify another one with the =:indic= attribute. @@ -15580,7 +16061,7 @@ the =:indic= attribute. #+cindex: multiple items in Texinfo lists #+cindex: sep, Texinfo attribute Org syntax is limited to one entry per list item. Nevertheless, the -Texinfo export back-end can split that entry according to any text +Texinfo export backend can split that entry according to any text provided through the =:sep= attribute. Each part then becomes a new entry in the first column of the table. @@ -15604,9 +16085,9 @@ This is the common text for variables foo and bar. The =:compact= attribute is an alternative to the =:sep= attribute, which allows writing each entry on its own line. If this attribute is -non-nil and an item in a description list has no body but is followed -by another item, then the second item is transcoded to =@itemx=. This -example is transcoded to the same output as above. +non-~nil~ and an item in a description list has no body but is +followed by another item, then the second item is transcoded to +=@itemx=. This example is transcoded to the same output as above. #+begin_example ,#+ATTR_TEXINFO: :table-type vtable :indic asis :compact t @@ -15619,12 +16100,12 @@ Support for this compact syntax can also be enabled for all lists in a file using the =compact-itemx= export option, or globally using the variable ~org-texinfo-compact-itemx~. -The Texinfo export back-end also supports two approaches to writing +The Texinfo export backend also supports two approaches to writing Texinfo definition commands (see [[info:texinfo::Definition Commands]]). One of them uses description lists and is described below, the other relies on special blocks (see [[*Special blocks in Texinfo export]]). -Items in a description list in a Org file that begin with =Function:= +Items in a description list in an Org file that begin with =Function:= or certain other prefixes are converted using Texinfo definition commands. This works even if other items in the same list do not have such a prefix; if necessary a single description list is converted @@ -15691,7 +16172,7 @@ Command in parenthesis, as done above, is optional. :END: #+cindex: @samp{ATTR_TEXINFO}, keyword -When exporting tables, the Texinfo export back-end uses the widest +When exporting tables, the Texinfo export backend uses the widest cell width in each column. To override this and instead specify as fractions of line length, use the =:columns= attribute. See example below. @@ -15708,7 +16189,7 @@ below. #+cindex: @samp{ATTR_TEXINFO}, keyword Insert a file link to the image in the Org file, and the Texinfo -export back-end inserts the image. These links must have the usual +export backend inserts the image. These links must have the usual supported image extensions and no descriptions. To scale the image, use =:width= and =:height= attributes. For alternate text, use =:alt= and specify the text using Texinfo code, as shown in the example: @@ -15779,13 +16260,13 @@ Type @kbd{C-c @key{SPC}}. :DESCRIPTION: Special block attributes. :END: -The Texinfo export back-end supports two approaches to writing Texinfo +The Texinfo export backend supports two approaches to writing Texinfo definition commands. One of them is described here, the other in [[*Plain lists in Texinfo export]]. #+cindex: @samp{ATTR_TEXINFO}, keyword -The Texinfo export back-end converts special blocks to commands with +The Texinfo export backend converts special blocks to commands with the same name. It also adds any =:options= attributes to the end of the command, as shown in this example: @@ -15830,7 +16311,7 @@ Texinfo code. ,#+TEXINFO_HEADER: @syncodeindex pg cp ,#+TEXINFO_DIR_CATEGORY: Texinfo documentation system -,#+TEXINFO_DIR_TITLE: sample: (sample) +,#+TEXINFO_DIR_NAME: sample ,#+TEXINFO_DIR_DESC: Invoking sample ,#+TEXINFO_PRINTED_TITLE: GNU Sample @@ -15887,24 +16368,35 @@ This manual is for GNU Sample (version {{{version}}}, A large part of Org mode's interoperability success is its ability to easily export to or import from external applications. The iCalendar -export back-end takes calendar data from Org files and exports to the +export backend takes calendar data from Org files and exports to the standard iCalendar format. +#+vindex: icalendar-export-sexp-enumeration-days +By default, iCalendar export only includes headings that contain +active timestamps or diary sexps[fn:: Diary sexp events, except +certain built-in types (see ~icalendar-export-sexp-enumerate-all~), +are exported up to ~icalendar-export-sexp-enumeration-days~ into +future.]. + #+vindex: org-icalendar-include-todo -#+vindex: org-icalendar-use-deadline -#+vindex: org-icalendar-use-scheduled -The iCalendar export back-end can also incorporate TODO entries based +The iCalendar export backend can also incorporate TODO entries based on the configuration of the ~org-icalendar-include-todo~ variable. -The back-end exports plain timestamps as =VEVENT=, TODO items as +The backend exports plain timestamps as =VEVENT=, TODO items as =VTODO=, and also create events from deadlines that are in non-TODO -items. The back-end uses the deadlines and scheduling dates in Org -TODO items for setting the start and due dates for the iCalendar TODO -entry. Consult the ~org-icalendar-use-deadline~ and -~org-icalendar-use-scheduled~ variables for more details. +items. + +#+vindex: org-icalendar-use-deadline +#+vindex: org-icalendar-use-scheduled +#+vindex: org-icalendar-todo-unscheduled-start +The backend uses the deadlines and scheduling dates in Org TODO items +for setting the start and due dates for the iCalendar TODO entry. +Consult the ~org-icalendar-use-deadline~, +~org-icalendar-use-scheduled~, and +~org-icalendar-todo-unscheduled-start~ variables for more details. #+vindex: org-icalendar-categories #+vindex: org-icalendar-alarm-time -For tags on the headline, the iCalendar export back-end makes them +For tags on the headline, the iCalendar export backend makes them into iCalendar categories. To tweak the inheritance of tags and TODO states, configure the variable ~org-icalendar-categories~. To assign clock alarms based on time, configure the ~org-icalendar-alarm-time~ @@ -15913,10 +16405,10 @@ variable. #+vindex: org-icalendar-store-UID #+cindex: @samp{ID}, property The iCalendar format standard requires globally unique identifier---or -UID---for each entry. The iCalendar export back-end creates UIDs +UID---for each entry. The iCalendar export backend creates UIDs during export. To save a copy of the UID in the Org file set the -variable ~org-icalendar-store-UID~. The back-end looks for the =ID= -property of the entry for re-using the same UID for subsequent +variable ~org-icalendar-store-UID~. The backend looks for the =ID= +property of the entry for reusing the same UID for subsequent exports. Since a single Org entry can result in multiple iCalendar @@ -15954,15 +16446,27 @@ connections. #+cindex: @samp{LOCATION}, property #+cindex: @samp{TIMEZONE}, property #+cindex: @samp{CLASS}, property -The iCalendar export back-end includes =SUMMARY=, =DESCRIPTION=, +The iCalendar export backend includes =SUMMARY=, =DESCRIPTION=, =LOCATION=, =TIMEZONE= and =CLASS= properties from the Org entries -when exporting. To force the back-end to inherit the =LOCATION=, +when exporting. To force the backend to inherit the =LOCATION=, =TIMEZONE= and =CLASS= properties, configure the ~org-use-property-inheritance~ variable. +=SUMMARY=, =LOCATION=, and =DESCRIPTION= properties can define +multi-line summary, location, or description using =+= +syntax (see [[*Property Syntax]]): + +: * Meeting at location with multi-line address +: <2024-01-08 Mon 14:20-15:00> +: :PROPERTIES: +: :LOCATION: Someplace +: :LOCATION+: Some Street 5 +: :LOCATION+: 12345 Small Town +: :END: + #+vindex: org-icalendar-include-body When Org entries do not have =SUMMARY=, =DESCRIPTION=, =LOCATION= and -=CLASS= properties, the iCalendar export back-end derives the summary +=CLASS= properties, the iCalendar export backend derives the summary from the headline, and derives the description from the body of the Org item. The ~org-icalendar-include-body~ variable limits the maximum number of characters of the content are turned into its @@ -15984,23 +16488,32 @@ information. The iCalendar standard defines three visibility classes: The server should treat unknown class properties the same as =PRIVATE=. +#+cindex: @samp{ICAL-TTL}, keyword +#+vindex: org-icalendar-ttl +The exported iCalendar file can advise clients how often to check for +updates. This duration can be set globally with the +~org-icalendar-ttl~ variable, or on a per-document basis with the +=ICAL-TTL= keyword. This option should be set using the iCalendar +notation for time durations; consult the docstring of +~org-icalendar-ttl~ for more details. + Exporting to iCalendar format depends in large part on the capabilities of the destination application. Some are more lenient than others. Consult the Org mode FAQ for advice on specific applications. -** Other Built-in Back-ends +** Other Built-in Backends :PROPERTIES: :DESCRIPTION: Exporting to a man page. :END: -Other export back-ends included with Org are: +Other export backends included with Org are: - =ox-man.el=: Export to a man page. -To activate such back-ends, either customize ~org-export-backends~ or +To activate such backends, either customize ~org-export-backends~ or load directly with =(require 'ox-man)=. On successful load, the -back-end adds new keys in the export dispatcher (see [[*The Export +backend adds new keys in the export dispatcher (see [[*The Export Dispatcher]]). Follow the comment section of such files, for example, =ox-man.el=, @@ -16017,31 +16530,33 @@ for usage and configuration details. :END: #+vindex: org-export-before-processing-hook +#+vindex: org-export-before-processing-functions #+vindex: org-export-before-parsing-hook The export process executes two hooks before the actual exporting -begins. The first hook, ~org-export-before-processing-hook~, runs -before any expansions of macros, Babel code, and include keywords in -the buffer. The second hook, ~org-export-before-parsing-hook~, runs -before the buffer is parsed. +begins. The first hook, ~org-export-before-processing-functions~, +runs before any expansions of macros, Babel code, and include keywords +in the buffer. The second hook, +~org-export-before-parsing-functions~, runs before the buffer is +parsed. Functions added to these hooks are called with a single argument: the -export back-end actually used, as a symbol. You may use them for +export backend actually used, as a symbol. You may use them for heavy duty structural modifications of the document. For example, you can remove every headline in the buffer during export like this: #+begin_src emacs-lisp (defun my-headline-removal (backend) "Remove all headlines in the current buffer. -BACKEND is the export back-end being used, as a symbol." +BACKEND is the export backend being used, as a symbol." (org-map-entries (lambda () (delete-region (point) (line-beginning-position 2)) ;; We need to tell `org-map-entries' to not skip over heading at - ;; point. Otherwise, it would continue from _next_ heading. See + ;; point. Otherwise, it would continue from _next_ heading. See ;; the docstring of `org-map-entries' for details. (setq org-map-continue-from (point))))) -(add-hook 'org-export-before-parsing-hook #'my-headline-removal) +(add-hook 'org-export-before-parsing-functions #'my-headline-removal) #+end_src *** Filters @@ -16051,7 +16566,7 @@ BACKEND is the export back-end being used, as a symbol." #+cindex: Filters, exporting Filters are lists of functions to be applied to certain parts for -a given back-end. The output from the first function in the filter is +a given backend. The output from the first function in the filter is passed on to the next function in the filter. The final output is the output from the final function in the filter. @@ -16082,7 +16597,7 @@ is the type targeted by the filter. Valid types are: | underline | verbatim | verse-block | Here is an example filter that replaces non-breaking spaces ~ ~ in the -Org buffer with =~= for the LaTeX back-end. +Org buffer with =~= for the LaTeX backend. #+begin_src emacs-lisp (defun my-latex-filter-nobreaks (text backend info) @@ -16095,10 +16610,10 @@ Org buffer with =~= for the LaTeX back-end. #+end_src A filter requires three arguments: the code to be transformed, the -name of the back-end, and some optional information about the export +name of the backend, and some optional information about the export process. The third argument can be safely ignored. Note the use of ~org-export-derived-backend-p~ predicate that tests for /latex/ -back-end or any other back-end, such as /beamer/, derived from +backend or any other backend, such as /beamer/, derived from /latex/. *** Defining filters for individual files @@ -16106,7 +16621,7 @@ back-end or any other back-end, such as /beamer/, derived from :UNNUMBERED: notoc :END: -The Org export can filter not just for back-ends, but also for +The Org export can filter not just for backends, but also for specific files through the =BIND= keyword. Here is an example with two filters; one removes brackets from time stamps, and the other removes strike-through text. The filter functions are defined in @@ -16123,26 +16638,179 @@ debugging. ,#+END_SRC #+end_example -*** Extending an existing back-end +*** Summary of the export process +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +#+findex: org-export-as +Org mode export is a multi-step process that works on a temporary copy +of the buffer. The export process consists of 4 major steps: + +1. Process the temporary copy, making necessary changes to the buffer + text; + +2. Parse the buffer, converting plain Org markup into an abstract + syntax tree (AST); + +3. Convert the AST to text, as prescribed by the selected export + backend; + +4. Post-process the resulting exported text. + + +#+texinfo: @noindent +Process temporary copy of the source Org buffer [fn::Unless +otherwise specified, each step of the export process only operates on +the accessible portion of the buffer. When subtree export is selected +(see [[*The Export Dispatcher]]), the buffer is narrowed to the body of +the selected subtree, so that the rest of the buffer text, except +export keywords, does not contribute to the export output.]: + +1. Execute ~org-export-before-processing-functions~ (see [[*Export hooks]]); + +2. Expand =#+include= keywords in the whole buffer (see + [[*Include Files]]); + +3. Remove commented subtrees in the whole buffer (see [[*Comment + Lines]]); + +4. Replace macros in the whole buffer (see [[*Macro Replacement]]); + +5. When ~org-export-use-babel~ is non-nil (default), process code + blocks: + + - Leave code blocks inside archived subtrees (see [[*Internal + archiving]]) as is; + + - Evaluate all the other code blocks according to code block + headers (see [[*Limit code block evaluation]]); + + - Remove code, results of evaluation, both, or neither according + to =:exports= header argument (see [[*Exporting Code Blocks]]). + + +#+texinfo: @noindent +Parse the temporary buffer, creating AST: + +1. Execute ~org-export-before-parsing-functions~ (see [[*Export hooks]]). + The hook functions may still modify the buffer; + +2. Calculate export option values according to subtree-specific export + settings, in-buffer keywords, =#+BIND= keywords, and buffer-local + and global customization. The whole buffer is considered; + +3. When ~org-org-with-cite-processors~ is non-nil (default), determine + contributing bibliographies and record them into export options + (see [[*Citations]]). The whole buffer is considered; + +4. Execute ~org-export-filter-options-functions~; + +5. Parse the accessible portion of the temporary buffer to generate an + AST. The AST is a nested list of lists representing Org syntax + elements (see [[https://orgmode.org/worg/dev/org-element-api.html][Org Element API]] for more details): + + : (org-data ... + : (heading + : (section + : (paragraph (plain-text) (bold (plain-text)))) + : (heading) + : (heading (section ...)))) + + Past this point, modifications to the temporary buffer no longer + affect the export; Org export works only with the AST; + +6. Remove elements that are not exported from the AST: + + - Headings according to =SELECT_TAGS= and =EXCLUDE_TAGS= export + keywords; =task=, =inline=, =arch= export options (see + [[*Export Settings]]); + + - Comments; + + - Clocks, drawers, fixed-width environments, footnotes, LaTeX + environments and fragments, node properties, planning lines, + property drawers, statistics cookies, timestamps, etc according + to =#+OPTIONS= keyword (see [[*Export Settings]]); + + - Table rows containing width and alignment markers, unless the + selected export backend changes ~:with-special-rows~ export option + to non-nil (see [[*Column Width and Alignment]]); + + - Table columns containing recalc marks (see [[*Advanced features]]). + +7. Expand environment variables in file link AST nodes according to + the =expand-links= export option (see [[*Export Settings]]); + +8. Execute ~org-export-filter-parse-tree-functions~. These + functions can modify the AST by side effects; + +9. When ~org-org-with-cite-processors~ is non-nil (default), replace + citation AST nodes and =#+print_bibliography= keyword AST nodes as + prescribed by the selected citation export processor (see [[*Citation + export processors]]). + + +#+texinfo: @noindent +Convert the AST to text by traversing the AST nodes, depth-first: + +1. Convert the leaf nodes (without children) to text as prescribed + by "transcoders" in the selected export backend + [fn:: See transcoders and ~:translate-alist~ in the docstrings + of ~org-export-define-backend~ and ~org-export-define-derived-backend~.]; + +2. Pass the converted nodes through the corresponding export + filters (see [[*Filters]]); + +3. Concatenate all the converted child nodes to produce parent + node contents; + +4. Convert the nodes with children to text, passing the nodes + themselves and their exported contents to the corresponding + transcoders and then to the export filters (see [[*Filters]]). + + +#+texinfo: @noindent +Post-process the exported text: + + 1. Post-process the converted AST, as prescribed by the export + backend. [fn:: See ~inner-template~ in the docstring of ~org-export-define-backend~.] + This step usually adds generated content (like Table of Contents) + to the exported text; + + 2. Execute ~org-export-filter-body-functions~; + + 3. Unless body-only export is selected (see [[*The Export Dispatcher]]), + add the necessary metadata to the final document, as prescribed + by the export backend. Examples: Document author/title; HTML + headers/footers; LaTeX preamble; + + 4. When ~org-org-with-cite-processors~ is non-nil (default), add + bibliography metadata, as prescribed by the citation export + processor; + + 5. Execute ~org-export-filter-final-output-functions~. + +*** Extending an existing backend :PROPERTIES: :UNNUMBERED: notoc :END: Some parts of the conversion process can be extended for certain elements so as to introduce a new or revised translation. That is how -the HTML export back-end was extended to handle Markdown format. The +the HTML export backend was extended to handle Markdown format. The extensions work seamlessly so any aspect of filtering not done by the -extended back-end is handled by the original back-end. Of all the +extended backend is handled by the original backend. Of all the export customization in Org, extending is very powerful as it operates at the parser level. -For this example, make the /ascii/ back-end display the language used +For this example, make the /ascii/ backend display the language used in a source code block. Also make it display only when some attribute is non-~nil~, like the following: : #+ATTR_ASCII: :language t -Then extend ASCII back-end with a custom "my-ascii" back-end. +Then extend ASCII backend with a custom "my-ascii" backend. #+begin_src emacs-lisp (defun my-ascii-src-block (src-block contents info) @@ -16164,13 +16832,13 @@ channel." #+end_src The ~my-ascii-src-block~ function looks at the attribute above the -current element. If not true, hands over to /ascii/ back-end. If +current element. If not true, hands over to /ascii/ backend. If true, which it is in this example, it creates a box around the code and leaves room for the inserting a string for language. The last -form creates the new back-end that springs to action only when +form creates the new backend that springs to action only when translating ~src-block~ type elements. -To use the newly defined back-end, evaluate the following from an Org +To use the newly defined backend, evaluate the following from an Org buffer: #+begin_src emacs-lisp @@ -16179,79 +16847,60 @@ buffer: Further steps to consider would be an interactive function, self-installing an item in the export dispatcher menu, and other -user-friendly improvements. +user-friendly improvements. See + for more +details. -** Export in Foreign Buffers +** Export Region :PROPERTIES: :DESCRIPTION: Author tables and lists in Org syntax. :END: -The export back-ends in Org often include commands to convert selected -regions. A convenient feature of this in-place conversion is that the -exported output replaces the original source. Here are such -functions: +Some export backends include commands to convert a region of Org +formatted text to another format, such as HTML or LaTeX. The +conversion replaces the original source. Here are such commands: -- ~org-ascii-convert-region-to-ascii~ :: +- ~org-export-region-to-ascii~ :: #+findex: org-ascii-convert-region-to-ascii + #+findex: org-export-region-to-ascii Convert the selected region into ASCII. -- ~org-ascii-convert-region-to-utf8~ :: +- ~org-export-region-to-utf8~ :: #+findex: org-ascii-convert-region-to-utf8 + #+findex: org-export-region-to-utf8 Convert the selected region into UTF-8. -- ~org-html-convert-region-to-html~ :: +- ~org-export-region-to-html~ :: #+findex: org-html-convert-region-to-html + #+findex: org-export-region-to-html Convert the selected region into HTML. -- ~org-latex-convert-region-to-latex~ :: +- ~org-export-region-to-latex~ :: #+findex: org-latex-convert-region-to-latex + #+findex: org-export-region-to-latex Convert the selected region into LaTeX. -- ~org-texinfo-convert-region-to-texinfo~ :: +- ~org-export-region-to-texinfo~ :: #+findex: org-texinfo-convert-region-to-texinfo + #+findex: org-export-region-to-texinfo Convert the selected region into Texinfo. -- ~org-md-convert-region-to-md~ :: +- ~org-export-region-to-md~ :: #+findex: org-md-convert-region-to-md + #+findex: org-export-region-to-md Convert the selected region into Markdown. -In-place conversions are particularly handy for quick conversion of -tables and lists in foreign buffers. For example, in an HTML buffer, +The in-place conversion is particularly handy for quick conversion of +tables and lists in non-Org buffers. For example, in an HTML buffer, write a list in Org syntax, select it, and convert it to HTML with {{{kbd(M-x org-html-convert-region-to-html)}}}. -*** Exporting to minimal HTML -:PROPERTIES: -:DESCRIPTION: Exporting HTML without CSS, Javascript, etc. -:ALT_TITLE: Bare HTML -:END: - -If you want to output a minimal HTML file, with no CSS, no Javascript, -no preamble or postamble, here are the variable you would need to set: - -#+vindex: org-html-head -#+vindex: org-html-head-extra -#+vindex: org-html-head-include-default-style -#+vindex: org-html-head-include-scripts -#+vindex: org-html-preamble -#+vindex: org-html-postamble -#+vindex: org-html-use-infojs -#+begin_src emacs-lisp -(setq org-html-head "" - org-html-head-extra "" - org-html-head-include-default-style nil - org-html-head-include-scripts nil - org-html-preamble nil - org-html-postamble nil - org-html-use-infojs nil) -#+end_src - * Publishing :PROPERTIES: :DESCRIPTION: Create a web site of linked Org files. @@ -16446,228 +17095,107 @@ Settings]]), however, override everything. :UNNUMBERED: notoc :END: -| ~:archived-trees~ | ~org-export-with-archived-trees~ | -| ~:exclude-tags~ | ~org-export-exclude-tags~ | -| ~:headline-levels~ | ~org-export-headline-levels~ | -| ~:language~ | ~org-export-default-language~ | -| ~:preserve-breaks~ | ~org-export-preserve-breaks~ | -| ~:section-numbers~ | ~org-export-with-section-numbers~ | -| ~:select-tags~ | ~org-export-select-tags~ | -| ~:with-author~ | ~org-export-with-author~ | -| ~:with-broken-links~ | ~org-export-with-broken-links~ | -| ~:with-clocks~ | ~org-export-with-clocks~ | -| ~:with-creator~ | ~org-export-with-creator~ | -| ~:with-date~ | ~org-export-with-date~ | -| ~:with-drawers~ | ~org-export-with-drawers~ | -| ~:with-email~ | ~org-export-with-email~ | -| ~:with-emphasize~ | ~org-export-with-emphasize~ | -| ~:with-fixed-width~ | ~org-export-with-fixed-width~ | -| ~:with-footnotes~ | ~org-export-with-footnotes~ | -| ~:with-latex~ | ~org-export-with-latex~ | -| ~:with-planning~ | ~org-export-with-planning~ | -| ~:with-priority~ | ~org-export-with-priority~ | -| ~:with-properties~ | ~org-export-with-properties~ | -| ~:with-special-strings~ | ~org-export-with-special-strings~ | -| ~:with-sub-superscript~ | ~org-export-with-sub-superscripts~ | -| ~:with-tables~ | ~org-export-with-tables~ | -| ~:with-tags~ | ~org-export-with-tags~ | -| ~:with-tasks~ | ~org-export-with-tasks~ | -| ~:with-timestamps~ | ~org-export-with-timestamps~ | -| ~:with-title~ | ~org-export-with-title~ | -| ~:with-toc~ | ~org-export-with-toc~ | -| ~:with-todo-keywords~ | ~org-export-with-todo-keywords~ | +#+NAME: org-manual-get-export-props-customizations +#+begin_src emacs-lisp :exports none :results table +(require 'ox) +(let (result) + (dolist (spec alist) + (when (and (nth 3 spec) (symbolp (nth 3 spec))) ; has customization + (push (list (format "~%s~" (car spec)) (format "~%s~" (nth 3 spec))) result))) + (nreverse result)) +#+end_src + +#+begin_src emacs-lisp :exports results :results table :eval yes :noweb yes +(require 'ox) +(let ((alist org-export-options-alist)) +<> +) +#+end_src + **** ASCII specific properties :PROPERTIES: :UNNUMBERED: notoc :END: -| ~:ascii-bullets~ | ~org-ascii-bullets~ | -| ~:ascii-caption-above~ | ~org-ascii-caption-above~ | -| ~:ascii-charset~ | ~org-ascii-charset~ | -| ~:ascii-global-margin~ | ~org-ascii-global-margin~ | -| ~:ascii-format-drawer-function~ | ~org-ascii-format-drawer-function~ | -| ~:ascii-format-inlinetask-function~ | ~org-ascii-format-inlinetask-function~ | -| ~:ascii-headline-spacing~ | ~org-ascii-headline-spacing~ | -| ~:ascii-indented-line-width~ | ~org-ascii-indented-line-width~ | -| ~:ascii-inlinetask-width~ | ~org-ascii-inlinetask-width~ | -| ~:ascii-inner-margin~ | ~org-ascii-inner-margin~ | -| ~:ascii-links-to-notes~ | ~org-ascii-links-to-notes~ | -| ~:ascii-list-margin~ | ~org-ascii-list-margin~ | -| ~:ascii-paragraph-spacing~ | ~org-ascii-paragraph-spacing~ | -| ~:ascii-quote-margin~ | ~org-ascii-quote-margin~ | -| ~:ascii-table-keep-all-vertical-lines~ | ~org-ascii-table-keep-all-vertical-lines~ | -| ~:ascii-table-use-ascii-art~ | ~org-ascii-table-use-ascii-art~ | -| ~:ascii-table-widen-columns~ | ~org-ascii-table-widen-columns~ | -| ~:ascii-text-width~ | ~org-ascii-text-width~ | -| ~:ascii-underline~ | ~org-ascii-underline~ | -| ~:ascii-verbatim-format~ | ~org-ascii-verbatim-format~ | +#+begin_src emacs-lisp :exports results :results table :eval yes :noweb yes +(require 'ox-ascii) +(let ((alist (org-export-backend-options (org-export-get-backend 'ascii)))) +<> +) +#+end_src **** Beamer specific properties :PROPERTIES: :UNNUMBERED: notoc :END: -| ~:beamer-theme~ | ~org-beamer-theme~ | -| ~:beamer-column-view-format~ | ~org-beamer-column-view-format~ | -| ~:beamer-environments-extra~ | ~org-beamer-environments-extra~ | -| ~:beamer-frame-default-options~ | ~org-beamer-frame-default-options~ | -| ~:beamer-outline-frame-options~ | ~org-beamer-outline-frame-options~ | -| ~:beamer-outline-frame-title~ | ~org-beamer-outline-frame-title~ | -| ~:beamer-subtitle-format~ | ~org-beamer-subtitle-format~ | +#+begin_src emacs-lisp :exports results :results table :eval yes :noweb yes +(require 'ox-beamer) +(let ((alist (org-export-backend-options (org-export-get-backend 'beamer)))) +<> +) +#+end_src **** HTML specific properties :PROPERTIES: :UNNUMBERED: notoc :END: -| ~:html-allow-name-attribute-in-anchors~ | ~org-html-allow-name-attribute-in-anchors~ | -| ~:html-checkbox-type~ | ~org-html-checkbox-type~ | -| ~:html-container~ | ~org-html-container-element~ | -| ~:html-divs~ | ~org-html-divs~ | -| ~:html-doctype~ | ~org-html-doctype~ | -| ~:html-extension~ | ~org-html-extension~ | -| ~:html-footnote-format~ | ~org-html-footnote-format~ | -| ~:html-footnote-separator~ | ~org-html-footnote-separator~ | -| ~:html-footnotes-section~ | ~org-html-footnotes-section~ | -| ~:html-format-drawer-function~ | ~org-html-format-drawer-function~ | -| ~:html-format-headline-function~ | ~org-html-format-headline-function~ | -| ~:html-format-inlinetask-function~ | ~org-html-format-inlinetask-function~ | -| ~:html-head-extra~ | ~org-html-head-extra~ | -| ~:html-head-include-default-style~ | ~org-html-head-include-default-style~ | -| ~:html-head-include-scripts~ | ~org-html-head-include-scripts~ | -| ~:html-head~ | ~org-html-head~ | -| ~:html-home/up-format~ | ~org-html-home/up-format~ | -| ~:html-html5-fancy~ | ~org-html-html5-fancy~ | -| ~:html-indent~ | ~org-html-indent~ | -| ~:html-infojs-options~ | ~org-html-infojs-options~ | -| ~:html-infojs-template~ | ~org-html-infojs-template~ | -| ~:html-inline-image-rules~ | ~org-html-inline-image-rules~ | -| ~:html-inline-images~ | ~org-html-inline-images~ | -| ~:html-link-home~ | ~org-html-link-home~ | -| ~:html-link-org-files-as-html~ | ~org-html-link-org-files-as-html~ | -| ~:html-link-up~ | ~org-html-link-up~ | -| ~:html-link-use-abs-url~ | ~org-html-link-use-abs-url~ | -| ~:html-mathjax-options~ | ~org-html-mathjax-options~ | -| ~:html-mathjax-template~ | ~org-html-mathjax-template~ | -| ~:html-equation-reference-format~ | ~org-html-equation-reference-format~ | -| ~:html-metadata-timestamp-format~ | ~org-html-metadata-timestamp-format~ | -| ~:html-postamble-format~ | ~org-html-postamble-format~ | -| ~:html-postamble~ | ~org-html-postamble~ | -| ~:html-preamble-format~ | ~org-html-preamble-format~ | -| ~:html-preamble~ | ~org-html-preamble~ | -| ~:html-self-link-headlines~ | ~org-html-self-link-headlines~ | -| ~:html-table-align-individual-field~ | ~org-html-table-align-individual-fields~ | -| ~:html-table-attributes~ | ~org-html-table-default-attributes~ | -| ~:html-table-caption-above~ | ~org-html-table-caption-above~ | -| ~:html-table-data-tags~ | ~org-html-table-data-tags~ | -| ~:html-table-header-tags~ | ~org-html-table-header-tags~ | -| ~:html-table-row-tags~ | ~org-html-table-row-tags~ | -| ~:html-table-use-header-tags-for-first-column~ | ~org-html-table-use-header-tags-for-first-column~ | -| ~:html-tag-class-prefix~ | ~org-html-tag-class-prefix~ | -| ~:html-text-markup-alist~ | ~org-html-text-markup-alist~ | -| ~:html-todo-kwd-class-prefix~ | ~org-html-todo-kwd-class-prefix~ | -| ~:html-toplevel-hlevel~ | ~org-html-toplevel-hlevel~ | -| ~:html-use-infojs~ | ~org-html-use-infojs~ | -| ~:html-validation-link~ | ~org-html-validation-link~ | -| ~:html-viewport~ | ~org-html-viewport~ | -| ~:html-wrap-src-lines~ | ~org-html-wrap-src-lines~ | -| ~:html-xml-declaration~ | ~org-html-xml-declaration~ | +#+begin_src emacs-lisp :exports results :results table :eval yes :noweb yes +(require 'ox-html) +(let ((alist (org-export-backend-options (org-export-get-backend 'html)))) +<> +) +#+end_src **** LaTeX specific properties :PROPERTIES: :UNNUMBERED: notoc :END: -| ~:latex-active-timestamp-format~ | ~org-latex-active-timestamp-format~ | -| ~:latex-caption-above~ | ~org-latex-caption-above~ | -| ~:latex-classes~ | ~org-latex-classes~ | -| ~:latex-class~ | ~org-latex-default-class~ | -| ~:latex-compiler~ | ~org-latex-compiler~ | -| ~:latex-default-figure-position~ | ~org-latex-default-figure-position~ | -| ~:latex-default-table-environment~ | ~org-latex-default-table-environment~ | -| ~:latex-default-table-mode~ | ~org-latex-default-table-mode~ | -| ~:latex-diary-timestamp-format~ | ~org-latex-diary-timestamp-format~ | -| ~:latex-engraved-options~ | ~org-latex-engraved-options~ | -| ~:latex-engraved-preamble~ | ~org-latex-engraved-preamble~ | -| ~:latex-engraved-theme~ | ~org-latex-engraved-theme~ | -| ~:latex-footnote-defined-format~ | ~org-latex-footnote-defined-format~ | -| ~:latex-footnote-separator~ | ~org-latex-footnote-separator~ | -| ~:latex-format-drawer-function~ | ~org-latex-format-drawer-function~ | -| ~:latex-format-headline-function~ | ~org-latex-format-headline-function~ | -| ~:latex-format-inlinetask-function~ | ~org-latex-format-inlinetask-function~ | -| ~:latex-hyperref-template~ | ~org-latex-hyperref-template~ | -| ~:latex-image-default-height~ | ~org-latex-image-default-height~ | -| ~:latex-image-default-option~ | ~org-latex-image-default-option~ | -| ~:latex-image-default-width~ | ~org-latex-image-default-width~ | -| ~:latex-images-centered~ | ~org-latex-images-centered~ | -| ~:latex-inactive-timestamp-format~ | ~org-latex-inactive-timestamp-format~ | -| ~:latex-inline-image-rules~ | ~org-latex-inline-image-rules~ | -| ~:latex-link-with-unknown-path-format~ | ~org-latex-link-with-unknown-path-format~ | -| ~:latex-listings-langs~ | ~org-latex-listings-langs~ | -| ~:latex-listings-options~ | ~org-latex-listings-options~ | -| ~:latex-minted-langs~ | ~org-latex-minted-langs~ | -| ~:latex-minted-options~ | ~org-latex-minted-options~ | -| ~:latex-prefer-user-labels~ | ~org-latex-prefer-user-labels~ | -| ~:latex-subtitle-format~ | ~org-latex-subtitle-format~ | -| ~:latex-subtitle-separate~ | ~org-latex-subtitle-separate~ | -| ~:latex-src-block-backend~ | ~org-latex-src-block-backend~ | -| ~:latex-table-scientific-notation~ | ~org-latex-table-scientific-notation~ | -| ~:latex-tables-booktabs~ | ~org-latex-tables-booktabs~ | -| ~:latex-tables-centered~ | ~org-latex-tables-centered~ | -| ~:latex-text-markup-alist~ | ~org-latex-text-markup-alist~ | -| ~:latex-title-command~ | ~org-latex-title-command~ | -| ~:latex-toc-command~ | ~org-latex-toc-command~ | +#+begin_src emacs-lisp :exports results :results table :eval yes :noweb yes +(require 'ox-latex) +(let ((alist (org-export-backend-options (org-export-get-backend 'latex)))) +<> +) +#+end_src **** Markdown specific properties :PROPERTIES: :UNNUMBERED: notoc :END: -| ~:md-footnote-format~ | ~org-md-footnote-format~ | -| ~:md-footnotes-section~ | ~org-md-footnotes-section~ | -| ~:md-headline-style~ | ~org-md-headline-style~ | -| ~:md-toplevel-hlevel~ | ~org-md-toplevel-hlevel~ | +#+begin_src emacs-lisp :exports results :results table :eval yes :noweb yes +(require 'ox-md) +(let ((alist (org-export-backend-options (org-export-get-backend 'md)))) +<> +) +#+end_src **** ODT specific properties :PROPERTIES: :UNNUMBERED: notoc :END: -| ~:odt-content-template-file~ | ~org-odt-content-template-file~ | -| ~:odt-display-outline-level~ | ~org-odt-display-outline-level~ | -| ~:odt-fontify-srcblocks~ | ~org-odt-fontify-srcblocks~ | -| ~:odt-format-drawer-function~ | ~org-odt-format-drawer-function~ | -| ~:odt-format-headline-function~ | ~org-odt-format-headline-function~ | -| ~:odt-format-inlinetask-function~ | ~org-odt-format-inlinetask-function~ | -| ~:odt-inline-formula-rules~ | ~org-odt-inline-formula-rules~ | -| ~:odt-inline-image-rules~ | ~org-odt-inline-image-rules~ | -| ~:odt-pixels-per-inch~ | ~org-odt-pixels-per-inch~ | -| ~:odt-styles-file~ | ~org-odt-styles-file~ | -| ~:odt-table-styles~ | ~org-odt-table-styles~ | -| ~:odt-use-date-fields~ | ~org-odt-use-date-fields~ | +#+begin_src emacs-lisp :exports results :results table :eval yes :noweb yes +(require 'ox-odt) +(let ((alist (org-export-backend-options (org-export-get-backend 'odt)))) +<> +) +#+end_src **** Texinfo specific properties :PROPERTIES: :UNNUMBERED: notoc :END: -| ~:texinfo-active-timestamp-format~ | ~org-texinfo-active-timestamp-format~ | -| ~:texinfo-classes~ | ~org-texinfo-classes~ | -| ~:texinfo-class~ | ~org-texinfo-default-class~ | -| ~:texinfo-compact-itemx | ~org-texinfo-compact-itemx~ | -| ~:texinfo-table-default-markup~ | ~org-texinfo-table-default-markup~ | -| ~:texinfo-diary-timestamp-format~ | ~org-texinfo-diary-timestamp-format~ | -| ~:texinfo-filename~ | ~org-texinfo-filename~ | -| ~:texinfo-format-drawer-function~ | ~org-texinfo-format-drawer-function~ | -| ~:texinfo-format-headline-function~ | ~org-texinfo-format-headline-function~ | -| ~:texinfo-format-inlinetask-function~ | ~org-texinfo-format-inlinetask-function~ | -| ~:texinfo-inactive-timestamp-format~ | ~org-texinfo-inactive-timestamp-format~ | -| ~:texinfo-link-with-unknown-path-format~ | ~org-texinfo-link-with-unknown-path-format~ | -| ~:texinfo-node-description-column~ | ~org-texinfo-node-description-column~ | -| ~:texinfo-table-scientific-notation~ | ~org-texinfo-table-scientific-notation~ | -| ~:texinfo-tables-verbatim~ | ~org-texinfo-tables-verbatim~ | -| ~:texinfo-text-markup-alist~ | ~org-texinfo-text-markup-alist~ | +#+begin_src emacs-lisp :exports results :results table :eval yes :noweb yes +(require 'ox-texinfo) +(let ((alist (org-export-backend-options (org-export-get-backend 'texinfo)))) +<> +) +#+end_src *** Publishing links :PROPERTIES: @@ -16712,6 +17240,7 @@ to HTML, the following links all point to a dedicated anchor in :END: #+cindex: sitemap, of published pages +#+vindex: org-publish-project-alist The following properties may be used to control publishing of a map of files for a given project. @@ -16729,6 +17258,12 @@ a map of files for a given project. Title of sitemap page. Defaults to name of file. +- ~:sitemap-style~ :: + + Can be ~list~ (site-map is just an itemized list of the titles of + the files involved) or ~tree~ (the directory structure of the + source files is reflected in the site-map). Defaults to ~tree~. + - ~:sitemap-format-entry~ :: #+findex: org-publish-find-date @@ -16774,21 +17309,6 @@ a map of files for a given project. Should sorting be case-sensitive? Default ~nil~. -- ~:sitemap-file-entry-format~ :: - - With this option one can tell how a sitemap's entry is formatted in - the sitemap. This is a format string with some escape sequences: - ~%t~ stands for the title of the file, ~%a~ stands for the author of - the file and ~%d~ stands for the date of the file. The date is - retrieved with the ~org-publish-find-date~ function and formatted - with ~org-publish-sitemap-date-format~. Default ~%t~. - -- ~:sitemap-date-format~ :: - - Format string for the ~format-time-string~ function that tells how - a sitemap entry's date is to be formatted. This property bypasses - ~org-publish-sitemap-date-format~ which defaults to ~%Y-%m-%d~. - *** Generating an index :PROPERTIES: :DESCRIPTION: An index that reaches across pages. @@ -16909,12 +17429,12 @@ place on the web server, and publishing images to it. #+begin_src emacs-lisp (setq org-publish-project-alist - '(("orgfiles" + `(("orgfiles" :base-directory "~/org/" :base-extension "org" :publishing-directory "/ssh:user@host:~/html/notebook/" :publishing-function org-html-publish-to-html - :exclude "PrivatePage.org" ;; regexp + :exclude ,(rx (or "PrivateFile.org" (seq line-start "private/"))) ;; regexp :headline-levels 3 :section-numbers nil :with-toc nil @@ -16982,40 +17502,90 @@ keywords. :DESCRIPTION: create, follow and export citations. :END: #+cindex: citation +#+cindex: citation processor -The =oc.el= library provides tooling to handle citations in Org via -"citation processors" that offer some or all of the following -capabilities: +While links (see [[*Hyperlinks]]) are often sufficient to refer to +external or internal information from Org, they have their limitations +when referring to multiple targets or typesetting printed +publications. -- 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. +Org mode provides a more sophisticated markup to "cite" external +resources. For example, consider the following Org mode snippet -To use a "citation processor", the user must load them; for example; +: #+bibliography: citationdata.bib +: +: Org mode is used by various communities [cite:teaching: @orgteaching; +: and TeX: @orgtex]. [cite/author/caps:@orgtex] uses Org mode to simplify +: writing scientific publications, while [cite/author/caps:@orgteaching] +: experiment with Org babel to improve teaching. +: +: #+print_bibliography: -#+begin_src emacs-lisp -(require 'oc-bibtex) -#+end_src +Org mode will gather citation metadata from the =#+bibliography= +database and use it to typeset the exported document in arbitrary +formats. For example, the snippet below shows ASCII export output. -They can then configure them with ~org-cite-activate-processor~, -~org-cite-follow-processor~, ~org-cite-insert-processor~, and -~org-cite-export-processors~ respectively. +: Org mode is used by various communities (teaching: Birkenkrahe, Marcus, +: 2023, and TeX: Somma, Emmanuele F, 2023). Somma, Emmanuele F uses Org +: mode to simplify writing scientific publications, while Birkenkrahe, +: Marcus experiment with Org babel to improve teaching. +: +: Birkenkrahe, Marcus (2023). /Teaching Data Science with Literate +: Programming Tools/, MDPI. +: +: Somma, Emmanuele F (2023). /Simplifying LaTeX with ORG-mode in Emacs/, +: TUGboat volume. + +In addition to export, users can use completion to search and insert +citations from the bibliography (via ~org-cite-insert~). Citations +also act like ordinary links, jumping to the citation metadata when +"following" them using ~org-open-at-point~. + +You can customize every aspect (/capability/) of citation handling +using built-in or external /citation processors/. + +Org mode ships with several built-in citation processors tailored to +work with LaTeX export and BibTeX bibliographies (=bibtex=, +=biblatex=, and =natbib= processors), or with more generic formats +described using [[https://citationstyles.org/][Citation Style +Language]] (=csl= processor). +The default citation processor is =basic= - it works with arbitrary +export formats and recognizes both BibTeX and CSL bibliographies. +More citation processors are distributed as Emacs packages. + +#+vindex: org-cite-activate-processor +#+vindex: org-cite-follow-processor +#+vindex: org-cite-insert-processor +#+vindex: org-cite-export-processor +Multiple citation processors can be mixed to meet your preferences. +Configure ~org-cite-activate-processor~, ~org-cite-follow-processor~, +~org-cite-insert-processor~, and ~org-cite-export-processors~ to +select which processor to use for every citation capability: -The included "basic" processor provides all four 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. ** Citations +#+cindex: bibliography + +#+vindex: org-cite-global-bibliography Before adding citations, first set one-or-more bibliographies, either globally with ~org-cite-global-bibliography~, or locally using one or more "bibliography" keywords. +#+cindex: @samp{BIBLIOGRAPHY}, keyword #+begin_example #+bibliography: SomeFile.bib #+bibliography: /some/other/file.json #+bibliography: "/some/file/with spaces/in its name.bib" #+end_example +Org mode uses all the local and global bibliographies combined to +search for citation keys. + #+kindex: C-c C-x @@ #+findex: org-cite-insert One can then insert and edit citations using ~org-cite-insert~, called @@ -17028,20 +17598,40 @@ identifying a reference in the bibliography. - Each key starts with the character =@=. + : [cite:@key] + - Each key can be qualified by a /prefix/ (e.g.\nbsp{}"see ") and/or a /suffix/ (e.g.\nbsp{}"p.\nbsp{}123"), giving information useful or necessary for the comprehension of the citation but not included in the reference. + : [cite:see @key p. 123] + - 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. + : [cite:@key1;@key2;@key3] + - 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 usually makes sense only for the author-year styles. -: [cite/style:common prefix ;prefix @key suffix; ... ; common suffix] + : [cite/style:common prefix ;prefix @key suffix; ... ; common suffix] + + When =style= is not specified, one of the two default styles are + used + + + either the default style specified in the =CITE_EXPORT= keyword + (see [[*Citation export processors]]) + + : #+cite_export: basic numeric noauthor/bare + : [cite:@key] is the same as [cite/noauthor/bare:@key] + + + or, if =CITE_EXPORT= is not set, using the default =nil= style + + : [cite:@key] is the same as [cite/nil:@key] + The only mandatory elements are: @@ -17060,8 +17650,10 @@ Org currently includes the following export processors: 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]]; + - 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, three other processors target LaTeX and LaTeX-derived formats exclusively: @@ -17069,7 +17661,7 @@ Org currently includes the following export processors: - bibtex :: 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 only supports LaTeX's + large number of publishers' styles). It only supports LaTeX's =\cite= and =\nocite= commands. - natbib :: as with the bibtex processor, but using the LaTeX @@ -17081,20 +17673,22 @@ Org currently includes the following export processors: with LaTeX, which overcomes some serious BibTeX limitations, but has not (yet?)\nbsp{}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) +#+cindex: @samp{CITE_EXPORT}, keyword +The =CITE_EXPORT= keyword specifies the export processor, citation +style, and bibliography style; for example (all arguments are +optional) -: #+cite_export: basic author author-year +: #+cite_export: [export processor name] [bibliography style] [default citation style] +: #+cite_export: basic author-year author #+texinfo: @noindent -specifies the "basic" export processor with citations inserted as +specifies the =basic= export processor with citations inserted as author's name and references indexed by author's names and year; : #+cite_export: csl /some/path/to/vancouver-brackets.csl #+texinfo: @noindent -specifies the "csl" processor and CSL style, which in this case +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; @@ -17107,16 +17701,33 @@ 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. +: #+cite_export: biblatex numeric,backend=bibtex + +#+vindex: org-cite-biblatex-options +#+texinfo: @noindent +specifies the =biblatex= export processor with the default =numeric= +style and the =bibtex= backend. Always define the style first and then +the rest of load-time options for the =biblatex= +package. Alternatively, you can use the ~key=val,key=val~ format for +the options as documented in the =biblatex= package documentation: + +: #+cite_export: biblatex backend=bibtex,style=numeric + +The ~org-cite-biblatex-options~ variable in your Emacs configuration +uses this format. It will only export to PDF, since it relies on the +~biblatex~ processor of your LaTeX installation. + ** Bibliography printing +#+cindex: @samp{PRINT_BIBLIOGRAPHY}, keyword The =PRINT_BIBLIOGRAPHY= keyword specifies where the bibliography should be printed (note the colon): : #+print_bibliography: The bibliography printed by the LaTeX-based export processors -"bibtex", "natbib" and "biblatex" has a chapter or section heading by -default, while the "basic" and "csl" processors print the list of +=bibtex=, =natbib= and =biblatex= has a chapter or section heading by +default, while the =basic= and =csl= processors print the list of bibliography entries without a heading. A document may contain more than one =PRINT_BIBLIOGRAPHY= keywords. @@ -17129,23 +17740,24 @@ certain category or to control formatting. The set of supported the different citation export processors. Some export processors do not support passing options. -*** Bibliography options in the "biblatex" and "csl" export processors +*** Bibliography options in the =biblatex= and =csl= export processors -The "biblatex" and "csl" export processors support bibliography +The =biblatex= and =csl= export processors support bibliography options through a property list attached to the =PRINT_BIBLIOGRAPHY= keyword. For example, -: #print_bibliography: :keyword algebra :type book +: #+print_bibliography: :keyword algebra :type book Values including spaces must be surrounded with double quotes. If you need to use a key multiple times, you can separate its values with commas, but without any space in-between: -: #print_bibliography: :keyword "algebraic logic" :nottype article,book +: #+print_bibliography: :keyword "algebraic logic" :nottype article,book + +The =biblatex= export processor accepts all options supported by +BibLaTeX's ~\printbibliography~ command. -The "biblatex" export processor accepts all options supported by -BibLaTeX's ~\printbibliography~ command, while the "csl" processor -accepts the following ones: +The =csl= processor accepts the following options: - =:keyword = :: Print only entries whose keyword field contains all given keywords. @@ -17231,7 +17843,7 @@ Org can extract one or more source code blocks and write them to one or more source files---a process known as /tangling/ in literate programming terminology. -For exporting and publishing, Org's back-ends can format a source code +For exporting and publishing, Org's backends can format a source code block appropriately, often with native syntax highlighting. For executing and compiling a source code block, the user can @@ -17306,7 +17918,8 @@ or from table formulas (see [[*The Spreadsheet]]) can use the name to reference a source block. This naming serves the same purpose as naming Org tables. Org mode requires unique names. For duplicate - names, Org mode's behavior is undefined. + names, Org mode's behavior is undefined. Inline code blocks cannot + have a name. - =#+BEGIN_SRC= ... =#+END_SRC= :: @@ -17317,9 +17930,16 @@ or - == :: #+cindex: language, in code blocks - Mandatory. It is the identifier of the source code language in the + Optional. It is the identifier of the source code language in the block. See [[*Languages]], for identifiers of supported languages. + When == identifier is omitted, the block also cannot + have == and =
=. + + Language identifier is also used to fontify code blocks in Org + buffers, when ~org-src-fontify-natively~ is set to non-~nil~. See + [[*Editing Source Code]]. + - == :: #+cindex: switches, in code blocks @@ -17591,6 +18211,10 @@ from the reference. : :var NAME=FILE:REFERENCE +When =FILE= does not exist, the reference is searched in the current +file, using the verbatim reference. This way, +=:var table=tbl:example= will be searched inside the current buffer. + Here are examples of passing values by reference: - table :: @@ -17623,10 +18247,12 @@ Here are examples of passing values by reference: names---because the second row is a horizontal rule---then Org removes the column names, processes the table, puts back the column names, and then writes the table to the results block. Using =yes=, - Org does the same to the first row, even if the initial table does - not contain any horizontal rule. When set to =no=, Org does not - pre-process column names at all. + Org does the same to the first non-hline row, even if the initial + table does not contain any horizontal rule. When set to =no=, Org + does not pre-process column names at all. + # We keep python blocks unindented on purpose - to keep the example + # working even for users who changed the default value of ~org-src-preserve-indentation~ #+begin_example ,#+NAME: less-cols | a | @@ -17635,7 +18261,7 @@ Here are examples of passing values by reference: | c | ,#+BEGIN_SRC python :var tab=less-cols :colnames nil - return [[val + '*' for val in row] for row in tab] + return [[val + '*' for val in row] for row in tab] ,#+END_SRC ,#+RESULTS: @@ -17660,7 +18286,7 @@ Here are examples of passing values by reference: | two | 6 | 7 | 8 | 9 | 10 | ,#+BEGIN_SRC python :var tab=with-rownames :rownames yes - return [[val + 10 for val in row] for row in tab] + return [[val + 10 for val in row] for row in tab] ,#+END_SRC ,#+RESULTS: @@ -17711,6 +18337,7 @@ a colon, for example: =:var table=other-file.org:example-table=. A code block name, as assigned by =NAME= keyword, followed by parentheses and optional arguments passed within the parentheses. + The block is evaluated with point at its location. #+begin_example ,#+NAME: double @@ -18029,7 +18656,7 @@ 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:48] from an Org mode buffer or +By calling a named code block[fn:49] 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]]). @@ -18237,7 +18864,7 @@ they are mutually exclusive. - =value= :: - Default for most Babel libraries[fn:48]. Functional mode. Org + Default for most Babel libraries[fn:49]. 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 @@ -18290,6 +18917,8 @@ described in the documentation for individual languages. See those =hline= symbols raise unbound variable errors. A =yes= accepts such lines, as demonstrated in the following example. + # We keep python blocks unindented on purpose - to keep the example + # working even for users who changed the default value of ~org-src-preserve-indentation~ #+begin_example ,#+NAME: many-cols | a | b | c | @@ -18300,7 +18929,7 @@ described in the documentation for individual languages. See ,#+NAME: no-hline ,#+BEGIN_SRC python :var tab=many-cols :hlines no - return tab + return tab ,#+END_SRC ,#+RESULTS: no-hline @@ -18310,7 +18939,7 @@ described in the documentation for individual languages. See ,#+NAME: hlines ,#+BEGIN_SRC python :var tab=many-cols :hlines yes - return tab + return tab ,#+END_SRC ,#+RESULTS: hlines @@ -18357,6 +18986,9 @@ described in the documentation for individual languages. See from the =file-ext= header argument. In that case, both the name and the extension are mandatory. + Result can also be interpreted as path to file. See =:results + link=. + #+begin_example ,#+name: circle ,#+BEGIN_SRC asymptote :results value file :file-ext pdf @@ -18399,6 +19031,11 @@ Choose one of the options; they are mutually exclusive. The default follows from the type specified above. #+attr_texinfo: :sep , +- =raw= :: + + Interpreted as raw Org mode. Inserted directly into the buffer. + Aligned if it is a table. Usage example: =:results value raw=. + - =code= :: Result enclosed in a code block. Useful for parsing. Usage @@ -18406,8 +19043,9 @@ follows from the type specified above. - =drawer= :: - Result wrapped in a =RESULTS= drawer. Useful for containing =raw= - or =org= results for later scripting and automated processing. + Results are added directly to the Org file as with =raw=, but are + wrapped in a =RESULTS= drawer or results macro (for inline code + blocks), for later scripting and automated processing. Usage example: =:results value drawer=. - =html= :: @@ -18437,6 +19075,9 @@ follows from the type specified above. [[file:org-mode-unicorn.svg]] #+end_example + If =:file= header argument is omitted, interpret source block result + as the file path. + - =org= :: Results enclosed in a =BEGIN_SRC org= block. For comma-escape, @@ -18449,10 +19090,6 @@ follows from the type specified above. block. Languages supported: Emacs Lisp, Python, and Ruby. Usage example: =:results value pp=. -- =raw= :: - - Interpreted as raw Org mode. Inserted directly into the buffer. - Aligned if it is a table. Usage example: =:results value raw=. #+cindex: @samp{wrap}, header argument The =wrap= header argument unconditionally marks the results block by @@ -18503,7 +19140,7 @@ options; they are mutually exclusive. but no processing is performed on the return value. Calling the code block programmatically (see [[*How to evaluate source code]]) or by reference (see [[*Passing arguments]] and [[*Noweb Reference Syntax]]) will - always yield nil. + always yield ~nil~. - =append= :: @@ -18788,10 +19425,10 @@ the tangled file's executable permission. The =tangle-mode= header argument specifies what permissions to set for tangled files by ~set-file-modes~. Permissions are given by an octal value, which can be provided calling the ~identity~ function on -an elisp octal value. For instance, to create a read-only file one may -use =:tangle-mode (identity #o444)=. To reduce the verbosity required, -a octal shorthand is defined, =oXXX= (=o= for octal). Using this, our -read-only example is =:tangle-mode o444=. Omitting the =o= prefix will +an elisp octal value. For instance, to create a read-only file one may +use =:tangle-mode (identity #o444)=. To reduce the verbosity required, +a octal shorthand is defined, =oXXX= (=o= for octal). Using this, our +read-only example is =:tangle-mode o444=. Omitting the =o= prefix will cause the argument to be interpreted as an integer, which can lead to unexpected results (=444= is the same as =o674=). Two other shorthands are recognized, ls-style strings like @@ -18800,7 +19437,7 @@ Note that chmod-style permissions are based on ~org-babel-tangle-default-file-mode~, which is =#o544= by default. When =:tangle-mode= and =:shebang= are both specified, the give -=:tangle-mode= will override the permissions from =:shebang=. When +=:tangle-mode= will override the permissions from =:shebang=. When multiple source code blocks tangle to a single file with conflicting =:tangle-mode= header arguments, Org's behavior is undefined. @@ -18950,6 +19587,9 @@ group ~org-edit-structure~. header line, then the edit buffer uses that major mode. Use this variable to arbitrarily map language identifiers to major modes. + When language identifier is omitted in the src block, Org mode's + behavior is undefined. + - ~org-src-window-setup~ :: #+vindex: org-src-window-setup @@ -18975,10 +19615,13 @@ group ~org-edit-structure~. #+vindex: org-src-fontify-natively #+vindex: org-src-block-faces -Set ~org-src-fontify-natively~ to non-~nil~ to turn on native code -fontification in the /Org/ buffer. Fontification of code blocks can -give visual separation of text and code on the display page. To -further customize the appearance of ~org-block~ for specific +Fontification of code blocks can give visual separation of text and +code on the display page. Set ~org-src-fontify-natively~ to non-~nil~ +to turn on native code fontification in the /Org/ buffer. The +fontification follows the major mode used to edit the code block (see +~org-src-lang-modes~ above). + +To further customize the appearance of ~org-block~ for specific languages, customize ~org-src-block-faces~. The following example shades the background of regular blocks, and colors source blocks only for Python and Emacs Lisp languages. @@ -19084,6 +19727,9 @@ the second code block is expanded as ,#+END_SRC #+end_example +Note that noweb expansion does not automatically carry over =:var= +header arguments[fn:50]. + You may also include the contents of multiple blocks sharing a common =noweb-ref= header argument, which can be set at the file, subtree, or code block level. In the example Org file shown next, the body of @@ -19120,9 +19766,10 @@ By default a newline separates each noweb reference concatenation. To use a different separator, edit the =noweb-sep= header argument. Alternatively, Org can include the results of evaluation of a single -code block rather than its body. Evaluation occurs when parentheses, -possibly including arguments, are appended to the code block name, as -shown below. +code block rather than its body [[fn::The reference is evaluated with +point at the referenced block, using its header arguments (including +inherited)]. Evaluation occurs when parentheses, possibly including +arguments, are appended to the code block name, as shown below. : <> @@ -19134,10 +19781,12 @@ Here is an example that demonstrates how the exported content changes when noweb style references are used with parentheses versus without. Given: +# We keep python blocks unindented on purpose - to keep the example +# working even for users who changed the default value of ~org-src-preserve-indentation~ #+begin_example ,#+NAME: some-code ,#+BEGIN_SRC python :var num=0 :results output :exports none - print(num*10) +print(num*10) ,#+END_SRC #+end_example @@ -19209,15 +19858,17 @@ newlines in them, inline noweb references are acceptable. This feature can also be used for management of indentation in exported code snippets. With: +# We keep python blocks unindented on purpose - to keep the example +# working even for users who changed the default value of ~org-src-preserve-indentation~ #+begin_example ,#+NAME: if-true ,#+BEGIN_SRC python :exports none - print('do things when true') +print('do things when true') ,#+end_src ,#+name: if-false ,#+begin_src python :exports none - print('do things when false') +print('do things when false') ,#+end_src #+end_example @@ -19226,10 +19877,10 @@ this code block: #+begin_example ,#+begin_src python :noweb yes :results output - if true: - <> - else: - <> +if true: + <> +else: + <> ,#+end_src #+end_example @@ -19619,7 +20270,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:49]. +the headline text[fn:51]. #+vindex: org-indent-indentation-per-level To make more horizontal space, the headlines are shifted by two @@ -19647,7 +20298,7 @@ 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:50]. With Org's support, you have to indent all lines to +Emacs[fn:52]. With Org's support, you have to indent all lines to line up with the outline headers. You would use these settings[fn:: ~org-adapt-indentation~ can also be set to ='headline-data=, in which case only data lines below the headline will be indented.]: @@ -19890,15 +20541,18 @@ changes. #+cindex: @samp{SETUPFILE}, keyword The setup file or a URL pointing to such file is for additional in-buffer settings. Org loads this file and parses it for any - settings in it only when Org opens the main file. If URL is + settings in it when Org opens the main file. If URL is specified, the contents are downloaded and stored in a temporary - file cache. {{{kbd(C-c C-c)}}} on the settings line parses and - loads the file, and also resets the temporary file cache. Org also - parses and loads the document during normal exporting process. Org - parses the contents of this document as if it was included in the - buffer. It can be another Org file. To visit the file---not - a URL---use {{{kbd(C-c ')}}} while point is on the line with the - file name. + file cache. {{{kbd(C-c C-c)}}} on the settings line re-parses and + re-loads the file, and also resets the temporary file cache. + + Org also parses and loads /in-buffer settings/ from the setup file + during normal exporting process. Org parses the /in-buffer + settings/ as if it was included in the containing Org buffer. The + rest of the contents of setup file is ignored. + + To visit the setup file---not a URL---use {{{kbd(C-c ')}}} while point + is on the line with the setup file name. - =#+STARTUP:= :: @@ -19959,6 +20613,17 @@ changes. | =inlineimages= | Show inline images. | | =noinlineimages= | Do not show inline images on startup. | + #+vindex: org-link-descriptive + Bracket links in Org buffers are displayed hiding the link path and + brackets. For example, =[[https://orgmode.org][Org Website]]= is, + by default, displayed as "Org Website", hiding the link itself and + just displaying its description. Alternatively, the links can be + displayed in full. The corresponding variable is + ~org-link-descriptive~. + + | =descriptivelinks= | Hide path and brackets in links. | + | =literallinks= | Do not hide anything. | + #+vindex: org-log-done #+vindex: org-log-note-clock-out #+vindex: org-log-repeat @@ -19999,11 +20664,12 @@ changes. | =odd= | Allow only odd outline levels (1, 3, ...). | | =oddeven= | Allow all outline levels. | - #+vindex: org-put-time-stamp-overlays - #+vindex: org-time-stamp-overlay-formats + #+vindex: org-display-custom-times + #+vindex: org-timestamp-custom-formats + #+vindex: org-time-stamp-custom-formats To turn on custom format overlays over timestamps (variables - ~org-put-time-stamp-overlays~ and - ~org-time-stamp-overlay-formats~), use: + ~org-display-custom-times~ and + ~org-timestamp-custom-formats~), use: | =customtime= | Overlay custom time format. | @@ -20029,6 +20695,7 @@ changes. | =fnconfirm= | Offer automatic label for editing or confirmation. | | =fnadjust= | Automatically renumber and sort footnotes. | | =nofnadjust= | Do not renumber and sort automatically. | + | =fnanon= | Create anonymous footnotes with ~org-footnote-new~. | #+vindex: org-hide-block-startup #+vindex: org-hide-drawer-startup @@ -20088,8 +20755,8 @@ For more information, see [[info:emacs::Regexps][Regular Expressions in Emacs]]. :END: A reference document providing a formal description of Org's syntax is -available as [[https://orgmode.org/worg/dev/org-syntax.html][a draft on Worg]], written and maintained by Nicolas -Goaziou. It defines Org's core internal concepts such as "headlines", +available as [[https://orgmode.org/worg/org-syntax.html][a draft on Worg]], initially written by Nicolas Goaziou. +It defines Org's core internal concepts such as "headlines", "sections", "affiliated keywords", "(greater) elements" and "objects". Each part of an Org document belongs to one of the previous categories. @@ -20266,12 +20933,12 @@ packages are documented here. #+vindex: org-table-formula-constants Org can use names for constants in formulas in tables. Org can also - use calculation suffixes for units, such as =M= for =Mega=. For - a standard collection of such constants, install the =constants= + use calculation suffixes for units, such as =M= for =Mega=. For a + standard collection of such constants, install the =constants= package. Install version 2.0 of this package, available at - [[http://www.astro.uva.nl/~dominik/Tools]]. Org checks if the function - ~constants-get~ has been autoloaded. Installation instructions are - in the file =constants.el=. + [[https://github.com/cdominik/constants-for-Emacs]]. Org checks if the + function ~constants-get~ has been autoloaded. Installation + instructions are in the file =constants.el=. - =cdlatex.el= by Carsten Dominik :: #+cindex: @file{cdlatex.el} @@ -20295,6 +20962,10 @@ packages are documented here. By default the index is two levels deep---you can modify the depth using the option ~org-imenu-depth~. + Org activates Imenu support only in the buffers opened after loading + Imenu library. To enable Imenu support in an already opened Org + buffer, reload Org. + - =speedbar.el= by Eric\nbsp{}M.\nbsp{}Ludlam :: #+cindex: @file{speedbar.el} @@ -20496,6 +21167,7 @@ further based on their usage needs. For example, the normal | {{{kbd(S-DOWN)}}} | {{{kbd(C-c DOWN)}}} | | | | {{{kbd(C-S-LEFT)}}} | {{{kbd(C-c C-x LEFT)}}} | | | | {{{kbd(C-S-RIGHT)}}} | {{{kbd(C-c C-x RIGHT)}}} | | | +| {{{kbd(C-c C-\,)}}} | {{{kbd(C-c C-x s)}}} | | | ** Protocols for External Access :PROPERTIES: @@ -20693,8 +21365,8 @@ adding ~:rewrites~ rules like this: #+texinfo: @noindent Since =example.com/$= is used as a regular expression, it maps -=http://example.com/=, =https://example.com=, -=http://www.example.com/= and similar to +=https://example.com/=, =https://example.com=, +=https://www.example.com/= and similar to =/home/user/example/index.php=. The ~:rewrites~ rules are searched as a last resort if and only if no @@ -20754,8 +21426,8 @@ specifying the respective key as property =CRYPTKEY=, e.g.: :END: #+end_example -Note that =CRYPTKEY= property is only effective when ~org-crypt-key~ -is set to non-nil. ~nil~ value of ~org-crypt-key~ makes Org use +Note that the =CRYPTKEY= property is only effective when +~org-crypt-key~ is non-~nil~. If ~org-crypt-key~ is ~nil~, Org uses symmetric encryption unconditionally. Excluding the =crypt= tag from inheritance prevents already encrypted @@ -20793,7 +21465,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:51] to interact with Emacs. Pass its location through +a server[fn:53] 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: @@ -20837,7 +21509,7 @@ Symbolic links in ~org-directory~ need to have the same name as their targets.]. Push creates a special Org file =agendas.org= with custom agenda views -defined by the user[fn:52]. +defined by the user[fn:54]. Finally, Org writes the file =index.org=, containing links to other files. The mobile application reads this file first from the server @@ -20898,6 +21570,51 @@ most recent since the mobile application searches files that were last pulled. To get an updated agenda view with changes since the last pull, pull again. +** Drag and Drop & ~yank-media~ +:PROPERTIES: +:DESCRIPTION: Dropping and pasting files and images +:END: + +#+cindex: dropping files +#+cindex: dragging files +#+cindex: drag and drop +#+cindex: dnd +#+vindex: org-yank-dnd-method +Org mode supports drag and drop (DnD) of files. By default, Org asks +the user what must be done with the dropped file: attach it, insert +=file:= link, or open the file. Customize ~org-yank-dnd-method~ to +set the default DnD action. + +When DnD method is "attach", Org mode first consults DnD metadata to +decide the attach method. For example, when file/files are dragged +from a file manager, Org may attach by copying or by moving. + +#+vindex: org-yank-dnd-default-attach-method +If Org cannot figure out which attachment method to use from the +metadata, it defaults to ~org-yank-dnd-default-attach-method~ [fn::By +default, ~org-yank-dnd-default-attach-method~ is set to nil -- use the same +value as ~org-attach-method~ (~cp~ by default).] + +#+cindex: pasting files, images from clipboard +Starting from Emacs 29, Org mode supports ~yank-media~ command to yank +images from the clipboard and files from a file manager. + +#+vindex: org-yank-image-save-method +When yanking images from clipboard, Org saves the image on disk and +inserts the image link to Org buffer. Images are either saved as +attachments to heading (default) or to a globally defined directory. +The save location is controlled by ~org-yank-image-save-method~. + +#+vindex: org-yank-image-file-name-function +The yanked images are saved under automatically generated name. You +can customize ~org-yank-image-file-name-function~ to make Org query +the image names or change the naming scheme. + +When yanking files copied from a file manager, Org respects the value +of ~org-yank-dnd-method~. Image files pasted this way also respect +the value of ~org-yank-image-save-method~ when the action to perform +is =attach=. + * Hacking :PROPERTIES: :DESCRIPTION: How to hack your way around. @@ -20914,10 +21631,9 @@ of Org. :END: #+cindex: hooks -Org has a large number of hook variables for adding functionality. -This appendix illustrates using a few. A complete list of hooks with -documentation is maintained by the Worg project at -https://orgmode.org/worg/doc.html#hooks. +Org has a large number of hook variables for adding functionality. A +complete list of hooks with documentation is maintained by the Worg +project at https://orgmode.org/worg/doc.html#hooks. ** Add-on Packages :PROPERTIES: @@ -20965,7 +21681,7 @@ The following =ol-man.el= file implements it PATH should be a topic that can be thrown at the man command." (funcall org-man-command path)) -(defun org-man-store-link () +(defun org-man-store-link (&optional _interactive?) "Store a link to a man page." (when (memq major-mode '(Man-mode woman-mode)) ;; This is a man page, we do make this link. @@ -21025,41 +21741,43 @@ A review of =ol-man.el=: For example, ~org-man-store-link~ is responsible for storing a link when ~org-store-link~ (see [[*Handling Links]]) is called from a buffer - displaying a man page. It first checks if the major mode is - appropriate. If check fails, the function returns ~nil~, which - means it isn't responsible for creating a link to the current - buffer. Otherwise the function makes a link string by combining - the =man:= prefix with the man topic. It also provides a default - description. The function ~org-insert-link~ can insert it back - into an Org buffer later on. + displaying a man page. It is passed an argument ~interactive?~ + which this function does not use, but other store functions use to + behave differently when a link is stored interactively by the user. + It first checks if the major mode is appropriate. If check fails, + the function returns ~nil~, which means it isn't responsible for + creating a link to the current buffer. Otherwise the function + makes a link string by combining the =man:= prefix with the man + topic. It also provides a default description. The function + ~org-insert-link~ can insert it back into an Org buffer later on. -** Adding Export Back-ends +** Adding Export Backends :PROPERTIES: -:DESCRIPTION: How to write new export back-ends. +:DESCRIPTION: How to write new export backends. :END: -#+cindex: Export, writing back-ends +#+cindex: Export, writing backends -Org's export engine makes it easy for writing new back-ends. The +Org's export engine makes it easy for writing new backends. The framework on which the engine was built makes it easy to derive new -back-ends from existing ones. +backends from existing ones. #+findex: org-export-define-backend #+findex: org-export-define-derived-backend The two main entry points to the export engine are: ~org-export-define-backend~ and ~org-export-define-derived-backend~. To grok these functions, see =ox-latex.el= for an example of defining -a new back-end from scratch, and =ox-beamer.el= for an example of +a new backend from scratch, and =ox-beamer.el= for an example of deriving from an existing engine. -For creating a new back-end from scratch, first set its name as +For creating a new backend from scratch, first set its name as a symbol in an alist consisting of elements and export functions. To -make the back-end visible to the export dispatcher, set ~:menu-entry~ -keyword. For export options specific to this back-end, set the +make the backend visible to the export dispatcher, set ~:menu-entry~ +keyword. For export options specific to this backend, set the ~:options-alist~. -For creating a new back-end from an existing one, set +For creating a new backend from an existing one, set ~:translate-alist~ to an alist of export functions. This alist -replaces the parent back-end functions. +replaces the parent backend functions. For complete documentation, see [[https://orgmode.org/worg/dev/org-export-reference.html][the Org Export Reference on Worg]]. @@ -21157,7 +21875,7 @@ of these strategies: To wrap a source table in LaTeX, use the =comment= environment provided by =comment.sty=[fn:: https://www.ctan.org/pkg/comment]. To activate it, put ~\usepackage{comment}~ in the document header. -Orgtbl mode inserts a radio table skeleton[fn:53] with the command +Orgtbl mode inserts a radio table skeleton[fn:55] 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: @@ -21177,7 +21895,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:54]: +features[fn:56]: #+begin_example % BEGIN RECEIVE ORGTBL salesfigures @@ -21269,7 +21987,7 @@ Orgtbl mode has built-in translator functions: ~orgtbl-to-csv~ ~orgtbl-to-latex~, ~orgtbl-to-html~, ~orgtbl-to-texinfo~, ~orgtbl-to-unicode~ and ~orgtbl-to-orgtbl~. They use the generic translator, ~orgtbl-to-generic~, which delegates translations to -various export back-ends. +various export backends. Properties passed to the function through the =ORGTBL SEND= line take precedence over properties defined inside the function. For example, @@ -21396,7 +22114,7 @@ Org provides a special hook to further limit items in agenda views: ~agenda~, ~agenda*~[fn:: 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.], ~todo~, ~alltodo~, ~tags~, ~tags-todo~, ~tags-tree~. +timestamps.], ~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. @@ -21538,15 +22256,13 @@ number. Here are tips to speed up: #+end_src #+vindex: org-agenda-ignore-properties -- Disable parsing of some drawer properties: +- Disable parsing of some properties: #+begin_src emacs-lisp - (setq org-agenda-ignore-properties '(effort appt stats category)) + (setq org-agenda-ignore-properties '(stats)) #+end_src - The drawer properties you can disable in the agenda are effort - estimates (~effort~), appointments (~appt~), statistics (~stats~) - and subtree-local categories (~category~). + This will disable parsing and updating statistic cookies. These options can be applied to selected agenda views. For more details about generation of agenda views, see the docstrings for the @@ -21713,7 +22429,7 @@ Get all property keys in the current buffer. #+attr_texinfo: :options org-insert-property-drawer #+begin_defun -Insert a property drawer for the current entry. Also +Insert a property drawer for the current entry. #+end_defun #+attr_texinfo: :options org-entry-put-multivalued-property pom property &rest values @@ -22315,7 +23031,7 @@ that are mentioned in the manual. For a more complete list, use This manual is for Org version {{{version}}}. -Copyright \copy 2004--2023 Free Software Foundation, Inc. +Copyright \copy 2004--2024 Free Software Foundation, Inc. #+begin_quote Permission is granted to copy, distribute and/or modify this document @@ -22336,7 +23052,7 @@ modify this GNU manual." #+export_file_name: org.texi #+texinfo_dir_category: Emacs editing modes -#+texinfo_dir_title: Org Mode: (org) +#+texinfo_dir_name: Org Mode: (org) #+texinfo_dir_desc: Outline-based notes management and organizer * Footnotes @@ -22416,20 +23132,20 @@ from the list of stored links. To keep it in the list for later use, use a triple {{{kbd(C-u)}}} prefix argument to {{{kbd(C-c C-l)}}}, or configure the option ~org-link-keep-stored-after-insertion~. -[fn:15] Check also the variable ~org-fast-tag-selection-include-todo~, -it allows you to change the TODO state through the tags interface (see -[[*Setting Tags]]), in case you like to mingle the two concepts. Note -that this means you need to come up with unique keys across both sets -of keywords. - -[fn:16] It is possible that Org mode records two timestamps when you +[fn:15] It is possible that Org mode records two timestamps when you are using both ~org-log-done~ and state change logging. However, it never prompts for two notes: if you have configured both, the state change recording note takes precedence and cancel the closing note. -[fn:17] With the exception of description lists. But you can allow it +[fn:16] With the exception of description lists. But you can allow it by modifying ~org-list-automatic-rules~ accordingly. +[fn:17] For both =TIMESTAMP= and =TIMESTAMP_IA=: the word "first" +refers to the first occurrence in the entry, not the earliest in time; +the prefix =CLOCK:= at the beginning of a clock entry is considered a +keyword in this context; and timestamps inside property drawers are +ignored. + [fn:18] An age can be defined as a duration, using units defined in ~org-duration-units~, e.g., =3d 1h=. If any value in the column is as such, the summary is also expressed as a duration. @@ -22447,7 +23163,7 @@ specify a date December 1, 2005, the call might look like =(diary-date 12 1 2005)= or =(diary-date 1 12 2005)= or =(diary-date 2005 12 1)=, depending on the settings. This has been the source of much confusion. Org mode users can resort to special versions of -these functions, namely ~org-date~, ~org-anniversary~, ~org-cyclic, and +these functions, namely ~org-date~, ~org-anniversary~, ~org-cyclic~, and ~org-block~. These work just like the corresponding ~diary-~ functions, but with stable ISO order of arguments (year, month, day) wherever applicable, independent of the value of @@ -22481,21 +23197,24 @@ With =lognoterepeat=, you will also be prompted for a note. than 30 stars. This is a hard-coded limitation of ~lmax~ in ~org-clock-sum~. -[fn:28] On computers using macOS, idleness is based on actual user -idleness, not just Emacs' idle time. For X11, you can install a +[fn:28] When using ~:step~, ~untilnow~ starts from the beginning of +2003, not the beginning of time. + +[fn:29] On computers using macOS, idleness is based on actual user +idleness, not just Emacs's 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:29] Org used to offer four different targets for date/week tree +[fn:30] Org used to offer four different targets for date/week tree capture. Now, Org automatically translates these to use ~file+olp+datetree~, applying the ~:time-prompt~ and ~:tree-type~ properties. Please rewrite your date/week-tree targets using ~file+olp+datetree~ since the older targets are now deprecated. -[fn:30] A date tree is an outline structure with years on the highest +[fn:31] A date tree is an outline structure with years on the highest level, months or ISO weeks as sublevels and then dates on the lowest level. @@ -22506,17 +23225,18 @@ level. ,*** 2022-10-08 Saturday #+end_example -Tags are allowed in the tree structure. +TODO state, priority, tags, statistics cookies, and COMMENT keywords +are allowed in the tree structure. -[fn:31] This is always the other, not the user. See the variable +[fn:32] This is always the other, not the user. See the variable ~org-link-from-user-regexp~. -[fn:32] For backward compatibility, the universal prefix argument +[fn:33] For backward compatibility, the universal prefix argument {{{kbd(C-u)}}} causes all TODO entries to be listed before the agenda. This feature is deprecated, use the dedicated TODO list, or a block agenda instead (see [[*Block agenda]]). -[fn:33] Custom agenda commands can preset a filter by binding one of +[fn:34] Custom agenda commands can preset a filter by binding one of the variables ~org-agenda-tag-filter-preset~, ~org-agenda-category-filter-preset~, ~org-agenda-effort-filter-preset~ or ~org-agenda-regexp-filter-preset~ as an option. This filter is @@ -22526,94 +23246,122 @@ property of the entire agenda view---in a block agenda, you should only set this in the global options section, not in the section of an individual block. -[fn:34] /Planned/ means here that these entries have some planning -information attached to them, like a time-stamp, a scheduled or +[fn:35] /Planned/ means here that these entries have some planning +information attached to them, like a timestamp, a scheduled or a deadline string. See ~org-agenda-entry-types~ on how to set what planning information is taken into account. -[fn:35] To create PDF output, the Ghostscript ps2pdf utility must be +[fn:36] To create PDF output, the Ghostscript ps2pdf utility must be installed on the system. Selecting a PDF file also creates the postscript file. -[fn:36] LaTeX is a macro system based on Donald\nbsp{}E.\nbsp{}Knuth's TeX +[fn:37] LaTeX is a macro system based on Donald\nbsp{}E.\nbsp{}Knuth's TeX system. Many of the features described here as "LaTeX" are really from TeX, but for simplicity I am blurring this distinction. -[fn:37] When MathJax is used, only the environments recognized by +[fn:38] When MathJax is used, only the environments recognized by MathJax are processed. When dvipng, dvisvgm, or ImageMagick suite is used to create images, any LaTeX environment is handled. -[fn:38] These are respectively available at +[fn:39] These are respectively available at [[https://sourceforge.net/projects/dvipng/]], [[http://dvisvgm.bplaced.net/]] and from the ImageMagick suite. Choose the converter by setting the variable ~org-preview-latex-default-process~ accordingly. -[fn:39] This works automatically for the HTML backend (it requires +[fn:40] This works automatically for the HTML backend (it requires 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]] LaTeX package, [[https://www.ctan.org/pkg/minted][minted]] LaTeX package, or by using [[https://elpa.gnu.org/packages/engrave-faces.html][engrave-faces]] . Refer to ~org-latex-src-block-backend~ for details. -[fn:40] Source code in code blocks may also be evaluated either +[fn:41] Source code in code blocks may also be evaluated either interactively or on export. See [[*Working with Source Code]] for more information on evaluating code blocks. -[fn:41] For export to LaTeX format---or LaTeX-related formats such as +[fn:42] 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:42] At the moment, some export back-ends do not obey this +[fn:43] At the moment, some export backends do not obey this specification. For example, LaTeX export excludes every unnumbered headline from the table of contents. -[fn:43] Note that ~org-link-search-must-match-exact-headline~ is +[fn:44] Note that ~org-link-search-must-match-exact-headline~ is locally bound to non-~nil~. Therefore, ~org-link-search~ only matches headlines and named elements. -[fn:44] Since commas separate the arguments, commas within arguments +[fn:45] Since commas separate the arguments, commas within arguments have to be escaped with the backslash character. So only those backslash characters before a comma need escaping with another backslash character. -[fn:45] If =BEAMER_ENV= is set, Org export adds =B_environment= tag +[fn:46] If =BEAMER_ENV= is set, Org export adds =B_environment= tag to make it visible. The tag serves as a visual aid and has no semantic relevance. -[fn:46] Please note that exported formulas are part of an HTML +[fn:47] Please note that exported formulas are part of an HTML document, and that signs such as =<=, =>=, or =&= have special meanings. See [[https://docs.mathjax.org/en/latest/input/tex/html.html#tex-and-latex-in-html-documents][MathJax TeX and LaTeX in HTML documents]]. -[fn:47] This does not allow setting different bibliography compilers +[fn:48] This does not allow setting different bibliography compilers for different files. However, "smart" LaTeX compilation systems, such as latexmk, can select the correct bibliography compiler. -[fn:48] Actually, the constructs =call_()= and =src_{}= +[fn:49] Actually, the constructs =call_()= and =src_{}= are not evaluated when they appear in a keyword (see [[*Summary of In-Buffer Settings]]). -[fn:49] Org Indent mode also sets ~wrap-prefix~ correctly for +[fn:50] In the following example, attempting to evaluate +the second code block will give an error, because the variables +defined in the first code block will not be defined in the second +block. + +#+begin_example +,#+NAME: get-prompt +,#+BEGIN_SRC emacs-lisp :var prompt="root> " :var command="ls" + (concat prompt command) +,#+END_SRC + +,#+RESULTS: get-prompt +: root> ls + +,#+BEGIN_SRC emacs-lisp :noweb yes + <> +,#+END_SRC +#+end_example + +The previous block is expanded without setting ~prompt~ and ~command~ +values. + +#+begin_example +,#+BEGIN_SRC emacs-lisp + (concat prompt command) +,#+END_SRC +#+end_example + +[fn:51] 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:50] This works, but requires extra effort. Org Indent mode is +[fn:52] This works, but requires extra effort. Org Indent mode is more convenient for most applications. -[fn:51] For a server to host files, consider using a WebDAV server, +[fn:53] 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:52] While creating the agendas, Org mode forces =ID= properties +[fn:54] 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:53] By default this works only for LaTeX, HTML, and Texinfo. +[fn:55] By default this works only for LaTeX, HTML, and Texinfo. Configure the variable ~orgtbl-radio-table-templates~ to install templates for other modes. -[fn:54] If the =TBLFM= keyword contains an odd number of dollar +[fn:56] 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 diff --git a/elpa/org-9.7.17/doc/org-version.inc b/elpa/org-9.7.17/doc/org-version.inc new file mode 100644 index 00000000..b02e2219 --- /dev/null +++ b/elpa/org-9.7.17/doc/org-version.inc @@ -0,0 +1,3 @@ +@c automatically generated, do not edit +@set VERSION 9.7.17 (9.7.17-3ae179) +@set DATE 2024-12-07 diff --git a/elpa/org-9.6.7/doc/org.texi b/elpa/org-9.7.17/doc/org.texi similarity index 92% rename from elpa/org-9.6.7/doc/org.texi rename to elpa/org-9.7.17/doc/org.texi index bc20bf73..5744193c 100644 --- a/elpa/org-9.6.7/doc/org.texi +++ b/elpa/org-9.7.17/doc/org.texi @@ -13,9 +13,9 @@ @c %**end of header @copying -This manual is for Org version 9.6. +This manual is for Org version 9.7. -Copyright @copyright{} 2004--2023 Free Software Foundation, Inc. +Copyright @copyright{} 2004--2024 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -39,7 +39,7 @@ modify this GNU manual.'' @finalout @titlepage @title The Org Manual -@subtitle Release 9.6 +@subtitle Release 9.7 @author The Org Mode Developers @page @vskip 0pt plus 1filll @@ -53,6 +53,7 @@ modify this GNU manual.'' @top The Org Manual @insertcopying + @end ifnottex @menu @@ -323,9 +324,9 @@ Exporting * Org Export:: Exporting to Org. * Texinfo Export:: Exporting to Texinfo. * iCalendar Export:: Exporting to iCalendar. -* Other Built-in Back-ends:: Exporting to a man page. +* Other Built-in Backends:: Exporting to a man page. * Advanced Export Configuration:: Fine-tuning the export output. -* Export in Foreign Buffers:: Author tables and lists in Org syntax. +* Export Region:: Author tables and lists in Org syntax. Beamer Export @@ -342,6 +343,7 @@ HTML Export * HTML specific export settings:: Settings for HTML export. * HTML doctypes:: Exporting various (X)HTML flavors. * HTML preamble and postamble:: Inserting preamble and postamble. +* Bare HTML:: Exporting HTML without CSS, Javascript, etc. * Quoting HTML tags:: Using direct HTML in Org files. * Headlines in HTML export:: Formatting headlines. * Links in HTML export:: Inserting and formatting links. @@ -355,7 +357,7 @@ HTML Export @LaTeX{} Export * @LaTeX{}/PDF export commands:: For producing @LaTeX{} and PDF documents. -* @LaTeX{} specific export settings:: Unique to this @LaTeX{} back-end. +* @LaTeX{} specific export settings:: Unique to this @LaTeX{} backend. * @LaTeX{} header and sectioning:: Setting up the export file structure. * Quoting @LaTeX{} code:: Incorporating literal @LaTeX{} code. * Tables in @LaTeX{} export:: Options for exporting tables to @LaTeX{}. @@ -406,10 +408,6 @@ Texinfo Export * Special blocks in Texinfo export:: Special block attributes. * A Texinfo example:: Processing Org to Texinfo. -Export in Foreign Buffers - -* Bare HTML:: Exporting HTML without CSS, Javascript, etc. - Publishing * Configuration:: Defining projects. @@ -441,7 +439,7 @@ Citation handling Bibliography printing -* Bibliography options in the ``biblatex'' and ``csl'' export processors:: +* Bibliography options in the @samp{biblatex} and @samp{csl} export processors:: Working with Source Code @@ -480,6 +478,7 @@ Miscellaneous * Protocols:: External access to Emacs and Org. * Org Crypt:: Encrypting Org files. * Org Mobile:: Viewing and capture on a mobile device. +* Drag and Drop & @code{yank-media}:: Dropping and pasting files and images Clean View @@ -508,7 +507,7 @@ Hacking * Hooks:: How to reach into Org's internals. * Add-on Packages:: Available extensions. * Adding Hyperlink Types:: New custom link types. -* Adding Export Back-ends:: How to write new export back-ends. +* Adding Export Backends:: How to write new export backends. * Tables in Arbitrary Syntax:: Orgtbl for LaTeX and other programs. * Dynamic Blocks:: Automatically filled blocks. * Special Agenda Views:: Customized views. @@ -548,8 +547,11 @@ Org Mode is an authoring tool and a TODO lists manager for GNU Emacs. It relies on a lightweight plain-text markup language used in files with the @samp{.org} extension. +Authoring Org files is best supported by Emacs, but you can view, +understand, and change them with any text editor. + As an authoring tool, Org helps you write structured documents and -provides exporting facilities. Org files can also be used for literate +provides exporting facilities. Org files can also be used for literate programming and reproducible research. As a TODO lists manager, Org helps you organize your tasks in a flexible way, from daily needs to detailed project-planning, allowing logging, multiple views on your @@ -621,6 +623,10 @@ When installing Org on top of the pre-packaged version, please note that Org stable versions are meant to be fully compatible with the last three stable versions of Emacs but not with older Emacsen. +Some Org components also depend on third-party packages available +through package archives. Org is only guaranteed to be compatible +with the latest stable versions of these third-party packages. + @anchor{Using Emacs packaging system} @subheading Using Emacs packaging system @@ -635,6 +641,16 @@ Otherwise autoload Org functions will mess up the installation. @end quotation +To avoid interference with built-in Org mode, you can use command line: + +@example +emacs -Q -batch -eval "(progn (require 'package) (package-initialize) (package-refresh-contents) (package-upgrade 'org))" +@end example + +This approach has the advantage of isolating the upgrade process from +a running Emacs session, ensuring that version conflicts can not +arise. + @anchor{Using Org's git repository} @subheading Using Org's git repository @@ -702,7 +718,7 @@ For a better experience, the three Org commands @code{org-store-link}, Emacs, not just in Org buffers. To that effect, you need to bind them to globally available keys, like the ones reserved for users (see @ref{Key Binding Conventions,,,elisp,}). Here are suggested bindings, -please modify the keys to your own liking. +please modify the keys to your own liking in your @ref{Init File,personal init file,,emacs,}. @lisp (global-set-key (kbd "C-c l") #'org-store-link) @@ -735,14 +751,18 @@ region by using the mouse to select a region, or pressing @section Feedback @cindex feedback +@cindex contact @cindex bug reports @cindex reporting a bug +@cindex request a feature +@cindex feature requests +@cindex ideas @cindex maintainer @cindex author If you find problems with Org, or if you have questions, remarks, or ideas about it, please send an email to the Org mailing list -@email{emacs-orgmode@@gnu.org}. You can subscribe to the list +@email{mailto:emacs-orgmode@@gnu.org}. You can subscribe to the list @uref{https://lists.gnu.org/mailman/listinfo/emacs-orgmode, from this web page}. If you are not a member of the mailing list, your mail will be passed to the list after a moderator has approved it@footnote{ Please @@ -828,6 +848,16 @@ What did you expect to happen? What happened instead? @end enumerate +@cindex performance +@cindex profile +@cindex slow +@cindex slowdown +@cindex laggy +@cindex not responsive +If you experience degraded performance, you can record a ``profile'' and +share it on the Org mailing list. See below for the instructions how +to record a useful profile. + Thank you for helping to improve this program. @anchor{How to create a useful backtrace} @@ -874,10 +904,84 @@ When you hit the error, a @samp{*Backtrace*} buffer appears on the screen. Save this buffer to a file---for example using @kbd{C-x C-w}---and attach it to your bug report. @end enumerate -@node Conventions -@section Typesetting Conventions Used in this Manual +@anchor{How to profile Org performance} +@subheading How to profile Org performance + +@cindex profiler +Sometimes, Org is becoming slow for no apparent reason. Such slowdown +is often caused by interaction between third-party packages and Org +mode. However, identifying the root cause is not always straightforward. + +Emacs is able to record performance statistics, which can then be used +to find out which functions are taking most of the time to execute. +To record the statistics, one can use so-called profiler. To use the +Emacs profiler, we recommend the following steps: + +@enumerate +@item +Make sure that no profiler is currently active: + +@example +M-x profiler-stop +@end example + +@item +Start a new CPU profiler session: + +@example +M-x profiler-start cpu +@end example + +@item +Use Emacs as usual, performing the actions that are deemed slow. + +@item +Display and examine the recorded performance statistics: +@example +M-x profiler-report +@end example + + +This command will display a summary of the commands and functions +that have been executed between @code{profiler-start} and +@code{profiler-report} invocations, with command taking most of the time +displayed on top. + +@samp{} key can be used to fold and unfold lines in the profiler +buffer. The child items revealed upon unfolding are the functions +and commands called by the unfolded parent. + +The root causes are often buried deep inside sub-children items in +the profiler. You can press @samp{B} (@code{profiler-report-render-reversed-calltree}) +to quickly reveal the actual function/command that takes most of +the time to run. + +Pressing @samp{C} @code{profiler-report-render-calltree} will recover the +original view. + +@item +If you need further help, you can share the statistics data. + +Just save the data by issuing + +@example +M-x profiler-report-write-profile +/path/to/profile-file-to-be-saved +@end example + + +Then, you can attached the saved file to your email to the Org +mailing list, alongside with details about what you did to trigger +the slowdown. + +Note that the saved statistics will only contain the function names +and how long their execution takes. No private data will be +recorded. +@end enumerate +@node Conventions +@section Typesetting Conventions Used in this Manual @anchor{TODO keywords tags properties etc} @subheading TODO keywords, tags, properties, etc. @@ -980,7 +1084,7 @@ as a title for your own headings. Some people find the many stars too noisy and would prefer an outline that has whitespace followed by a single star as headline starters. -This can be achieved using a Org Indent minor mode. See @ref{Clean View} for more information. +This can be achieved using an Org Indent minor mode. See @ref{Clean View} for more information. Headlines are not numbered. However, you may want to dynamically number some, or all, of them. See @ref{Dynamic Headline Numbering}. @@ -1064,10 +1168,10 @@ You can run global cycling using @kbd{@key{TAB}} only if point is at the very beginning of the buffer, but not on a headline, and @code{org-cycle-global-at-bob} is set to a non-@code{nil} value. -@item @kbd{C-u C-u @key{TAB}} (@code{org-set-startup-visibility}) +@item @kbd{C-u C-u @key{TAB}} (@code{org-cycle-set-startup-visibility}) @cindex startup visibility @kindex C-u C-u TAB -@findex org-set-startup-visibility +@findex org-cycle-set-startup-visibility Switch back to the startup visibility of the buffer (see @ref{Initial visibility}). @item @kbd{C-u C-u C-u @key{TAB}} (@code{org-show-all}) @@ -1148,9 +1252,9 @@ Furthermore, any entries with a @samp{VISIBILITY} property (see @ref{Properties for this property are @samp{folded}, @samp{children}, @samp{content}, and @samp{all}. @table @asis -@item @kbd{C-u C-u @key{TAB}} (@code{org-set-startup-visibility}) +@item @kbd{C-u C-u @key{TAB}} (@code{org-cycle-set-startup-visibility}) @kindex C-u C-u TAB -@findex org-set-startup-visibility +@findex org-cycle-set-startup-visibility Switch back to the startup visibility of the buffer, i.e., whatever is requested by startup options and @samp{VISIBILITY} properties in individual entries. @@ -1162,11 +1266,17 @@ individual entries. @cindex edits, catching invisible @vindex org-fold-catch-invisible-edits +@vindex org-fold-catch-invisible-edits-commands Sometimes you may inadvertently edit an invisible part of the buffer and be confused on what has been edited and how to undo the mistake. -Setting @code{org-fold-catch-invisible-edits} to non-@code{nil} helps preventing -this. See the docstring of this option on how Org should catch -invisible edits and process them. +By default, Org prevents such edits for a limited set of user +commands. Users can control which commands are affected by +customizing @code{org-fold-catch-invisible-edits-commands}. + +The strategy used to decide if a given edit is dangerous is controlled +by @code{org-fold-catch-invisible-edits}. See the docstring of this option +on the available strategies. Set the option to @code{nil} to disable +catching invisible edits completely. @node Motion @section Motion @@ -1369,7 +1479,9 @@ the N sequential subtrees. Yank subtree from kill ring. This does modify the level of the subtree to make sure the tree fits in nicely at the yank position. The yank level can also be specified with a numeric prefix argument, -or by yanking after a headline marker like @samp{****}. +or by yanking after a headline marker like @samp{****}. With +@kbd{C-u} prefix, force inserting as a sibling. With +@kbd{C-u C-u} prefix argument, force inserting as a child. @item @kbd{C-y} (@code{org-yank}) @kindex C-y @@ -1597,6 +1709,7 @@ My favorite scenes are (in this order) 3. Peter Jackson being shot by Legolas - on DVD only He makes a really funny face when it happens. +8. [@@8] But in the end, no individual scenes matter but the film as a whole. Important actors in this film are: - Elijah Wood :: He plays Frodo @@ -2798,6 +2911,23 @@ to read than the equivalent: '(substring $1 (string-to-number $2) (string-to-number $3)) @end example + +When the formula itself contains @samp{;} symbol, Org mode may incorrectly +interpret everything past @samp{;} as format specifier: + +@example +'(concat $1 ";") +@end example + + +@noindent +You can put an extra tailing @samp{;} to indicate that all the earlier +instances of @samp{;} belong to the formula itself: + +@example +'(concat $1 ";"); +@end example + @node Durations and time values @subsection Durations and time values @@ -3407,13 +3537,17 @@ Specify the title of the plot. @item @samp{ind} Specify which column of the table to use as the @samp{x} axis. +@item @samp{timeind} +Specify which column of the table to use as the @samp{x} axis as a time +value. + @item @samp{deps} Specify the columns to graph as a Lisp style list, surrounded by parentheses and separated by spaces for example @samp{dep:(3 4)} to graph the third and fourth columns. Defaults to graphing all other columns aside from the @samp{ind} column. -@item transpose +@item @samp{transpose} When @samp{y}, @samp{yes}, or @samp{t} attempt to transpose the table data before plotting. Also recognizes the shorthand option @samp{trans}. @@ -3441,19 +3575,19 @@ Specify an entire line to be inserted in the Gnuplot script. When plotting @samp{3d} or @samp{grid} types, set this to @samp{t} to graph a flat mapping rather than a @samp{3d} slope. -@item min +@item @samp{min} Provides a minimum axis value that may be used by a plot type. Implicitly assumes the @samp{y} axis is being referred to. Can explicitly provide a value for a either the @samp{x} or @samp{y} axis with @samp{xmin} and @samp{ymin}. -@item max +@item @samp{max} Provides a maximum axis value that may be used by a plot type. Implicitly assumes the @samp{y} axis is being referred to. Can explicitly provide a value for a either the @samp{x} or @samp{y} axis with @samp{xmax} and @samp{ymax}. -@item ticks +@item @samp{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 @code{org--plot/sensible-tick-num} to try to determine a good @@ -3475,7 +3609,7 @@ plot type, as that can impact the content of the data file. @anchor{ASCII bar plots} @subheading ASCII bar plots -While point is on a column, typing @kbd{C-c `` a} or @kbd{M-x orgtbl-ascii-plot} create a new column containing an ASCII-art bars +While point is on a column, typing @kbd{C-c " a} or @kbd{M-x orgtbl-ascii-plot} create a new column containing an ASCII-art bars plot. The plot is implemented through a regular column formula. When the source column changes, the bar plot may be updated by refreshing the table, for example typing @kbd{C-u C-c *}. @@ -3600,7 +3734,8 @@ precise behavior depends on how point arrived there---see incomplete and the internals are again displayed as plain text. Inserting the missing bracket hides the link internals again. To show the internal structure of all links, use the menu: Org @arrow{} -Hyperlinks @arrow{} Literal links. +Hyperlinks @arrow{} Literal links, customize @code{org-link-descriptive}, or use +@samp{literallinks} @ref{In-buffer Settings, , startup option}. @node Internal Links @section Internal Links @@ -3724,10 +3859,6 @@ Here is the full set of built-in link types: @item @samp{file} 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. - As a special case, ``file'' prefix may be omitted if the file name is complete, e.g., it starts with @samp{./}, or @samp{/}. @@ -3751,7 +3882,7 @@ Link to an electronic resource, through its handle. Execute an Elisp command upon activation. @item @samp{gnus}, @samp{rmail}, @samp{mhe} -Link to messages or folders from a given Emacs' MUA@. +Link to messages or folders from a given Emacs MUA@. @item @samp{help} Display documentation of a symbol in @samp{*Help*} buffer. @@ -3778,10 +3909,15 @@ Usenet links. Execute a shell command upon activation. @end table + +For @samp{file:} and @samp{id:} links, you can additionally specify a line +number, or a text search string, separated by @samp{::}. In Org files, you +may link to a headline name, a custom ID, or a code reference instead. + The following table illustrates the link types above, along with their options: -@multitable {aaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} +@multitable {aaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} @headitem Link Type @tab Example @item http @@ -3825,6 +3961,8 @@ it is not found, then the user is queried to create it.} @tab @samp{docview:papers/last.pdf::NNN} @item id @tab @samp{id:B7423F4D-2E8A-471B-8810-C40F074717E9} +@item +@tab @samp{id:B7423F4D-2E8A-471B-8810-C40F074717E9::*task} (headline search) @item news @tab @samp{news:comp.emacs} @item mailto @@ -3924,8 +4062,9 @@ current buffer: @table @asis @item @emph{Org mode buffers} For Org files, if there is a @samp{<>} at point, the link points -to the target. Otherwise it points to the current headline, which -is also the description. +to the target. If there is a named block (using @samp{#+name:}) at +point, the link points to that name. Otherwise it points to the +current headline, which is also the description. @vindex org-id-link-to-org-use-id @cindex @samp{CUSTOM_ID}, property @@ -3943,6 +4082,32 @@ file. The @samp{ID} property can be either a UUID (default) or a timestamp, depending on @code{org-id-method}. Later, when inserting the link, you need to decide which one to use. +@vindex org-id-link-consider-parent-id +@vindex org-id-link-use-context +@vindex org-link-context-for-files +When @code{org-id-link-consider-parent-id} is @code{t}@footnote{ Also, +@code{org-link-context-for-files} and @code{org-id-link-use-context} should be +both enabled (which they are, by default).}, parent @samp{ID} properties +are considered. This allows linking to specific targets, named +blocks, or headlines (which may not have a globally unique @samp{ID} +themselves) within the context of a parent headline or file which +does. + +For example, given this org file: + +@example +* Parent +:PROPERTIES: +:ID: abc +:END: +** Child 1 +** Child 2 +@end example + +Storing a link with point at ``Child 1'' will produce a link +@samp{}, which precisely links to the ``Child 1'' +headline even though it does not have its own ID@. + @item @emph{Email/News clients: VM, Rmail, Wanderlust, MH-E, Gnus} @vindex org-link-email-description-format Pretty much all Emacs mail clients are supported. The link points @@ -4156,7 +4321,7 @@ replacement text. Here is an example: @lisp (setq org-link-abbrev-alist - '(("bugzilla" . "http://10.1.2.9/bugzilla/show_bug.cgi?id=") + '(("bugzilla" . "https://10.1.2.9/bugzilla/show_bug.cgi?id=") ("Nu Html Checker" . "https://validator.w3.org/nu/?doc=%h") ("duckduckgo" . "https://duckduckgo.com/?q=%s") ("omap" . "https://nominatim.openstreetmap.org/search?q=%s&polygon=1") @@ -4178,8 +4343,8 @@ argument. With the above setting, you could link to a specific bug with @samp{[[bugzilla:129]]}, search the web for @samp{OrgMode} with @samp{[[duckduckgo:OrgMode]]}, -show the map location of the Free Software Foundation @samp{[[gmap:51 -Franklin Street, Boston]]} or of Carsten office @samp{[[omap:Science Park 904, +show the map location of the Free Software Foundation @samp{[[omap:31 +Milk Street, Boston]]} or of Carsten's office @samp{[[omap:Science Park 904, Amsterdam, The Netherlands]]} and find out what the Org author is doing besides Emacs hacking with @samp{[[ads:Dominik,C]]}. @@ -4210,7 +4375,9 @@ the link completion function like this: @section Search Options in File Links @cindex search option in file links +@cindex search option in id links @cindex file links, searching +@cindex id links, searching @cindex attachment links, searching File links can contain additional information to make Emacs jump to a @@ -4222,8 +4389,8 @@ example, when the command @code{org-store-link} creates a link (see line as a search string that can be used to find this line back later when following the link with @kbd{C-c C-o}. -Note that all search options apply for Attachment links in the same -way that they apply for File links. +Note that all search options apply for Attachment and ID links in the +same way that they apply for File links. Here is the syntax of the different ways to attach a search to a file link, together with explanations for each: @@ -4551,14 +4718,9 @@ meaning here.}. For example: (sequence "|" "CANCELED(c)"))) @end lisp -@vindex org-fast-tag-selection-include-todo If you then press @kbd{C-c C-t} followed by the selection key, the entry is switched to this state. @kbd{@key{SPC}} can be used to -remove any TODO keyword from an entry@footnote{Check also the variable @code{org-fast-tag-selection-include-todo}, -it allows you to change the TODO state through the tags interface (see -@ref{Setting Tags}), in case you like to mingle the two concepts. Note -that this means you need to come up with unique keys across both sets -of keywords.}. +remove any TODO keyword from an entry. @node Per-file keywords @subsection Setting up keywords for individual files @@ -4887,8 +5049,10 @@ The property @samp{STYLE} is set to the value @samp{habit} (see @ref{Properties @item The TODO has a scheduled date, usually with a @samp{.+} style repeat interval. A @samp{++} style may be appropriate for habits with time -constraints, e.g., must be done on weekends, or a @samp{+} style for an -unusual habit that can have a backlog, e.g., weekly reports. +constraints, e.g., must be done on specific days of week (@samp{++1w}), +or a @samp{+} style for an unusual habit that can have a backlog, e.g., +weekly reports. See @ref{Repeated tasks} for more details about repeat +intervals. @item The TODO may also have minimum and maximum ranges specified by @@ -5117,7 +5281,7 @@ all children are done, you can use the following setup: @lisp (defun org-summary-todo (n-done n-not-done) "Switch entry to DONE when all subentries are done, to TODO otherwise." - (let (org-log-done org-log-states) ; turn off logging + (let (org-log-done org-todo-log-states) ; turn off logging (org-todo (if (= n-not-done 0) "DONE" "TODO")))) (add-hook 'org-after-todo-statistics-hook #'org-summary-todo) @@ -5153,15 +5317,10 @@ Here is an example of a checkbox list. - [X] talk to the neighbors @end example -Checkboxes work hierarchically, so if a checkbox item has children -that are checkboxes, toggling one of the children checkboxes makes the -parent checkbox reflect if none, some, or all of the children are -checked. - @cindex statistics, for checkboxes @cindex checkbox statistics @cindex @samp{COOKIE_DATA}, property -@vindex org-hierarchical-checkbox-statistics +@vindex org-checkbox-hierarchical-statistics The @samp{[2/4]} and @samp{[1/3]} in the first and second line are cookies indicating how many checkboxes present in this entry have been checked off, and the total number of checkboxes present. This can give you an @@ -5169,7 +5328,7 @@ idea on how many checkboxes remain, even without opening a folded entry. The cookies can be placed into a headline or into (the first line of) a plain list item. Each cookie covers checkboxes of direct children structurally below the headline/item on which the cookie -appears@footnote{ Set the variable @code{org-hierarchical-checkbox-statistics} +appears@footnote{ Set the variable @code{org-checkbox-hierarchical-statistics} if you want such cookies to count all checkboxes below the cookie, not just those belonging to direct children.}. You have to insert the cookie yourself by typing either @samp{[/]} or @samp{[%]}. With @samp{[/]} you get @@ -5188,6 +5347,42 @@ If the current outline node has an @samp{ORDERED} property, checkboxes must be checked off in sequence, and an error is thrown if you try to check off a box while there are unchecked boxes above it. +A checkbox can be in one of the three states: +@enumerate +@item +not checked @samp{[ ]} +@item +partially checked @samp{[-]} +@item +checked @samp{[X]} +@end enumerate + +Checkboxes work hierarchically, so if a checkbox item has children +that are checkboxes, toggling one of the children checkboxes makes the +parent checkbox reflect if none, some, or all of the children are +checked. + +If all child checkboxes are not checked, the parent checkbox is also not checked. +@example +- [ ] call people + - [ ] Peter + - [ ] Sarah +@end example + +If some but not all child checkboxes are checked, the parent checkbox is partially checked. +@example +- [-] call people + - [X] Peter + - [ ] Sarah +@end example + +If all child checkboxes are checked, the parent checkbox is also checked. +@example +- [X] call people + - [X] Peter + - [X] Sarah +@end example + The following commands work with checkboxes: @table @asis @@ -5333,14 +5528,6 @@ To limit tag inheritance to specific tags, or to turn it off entirely, use the variables @code{org-use-tag-inheritance} and @code{org-tags-exclude-from-inheritance}. -@vindex org-tags-match-list-sublevels -When a headline matches during a tags search while tag inheritance is -turned on, all the sublevels in the same tree---for a simple match -form---match as well@footnote{ This is only true if the search does not -involve more complex tests including properties (see @ref{Property Searches}).}. The list of matches may then become very long. If you -only want to see the first tags match in a subtree, configure the -variable @code{org-tags-match-list-sublevels} (not recommended). - @vindex org-agenda-use-tag-inheritance Tag inheritance is relevant when the agenda search tries to match a tag, either in the @code{tags} or @code{tags-todo} agenda types. In other @@ -5556,6 +5743,11 @@ effect: start selection with @kbd{C-c C-c C-c} instead of the special window is not even shown for single-key tag selection, it comes up only when you press an extra @kbd{C-c}. +@vindex org-fast-tag-selection-maximum-tags +The number of tags displayed in the fast tag selection interface is +limited by @code{org-fast-tag-selection-maximum-tags} to avoid running out +of keyboard keys. You can customize this variable. + @node Tag Hierarchy @section Tag Hierarchy @@ -5708,10 +5900,8 @@ Create a global list of tag matches from all agenda files. See @item @kbd{M-x org-agenda M} (@code{org-tags-view}) @kindex M @r{(Agenda dispatcher)} -@vindex org-tags-match-list-sublevels Create a global list of tag matches from all agenda files, but check -only TODO items and force checking subitems (see the option -@code{org-tags-match-list-sublevels}). +only TODO items. @end table These commands all prompt for a match string which allows basic @@ -5799,10 +5989,10 @@ disks in a box like this: :END: @end example -Properties can be inserted on buffer level. That means they apply +Properties can be inserted at the buffer level. That means they apply before the first headline and can be inherited by all entries in a -file. Property blocks defined before first headline needs to be -located at the top of the buffer, allowing only comments above. +file. Property blocks defined before the first headline must be at +the top of the buffer with only comments above them. Properties can also be defined using lines like: @@ -5964,9 +6154,13 @@ not be used as keys in the properties drawer: @item @samp{TAGS} @tab The tags defined directly in the headline. @item @samp{TIMESTAMP} -@tab The first keyword-less timestamp in the entry. +@tab The first active keyword-less timestamp in the entry.@footnote{For both @samp{TIMESTAMP} and @samp{TIMESTAMP_IA}: the word ``first'' +refers to the first occurrence in the entry, not the earliest in time; +the prefix @samp{CLOCK:} at the beginning of a clock entry is considered a +keyword in this context; and timestamps inside property drawers are +ignored.} @item @samp{TIMESTAMP_IA} -@tab The first inactive timestamp in the entry. +@tab The first inactive keyword-less timestamp in the entry. @item @samp{TODO} @tab The TODO keyword of the entry. @end multitable @@ -5996,10 +6190,8 @@ Create a global list of tag/property matches from all agenda files. @item @kbd{M-x org-agenda M} (@code{org-tags-view}) @kindex M @r{(Agenda dispatcher)} -@vindex org-tags-match-list-sublevels Create a global list of tag matches from all agenda files, but check -only TODO items and force checking of subitems (see the option -@code{org-tags-match-list-sublevels}). +only TODO items. @end table The syntax for the search string is described in @ref{Matching tags and properties}. @@ -6265,8 +6457,6 @@ either for all clocks or just for today. @node Using column view @subsection Using column view - - @anchor{Turning column view on or off} @subsubheading Turning column view on or off @@ -6373,6 +6563,26 @@ Insert a new column, to the left of the current column. @kindex S-M-LEFT @findex org-columns-delete Delete the current column. + +@item @kbd{M-@key{LEFT}} (@code{org-columns-move-left}) +@kindex M-LEFT +@findex org-columns-move-left +Move the current column left. + +@item @kbd{M-@key{RIGHT}} (@code{org-columns-move-right}) +@kindex M-RIGHT +@findex org-columns-move-right +Move the current column right. + +@item @kbd{M-@key{UP}} (@code{org-columns-move-row-up}) +@kindex M-UP +@findex org-columns-move-row-up +Move the current row up. + +@item @kbd{M-@key{DOWN}} (@code{org-columns-move-row-down}) +@kindex M-DOWN +@findex org-columns-move-row-down +Move the current row down. @end table @node Capturing column view @@ -6447,9 +6657,19 @@ tags will be excluded from the column view. @item @samp{:indent} When non-@code{nil}, indent each @samp{ITEM} field according to its level. +@item @samp{:link} +When non-@code{nil}, link the @samp{ITEM} headlines in the table to their +origins. + @item @samp{:format} Specify a column attribute (see @ref{Column attributes}) for the dynamic block. + +@item @samp{:formatter} +@cindex @samp{formatter}, dynamic block parameter +@vindex org-columns-dblock-formatter +A function to format column view data and insert it into the buffer. +See the option @code{org-columns-dblock-formatter}. @end table The following commands insert or update the dynamic block: @@ -6469,7 +6689,7 @@ selecting ``columnview'' (see @ref{Dynamic Blocks}). @kindex C-c C-c @kindex C-c C-x C-u @findex org-dblock-update -Update dynamic block at point. point needs to be in the @samp{#+BEGIN} +Update dynamic block at point. Point needs to be on the @samp{#+BEGIN} line of the dynamic block. @item @kbd{C-u C-c C-x C-u} (@code{org-update-all-dblocks}) @@ -6508,6 +6728,11 @@ a little confusing because timestamp is often used as indicating when something was created or last changed. However, in Org mode this term is used in a much wider sense. +Timestamps can be used to plan appointments, schedule tasks, set +deadlines, track time, and more. The following sections describe +the timestamp format and tooling that Org mode provides for common +use cases dealing with time and time intervals. + @menu * Timestamps:: Assigning a time to a tree entry. * Creating Timestamps:: Commands to insert timestamps. @@ -6526,8 +6751,8 @@ is used in a much wider sense. @cindex deadlines @cindex scheduling -A timestamp is a specification of a date (possibly with a time or -a range of times) in a special format, either @samp{<2003-09-16 Tue>} or +A timestamp is a specification of a date---possibly with a time or +time range---in a special format, either @samp{<2003-09-16 Tue>} or @samp{<2003-09-16 Tue 09:39>} or @samp{<2003-09-16 Tue 12:00-12:30>}@footnote{The Org date format is inspired by the standard ISO 8601 date/time format. To use an alternative format, see @ref{Custom time format}. The day name is optional when you type the date yourself. However, any date inserted or modified by Org adds that day name, for @@ -6543,13 +6768,17 @@ the agenda (see @ref{Weekly/daily agenda}). We distinguish: A simple timestamp just assigns a date/time to an item. This is just like writing down an appointment or event in a paper agenda. In the agenda display, the headline of an entry associated with -a plain timestamp is shown exactly on that date. +a plain timestamp is shown exactly on that date. There can be +multiple timestamps in an item. @example * Meet Peter at the movies <2006-11-01 Wed 19:15> * Discussion on climate change - <2006-11-02 Thu 20:00-22:00> + <2006-11-02 Thu 10:00-12:00> +* My days off + <2006-11-03 Fri> + <2006-11-06 Mon> @end example @item Timestamp with repeater interval @@ -6582,8 +6811,8 @@ specify a date December 1, 2005, the call might look like @samp{(diary-date 12 1 2005)} or @samp{(diary-date 1 12 2005)} or @samp{(diary-date 2005 12 1)}, depending on the settings. This has been the source of much confusion. Org mode users can resort to special versions of -these functions, namely @code{org-date}, @code{org-anniversary}, @code{org-cyclic, and -~org-block}. These work just like the corresponding @code{diary-} +these functions, namely @code{org-date}, @code{org-anniversary}, @code{org-cyclic}, and +@code{org-block}. These work just like the corresponding @code{diary-} functions, but with stable ISO order of arguments (year, month, day) wherever applicable, independent of the value of @code{calendar-date-style}.}. @@ -6591,19 +6820,34 @@ For example, with optional time: @example * 22:00-23:00 The nerd meeting on every 2nd Thursday of the month - <%%(diary-float t 4 2)> + <%%(diary-float t 4 2) 22:00-23:00> +@end example + +@item Time range +@cindex time range + +Time range is a timestamp having two time units connected by @samp{-} + +@example +* Discussion on climate change + <2006-11-02 Thu 10:00-12:00> @end example @item Time/Date range +@cindex time range @cindex timerange @cindex date range -Two timestamps connected by @samp{--} denote a range. The headline is -shown on the first and last day of the range, and on any dates that -are displayed and fall in the range. Here is an example: +Two timestamps connected by @samp{--} denote a range. In the agenda, the +headline is shown on the first and last day of the range, and on any +dates that are displayed and fall in the range. The first example +specifies just the dates of the range while the second example +specifies a time range for each date. @example ** Meeting in Amsterdam <2004-08-23 Mon>--<2004-08-26 Thu> +** This weeks committee meetings + <2004-08-23 Mon 10:00-11:00>--<2004-08-26 Thu 10:00-11:00> @end example @item Inactive timestamp @@ -6627,9 +6871,10 @@ format. All commands listed below produce timestamps in the correct format. @table @asis -@item @kbd{C-c .} (@code{org-time-stamp}) +@item @kbd{C-c .} (@code{org-timestamp}) @kindex C-c . @findex org-time-stamp +@findex org-timestamp Prompt for a date and insert a corresponding timestamp. When point is at an existing timestamp in the buffer, the command is used to modify this timestamp instead of inserting a new one. When this @@ -6637,20 +6882,22 @@ command is used twice in succession, a time range is inserted. @kindex C-u C-c . @vindex org-time-stamp-rounding-minutes +@vindex org-timestamp-rounding-minutes When called with a prefix argument, use the alternative format which contains date and time. The default time can be rounded to multiples of 5 minutes. See the option -@code{org-time-stamp-rounding-minutes}. +@code{org-timestamp-rounding-minutes}. @kindex C-u C-u C-c . With two prefix arguments, insert an active timestamp with the current time without prompting. -@item @kbd{C-c !} (@code{org-time-stamp-inactive}) +@item @kbd{C-c !} (@code{org-timestamp-inactive}) @kindex C-c ! @kindex C-u C-c ! @kindex C-u C-u C-c ! @findex org-time-stamp-inactive +@findex org-timestamp-inactive Like @kbd{C-c .}, but insert an inactive timestamp that does not cause an agenda entry. @@ -6902,16 +7149,18 @@ turn off the display with @code{org-read-date-display-live}.}. @vindex org-display-custom-times @vindex org-time-stamp-custom-formats +@vindex org-timestamp-custom-formats Org mode uses the standard ISO notation for dates and times as it is defined in ISO 8601. If you cannot get used to this and require another representation of date and time to keep you happy, you can get it by customizing the variables @code{org-display-custom-times} and -@code{org-time-stamp-custom-formats}. +@code{org-timestamp-custom-formats}. @table @asis -@item @kbd{C-c C-x C-t} (@code{org-toggle-time-stamp-overlays}) +@item @kbd{C-c C-x C-t} (@code{org-toggle-timestamp-overlays}) @kindex C-c C-x C-t @findex org-toggle-time-stamp-overlays +@findex org-toggle-timestamp-overlays Toggle the display of custom formats for dates and times. @end table @@ -7154,6 +7403,9 @@ state to @samp{DONE} would actually switch the date like this: DEADLINE: <2005-11-01 Tue +1m> @end example +When task contains multiple timestamps with repeater interval, all +these timestamps are shifted. + To mark a task with a repeater as DONE, use @kbd{C-- 1 C-c C-t}, i.e., @code{org-todo} with a numeric prefix argument of @samp{-1}. @@ -7202,16 +7454,16 @@ special repeaters @samp{++} and @samp{.+}. For example: Marking this DONE shifts the date to exactly one hour from now. @end example -@vindex org-agenda-skip-scheduled-if-deadline-is-shown +@vindex org-agenda-skip-scheduled-repeats-after-deadline You may have both scheduling and deadline information for a specific task. If the repeater is set for the scheduling information only, you probably want the repeater to be ignored after the deadline. If so, -set the variable @code{org-agenda-skip-scheduled-if-deadline-is-shown} to -@code{repeated-after-deadline}. However, any scheduling information -without a repeater is no longer relevant once the task is done, and -thus, removed upon repeating the task. If you want both scheduling -and deadline information to repeat after the same interval, set the -same repeater for both timestamps. +set the variable @code{org-agenda-skip-scheduled-repeats-after-deadline} to +@code{t}. However, any scheduling information without a repeater is no +longer relevant once the task is done, and thus, removed upon +repeating the task. If you want both scheduling and deadline +information to repeat after the same interval, set the same repeater +for both timestamps. An alternative to using a repeater is to create a number of copies of a task subtree, with dates shifted in each copy. The command @@ -7339,23 +7591,30 @@ automatic. @itemx @kbd{C-S-@key{DOWN}} (@code{org-clock-timestamps-down}) @kindex C-S-UP @findex org-clock-timestamps-up +@findex org-shiftcontrolup @kindex C-S-DOWN @findex org-clock-timestamps-down +@findex org-shiftcontroldown On CLOCK log lines, increase/decrease both timestamps so that the clock duration keeps the same value. @item @kbd{S-M-@key{UP}} (@code{org-timestamp-up}) @itemx @kbd{S-M-@key{DOWN}} (@code{org-timestamp-down}) @kindex S-M-UP -@findex org-clock-timestamp-up +@findex org-timestamp-up +@findex org-shiftmetaup @kindex S-M-DOWN -@findex org-clock-timestamp-down +@findex org-timestamp-down +@findex org-shiftmetadown On @samp{CLOCK} log lines, increase/decrease the timestamp at point and the one of the previous, or the next, clock timestamp by the same duration. For example, if you hit @kbd{S-M-@key{UP}} to increase a clocked-out timestamp by five minutes, then the clocked-in timestamp of the next clock is increased by five minutes. +Only @samp{CLOCK} logs created during current Emacs session are +considered when adjusting next/previous timestamp. + @item @kbd{C-c C-t} (@code{org-todo}) @kindex C-c C-t @findex org-todo @@ -7490,7 +7749,7 @@ The time block to consider. This block is specified either absolutely, or relative to the current time and may be any of these formats: -@multitable {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaa} +@multitable {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaa} @item @samp{2007-12-31} @tab New year eve 2007 @item @samp{2007-12} @@ -7509,7 +7768,8 @@ formats: @tab a relative month @item @samp{thisyear}, @samp{lastyear}, @samp{thisyear-N} @tab a relative year -@item @samp{untilnow}@footnote{ When using @code{:step}, @code{untilnow} starts from the beginning of 2003, not the beginning of time.} +@item @samp{untilnow}@footnote{When using @code{:step}, @code{untilnow} starts from the beginning of +2003, not the beginning of time.} @tab all clocked time ever @end multitable @@ -7673,8 +7933,6 @@ last week would be @node Resolving idle time @subsection Resolving idle time and continuous clocking - - @anchor{Resolving idle time (1)} @subsubheading Resolving idle time @@ -7691,7 +7949,7 @@ current clock, or applying it to another one. By customizing the variable @code{org-clock-idle-time} to some integer, such as 10 or 15, Emacs can alert you when you get back to your computer after being idle for that many minutes@footnote{On computers using macOS, idleness is based on actual user -idleness, not just Emacs' idle time. For X11, you can install a +idleness, not just Emacs's idle time. For X11, you can install a utility program @samp{x11idle.c}, available in the @samp{org-contrib/} repository, or install the xprintidle package and set it to the variable @code{org-clock-x11idle-program-name} if you are running Debian, @@ -8321,10 +8579,10 @@ the template in the usual way. Visit the last stored capture item in its buffer. @end table -@vindex org-capture-bookmark +@vindex org-bookmark-names-plist @vindex org-capture-last-stored You can also jump to the bookmark @code{org-capture-last-stored}, which is -automatically created unless you set @code{org-capture-bookmark} to @code{nil}. +automatically created unless you customize @code{org-bookmark-names-plist}. To insert the capture at point in an Org buffer, call @code{org-capture} with a @kbd{C-0} prefix argument. @@ -8480,15 +8738,14 @@ properties. Please rewrite your date/week-tree targets using @code{file+olp+datetree} since the older targets are now deprecated.} creates a heading in a date tree@footnote{A date tree is an outline structure with years on the highest level, months or ISO weeks as sublevels and then dates on the lowest level. - @example * 2022 ** 2022-10 October *** 2022-10-07 Friday *** 2022-10-08 Saturday @end example - -Tags are allowed in the tree structure.} for +TODO state, priority, tags, statistics cookies, and COMMENT keywords +are allowed in the tree structure.} for today's date. If the optional outline path is given, the tree will be built under the node it is pointing to, instead of at top level. Check out the @code{:time-prompt} and @code{:tree-type} properties @@ -8500,6 +8757,9 @@ A function to find the right location in the file. @item @samp{(clock)} File to the entry that is currently being clocked. +@item @samp{(here)} +The position of @samp{point}. + @item @samp{(function function-finding-location)} Most general way: write your own function which both visits the file and moves point to the right location. @@ -8602,6 +8862,7 @@ value of this property. A nullary function or list of nullary functions run before @code{org-capture-mode-hook} when the template is selected. @end table + @table @asis @item @code{:prepare-finalize} A nullary function or list of nullary functions run before @@ -8712,6 +8973,11 @@ Like @samp{%^C}, but insert as link. Prompt the user for a value for property @var{PROP}. You may specify a default value with @samp{%^@{PROP|default@}}. +@item @samp{%^@{PROMPT@}X}, X is one of g,G,t,T,u,U,C,L +Prompt the user as in @samp{%^X}, but use the custom prompt string. You +may specify a default value and completions with +@samp{%^@{PROMPT|default|completion1|completion2|completion3...@}X}. + @item @samp{%^@{PROMPT@}} Prompt the user for a string and replace this sequence with it. You may specify a default value and a completion table with @@ -9365,9 +9631,9 @@ need to press the character selecting the command. @item @kbd{< <} @kindex < < @r{(Agenda dispatcher)} If there is an active region, restrict the following agenda command -to the region. Otherwise, restrict it to the current subtree@footnote{ -For backward compatibility, you can also press @kbd{0} to -restrict to the current region/subtree.}. After pressing @kbd{< <}, you still need to press the character selecting the command. +to the region. Otherwise, restrict it to the current subtree. +After pressing @kbd{< <}, you still need to press the character +selecting the command. @item @kbd{*} @kindex * @r{(Agenda dispatcher)} @@ -9681,14 +9947,11 @@ command for it (see @ref{Agenda Dispatcher}). @item @kbd{M-x org-agenda M} (@code{org-tags-view}) @kindex M @r{(Agenda dispatcher)} @findex org-tags-view -@vindex org-tags-match-list-sublevels @vindex org-agenda-tags-todo-honor-ignore-options Like @kbd{m}, but only select headlines that are also TODO -items and force checking subitems (see the variable -@code{org-tags-match-list-sublevels}). To exclude scheduled/deadline -items, see the variable @code{org-agenda-tags-todo-honor-ignore-options}. -Matching specific TODO keywords together with a tags match is also -possible, see @ref{Tag Searches}. +items. To exclude scheduled/deadline items, see the variable +@code{org-agenda-tags-todo-honor-ignore-options}. Matching specific TODO +keywords together with a tags match is also possible, see @ref{Tag Searches}. @end table The commands available in the tags list are described in @ref{Agenda Commands}. @@ -9759,10 +10022,11 @@ When matching properties, a number of different operators can be used to test the value of a property. Here is a complex example: @example -+work-boss+PRIORITY="A"+Coffee="unlimited"+Effort<2 ++work-boss+PRIORITY="A"+Coffee="unlimited"+Effort<*2 +With=@{Sarah\|Denny@}+SCHEDULED>="<2008-10-11>" @end example +@cindex operator, for property search @noindent The type of comparison depends on how the comparison value is written: @@ -9770,7 +10034,8 @@ The type of comparison depends on how the comparison value is written: @item If the comparison value is a plain number, a numerical comparison is done, and the allowed operators are @samp{<}, @samp{=}, @samp{>}, @samp{<=}, @samp{>=}, and -@samp{<>}. +@samp{<>}. As a synonym for the equality operator @samp{=}, there is also +@samp{==}; @samp{!=} and @samp{/=} are synonyms of the inequality operator @samp{<>}. @item If the comparison value is enclosed in double-quotes, a string @@ -9790,6 +10055,14 @@ You can also use strings like @samp{"<+5d>"} or @samp{"<-2m>"} with units @samp{ If the comparison value is enclosed in curly braces, a regexp match is performed, with @samp{=} meaning that the regexp matches the property value, and @samp{<>} meaning that it does not match. + +@item +All operators may be optionally followed by an asterisk @samp{*}, like in +@samp{<*}, @samp{!=*}, etc. Such @emph{starred operators} work like their regular, +unstarred counterparts except that they match only headlines where +the tested property is actually present. This is most useful for +search terms that logically exclude results, like the inequality +operator. @end itemize So the search string in the example finds entries tagged @samp{work} but @@ -9799,6 +10072,28 @@ smaller than 2, a @samp{With} property that is matched by the regular expression @samp{Sarah\|Denny}, and that are scheduled on or after October 11, 2008. +Note that the test on the @samp{EFFORT} property uses operator @samp{<*}, so +that the search result will include only entries that actually have an +@samp{EFFORT} property defined and with numerical value smaller than 2. +With the regular @samp{<} operator, the search would handle entries without +an @samp{EFFORT} property as having a zero effort and would include them in +the result as well. + +You can use all characters valid in property names when matching +properties. However, you have to quote some characters in property +names with backslashes when using them in search strings, namely all +characters different from alphanumerics and underscores@footnote{ If you +quote alphanumeric characters or underscores with a backslash, that +backslash is ignored.}. For example, to search for all entries having +a property @samp{boss-prio}, @samp{boss:prio}, or @samp{boss\prio}, respectively, +with value @samp{C}, use search strings + +@example +boss\-prio="C" +boss\:prio="C" +boss\\prio="C" +@end example + You can configure Org mode to use property inheritance during a search, but beware that this can slow down searches considerably. See @ref{Property Inheritance}, for details. @@ -10062,17 +10357,17 @@ default order is to first collect all items containing an explicit time-of-day specification. These entries are shown at the beginning of the list, as a @emph{schedule} for the day. After that, items remain grouped in categories, in the sequence given by @code{org-agenda-files}. -Within each category, items are sorted by priority (see -@ref{Priorities}), which is composed of the base priority (2000 for -priority @samp{A}, 1000 for @samp{B}, and 0 for @samp{C}), plus additional -increments for overdue scheduled or deadline items. +Within each category, items are sorted by urgency, which is composed +of the base priority (see @ref{Priorities}; 2000 for priority @samp{A}, 1000 +for @samp{B}, and 0 for @samp{C}), plus additional increments for overdue +scheduled or deadline items. @item For the TODO list, items remain in the order of categories, but -within each category, sorting takes place according to priority (see -@ref{Priorities}). The priority used for sorting derives from the -priority cookie, with additions depending on how close an item is to -its due or scheduled date. +within each category, sorting takes place according to urgency. The +urgency used for sorting derives from the priority cookie, with +additions depending on how close an item is to its due or scheduled +date. @item For tags matches, items are not sorted at all, but just appear in @@ -10092,7 +10387,7 @@ the estimated effort of an entry (see @ref{Effort Estimates}). @vindex org-agenda-effort-filter-preset @vindex org-agenda-regexp-filter-preset Agenda built-in or custom commands are statically defined. Agenda -filters and limits allow to flexibly narrow down the list of agenda +filters and limits allow flexibly narrowing down the list of agenda entries. @emph{Filters} only change the visibility of items, are very fast and are @@ -10513,9 +10808,13 @@ weekly/daily agenda. @item @kbd{v a} (@code{org-agenda-archives-mode}) @kindex v a @findex org-agenda-archives-mode +@vindex org-agenda-start-with-archives-mode Toggle Archives mode. In Archives mode, trees that are archived (see @ref{Internal archiving}) are also scanned when producing the -agenda. To exit archives mode, press @kbd{v a} again. +agenda. To exit archives mode, press @kbd{v a} again. The +initial setting for this mode in new agenda buffers can set with the +variable @code{org-agenda-start-with-archives-mode}, which can be set +with the same values as @code{org-agenda-archives-mode}. @item @kbd{v A} @kindex v A @@ -11106,7 +11405,7 @@ used for the matching. The example above will therefore define: @table @asis @item @kbd{x} as a global search for agenda entries planned@footnote{@emph{Planned} means here that these entries have some planning -information attached to them, like a time-stamp, a scheduled or +information attached to them, like a timestamp, a scheduled or a deadline string. See @code{org-agenda-entry-types} on how to set what planning information is taken into account.} this week/day. @@ -11574,12 +11873,29 @@ but not any simpler You can make words @samp{*bold*}, @samp{/italic/}, @samp{_underlined_}, @samp{=verbatim=} and @samp{~code~}, and, if you must, @samp{+strike-through+}. Text in the code and verbatim string is not processed for Org specific syntax; it is -exported verbatim. +exported verbatim. Org provides a single command as entry point for +inserting the marker character. + +@table @asis +@item @kbd{C-c C-x C-f} (@code{org-emphasize}) +@kindex C-c C-x C-f +@findex org-emphasize +Prompt for a marker character and insert or change an emphasis. If +there is an active region, change that region to a new emphasis. If +there is no region, just insert the marker characters and position +the cursor between them. +@end table @vindex org-fontify-emphasized-text To turn off fontification for marked up text, you can set @code{org-fontify-emphasized-text} to @code{nil}. To narrow down the list of -available markup syntax, you can customize @code{org-emphasis-alist}. +the fontified markup syntax, you can customize +@code{org-emphasis-alist}@footnote{ The markup will still be recognized. Just +not highlighted visually in Emacs.}. + +@vindex org-hide-emphasis-markers +To hide the emphasis markup characters in your buffers, set +@code{org-hide-emphasis-markers} to @code{t}. Sometimes, when marked text also contains the marker character itself, the result may be unsettling. For example, @@ -11610,15 +11926,20 @@ the radius of Alpha Centauri is R_@{Alpha Centauri@} = 1.28 x R_@{sun@}. @end example @vindex org-use-sub-superscripts +@vindex org-export-with-sub-superscripts If you write a text where the underscore is often used in a different context, Org's convention to always interpret these as subscripts can -get in your way. Configure the variable @code{org-use-sub-superscripts} to -change this convention. For example, when setting this variable to -@code{@{@}}, @samp{a_b} is not interpreted as a subscript, but @samp{a_@{b@}} is. - -You can set @code{org-use-sub-superscripts} in a file using the export -option @samp{^:} (see @ref{Export Settings}). For example, @samp{#+OPTIONS: ^:@{@}} -sets @code{org-use-sub-superscripts} to @code{@{@}} and limits super- and +get in your way. Configure the variable @code{org-use-sub-superscripts} +and/or @code{org-export-with-sub-superscripts} to change this convention. +For example, when setting these variables to @code{@{@}}, @samp{a_b} is not +displayed/exported@footnote{The underlying markup still remains a +sub/superscript. Only the visual display and export behavior +changes.} as a subscript, but @samp{a_@{b@}} is. + +You can set both @code{org-use-sub-superscripts} +@code{org-export-with-sub-superscripts} in a file using the export option +@samp{^:} (see @ref{Export Settings}). For example, +@samp{#+OPTIONS: ^:@{@}} sets the two options to @code{@{@}} and limits super- and subscripts to the curly bracket notation. You can also toggle the visual display of super- and subscripts: @@ -11665,7 +11986,7 @@ possible to provide your own special symbols in the variable @code{org-entities-user}. During export, these symbols are transformed into the native format of -the exporter back-end. Strings like @samp{\alpha} are exported as @samp{α} in +the exporter backend. Strings like @samp{\alpha} are exported as @samp{α} in the HTML output, and as @samp{\(\alpha\)} in the @LaTeX{} output. Similarly, @samp{\nbsp} becomes @samp{ } in HTML and @samp{~} in @LaTeX{}. @@ -11708,7 +12029,7 @@ from @TeX{}, but for simplicity I am blurring this distinction.} is widely used typeset scientific documents. Org mode supports embedding @LaTeX{} code into its files, because many academics are used to writing and reading @LaTeX{} source code, and because it can be readily processed to produce -pretty output for a number of export back-ends. +pretty output for a number of export backends. @menu * @LaTeX{} fragments:: Complex formulas made easy. @@ -11723,7 +12044,7 @@ pretty output for a number of export back-ends. @vindex org-format-latex-header Org mode can contain @LaTeX{} math fragments, and it supports ways to -process these for several export back-ends. When exporting to @LaTeX{}, +process these for several export backends. When exporting to @LaTeX{}, the code is left as it is. When exporting to HTML, Org can use either @uref{https://www.mathjax.org, MathJax} (see @ref{Math formatting in HTML export}) or transcode the math into images (see @ref{Previewing @LaTeX{} fragments}). @@ -11740,14 +12061,19 @@ used to create images, any @LaTeX{} environment is handled.}. The only requirem whitespace. @item -Text within the usual @LaTeX{} math delimiters. To avoid conflicts -with currency specifications, single @samp{$} characters are only -recognized as math delimiters if the enclosed text contains at most -two line breaks, is directly attached to the @samp{$} characters with no -whitespace in between, and if the closing @samp{$} is followed by -whitespace, punctuation or a dash. For the other delimiters, there -is no such restriction, so when in doubt, use @samp{\(...\)} as inline -math delimiters. +Text within the usual @LaTeX{} math delimiters. Prefer @samp{\(...\)} for +inline fragments. The @samp{$...$} alternative has some restrictions and +may be a source of confusion. To avoid conflicts with currency +specifications, single @samp{$} characters are only recognized as math +delimiters if the enclosed text contains at most two line breaks, is +directly attached to the @samp{$} characters with no whitespace in +between, and if the closing @samp{$} is followed by whitespace or +punctuation (but not a dash). + +Sometimes, it may necessary to have a literal dollar symbol even +when it is recognized as @LaTeX{} math delimiter. Org provides @samp{\dollar} and +@samp{\USD} entities (see @ref{Special Symbols}) that are rendered as @samp{$} for +such scenarios. Also, see @ref{Escape Character}. @end itemize @noindent @@ -11755,8 +12081,8 @@ For example: @example \begin@{equation@} % arbitrary environments, -x=\sqrt@{b@} % even tables, figures -\end@{equation@} % etc +x=\sqrt@{b@} % even tables, figures, etc +\end@{equation@} If $a^2=b$ and \( b=2 \), then the solution must be either $$ a=+\sqrt@{2@} $$ or \[ a=-\sqrt@{2@} \]. @@ -11765,7 +12091,7 @@ either $$ a=+\sqrt@{2@} $$ or \[ a=-\sqrt@{2@} \]. @vindex org-export-with-latex @LaTeX{} processing can be configured with the variable @code{org-export-with-latex}. The default setting is @code{t} which means -MathJax for HTML, and no processing for ASCII and @LaTeX{} back-ends. +MathJax for HTML, and no processing for ASCII and @LaTeX{} backends. You can also set this variable on a per-file basis using one of these lines: @@ -11967,17 +12293,18 @@ see @ref{Structure Templates} for shortcuts to easily insert code blocks. (defun org-xor (a b) "Exclusive or." (if a (not b) b)) - #+END_SRC +#+END_SRC @end example Both in @samp{example} and in @samp{src} snippets, you can add a @samp{-n} switch to -the end of the @samp{#+BEGIN} line, to get the lines of the example -numbered. The @samp{-n} takes an optional numeric argument specifying the -starting line number of the block. If you use a @samp{+n} switch, the -numbering from the previous numbered snippet is continued in the -current one. The @samp{+n} switch can also take a numeric argument. This -adds the value of the argument to the last line of the previous block -to determine the starting line number. +the @samp{#+BEGIN} line@footnote{In the @samp{src} snippets, switches must be placed +right after the language name and before the @ref{Structure of Code Blocks, , header arguments}}, to get the lines of the example numbered. +The @samp{-n} takes an optional numeric argument specifying the starting +line number of the block. If you use a @samp{+n} switch, the numbering +from the previous numbered snippet is continued in the current one. +The @samp{+n} switch can also take a numeric argument. This adds the value +of the argument to the last line of the previous block to determine +the starting line number. @example #+BEGIN_SRC emacs-lisp -n 20 @@ -11993,9 +12320,12 @@ to determine the starting line number. In literal examples, Org interprets strings like @samp{(ref:name)} as labels, and use them as targets for special hyperlinks like -@samp{[[(name)]]}---i.e., the reference name enclosed in single parenthesis. -In HTML, hovering the mouse over such a link remote-highlights the -corresponding code line, which is kind of cool. +@samp{[[(name)]]}---i.e., the reference name enclosed in single +parentheses. In HTML, hovering the mouse over such a link +remote-highlights the corresponding code line@footnote{ This requires some +Javascript which is @emph{not} automatically included in the HTML output: +you have to customize the variable @samp{org-html-head-include-scripts} to +@code{t} to have it included (it is @code{nil} by default).}, which is kind of cool. You can also add a @samp{-r} switch which @emph{removes} the labels from the source code@footnote{ Adding @samp{-k} to @samp{-n -r} @emph{keeps} the labels in the @@ -12079,7 +12409,7 @@ example If you wish to define a caption for the image (see @ref{Captions}) and -maybe a label for internal cross references (see @ref{Internal Links}), +maybe a label for internal cross-references (see @ref{Internal Links}), make sure that the link is on a line by itself and precede it with @samp{CAPTION} and @samp{NAME} keywords as follows: @@ -12108,16 +12438,21 @@ startup by configuring the variable @vindex org-image-actual-width +@vindex org-image-max-width @cindex @samp{ORG-IMAGE-ACTUAL-WIDTH}, property By default, Org mode displays inline images according to their -actual width. You can customize the displayed image width using +actual width, but no wider than @code{fill-column} characters. + +You can customize the displayed image width using @code{org-image-actual-width} variable (globally) or @samp{ORG-IMAGE-ACTUAL-WIDTH} property (subtree-level)@footnote{ The width can be customized in Emacs >= 24.1, built with imagemagick support.}. Their value can be the following: @itemize @item -(default) Non-nil, use the actual width of images when inlining them. +(default) Non-@code{nil}, use the actual width of images when inlining +them. If the actual width is too wide, limit it according to +@code{org-image-max-width}. @item When set to a number, use imagemagick (when available) to set the image's width to this value. @@ -12129,10 +12464,63 @@ When set to a number in a list, try to get the width from any @end example and fall back on that number if none is found. @item -When set to nil, try to get the width from an @samp{#+ATTR.*} keyword -and fall back on the original width if none is found. +When set to @code{nil}, try to get the width from an @samp{#+ATTR.*} keyword +and fall back on the original width or @code{org-image-max-width} if +none is found. +@end itemize + +@code{org-image-max-width} limits the maximum displayed image width, but +only when the image width is not set explicitly. Possible maximum +width can be set to: +@itemize +@item +(default) @code{fill-column}, limit width to @code{fill-column} number of +characters. +@item +@code{window}, limit width to current window width. +@item +integer number, limit width to that specified number of pixels. +@item +@code{nil}, do not limit the width. +@end itemize + +@vindex org-image-align +Org mode can left-align, center or right-align the display of inline +images. This setting is controlled (globally) by @code{org-image-align}. +Only standalone images are affected, corresponding to links with no +surrounding text in their paragraph except for whitespace. Its +value can be the following: +@itemize +@item +(default) The symbol @code{left}, which inserts the image where the +link appears in the buffer. +@item +The symbol @code{center}, which will preview links centered in the +Emacs window. +@item +The symbol @code{right}, which will preview links right-aligned in the +Emacs window. @end itemize +Inline image alignment can be specified for each link using the +@samp{#+ATTR.*} keyword if it matches an alignment specification like: +@example +#+ATTR_HTML: :align center +@end example +Org will use the alignment specification from any @samp{#+ATTR.*} +keyword, such as @samp{#+ATTR_HTML} or @samp{#+ATTR_LATEX}, but @samp{#+ATTR_ORG} +(if present) will override the others. For instance, this link +@example +#+ATTR_HTML: :align right +#+ATTR_ORG: :align center +[[/path/to/image/file.png]] +@end example +will be displayed centered in Emacs but exported right-aligned to +HTML@. + +When @samp{#+ATTR_ORG} is not set, inline image alignment is also read +from the @samp{:center} attribute supported by some export backends (like +HTML, @LaTeX{} and Beamer.) @vindex org-cycle-inline-images-display Inline images can also be displayed when cycling the folding state. @@ -12164,7 +12552,7 @@ Optionally, the caption can take the form: Even though images and tables are prominent examples of captioned structures, the same caption mechanism can apply to many others---e.g., @LaTeX{} equations, source code blocks. Depending on the -export back-end, those may or may not be handled. +export backend, those may or may not be handled. @node Horizontal Rules @section Horizontal Rules @@ -12187,7 +12575,7 @@ text. Markers always start with @samp{fn:}. For example: @example The Org website[fn:1] now looks a lot better than it used to. ... -[fn:55] The link is: https://orgmode.org +[fn:50] The link is: https://orgmode.org @end example Org mode extends the number-based syntax to @emph{named} footnotes and @@ -12280,10 +12668,11 @@ web, or share them with people not using Org. Org can convert and export documents to a variety of other formats while retaining as much structure (see @ref{Document Structure}) and markup (see @ref{Markup for Rich Contents}) as possible. +@cindex export backend @cindex export back-end The libraries responsible for translating Org files to other formats -are called @emph{back-ends}. Org ships with support for the following -back-ends: +are called @emph{backends}. Org ships with support for the following +backends: @itemize @item @@ -12311,15 +12700,15 @@ back-ends: Users can install libraries for additional formats from the Emacs packaging system. For easy discovery, these packages have a common naming scheme: @code{ox-NAME}, where @var{NAME} is a format. For -example, @code{ox-koma-letter} for @emph{koma-letter} back-end. More libraries +example, @code{ox-koma-letter} for @emph{koma-letter} backend. More libraries can be found in the @samp{org-contrib} repository (see @ref{Installation}). @vindex org-export-backends -Org only loads back-ends for the following formats by default: ASCII, -HTML, iCalendar, @LaTeX{}, and ODT@. Additional back-ends can be loaded +Org only loads backends for the following formats by default: ASCII, +HTML, iCalendar, @LaTeX{}, and ODT@. Additional backends can be loaded in either of two ways: by configuring the @code{org-export-backends} variable, or by requiring libraries in the Emacs init file. For -example, to load the Markdown back-end, add this to your Emacs config: +example, to load the Markdown backend, add this to your Emacs config: @lisp (require 'ox-md) @@ -12341,9 +12730,9 @@ example, to load the Markdown back-end, add this to your Emacs config: * Org Export:: Exporting to Org. * Texinfo Export:: Exporting to Texinfo. * iCalendar Export:: Exporting to iCalendar. -* Other Built-in Back-ends:: Exporting to a man page. +* Other Built-in Backends:: Exporting to a man page. * Advanced Export Configuration:: Fine-tuning the export output. -* Export in Foreign Buffers:: Author tables and lists in Org syntax. +* Export Region:: Author tables and lists in Org syntax. @end menu @node The Export Dispatcher @@ -12404,9 +12793,27 @@ by setting @code{org-export-async-init-file}. @kindex C-c C-e C-b Toggle body-only export. Useful for excluding headers and footers -in the export. Affects only those back-end formats that have +in the export. Affects only those backend formats that have sections like @samp{...} in HTML@. +@vindex org-export-body-only +To make body-only export the default, customize the variable +@code{org-export-body-only}. + +@item @kbd{C-f} +@kindex C-c C-e C-f + +Toggle force-publishing export. Publish functions normally only +publish changed files (see [BROKEN LINK: **Triggering Publication]). Forced +publishing causes files to be published even if their timestamps do +not indicate the file has been changed. + +@vindex org-export-force-publishing +To make forced publishing the default, customize the variable +@code{org-export-force-publishing}. (This is similar to +@code{org-publish-use-timestamps-flag}, but only affects the export +dispatcher.) + @item @kbd{C-s} @kindex C-c C-e C-s @@ -12427,6 +12834,10 @@ To make subtree export the default, customize the variable Toggle visible-only export. This is useful for exporting only certain parts of an Org document by adjusting the visibility of particular headings. See also @ref{Sparse Trees}. + +@vindex org-export-visible-only +To make visible-only export the default, customize the variable +@code{org-export-visible-only}. @end table @node Export Settings @@ -12446,14 +12857,14 @@ set at a specific level override options set at a more general level. @cindex @samp{SETUPFILE}, keyword In-buffer settings may appear anywhere in the file, either directly or indirectly through a file included using @samp{#+SETUPFILE: filename or -URL} syntax. Option keyword sets tailored to a particular back-end +URL} syntax. Option keyword sets tailored to a particular backend can be inserted from the export dispatcher (see @ref{The Export Dispatcher}) using the @samp{Insert template} command by pressing @kbd{#}. To insert keywords individually, a good way to make sure the keyword is correct is to type @samp{#+} and then to use @kbd{M-@key{TAB}}@footnote{Many desktops intercept @kbd{M-@key{TAB}} to switch windows. Use @kbd{C-M-i} or @kbd{@key{ESC} @key{TAB}} instead.} for completion. -The export keywords available for every back-end, and their equivalent +The export keywords available for every backend, and their equivalent global variables, include: @table @asis @@ -12471,7 +12882,7 @@ Entity responsible for output generation @item @samp{DATE} @cindex @samp{DATE}, keyword @vindex org-export-date-timestamp-format -A date or a time-stamp@footnote{ The variable +A date or a timestamp@footnote{ The variable @code{org-export-date-timestamp-format} defines how this timestamp are exported.}. @@ -12493,21 +12904,37 @@ configuration. See @ref{@LaTeX{} specific export settings}.}. @item @samp{SELECT_TAGS} @cindex @samp{SELECT_TAGS}, keyword @vindex org-export-select-tags -The default value is @samp{("export")}. When a tree is tagged with -@samp{export} (@code{org-export-select-tags}), Org selects that tree and its -subtrees for export. Org excludes trees with @samp{noexport} tags, see -below. When selectively exporting files with @samp{export} tags set, Org -does not export any text that appears before the first headline. +List of tags that will, if present, be selected for export. The +default value is @code{org-export-select-tags} @samp{("export")}. When a tree +is tagged with @samp{export}, Org selects that tree and its subtrees for +export, ignoring all the other sections that do not possess the +@samp{export} tag. + +When selectively exporting files with @samp{export} tags set, Org does +not export any text that appears before the first headline. + +Note that a file without the @samp{export} tags will export all its +sections. + +To select non-default tags for export, customize +@code{org-export-select-tags} (globally) or add @samp{#+SELECT_TAGS: tag1 + tag2} to the document. @item @samp{EXCLUDE_TAGS} @cindex @samp{EXCLUDE_TAGS}, keyword @vindex org-export-exclude-tags -The default value is @samp{("noexport")}. When a tree is tagged with -@samp{noexport} (@code{org-export-exclude-tags}), Org excludes that tree and -its subtrees from export. Entries tagged with @samp{noexport} are -unconditionally excluded from the export, even if they have an -@samp{export} tag. Even if a subtree is not exported, Org executes any -code blocks contained there. +List of tags that will be excluded from export. The default value is +@code{org-export-exclude-tags} @samp{("noexport")}. When a tree is tagged +with @samp{noexport}, Org excludes that tree and its subtrees from +export. + +Entries tagged with @samp{noexport} are unconditionally excluded from the +export, even if they have an @samp{export} tag. Even if a subtree is not +exported, Org executes any code blocks contained there. + +To select non-default tags for the exclusion, customize +@code{org-export-exclude-tags} (globally) or add @samp{#+EXCLUDE_TAGS: tag1 + tag2} to the document. @item @samp{TITLE} @cindex @samp{TITLE}, keyword @@ -12519,7 +12946,7 @@ lines. @cindex @samp{EXPORT_FILE_NAME}, keyword The name of the output file to be generated. Otherwise, Org generates the file name based on the buffer name and the extension -based on the back-end format. +based on the backend format. @end table The @samp{OPTIONS} keyword is a compact form. To configure multiple @@ -12574,6 +13001,11 @@ headlines (@code{org-export-with-archived-trees}). Toggle inclusion of author name into exported file (@code{org-export-with-author}). +@item @code{expand-links} +@vindex org-export-expand-links +Toggle expansion of environment variables in file paths +(@code{org-export-expand-links}). + @item @code{broken-links} @vindex org-export-with-broken-links Toggles if Org should continue exporting upon finding a broken @@ -12616,7 +13048,7 @@ Toggle the inclusion of footnotes (@code{org-export-with-footnotes}). @vindex org-export-headline-levels Set the number of headline levels for export (@code{org-export-headline-levels}). Below that level, headlines are -treated differently. In most back-ends, they become list items. +treated differently. In most backends, they become list items. @item @code{inline} @vindex org-export-with-inlinetasks @@ -12672,8 +13104,9 @@ verbatim (@code{org-export-with-latex}). @item @code{timestamp} @vindex org-export-time-stamp-file +@vindex org-export-timestamp-file Toggle inclusion of the creation time in the exported file -(@code{org-export-time-stamp-file}). +(@code{org-export-timestamp-file}). @item @code{title} @vindex org-export-with-title @@ -12731,7 +13164,7 @@ keyword: @cindex excluding entries from table of contents @cindex table of contents, exclude entries Org includes both numbered and unnumbered headlines in the table of -contents@footnote{At the moment, some export back-ends do not obey this +contents@footnote{At the moment, some export backends do not obey this specification. For example, @LaTeX{} export excludes every unnumbered headline from the table of contents.}. If you need to exclude an unnumbered headline, along with all its children, set the @samp{UNNUMBERED} property to @samp{notoc} @@ -12745,11 +13178,11 @@ value. @end example @cindex @samp{TOC}, keyword -Org normally inserts the table of contents directly before the first -headline of the file. To move the table of contents to a different -location, first turn off the default with @code{org-export-with-toc} -variable or with @samp{#+OPTIONS: toc:nil}. Then insert @samp{#+TOC: headlines -N} at the desired location(s). +Org normally inserts the table of contents in front of the exported +document. To move the table of contents to a different location, +first turn off the default with @code{org-export-with-toc} variable or with +@samp{#+OPTIONS: toc:nil}. Then insert @samp{#+TOC: headlines N} at the desired +location(s). @example #+OPTIONS: toc:nil @@ -12808,7 +13241,7 @@ the table of contents. @cindex export, include files @cindex @samp{INCLUDE}, keyword -During export, you can include the content of another file. For +@ref{Summary of the export process, , During export}, you can include the content of another file. For example, to include your @samp{.emacs} file, you could use: @example @@ -12817,16 +13250,20 @@ example, to include your @samp{.emacs} file, you could use: @noindent -The first parameter is the file name to include. The optional second -parameter specifies the block type: @samp{example}, @samp{export} or @samp{src}. The -optional third parameter specifies the source code language to use for -formatting the contents. This is relevant to both @samp{export} and @samp{src} -block types. - -If an included file is specified as having a markup language, Org -neither checks for valid syntax nor changes the contents in any way. -For example and source blocks, Org code-escapes the contents before -inclusion. +There are three positional arguments after the include keyword, they are: +@enumerate +@item +The file name, this is the sole mandatory argument. Org neither +checks for correctness or validates the content in any way. +@item +The block name to wrap the file content in. When this is +@samp{example}, @samp{export}, or @samp{src} the content is escaped by +@code{org-escape-code-in-string}. Arbitrary block names may be given, +however block names starting with @samp{:} must be quoted, i.e. @samp{":name"}. +@item +The source code language to use for formatting the contents. This is relevant +to both @samp{export} and @samp{src} block types. +@end enumerate @cindex @samp{minlevel}, include If an included file is not specified as having any markup language, @@ -12869,7 +13306,7 @@ ranges for @samp{:lines} keyword are relative to the requested element. Therefore, @example -#+INCLUDE: "./paper.org::*conclusion" :lines 1-20 +#+INCLUDE: "./paper.org::*conclusion" :lines "1-20" @end example @@ -12949,7 +13386,7 @@ turns @samp{@{@{@{gnustamp(linux)@}@}@}} into @samp{GNU/Linux} during export. Org recognizes macro references in following Org markup areas: paragraphs, headlines, verse blocks, tables cells and lists. Org also recognizes macro references in keywords, such as @samp{CAPTION}, @samp{TITLE}, -@samp{AUTHOR}, @samp{DATE}, and for some back-end specific export options. +@samp{AUTHOR}, @samp{DATE}, and for some backend specific export options. Org comes with following pre-defined macros: @@ -13109,7 +13546,7 @@ Export to a temporary buffer. Does not create a file. @anchor{ASCII specific export settings} @subheading ASCII specific export settings -The ASCII export back-end has one extra keyword for customizing ASCII +The ASCII export backend has one extra keyword for customizing ASCII output. Setting this keyword works similar to the general options (see @ref{Export Settings}). @@ -13131,7 +13568,7 @@ cut-off point where levels become lists, see @ref{Export Settings}. @anchor{Quoting ASCII text} @subheading Quoting ASCII text -To insert text within the Org file by the ASCII back-end, use one the +To insert text within the Org file by the ASCII backend, use one the following constructs, inline, keyword, or export block: @cindex @samp{ASCII}, keyword @@ -13142,7 +13579,7 @@ Inline text @@@@ascii:and additional text@@@@ within a paragraph. #+ASCII: Some text #+BEGIN_EXPORT ascii -Org exports text in this block only when using ASCII back-end. +Org exports text in this block only when using ASCII backend. #+END_EXPORT @end example @@ -13152,7 +13589,7 @@ Org exports text in this block only when using ASCII back-end. @cindex @samp{ATTR_ASCII}, keyword @cindex horizontal rules, in ASCII export -ASCII back-end recognizes only one attribute, @samp{:width}, which +ASCII backend recognizes only one attribute, @samp{:width}, which specifies the width of a horizontal rule in number of characters. The keyword and syntax for specifying widths is: @@ -13168,7 +13605,7 @@ keyword and syntax for specifying widths is: @cindex @samp{BEGIN_JUSTIFYLEFT} @cindex @samp{BEGIN_JUSTIFYRIGHT} -Besides @samp{#+BEGIN_CENTER} blocks (see @ref{Paragraphs}), ASCII back-end has +Besides @samp{#+BEGIN_CENTER} blocks (see @ref{Paragraphs}), ASCII backend has these two left and right justification blocks: @example @@ -13233,7 +13670,7 @@ PDF file. @node Beamer specific export settings @subsection Beamer specific export settings -Beamer export back-end has several additional keywords for customizing +Beamer export backend has several additional keywords for customizing Beamer output. These keywords work similar to the general options settings (see @ref{Export Settings}). @@ -13344,7 +13781,7 @@ When @samp{BEAMER_ACT} is set for a headline, Org export translates that headline as an overlay or action specification. When enclosed in square brackets, Org export makes the overlay specification a default. Use @samp{BEAMER_OPT} to set any options applicable to the -current Beamer frame or block. The Beamer export back-end wraps +current Beamer frame or block. The Beamer export backend wraps with appropriate angular or square brackets. It also adds the @samp{fragile} option for any code that may require a verbatim block. @@ -13365,8 +13802,8 @@ needs, use the @samp{BEAMER_ENV} property. @node Beamer specific syntax @subsection Beamer specific syntax -Since Org's Beamer export back-end is an extension of the @LaTeX{} -back-end, it recognizes other @LaTeX{} specific syntax---for example, +Since Org's Beamer export backend is an extension of the @LaTeX{} +backend, it recognizes other @LaTeX{} specific syntax---for example, @samp{#+LATEX:} or @samp{#+ATTR_LATEX:}. See @ref{@LaTeX{} Export}, for details. Beamer export wraps the table of contents generated with @samp{toc:t} @@ -13386,7 +13823,7 @@ Insert Beamer-specific code using the following constructs: #+BEAMER: \pause #+BEGIN_EXPORT beamer - Only Beamer export back-end exports this. + Only Beamer export backend exports this. #+END_EXPORT Text @@@@beamer:some code@@@@ within a paragraph. @@ -13501,6 +13938,7 @@ compatible with XHTML 1.0 strict standard. * HTML specific export settings:: Settings for HTML export. * HTML doctypes:: Exporting various (X)HTML flavors. * HTML preamble and postamble:: Inserting preamble and postamble. +* Bare HTML:: Exporting HTML without CSS, Javascript, etc. * Quoting HTML tags:: Using direct HTML in Org files. * Headlines in HTML export:: Formatting headlines. * Links in HTML export:: Inserting and formatting links. @@ -13651,7 +14089,7 @@ introduced with the HTML5 standard. To enable them, set @code{org-html-html5-fancy} to non-@code{nil}. Or use an @samp{OPTIONS} line in the file to set @samp{html5-fancy}. -HTML5 documents can now have arbitrary @samp{#+BEGIN} @dots{} @samp{#+END} blocks. +HTML5 documents can have arbitrary @samp{#+BEGIN} @dots{} @samp{#+END} blocks. For example: @example @@ -13730,11 +14168,34 @@ set to @code{auto} (its default value), which makes the HTML exporter build a postamble from looking up author's name, email address, creator's name, and date. +@node Bare HTML +@subsection Exporting to minimal HTML + +If you want to output a minimal HTML file, with no CSS, no Javascript, +no preamble or postamble, here are the variable you would need to set: + +@vindex org-html-head +@vindex org-html-head-extra +@vindex org-html-head-include-default-style +@vindex org-html-head-include-scripts +@vindex org-html-preamble +@vindex org-html-postamble +@vindex org-html-use-infojs +@lisp +(setq org-html-head "" + org-html-head-extra "" + org-html-head-include-default-style nil + org-html-head-include-scripts nil + org-html-preamble nil + org-html-postamble nil + org-html-use-infojs nil) +@end lisp + @node Quoting HTML tags @subsection Quoting HTML tags -The HTML export back-end transforms @samp{<} and @samp{>} to @samp{<} and @samp{>}. -To include raw HTML code in the Org file so the HTML export back-end +The HTML export backend transforms @samp{<} and @samp{>} to @samp{<} and @samp{>}. +To include raw HTML code in the Org file so the HTML export backend can insert that HTML code in the output, use this inline syntax: @samp{@@@@html:...@@@@}. For example: @@ -13776,25 +14237,25 @@ a @samp{href} attribute making the headlines link to themselves. @cindex internal links, in HTML export @cindex external links, in HTML export -The HTML export back-end transforms Org's internal links (see -@ref{Internal Links}) to equivalent HTML links in the output. The back-end +The HTML export backend transforms Org's internal links (see +@ref{Internal Links}) to equivalent HTML links in the output. The backend similarly handles Org's automatic links created by radio targets (see @ref{Radio Targets}) similarly. For Org links to external files, the -back-end transforms the links to @emph{relative} paths. +backend transforms the links to @emph{relative} paths. @vindex org-html-link-org-files-as-html -For Org links to other @samp{.org} files, the back-end automatically +For Org links to other @samp{.org} files, the backend automatically changes the file extension to @samp{.html} and makes file paths relative. If the @samp{.org} files have an equivalent @samp{.html} version at the same location, then the converted links should work without any further manual intervention. However, to disable this automatic path translation, set @code{org-html-link-org-files-as-html} to @code{nil}. When -disabled, the HTML export back-end substitutes the ID-based links in +disabled, the HTML export backend substitutes the ID-based links in the HTML output. For more about linking files when publishing to a directory, see @ref{Publishing links}. Org files can also have special directives to the HTML export -back-end. For example, by using @samp{#+ATTR_HTML} lines to specify new +backend. For example, by using @samp{#+ATTR_HTML} lines to specify new format attributes to @code{} or @code{} tags. This example shows changing the link's title and style: @@ -13810,7 +14271,7 @@ changing the link's title and style: @cindex tables, in HTML @vindex org-export-html-table-tag -The HTML export back-end uses @code{org-html-table-default-attributes} when +The HTML export backend uses @code{org-html-table-default-attributes} when exporting Org tables to HTML@. By default, the exporter does not draw frames and cell borders. To change for this for a table, use the following lines before the table in the Org file: @@ -13822,7 +14283,7 @@ following lines before the table in the Org file: #+ATTR_HTML: :border 2 :rules all :frame border @end example -The HTML export back-end preserves column groupings in Org tables (see +The HTML export backend preserves column groupings in Org tables (see @ref{Column Groups}) when exporting to HTML@. Additional options for customizing tables for HTML export. @@ -13864,20 +14325,20 @@ Non-@code{nil} formats column one in tables with header tags. @cindex images, inline in HTML @cindex inlining images in HTML -The HTML export back-end has features to convert Org image links to +The HTML export backend has features to convert Org image links to HTML inline images and HTML clickable image links. @vindex org-html-inline-images When the link in the Org file has no description, the HTML export -back-end by default in-lines that image. For example: +backend by default in-lines that image. For example: @samp{[[file:myimg.jpg]]} is in-lined, while @samp{[[file:myimg.jpg][the image]]} links to the text, @samp{the image}. For more details, see the variable @code{org-html-inline-images}. On the other hand, if the description part of the Org link is itself another link, such as @samp{file:} or @samp{http:} URL pointing to an image, the -HTML export back-end in-lines this image and links to the main image. -This Org syntax enables the back-end to link low-resolution thumbnail +HTML export backend in-lines this image and links to the main image. +This Org syntax enables the backend to link low-resolution thumbnail to the high-resolution version of the image, as shown in this example: @example @@ -13898,7 +14359,7 @@ accessibility standards. [[./img/a.jpg]] @end example -The HTML export back-end copies the @samp{http} links from the Org file +The HTML export backend copies the @samp{http} links from the Org file as-is. @node Math formatting in HTML export @@ -13968,12 +14429,12 @@ HTML was by using @samp{:textarea}. The advantage of this approach was that copying and pasting was built into browsers with simple JavaScript commands. Even editing before pasting was made simple. -The HTML export back-end can create such text areas. It requires an +The HTML export backend can create such text areas. It requires an @samp{#+ATTR_HTML} line as shown in the example below with the @samp{:textarea} option. This must be followed by either an example or a source code block. Other Org block types do not honor the @samp{:textarea} option. -By default, the HTML export back-end creates a text area 80 characters +By default, the HTML export backend creates a text area 80 characters wide and height just enough to fit the content. Override these defaults with @samp{:width} and @samp{:height} options on the @samp{#+ATTR_HTML} line. @@ -14072,7 +14533,7 @@ classes like for headlines, tables, etc. @vindex org-html-head @vindex org-html-head-extra @cindex @samp{HTML_INCLUDE_STYLE}, keyword -The HTML export back-end includes a compact default style in each +The HTML export backend includes a compact default style in each exported HTML file. To override the default style with another style, use these keywords in the Org file. They will replace the global defaults the HTML exporter uses. @@ -14202,7 +14663,7 @@ to your pages, configure the variable @code{org-export-html-use-infojs}. @cindex @LaTeX{} export @cindex PDF export -The @LaTeX{} export back-end can handle complex documents, incorporate +The @LaTeX{} export backend can handle complex documents, incorporate standard or custom @LaTeX{} document classes, generate documents using alternate @LaTeX{} engines, and produce fully linked PDF files with indexes, bibliographies, and tables of contents, destined for @@ -14214,13 +14675,20 @@ quick references to variables for the impatient: for engines, see @code{org-latex-pdf-process}; for packages, see @code{org-latex-default-packages-alist} and @code{org-latex-packages-alist}. -An important note about the @LaTeX{} export back-end: it is sensitive to +An important note about the @LaTeX{} export backend: it is sensitive to blank lines in the Org document. That's because @LaTeX{} itself depends on blank lines to tell apart syntactical elements, such as paragraphs. +The following sections expect users to be familiar with common @LaTeX{} +terminology. You may refer to @uref{https://tug.org/begin.html} to get +familiar with @LaTeX{} basics. Users with @LaTeX{} installed may also run +@samp{texdoc latex} from terminal to open @LaTeX{} introduction @footnote{ The +command will open a PDF file, which is also available for download +from @uref{http://mirrors.ctan.org/info/latex-doc-ptr/latex-doc-ptr.pdf}} + @menu * @LaTeX{}/PDF export commands:: For producing @LaTeX{} and PDF documents. -* @LaTeX{} specific export settings:: Unique to this @LaTeX{} back-end. +* @LaTeX{} specific export settings:: Unique to this @LaTeX{} backend. * @LaTeX{} header and sectioning:: Setting up the export file structure. * Quoting @LaTeX{} code:: Incorporating literal @LaTeX{} code. * Tables in @LaTeX{} export:: Options for exporting tables to @LaTeX{}. @@ -14272,10 +14740,10 @@ any buffer. @cindex xelatex @cindex lualatex @cindex @samp{LATEX_COMPILER}, keyword -The @LaTeX{} export back-end can use any of these @LaTeX{} engines: +The @LaTeX{} export backend can use any of these @LaTeX{} engines: @samp{pdflatex}, @samp{xelatex}, and @samp{lualatex}. These engines compile @LaTeX{} files with different compilers, packages, and output options. The -@LaTeX{} export back-end finds the compiler version to use from +@LaTeX{} export backend finds the compiler version to use from @code{org-latex-compiler} variable or the @samp{#+LATEX_COMPILER} keyword in the Org file. See the docstring for the @code{org-latex-default-packages-alist} for loading packages with certain @@ -14287,7 +14755,7 @@ as latexmk, can select the correct bibliography compiler.}. @node @LaTeX{} specific export settings @subsection @LaTeX{} specific export settings -The @LaTeX{} export back-end has several additional keywords for +The @LaTeX{} export backend has several additional keywords for customizing @LaTeX{} output. Setting these keywords works similar to the general options (see @ref{Export Settings}). @@ -14307,8 +14775,11 @@ multiple @samp{DESCRIPTION} keywords for long descriptions. @cindex @samp{LANGUAGE}, keyword @vindex org-latex-packages-alist @vindex org-latex-language-alist +@vindex org-export-default-language -Language code of the primary document language. +Language code of the primary document language. When @samp{LANGUAGE} +keyword is not not specified use the value of +@code{org-export-default-language} (by default - @samp{en}, American English) The list of language codes supported by Org is stored in the variable @code{org-latex-language-alist}. @@ -14333,14 +14804,14 @@ pdf@LaTeX{}): @vindex org-latex-classes This is @LaTeX{} document class, such as @emph{article}, @emph{report}, @emph{book}, and so on, which contain predefined preamble and headline level -mapping that the @LaTeX{} export back-end needs. The back-end reads +mapping that the @LaTeX{} export backend needs. The backend reads the default class name from the @code{org-latex-default-class} variable. Org has @emph{article} as the default class. A valid default class must be an element of @code{org-latex-classes}. @item @samp{LATEX_CLASS_OPTIONS} @cindex @samp{LATEX_CLASS_OPTIONS}, keyword -Options the @LaTeX{} export back-end uses when calling the @LaTeX{} +Options the @LaTeX{} export backend uses when calling the @LaTeX{} document class. @item @samp{LATEX_COMPILER} @@ -14392,12 +14863,12 @@ The following sections have further details. @cindex header, for @LaTeX{} files @cindex sectioning structure, for @LaTeX{} export -The @LaTeX{} export back-end converts the first three of Org's outline +The @LaTeX{} export backend converts the first three of Org's outline levels into @LaTeX{} headlines. The remaining Org levels are exported as lists. To change this globally for the cut-off point between levels and lists, (see @ref{Export Settings}). -By default, the @LaTeX{} export back-end uses the @emph{article} class. +By default, the @LaTeX{} export backend uses the @emph{article} class. @vindex org-latex-default-class @vindex org-latex-classes @@ -14417,7 +14888,7 @@ custom sectioning or custom classes. @cindex @samp{LATEX_CLASS_OPTIONS}, keyword @cindex @samp{EXPORT_LATEX_CLASS}, property @cindex @samp{EXPORT_LATEX_CLASS_OPTIONS}, property -The @LaTeX{} export back-end sends the @samp{LATEX_CLASS_OPTIONS} keyword and +The @LaTeX{} export backend sends the @samp{LATEX_CLASS_OPTIONS} keyword and @samp{EXPORT_LATEX_CLASS_OPTIONS} property as options to the @LaTeX{} @code{\documentclass} macro. The options and the syntax for specifying them, including enclosing them in square brackets, follow @LaTeX{} @@ -14430,10 +14901,10 @@ conventions. @cindex @samp{LATEX_HEADER}, keyword @cindex @samp{LATEX_HEADER_EXTRA}, keyword -The @LaTeX{} export back-end appends values from @samp{LATEX_HEADER} and +The @LaTeX{} export backend appends values from @samp{LATEX_HEADER} and @samp{LATEX_HEADER_EXTRA} keywords to the @LaTeX{} header. The docstring for @code{org-latex-classes} explains in more detail. Also note that @LaTeX{} -export back-end does not append @samp{LATEX_HEADER_EXTRA} to the header +export backend does not append @samp{LATEX_HEADER_EXTRA} to the header when previewing @LaTeX{} snippets (see @ref{Previewing @LaTeX{} fragments}). A sample Org file with the above headers: @@ -14500,9 +14971,10 @@ This would produce in @LaTeX{} (with the actual @samp{polyglossia} syntax): @node Quoting @LaTeX{} code @subsection Quoting @LaTeX{} code -The @LaTeX{} export back-end can insert any arbitrary @LaTeX{} code, see -@ref{Embedded @LaTeX{}}. There are three ways to embed such code in the Org -file and they all use different quoting syntax. +When the available @LaTeX{} export customizations are not sufficient to +fine-tune the desired output, it is possible to insert any arbitrary +@LaTeX{} code (see @ref{Embedded @LaTeX{}}). There are three ways to embed such +code in the Org file and they all use different quoting syntax. @cindex inline, in @LaTeX{} export Inserting in-line quoted with @@ symbols: @@ -14521,7 +14993,7 @@ Inserting as one or more keyword lines in the Org file: @cindex @samp{BEGIN_EXPORT latex} -Inserting as an export block in the Org file, where the back-end +Inserting as an export block in the Org file, where the backend exports any code between begin and end markers: @example @@ -14535,7 +15007,7 @@ exports any code between begin and end markers: @cindex tables, in @LaTeX{} export -The @LaTeX{} export back-end can pass several @LaTeX{} attributes for table +The @LaTeX{} export backend can pass several @LaTeX{} attributes for table contents and layout. Besides specifying a label (see @ref{Internal Links}) and a caption (see @ref{Captions}), the other valid @LaTeX{} attributes include: @@ -14543,26 +15015,26 @@ include: @table @asis @item @samp{:mode} @vindex org-latex-default-table-mode -The @LaTeX{} export back-end wraps the table differently depending on +The @LaTeX{} export backend wraps the table differently depending on the mode for accurate rendering of math symbols. Mode is either @samp{table}, @samp{math}, @samp{inline-math}, @samp{verbatim} or @samp{tabbing}. -For @samp{math} or @samp{inline-math} mode, @LaTeX{} export back-end wraps the +For @samp{math} or @samp{inline-math} mode, @LaTeX{} export backend wraps the table in a math environment, but every cell in it is exported as-is. For @samp{tabbing} the @LaTeX{} tabbing environment is used and the correct tabbing delimiters @samp{\>} are used. -The @LaTeX{} export back-end determines the default mode from -@code{org-latex-default-table-mode}. The @LaTeX{} export back-end merges +The @LaTeX{} export backend determines the default mode from +@code{org-latex-default-table-mode}. The @LaTeX{} export backend merges contiguous tables in the same mode into a single environment. @item @samp{:environment} @vindex org-latex-default-table-environment Set the default @LaTeX{} table environment for the @LaTeX{} export -back-end to use when exporting Org tables. Common @LaTeX{} table +backend to use when exporting Org tables. Common @LaTeX{} table environments are provided by these packages: tabularx, longtable, array, tabu, and bmatrix. For packages, such as tabularx and tabu, or any newer replacements, include them in the -@code{org-latex-packages-alist} variable so the @LaTeX{} export back-end can +@code{org-latex-packages-alist} variable so the @LaTeX{} export backend can insert the appropriate load package headers in the converted @LaTeX{} file. Look in the docstring for the @code{org-latex-packages-alist} variable for configuring these packages for @LaTeX{} snippet previews, @@ -14587,12 +15059,12 @@ any arbitrary value, for example a user-defined float type with the @LaTeX{} floats can also have additional layout @samp{:placement} attributes. These are the usual @samp{[h t b p ! H]} permissions specified in square brackets. Note that for @samp{:float sideways} -tables, the @LaTeX{} export back-end ignores @samp{:placement} attributes. +tables, the @LaTeX{} export backend ignores @samp{:placement} attributes. @item @samp{:align} @itemx @samp{:font} @itemx @samp{:width} -The @LaTeX{} export back-end uses these attributes for regular tables +The @LaTeX{} export backend uses these attributes for regular tables to set their alignments, fonts, and widths. @item @samp{:options} @@ -14603,7 +15075,7 @@ tabularray @LaTeX{} package, provides this structure. For example: @samp{:options remark@{Note@}=@{note@},remark@{Source@}=@{source@}}. @item @samp{:spread} -When @samp{:spread} is non-@code{nil}, the @LaTeX{} export back-end spreads or +When @samp{:spread} is non-@code{nil}, the @LaTeX{} export backend spreads or shrinks the table by the @samp{:width} for tabu and longtabu environments. @samp{:spread} has no effect if @samp{:width} is not set. @@ -14622,10 +15094,10 @@ only. @item @samp{:math-prefix} @itemx @samp{:math-suffix} @itemx @samp{:math-arguments} -The @LaTeX{} export back-end inserts @samp{:math-prefix} string value in -a math environment before the table. The @LaTeX{} export back-end +The @LaTeX{} export backend inserts @samp{:math-prefix} string value in +a math environment before the table. The @LaTeX{} export backend inserts @samp{:math-suffix} string value in a math environment after the -table. The @LaTeX{} export back-end inserts @samp{:math-arguments} string +table. The @LaTeX{} export backend inserts @samp{:math-arguments} string value between the macro name and the table's contents. @samp{:math-arguments} comes in use for matrix macros that require more than one argument, such as @samp{qbordermatrix}. @@ -14663,13 +15135,13 @@ Set the caption with the @LaTeX{} command @cindex inlining images in LaTeX @cindex @samp{ATTR_LATEX}, keyword -The @LaTeX{} export back-end processes image links in Org files that do +The @LaTeX{} export backend processes image links in Org files that do not have descriptions, such as these links @samp{[[file:img.jpg]]} or @samp{[[./img.jpg]]}, as direct image insertions in the final PDF output. In the PDF, they are no longer links but actual images embedded on the -page. The @LaTeX{} export back-end uses @samp{\includegraphics} macro to +page. The @LaTeX{} export backend uses @samp{\includegraphics} macro to insert the image. But for TikZ (@uref{https://sourceforge.net/projects/pgf/}) -images, the back-end uses an @code{\input} macro wrapped within +images, the backend uses an @code{\input} macro wrapped within a @code{tikzpicture} environment. For specifying image @samp{:width}, @samp{:height}, @samp{:scale} and other @samp{:options}, @@ -14691,7 +15163,7 @@ overrides the default @samp{#+CAPTION} value: @end example When captions follow the method as described in @ref{Captions}, the @LaTeX{} -export back-end wraps the picture in a floating @samp{figure} environment. +export backend wraps the picture in a floating @samp{figure} environment. To float an image without specifying a caption, set the @samp{:float} attribute to one of the following: @@ -14700,7 +15172,7 @@ attribute to one of the following: For a default @samp{figure} environment. @item @samp{multicolumn} -To span the image across multiple columns of a page; the back-end +To span the image across multiple columns of a page; the backend wraps the image in a @samp{figure*} environment. @item @samp{wrap} @@ -14731,19 +15203,19 @@ placement. @vindex org-latex-images-centered @cindex center image in LaTeX export @cindex image, centering in LaTeX export -The @LaTeX{} export back-end centers all images by default. Setting +The @LaTeX{} export backend centers all images by default. Setting @samp{:center} to @samp{nil} disables centering. To disable centering globally, set @code{org-latex-images-centered} to @samp{nil}. Set the @samp{:comment-include} attribute to non-@code{nil} value for the @LaTeX{} -export back-end to comment out the @samp{\includegraphics} macro. +export backend to comment out the @samp{\includegraphics} macro. @node Plain lists in @LaTeX{} export @subsection Plain lists in @LaTeX{} export @cindex plain lists, in @LaTeX{} export @cindex @samp{ATTR_LATEX}, keyword -The @LaTeX{} export back-end accepts the @samp{environment} and @samp{options} +The @LaTeX{} export backend accepts the @samp{environment} and @samp{options} attributes for plain lists. Both attributes work together for customizing lists, as shown in the examples: @@ -14778,7 +15250,16 @@ four: @cindex source blocks, in @LaTeX{} export @cindex @samp{ATTR_LATEX}, keyword -The @LaTeX{} export back-end can make source code blocks into floating +@vindex org-latex-src-block-backend +@LaTeX{} export backend provides multiple ways to render src blocks in +@LaTeX{}, according to the value of @code{org-latex-src-block-backend}. The +default value @samp{verbatim} renders the src code verbatim, without any +extra styling. Alternative values allow more colorful styling, but +require additional @LaTeX{} (@samp{listings}, @samp{minted}), system (@samp{minted}), or +Emacs (@samp{engraved}) packages. See the @code{org-latex-src-block-backend} +docstring for more details. + +The @LaTeX{} export backend can make source code blocks into floating objects through the attributes @samp{:float} and @samp{:options}. For @samp{:float}: @table @asis @@ -14804,7 +15285,7 @@ blocks that may not fit on a page. @vindex org-latex-listings-options @vindex org-latex-minted-options @vindex org-latex-engraved-options -The @LaTeX{} export back-end passes string values in @samp{:options} to @LaTeX{} +The @LaTeX{} export backend passes string values in @samp{:options} to @LaTeX{} packages for customization of that specific source block. In the example below, the @samp{:options} are set for Engraved or Minted. Minted is a source code highlighting @LaTeX{} package with many configurable @@ -14834,7 +15315,7 @@ variables. @cindex verbatim blocks, in @LaTeX{} export @cindex @samp{ATTR_LATEX}, keyword -The @LaTeX{} export back-end wraps the contents of example blocks in +The @LaTeX{} export backend wraps the contents of example blocks in a @samp{verbatim} environment. To change this behavior to use another environment globally, specify an appropriate export filter (see @ref{Advanced Export Configuration}). To change this behavior to use @@ -14856,8 +15337,8 @@ to specify a custom environment. @cindex proof, in @LaTeX{} export @cindex @samp{ATTR_LATEX}, keyword -For other special blocks in the Org file, the @LaTeX{} export back-end -makes a special environment of the same name. The back-end also takes +For other special blocks in the Org file, the @LaTeX{} export backend +makes a special environment of the same name. The backend also takes @samp{:options}, if any, and appends as-is to that environment's opening string. For example: @@ -14904,7 +15385,7 @@ example: @cindex horizontal rules, in @LaTeX{} export @cindex @samp{ATTR_LATEX}, keyword -The @LaTeX{} export back-end converts horizontal rules by the specified +The @LaTeX{} export backend converts horizontal rules by the specified @samp{:width} and @samp{:thickness} attributes. For example: @example @@ -14918,10 +15399,10 @@ The @LaTeX{} export back-end converts horizontal rules by the specified @cindex verse blocks, in @LaTeX{} export @cindex @samp{ATTR_LATEX}, keyword -The @LaTeX{} export back-end accepts four attributes for verse blocks: -@samp{:lines}, @samp{:center}, @samp{:versewidth} and @samp{:latexcode}. The three first -require the external @LaTeX{} package @samp{verse.sty}, which is an extension -of the standard @LaTeX{} environment. +The @LaTeX{} export backend accepts five attributes for verse blocks: +@samp{:lines}, @samp{:center}, @samp{:versewidth}, @samp{:latexcode} and @samp{:literal}. The +three first require the external @LaTeX{} package @samp{verse.sty}, which is +an extension of the standard @LaTeX{} environment. @table @asis @item @samp{:lines} @@ -14938,6 +15419,17 @@ verse. @item @samp{:latexcode} It accepts any arbitrary @LaTeX{} code that can be included within a @LaTeX{} @samp{verse} environment. +@item @samp{:literal} +With value t, all blank lines are preserved and +exported as @samp{\vspace*@{\baselineskip@}}, including the blank lines +before or after contents. Note that without the @samp{:literal} +attribute, one or more blank lines between stanzas are exported as a +single blank line, and any blank lines before or after the content +are removed, which is more consistent with the syntax of the @LaTeX{} +`verse' environment, and the one provided by the @samp{verse} package. +If the @samp{verse} package is loaded, the vertical spacing between all +stanzas can be controlled by the global length @samp{\stanzaskip} (see +@uref{https://www.ctan.org/pkg/verse}). @end table A complete example with Shakespeare's first sonnet: @@ -14970,7 +15462,7 @@ To eat the world’s due, by the grave and thee. @cindex @samp{ATTR_LATEX}, keyword @cindex org-latex-default-quote-environment -The @LaTeX{} export back-end accepts two attributes for quote blocks: +The @LaTeX{} export backend accepts two attributes for quote blocks: @samp{:environment}, for an arbitrary quoting environment (the default value is that of @code{org-latex-default-quote-environment}: @code{"quote"}) and @samp{:options}. For example, to choose the environment @samp{quotation}, @@ -15008,12 +15500,17 @@ some text in German... @cindex Markdown export -The Markdown export back-end, ``md'', converts an Org file to Markdown +The Markdown export backend, ``md'', converts an Org file to Markdown format, as defined at @uref{https://daringfireball.net/projects/markdown/}. +This is the original Markdown specification, developed by John Gruber +and Aaron Swartz. -Since it is built on top of the HTML back-end (see @ref{HTML Export}), it -converts every Org construct not defined in Markdown syntax, such as -tables, to HTML@. +Since ``md'' backend is built on top of the HTML backend (see @ref{HTML Export}), it converts every Org construct not defined in Markdown +syntax, such as tables, to HTML@. + +Do note that the original markdown syntax has differences with other +commonly used Markdown flavors. See +@uref{https://en.wikipedia.org/wiki/Markdown} for more details. @anchor{Markdown export commands} @subheading Markdown export commands @@ -15040,10 +15537,12 @@ Export as a text file with Markdown syntax, then open it. @vindex org-md-headline-style Based on @code{org-md-headline-style}, Markdown export can generate -headlines of both @emph{atx} and @emph{setext} types. @emph{atx} limits headline -levels to two whereas @emph{setext} limits headline levels to six. Beyond -these limits, the export back-end converts headlines to lists. To set -a limit to a level before the absolute limit (see @ref{Export Settings}). +headlines of both @emph{atx} and @emph{setext} types. @emph{setext} limits headline +levels to two whereas @emph{atx} limits headline levels to six. @emph{mixed} +exports headline levels one and two in @emph{setext}-style, and headline +levels three through six as @emph{atx}-style headlines. Beyond these +limits, the export backend converts headlines to lists. To set a +limit to a level before the absolute limit (see @ref{Export Settings}). @node OpenDocument Text Export @section OpenDocument Text Export @@ -15053,7 +15552,7 @@ a limit to a level before the absolute limit (see @ref{Export Settings}). @cindex export, OpenDocument @cindex LibreOffice -The ODT export back-end handles creating of OpenDocument Text (ODT) +The ODT export backend handles creating of OpenDocument Text (ODT) format. Documents created by this exporter use the @cite{OpenDocument-v1.2 specification}@footnote{ See @uref{https://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html, Open @@ -15080,7 +15579,7 @@ and are compatible with LibreOffice 3.4. @cindex zip -The ODT export back-end relies on the zip program to create the final +The ODT export backend relies on the zip program to create the final compressed ODT output. Check if @samp{zip} is locally available and executable. Without it, export cannot finish. @@ -15097,15 +15596,15 @@ Export as OpenDocument Text file. @vindex org-odt-preferred-output-format If @code{org-odt-preferred-output-format} is specified, the ODT export -back-end automatically converts the exported file to that format. +backend automatically converts the exported file to that format. For @samp{myfile.org}, Org exports to @samp{myfile.odt}, overwriting without -warning. The ODT export back-end exports a region only if a region +warning. The ODT export backend exports a region only if a region was active. -If the selected region is a single tree, the ODT export back-end +If the selected region is a single tree, the ODT export backend makes the tree head the document title. Incidentally, @kbd{C-c @@} selects the current subtree. If the tree head entry has, or -inherits, an @samp{EXPORT_FILE_NAME} property, the ODT export back-end +inherits, an @samp{EXPORT_FILE_NAME} property, the ODT export backend uses that for file name. @item @kbd{C-c C-e o O} @@ -15120,20 +15619,20 @@ converted file instead. See @ref{Automatically exporting to other formats}. @node ODT specific export settings @subsection ODT specific export settings -The ODT export back-end has several additional keywords for +The ODT export backend has several additional keywords for customizing ODT output. Setting these keywords works similar to the general options (see @ref{Export Settings}). @table @asis @item @samp{DESCRIPTION} @cindex @samp{DESCRIPTION}, keyword -This is the document's description, which the ODT export back-end +This is the document's description, which the ODT export backend inserts as document metadata. For long descriptions, use multiple lines, prefixed with @samp{DESCRIPTION}. @item @samp{KEYWORDS} @cindex @samp{KEYWORDS}, keyword -The keywords for the document. The ODT export back-end inserts the +The keywords for the document. The ODT export backend inserts the description along with author name, keywords, and related file metadata as metadata in the output file. Use multiple @samp{KEYWORDS} if necessary. @@ -15141,7 +15640,7 @@ necessary. @item @samp{ODT_STYLES_FILE} @cindex @samp{ODT_STYLES_FILE}, keyword @vindex org-odt-styles-file -The ODT export back-end uses the @code{org-odt-styles-file} by default. +The ODT export backend uses the @code{org-odt-styles-file} by default. See @ref{Applying custom styles} for details. @item @samp{SUBTITLE} @@ -15152,7 +15651,7 @@ The document subtitle. @node Extending ODT export @subsection Extending ODT export -The ODT export back-end can produce documents in other formats besides +The ODT export backend can produce documents in other formats besides ODT using a specialized ODT converter process. Its common interface works with popular converters to produce formats such as @samp{doc}, or convert a document from one format, say @samp{csv}, to another format, say @@ -15171,14 +15670,14 @@ other converters may be substituted here. See @ref{Configuring a document conve @vindex org-odt-preferred-output-format If ODT format is just an intermediate step to get to other formats, such as @samp{doc}, @samp{docx}, @samp{rtf}, or @samp{pdf}, etc., then extend the ODT -export back-end to directly produce that format. Specify the final +export backend to directly produce that format. Specify the final format in the @code{org-odt-preferred-output-format} variable. This is one way to extend (see @ref{ODT export commands}). @anchor{Converting between document formats} @subsubheading Converting between document formats -The Org export back-end is made to be inter-operable with a wide range +The Org export backend is made to be inter-operable with a wide range of text document format converters. Newer generation converters, such as LibreOffice and Pandoc, can handle hundreds of formats at once. Org provides a consistent interaction with whatever converter is @@ -15197,7 +15696,7 @@ a prefix argument, opens the newly produced file. @cindex styles, custom @cindex template, custom -The ODT export back-end comes with many OpenDocument styles (see +The ODT export backend comes with many OpenDocument styles (see @ref{Working with OpenDocument style files}). To expand or further customize these built-in style sheets, either edit the style sheets directly or generate them using an application such as LibreOffice. @@ -15247,7 +15746,7 @@ or @anchor{Using third-party styles and templates} @subsubheading Using third-party styles and templates -The ODT export back-end relies on many templates and style names. +The ODT export backend relies on many templates and style names. Using third-party styles and templates can lead to mismatches. Templates derived from built-in ODT templates and styles seem to have fewer problems. @@ -15273,18 +15772,18 @@ with a cross-reference and sequence number of the labeled entity. See @cindex tables, in ODT export -The ODT export back-end handles native Org mode tables (see @ref{Tables}) +The ODT export backend handles native Org mode tables (see @ref{Tables}) and simple @samp{table.el} tables. Complex @samp{table.el} tables having column or row spans are not supported. Such tables are stripped from the exported document. -By default, the ODT export back-end exports a table with top and +By default, the ODT export backend exports a table with top and bottom frames and with ruled lines separating row and column groups (see @ref{Column Groups}). All tables are typeset to occupy the same -width. The ODT export back-end honors any table alignments and +width. The ODT export backend honors any table alignments and relative widths for columns (see @ref{Column Width and Alignment}). -Note that the ODT export back-end interprets column widths as weighted +Note that the ODT export backend interprets column widths as weighted ratios, the default weight being 1. @cindex @samp{ATTR_ODT}, keyword @@ -15322,7 +15821,7 @@ them with a table using the @samp{ATTR_ODT} keyword. See @ref{Customizing table @anchor{Embedding images} @subsubheading Embedding images -The ODT export back-end processes image links in Org files that do not +The ODT export backend processes image links in Org files that do not have descriptions, such as these links @samp{[[file:img.jpg]]} or @samp{[[./img.jpg]]}, as direct image insertions in the final output. Either of these examples works: @@ -15358,13 +15857,13 @@ attribute. @cindex identify, ImageMagick @vindex org-odt-pixels-per-inch -The ODT export back-end starts with establishing the size of the image +The ODT export backend starts with establishing the size of the image in the final document. The dimensions of this size are measured in -centimeters. The back-end then queries the image file for its -dimensions measured in pixels. For this measurement, the back-end +centimeters. The backend then queries the image file for its +dimensions measured in pixels. For this measurement, the backend relies on ImageMagick's identify program or Emacs @code{create-image} and @code{image-size} API@. ImageMagick is the preferred choice for large file -sizes or frequent batch operations. The back-end then converts the +sizes or frequent batch operations. The backend then converts the pixel dimensions using @code{org-odt-pixels-per-inch} into the familiar 72 dpi or 96 dpi. The default value for this is in @code{display-pixels-per-inch}, which can be tweaked for better results @@ -15411,7 +15910,7 @@ original height:width ratio, do the following: @subsubheading Anchoring of images @cindex @samp{ATTR_ODT}, keyword -The ODT export back-end can anchor images to @samp{as-char}, @samp{paragraph}, +The ODT export backend can anchor images to @samp{as-char}, @samp{paragraph}, or @samp{page}. Set the preferred anchor using the @samp{:anchor} property of the @samp{ATTR_ODT} line. @@ -15478,7 +15977,7 @@ instead, @lisp (setq org-latex-to-mathml-convert-command - "latexmlmath \"%i\" --presentationmathml=%o") + "latexmlmath %i --presentationmathml=%o") @end lisp To quickly verify the reliability of the @LaTeX{}-to-MathML @@ -15589,8 +16088,8 @@ Illustration 2: Bell curve @node Literal examples in ODT export @subsection Literal examples in ODT export -The ODT export back-end supports literal examples (see @ref{Literal Examples}) with full fontification. Internally, the ODT export -back-end relies on @samp{htmlfontify.el} to generate the style definitions +The ODT export backend supports literal examples (see @ref{Literal Examples}) with full fontification. Internally, the ODT export +backend relies on @samp{htmlfontify.el} to generate the style definitions needed for fancy listings. The auto-generated styles get @samp{OrgSrc} prefix and inherit colors from the faces used by Emacs Font Lock library for that source language. @@ -15606,7 +16105,7 @@ To turn off fontification of literal examples, customize the @node Advanced topics in ODT export @subsection Advanced topics in ODT export -The ODT export back-end has extensive features useful for power users +The ODT export backend has extensive features useful for power users and frequent uses of ODT formats. @anchor{Configuring a document converter} @@ -15616,7 +16115,7 @@ and frequent uses of ODT formats. @cindex doc, docx, rtf @cindex converter -The ODT export back-end works with popular converters with little or +The ODT export backend works with popular converters with little or no extra configuration. See @ref{Extending ODT export}. The following is for unsupported converters or tweaking existing defaults. @@ -15695,7 +16194,7 @@ factory styles used by the exporter. @table @asis @item @code{org-odt-styles-file} -The ODT export back-end uses the file pointed to by this variable, +The ODT export backend uses the file pointed to by this variable, such as @samp{styles.xml}, for the final output. It can take one of the following values: @@ -15727,7 +16226,7 @@ final output. @anchor{Creating one-off styles} @subsubheading Creating one-off styles -The ODT export back-end can read embedded raw OpenDocument XML from +The ODT export backend can read embedded raw OpenDocument XML from the Org file. Such direct formatting is useful for one-off instances. @table @asis @@ -15752,7 +16251,7 @@ below: @item Embedding a one-line OpenDocument XML @cindex @samp{ODT}, keyword -The ODT export back-end can read one-liner options with @samp{#+ODT:} in +The ODT export backend can read one-liner options with @samp{#+ODT:} in the Org file. For example, to force a page break: @example @@ -15771,7 +16270,7 @@ style as shown below. @end example @item Embedding a block of OpenDocument XML -The ODT export back-end can also read ODT export blocks for +The ODT export backend can also read ODT export blocks for OpenDocument XML@. Such blocks use the @samp{#+BEGIN_EXPORT odt} @dots{} @samp{#+END_EXPORT} constructs. @@ -15972,15 +16471,15 @@ schema-sensitive editing---of XML files: @ref{Introduction,,,nxml-mode,}. @vindex org-export-odt-schema-dir Customize @code{org-odt-schema-dir} to point to a directory with OpenDocument RNC files and the needed schema-locating rules. The ODT -export back-end takes care of updating the +export backend takes care of updating the @code{rng-schema-locating-files}. @node Org Export @section Org Export @cindex Org export -@emph{org} export back-end creates a normalized version of the Org document -in current buffer. The exporter evaluates Babel code (see @ref{Evaluating Code Blocks}) and removes content specific to other back-ends. +@emph{org} export backend creates a normalized version of the Org document +in current buffer. The exporter evaluates Babel code (see @ref{Evaluating Code Blocks}) and removes content specific to other backends. @anchor{Org export commands} @subheading Org export commands @@ -16040,7 +16539,7 @@ file. To generate other formats, such as DocBook, customize the @node Texinfo specific export settings @subsection Texinfo specific export settings -The Texinfo export back-end has several additional keywords for +The Texinfo export backend has several additional keywords for customizing Texinfo output. Setting these keywords works similar to the general options (see @ref{Export Settings}). @@ -16073,15 +16572,24 @@ Arbitrary lines inserted after the end of the header. @item @samp{TEXINFO_DIR_CATEGORY} @cindex @samp{TEXINFO_DIR_CATEGORY}, keyword -The directory category of the document. +The directory category of the document. Defaults to @code{Misc}. + +@item @samp{TEXINFO_DIR_NAME} +@cindex @samp{TEXINFO_DIR_NAME}, keyword +The directory name of the document. +This is the short name under which the @code{m} command will find your +manual in the main Info directory. It defaults to the base name of +the Texinfo file. -@item @samp{TEXINFO_DIR_TITLE} -@cindex @samp{TEXINFO_DIR_TITLE}, keyword -The directory title of the document. +The full form of the Texinfo entry is @code{* DIRNAME: NODE.} where @code{NODE} +is usually just @code{(FILENAME)}. Normally this option only provides the +@code{DIRNAME} part, but if you need more control, it can also be the full +entry (recognized by the presence of parentheses or a leading ~* ~). @item @samp{TEXINFO_DIR_DESC} @cindex @samp{TEXINFO_DIR_DESC}, keyword The directory description of the document. +Defaults to the title of the document. @item @samp{TEXINFO_PRINTED_TITLE} @cindex @samp{TEXINFO_PRINTED_TITLE}, keyword @@ -16092,7 +16600,7 @@ The printed title of the document. @subsection Texinfo file header @cindex @samp{TEXINFO_FILENAME}, keyword -After creating the header for a Texinfo file, the Texinfo back-end +After creating the header for a Texinfo file, the Texinfo backend automatically generates a name and destination path for the Info file. To override this default with a more sensible path and name, specify the @samp{TEXINFO_FILENAME} keyword. @@ -16137,7 +16645,7 @@ keywords. They have to be set in raw Texinfo code. @cindex @samp{COPYING}, property Copying material is defined in a dedicated headline with a non-@code{nil} -@samp{COPYING} property. The back-end inserts the contents within +@samp{COPYING} property. The backend inserts the contents within a @samp{@@copying} command at the beginning of the document. The heading itself does not appear in the structure of the document. @@ -16162,11 +16670,11 @@ Copyright information is printed on the back of the title page. @cindex @code{install-info}, in Texinfo export @cindex @samp{TEXINFO_DIR_CATEGORY}, keyword -@cindex @samp{TEXINFO_DIR_TITLE}, keyword +@cindex @samp{TEXINFO_DIR_NAME}, keyword @cindex @samp{TEXINFO_DIR_DESC}, keyword The end result of the Texinfo export process is the creation of an Info file. This Info file's metadata has variables for category, -title, and description: @samp{TEXINFO_DIR_CATEGORY}, @samp{TEXINFO_DIR_TITLE}, +title, and description: @samp{TEXINFO_DIR_CATEGORY}, @samp{TEXINFO_DIR_NAME}, and @samp{TEXINFO_DIR_DESC} keywords that establish where in the Info hierarchy the file fits. @@ -16174,7 +16682,7 @@ Here is an example that writes to the Info directory file: @example #+TEXINFO_DIR_CATEGORY: Emacs -#+TEXINFO_DIR_TITLE: Org Mode: (org) +#+TEXINFO_DIR_NAME: Org Mode #+TEXINFO_DIR_DESC: Outline-based notes management and organizer @end example @@ -16184,7 +16692,7 @@ Here is an example that writes to the Info directory file: @vindex org-texinfo-classes @vindex org-texinfo-default-class @cindex @samp{TEXINFO_CLASS}, keyword -The Texinfo export back-end uses a pre-defined scheme to convert Org +The Texinfo export backend uses a pre-defined scheme to convert Org headlines to equivalent Texinfo structuring commands. A scheme like this maps top-level headlines to numbered chapters tagged as @code{@@chapter} and lower-level headlines to unnumbered chapters tagged as @@ -16192,21 +16700,21 @@ this maps top-level headlines to numbered chapters tagged as other Texinfo structuring commands, define a new class in @code{org-texinfo-classes}. Activate the new class with the @samp{TEXINFO_CLASS} keyword. When no new class is defined and activated, -the Texinfo export back-end defaults to the +the Texinfo export backend defaults to the @code{org-texinfo-default-class}. If an Org headline's level has no associated Texinfo structuring command, or is below a certain threshold (see @ref{Export Settings}), then -the Texinfo export back-end makes it into a list item. +the Texinfo export backend makes it into a list item. @cindex @samp{APPENDIX}, property -The Texinfo export back-end makes any headline with a non-@code{nil} +The Texinfo export backend makes any headline with a non-@code{nil} @samp{APPENDIX} property into an appendix. This happens independent of the Org headline level or the @samp{TEXINFO_CLASS} keyword. @cindex @samp{ALT_TITLE}, property @cindex @samp{DESCRIPTION}, property -The Texinfo export back-end creates a menu entry after the Org +The Texinfo export backend creates a menu entry after the Org headline for each regular sectioning structure. To override this with a shorter menu entry, use the @samp{ALT_TITLE} property (see @ref{Table of Contents}). Texinfo menu entries also have an option for a longer @samp{DESCRIPTION} property. Here's an example that uses both to override @@ -16241,7 +16749,7 @@ file. See @ref{The Top Node,,,texinfo,}, for more information. @cindex data type index, in Texinfo export @cindex @samp{VINDEX}, keyword @cindex variable index, in Texinfo export -The Texinfo export back-end recognizes these indexing keywords if used +The Texinfo export backend recognizes these indexing keywords if used in the Org file: @samp{CINDEX}, @samp{FINDEX}, @samp{KINDEX}, @samp{PINDEX}, @samp{TINDEX} and @samp{VINDEX}. Write their value as verbatim Texinfo code; in particular, @samp{@{}, @samp{@}} and @samp{@@} characters need to be escaped with @samp{@@} if they do not @@ -16253,10 +16761,10 @@ belong to a Texinfo command. @cindex @samp{INDEX}, property -For the back-end to generate an index entry for a headline, set the +For the backend to generate an index entry for a headline, set the @samp{INDEX} property to @samp{cp} or @samp{vr}. These abbreviations come from Texinfo that stand for concept index and variable index. The Texinfo -manual has abbreviations for all other kinds of indexes. The back-end +manual has abbreviations for all other kinds of indexes. The backend exports the headline as an unnumbered chapter or section command, and then inserts the index after its contents. @@ -16292,7 +16800,7 @@ This paragraph is preceded by... @cindex lettered lists, in Texinfo export @cindex enum, Texinfo attribute -The Texinfo export back-end converts unordered and ordered lists in +The Texinfo export backend converts unordered and ordered lists in the Org file using the default command @samp{@@itemize}. Ordered lists are numbered when exported to Texinfo format. Such @@ -16310,7 +16818,7 @@ specific number, or switch to a lettered list, as illustrated here: @cindex @samp{ATTR_TEXINFO}, keyword @cindex two-column tables, in Texinfo export @cindex table-type, Texinfo attribute -The Texinfo export back-end by default converts description lists in +The Texinfo export backend by default converts description lists in the Org file using the default command @samp{@@table}, which results in a table with two columns. To change this behavior, set @samp{:table-type} attribute to either @samp{ftable} or @samp{vtable} value. For more information, @@ -16318,7 +16826,7 @@ see @ref{Two-column Tables,,,texinfo,}. @vindex org-texinfo-table-default-markup @cindex indic, Texinfo attribute -The Texinfo export back-end by default also applies a text highlight +The Texinfo export backend by default also applies a text highlight based on the defaults stored in @code{org-texinfo-table-default-markup}. To override the default highlight command, specify another one with the @samp{:indic} attribute. @@ -16326,7 +16834,7 @@ the @samp{:indic} attribute. @cindex multiple items in Texinfo lists @cindex sep, Texinfo attribute Org syntax is limited to one entry per list item. Nevertheless, the -Texinfo export back-end can split that entry according to any text +Texinfo export backend can split that entry according to any text provided through the @samp{:sep} attribute. Each part then becomes a new entry in the first column of the table. @@ -16350,9 +16858,9 @@ This is the common text for variables foo and bar. The @samp{:compact} attribute is an alternative to the @samp{:sep} attribute, which allows writing each entry on its own line. If this attribute is -non-nil and an item in a description list has no body but is followed -by another item, then the second item is transcoded to @samp{@@itemx}. This -example is transcoded to the same output as above. +non-@code{nil} and an item in a description list has no body but is +followed by another item, then the second item is transcoded to +@samp{@@itemx}. This example is transcoded to the same output as above. @example #+ATTR_TEXINFO: :table-type vtable :indic asis :compact t @@ -16365,12 +16873,12 @@ Support for this compact syntax can also be enabled for all lists in a file using the @samp{compact-itemx} export option, or globally using the variable @code{org-texinfo-compact-itemx}. -The Texinfo export back-end also supports two approaches to writing +The Texinfo export backend also supports two approaches to writing Texinfo definition commands (see @ref{Definition Commands,,,texinfo,}). One of them uses description lists and is described below, the other relies on special blocks (see @ref{Special blocks in Texinfo export}). -Items in a description list in a Org file that begin with @samp{Function:} +Items in a description list in an Org file that begin with @samp{Function:} or certain other prefixes are converted using Texinfo definition commands. This works even if other items in the same list do not have such a prefix; if necessary a single description list is converted @@ -16435,7 +16943,7 @@ Command in parenthesis, as done above, is optional. @subsection Tables in Texinfo export @cindex @samp{ATTR_TEXINFO}, keyword -When exporting tables, the Texinfo export back-end uses the widest +When exporting tables, the Texinfo export backend uses the widest cell width in each column. To override this and instead specify as fractions of line length, use the @samp{:columns} attribute. See example below. @@ -16450,7 +16958,7 @@ below. @cindex @samp{ATTR_TEXINFO}, keyword Insert a file link to the image in the Org file, and the Texinfo -export back-end inserts the image. These links must have the usual +export backend inserts the image. These links must have the usual supported image extensions and no descriptions. To scale the image, use @samp{:width} and @samp{:height} attributes. For alternate text, use @samp{:alt} and specify the text using Texinfo code, as shown in the example: @@ -16515,13 +17023,13 @@ Type @@kbd@{C-c @@key@{SPC@}@}. @node Special blocks in Texinfo export @subsection Special blocks in Texinfo export -The Texinfo export back-end supports two approaches to writing Texinfo +The Texinfo export backend supports two approaches to writing Texinfo definition commands. One of them is described here, the other in @ref{Plain lists in Texinfo export}. @cindex @samp{ATTR_TEXINFO}, keyword -The Texinfo export back-end converts special blocks to commands with +The Texinfo export backend converts special blocks to commands with the same name. It also adds any @samp{:options} attributes to the end of the command, as shown in this example: @@ -16564,7 +17072,7 @@ Texinfo code. #+TEXINFO_HEADER: @@syncodeindex pg cp #+TEXINFO_DIR_CATEGORY: Texinfo documentation system -#+TEXINFO_DIR_TITLE: sample: (sample) +#+TEXINFO_DIR_NAME: sample #+TEXINFO_DIR_DESC: Invoking sample #+TEXINFO_PRINTED_TITLE: GNU Sample @@ -16620,24 +17128,35 @@ This manual is for GNU Sample (version @{@{@{version@}@}@}, A large part of Org mode's interoperability success is its ability to easily export to or import from external applications. The iCalendar -export back-end takes calendar data from Org files and exports to the +export backend takes calendar data from Org files and exports to the standard iCalendar format. +@vindex icalendar-export-sexp-enumeration-days +By default, iCalendar export only includes headings that contain +active timestamps or diary sexps@footnote{ Diary sexp events, except +certain built-in types (see @code{icalendar-export-sexp-enumerate-all}), +are exported up to @code{icalendar-export-sexp-enumeration-days} into +future.}. + @vindex org-icalendar-include-todo -@vindex org-icalendar-use-deadline -@vindex org-icalendar-use-scheduled -The iCalendar export back-end can also incorporate TODO entries based +The iCalendar export backend can also incorporate TODO entries based on the configuration of the @code{org-icalendar-include-todo} variable. -The back-end exports plain timestamps as @samp{VEVENT}, TODO items as +The backend exports plain timestamps as @samp{VEVENT}, TODO items as @samp{VTODO}, and also create events from deadlines that are in non-TODO -items. The back-end uses the deadlines and scheduling dates in Org -TODO items for setting the start and due dates for the iCalendar TODO -entry. Consult the @code{org-icalendar-use-deadline} and -@code{org-icalendar-use-scheduled} variables for more details. +items. + +@vindex org-icalendar-use-deadline +@vindex org-icalendar-use-scheduled +@vindex org-icalendar-todo-unscheduled-start +The backend uses the deadlines and scheduling dates in Org TODO items +for setting the start and due dates for the iCalendar TODO entry. +Consult the @code{org-icalendar-use-deadline}, +@code{org-icalendar-use-scheduled}, and +@code{org-icalendar-todo-unscheduled-start} variables for more details. @vindex org-icalendar-categories @vindex org-icalendar-alarm-time -For tags on the headline, the iCalendar export back-end makes them +For tags on the headline, the iCalendar export backend makes them into iCalendar categories. To tweak the inheritance of tags and TODO states, configure the variable @code{org-icalendar-categories}. To assign clock alarms based on time, configure the @code{org-icalendar-alarm-time} @@ -16646,10 +17165,10 @@ variable. @vindex org-icalendar-store-UID @cindex @samp{ID}, property The iCalendar format standard requires globally unique identifier---or -UID---for each entry. The iCalendar export back-end creates UIDs +UID---for each entry. The iCalendar export backend creates UIDs during export. To save a copy of the UID in the Org file set the -variable @code{org-icalendar-store-UID}. The back-end looks for the @samp{ID} -property of the entry for re-using the same UID for subsequent +variable @code{org-icalendar-store-UID}. The backend looks for the @samp{ID} +property of the entry for reusing the same UID for subsequent exports. Since a single Org entry can result in multiple iCalendar @@ -16686,15 +17205,30 @@ Create a combined iCalendar file from Org files in @cindex @samp{LOCATION}, property @cindex @samp{TIMEZONE}, property @cindex @samp{CLASS}, property -The iCalendar export back-end includes @samp{SUMMARY}, @samp{DESCRIPTION}, +The iCalendar export backend includes @samp{SUMMARY}, @samp{DESCRIPTION}, @samp{LOCATION}, @samp{TIMEZONE} and @samp{CLASS} properties from the Org entries -when exporting. To force the back-end to inherit the @samp{LOCATION}, +when exporting. To force the backend to inherit the @samp{LOCATION}, @samp{TIMEZONE} and @samp{CLASS} properties, configure the @code{org-use-property-inheritance} variable. +@samp{SUMMARY}, @samp{LOCATION}, and @samp{DESCRIPTION} properties can define +multi-line summary, location, or description using @samp{+} +syntax (see @ref{Property Syntax}): + +@example +* Meeting at location with multi-line address +<2024-01-08 Mon 14:20-15:00> +:PROPERTIES: +:LOCATION: Someplace +:LOCATION+: Some Street 5 +:LOCATION+: 12345 Small Town +:END: +@end example + + @vindex org-icalendar-include-body When Org entries do not have @samp{SUMMARY}, @samp{DESCRIPTION}, @samp{LOCATION} and -@samp{CLASS} properties, the iCalendar export back-end derives the summary +@samp{CLASS} properties, the iCalendar export backend derives the summary from the headline, and derives the description from the body of the Org item. The @code{org-icalendar-include-body} variable limits the maximum number of characters of the content are turned into its @@ -16721,24 +17255,33 @@ The entry can be retrieved only by its owner. The server should treat unknown class properties the same as @samp{PRIVATE}. +@cindex @samp{ICAL-TTL}, keyword +@vindex org-icalendar-ttl +The exported iCalendar file can advise clients how often to check for +updates. This duration can be set globally with the +@code{org-icalendar-ttl} variable, or on a per-document basis with the +@samp{ICAL-TTL} keyword. This option should be set using the iCalendar +notation for time durations; consult the docstring of +@code{org-icalendar-ttl} for more details. + Exporting to iCalendar format depends in large part on the capabilities of the destination application. Some are more lenient than others. Consult the Org mode FAQ for advice on specific applications. -@node Other Built-in Back-ends -@section Other Built-in Back-ends +@node Other Built-in Backends +@section Other Built-in Backends -Other export back-ends included with Org are: +Other export backends included with Org are: @itemize @item @samp{ox-man.el}: Export to a man page. @end itemize -To activate such back-ends, either customize @code{org-export-backends} or +To activate such backends, either customize @code{org-export-backends} or load directly with @samp{(require 'ox-man)}. On successful load, the -back-end adds new keys in the export dispatcher (see @ref{The Export Dispatcher}). +backend adds new keys in the export dispatcher (see @ref{The Export Dispatcher}). Follow the comment section of such files, for example, @samp{ox-man.el}, for usage and configuration details. @@ -16746,37 +17289,37 @@ for usage and configuration details. @node Advanced Export Configuration @section Advanced Export Configuration - - @anchor{Export hooks} @subheading Export hooks @vindex org-export-before-processing-hook +@vindex org-export-before-processing-functions @vindex org-export-before-parsing-hook The export process executes two hooks before the actual exporting -begins. The first hook, @code{org-export-before-processing-hook}, runs -before any expansions of macros, Babel code, and include keywords in -the buffer. The second hook, @code{org-export-before-parsing-hook}, runs -before the buffer is parsed. +begins. The first hook, @code{org-export-before-processing-functions}, +runs before any expansions of macros, Babel code, and include keywords +in the buffer. The second hook, +@code{org-export-before-parsing-functions}, runs before the buffer is +parsed. Functions added to these hooks are called with a single argument: the -export back-end actually used, as a symbol. You may use them for +export backend actually used, as a symbol. You may use them for heavy duty structural modifications of the document. For example, you can remove every headline in the buffer during export like this: @lisp (defun my-headline-removal (backend) "Remove all headlines in the current buffer. -BACKEND is the export back-end being used, as a symbol." +BACKEND is the export backend being used, as a symbol." (org-map-entries (lambda () (delete-region (point) (line-beginning-position 2)) ;; We need to tell `org-map-entries' to not skip over heading at - ;; point. Otherwise, it would continue from _next_ heading. See + ;; point. Otherwise, it would continue from _next_ heading. See ;; the docstring of `org-map-entries' for details. (setq org-map-continue-from (point))))) -(add-hook 'org-export-before-parsing-hook #'my-headline-removal) +(add-hook 'org-export-before-parsing-functions #'my-headline-removal) @end lisp @anchor{Filters} @@ -16784,7 +17327,7 @@ BACKEND is the export back-end being used, as a symbol." @cindex Filters, exporting Filters are lists of functions to be applied to certain parts for -a given back-end. The output from the first function in the filter is +a given backend. The output from the first function in the filter is passed on to the next function in the filter. The final output is the output from the final function in the filter. @@ -16851,8 +17394,8 @@ is the type targeted by the filter. Valid types are: @tab verse-block @end multitable -Here is an example filter that replaces non-breaking spaces @code{ } in the -Org buffer with @samp{~} for the @LaTeX{} back-end. +Here is an example filter that replaces non-breaking spaces ~ ~ in the +Org buffer with @samp{~} for the @LaTeX{} backend. @lisp (defun my-latex-filter-nobreaks (text backend info) @@ -16865,16 +17408,16 @@ Org buffer with @samp{~} for the @LaTeX{} back-end. @end lisp A filter requires three arguments: the code to be transformed, the -name of the back-end, and some optional information about the export +name of the backend, and some optional information about the export process. The third argument can be safely ignored. Note the use of @code{org-export-derived-backend-p} predicate that tests for @emph{latex} -back-end or any other back-end, such as @emph{beamer}, derived from +backend or any other backend, such as @emph{beamer}, derived from @emph{latex}. @anchor{Defining filters for individual files} @subheading Defining filters for individual files -The Org export can filter not just for back-ends, but also for +The Org export can filter not just for backends, but also for specific files through the @samp{BIND} keyword. Here is an example with two filters; one removes brackets from time stamps, and the other removes strike-through text. The filter functions are defined in @@ -16891,29 +17434,229 @@ debugging. #+END_SRC @end example -@anchor{Extending an existing back-end} -@subheading Extending an existing back-end +@anchor{Summary of the export process} +@subheading Summary of the export process -Some parts of the conversion process can be extended for certain -elements so as to introduce a new or revised translation. That is how -the HTML export back-end was extended to handle Markdown format. The -extensions work seamlessly so any aspect of filtering not done by the -extended back-end is handled by the original back-end. Of all the -export customization in Org, extending is very powerful as it operates -at the parser level. +@findex org-export-as +Org mode export is a multi-step process that works on a temporary copy +of the buffer. The export process consists of 4 major steps: -For this example, make the @emph{ascii} back-end display the language used -in a source code block. Also make it display only when some attribute -is non-@code{nil}, like the following: +@enumerate +@item +Process the temporary copy, making necessary changes to the buffer +text; -@example -#+ATTR_ASCII: :language t -@end example +@item +Parse the buffer, converting plain Org markup into an abstract +syntax tree (AST); +@item +Convert the AST to text, as prescribed by the selected export +backend; -Then extend ASCII back-end with a custom ``my-ascii'' back-end. +@item +Post-process the resulting exported text. +@end enumerate -@lisp + +@noindent +Process temporary copy of the source Org buffer @footnote{Unless +otherwise specified, each step of the export process only operates on +the accessible portion of the buffer. When subtree export is selected +(see @ref{The Export Dispatcher}), the buffer is narrowed to the body of +the selected subtree, so that the rest of the buffer text, except +export keywords, does not contribute to the export output.}: + +@enumerate +@item +Execute @code{org-export-before-processing-functions} (see @ref{Export hooks}); + +@item +Expand @samp{#+include} keywords in the whole buffer (see +@ref{Include Files}); + +@item +Remove commented subtrees in the whole buffer (see @ref{Comment Lines}); + +@item +Replace macros in the whole buffer (see @ref{Macro Replacement}); + +@item +When @code{org-export-use-babel} is non-nil (default), process code +blocks: + +@itemize +@item +Leave code blocks inside archived subtrees (see @ref{Internal archiving}) as is; + +@item +Evaluate all the other code blocks according to code block +headers (see @ref{Limit code block evaluation}); + +@item +Remove code, results of evaluation, both, or neither according +to @samp{:exports} header argument (see @ref{Exporting Code Blocks}). +@end itemize +@end enumerate + + +@noindent +Parse the temporary buffer, creating AST: + +@enumerate +@item +Execute @code{org-export-before-parsing-functions} (see @ref{Export hooks}). +The hook functions may still modify the buffer; + +@item +Calculate export option values according to subtree-specific export +settings, in-buffer keywords, @samp{#+BIND} keywords, and buffer-local +and global customization. The whole buffer is considered; + +@item +When @code{org-org-with-cite-processors} is non-nil (default), determine +contributing bibliographies and record them into export options +(see @ref{Citations}). The whole buffer is considered; + +@item +Execute @code{org-export-filter-options-functions}; + +@item +Parse the accessible portion of the temporary buffer to generate an +AST@. The AST is a nested list of lists representing Org syntax +elements (see @uref{https://orgmode.org/worg/dev/org-element-api.html, Org Element API} for more details): + +@example +(org-data ... + (heading + (section + (paragraph (plain-text) (bold (plain-text)))) + (heading) + (heading (section ...)))) +@end example + + +Past this point, modifications to the temporary buffer no longer +affect the export; Org export works only with the AST; + +@item +Remove elements that are not exported from the AST: + +@itemize +@item +Headings according to @samp{SELECT_TAGS} and @samp{EXCLUDE_TAGS} export +keywords; @samp{task}, @samp{inline}, @samp{arch} export options (see +@ref{Export Settings}); + +@item +Comments; + +@item +Clocks, drawers, fixed-width environments, footnotes, @LaTeX{} +environments and fragments, node properties, planning lines, +property drawers, statistics cookies, timestamps, etc according +to @samp{#+OPTIONS} keyword (see @ref{Export Settings}); + +@item +Table rows containing width and alignment markers, unless the +selected export backend changes @code{:with-special-rows} export option +to non-nil (see @ref{Column Width and Alignment}); + +@item +Table columns containing recalc marks (see @ref{Advanced features}). +@end itemize + +@item +Expand environment variables in file link AST nodes according to +the @samp{expand-links} export option (see @ref{Export Settings}); + +@item +Execute @code{org-export-filter-parse-tree-functions}. These +functions can modify the AST by side effects; + +@item +When @code{org-org-with-cite-processors} is non-nil (default), replace +citation AST nodes and @samp{#+print_bibliography} keyword AST nodes as +prescribed by the selected citation export processor (see @ref{Citation export processors}). +@end enumerate + + +@noindent +Convert the AST to text by traversing the AST nodes, depth-first: + +@enumerate +@item +Convert the leaf nodes (without children) to text as prescribed +by ``transcoders'' in the selected export backend +@footnote{ See transcoders and @code{:translate-alist} in the docstrings +of @code{org-export-define-backend} and @code{org-export-define-derived-backend}.}; + +@item +Pass the converted nodes through the corresponding export +filters (see @ref{Filters}); + +@item +Concatenate all the converted child nodes to produce parent +node contents; + +@item +Convert the nodes with children to text, passing the nodes +themselves and their exported contents to the corresponding +transcoders and then to the export filters (see @ref{Filters}). +@end enumerate + + +@noindent +Post-process the exported text: + +@enumerate +@item +Post-process the converted AST, as prescribed by the export +backend. @footnote{ See @code{inner-template} in the docstring of @code{org-export-define-backend}.} +This step usually adds generated content (like Table of Contents) +to the exported text; + +@item +Execute @code{org-export-filter-body-functions}; + +@item +Unless body-only export is selected (see @ref{The Export Dispatcher}), +add the necessary metadata to the final document, as prescribed +by the export backend. Examples: Document author/title; HTML +headers/footers; @LaTeX{} preamble; + +@item +When @code{org-org-with-cite-processors} is non-nil (default), add +bibliography metadata, as prescribed by the citation export +processor; + +@item +Execute @code{org-export-filter-final-output-functions}. +@end enumerate + +@anchor{Extending an existing backend} +@subheading Extending an existing backend + +Some parts of the conversion process can be extended for certain +elements so as to introduce a new or revised translation. That is how +the HTML export backend was extended to handle Markdown format. The +extensions work seamlessly so any aspect of filtering not done by the +extended backend is handled by the original backend. Of all the +export customization in Org, extending is very powerful as it operates +at the parser level. + +For this example, make the @emph{ascii} backend display the language used +in a source code block. Also make it display only when some attribute +is non-@code{nil}, like the following: + +@example +#+ATTR_ASCII: :language t +@end example + + +Then extend ASCII backend with a custom ``my-ascii'' backend. + +@lisp (defun my-ascii-src-block (src-block contents info) "Transcode a SRC-BLOCK element from Org to ASCII. CONTENTS is nil. INFO is a plist used as a communication @@ -16933,13 +17676,13 @@ channel." @end lisp The @code{my-ascii-src-block} function looks at the attribute above the -current element. If not true, hands over to @emph{ascii} back-end. If +current element. If not true, hands over to @emph{ascii} backend. If true, which it is in this example, it creates a box around the code and leaves room for the inserting a string for language. The last -form creates the new back-end that springs to action only when +form creates the new backend that springs to action only when translating @code{src-block} type elements. -To use the newly defined back-end, evaluate the following from an Org +To use the newly defined backend, evaluate the following from an Org buffer: @lisp @@ -16948,74 +17691,54 @@ buffer: Further steps to consider would be an interactive function, self-installing an item in the export dispatcher menu, and other -user-friendly improvements. +user-friendly improvements. See +@uref{https://orgmode.org/worg/dev/org-export-reference.html} for more +details. -@node Export in Foreign Buffers -@section Export in Foreign Buffers +@node Export Region +@section Export Region -The export back-ends in Org often include commands to convert selected -regions. A convenient feature of this in-place conversion is that the -exported output replaces the original source. Here are such -functions: +Some export backends include commands to convert a region of Org +formatted text to another format, such as HTML or @LaTeX{}. The +conversion replaces the original source. Here are such commands: @table @asis -@item @code{org-ascii-convert-region-to-ascii} +@item @code{org-export-region-to-ascii} @findex org-ascii-convert-region-to-ascii +@findex org-export-region-to-ascii Convert the selected region into ASCII@. -@item @code{org-ascii-convert-region-to-utf8} +@item @code{org-export-region-to-utf8} @findex org-ascii-convert-region-to-utf8 +@findex org-export-region-to-utf8 Convert the selected region into UTF-8. -@item @code{org-html-convert-region-to-html} +@item @code{org-export-region-to-html} @findex org-html-convert-region-to-html +@findex org-export-region-to-html Convert the selected region into HTML@. -@item @code{org-latex-convert-region-to-latex} +@item @code{org-export-region-to-latex} @findex org-latex-convert-region-to-latex +@findex org-export-region-to-latex Convert the selected region into @LaTeX{}. -@item @code{org-texinfo-convert-region-to-texinfo} +@item @code{org-export-region-to-texinfo} @findex org-texinfo-convert-region-to-texinfo +@findex org-export-region-to-texinfo Convert the selected region into Texinfo. -@item @code{org-md-convert-region-to-md} +@item @code{org-export-region-to-md} @findex org-md-convert-region-to-md +@findex org-export-region-to-md Convert the selected region into Markdown. @end table -In-place conversions are particularly handy for quick conversion of -tables and lists in foreign buffers. For example, in an HTML buffer, +The in-place conversion is particularly handy for quick conversion of +tables and lists in non-Org buffers. For example, in an HTML buffer, write a list in Org syntax, select it, and convert it to HTML with @kbd{M-x org-html-convert-region-to-html}. -@menu -* Bare HTML:: Exporting HTML without CSS, Javascript, etc. -@end menu - -@node Bare HTML -@subsection Exporting to minimal HTML - -If you want to output a minimal HTML file, with no CSS, no Javascript, -no preamble or postamble, here are the variable you would need to set: - -@vindex org-html-head -@vindex org-html-head-extra -@vindex org-html-head-include-default-style -@vindex org-html-head-include-scripts -@vindex org-html-preamble -@vindex org-html-postamble -@vindex org-html-use-infojs -@lisp -(setq org-html-head "" - org-html-head-extra "" - org-html-head-include-default-style nil - org-html-head-include-scripts nil - org-html-preamble nil - org-html-postamble nil - org-html-use-infojs nil) -@end lisp - @node Publishing @chapter Publishing @@ -17210,23 +17933,33 @@ any, during publishing. Options set within a file (see @ref{Export Settings}), @anchor{Generic properties} @subsubheading Generic properties -@multitable {aaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} -@item @code{:archived-trees} -@tab @code{org-export-with-archived-trees} +@multitable {aaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} +@item @code{:author} +@tab @code{user-full-name} +@item @code{:email} +@tab @code{user-mail-address} +@item @code{:language} +@tab @code{org-export-default-language} +@item @code{:select-tags} +@tab @code{org-export-select-tags} @item @code{:exclude-tags} @tab @code{org-export-exclude-tags} +@item @code{:creator} +@tab @code{org-export-creator-string} @item @code{:headline-levels} @tab @code{org-export-headline-levels} -@item @code{:language} -@tab @code{org-export-default-language} @item @code{:preserve-breaks} @tab @code{org-export-preserve-breaks} @item @code{:section-numbers} @tab @code{org-export-with-section-numbers} -@item @code{:select-tags} -@tab @code{org-export-select-tags} +@item @code{:time-stamp-file} +@tab @code{org-export-timestamp-file} +@item @code{:with-archived-trees} +@tab @code{org-export-with-archived-trees} @item @code{:with-author} @tab @code{org-export-with-author} +@item @code{:expand-links} +@tab @code{org-export-expand-links} @item @code{:with-broken-links} @tab @code{org-export-with-broken-links} @item @code{:with-clocks} @@ -17241,10 +17974,14 @@ any, during publishing. Options set within a file (see @ref{Export Settings}), @tab @code{org-export-with-email} @item @code{:with-emphasize} @tab @code{org-export-with-emphasize} +@item @code{:with-entities} +@tab @code{org-export-with-entities} @item @code{:with-fixed-width} @tab @code{org-export-with-fixed-width} @item @code{:with-footnotes} @tab @code{org-export-with-footnotes} +@item @code{:with-inlinetasks} +@tab @code{org-export-with-inlinetasks} @item @code{:with-latex} @tab @code{org-export-with-latex} @item @code{:with-planning} @@ -17253,10 +17990,16 @@ any, during publishing. Options set within a file (see @ref{Export Settings}), @tab @code{org-export-with-priority} @item @code{:with-properties} @tab @code{org-export-with-properties} +@item @code{:with-smart-quotes} +@tab @code{org-export-with-smart-quotes} @item @code{:with-special-strings} @tab @code{org-export-with-special-strings} +@item @code{:with-statistics-cookies} +@tab @code{org-export-with-statistics-cookies} @item @code{:with-sub-superscript} @tab @code{org-export-with-sub-superscripts} +@item @code{:with-toc} +@tab @code{org-export-with-toc} @item @code{:with-tables} @tab @code{org-export-with-tables} @item @code{:with-tags} @@ -17267,10 +18010,12 @@ any, during publishing. Options set within a file (see @ref{Export Settings}), @tab @code{org-export-with-timestamps} @item @code{:with-title} @tab @code{org-export-with-title} -@item @code{:with-toc} -@tab @code{org-export-with-toc} @item @code{:with-todo-keywords} @tab @code{org-export-with-todo-keywords} +@item @code{:with-cite-processors} +@tab @code{org-export-process-citations} +@item @code{:cite-export} +@tab @code{org-cite-export-processors} @end multitable @anchor{ASCII specific properties} @@ -17323,10 +18068,14 @@ any, during publishing. Options set within a file (see @ref{Export Settings}), @subsubheading Beamer specific properties @multitable {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} -@item @code{:beamer-theme} -@tab @code{org-beamer-theme} +@item @code{:headline-levels} +@tab @code{org-beamer-frame-level} +@item @code{:beamer-subtitle-format} +@tab @code{org-beamer-subtitle-format} @item @code{:beamer-column-view-format} @tab @code{org-beamer-column-view-format} +@item @code{:beamer-theme} +@tab @code{org-beamer-theme} @item @code{:beamer-environments-extra} @tab @code{org-beamer-environments-extra} @item @code{:beamer-frame-default-options} @@ -17335,24 +18084,46 @@ any, during publishing. Options set within a file (see @ref{Export Settings}), @tab @code{org-beamer-outline-frame-options} @item @code{:beamer-outline-frame-title} @tab @code{org-beamer-outline-frame-title} -@item @code{:beamer-subtitle-format} -@tab @code{org-beamer-subtitle-format} @end multitable @anchor{HTML specific properties} @subsubheading HTML specific properties @multitable {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} -@item @code{:html-allow-name-attribute-in-anchors} -@tab @code{org-html-allow-name-attribute-in-anchors} -@item @code{:html-checkbox-type} -@tab @code{org-html-checkbox-type} +@item @code{:html-doctype} +@tab @code{org-html-doctype} @item @code{:html-container} @tab @code{org-html-container-element} +@item @code{:html-content-class} +@tab @code{org-html-content-class} +@item @code{:html-html5-fancy} +@tab @code{org-html-html5-fancy} +@item @code{:html-link-use-abs-url} +@tab @code{org-html-link-use-abs-url} +@item @code{:html-link-home} +@tab @code{org-html-link-home} +@item @code{:html-link-up} +@tab @code{org-html-link-up} +@item @code{:html-equation-reference-format} +@tab @code{org-html-equation-reference-format} +@item @code{:html-postamble} +@tab @code{org-html-postamble} +@item @code{:html-preamble} +@tab @code{org-html-preamble} +@item @code{:html-head} +@tab @code{org-html-head} +@item @code{:html-head-extra} +@tab @code{org-html-head-extra} +@item @code{:html-head-include-default-style} +@tab @code{org-html-head-include-default-style} +@item @code{:html-head-include-scripts} +@tab @code{org-html-head-include-scripts} +@item @code{:html-allow-name-attribute-in-anchors} +@tab @code{org-html-allow-name-attribute-in-anchors} @item @code{:html-divs} @tab @code{org-html-divs} -@item @code{:html-doctype} -@tab @code{org-html-doctype} +@item @code{:html-checkbox-type} +@tab @code{org-html-checkbox-type} @item @code{:html-extension} @tab @code{org-html-extension} @item @code{:html-footnote-format} @@ -17367,18 +18138,8 @@ any, during publishing. Options set within a file (see @ref{Export Settings}), @tab @code{org-html-format-headline-function} @item @code{:html-format-inlinetask-function} @tab @code{org-html-format-inlinetask-function} -@item @code{:html-head-extra} -@tab @code{org-html-head-extra} -@item @code{:html-head-include-default-style} -@tab @code{org-html-head-include-default-style} -@item @code{:html-head-include-scripts} -@tab @code{org-html-head-include-scripts} -@item @code{:html-head} -@tab @code{org-html-head} @item @code{:html-home/up-format} @tab @code{org-html-home/up-format} -@item @code{:html-html5-fancy} -@tab @code{org-html-html5-fancy} @item @code{:html-indent} @tab @code{org-html-indent} @item @code{:html-infojs-options} @@ -17387,46 +18148,30 @@ any, during publishing. Options set within a file (see @ref{Export Settings}), @tab @code{org-html-infojs-template} @item @code{:html-inline-image-rules} @tab @code{org-html-inline-image-rules} -@item @code{:html-inline-images} -@tab @code{org-html-inline-images} -@item @code{:html-link-home} -@tab @code{org-html-link-home} @item @code{:html-link-org-files-as-html} @tab @code{org-html-link-org-files-as-html} -@item @code{:html-link-up} -@tab @code{org-html-link-up} -@item @code{:html-link-use-abs-url} -@tab @code{org-html-link-use-abs-url} @item @code{:html-mathjax-options} @tab @code{org-html-mathjax-options} @item @code{:html-mathjax-template} @tab @code{org-html-mathjax-template} -@item @code{:html-equation-reference-format} -@tab @code{org-html-equation-reference-format} @item @code{:html-metadata-timestamp-format} @tab @code{org-html-metadata-timestamp-format} @item @code{:html-postamble-format} @tab @code{org-html-postamble-format} -@item @code{:html-postamble} -@tab @code{org-html-postamble} @item @code{:html-preamble-format} @tab @code{org-html-preamble-format} -@item @code{:html-preamble} -@tab @code{org-html-preamble} +@item @code{:html-prefer-user-labels} +@tab @code{org-html-prefer-user-labels} @item @code{:html-self-link-headlines} @tab @code{org-html-self-link-headlines} -@item @code{:html-table-align-individual-field} +@item @code{:html-table-align-individual-fields} @tab @code{org-html-table-align-individual-fields} -@item @code{:html-table-attributes} -@tab @code{org-html-table-default-attributes} @item @code{:html-table-caption-above} @tab @code{org-html-table-caption-above} @item @code{:html-table-data-tags} @tab @code{org-html-table-data-tags} @item @code{:html-table-header-tags} @tab @code{org-html-table-header-tags} -@item @code{:html-table-row-tags} -@tab @code{org-html-table-row-tags} @item @code{:html-table-use-header-tags-for-first-column} @tab @code{org-html-table-use-header-tags-for-first-column} @item @code{:html-tag-class-prefix} @@ -17443,32 +18188,54 @@ any, during publishing. Options set within a file (see @ref{Export Settings}), @tab @code{org-html-validation-link} @item @code{:html-viewport} @tab @code{org-html-viewport} -@item @code{:html-wrap-src-lines} -@tab @code{org-html-wrap-src-lines} +@item @code{:html-inline-images} +@tab @code{org-html-inline-images} +@item @code{:html-table-attributes} +@tab @code{org-html-table-default-attributes} +@item @code{:html-table-row-open-tag} +@tab @code{org-html-table-row-open-tag} +@item @code{:html-table-row-close-tag} +@tab @code{org-html-table-row-close-tag} @item @code{:html-xml-declaration} @tab @code{org-html-xml-declaration} +@item @code{:html-wrap-src-lines} +@tab @code{org-html-wrap-src-lines} +@item @code{:html-klipsify-src} +@tab @code{org-html-klipsify-src} +@item @code{:html-klipse-css} +@tab @code{org-html-klipse-css} +@item @code{:html-klipse-js} +@tab @code{org-html-klipse-js} +@item @code{:html-klipse-selection-script} +@tab @code{org-html-klipse-selection-script} +@item @code{:creator} +@tab @code{org-html-creator-string} +@item @code{:with-latex} +@tab @code{org-html-with-latex} @end multitable @anchor{@LaTeX{} specific properties} @subsubheading @LaTeX{} specific properties @multitable {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} +@item @code{:latex-class} +@tab @code{org-latex-default-class} @item @code{:latex-active-timestamp-format} @tab @code{org-latex-active-timestamp-format} @item @code{:latex-caption-above} @tab @code{org-latex-caption-above} @item @code{:latex-classes} @tab @code{org-latex-classes} -@item @code{:latex-class} -@tab @code{org-latex-default-class} -@item @code{:latex-compiler} -@tab @code{org-latex-compiler} @item @code{:latex-default-figure-position} @tab @code{org-latex-default-figure-position} @item @code{:latex-default-table-environment} @tab @code{org-latex-default-table-environment} +@item @code{:latex-default-quote-environment} +@tab @code{org-latex-default-quote-environment} @item @code{:latex-default-table-mode} @tab @code{org-latex-default-table-mode} +@item @code{:latex-default-footnote-command} +@tab @code{org-latex-default-footnote-command} @item @code{:latex-diary-timestamp-format} @tab @code{org-latex-diary-timestamp-format} @item @code{:latex-engraved-options} @@ -17489,6 +18256,8 @@ any, during publishing. Options set within a file (see @ref{Export Settings}), @tab @code{org-latex-format-inlinetask-function} @item @code{:latex-hyperref-template} @tab @code{org-latex-hyperref-template} +@item @code{:latex-image-default-scale} +@tab @code{org-latex-image-default-scale} @item @code{:latex-image-default-height} @tab @code{org-latex-image-default-height} @item @code{:latex-image-default-option} @@ -17503,10 +18272,14 @@ any, during publishing. Options set within a file (see @ref{Export Settings}), @tab @code{org-latex-inline-image-rules} @item @code{:latex-link-with-unknown-path-format} @tab @code{org-latex-link-with-unknown-path-format} +@item @code{:latex-src-block-backend} +@tab @code{org-latex-src-block-backend} @item @code{:latex-listings-langs} @tab @code{org-latex-listings-langs} @item @code{:latex-listings-options} @tab @code{org-latex-listings-options} +@item @code{:latex-listings-src-omit-language} +@tab @code{org-latex-listings-src-omit-language} @item @code{:latex-minted-langs} @tab @code{org-latex-minted-langs} @item @code{:latex-minted-options} @@ -17517,8 +18290,6 @@ any, during publishing. Options set within a file (see @ref{Export Settings}), @tab @code{org-latex-subtitle-format} @item @code{:latex-subtitle-separate} @tab @code{org-latex-subtitle-separate} -@item @code{:latex-src-block-backend} -@tab @code{org-latex-src-block-backend} @item @code{:latex-table-scientific-notation} @tab @code{org-latex-table-scientific-notation} @item @code{:latex-tables-booktabs} @@ -17531,6 +18302,8 @@ any, during publishing. Options set within a file (see @ref{Export Settings}), @tab @code{org-latex-title-command} @item @code{:latex-toc-command} @tab @code{org-latex-toc-command} +@item @code{:latex-compiler} +@tab @code{org-latex-compiler} @end multitable @anchor{Markdown specific properties} @@ -17551,6 +18324,8 @@ any, during publishing. Options set within a file (see @ref{Export Settings}), @subsubheading ODT specific properties @multitable {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} +@item @code{:odt-styles-file} +@tab @code{org-odt-styles-file} @item @code{:odt-content-template-file} @tab @code{org-odt-content-template-file} @item @code{:odt-display-outline-level} @@ -17569,50 +18344,50 @@ any, during publishing. Options set within a file (see @ref{Export Settings}), @tab @code{org-odt-inline-image-rules} @item @code{:odt-pixels-per-inch} @tab @code{org-odt-pixels-per-inch} -@item @code{:odt-styles-file} -@tab @code{org-odt-styles-file} @item @code{:odt-table-styles} @tab @code{org-odt-table-styles} @item @code{:odt-use-date-fields} @tab @code{org-odt-use-date-fields} +@item @code{:with-latex} +@tab @code{org-odt-with-latex} @end multitable @anchor{Texinfo specific properties} @subsubheading Texinfo specific properties @multitable {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} -@item @code{:texinfo-active-timestamp-format} -@tab @code{org-texinfo-active-timestamp-format} -@item @code{:texinfo-classes} -@tab @code{org-texinfo-classes} @item @code{:texinfo-class} @tab @code{org-texinfo-default-class} -@item ~:texinfo-compact-itemx -@tab @code{org-texinfo-compact-itemx} -@item @code{:texinfo-table-default-markup} -@tab @code{org-texinfo-table-default-markup} -@item @code{:texinfo-diary-timestamp-format} -@tab @code{org-texinfo-diary-timestamp-format} -@item @code{:texinfo-filename} -@tab @code{org-texinfo-filename} -@item @code{:texinfo-format-drawer-function} -@tab @code{org-texinfo-format-drawer-function} +@item @code{:texinfo-classes} +@tab @code{org-texinfo-classes} @item @code{:texinfo-format-headline-function} @tab @code{org-texinfo-format-headline-function} -@item @code{:texinfo-format-inlinetask-function} -@tab @code{org-texinfo-format-inlinetask-function} +@item @code{:texinfo-node-description-column} +@tab @code{org-texinfo-node-description-column} +@item @code{:texinfo-active-timestamp-format} +@tab @code{org-texinfo-active-timestamp-format} @item @code{:texinfo-inactive-timestamp-format} @tab @code{org-texinfo-inactive-timestamp-format} +@item @code{:texinfo-diary-timestamp-format} +@tab @code{org-texinfo-diary-timestamp-format} @item @code{:texinfo-link-with-unknown-path-format} @tab @code{org-texinfo-link-with-unknown-path-format} -@item @code{:texinfo-node-description-column} -@tab @code{org-texinfo-node-description-column} -@item @code{:texinfo-table-scientific-notation} -@tab @code{org-texinfo-table-scientific-notation} @item @code{:texinfo-tables-verbatim} @tab @code{org-texinfo-tables-verbatim} +@item @code{:texinfo-table-scientific-notation} +@tab @code{org-texinfo-table-scientific-notation} +@item @code{:texinfo-table-default-markup} +@tab @code{org-texinfo-table-default-markup} @item @code{:texinfo-text-markup-alist} @tab @code{org-texinfo-text-markup-alist} +@item @code{:texinfo-format-drawer-function} +@tab @code{org-texinfo-format-drawer-function} +@item @code{:texinfo-format-inlinetask-function} +@tab @code{org-texinfo-format-inlinetask-function} +@item @code{:texinfo-compact-itemx} +@tab @code{org-texinfo-compact-itemx} +@item @code{:with-latex} +@tab @code{org-texinfo-with-latex} @end multitable @node Publishing links @@ -17655,6 +18430,7 @@ to HTML, the following links all point to a dedicated anchor in @cindex sitemap, of published pages +@vindex org-publish-project-alist The following properties may be used to control publishing of a map of files for a given project. @@ -17670,6 +18446,11 @@ becomes @samp{sitemap.html}. @item @code{:sitemap-title} Title of sitemap page. Defaults to name of file. +@item @code{:sitemap-style} +Can be @code{list} (site-map is just an itemized list of the titles of +the files involved) or @code{tree} (the directory structure of the +source files is reflected in the site-map). Defaults to @code{tree}. + @item @code{:sitemap-format-entry} @findex org-publish-find-date @findex org-publish-find-property @@ -17709,19 +18490,6 @@ The date of a file is retrieved with @code{org-publish-find-date}. @item @code{:sitemap-ignore-case} Should sorting be case-sensitive? Default @code{nil}. - -@item @code{:sitemap-file-entry-format} -With this option one can tell how a sitemap's entry is formatted in -the sitemap. This is a format string with some escape sequences: -@code{%t} stands for the title of the file, @code{%a} stands for the author of -the file and @code{%d} stands for the date of the file. The date is -retrieved with the @code{org-publish-find-date} function and formatted -with @code{org-publish-sitemap-date-format}. Default @code{%t}. - -@item @code{:sitemap-date-format} -Format string for the @code{format-time-string} function that tells how -a sitemap entry's date is to be formatted. This property bypasses -@code{org-publish-sitemap-date-format} which defaults to @code{%Y-%m-%d}. @end table @node Generating an index @@ -17843,12 +18611,12 @@ place on the web server, and publishing images to it. @lisp (setq org-publish-project-alist - '(("orgfiles" + `(("orgfiles" :base-directory "~/org/" :base-extension "org" :publishing-directory "/ssh:user@@host:~/html/notebook/" :publishing-function org-html-publish-to-html - :exclude "PrivatePage.org" ;; regexp + :exclude ,(rx (or "PrivateFile.org" (seq line-start "private/"))) ;; regexp :headline-levels 3 :section-numbers nil :with-toc nil @@ -17911,10 +18679,71 @@ keywords. @chapter Citation handling @cindex citation +@cindex citation processor + +While links (see @ref{Hyperlinks}) are often sufficient to refer to +external or internal information from Org, they have their limitations +when referring to multiple targets or typesetting printed +publications. + +Org mode provides a more sophisticated markup to ``cite'' external +resources. For example, consider the following Org mode snippet + +@example +#+bibliography: citationdata.bib + +Org mode is used by various communities [cite:teaching: @@orgteaching; +and TeX: @@orgtex]. [cite/author/caps:@@orgtex] uses Org mode to simplify +writing scientific publications, while [cite/author/caps:@@orgteaching] +experiment with Org babel to improve teaching. + +#+print_bibliography: +@end example + + +Org mode will gather citation metadata from the @samp{#+bibliography} +database and use it to typeset the exported document in arbitrary +formats. For example, the snippet below shows ASCII export output. + +@example +Org mode is used by various communities (teaching: Birkenkrahe, Marcus, +2023, and TeX: Somma, Emmanuele F, 2023). Somma, Emmanuele F uses Org +mode to simplify writing scientific publications, while Birkenkrahe, +Marcus experiment with Org babel to improve teaching. -The @samp{oc.el} library provides tooling to handle citations in Org via -``citation processors'' that offer some or all of the following -capabilities: +Birkenkrahe, Marcus (2023). /Teaching Data Science with Literate +Programming Tools/, MDPI. + +Somma, Emmanuele F (2023). /Simplifying LaTeX with ORG-mode in Emacs/, +TUGboat volume. +@end example + + +In addition to export, users can use completion to search and insert +citations from the bibliography (via @code{org-cite-insert}). Citations +also act like ordinary links, jumping to the citation metadata when +``following'' them using @code{org-open-at-point}. + +You can customize every aspect (@emph{capability}) of citation handling +using built-in or external @emph{citation processors}. + +Org mode ships with several built-in citation processors tailored to +work with @LaTeX{} export and Bib@TeX{} bibliographies (@samp{bibtex}, +@samp{biblatex}, and @samp{natbib} processors), or with more generic formats +described using @uref{https://citationstyles.org/, Citation Style +Language} (@samp{csl} processor). +The default citation processor is @samp{basic} - it works with arbitrary +export formats and recognizes both Bib@TeX{} and CSL bibliographies. +More citation processors are distributed as Emacs packages. + +@vindex org-cite-activate-processor +@vindex org-cite-follow-processor +@vindex org-cite-insert-processor +@vindex org-cite-export-processor +Multiple citation processors can be mixed to meet your preferences. +Configure @code{org-cite-activate-processor}, @code{org-cite-follow-processor}, +@code{org-cite-insert-processor}, and @code{org-cite-export-processors} to +select which processor to use for every citation capability: @table @asis @item activate @@ -17927,18 +18756,6 @@ Add and edit citations via @code{org-cite-insert}. Via different libraries for different target formats. @end table -To use a ``citation processor'', the user must load them; for example; - -@lisp -(require 'oc-bibtex) -@end lisp - -They can then configure them with @code{org-cite-activate-processor}, -@code{org-cite-follow-processor}, @code{org-cite-insert-processor}, and -@code{org-cite-export-processors} respectively. - -The included ``basic'' processor provides all four capabilities. - @menu * Citations:: * Citation export processors:: @@ -17948,16 +18765,23 @@ The included ``basic'' processor provides all four capabilities. @node Citations @section Citations +@cindex bibliography + +@vindex org-cite-global-bibliography Before adding citations, first set one-or-more bibliographies, either globally with @code{org-cite-global-bibliography}, or locally using one or more ``bibliography'' keywords. +@cindex @samp{BIBLIOGRAPHY}, keyword @example #+bibliography: SomeFile.bib #+bibliography: /some/other/file.json #+bibliography: "/some/file/with spaces/in its name.bib" @end example +Org mode uses all the local and global bibliographies combined to +search for citation keys. + @kindex C-c C-x @@ @findex org-cite-insert One can then insert and edit citations using @code{org-cite-insert}, called @@ -17973,28 +18797,62 @@ Each citation is surrounded by brackets and uses the @samp{cite} type. @item Each key starts with the character @samp{@@}. +@example +[cite:@@key] +@end example + @item Each key can be qualified by a @emph{prefix} (e.g.@tie{}``see '') and/or a @emph{suffix} (e.g.@tie{}``p.@tie{}123''), giving information useful or necessary for the comprehension of the citation but not included in the reference. +@example +[cite:see @@key p. 123] +@end example + @item 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. +@example +[cite:@@key1;@@key2;@@key3] +@end example + @item One can also specify a stylistic variation for the citations by inserting a @samp{/} and a style name between the @samp{cite} keyword and the colon; this usually makes sense only for the author-year styles. -@end itemize @example [cite/style:common prefix ;prefix @@key suffix; ... ; common suffix] @end example +When @samp{style} is not specified, one of the two default styles are +used + +@itemize +@item +either the default style specified in the @samp{CITE_EXPORT} keyword +(see @ref{Citation export processors}) + +@example +#+cite_export: basic numeric noauthor/bare +[cite:@@key] is the same as [cite/noauthor/bare:@@key] +@end example + +@item +or, if @samp{CITE_EXPORT} is not set, using the default @samp{nil} style + +@example +[cite:@@key] is the same as [cite/nil:@@key] +@end example +@end itemize +@end itemize + + The only mandatory elements are: @itemize @@ -18023,8 +18881,10 @@ where backward compatibility is not a requirement and formatting needs are minimal; @item csl -this export processor uses format files written in @uref{https://en.wikipedia.org/wiki/Citation_Style_Language, Citation -Style Language} via @uref{https://github.com/andras-simonyi/citeproc-el, citeproc-el}; +this export processor uses format files written in +@uref{https://en.wikipedia.org/wiki/Citation_Style_Language, Citation +Style Language} via +@uref{https://github.com/andras-simonyi/citeproc-el, citeproc-el}; @end table @item @@ -18036,7 +18896,7 @@ formats exclusively: this export processor uses Bib@TeX{}, 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 only supports @LaTeX{}'s +large number of publishers' styles). It only supports @LaTeX{}'s @samp{\cite} and @samp{\nocite} commands. @item natbib @@ -18052,17 +18912,19 @@ has not (yet?)@tie{}been widely adopted by publishers. @end table @end itemize -The @samp{CITE_EXPORT} keyword specifies the export processor and the -citation (and possibly reference) style(s); for example (all arguments -are optional) +@cindex @samp{CITE_EXPORT}, keyword +The @samp{CITE_EXPORT} keyword specifies the export processor, citation +style, and bibliography style; for example (all arguments are +optional) @example -#+cite_export: basic author author-year +#+cite_export: [export processor name] [bibliography style] [default citation style] +#+cite_export: basic author-year author @end example @noindent -specifies the ``basic'' export processor with citations inserted as +specifies the @samp{basic} export processor with citations inserted as author's name and references indexed by author's names and year; @example @@ -18071,7 +18933,7 @@ author's name and references indexed by author's names and year; @noindent -specifies the ``csl'' processor and CSL style, which in this case +specifies the @samp{csl} processor and CSL style, which in this case defines numeric citations and numeric references according to the @samp{Vancouver} specification (as style used in many medical journals), following a typesetting variation putting citations between brackets; @@ -18087,9 +18949,32 @@ conformant to the Harvard style and the specification of the Wolkers-Kluwer publisher; since it relies on the @code{bibtex} processor of your @LaTeX{} installation, it won't export to anything but PDF@. +@example +#+cite_export: biblatex numeric,backend=bibtex +@end example + + +@vindex org-cite-biblatex-options +@noindent +specifies the @samp{biblatex} export processor with the default @samp{numeric} +style and the @samp{bibtex} backend. Always define the style first and then +the rest of load-time options for the @samp{biblatex} +package. Alternatively, you can use the @code{key=val,key=val} format for +the options as documented in the @samp{biblatex} package documentation: + +@example +#+cite_export: biblatex backend=bibtex,style=numeric +@end example + + +The @code{org-cite-biblatex-options} variable in your Emacs configuration +uses this format. It will only export to PDF, since it relies on the +@code{biblatex} processor of your @LaTeX{} installation. + @node Bibliography printing @section Bibliography printing +@cindex @samp{PRINT_BIBLIOGRAPHY}, keyword The @samp{PRINT_BIBLIOGRAPHY} keyword specifies where the bibliography should be printed (note the colon): @@ -18099,8 +18984,8 @@ should be printed (note the colon): The bibliography printed by the @LaTeX{}-based export processors -``bibtex'', ``natbib'' and ``biblatex'' has a chapter or section heading by -default, while the ``basic'' and ``csl'' processors print the list of +@samp{bibtex}, @samp{natbib} and @samp{biblatex} has a chapter or section heading by +default, while the @samp{basic} and @samp{csl} processors print the list of bibliography entries without a heading. A document may contain more than one @samp{PRINT_BIBLIOGRAPHY} keywords. @@ -18114,18 +18999,18 @@ the different citation export processors. Some export processors do not support passing options. @menu -* Bibliography options in the ``biblatex'' and ``csl'' export processors:: +* Bibliography options in the @samp{biblatex} and @samp{csl} export processors:: @end menu -@node Bibliography options in the ``biblatex'' and ``csl'' export processors -@subsection Bibliography options in the ``biblatex'' and ``csl'' export processors +@node Bibliography options in the @samp{biblatex} and @samp{csl} export processors +@subsection Bibliography options in the @samp{biblatex} and @samp{csl} export processors -The ``biblatex'' and ``csl'' export processors support bibliography +The @samp{biblatex} and @samp{csl} export processors support bibliography options through a property list attached to the @samp{PRINT_BIBLIOGRAPHY} keyword. For example, @example -#print_bibliography: :keyword algebra :type book +#+print_bibliography: :keyword algebra :type book @end example @@ -18134,13 +19019,14 @@ need to use a key multiple times, you can separate its values with commas, but without any space in-between: @example -#print_bibliography: :keyword "algebraic logic" :nottype article,book +#+print_bibliography: :keyword "algebraic logic" :nottype article,book @end example -The ``biblatex'' export processor accepts all options supported by -Bib@LaTeX{}'s @code{\printbibliography} command, while the ``csl'' processor -accepts the following ones: +The @samp{biblatex} export processor accepts all options supported by +Bib@LaTeX{}'s @code{\printbibliography} command. + +The @samp{csl} processor accepts the following options: @table @asis @item @samp{:keyword } @@ -18248,7 +19134,7 @@ Org can extract one or more source code blocks and write them to one or more source files---a process known as @emph{tangling} in literate programming terminology. -For exporting and publishing, Org's back-ends can format a source code +For exporting and publishing, Org's backends can format a source code block appropriately, often with native syntax highlighting. For executing and compiling a source code block, the user can @@ -18328,7 +19214,8 @@ to capture the results. Code from other blocks, other files, and from table formulas (see @ref{The Spreadsheet}) can use the name to reference a source block. This naming serves the same purpose as naming Org tables. Org mode requires unique names. For duplicate -names, Org mode's behavior is undefined. +names, Org mode's behavior is undefined. Inline code blocks cannot +have a name. @item @samp{#+BEGIN_SRC} @dots{} @samp{#+END_SRC} Mandatory. They mark the start and end of a block that Org @@ -18337,9 +19224,16 @@ described next. @item @samp{} @cindex language, in code blocks -Mandatory. It is the identifier of the source code language in the +Optional. It is the identifier of the source code language in the block. See @ref{Languages}, for identifiers of supported languages. +When @samp{} identifier is omitted, the block also cannot +have @samp{} and @samp{
}. + +Language identifier is also used to fontify code blocks in Org +buffers, when @code{org-src-fontify-natively} is set to non-@code{nil}. See +@ref{Editing Source Code}. + @item @samp{} @cindex switches, in code blocks Optional. Switches provide finer control of the code execution, @@ -18574,8 +19468,6 @@ evaluation of @samp{factorial} code block. @node Environment of a Code Block @section Environment of a Code Block - - @anchor{Passing arguments} @subheading Passing arguments @@ -18610,6 +19502,10 @@ from the reference. @end example +When @samp{FILE} does not exist, the reference is searched in the current +file, using the verbatim reference. This way, +@samp{:var table=tbl:example} will be searched inside the current buffer. + Here are examples of passing values by reference: @table @asis @@ -18642,9 +19538,9 @@ The default value is @samp{nil}: if an input table has column names---because the second row is a horizontal rule---then Org removes the column names, processes the table, puts back the column names, and then writes the table to the results block. Using @samp{yes}, -Org does the same to the first row, even if the initial table does -not contain any horizontal rule. When set to @samp{no}, Org does not -pre-process column names at all. +Org does the same to the first non-hline row, even if the initial +table does not contain any horizontal rule. When set to @samp{no}, Org +does not pre-process column names at all. @example #+NAME: less-cols @@ -18654,7 +19550,7 @@ pre-process column names at all. | c | #+BEGIN_SRC python :var tab=less-cols :colnames nil - return [[val + '*' for val in row] for row in tab] +return [[val + '*' for val in row] for row in tab] #+END_SRC #+RESULTS: @@ -18679,7 +19575,7 @@ table-handling in Emacs. | two | 6 | 7 | 8 | 9 | 10 | #+BEGIN_SRC python :var tab=with-rownames :rownames yes - return [[val + 10 for val in row] for row in tab] +return [[val + 10 for val in row] for row in tab] #+END_SRC #+RESULTS: @@ -18729,6 +19625,7 @@ above, optionally followed by parentheses. @item code block with arguments A code block name, as assigned by @samp{NAME} keyword, followed by parentheses and optional arguments passed within the parentheses. +The block is evaluated with point at its location. @example #+NAME: double @@ -19299,7 +20196,7 @@ accepts such lines, as demonstrated in the following example. #+NAME: no-hline #+BEGIN_SRC python :var tab=many-cols :hlines no - return tab +return tab #+END_SRC #+RESULTS: no-hline @@ -19309,7 +20206,7 @@ accepts such lines, as demonstrated in the following example. #+NAME: hlines #+BEGIN_SRC python :var tab=many-cols :hlines yes - return tab +return tab #+END_SRC #+RESULTS: hlines @@ -19354,6 +20251,9 @@ the output file from the name of the code block, and its extension from the @samp{file-ext} header argument. In that case, both the name and the extension are mandatory. +Result can also be interpreted as path to file. See @samp{:results + link}. + @example #+name: circle #+BEGIN_SRC asymptote :results value file :file-ext pdf @@ -19394,13 +20294,18 @@ Choose one of the options; they are mutually exclusive. The default follows from the type specified above. @table @asis +@item @samp{raw} +Interpreted as raw Org mode. Inserted directly into the buffer. +Aligned if it is a table. Usage example: @samp{:results value raw}. + @item @samp{code} Result enclosed in a code block. Useful for parsing. Usage example: @samp{:results value code}. @item @samp{drawer} -Result wrapped in a @samp{RESULTS} drawer. Useful for containing @samp{raw} -or @samp{org} results for later scripting and automated processing. +Results are added directly to the Org file as with @samp{raw}, but are +wrapped in a @samp{RESULTS} drawer or results macro (for inline code +blocks), for later scripting and automated processing. Usage example: @samp{:results value drawer}. @item @samp{html} @@ -19428,6 +20333,9 @@ following example: [[file:org-mode-unicorn.svg]] @end example +If @samp{:file} header argument is omitted, interpret source block result +as the file path. + @item @samp{org} Results enclosed in a @samp{BEGIN_SRC org} block. For comma-escape, either @kbd{@key{TAB}} in the block, or export the file. Usage @@ -19437,12 +20345,9 @@ example: @samp{:results value org}. Result converted to pretty-print source code. Enclosed in a code block. Languages supported: Emacs Lisp, Python, and Ruby. Usage example: @samp{:results value pp}. - -@item @samp{raw} -Interpreted as raw Org mode. Inserted directly into the buffer. -Aligned if it is a table. Usage example: @samp{:results value raw}. @end table + @cindex @samp{wrap}, header argument The @samp{wrap} header argument unconditionally marks the results block by appending strings to @samp{#+BEGIN_} and @samp{#+END_}. If no string is @@ -19487,7 +20392,7 @@ Ignore the results completely. This option is similar to @samp{none}, but no processing is performed on the return value. Calling the code block programmatically (see @ref{How to evaluate source code}) or by reference (see @ref{Passing arguments} and @ref{Noweb Reference Syntax}) will -always yield nil. +always yield @code{nil}. @item @samp{append} Append results to the Org buffer. Latest results are at the bottom. @@ -19760,10 +20665,10 @@ the tangled file's executable permission. The @samp{tangle-mode} header argument specifies what permissions to set for tangled files by @code{set-file-modes}. Permissions are given by an octal value, which can be provided calling the @code{identity} function on -an elisp octal value. For instance, to create a read-only file one may -use @samp{:tangle-mode (identity #o444)}. To reduce the verbosity required, -a octal shorthand is defined, @samp{oXXX} (@samp{o} for octal). Using this, our -read-only example is @samp{:tangle-mode o444}. Omitting the @samp{o} prefix will +an elisp octal value. For instance, to create a read-only file one may +use @samp{:tangle-mode (identity #o444)}. To reduce the verbosity required, +a octal shorthand is defined, @samp{oXXX} (@samp{o} for octal). Using this, our +read-only example is @samp{:tangle-mode o444}. Omitting the @samp{o} prefix will cause the argument to be interpreted as an integer, which can lead to unexpected results (@samp{444} is the same as @samp{o674}). Two other shorthands are recognized, ls-style strings like @@ -19772,7 +20677,7 @@ Note that chmod-style permissions are based on @code{org-babel-tangle-default-file-mode}, which is @samp{#o544} by default. When @samp{:tangle-mode} and @samp{:shebang} are both specified, the give -@samp{:tangle-mode} will override the permissions from @samp{:shebang}. When +@samp{:tangle-mode} will override the permissions from @samp{:shebang}. When multiple source code blocks tangle to a single file with conflicting @samp{:tangle-mode} header arguments, Org's behavior is undefined. @@ -19917,6 +20822,9 @@ If an Emacs major-mode named @code{-mode} exists, where header line, then the edit buffer uses that major mode. Use this variable to arbitrarily map language identifiers to major modes. +When language identifier is omitted in the src block, Org mode's +behavior is undefined. + @item @code{org-src-window-setup} @vindex org-src-window-setup For specifying Emacs window arrangement when the new edit buffer is @@ -19940,10 +20848,13 @@ The default prompts for a confirmation. @vindex org-src-fontify-natively @vindex org-src-block-faces -Set @code{org-src-fontify-natively} to non-@code{nil} to turn on native code -fontification in the @emph{Org} buffer. Fontification of code blocks can -give visual separation of text and code on the display page. To -further customize the appearance of @code{org-block} for specific +Fontification of code blocks can give visual separation of text and +code on the display page. Set @code{org-src-fontify-natively} to non-@code{nil} +to turn on native code fontification in the @emph{Org} buffer. The +fontification follows the major mode used to edit the code block (see +@code{org-src-lang-modes} above). + +To further customize the appearance of @code{org-block} for specific languages, customize @code{org-src-block-faces}. The following example shades the background of regular blocks, and colors source blocks only for Python and Emacs Lisp languages. @@ -20045,6 +20956,31 @@ the second code block is expanded as #+END_SRC @end example +Note that noweb expansion does not automatically carry over @samp{:var} +header arguments@footnote{In the following example, attempting to evaluate +the second code block will give an error, because the variables +defined in the first code block will not be defined in the second +block. +@example +#+NAME: get-prompt +#+BEGIN_SRC emacs-lisp :var prompt="root> " :var command="ls" + (concat prompt command) +#+END_SRC +#+RESULTS: get-prompt +: root> ls +#+BEGIN_SRC emacs-lisp :noweb yes + <> +#+END_SRC +@end example +The previous block is expanded without setting @code{prompt} and @code{command} +values. +@example +#+BEGIN_SRC emacs-lisp + (concat prompt command) +#+END_SRC +@end example +}. + You may also include the contents of multiple blocks sharing a common @samp{noweb-ref} header argument, which can be set at the file, subtree, or code block level. In the example Org file shown next, the body of @@ -20081,9 +21017,10 @@ By default a newline separates each noweb reference concatenation. To use a different separator, edit the @samp{noweb-sep} header argument. Alternatively, Org can include the results of evaluation of a single -code block rather than its body. Evaluation occurs when parentheses, -possibly including arguments, are appended to the code block name, as -shown below. +code block rather than its body [@footnote{The reference is evaluated with +point at the referenced block, using its header arguments (including +inherited)}. Evaluation occurs when parentheses, possibly including +arguments, are appended to the code block name, as shown below. @example <> @@ -20101,7 +21038,7 @@ Given: @example #+NAME: some-code #+BEGIN_SRC python :var num=0 :results output :exports none - print(num*10) +print(num*10) #+END_SRC @end example @@ -20182,12 +21119,12 @@ exported code snippets. With: @example #+NAME: if-true #+BEGIN_SRC python :exports none - print('do things when true') +print('do things when true') #+end_src #+name: if-false #+begin_src python :exports none - print('do things when false') +print('do things when false') #+end_src @end example @@ -20196,10 +21133,10 @@ this code block: @example #+begin_src python :noweb yes :results output - if true: - <> - else: - <> +if true: + <> +else: + <> #+end_src @end example @@ -20457,6 +21394,7 @@ emacs -Q --batch --eval " * Protocols:: External access to Emacs and Org. * Org Crypt:: Encrypting Org files. * Org Mobile:: Viewing and capture on a mobile device. +* Drag and Drop & @code{yank-media}:: Dropping and pasting files and images @end menu @node Completion @@ -20936,15 +21874,18 @@ a property. @cindex @samp{SETUPFILE}, keyword The setup file or a URL pointing to such file is for additional in-buffer settings. Org loads this file and parses it for any -settings in it only when Org opens the main file. If URL is +settings in it when Org opens the main file. If URL is specified, the contents are downloaded and stored in a temporary -file cache. @kbd{C-c C-c} on the settings line parses and -loads the file, and also resets the temporary file cache. Org also -parses and loads the document during normal exporting process. Org -parses the contents of this document as if it was included in the -buffer. It can be another Org file. To visit the file---not -a URL---use @kbd{C-c '} while point is on the line with the -file name. +file cache. @kbd{C-c C-c} on the settings line re-parses and +re-loads the file, and also resets the temporary file cache. + +Org also parses and loads @emph{in-buffer settings} from the setup file +during normal exporting process. Org parses the @emph{in-buffer +settings} as if it was included in the containing Org buffer. The +rest of the contents of setup file is ignored. + +To visit the setup file---not a URL---use @kbd{C-c '} while point +is on the line with the setup file name. @item @samp{#+STARTUP:} @cindex @samp{STARTUP}, keyword @@ -21030,6 +21971,21 @@ avoid delays when visiting a file. @tab Do not show inline images on startup. @end multitable +@vindex org-link-descriptive +Bracket links in Org buffers are displayed hiding the link path and +brackets. For example, @samp{[[https://orgmode.org][Org Website]]} is, +by default, displayed as ``Org Website'', hiding the link itself and +just displaying its description. Alternatively, the links can be +displayed in full. The corresponding variable is +@code{org-link-descriptive}. + +@multitable {aaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} +@item @samp{descriptivelinks} +@tab Hide path and brackets in links. +@item @samp{literallinks} +@tab Do not hide anything. +@end multitable + @vindex org-log-done @vindex org-log-note-clock-out @vindex org-log-repeat @@ -21097,11 +22053,12 @@ variables are @code{org-hide-leading-stars} and @tab Allow all outline levels. @end multitable -@vindex org-put-time-stamp-overlays -@vindex org-time-stamp-overlay-formats +@vindex org-display-custom-times +@vindex org-timestamp-custom-formats +@vindex org-time-stamp-custom-formats To turn on custom format overlays over timestamps (variables -@code{org-put-time-stamp-overlays} and -@code{org-time-stamp-overlay-formats}), use: +@code{org-display-custom-times} and +@code{org-timestamp-custom-formats}), use: @multitable {aaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaa} @item @samp{customtime} @@ -21143,6 +22100,8 @@ corresponding variables are @code{org-footnote-define-inline}, @tab Automatically renumber and sort footnotes. @item @samp{nofnadjust} @tab Do not renumber and sort automatically. +@item @samp{fnanon} +@tab Create anonymous footnotes with @code{org-footnote-new}. @end multitable @vindex org-hide-block-startup @@ -21211,8 +22170,8 @@ For more information, see @ref{Regexps,Regular Expressions in Emacs,,emacs,}. @section Org Syntax A reference document providing a formal description of Org's syntax is -available as @uref{https://orgmode.org/worg/dev/org-syntax.html, a draft on Worg}, written and maintained by Nicolas -Goaziou. It defines Org's core internal concepts such as ``headlines'', +available as @uref{https://orgmode.org/worg/org-syntax.html, a draft on Worg}, initially written by Nicolas Goaziou. +It defines Org's core internal concepts such as ``headlines'', ``sections'', ``affiliated keywords'', ``(greater) elements'' and ``objects''. Each part of an Org document belongs to one of the previous categories. @@ -21397,12 +22356,12 @@ embedded calculations. See @ref{Embedded Mode,GNU Emacs Calc Manual,,calc,}. @vindex org-table-formula-constants Org can use names for constants in formulas in tables. Org can also -use calculation suffixes for units, such as @samp{M} for @samp{Mega}. For -a standard collection of such constants, install the @samp{constants} +use calculation suffixes for units, such as @samp{M} for @samp{Mega}. For a +standard collection of such constants, install the @samp{constants} package. Install version 2.0 of this package, available at -@uref{http://www.astro.uva.nl/~dominik/Tools}. Org checks if the function -@code{constants-get} has been autoloaded. Installation instructions are -in the file @samp{constants.el}. +@uref{https://github.com/cdominik/constants-for-Emacs}. Org checks if the +function @code{constants-get} has been autoloaded. Installation +instructions are in the file @samp{constants.el}. @item @samp{cdlatex.el} by Carsten Dominik @cindex @file{cdlatex.el} @@ -21426,6 +22385,10 @@ follows: By default the index is two levels deep---you can modify the depth using the option @code{org-imenu-depth}. +Org activates Imenu support only in the buffers opened after loading +Imenu library. To enable Imenu support in an already opened Org +buffer, reload Org. + @item @samp{speedbar.el} by Eric@tie{}M@.@tie{}Ludlam @cindex @file{speedbar.el} @@ -21681,6 +22644,10 @@ further based on their usage needs. For example, the normal @tab @kbd{C-c C-x @key{RIGHT}} @tab @tab +@item @kbd{C-c C-,} +@tab @kbd{C-c C-x s} +@tab +@tab @end multitable @node Protocols @@ -21892,8 +22859,8 @@ adding @code{:rewrites} rules like this: @noindent Since @samp{example.com/$} is used as a regular expression, it maps -@samp{http://example.com/}, @samp{https://example.com}, -@samp{http://www.example.com/} and similar to +@samp{https://example.com/}, @samp{https://example.com}, +@samp{https://www.example.com/} and similar to @samp{/home/user/example/index.php}. The @code{:rewrites} rules are searched as a last resort if and only if no @@ -21952,8 +22919,8 @@ specifying the respective key as property @samp{CRYPTKEY}, e.g.: :END: @end example -Note that @samp{CRYPTKEY} property is only effective when @code{org-crypt-key} -is set to non-nil. @code{nil} value of @code{org-crypt-key} makes Org use +Note that the @samp{CRYPTKEY} property is only effective when +@code{org-crypt-key} is non-@code{nil}. If @code{org-crypt-key} is @code{nil}, Org uses symmetric encryption unconditionally. Excluding the @samp{crypt} tag from inheritance prevents already encrypted @@ -22103,6 +23070,49 @@ most recent since the mobile application searches files that were last pulled. To get an updated agenda view with changes since the last pull, pull again. +@node Drag and Drop & @code{yank-media} +@section Drag and Drop & @code{yank-media} + +@cindex dropping files +@cindex dragging files +@cindex drag and drop +@cindex dnd +@vindex org-yank-dnd-method +Org mode supports drag and drop (DnD) of files. By default, Org asks +the user what must be done with the dropped file: attach it, insert +@samp{file:} link, or open the file. Customize @code{org-yank-dnd-method} to +set the default DnD action. + +When DnD method is ``attach'', Org mode first consults DnD metadata to +decide the attach method. For example, when file/files are dragged +from a file manager, Org may attach by copying or by moving. + +@vindex org-yank-dnd-default-attach-method +If Org cannot figure out which attachment method to use from the +metadata, it defaults to @code{org-yank-dnd-default-attach-method} @footnote{By +default, @code{org-yank-dnd-default-attach-method} is set to nil -- use the same +value as @code{org-attach-method} (@code{cp} by default).} + +@cindex pasting files, images from clipboard +Starting from Emacs 29, Org mode supports @code{yank-media} command to yank +images from the clipboard and files from a file manager. + +@vindex org-yank-image-save-method +When yanking images from clipboard, Org saves the image on disk and +inserts the image link to Org buffer. Images are either saved as +attachments to heading (default) or to a globally defined directory. +The save location is controlled by @code{org-yank-image-save-method}. + +@vindex org-yank-image-file-name-function +The yanked images are saved under automatically generated name. You +can customize @code{org-yank-image-file-name-function} to make Org query +the image names or change the naming scheme. + +When yanking files copied from a file manager, Org respects the value +of @code{org-yank-dnd-method}. Image files pasted this way also respect +the value of @code{org-yank-image-save-method} when the action to perform +is @samp{attach}. + @node Hacking @appendix Hacking @@ -22115,7 +23125,7 @@ of Org. * Hooks:: How to reach into Org's internals. * Add-on Packages:: Available extensions. * Adding Hyperlink Types:: New custom link types. -* Adding Export Back-ends:: How to write new export back-ends. +* Adding Export Backends:: How to write new export backends. * Tables in Arbitrary Syntax:: Orgtbl for LaTeX and other programs. * Dynamic Blocks:: Automatically filled blocks. * Special Agenda Views:: Customized views. @@ -22130,10 +23140,9 @@ of Org. @cindex hooks -Org has a large number of hook variables for adding functionality. -This appendix illustrates using a few. A complete list of hooks with -documentation is maintained by the Worg project at -@uref{https://orgmode.org/worg/doc.html#hooks}. +Org has a large number of hook variables for adding functionality. A +complete list of hooks with documentation is maintained by the Worg +project at @uref{https://orgmode.org/worg/doc.html#hooks}. @node Add-on Packages @appendixsec Add-on Packages @@ -22182,7 +23191,7 @@ The following @samp{ol-man.el} file implements it PATH should be a topic that can be thrown at the man command." (funcall org-man-command path)) -(defun org-man-store-link () +(defun org-man-store-link (&optional _interactive?) "Store a link to a man page." (when (memq major-mode '(Man-mode woman-mode)) ;; This is a man page, we do make this link. @@ -22244,41 +23253,43 @@ The rest of the file implements necessary variables and functions. For example, @code{org-man-store-link} is responsible for storing a link when @code{org-store-link} (see @ref{Handling Links}) is called from a buffer -displaying a man page. It first checks if the major mode is -appropriate. If check fails, the function returns @code{nil}, which -means it isn't responsible for creating a link to the current -buffer. Otherwise the function makes a link string by combining -the @samp{man:} prefix with the man topic. It also provides a default -description. The function @code{org-insert-link} can insert it back -into an Org buffer later on. +displaying a man page. It is passed an argument @code{interactive?} +which this function does not use, but other store functions use to +behave differently when a link is stored interactively by the user. +It first checks if the major mode is appropriate. If check fails, +the function returns @code{nil}, which means it isn't responsible for +creating a link to the current buffer. Otherwise the function +makes a link string by combining the @samp{man:} prefix with the man +topic. It also provides a default description. The function +@code{org-insert-link} can insert it back into an Org buffer later on. @end enumerate -@node Adding Export Back-ends -@appendixsec Adding Export Back-ends +@node Adding Export Backends +@appendixsec Adding Export Backends -@cindex Export, writing back-ends +@cindex Export, writing backends -Org's export engine makes it easy for writing new back-ends. The +Org's export engine makes it easy for writing new backends. The framework on which the engine was built makes it easy to derive new -back-ends from existing ones. +backends from existing ones. @findex org-export-define-backend @findex org-export-define-derived-backend The two main entry points to the export engine are: @code{org-export-define-backend} and @code{org-export-define-derived-backend}. To grok these functions, see @samp{ox-latex.el} for an example of defining -a new back-end from scratch, and @samp{ox-beamer.el} for an example of +a new backend from scratch, and @samp{ox-beamer.el} for an example of deriving from an existing engine. -For creating a new back-end from scratch, first set its name as +For creating a new backend from scratch, first set its name as a symbol in an alist consisting of elements and export functions. To -make the back-end visible to the export dispatcher, set @code{:menu-entry} -keyword. For export options specific to this back-end, set the +make the backend visible to the export dispatcher, set @code{:menu-entry} +keyword. For export options specific to this backend, set the @code{:options-alist}. -For creating a new back-end from an existing one, set +For creating a new backend from an existing one, set @code{:translate-alist} to an alist of export functions. This alist -replaces the parent back-end functions. +replaces the parent backend functions. For complete documentation, see @uref{https://orgmode.org/worg/dev/org-export-reference.html, the Org Export Reference on Worg}. @@ -22504,7 +23515,7 @@ Orgtbl mode has built-in translator functions: @code{orgtbl-to-csv} @code{orgtbl-to-latex}, @code{orgtbl-to-html}, @code{orgtbl-to-texinfo}, @code{orgtbl-to-unicode} and @code{orgtbl-to-orgtbl}. They use the generic translator, @code{orgtbl-to-generic}, which delegates translations to -various export back-ends. +various export backends. Properties passed to the function through the @samp{ORGTBL SEND} line take precedence over properties defined inside the function. For example, @@ -22544,7 +23555,7 @@ table. The first argument is the table whose lines are a list of fields or the symbol @code{hline}. The second argument is the property list consisting of parameters specified in the @samp{#+ORGTBL: SEND} line. Please share your translator functions by posting them to the Org -users mailing list, at @email{emacs-orgmode@@gnu.org}. +users mailing list, at @email{mailto:emacs-orgmode@@gnu.org}. @node Dynamic Blocks @appendixsec Dynamic Blocks @@ -22632,7 +23643,7 @@ Org provides a special hook to further limit items in agenda views: @code{agenda}, @code{agenda*}@footnote{ The @code{agenda*} view is the same as @code{agenda} except that it only considers @emph{appointments}, i.e., scheduled and deadline items that have a time specification @samp{[h]h:mm} in their -time-stamps.}, @code{todo}, @code{alltodo}, @code{tags}, @code{tags-todo}, @code{tags-tree}. +timestamps.}, @code{todo}, @code{alltodo}, @code{tags}, @code{tags-todo}, @code{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. @@ -22772,15 +23783,13 @@ Disable tag inheritance for agendas: @vindex org-agenda-ignore-properties @item -Disable parsing of some drawer properties: +Disable parsing of some properties: @lisp -(setq org-agenda-ignore-properties '(effort appt stats category)) +(setq org-agenda-ignore-properties '(stats)) @end lisp -The drawer properties you can disable in the agenda are effort -estimates (@code{effort}), appointments (@code{appt}), statistics (@code{stats}) -and subtree-local categories (@code{category}). +This will disable parsing and updating statistic cookies. @end itemize These options can be applied to selected agenda views. For more @@ -22967,7 +23976,7 @@ Get all property keys in the current buffer. @end defun @defun org-insert-property-drawer -Insert a property drawer for the current entry. Also +Insert a property drawer for the current entry. @end defun @defun org-entry-put-multivalued-property pom property &rest values @@ -23138,8 +24147,6 @@ The following example counts the number of entries with TODO keyword @node History and Acknowledgments @appendix History and Acknowledgments - - @anchor{From Carsten} @appendixsec From Carsten @@ -23161,7 +24168,7 @@ and intuitive editing features, and to incorporate project planning functionality directly into a notes file. Since the first release, literally thousands of emails to me or to the -@email{emacs-orgmode@@gnu.org, mailing list} have provided a constant stream of bug reports, feedback, +@email{mailto:emacs-orgmode@@gnu.org, mailing list} have provided a constant stream of bug reports, feedback, new ideas, and sometimes patches and add-on code. Many thanks to everyone who has helped to improve this package. I am trying to keep here a list of the people who had significant influence in shaping one @@ -24123,4 +25130,4 @@ that are mentioned in the manual. For a more complete list, use @printindex vr -@bye \ No newline at end of file +@bye diff --git a/elpa/org-9.6.7/doc/orgcard.tex b/elpa/org-9.7.17/doc/orgcard.tex similarity index 98% rename from elpa/org-9.6.7/doc/orgcard.tex rename to elpa/org-9.7.17/doc/orgcard.tex index 13e8b8d7..8741a9c4 100644 --- a/elpa/org-9.6.7/doc/orgcard.tex +++ b/elpa/org-9.7.17/doc/orgcard.tex @@ -9,13 +9,17 @@ % Specify how many you want here. \columnsperpage=3 +% Set letterpaper to 0 for A4 paper, 1 for letter (US) paper. Useful +% only when columnsperpage is 2 or 3. +\letterpaper=1 + % PDF output layout. 0 for A4, 1 for letter (US), a `l' is added for % a landscape layout. \input pdflayout.sty -\pdflayout=(0l) +\pdflayout=(1l) % Nothing else needs to be changed below this line. -% Copyright (C) 1987, 1993, 1996--1997, 2001--2023 Free Software +% Copyright (C) 1987, 1993, 1996--1997, 2001--2024 Free Software % Foundation, Inc. % This document is free software: you can redistribute it and/or modify @@ -108,17 +112,14 @@ \footline{\hss\folio} \def\makefootline{\baselineskip10pt\hsize6.5in\line{\the\footline}} \else %2 or 3 columns uses prereduced size + \hsize 3.2in \if 1\the\letterpaper - \hsize 3.2in \vsize 7.95in - \hoffset -.75in - \voffset -.745in \else - \hsize 3.2in \vsize 7.65in - \hoffset -.25in - \voffset -.745in \fi + \hoffset -.75in + \voffset -.745in \font\titlefont=cmbx10 \scaledmag2 \font\headingfont=cmbx10 \scaledmag1 \font\smallfont=cmr6 @@ -275,7 +276,7 @@ %**end of header -\title{Org-Mode Reference Card (1/2)} +\title{Org-Mode Reference Card} \centerline{(for version \orgversionnumber)} @@ -477,7 +478,7 @@ after ``{\tt :}'', and dictionary words elsewhere. \newcolumn -\title{Org-Mode Reference Card (2/2)} +\title{Org-Mode Reference Card} \centerline{(for version \orgversionnumber)} diff --git a/elpa/org-9.6.7/doc/orgguide.texi b/elpa/org-9.7.17/doc/orgguide.texi similarity index 89% rename from elpa/org-9.6.7/doc/orgguide.texi rename to elpa/org-9.7.17/doc/orgguide.texi index af7668e7..69a3dfde 100644 --- a/elpa/org-9.6.7/doc/orgguide.texi +++ b/elpa/org-9.7.17/doc/orgguide.texi @@ -13,7 +13,7 @@ @c %**end of header @copying -Copyright @copyright{} 2004--2023 Free Software Foundation, Inc. +Copyright @copyright{} 2004--2024 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -39,7 +39,7 @@ modify this GNU manual.'' @finalout @titlepage @title Org Mode Compact Guide -@subtitle Release 9.6 +@subtitle Release 9.7 @author The Org Mode Developers @page @vskip 0pt plus 1filll @@ -53,6 +53,7 @@ modify this GNU manual.'' @top Org Mode Compact Guide @insertcopying + @end ifnottex @menu @@ -202,8 +203,8 @@ Files with extension @samp{.org} will be put into Org mode automatically. If you find problems with Org, or if you have questions, remarks, or ideas about it, please mail to the Org mailing list -@email{emacs-orgmode@@gnu.org}. For information on how to submit bug -reports, see the main manual. +@email{mailto:emacs-orgmode@@gnu.org}. For information on how to submit bug +reports, see the @ref{Top,main manual,,org,}. @node Document Structure @chapter Document Structure @@ -257,10 +258,11 @@ See @ref{Miscellaneous} for a setup to realize this. Outlines make it possible to hide parts of the text in the buffer. Org uses just two commands, bound to @kbd{@key{TAB}} and -@kbd{S-@key{TAB}} to change the visibility in the buffer. +@kbd{S-@key{TAB}} (@code{org-cycle} and @code{org-shifttab}) to change the +visibility in the buffer. @table @asis -@item @kbd{@key{TAB}} +@item @kbd{@key{TAB}} (@code{org-cycle}) @emph{Subtree cycling}: Rotate current subtree among the states @example @@ -272,8 +274,8 @@ Org uses just two commands, bound to @kbd{@key{TAB}} and When called with a prefix argument (@kbd{C-u @key{TAB}}), or with the Shift key, global cycling is invoked. -@item @kbd{S-@key{TAB}} -@itemx @kbd{C-u @key{TAB}} +@item @kbd{S-@key{TAB}} (@code{org-global-cycle}) +@itemx @kbd{C-u @key{TAB}} (@code{org-cycle}) @emph{Global cycling}: Rotate the entire buffer among the states @example @@ -281,12 +283,12 @@ Shift key, global cycling is invoked. '--------------------------------------' @end example -@item @kbd{C-u C-u C-u @key{TAB}} +@item @kbd{C-u C-u C-u @key{TAB}} (@code{org-show-all}) Show all, including drawers. @end table When Emacs first visits an Org file, the global state is set to -OVERVIEW, i.e., only the top level headlines are visible. This can be +@code{showeverything}, i.e., all file content is visible. This can be configured through the variable @code{org-startup-folded}, or on a per-file basis by adding a @samp{STARTUP} keyword to @samp{overview}, @samp{content}, @samp{showall}, @samp{showeverything} or @samp{showlevels} (n = 2..5) like this: @@ -301,55 +303,58 @@ basis by adding a @samp{STARTUP} keyword to @samp{overview}, @samp{content}, The following commands jump to other headlines in the buffer. @table @asis -@item @kbd{C-c C-n} +@item @kbd{C-c C-n} (@code{org-next-visible-heading}) Next heading. +@item @kbd{C-c C-p} (@code{org-previous-visible-heading}) +Previous +heading. -@item @kbd{C-c C-p} -Previous heading. - -@item @kbd{C-c C-f} -Next heading same level. +@item @kbd{C-c C-f} (@code{org-backward-heading-same-level}) +Next +heading same level. -@item @kbd{C-c C-b} -Previous heading same level. +@item @kbd{C-c C-b} (@code{outline-backward-same-level}) +Previous +heading same level. -@item @kbd{C-c C-u} -Backward to higher level heading. +@item @kbd{C-c C-u} (@code{outline-up-heading}) +Backward to higher +level heading. @end table @node Structure Editing @section Structure Editing @table @asis -@item @kbd{M-@key{RET}} +@item @kbd{M-@key{RET}} (@code{org-meta-return}) Insert new heading with same level as current. If point is in a plain list item, a new item is created (see @ref{Plain Lists}). When this command is used in the middle of a line, the line is split and the rest of the line becomes the new headline@footnote{If you do not want the line to be split, customize the variable @code{org-M-RET-may-split-line}.}. -@item @kbd{M-S-@key{RET}} +@item @kbd{M-S-@key{RET}} (@code{org-insert-todo-heading}) Insert new TODO entry with same level as current heading. -@item @kbd{@key{TAB}} in new +@item @kbd{@key{TAB}} (@code{org-cycle}) in new @itemx empty entry In a new entry with no text yet, @kbd{@key{TAB}} cycles through reasonable levels. -@item @kbd{M-@key{LEFT}} -@itemx @kbd{M-@key{RIGHT}} +@item @kbd{M-@key{LEFT}} (@code{org-metaleft}) +@itemx @kbd{M-@key{RIGHT}} (@code{org-metaright}) Promote or demote current heading by one level. -@item @kbd{M-@key{UP}} -@itemx @kbd{M-@key{DOWN}} +@item @kbd{M-@key{UP}} (@code{org-move-subtree-up}) +@itemx @kbd{M-@key{DOWN}} (@code{org-move-subtree-down}) Move subtree up or down, i.e., swap with previous or next subtree of same level. -@item @kbd{C-c C-w} +@item @kbd{C-c C-w} (@code{org-refile}) Refile entry or region to a different location. See @ref{Refile and Copy}. -@item @kbd{C-x n s} -@itemx @kbd{C-x n w} +@item @kbd{C-x n s} (@code{org-narrow-to-subtree}) +@itemx @kbd{C-x n w} (@code{widen}) Narrow buffer to current subtree and widen it again. @end table @@ -370,11 +375,11 @@ Org mode contains several commands creating such trees, all these commands can be accessed through a dispatcher: @table @asis -@item @kbd{C-c /} +@item @kbd{C-c /} (@code{org-sparse-tree}) This prompts for an extra key to select a sparse-tree creating command. -@item @kbd{C-c / r} +@item @kbd{C-c / r} (@code{org-occur}) Occur. Prompts for a regexp and shows a sparse tree with all matches. Each match is also highlighted; the highlights disappear by pressing @kbd{C-c C-c}. @@ -427,37 +432,37 @@ The following commands act on items when point is in the first line of an item (the line with the bullet or number). @table @asis -@item @kbd{@key{TAB}} +@item @kbd{@key{TAB}} (@code{org-cycle}) Items can be folded just like headline levels. -@item @kbd{M-@key{RET}} +@item @kbd{M-@key{RET}} (@code{org-insert-heading}) Insert new item at current level. With a prefix argument, force a new heading (see @ref{Structure Editing}). -@item @kbd{M-S-@key{RET}} +@item @kbd{M-S-@key{RET}} (@code{org-insert-todo-heading}) Insert a new item with a checkbox (see @ref{Checkboxes}). -@item @kbd{M-S-@key{UP}} -@itemx @kbd{M-S-@key{DOWN}} +@item @kbd{M-@key{UP}} (@code{org-move-item-up}) +@itemx @kbd{M-@key{DOWN}} (@code{org-move-item-down}) Move the item including subitems up/down (swap with previous/next item of same indentation). If the list is ordered, renumbering is automatic. -@item @kbd{M-@key{LEFT}} -@itemx @kbd{M-@key{RIGHT}} +@item @kbd{M-@key{LEFT}} (@code{org-do-promote}) +@itemx @kbd{M-@key{RIGHT}} (@code{org-do-demote}) Decrease/increase the indentation of an item, leaving children alone. -@item @kbd{M-S-@key{LEFT}} -@itemx @kbd{M-S-@key{RIGHT}} +@item @kbd{M-S-@key{LEFT}} (@code{org-promote-subtree}) +@itemx @kbd{M-S-@key{RIGHT}} (@code{org-demote-subtree}) Decrease/increase the indentation of the item, including subitems. -@item @kbd{C-c C-c} +@item @kbd{C-c C-c} (@code{org-toggle-checkbox}) If there is a checkbox (see @ref{Checkboxes}) in the item line, toggle the state of the checkbox. Also verify bullets and indentation consistency in the whole list. -@item @kbd{C-c -} +@item @kbd{C-c -} (@code{org-cycle-list-bullet}) Cycle the entire list level through the different itemize/enumerate bullets (@samp{-}, @samp{+}, @samp{*}, @samp{1.}, @samp{1)}). @end table @@ -511,7 +516,7 @@ automatically made blank. @heading Creation and conversion @table @asis -@item @kbd{C-c |} +@item @kbd{C-c |} (@code{org-table-create-or-convert-from-region}) Convert the active region to table. If every line contains at least one @kbd{@key{TAB}} character, the function assumes that the material is tab separated. If every line contains a comma, comma-separated @@ -526,24 +531,24 @@ table. But it is easier just to start typing, like @kbd{| N a m e | P h o n e | @heading Re-aligning and field motion @table @asis -@item @kbd{C-c C-c} +@item @kbd{C-c C-c} (@code{org-table-align}) Re-align the table without moving point. -@item @kbd{@key{TAB}} +@item @kbd{@key{TAB}} (@code{org-table-next-field}) Re-align the table, move to the next field. Creates a new row if necessary. -@item @kbd{S-@key{TAB}} +@item @kbd{S-@key{TAB}} (@code{org-table-previous-field}) Re-align, move to previous field. -@item @kbd{@key{RET}} +@item @kbd{@key{RET}} (@code{org-table-next-row}) Re-align the table and move down to next row. Creates a new row if necessary. -@item @kbd{S-@key{UP}} -@itemx @kbd{S-@key{DOWN}} -@itemx @kbd{S-@key{LEFT}} -@itemx @kbd{S-@key{RIGHT}} +@item @kbd{S-@key{UP}} (@code{org-table-move-cell-up}) +@itemx @kbd{S-@key{DOWN}} (@code{org-table-move-cell-down}) +@itemx @kbd{S-@key{LEFT}} (@code{org-table-move-cell-left}) +@itemx @kbd{S-@key{RIGHT}} (@code{org-table-move-cell-right}) Move a cell up, down, left, and right by swapping with adjacent cell. @end table @@ -552,34 +557,34 @@ cell. @heading Column and row editing @table @asis -@item @kbd{M-@key{LEFT}}, @kbd{M-@key{RIGHT}} +@item @kbd{M-@key{LEFT}} (@code{org-table-move-column-left}), @kbd{M-@key{RIGHT}} (@code{org-table-move-column-right}) Move the current column left/right. -@item @kbd{M-S-@key{LEFT}} +@item @kbd{M-S-@key{LEFT}} (@code{org-table-delete-column}) Kill the current column. -@item @kbd{M-S-@key{RIGHT}} +@item @kbd{M-S-@key{RIGHT}} (@code{org-table-insert-column}) Insert a new column to the left of point position. -@item @kbd{M-@key{UP}}, @kbd{M-@key{DOWN}} +@item @kbd{M-@key{UP}} (@code{org-table-move-row-up}), @kbd{M-@key{DOWN}} (@code{org-table-move-row-down}) Move the current row up/down. -@item @kbd{M-S-@key{UP}} +@item @kbd{M-S-@key{UP}} (@code{org-table-kill-row}) Kill the current row or horizontal line. -@item @kbd{M-S-@key{DOWN}} +@item @kbd{M-S-@key{DOWN}} (@code{org-table-insert-row}) Insert a new row above the current row. With a prefix argument, the line is created below the current one. -@item @kbd{C-c -} +@item @kbd{C-c -} (@code{org-table-insert-hline}) Insert a horizontal line below current row. With a prefix argument, the line is created above the current line. -@item @kbd{C-c @key{RET}} +@item @kbd{C-c @key{RET}} (@code{org-table-hline-and-move}) Insert a horizontal line below current row, and move the point into the row below that line. -@item @kbd{C-c ^} +@item @kbd{C-c ^} (@code{org-table-sort-lines}) Sort the table lines in the region. The position of point indicates the column to be used for sorting, and the range of lines is the range between the nearest horizontal separator lines, or the entire @@ -700,7 +705,7 @@ From an Org buffer, the following commands create, navigate or, more generally, act on links. @table @asis -@item @kbd{C-c C-l} +@item @kbd{C-c C-l} (@code{org-insert-link}) Insert a link. This prompts for a link to be inserted into the buffer. You can just type a link, or use history keys @kbd{@key{UP}} and @kbd{@key{DOWN}} to access stored links. You will be prompted @@ -709,14 +714,14 @@ for the description part of the link. When called with a @kbd{C-u} prefix argument, file name completion is used to link to a file. -@item @kbd{C-c C-l} (with point on existing link) +@item @kbd{C-c C-l} (with point on existing link) (@code{org-insert-link}) When point is on an existing link, @kbd{C-c C-l} allows you to edit the link and description parts of the link. -@item @kbd{C-c C-o} +@item @kbd{C-c C-o} (@code{open-link-at-point}) Open link at point. -@item @kbd{C-c &} +@item @kbd{C-c &} (@code{org-mark-ring-goto}) Jump back to a recorded position. A position is recorded by the commands following internal links, and by @kbd{C-c %}. Using this command several times in direct succession moves through a ring @@ -759,7 +764,7 @@ for example: The most important commands to work with TODO entries are: @table @asis -@item @kbd{C-c C-t} +@item @kbd{C-c C-t} (@code{org-todo}) Rotate the TODO state of the current item among @example @@ -771,21 +776,21 @@ Rotate the TODO state of the current item among The same rotation can also be done ``remotely'' from the agenda buffer with the @kbd{t} command key (see @ref{Agenda Commands}). -@item @kbd{S-@key{RIGHT}} -@itemx @kbd{S-@key{LEFT}} +@item @kbd{S-@key{RIGHT}} (@code{org-shiftright}) +@itemx @kbd{S-@key{LEFT}} (@code{org-shiftleft}) Select the following/preceding TODO state, similar to cycling. -@item @kbd{C-c / t} +@item @kbd{C-c / t} (@code{org-show-todo-tree}) View TODO items in a @emph{sparse tree} (see @ref{Sparse Trees}). Folds the entire buffer, but shows all TODO items---with not-DONE state---and the headings hierarchy above them. -@item @kbd{M-x org-agenda t} +@item @kbd{M-x org-agenda t} (@code{org-todo-list}) Show the global TODO list. Collects the TODO items (with not-DONE states) from all agenda files (see @ref{Agenda Views}) into a single buffer. See @ref{Global TODO List}, for more information. -@item @kbd{S-M-@key{RET}} +@item @kbd{S-M-@key{RET}} (@code{org-insert-todo-heading}) Insert a new TODO entry below the current one. @end table @@ -848,7 +853,7 @@ To record a timestamp and a note when changing a TODO state, call the command @code{org-todo} with a prefix argument. @table @asis -@item @kbd{C-u C-c C-t} +@item @kbd{C-u C-c C-t} (@code{org-todo}) Prompt for a note and record a the time of the TODO state change. @end table @@ -929,7 +934,7 @@ highest, @samp{B} the default if none is given. Priorities make a difference only in the agenda. @table @asis -@item @kbd{C-c ,} +@item @kbd{C-c ,} (@code{org-priority}) Set the priority of the current headline. Press @kbd{A}, @kbd{B} or @kbd{C} to select a priority, or @kbd{@key{SPC}} to remove the cookie. @@ -985,11 +990,11 @@ checked. The following commands work with checkboxes: @table @asis -@item @kbd{C-c C-c} +@item @kbd{C-c C-c}, @kbd{C-u C-c C-c} (@code{org-toggle-checkbox}) Toggle checkbox status or---with prefix argument---checkbox presence at point. -@item @kbd{M-S-@key{RET}} +@item @kbd{M-S-@key{RET}} (@code{org-insert-todo-heading}) Insert a new item with a checkbox. This works only if point is already in a plain list item (see @ref{Plain Lists}). @end table @@ -1041,12 +1046,12 @@ After a colon, @kbd{M-@key{TAB}} offers completion on tags. There is also a special command for inserting tags: @table @asis -@item @kbd{C-c C-q} +@item @kbd{C-c C-q} (@code{org-set-tags-command}) Enter new tags for the current headline. Org mode either offers completion or a special single-key interface for setting tags, see below. -@item @kbd{C-c C-c} +@item @kbd{C-c C-c} (@code{org-set-tags-command}) When point is in a headline, this does the same as @kbd{C-c C-q}. @end table @@ -1117,19 +1122,18 @@ support with @code{org-toggle-tags-groups}, bound to @kbd{C-c C-x q}. @heading Tag searches @table @asis -@item @kbd{C-c / m} or @kbd{C-c \} +@item @kbd{C-c / m} or @kbd{C-c \} (@code{org-match-sparse-tree}) Create a sparse tree with all headlines matching a tags search. With a @kbd{C-u} prefix argument, ignore headlines that are not a TODO line. -@item @kbd{M-x org-agenda m} +@item @kbd{M-x org-agenda m} (@code{org-tags-view}) Create a global list of tag matches from all agenda files. See @ref{Matching Tags and Properties}. -@item @kbd{M-x org-agenda M} +@item @kbd{M-x org-agenda M} (@code{org-tags-view}) Create a global list of tag matches from all agenda files, but check -only TODO items and force checking subitems (see the option -@code{org-tags-match-list-sublevels}). +only TODO items. @end table These commands all prompt for a match string which allows basic @@ -1187,10 +1191,10 @@ a file, use a line like: The following commands help to work with properties: @table @asis -@item @kbd{C-c C-x p} +@item @kbd{C-c C-x p} (@code{org-set-property}) Set a property. This prompts for a property name and a value. -@item @kbd{C-c C-c d} +@item @kbd{C-c C-c d} (@code{org-delete-property}) Remove a property from the current entry. @end table @@ -1203,7 +1207,15 @@ properties, the same commands are used as for tag searches (see To assist project planning, TODO items can be labeled with a date and/or a time. The specially formatted string carrying the date and -time information is called a @emph{timestamp} in Org mode. +time information is called a @emph{timestamp} in Org mode. This may be +a little confusing because timestamp is often used as indicating when +something was created or last changed. However, in Org mode this term +is used in a much wider sense. + +Timestamps can be used to plan appointments, schedule tasks, set +deadlines, track time, and more. The following sections describe +the timestamp format and tooling that Org mode provides for common +use cases dealing with time and time intervals. @menu * Timestamps:: Assigning a time to a tree entry. @@ -1226,12 +1238,16 @@ the agenda (see @ref{Built-in Agenda Views}). We distinguish: @item Plain timestamp; Event; Appointment A simple timestamp just assigns a date/time to an item. This is just like writing down an appointment or event in a paper agenda. +There can be multiple timestamps in an item. @example * Meet Peter at the movies <2006-11-01 Wed 19:15> * Discussion on climate change <2006-11-02 Thu 20:00-22:00> +* My days off + <2006-11-03 Fri> + <2006-11-06 Mon> @end example @item Timestamp with repeater interval @@ -1246,8 +1262,6 @@ or years (y). The following shows up in the agenda every Wednesday: @end example @item Diary-style expression entries -@cindex diary style timestamps -@cindex sexp timestamps For more complex date specifications, Org mode supports using the special expression diary entries implemented in the Emacs Calendar package. For example, with optional time: @@ -1257,12 +1271,26 @@ package. For example, with optional time: <%%(diary-float t 4 2)> @end example +@item Time range +Time range is a timestamp having two time units connected by @samp{-} + +@example +* Discussion on climate change + <2006-11-02 Thu 10:00-12:00> +@end example + @item Time/Date range -Two timestamps connected by @samp{--} denote a range. +Two timestamps connected by @samp{--} denote a range. In the agenda, the +headline is shown on the first and last day of the range, and on any +dates that are displayed and fall in the range. The first example +specifies just the dates of the range while the second example +specifies a time range for each date. @example ** Meeting in Amsterdam <2004-08-23 Mon>--<2004-08-26 Thu> +** This weeks committee meetings + <2004-08-23 Mon 10:00-11:00>--<2004-08-26 Thu 10:00-11:00> @end example @item Inactive timestamp @@ -1284,23 +1312,23 @@ format. All commands listed below produce timestamps in the correct format. @table @asis -@item @kbd{C-c .} +@item @kbd{C-c .} (@code{org-timestamp}) Prompt for a date and insert a corresponding timestamp. When point is at an existing timestamp in the buffer, the command is used to modify this timestamp instead of inserting a new one. When this command is used twice in succession, a time range is inserted. With a prefix argument, it also adds the current time. -@item @kbd{C-c !} +@item @kbd{C-c !} (@code{org-timestamp-inactive}) Like @kbd{C-c .}, but insert an inactive timestamp that does not cause an agenda entry. -@item @kbd{S-@key{LEFT}} -@itemx @kbd{S-@key{RIGHT}} +@item @kbd{S-@key{LEFT}} (@code{org-timestamp-down-day}) +@itemx @kbd{S-@key{RIGHT}} (@code{org-timestamp-up-day}) Change date at point by one day. -@item @kbd{S-@key{UP}} -@itemx @kbd{S-@key{DOWN}} +@item @kbd{S-@key{UP}} (@code{org-timestamp-up}) +@itemx @kbd{S-@key{DOWN}} (@code{org-timestamp-down}) On the beginning or enclosing bracket of a timestamp, change its type. Within a timestamp, change the item under point. Point can be on a year, month, day, hour or minute. When the timestamp @@ -1314,7 +1342,7 @@ When Org mode prompts for a date/time, it accepts any string containing some date and/or time information, and intelligently interprets the string, deriving defaults for unspecified information from the current date and time. You can also select a date in the -pop-up calendar. See the manual for more information on how exactly +pop-up calendar. See the @ref{Top,manual,,org,} for more information on how exactly the date/time prompt works. @node Deadlines and Scheduling @@ -1324,7 +1352,7 @@ A timestamp may be preceded by special keywords to facilitate planning: @table @asis -@item @kbd{C-c C-d} +@item @kbd{C-c C-d} (@code{org-deadline}) Insert @samp{DEADLINE} keyword along with a time stamp, in the line following the headline. @@ -1343,7 +1371,7 @@ done. An example: The editor in charge is [[bbdb:Ford Prefect]] @end example -@item @kbd{C-c C-s} +@item @kbd{C-c C-s} (@code{org-schedule}) Insert @samp{SCHEDULED} keyword along with a stamp, in the line following the headline. @@ -1386,26 +1414,26 @@ Org mode allows you to clock the time you spend on specific tasks in a project. @table @asis -@item @kbd{C-c C-x C-i} +@item @kbd{C-c C-x C-i} (@code{org-clock-in}) Start the clock on the current item (clock-in). This inserts the @samp{CLOCK} keyword together with a timestamp. When called with a @kbd{C-u} prefix argument, select the task from a list of recently clocked tasks. -@item @kbd{C-c C-x C-o} +@item @kbd{C-c C-x C-o} (@code{org-clock-out}) Stop the clock (clock-out). This inserts another timestamp at the same location where the clock was last started. It also directly computes the resulting time in inserts it after the time range as @samp{=>HH:MM}. -@item @kbd{C-c C-x C-e} +@item @kbd{C-c C-x C-e} (@code{org-clock-modify-effort-estimate}) Update the effort estimate for the current clock task. -@item @kbd{C-c C-x C-q} +@item @kbd{C-c C-x C-q} (@code{org-clock-cancel}) Cancel the current clock. This is useful if a clock was started by mistake, or if you ended up working on something else. -@item @kbd{C-c C-x C-j} +@item @kbd{C-c C-x C-j} (@code{org-clock-goto}) Jump to the headline of the currently clocked in task. With a @kbd{C-u} prefix argument, select the target task from a list of recently clocked tasks. @@ -1455,21 +1483,21 @@ You may also define a global key for capturing new material (see @subheading Using capture @table @asis -@item @kbd{M-x org-capture} +@item @kbd{M-x org-capture} (@code{org-capture}) Start a capture process, placing you into a narrowed indirect buffer to edit. -@item @kbd{C-c C-c} +@item @kbd{C-c C-c} (@code{org-capture-finalize}) Once you have finished entering information into the capture buffer, @kbd{C-c C-c} returns you to the window configuration before the capture process, so that you can resume your work without further distraction. -@item @kbd{C-c C-w} +@item @kbd{C-c C-w} (@code{org-capture-refile}) Finalize the capture process by refiling the note to a different place (see @ref{Refile and Copy}). -@item @kbd{C-c C-k} +@item @kbd{C-c C-k} (@code{org-capture-kill}) Abort the capture process and return to the previous state. @end table @@ -1504,7 +1532,7 @@ the template for you like this: During expansion of the template, special %-escapes@footnote{If you need one of these sequences literally, escape the @samp{%} with a backslash.} allow dynamic insertion of content. Here is a small selection of the -possibilities, consult the manual for more. +possibilities, consult the @ref{Top,manual,,org,} for more. @multitable {aaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} @item @samp{%a} @@ -1529,7 +1557,7 @@ cumbersome. To simplify this process, you can use the following special command: @table @asis -@item @kbd{C-c C-w} +@item @kbd{C-c C-w} (@code{org-agenda-refile}) Refile the entry or region at point. This command offers possible locations for refiling the entry and lets you select one with completion. The item (or all items in the region) is filed below @@ -1540,13 +1568,13 @@ considered to be targets, but you can have more complex definitions across a number of files. See the variable @code{org-refile-targets} for details. -@item @kbd{C-u C-c C-w} +@item @kbd{C-u C-c C-w} (@code{org-agenda-refile}) Use the refile interface to jump to a heading. -@item @kbd{C-u C-u C-c C-w} +@item @kbd{C-u C-u C-c C-w} (@code{org-refile-goto-last-stored}) Jump to the location where @code{org-refile} last moved a tree to. -@item @kbd{C-c M-w} +@item @kbd{C-c M-w} (@code{org-refile-copy}) Copying works like refiling, except that the original note is not deleted. @end table @@ -1563,11 +1591,11 @@ The most common archiving action is to move a project tree to another file, the archive file. @table @asis -@item @kbd{C-c C-x C-a} +@item @kbd{C-c C-x C-a} (@code{org-archive-subtree-default}) Archive the current entry using the command specified in the variable @code{org-archive-default-command}. -@item @kbd{C-c C-x C-s} or short @kbd{C-c $} +@item @kbd{C-c C-x C-s} or short @kbd{C-c $} (@code{org-archive-subtree}) Archive the subtree starting at point position to the location given by @code{org-archive-location}. @end table @@ -1622,17 +1650,17 @@ The information to be shown is normally collected from all @emph{agenda files}, the files listed in the variable @code{org-agenda-files}. @table @asis -@item @kbd{C-c [} +@item @kbd{C-c [} (@code{org-agenda-file-to-front}) Add current file to the list of agenda files. The file is added to the front of the list. If it was already in the list, it is moved to the front. With a prefix argument, file is added/moved to the end. -@item @kbd{C-c ]} +@item @kbd{C-c ]} (@code{org-remove-file}) Remove current file from the list of agenda files. @item @kbd{C-'} -@itemx @kbd{C-,} +@itemx @kbd{C-,} (@code{org-cycle-agenda-files}) Cycle through agenda file list, visiting one file after the other. @end table @@ -1671,7 +1699,7 @@ The purpose of the weekly/daily @emph{agenda} is to act like a page of a paper agenda, showing all the tasks for the current week or day. @table @asis -@item @kbd{M-x org-agenda a} +@item @kbd{M-x org-agenda a} (@code{org-agenda-list}) Compile an agenda for the current week from a list of Org files. The agenda shows the entries for each day. @end table @@ -1707,11 +1735,11 @@ can change the state of a TODO entry with a single key press. For commands available in the TODO list, see @ref{Agenda Commands}. @table @asis -@item @kbd{M-x org-agenda t} +@item @kbd{M-x org-agenda t} (@code{org-todo-list}) Show the global TODO list. This collects the TODO items from all agenda files (see @ref{Agenda Views}) into a single buffer. -@item @kbd{M-x org-agenda T} +@item @kbd{M-x org-agenda T} (@code{org-todo-list}) Like the above, but allows selection of a specific TODO keyword. @end table @@ -1725,14 +1753,14 @@ syntax described here also applies when creating sparse trees with @kbd{C-c / m}. @table @asis -@item @kbd{M-x org-agenda m} +@item @kbd{M-x org-agenda m} (@code{org-tags-view}) Produce a list of all headlines that match a given set of tags. The command prompts for a selection criterion, which is a boolean logic expression with tags, like @samp{+work+urgent-withboss} or @samp{work|home} (see @ref{Tags}). If you often need a specific search, define a custom command for it (see @ref{Agenda Dispatcher}). -@item @kbd{M-x org-agenda M} +@item @kbd{M-x org-agenda M} (@code{org-tags-view}) Like @kbd{m}, but only select headlines that are also TODO items. @end table @@ -1761,7 +1789,7 @@ Like before, but require the @samp{laptop} lines to be tagged also @end table You may also test for properties at the same time as matching tags, -see the manual for more information. +see the @ref{Top,manual,,org,} for more information. @node Search View @section Search View @@ -1798,16 +1826,16 @@ file where they originate. You are not allowed to edit the agenda buffer itself, but commands are provided to show and jump to the original entry location, and to edit the Org files ``remotely'' from the agenda buffer. This is just a selection of the many commands, explore -the agenda menu and the manual for a complete list. +the agenda menu and the @ref{Top,manual,,org,} for a complete list. @anchor{Motion (1)} @subheading Motion @table @asis -@item @kbd{n} +@item @kbd{n} (@code{org-agenda-next-line}) Next line (same as @kbd{@key{DOWN}} and @kbd{C-n}). -@item @kbd{p} +@item @kbd{p} (@code{org-agenda-previous-line}) Previous line (same as @kbd{@key{UP}} and @kbd{C-p}). @end table @@ -1815,14 +1843,14 @@ Previous line (same as @kbd{@key{UP}} and @kbd{C-p}). @subheading View/Go to Org file @table @asis -@item @kbd{@key{SPC}} +@item @kbd{@key{SPC}} (@code{org-agenda-show-and-scroll-up}) Display the original location of the item in another window. With a prefix argument, make sure that drawers stay folded. -@item @kbd{@key{TAB}} +@item @kbd{@key{TAB}} (@code{org-agenda-goto}) Go to the original location of the item in another window. -@item @kbd{@key{RET}} +@item @kbd{@key{RET}} (@code{org-agenda-switch-to}) Go to the original location of the item and delete other windows. @end table @@ -1830,30 +1858,30 @@ Go to the original location of the item and delete other windows. @subheading Change display @table @asis -@item @kbd{o} +@item @kbd{o} (@code{delete-other-windows}) Delete other windows. -@item @kbd{v d} or short @kbd{d} +@item @kbd{v d} or short @kbd{d} (@code{org-agenda-day-view}) Switch to day view. -@item @kbd{v w} or short @kbd{w} +@item @kbd{v w} or short @kbd{w} (@code{org-agenda-week-view}) Switch to week view. -@item @kbd{f} +@item @kbd{f} (@code{org-agenda-later}) Go forward in time to display the span following the current one. For example, if the display covers a week, switch to the following week. -@item @kbd{b} +@item @kbd{b} (@code{org-agenda-earlier}) Go backward in time to display earlier dates. -@item @kbd{.} +@item @kbd{.} (@code{org-agenda-goto-today}) Go to today. -@item @kbd{j} +@item @kbd{j} (@code{org-agenda-goto-date}) Prompt for a date and go there. -@item @kbd{v l} or @kbd{v L} or short @kbd{l} +@item @kbd{v l} or @kbd{v L} or short @kbd{l} (@code{org-agenda-log-mode}) Toggle Logbook mode. In Logbook mode, entries that were marked as done while logging was on (see the variable @code{org-log-done}) are shown in the agenda, as are entries that have been clocked on that @@ -1861,11 +1889,11 @@ day. When called with a @kbd{C-u} prefix argument, show all possible logbook entries, including state changes. @item @kbd{r} -@itemx @kbd{g} +@itemx @kbd{g} (@code{org-agenda-redo}) Recreate the agenda buffer, for example to reflect the changes after modification of the timestamps of items. -@item @kbd{s} +@item @kbd{s} (@code{org-save-all-org-buffers}) @kindex C-x C-s @findex org-save-all-org-buffers @kindex s @@ -1880,50 +1908,50 @@ locations of IDs. @item @kbd{0--9} Digit argument. -@item @kbd{t} +@item @kbd{t} (@code{org-agenda-todo}) Change the TODO state of the item, both in the agenda and in the original Org file. -@item @kbd{C-k} +@item @kbd{C-k} (@code{org-agenda-kill}) Delete the current agenda item along with the entire subtree belonging to it in the original Org file. -@item @kbd{C-c C-w} +@item @kbd{C-c C-w} (@code{org-agenda-refile}) Refile the entry at point. -@item @kbd{a} +@item @kbd{a} (@code{org-agenda-archive-default-with-confirmation}) Archive the subtree corresponding to the entry at point using the default archiving command set in @code{org-archive-default-command}. -@item @kbd{$} +@item @kbd{$} (@code{org-agenda-archive}) Archive the subtree corresponding to the current headline. -@item @kbd{C-c C-s} +@item @kbd{C-c C-s} (@code{org-agenda-schedule}) Schedule this item. With a prefix argument, remove the scheduling timestamp -@item @kbd{C-c C-d} +@item @kbd{C-c C-d} (@code{org-agenda-deadline}) Set a deadline for this item. With a prefix argument, remove the deadline. -@item @kbd{S-@key{RIGHT}} +@item @kbd{S-@key{RIGHT}} (@code{org-agenda-do-date-later}) Change the timestamp associated with the current line by one day into the future. -@item @kbd{S-@key{LEFT}} +@item @kbd{S-@key{LEFT}} (@code{org-agenda-do-date-earlier}) Change the timestamp associated with the current line by one day into the past. -@item @kbd{I} +@item @kbd{I} (@code{org-agenda-clock-in}) Start the clock on the current item. -@item @kbd{O} +@item @kbd{O} (@code{org-agenda-clock-out}) Stop the previously started clock. -@item @kbd{X} +@item @kbd{X} (@code{org-agenda-clock-cancel}) Cancel the currently running clock. -@item @kbd{J} +@item @kbd{J} (@code{org-agenda-clock-goto}) Jump to the running clock in another window. @end table @@ -1931,10 +1959,10 @@ Jump to the running clock in another window. @subheading Quit and exit @table @asis -@item @kbd{q} +@item @kbd{q} (@code{org-agenda-quit}) Quit agenda, remove the agenda buffer. -@item @kbd{x} +@item @kbd{x} (@code{org-agenda-exit}) Exit agenda, remove the agenda buffer and all buffers loaded by Emacs for the compilation of the agenda. @end table @@ -2143,14 +2171,14 @@ The Org website[fn:1] now looks a lot better than it used to. The following commands handle footnotes: @table @asis -@item @kbd{C-c C-x f} +@item @kbd{C-c C-x f} (@code{org-footnote-action}) The footnote action command. When point is on a footnote reference, jump to the definition. When it is at a definition, jump to the (first) reference. Otherwise, create a new footnote. When this command is called with a prefix argument, a menu of additional options including renumbering is offered. -@item @kbd{C-c C-c} +@item @kbd{C-c C-c} (@code{org-ctrl-c-ctrl-c}) Jump between definition and reference. @end table @@ -2181,7 +2209,7 @@ A hierarchical menu presents the currently configured export formats. Options are shown as easy toggle switches on the same screen. @table @asis -@item @kbd{C-c C-e} +@item @kbd{C-c C-e} (@code{org-export-dispatch}) Invokes the export dispatcher interface. @end table @@ -2271,7 +2299,7 @@ any other keyword or priority cookie, comments out the entire subtree. The command below helps changing the comment status of a headline. @table @asis -@item @kbd{C-c ;} +@item @kbd{C-c ;} (@code{org-toggle-comment}) Toggle the @samp{COMMENT} keyword at the beginning of an entry. @end table @@ -2285,7 +2313,7 @@ characters and symbols available in this encoding standards. @table @asis @item @kbd{C-c C-e t a} -@itemx @kbd{C-c C-e t u} +@itemx @kbd{C-c C-e t u} (@code{org-ascii-export-to-ascii}) Export as an ASCII file with a @samp{.txt} extension. For @samp{myfile.org}, Org exports to @samp{myfile.txt}, overwriting without warning. For @samp{myfile.txt}, Org exports to @samp{myfile.txt.txt} in order to prevent @@ -2299,13 +2327,13 @@ Org mode contains an HTML exporter with extensive HTML formatting compatible with XHTML 1.0 strict standard. @table @asis -@item @kbd{C-c C-e h h} +@item @kbd{C-c C-e h h} (@code{org-html-export-to-html}) Export as HTML file with a @samp{.html} extension. For @samp{myfile.org}, Org exports to @samp{myfile.html}, overwriting without warning. @kbd{C-c C-e h o} exports to HTML and opens it in a web browser. @end table -The HTML export back-end transforms @samp{<} and @samp{>} to @samp{<} and @samp{>}. -To include raw HTML code in the Org file so the HTML export back-end +The HTML export backend transforms @samp{<} and @samp{>} to @samp{<} and @samp{>}. +To include raw HTML code in the Org file so the HTML export backend can insert that HTML code in the output, use this inline syntax: @samp{@@@@html:...@@@@}. For example: @@ -2327,7 +2355,7 @@ For larger raw HTML code blocks, use these HTML export code blocks: @node @LaTeX{} Export @section @LaTeX{} Export -The @LaTeX{} export back-end can handle complex documents, incorporate +The @LaTeX{} export backend can handle complex documents, incorporate standard or custom @LaTeX{} document classes, generate documents using alternate @LaTeX{} engines, and produce fully linked PDF files with indexes, bibliographies, and tables of contents, destined for @@ -2338,19 +2366,19 @@ this by adding an option like @samp{#+LATEX_CLASS: myclass} in your file. The class must be listed in @code{org-latex-classes}. @table @asis -@item @kbd{C-c C-e l l} +@item @kbd{C-c C-e l l} (@code{org-latex-export-to-latex}) Export to a @LaTeX{} file with a @samp{.tex} extension. For @samp{myfile.org}, Org exports to @samp{myfile.tex}, overwriting without warning. -@item @kbd{C-c C-e l p} +@item @kbd{C-c C-e l p} (@code{org-latex-export-to-pdf}) Export as @LaTeX{} file and convert it to PDF file. -@item @kbd{C-c C-e l o} +@item @kbd{C-c C-e l o} (@code{}) Export as @LaTeX{} file and convert it to PDF, then open the PDF using the default viewer. @end table -The @LaTeX{} export back-end can insert any arbitrary @LaTeX{} code, see +The @LaTeX{} export backend can insert any arbitrary @LaTeX{} code, see @ref{Embedded @LaTeX{}}. There are three ways to embed such code in the Org file and they all use different quoting syntax. @@ -2368,7 +2396,7 @@ Inserting as one or more keyword lines in the Org file: @end example -Inserting as an export block in the Org file, where the back-end +Inserting as an export block in the Org file, where the backend exports any code between begin and end markers: @example @@ -2382,15 +2410,15 @@ exports any code between begin and end markers: A large part of Org mode's interoperability success is its ability to easily export to or import from external applications. The iCalendar -export back-end takes calendar data from Org files and exports to the +export backend takes calendar data from Org files and exports to the standard iCalendar format. @table @asis -@item @kbd{C-c C-e c f} +@item @kbd{C-c C-e c f} (@code{org-icalendar-export-to-ics}) Create iCalendar entries from the current Org buffer and store them in the same directory, using a file extension @samp{.ics}. -@item @kbd{C-c C-e c c} +@item @kbd{C-c C-e c c} (@code{org-icalendar-combine-agenda-files}) Create a combined iCalendar file from Org files in @code{org-agenda-files} and write it to @code{org-icalendar-combined-agenda-file} file name. @@ -2409,7 +2437,7 @@ You can also use Org to convert files into PDF, or even combine HTML and PDF conversion so that files are available in both formats on the server. -For detailed instructions about setup, see the manual. Here is an +For detailed instructions about setup, see the @ref{Top,manual,,org,}. Here is an example: @lisp @@ -2426,17 +2454,17 @@ example: @end lisp @table @asis -@item @kbd{C-c C-e P x} +@item @kbd{C-c C-e P x} (@code{org-publish}) Prompt for a specific project and publish all files that belong to it. -@item @kbd{C-c C-e P p} +@item @kbd{C-c C-e P p} (@code{org-publish-current-project}) Publish the project containing the current file. -@item @kbd{C-c C-e P f} +@item @kbd{C-c C-e P f} (@code{org-publish-current-file}) Publish only the current file. -@item @kbd{C-c C-e P a} +@item @kbd{C-c C-e P a} (@code{org-publish-all}) Publish every project. @end table @@ -2533,7 +2561,7 @@ Use @kbd{C-c C-c} to evaluate the current code block and insert its results in the Org document. By default, evaluation is only turned on for @samp{emacs-lisp} code blocks, however support exists for evaluating blocks in many languages. For a complete list of supported -languages see the manual. The following shows a code block and its +languages see the @ref{Top,manual,,org,}. The following shows a code block and its results. @example @@ -2613,14 +2641,12 @@ referred to as ``tangling''---a term adopted from the literate programming community. During tangling of code blocks their bodies are expanded using @code{org-babel-expand-src-block}, which can expand both variable and ``Noweb'' style references. In order to tangle a code -block it must have a @samp{tangle} header argument, see the manual for +block it must have a @samp{tangle} header argument, see the @ref{Top,manual,,org,} for details. @node Miscellaneous @chapter Miscellaneous - - @anchor{Completion} @heading Completion @@ -2639,7 +2665,7 @@ To quickly insert empty structural blocks, such as @samp{#+BEGIN_SRC} @dots{} @samp{#+END_SRC}, or to wrap existing text in such a block, use @table @asis -@item @kbd{C-c C-,} +@item @kbd{C-c C-,} (@code{org-insert-structure-template}) Prompt for a type of block structure, and insert the block at point. If the region is active, it is wrapped in the block. @end table @@ -2685,4 +2711,4 @@ support in a file, use #+STARTUP: hidestars odd @end example -@bye \ No newline at end of file +@bye diff --git a/elpa/org-9.6.7/doc/pdflayout.sty b/elpa/org-9.7.17/doc/pdflayout.sty similarity index 100% rename from elpa/org-9.6.7/doc/pdflayout.sty rename to elpa/org-9.7.17/doc/pdflayout.sty diff --git a/elpa/org-9.6.7/doc/texinfo.tex b/elpa/org-9.7.17/doc/texinfo.tex similarity index 100% rename from elpa/org-9.6.7/doc/texinfo.tex rename to elpa/org-9.7.17/doc/texinfo.tex diff --git a/elpa/org-9.6.7/etc/Makefile b/elpa/org-9.7.17/etc/Makefile similarity index 100% rename from elpa/org-9.6.7/etc/Makefile rename to elpa/org-9.7.17/etc/Makefile diff --git a/elpa/org-9.6.7/etc/ORG-NEWS b/elpa/org-9.7.17/etc/ORG-NEWS similarity index 79% rename from elpa/org-9.6.7/etc/ORG-NEWS rename to elpa/org-9.7.17/etc/ORG-NEWS index 5f92c056..bb8d5d32 100644 --- a/elpa/org-9.6.7/etc/ORG-NEWS +++ b/elpa/org-9.7.17/etc/ORG-NEWS @@ -6,11 +6,1692 @@ ORG NEWS -- history of user-visible changes. -*- mode: org; coding: utf-8 -*- #+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-2023 Free Software Foundation, Inc. +Copyright (C) 2012-2024 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.7 + +** Important announcements and breaking changes + +# Here, we list the *most important* changes and changes that _likely_ +# require user action for most Org mode users. +# Sorted from most important to least important. +*** Arbitrary shell commands may no longer run when turning on Org mode + +This is for security reasons, to avoid running malicious commands. + +*** =python-mode.el (MELPA)= support in =ob-python.el= is removed + +=python-mode.el= support has been removed from =ob-python.el=. The +related customization =org-babel-python-mode= has been changed to a +constant. + +If you still want to use python-mode with ob-python, you might +consider [[https://gitlab.com/jackkamm/ob-python-mode-mode][ob-python-mode-mode]], where the code to support python-mode +has been ported to. +*** It is no longer possible to reveal hidden parts of the links during isearch + +Org 9.6 introduced support for searching hidden parts of the links. + +Unfortunately, we had to drop this support because its implementation +turned out to be unreliable for many users. Proper implementation +would require patching =isearch.el= and possibly a number of external +libraries implementing isearch equivalents. It cannot be done on Org +side alone. + +*** =ox-latex=: ~org-latex-line-break-safe~ is deprecated + +~org-latex-line-break-safe~ constant was previously introduced to deal +with edge cases when LaTeX interprets [...] as LaTeX command +argument. However, it caused a number of other issues and proved +itself not to be as "safe" as it supposed to be. + +We now use a Pandoc's approach to deal with the same problem, +utilizing ={[}= to escape =[...]= instances where needed. + +*** ~tab-width~ value is now assumed to be 8 + +Org mode now assumes tab width to be 8 characters, when calculating +list and other indentation. ~tab-width~ is also set to 8 when Org +major mode is loaded. + +This is done to improve consistency of the markup for lists, where +indentation affects list items. + +Users with non-default values of ~tab-width~ should avoid overriding +the value of 8 set by Org mode. If the custom ~tab-width~ value is +_smaller_ than 8, the existing Org documents can be converted to the +new standard tab width using the following helper command: + +#+begin_src emacs-lisp +(defun org-compat-adjust-tab-width-in-buffer (old-width) + "Adjust visual indentation from `tab-width' equal OLD-WIDTH to 8." + (interactive "nOld `tab-width': ") + (cl-assert (derived-mode-p 'org-mode)) + (unless (= old-width 8) + (org-with-wide-buffer + (goto-char (point-min)) + (let (bound + (repl (if (< old-width 8) + (make-string old-width ?\s) + (concat "\t" (make-string (- old-width 8) ?\s))))) + (while (re-search-forward "^ *\t" nil t) + (skip-chars-forward " \t") + (setq bound (point-marker)) + (forward-line 0) + (while (search-forward "\t" bound t) + (replace-match repl))))))) +#+end_src + +*** ~org-ctags~ is not activated by default any more + +To follow Emacs [[info:elisp#Coding Conventions][coding conventions]] and to avoid confusion of users +who accidentally get ~org-ctags~ autoloaded due to help completion, +the library does not modify ~org-open-link-functions~ during loading +any more. Run ~org-ctags-enable~ to setup hooks and advices: + +#+begin_src emacs-lisp +(with-eval-after-load "org-ctags" + (org-ctags-enable)) +#+end_src + +*** "Priority" used to sort items in agenda is renamed to "urgency" + +Previously, ~priority-up~ and ~priority-down~ in +~org-agenda-sorting-strategy~ used a composite rank depending on +item's priority (=[#A]=, =[#B]=, =[#C]=, etc) and overdue time to +order agenda items (see "11.4.3 Sorting of agenda items" section of +Org manual). + +Now, this composite rank is renamed to =urgency= and the relevant +sorting strategies are renamed to ~urgency-up~ and ~urgency-down~. +~priority-up~ and ~priority-down~ sort by item's priority only. + +Users relying on the previous composite ranking should adjust their +agenda sorting settings. + +*** ~org-priority-show~ command no longer adjusts for scheduled/deadline + +In agenda views, ~org-priority-show~ command previously displayed the +composite rank consisting of the item priority and overdue. This is +no longer the case. The displayed and returned value only depends on +the item priority now. + +The behavior in Org buffers is unchanged. + +*** =ox-icalendar.el= line ending fix may affect downstream packages + +iCalendar export now uses dos-style CRLF ("\r\n") line endings +throughout, as required by the iCalendar specification (RFC 5545). +Previously, the export used an inconsistent mix of dos and unix line +endings. + +This might cause errors in external packages that parse output from +ox-icalendar. In particular, older versions of org-caldav may +encounter issues, and users are advised to update to the most recent +version of org-caldav. See [[https://github.com/dengste/org-caldav/commit/618bf4cdc9be140ca1993901d017b7f18297f1b8][this org-caldav commit]] for more information. + +*** Icalendar export of unscheduled TODOs no longer have start time of today + +For TODOs without a scheduled start time, ox-icalendar no longer +forces them to have a scheduled start time of today when exporting. + +Instead, the new customization ~org-icalendar-todo-unscheduled-start~ +controls the exported start date for unscheduled tasks. Its default +is ~recurring-deadline-warning~ which will export unscheduled tasks +with no start date, unless it has a recurring deadline (in which case +the iCalendar spec demands a start date, and +~org-deadline-warning-days~ is used for that). + +To revert to the old behavior, set +~org-icalendar-todo-unscheduled-start~ to ~current-datetime~. + +*** Built-in HTML, LaTeX, Man, Markdown, ODT, and Texinfo exporters preserve the link protocol during export + +Previously, some link types where not exported as =protocol:uri= but +as bare =uri=. This is now changed. + +When a link is known by Org mode and does not have a custom ~:export~ +parameter (see A.3 Adding Hyperlink Types section of the manual), the +link protocol is now not stripped. + +For example, if one adds a link type =tel=, but does not define +~:export~ parameter +: (org-link-set-parameters "tel") +=[[tel:12345][John Doe]]= link will be correctly exported to LaTeX as +=\href{tel:12345}{John Doe}=, not =\href{12345}{John Doe}=. + +However, links like =[[elisp:(+ 1 2)]]= will be exported as +=\url{elisp:(+ 1 2)}=, which may be somewhat unexpected. + +*** =ox-html=: When exporting footnotes with custom non-number names, the names are used as link anchors + +Previously, link anchors for footnote references and footnote +definitions were based on the footnote number: =fn.1=, =fnr.15=, etc. + +Now, when the footnote has a non-number name, it is used as an anchor: +=fn.name=, =fnr.name=. + +*** =ox-org= disables citation processors by default + +Previously, when exporting to Org, all the citations and +=print_bibliography= keywords, were transformed according to the +chosen citation processor. + +This is no longer the case. All the citation-related markup is now +exported as is. + +The previous behavior can be reverted by setting new custom option +~org-org-with-cite-processors~. + +*** ODT export no longer opens the exported file in the background + +ODT exporter used to open the exported file in ~archive-mode~ "for +examination". This was not documented, was done in the background, +and is not consistent with all other export backends. Now, this +feature is removed. + +*** Inline image width value in =#+attr_org= is preferred over other =#+attr_...= keywords + +Previously, when ~org-image-actual-width~ is a list or nil, Org used the +first =#+attr_...= keyword containing =:width ...= to compute the inline +image width. Now, =#+attr_org=, if present, takes precedence. +In the following example the image preview has width of 75% +while earlier versions pick 33%. + +: #+attr_html: :width 33% +: #+attr_org: :width 0.75 +: [[image.png]] + +*** ~org-latex-to-mathml-convert-command~ and ~org-latex-to-html-convert-command~ may need to be adjusted + +Previously, =%i= placeholders in the +~org-latex-to-mathml-convert-command~ and +~org-latex-to-html-convert-command~ user options were replaced with +raw LaTeX fragment text, potentially triggering shell-expansion and +incorrect result. + +Now, the =%i= placeholders are shell-escaped to prevent shell +expansion. + +If you have single or double quotes around =%i= then update +customizations and remove quotes. + +*** ~org-insert-subheading~ no longer inserts a sub-heading above current when point is at the beginning of line + +Previously, calling ~org-insert-subheading~ on + +: * Heading 1 +: * Heading 2 + +yielded + +: * Heading 1 +: ** +: * Heading 2 + +This is no longer the case. The sub-heading is always created below +current heading (prefix arguments have the same meaning as in +~org-insert-heading~): + +: * Heading 1 +: * Heading 2 +: ** + +*** It is no longer allowed to tangle into the same file as Org source + +Previously, =file.org= with the following contents + +: #+begin_src org :tangle file.org +: Text +: #+end_src + +would overwrite itself. + +Now, an error is thrown. + +** New features + +# We list the most important features, and the features that may +# require user action to be used. + +*** Images and files in clipboard can be pasted + +Org asks the user what must be done when pasting images and files +copied to the clipboard from a file manager using the ~yank-media~ +command. The default action can be set by customizing +~org-yank-dnd-method~. The ~yank-media~ command was added in Emacs 29. + +Images can be saved to a separate directory instead of being attached, +customize ~org-yank-image-save-method~. + +Image filename chosen can be customized by setting +~org-yank-image-file-name-function~ which by default autogenerates a +filename based on the current time. + +Note that ~yank-media~, as of Emacs 30, does not yet support Windows +(Emacs bug#71909) and may not be always reliable on Mac (Emacs +bug#71731). + +*** Files and images can be attached by dropping onto Emacs + +By default, Org asks the user what to do with the dropped file like +for pasted files. The same user option ~org-yank-dnd-method~ is +respected. + +Images dropped also respect the value of ~org-yank-image-save-method~ +when ~org-yank-dnd-method~ is =attach=. + +*** Alignment of image previews can be customized + +Previously, all the image previews were always left-aligned. + +Now, you can customize image previews to be left-aligned, centered, or right-aligned. + +The customization can be done globally, via ~org-image-align~, or per +image, using =#+attr_...:=. Example: + +: #+attr_org: :align center +: [[/path/to/image/file/png]] +: +: or +: +: #+attr_org: :center t +: [[/path/to/image/file/png]] + +When =#+attr_org= is not present, ~:align~ and ~:center~ attributes +from other =#+attr_...:= keywords will be used. + +*** =id:= links support search options; ~org-id-store-link~ adds search option by default + +Adding search option by ~org-id-store-link~ can be disabled by setting +~org-id-link-use-context~ to ~nil~, or toggled for a single call by +passing universal argument. + +When using this feature, IDs should not include =::=, which is used in +links to indicate the start of the search string. For backwards +compatibility, existing IDs including =::= will still be matched (but +cannot be used together with search option). A new org-lint checker +has been added to warn about this. + +*** Org mode no longer disallows configuring ~display-buffer-alist~ to open Org popups in other frame + +Previously, Org mode disallowed pop-up frames when displaying dispatch buffers. +This is no longer the case. ~display-buffer-alist~ is fully obeyed. + +~org-switch-to-buffer-other-window~ and ~org-no-popups~ are now deprecated. + +*** Asynchronous code evaluatation in ~ob-shell~ + +Running shell blocks with the ~:session~ header freezes Emacs until +execution completes. The new ~:async~ header allows users to continue +editing with Emacs while a ~:session~ block executes. + +*** Add support for repeating tasks in iCalendar export + +Repeating Scheduled and Deadline timestamps in TODOs are now exported +as recurring tasks in iCalendar export. + +In case the TODO has just a single planning timestamp (Scheduled or +Deadline, but not both), its repeater is used as the iCalendar +recurrence rule (RRULE). + +If the TODO has both Scheduled and Deadline planning timestamps, then +the following cases are implemented: + +- If both have the same repeater, then it is used as the RRULE. +- Scheduled has repeater but Deadline does not: the Scheduled repeater + is used as RRULE, and Deadline is used as UNTIL (the end date for + the repeater). This is similar to ~repeated-after-deadline~ in + ~org-agenda-skip-scheduled-if-deadline-is-shown~. + +The following 2 cases are not yet implemented, and the repeater is +skipped (with a warning) if the ox-icalendar export encounters them: + +- Deadline has a repeater but Scheduled does not. +- Scheduled and Deadline have different repeaters. + +Also note that only vanilla repeaters are currently exported; the +special repeaters ~++~ and ~.+~ are skipped. + +*** Babel references =FILE:REFERENCE= now search current buffer when =FILE= does not exist + +When =FILE= does not exist, the reference is searched in the current +file, using the verbatim reference. This way, +=:var table=tbl:example= will be searched inside the current buffer. + +*** Folded lines can now extend their face beyond ellipsis + +Previously, ~:extend t~ face attribute did not make folded headlines, +blocks, and drawers extend their face beyond end of line. + +Now, the ellipsis and trailing newline use the same face as the last +character before the fold. + +*** iCalendar export now supports multiline =SUMMARY=, =LOCATION=, and =DESCRIPTION= properties + +Previously, it was not possible to specify multi-line location, +summary, or description when exporting to iCalendar. + +In the following example, =LOCATION= was exported as "Someplace", +ignoring the other lines. + +#+begin_src org +,* heading with multi-line property +:PROPERTIES: +:LOCATION: Someplace +:LOCATION+: Some Street 5 +:LOCATION+: 12345 Small Town +:END: +#+end_src + +Now, =SUMMARY+=, =LOCATION+=, and =DESCRIPTION+= properties can be +used to create multi-line values. + +In the above example, =LOCATION= is now exported as + +: Someplace +: Some Street 5 +: 12345 Small Town + +*** Org export backends can now disable citation processors + +A new global export option ~:with-cite-processors~, when set to nil, +disables citation processors completely. This option is available to +export backends via ~:options-alist~ when defining the backend. + +The backends disabling citation processors must take care about +exporting citation objects and =print_bibliography= keywords via +transcoders. + +Users can disable citations processors by customizing new +~org-export-process-citations~ option. + +*** Org babel backends are now expected to define an additional API function ~org-babel-session-buffer:~ + +Org babel now uses session buffer (if it exists) to retrieve +~default-directory~ environment during src block evaluation. + +By default, buffer named like session is checked. All the backends +that create sessions inside buffers named differently should provide a +function ~org-babel-session-buffer:~. The function must accept +two arguments - session name and info list (as returned by +~org-babel-get-src-block-info~); and return the session buffer name. + +*** ~org-paste-subtree~ now handles =C-u= and =C-u C-u= prefix arguments specially + +With =C-u= prefix argument, force inserting a sibling heading below. +With =C-u C-u= prefix argument, force inserting a child heading. + +*** ~org-metaup~ and ~org-metadown~ now act on headings in region + +When region is active and starts at a heading, ~org-metaup~ and +~org-metadown~ will move all the selected subtrees. + +*** Many structure editing commands now do not deactivate region + +Moving, promoting, and demoting of headings and items in region now do +not deactivate Transient mark mode. + +Users can thus conveniently select multiple headings/items and use, +for example, =M-=/=M-= repeatedly without losing the +selection. + +*** Capture templates now support ~(here)~ as a target + +A capture template can target ~(here)~ which is the equivalent of +invoking a capture template with a zero prefix. + +*** =colview= dynamic block supports custom formatting function + +The =colview= dynamic block understands a new ~:formatter~ parameter, +which specifies a user-supplied function to format and insert the data +in the dynamic block. + +A global default formatting function for =colview= dynamic blocks can +be set via the new option ~org-columns-dblock-formatter~ which +defaults to the new function ~org-columns-dblock-write-default~, that +implements the previous (fixed) formatting behavior. Hence, the +default behavior is identical to previous versions. + +The global default function can be overridden for any given =colview= +dynamic block individually by specifying a custom formatter function +using the new ~:formatter~ parameter on the block's =BEGIN= line. + +This new feature replicates the ~:formatter~ option already available +for =clocktable= dynamic blocks. + +*** =colview= dynamic block can link to headlines + +The =colview= dynamic block understands a new ~:link~ parameter, which +when non-~nil~ causes =ITEM= headlines in the table to be linked to +their origins. + +*** =ob-tangle.el=: New flag to remove tangle targets before writing + +When ~org-babel-tangle-remove-file-before-write~ is set to ~t~ the +tangle target is removed before writing. This will allow overwriting +read-only tangle targets. However, when tangle target is a symlink, +this will convert the tangle target into an ordinary file. + +The default value is ~auto~ -- overwrite tangle targets when they are +read-only. + +*** ~org-bibtex-yank~ accepts a prefix argument + +When called with a prefix argument, ~org-bibtex-yank~ adds data to the +headline of the entry at point instead of creating a new one. + +*** =ob-plantuml.el=: Support tikz file format output + +=ob-plantuml.el= now output =tikz= :file format via +=-tlatex:nopreamble= option. So that the output tikz file can be an +input into the exported latex correctly. + +For example, exporting the following to LaTeX + +#+begin_src plantuml :file test.tikz :exports results +Bob -> Alice : Hello World! +#+end_src + +will include the generated =.tikz= into the exported LaTeX source. + +*** =UNNUMBERED= property inheritance is now honored by ~org-num-mode~ + +When ~org-num-skip-unnumbered~ is non-nil, ~org-num-mode~ now honors +~org-use-property-inheritance~ for =UNNUMBERED= property (see manual +section "Property Inheritance"). Previously, only local =UNNUMBERED= +property was taken into account. + +Users can add ="UNNUMBERED"= to ~org-use-property-inheritance~ and set +~org-numb-skip-unnumbered~ to ~t~ to make ~org-num-mode~ skip +numbering of all the sub-headings with non-nil =UNNUMBERED= property. + +*** ~org-insert-todo-heading-respect-content~ now accepts prefix arguments + +The prefix arguments are passed to ~org-insert-todo-heading~. + +*** Make ~ob-sqlite~ use in-memory databases by default + +~sqlite~ source blocks with no ~:db~ header argument now make SQLite +use a temporary in-memory database instead of throwing an error, +matching the behavior of the official ~sqlite3~ shell. As a result, +~sqlite~ source blocks are now usable out of the box, that is with no +header arguments. + +*** ~org-return~ now acts on citations at point + +When ~org-return-follows-link~ is non-nil and cursor is over an +org-cite citation, ~org-return~ will call ~org-open-at-point~. + +*** ~org-tags-view~ supports more property operators + +It supports inequality operators ~!=~ and ~/=~ in addition to the less +common (BASIC? Pascal? SQL?) ~<>~. And it supports starred versions +of all relational operators (~<*~, ~=*~, ~!=*~, etc.) that work like +the regular, unstarred operators but match a headline only if the +tested property is actually present. + +*** =ob-python.el=: Support for more result types and plotting + +=ob-python= now converts the following objects to org-mode tables when +":results table" header arg is set: + +- Dictionaries +- Numpy arrays +- Pandas DataFrames +- Pandas Series + +When the header argument =:results graphics= is set, =ob-python= will +use matplotlib to save graphics. The behavior depends on whether value +or output results are used. For value results, the last line should +return a matplotlib Figure object to plot. For output results, the +current figure (as returned by =pyplot.gcf()=) is cleared before +evaluation, and then plotted afterwards. + +*** =ob-maxima.el=: Support for ~batch~ and ~draw~ + +=ob-maxima= has two new header arguments: ~:batch~ and +~:graphics-pkg~. + +The ~:batch~ header argument can be set to one of Maxima's file +loaders (~batch~, ~load~ or ~batchload~); the default remains +~batchload~. The ~:graphics-pkg~ header argument can be set to one of +Maxima's graphics packages (~draw~ or ~plot~); the default remains +~plot~. The graphics terminal is now determined from the file-ending +of the file-name set in the ~:file~ header argument. + +*** =ob-calc.el=: Support for tables in ~:var~ + +=ob-calc= now supports tables in ~:var~. They are converted to a +matrix or a vector depending on the dimensionality of the table. A +table with a single row is converted to a vector, the rest are +converted to a matrix. + +*** ox-texinfo always generates a ~@direntry~ + +We use defaults based on the file name and title of the document, and +place the entry in the ~Misc~ category if ~TEXINFO_DIR_CATEGORY~ is missing. + +=TEXINFO_DIR_TITLE= is renamed to =TEXINFO_DIR_NAME=. +The old name is obsolete. + +** New and changed options + +# Changes dealing with changing default values of customizations, +# adding new customizations, or changing the interpretation of the +# existing customizations. + +*** Org mode faces are now consistently combined, with markup faces taking precedence over the containing element faces + +Previously, fontification of inline source blocks, macros, footnotes, +target links, timestamps, radio targets, targets, inline export +snippets, verbatim code, and COMMENT keyword in headings replaced the +containing element fontification. Now, this is changed - the inner +markup faces and the containing element faces are combined, with +"inner" faces taking precedence; just as for all other markup. + +*** Org mode now fontifies whole table lines (including newline) according to ~org-table~ face + +Previously, leading indentation and trailing newline in table rows +were not fontified using ~org-table~ face. ~default~ face was used instead. +This made it impossible to scale line height when ~org-table~ face has +smaller height than default (Emacs calculates line height using the tallest face). + +Now, new ~org-table-row~ face is used on the whole table row lines, +including indentation and the final newline. This face, by default, +inherits from ~org-table~ face. + +If the new behavior is not desired, ~org-table-row~ face can be +changed to inherit from ~default~ face. See "Customizing Faces" +section of Emacs manual or "Face Attribute Functions" section of Elisp +manual. + +~org-table~ takes precedence over ~org-table-row~ for the parts of +table rows without indentation and newline. + +*** ~org-auto-align-tags~ is now respected universally + +Previously, only a subset of Org editing commands respected +~org-auto-align-tags~ option. Now, it is no longer the case. All the +editing commands, including typing (~org-self-insert-command~) and +deletion respect the option. + +~org-auto-align-tags~ is still enabled by default. For users who +customized ~org-auto-align-tags~ to nil, ~org-edit-headline~, +~org-priority~, ~org-set-tags~, ~org-entry-put~, ~org-kill-line~, and +typing/deleting in headlines will no longer unconditionally auto-align +the tags. + +*** New export option ~org-export-expand-links~ + +The new option makes Org expand environment variables in link and INCLUDE paths. +The option is on by default. + +Users who do not want variable expansion can set +~org-export-expand-links~ variable to nil or provide +=expand-links:nil= in-file export option. + +*** New hook ~org-after-note-stored-hook~ + +This new hook runs when a note has been stored. + +*** New option controlling how Org mode sorts things ~org-sort-function~ + +Sorting of agenda items, tables, menus, headlines, etc can now be +controlled using a new custom option ~org-sort-function~. + +By default, Org mode sorts things according to the operating system +language. However, language sorting rules may or may not produce good +results depending on the use case. For example, multi-language +documents may be sorted weirdly when sorting rules for system language +are applied on the text written using different language. Also, some +operations systems (e.g. MacOS), do not provide accurate string +sorting rules. + +Org mode provides 3 possible values for ~org-sort-function~: +1. (default) Sort using system language rules. +2. Sort using string comparison (~compare-strings~), making use of UTF + case conversion. This may work better for mixed-language documents + and on MacOS. +3. Custom function, if the above does not fit the needs. + +*** =ob-latex= now uses a new option ~org-babel-latex-process-alist~ to generate png output + +Previously, =ob-latex= used ~org-preview-latex-default-process~ from +~org-preview-latex-process-alist~ to produce png output. Now, the +process settings are separated into a new dedicated option +~org-babel-latex-process-alist~. + +The default value is pulled from =dvipng= process type from +~org-preview-latex-process-alist~, preserving the existing behavior. +However, the output is now immune to changes in +~org-preview-latex-default-process~ and can be customized +independently of the image preview settings. + +*** New option ~org-babel-lua-multiple-values-separator~ + +The string that separates the values of multi-valued results returned +from Lua code blocks. + +*** =.avif= images are now recognized in ~org-html-inline-image-rules~ + +In =ox-html=, =.avif= image links are now inlined by default. + +*** New option ~org-beamer-frame-environment~ + +The new option defines name of an alternative environment to be used +for fragile beamer frames. This option is needed to work around +beamer bug with frame contents containing literal =\end{frame}= string +(for example, inside example blocks). See +https://github.com/josephwright/beamer/issues/360 + +The default value is =orgframe=. + +The option should normally not be changed, except when you need to put +=\end{orgframe}= string inside beamer frames. + +A checker has been added to =M-x org-lint= to detect instances of +~org-beamer-frame-environment~ in Org documents. + +*** New option ~org-export-process-citations~ + +The new option controls whether to use citation processors to process +citations. + +*** New option ~org-org-with-cite-processors~ + +The new option controls whether to use citation processors to process +citations when exporting to Org. + +*** New option ~org-org-with-special-rows~ + +The new options controls whether to export special table rows in +Org-Org (=ox-org=) export. The default value is ~t~. + +*** New option ~org-babel-comint-fallback-regexp-threshold~ + +Org babel is often using Emacs's interactive REPL feature to implement +:session functionality in code blocks. However, Emacs's REPLs use +heuristics to detect which lines in the REPL buffer correspond to +output and which lines are user prompts. + +Normally, Org babel changes the default prompt to something unique. It +avoids incorrect detection of code block output. + +Sometimes, the Org-configured prompt is changed manually by users or +when running a sub-REPL (for example, when running ssh/python +interpreter inside shell). + +The new option controls Org mode's heuristics for catching +user-changed prompt in interactive Org babel sessions. When Org mode +cannot find REPL's prompt for more than +~org-babel-comint-fallback-regexp-threshold~ seconds, imprecise +generic prompt is tried to detect whether the code block output has +arrived. + +Users who often work with altering REPL prompts may consider reducing +the default 5 second value of the new option. + +*** ~repeated-after-deadline~ value of ~org-agenda-skip-scheduled-if-deadline-is-shown~ is moved to a new customization + +A new custom option ~org-agenda-skip-scheduled-repeats-after-deadline~ +is introduced in place of ~repeated-after-deadline~ value of +~org-agenda-skip-scheduled-if-deadline-is-shown~. + +The following example would no longer show in the agenda as scheduled +after January 5th with the new customization set to ~t~. + +: * TODO Do me every day until Jan, 5th (inclusive) +: SCHEDULED: <2024-01-03 Wed +1d> DEADLINE: <2024-01-05 Fri> + +The old customization will continue to work, ensuring backwards compatibility. + +*** New custom setting ~org-icalendar-ttl~ for the ~ox-icalendar~ backend + +The option ~org-icalendar-ttl~ allows to advise a subscriber to the +exported =.ics= file to reload after the given time interval. + +This is useful i.e. if a calendar server subscribes to your exported +file and that file is updated regularly. + +See IETF RFC 5545, Section 3.3.6 Duration and +https://en.wikipedia.org/wiki/ICalendar#Other_component_types for +details. + +Default for ~org-icalendar-ttl~ is ~nil~. In that case the setting +will not be used in the exported ICS file. + +The option may also be set using the =ICAL-TTL= keyword. + +*** The default value of ~org-attach-store-link-p~ is now ~attached~ + +Now, after attaching a file, =[[attach:...]]= link to the attached file +is stored. It can later be inserted using =M-x org-insert-link=. + +*** ~org-link-descriptive~ can now be set per-buffer via =#+STARTUP= options + +In addition to ~org-link-descriptive~ custom option, link display can +now be controlled per-buffer as: + +: #+STARTUP: literallinks +: #+STARTUP: descriptivelinks + +*** New option ~org-fast-tag-selection-maximum-tags~ + +You can now limit the total number of tags displayed in the fast tag +selection interface. Useful in buffers with huge number of tags. + +*** New variable ~org-clock-out-removed-last-clock~ + +The variable is intended to be used by ~org-clock-out-hook~. It is a +flag used to signal when the =CLOCK= line has been removed. This can +happen when ~org-clock-out-remove-zero-time-clocks~ is customized to +be non-nil. + +*** ~org-info-other-documents~ is now a custom option + +Users can now extend the value of ~org-info-other-documents~ to +specify Urls to third-party (non-Emacs) online info nodes when +exporting =info:= links. + +*** ~org-export-smart-quotes-alist~ is now a custom option + +Previously, smart quotes rules for different languages where +hard-coded. Now, they can be customized by users. + +*** Commands affected by ~org-fold-catch-invisible-edits~ can now be customized + +New user option ~org-fold-catch-invisible-edits-commands~ controls +which commands trigger checking for invisible edits. + +The full list of affected commands is: +- ~org-self-insert-command~ +- ~org-delete-backward-char~ +- ~org-delete-char~ +- ~org-meta-return~ +- ~org-return~ (not checked in earlier Org versions) + +*** New customization ~org-image-max-width~ limiting the displayed inline image width + +New custom variable ~org-image-max-width~ limits the maximum inline +image width, but only when the inline image width is not explicitly +set via ~org-image-actual-width~, =ORG-IMAGE-ACTUAL-WIDTH= property, +or =#+ATTR*= keyword. + +By default, when ~org-image-actual-width~ is set to t, +~org-image-max-width~ takes effect. Its default value is set to +~fill-column~, limiting the image previews to ~fill-column~ number of +characters. + +To fall back to previous defaults, where the inline image width is not +constrained, set ~org-image-max-width~ to nil. + +*** ~org-src-block-faces~ now accepts empty string ~""~ as language name + +It is now possible to customize face of source blocks without language specifier. + +: #+begin_src +: Source block with no language +: #+end_src + +For example, to set ~highlight~ face, use + +#+begin_src emacs-lisp +(setq org-src-fontify-natively t) +(add-to-list 'org-src-block-faces '("" highlight)) +#+end_src + +*** New ~org-cite-natbib-export-bibliography~ option defining fallback bibliography style + +~natbib~ citation export processor now uses +~org-cite-natbib-export-bibliography~ (defaults to ~unsrtnat~) as a +fallback bibliography style if none is specified by user in +=#+cite_export:= keyword. + +Previously, export would fail without explicitly selected bibliography +style. + +*** New escape in ~org-beamer-environments-extra~ for labels in Beamer export +The escape =%l= in ~org-beamer-environments-extra~ inserts the label +obtained from ~org-beamer--get-label~. This is added to the default +environments =theorem=, =definition=, =example=, and =exampleblock= in +~org-beamer-environments-default~. + +*** ~org-clock-x11idle-program-name~ now defaults to =xprintidle=, when available + +When =xprintidle= executable is available at =org-clock= load time, it +is used as the default value for ~org-clock-x11idle-program-name~. +The old =x11idle= default is used as the fallback. + +=xprintidle= is available as system package in most Linux +distributions, unlike ancient =x11idle= that is distributed via WORG. + +*** New options for the "csl" citation export processor's LaTeX output + +The ~org-cite-csl-latex-label-separator~ and +~org-cite-csl-latex-label-width-per-char~ options allow the user to +control the indentation of entries for labeled bibliography styles +when the "csl" citation processor is used for LaTeX export. The +indentation length is computed as the sum of +~org-cite-csl-latex-label-separator~ and the maximal label width, for +example: + +#+begin_example + indentation length +<-------------------------> +max. label width separator +<---------------><--------> +[Doe22] John Doe. A title... +[DoeSmithJones19] John Doe, Jane Smith and... +[SmithDoe02] Jane Smith and John Doe... +#+end_example + +The maximal label width, in turn, is calculated as the product of +~org-cite-csl-latex-label-width-per-char~ and the maximal label length +measured in characters. + +The ~org-cite-csl-latex-preamble~ option makes it possible to +customize the entire LaTeX fragment that the "csl" citation processor +injects into the preamble. + +*** New ~org-latex-listings-src-omit-language~ option for LaTeX export + +The ~org-latex-listings-src-omit-language~ option allows omitting the +=language= parameter in the exported =lstlisting= environment. This +is necessary when the =listings= backend delegates listing generation +to another package like =fancyvrb= using the following setup in the +document header: + +#+BEGIN_src org +,#+LATEX_HEADER: \RequirePackage{fancyvrb} +,#+LATEX_HEADER: \DefineVerbatimEnvironment{verbatim}{Verbatim}{...whatever...} +,#+LATEX_HEADER: \DefineVerbatimEnvironment{lstlisting}{Verbatim}{...whatever...} +#+END_src + +*** New face: ~org-agenda-calendar-daterange~ +The face ~org-agenda-calendar-daterange~ is used to show entries with +a date range in the agenda. It inherits from the default face in +order to remain backward-compatible. + +*** New ~org-babel-clojurescript-backend~ option to choose ClojureScript backend + +Before, a ClojureScript source block used the same backend as Clojure, +configured in ~org-babel-clojure-backend~ and relied on an undocumented +~:target~ parameter. + +Now, there's ~org-babel-clojurescript-backend~ to determine the +backend used for evaluation of ClojureScript. + +*** Support for Clojure CLI in ~ob-clojure~ + +~ob-clojure~ now supports executing babel source blocks with the +official [[https://clojure.org/guides/deps_and_cli][Clojure CLI tools]]. +The command can be customized with ~ob-clojure-cli-command~. + +*** New customization options for ~org-export-dispatch~ + +New custom variables ~org-export-body-only~, +~org-export-visible-only~, and ~org-export-force-publishing~ allow the +default settings of "Body only", "Visible only", and "Force +publishing" in the ~org-export-dispatch~ UI to be customized, +respectively. + +*** New option ~org-icalendar-todo-unscheduled-start~ to control unscheduled TODOs in ox-icalendar + +~org-icalendar-todo-unscheduled-start~ controls how ox-icalendar +exports the starting datetime for unscheduled TODOs. Note this option +only has an effect when ~org-icalendar-include-todo~ is non-nil. + +By default, ox-icalendar will not export a start datetime for +unscheduled TODOs, except in cases where the iCalendar spec demands a +start (specifically, for recurring deadlines, in which case +~org-deadline-warning-days~ is used). + +Currently implemented options are: + +- ~recurring-deadline-warning~: The default as described above. +- ~deadline-warning~: Use ~org-deadline-warning-days~ to set the start + time if the unscheduled task has a deadline (recurring or not). +- ~current-datetime~: Revert to old behavior, using the current + datetime as the start of unscheduled tasks. +- ~nil~: Never add a start time for unscheduled tasks. For repeating + tasks this technically violates the iCalendar spec, but some + iCalendar programs support this usage. + +*** Capture template expansion now supports ID links + +The capture template expansion element =%K= creates links using +~org-store-link~, which respects the values of ~org-id-link-to-use-id~. + +*** Changes to ~org-babel-python-command~, and new session/nonsession specific options + +The default Python command used by interactive sessions has been +changed to match ~python-shell-interpreter~ and +~python-shell-interpreter-args~ by default. The default Python +command for nonsessions has not changed. + +New options ~org-babel-python-command-nonsession~ and +~org-babel-python-command-session~ control the default Python command +for nonsessions and sessions, respectively. By default, +~org-babel-python-command-session~ is ~auto~, which means to use the +configuration for ~python-shell-interpreter(-args)~ as default. + +The old option ~org-babel-python-command~ has been changed to have +default value of ~auto~. When not ~auto~, it overrides both +~org-babel-python-command-nonsession~ and +~org-babel-python-command-session~. Therefore, users who had +previously set ~org-babel-python-command~ will not experience any +changes. + +Likewise, users who had neither set ~org-babel-python-command~ nor +~python-shell-interpreter(-args)~ will not see any changes -- ~python~ +remains the default command. + +The main change will be for users who did not configure +~org-babel-python-command~, but did configure +~python-shell-interpreter~, e.g. to use IPython. In this case, +~ob-python~ will now start interactive sessions in a more consistent +manner with ~run-python~. + +*** New hook option ~org-indent-post-buffer-init-functions~ + +This allows to run functions after ~org-indent~ initializes a buffer to +enrich its properties. +*** New option ~org-agenda-start-with-archives-mode~ + +This option starts the agenda to automatically include archives, +propagating the value for this variable to ~org-agenda-archives-mode~. +For acceptable values and their meaning, see the value of that variable. + +*** New option ~org-id-link-consider-parent-id~ to allow =id:= links to parent headlines + +For =id:= links, when this option is enabled, ~org-store-link~ will +look for ids from parent/ancestor headlines, if the current headline +does not have an id. + +Combined with the new ability for =id:= links to use search options + [fn:: when =org-id-link-use-context= is =t=, which is the default], +this allows linking to specific headlines without requiring every +headline to have an id property, as long as the headline is unique +within a subtree that does have an id property. + +For example, given this org file: + +#+begin_src org +,* Parent +:PROPERTIES: +:ID: abc +:END: +,** Child 1 +,** Child 2 +#+end_src + +Storing a link with point at "Child 1" will produce a link +==, which precisely links to the "Child 1" headline +even though it does not have its own ID. By giving files top-level id +properties, links to headlines in the file can also be made more +robust by using the file id instead of the file path. + +*** New option ~latex-default-footnote-command~ to customize the LaTeX footnote command + +This new option allows you to define the LaTeX command the Org mode +footnotes are converted to (for example ~\sidenote{%s%s}~ instead of +the default ~\footnote{%s%s}~). + +The option can be customized either by + +1. setting the global variable in the ~org-export-latex~ customization + group or +2. by setting the file local keyword =LATEX_FOOTNOTE_COMMAND= + +*** Options for ~#+cite_export: biblatex~ can use the package's option syntax + +When using =biblatex= to export bibliographies, you can use the format +as specified in the =biblatex= package documentation as +=key=val,key=val,...= + +*** New option ~org-columns-dblock-formatter~ + +=colview= dynamic blocks now understand a new ~:formatter~ parameter +to use a specific function for formatting and inserting the contents +of the dynamic block. This new option can be used to set the global +default formatting function that will be used for =colview= dynamic +blocks that do not specify any ~:formatter~ parameter. Its default +value (the new function ~org-columns-dblock-write-default~) yields the +previous (fixed) formatting behavior. + +*** New allowed value of ~org-md-headline-style~ to mix ATX and Setext style headlines + +Setting ~org-md-headline-style~ to ~'mixed~ will export headline +levels one and two as Setext style headlines, and headline levels +three through six will be exported as ATX style headlines. + +*** ~org-footnote-new~ can be configured to create anonymous footnotes + +When ~org-footnote-auto-label~ is set to ~'anonymous~, create +anonymous footnotes automatically with ~org-footnote-new~. + +The same can be done via startup options: +: #+STARTUP: fnanon + +*** New final hooks for Modifier-Cursor keys + +Final hooks are added to the following commands: +- ~org-metaleft-final-hook~ to ~org-metaleft~ (bound to =M-=). +- ~org-metaright-final-hook~ to ~org-metaright~ (bound to + =M-=). +- ~org-metaup-final-hook~ to ~org-metaup~ (bound to =M-=). +- ~org-metadown-final-hook~ to ~org-metadown~ (bound to =M-=). +- ~org-shiftmetaleft-final-hook~ to ~org-shiftmetaleft~ (bound to + =M-S-=). +- ~org-shiftmetaright-final-hook~ to ~org-shiftmetaright~ (bound to + =M-S-=). +- ~org-shiftmetaup-final-hook~ to ~org-shiftmetaup~ (bound to + =M-S-=). +- ~org-shiftmetadown-final-hook~ to ~org-shiftmetadown~ (bound to + =M-S-=). + +** Major changes and additions to Org element API and Org syntax +*** Diary type timestamps now support optional time/timerange + +Previously, diary type timestamps could not specify time. +Now, it is allowed to add a time or time range: + +: <%%(diary-float t 4 2) 22:00-23:00> +: <%%(diary-float t 4 2) 10:30> + +The parsed representation of such timestamps will have ~:hour-start~, +~:minute-start~, ~:hour-end~, ~:minute-end~, and ~:range-type~ +properties set appropriately. In addition, a new ~:diary-sexp~ +property will store the diary sexp value. + +For example, + +: <%%(diary-float t 4 2) 22:00-23:00> + +will have the following properties + +#+begin_src emacs-lisp +:type: diary +:range-type: timerange +:raw-value: "<%%(diary-float t 4 2) 22:00-23:00>" +:year-start: nil +:month-start: nil +:day-start: nil +:hour-start: 22 +:minute-start: 0 +:year-end: nil +:month-end: nil +:day-end: nil +:hour-end: 23 +:minute-end: 0 +:diary-sexp: "(diary-float t 4 2)" +#+end_src + +*** Underline syntax now takes priority over subscript when both are applicable + +Previously, Org mode interpreted =(_text_)= as subscript. +Now, the interpretation is changed to underline. + +=(_text_)= matches both subscript and underline markup. The +interpretation is changed to keep consistency with other emphasis like +=(*bold*)=. + +Most of the users should not be affected by this change - it only applies when character immediately preceding =_= is one of =-=, =(=, ='=, and ={=. + +*** New term: "syntax node" + +To reduce confusion with "element" referring to both "syntax element" +and "element/object" class, we now prefer using "syntax node" when +referring to generic Org syntax elements. "Elements" and "objects" +now refer to different syntax node classes of paragraph-like nodes and +markup-like nodes. + +*** New element type ~anonymous~ + +Secondary strings can now be recognized as ~anonymous~ type to +distinguish from non-elements. With a new optional argument, +~org-element-type~ will return ~anonymous~ for secondary strings +instead of nil. + +The new element type can be used in ~org-element-lineage~, +~org-element-map~, and other functions that filter by element type. + +*** Internal structure of Org parse tree has been changed + +The code relying upon the previously used =(TYPE PROPERTIES-PLIST CONTENTS-LIST)= +structure may no longer work. Please use ~org-element-create~, +~org-element-property~, and other Org element API functions to work +with Org syntax trees. + +Some syntax node properties are no longer stored as property list elements. +Instead, they are kept in a special vector value of a new +=:standard-properties= property. This is done to improve performance. + +If there is a need to traverse all the node properties, a new API +function ~org-element-properties-map~ can be used. + +Properties and their values can now be deferred to avoid overheads +when parsing. They are calculated lazily, when the value/property is +requested by ~org-element-property~ and other getter functions. Using +~plist-get~ to retrieve values of =PROPERTIES-PLIST= is not +recommended as deferred properties will not be resolved in such +scenario. + +New special property =:secondary= is used internally to record which +properties store secondary objects. + +New special property =:deferred= is used to keep information how to +calculate property names lazily. + +See the commentary in =lisp/org-element-ast.el= for more details. + +*** Multiple affiliated keyword values are now stored in the order they appear in buffer + +Previously, + +: #+caption: foo +: #+caption: bar +: Paragraph + +would have its =:caption= property set to ~(("bar") ("foo"))~ in reverse order. + +Now, the order is not reversed: ~(("foo") ("bar"))~. + +*** Some property values may now be calculated lazily and require original Org buffer to be live + +~org-element-at-point~, ~org-element-context~, and +~org-element-at-point-no-context~ may now not calculate all the +property values at the call time. Instead, the calculation will be +deferred until ~org-element-property~ or the equivalent getter +function is called. The property names may not all be calculated as +well. + +It may often be necessary to have the original Org buffer open when +resolving the deferred values. + +One can ensure that all the deferred values are resolved using new +function ~org-element-resolve-deferred~ and new optional argument for +~org-element-property~. + +~org-element-parse-buffer~ and ~org-element-parse-secondary-string~ +will resolve all the deferred values by default. No adjustment is +needed for their users. + +*** New API functions and macros +**** New property accessors and setters + +New functions to retrieve and set (via ~setf~) commonly used element properties: +- =:begin= :: ~org-element-begin~ +- =:end= :: ~org-element-end~ +- =:contents-begin= :: ~org-element-contents-begin~ +- =:contents-end= :: ~org-element-contents-end~ +- =:post-affiliated= :: ~org-element-post-affiliated~ +- =:post-blank= :: ~org-element-post-blank~ +- =:parent= :: ~org-element-parent~ + +**** New macro ~org-element-with-enabled-cache~ + +The macro arranges the element cache to be active during =BODY= execution. +When cache is enabled, the macro is identical to ~progn~. When cache +is disabled, the macro arranges a new fresh cache that is discarded +upon completion of =BODY=. + +**** New function ~org-element-property-raw~ + +This function is like ~org-element-property~ but does not try to +resolve deferred properties. + +~org-element-property-raw~ can be used with ~setf~. + +**** New function ~org-element-put-property-2~ + +Like ~org-element-put-property~, but the argument list is changed to have +=NODE= as the last argument. Useful with threading macros like +~thread-last~. + +**** New function ~org-element-properties-resolve~ + +This function resolves all the deferred values in a =NODE=, modifying +the =NODE= for side effect. + +**** New functions ~org-element-properties-map~ and ~org-element-properties-mapc~ + +New functions to map over =NODE= properties. + +**** New function ~org-element-ast-map~ + +This is a more general equivalent of ~org-element-map~. It allows +more precise control over recursion into secondary strings. + +**** New function ~org-element-lineage-map~ + +Traverse syntax tree ancestor list, applying arbitrary function to +each ancestor. + +**** New function ~org-element-property-inherited~ + +Like ~org-element-property~, but can be used to retrieve and combine +multiple different properties for a given =NODE= and its parents. + +*** ~org-element-cache-map~ can now be used even when element cache is disabled + +*** =org-element= API functions and macros can now accept syntax nodes as =POM= argument + +The following functions are updated: +- ~org-agenda-entry-get-agenda-timestamp~ +- ~org-element-at-point~ +- ~org-is-habit-p~ +- ~org-id-get~ +- ~org-with-point-at~ +- ~org-entry-properties~ +- ~org-entry-get~ +- ~org-entry-delete~ +- ~org-entry-add-to-multivalued-property~ +- ~org-entry-remove-from-multivalued-property~ +- ~org-entry-member-in-multivalued-property~ +- ~org-entry-put-multivalued-property~ +- ~org-entry-get-with-inheritance~ +- ~org-entry-put~ +- ~org-read-property-value~ +- ~org-property-get-allowed-values~ + +*** ~org-element-map~ now traverses main value in dual keywords before the secondary value + +The traverse order for dual keywords is reversed. The main value is +now traversed first, followed by the secondary value. + +*** Org parse tree is now non-printable + +Org parser now assigns a new property =:buffer= that holds +non-printable buffer object. This makes syntax tree non-printable. +Using ~print~/~read~ is no longer safe. + +*** Some Org API functions no longer preserve match data + +~org-element-at-point~, ~org-element-context~, ~org-get-category~, and +~org-get-tags~ may modify the match data. + +The relevant function docstrings now explicitly mention that match +data may be modified. + +*** ~org-element-create~ now treats a single ~anonymous~ =CHILDREN= argument as a list of child nodes + +When =CHILDREN= is a single anonymous node, use its contents as children +nodes. This way, + +: (org-element-create 'section nil (org-element-contents node)) + +will yield expected results with contents of another node adopted into +a newly created one. + +Previously, one had to use + +: (apply #'org-element-create 'section nil (org-element-contents node)) +*** New property ~:range-type~ for org-element timestamp object + +~org-element-timestamp-parser~ now adds =:range-type= property to each +timestamp object. Possible values: ~timerange~, ~daterange~, ~nil~. + +~org-element-timestamp-interpreter~ takes into account this property +and returns an appropriate timestamp string. + +*** New properties =:repeater-deadline-value= and =:repeater-deadline-unit= for org-element timestamp object + +~org-element-timestamp-parser~ now adds =:repeater-deadline-value= and +=:repeater-deadline-unit= properties to each timestamp object that has +a repeater deadline. For example, in =<2012-03-29 Thu ++1y/2y>=, =2y= +is the repeater deadline with a value of =2= and unit of =y=. See +"5.3.3 Tracking your habits" section in the manual. + +Possible values for =:repeater-deadline-value=: ~positive integer~, ~nil~. + +Possible values for =:repeater-deadline-unit=: ~hour~, ~day~, ~week~, +~month~, ~year~. + +~org-element-timestamp-interpreter~ takes into account these properties +and returns an appropriate timestamp string. + +*** =org-link= store functions are passed an ~interactive?~ argument + +The ~:store:~ functions set for link types using +~org-link-set-parameters~ are now passed an ~interactive?~ argument, +indicating whether ~org-store-link~ was called interactively. + +Existing store functions will continue to work. + +** New functions and changes in function arguments + +# This also includes changes in function behavior from Elisp perspective. + +*** ~org-babel-lilypond-compile-lilyfile~ ignores optional second argument + +The =TEST= parameter is better served by Emacs debugging tools. + +*** ~org-print-speed-command~ is now an internal function + +The old name is marked obsolete and the new name is +~org--print-speed-command~. + +This function was always aimed for internal use when building speed +command help buffer. Now, it is stated explicitly. + +*** When ~org-link-file-path-type~ is a function, its argument is now a filename as it is read by ~org-insert-link~; not an absolute path + +Previously, when ~org-link-file-path-type~ is set to a function, the +function argument was the filename from the link expanded via +~expand-file-name~. Now, a bare filename is passed to the function. + +*** ~org-create-file-search-functions~ can use ~org-list-store-props~ to suggest link description + +In Org <9.0, ~org-create-file-search-functions~ could set ~description~ +variable to suggest link description for the stored link. However, +this feature stopped working since Org 9.0 switched to lexical binding. + +Now, it is again possible for ~org-create-file-search-functions~ to +supply link descriptions using ~(org-list-store-props :description +"suggested description")~ in the search function body. + +*** New API functions to store data within ~org-element-cache~ + +Elisp programs can now store data inside Org element cache. + +The data will remain stored as long as the Org buffer text associated +with the cached elements remains unchanged. + +Two options are available: + - Store the data until any text within element boundaries is changed + - Store the data, but ignore any changes inside element contents that + do not affect the high-level element structure. For example, + changes inside subheadings can be ignored for the data stored + inside parent heading element. + +The new functions are: ~org-element-cache-store-key~ and +~org-element-cache-get-key~. + +*** New optional argument =UPDATE-HEADING= for ~org-bibtex-yank~ + +When the new argument is non-nil, add data to the headline of the +entry at point. + +*** ~org-fold-hide-drawer-all~ is now interactive + +~org-fold-hide-drawer-all~ is now a command, accepting two optional +arguments - region to act on. + +*** =TYPES= argument in ~org-element-lineage~ can now be a symbol + +When =TYPES= is symbol, only check syntax nodes of that type. + +*** New optional argument =KEEP-CONTENTS= for ~org-element-copy~ + +With the new argument, the contents is copied recursively. + +*** ~org-element-property~ can now be used with ~setf~ + +*** New optional arguments for ~org-element-property~ + +The value of the new optional argument =DFLT= is returned if the +property with given name is not present. Same as =DEFAULT= argument +for ~alist-get~. + +New optional argument =FORCE-UNDEFER= modifies the =NODE=, storing the +resolved deferred values. + +See the top comment in =lisp/org-element-ast.el= for more details +about the deferred values. + +*** New optional argument =NO-UNDEFER= in ~org-element-map~ and changed argument conventions + +New optional argument =NO-UNDEFER=, when non-nil, will make +~org-element-map~ keep deferred secondary string values in their raw +form. See the top comment in =lisp/org-element-ast.el= for more +details about the deferred values. + +=TYPES= argument can now be set to ~t~. This will match all the +syntax nodes when traversing the tree. + +~FUN~ can now be a lisp form that will be evaluated with symbol ~node~ +assigned to the current syntax node. + +~FUN~ can now throw ~:org-element-skip~ signal to skip recursing into +current element children and secondary strings. + +*** New optional argument =KEEP-DEFERRED= in ~org-element-parse-buffer~ + +When non-nil, the deferred values and properties will not be resolved. +See the top comment in =lisp/org-element-ast.el= for more details +about the deferred values. + +*** New optional argument =ANONYMOUS= for ~org-element-type~ + +When the new argument is non-nil, return symbol ~anonymous~ for anonymous elements. +Previously, ~nil~ would be returned. + +*** ~org-element-adopt-elements~ is renamed to ~org-element-adopt~ + +The old name is kept as an alias. The new name creates less confusion +as the function can also act on objects. + +*** ~org-element-extract-element~ is renamed to ~org-element-extract~ + +The old name is kept as an alias. The new name creates less confusion +as the function can also act on objects. + +*** ~org-element-set-element~ is renamed to ~org-element-set~ + +The old name is kept as an alias. The new name creates less confusion +as the function can also act on objects. + +*** ~org-export-get-parent~ is renamed to ~org-element-parent~ and moved to =lisp/org-element.el= + +*** ~org-export-get-parent-element~ is renamed to ~org-element-parent-element~ and moved to =lisp/org-element.el= + +*** ~org-insert-heading~ optional argument =TOP= is now =LEVEL= + +A numeric value forces a heading at that level to be inserted. For +backwards compatibility, non-numeric non-nil values insert level 1 +headings as before. + +*** New optional argument for ~org-id-get~ + +New optional argument =INHERIT= means inherited ID properties from +parent entries are considered when getting an entry's ID (see +~org-id-link-consider-parent-id~ option). + +*** New optional argument for ~org-link-search~ + +If a missing heading is created to match the search string, the new +optional argument =NEW-HEADING-CONTAINER= specifies where in the +buffer it will be added. If not specified, new headings are created +at level 1 at the end of the accessible part of the buffer, as before. + +** Miscellaneous +*** Add completion for links to man pages + +Completion is enabled for links to man pages added using ~org-insert-link~: +=C-c C-l man RET emacscl TAB= to get =emacsclient=. Of course, the ~ol-man~ +library should be loaded first. + +*** Datetree structure headlines can now be complex + +TODO state, priority, tags, statistics cookies, and COMMENT keywords +are allowed in the tree structure. + +*** Org links now support ~thing-at-point~ + +You can now retrieve the destination of a link by calling +~(thing-at-point 'url)~. Requires Emacs 28 or newer. + +In Emacs 30 or newer, ~forward-thing~ and ~bounds-of-thing-at-point~ +is also supported for links. + +*** Add support for ~logind~ idle time in ~org-user-idle-seconds~ + +When Emacs is built with =dbus= support and +the =org.freedesktop.login1= interface is available, fallback to +checking the =IdleSinceHint= property when +determining =org-user-idle-seconds= as the penultimate step. + +*** =colview= dynamic block now writes column width specifications + +When column format contains width specifications, =colview= dynamic +block now writes these specifications as column width in the generated +tables and automatically shrinks the columns on display. + +Example: + +: * PROYECTO EMACS +: :PROPERTIES: +: :COLUMNS: %10ITEM(PROJECT) +: :END: +: +: Before +: +: #+BEGIN: columnview :id local +: | PROJECT | +: |----------------| +: | PROYECTO EMACS | +: #+END: +: +: After +: +: #+BEGIN: columnview :id local +: | <10> | +: | PROJECT | +: |----------------| +: | PROYECTO EMACS | +: #+END: + +*** =ob-lua=: Support all types and multiple values in results + +Lua code blocks can now return values of any type and can also return +multiple values. Previously, values of certain types were incorrectly +converted to the empty string =""=, which broke HTML export for inline +code blocks, and multiple values were incorrectly concatenated, where +~return 1, 2, 3~ was evaluated as =123=. + +Multiple values are comma-separated by default, so that they work well +with inline code blocks. To change the string used as the separator, +customize ~org-babel-lua-multiple-values-separator~. + +*** ~org-store-link~ now moves an already stored link to front of the ~org-stored-links~ + +Previously, when the link to be stored were stored already, +~org-store-link~ displayed a message and did nothing. + +Now, ~org-store-link~ moves the stored link to front of the list of +stored links. This way, the link will show up first in the completion +and when inserting all the stored links with ~org-insert-all-links~. + +*** ob-python now sets ~python-shell-buffer-name~ in Org edit buffers + +When editing a Python src block, the editing buffer is now associated +with the Python shell specified by the src block's ~:session~ header, +which means users can now send code directly from the edit buffer, +e.g., using ~C-c C-c~, to the session specified in the Org buffer. + +*** ~org-edit-special~ no longer force-starts session in R and Julia source blocks + +Previously, when R/Julia source block had =:session= header argument +set to a session name with "earmuffs" (like =*session-name*=), +~org-edit-special~ always started a session, if it does not exist. + +Now, ~org-edit-special~ arranges that a new session with correct name +is initiated only when user explicitly executes R/Julia-mode commands +that trigger session interactions (requires ESS 24.01.0 or newer). +The same session will remain available in the context of Org babel. + +*** ~org-store-link~ behavior storing additional =CUSTOM_ID= links has changed + +Previously, when storing =id:= link, ~org-store-link~ stored an +additional "human readable" link using a node's =CUSTOM_ID= property. + +This behavior has been expanded to store an additional =CUSTOM_ID= +link when storing any type of external link type in an Org file, not +just =id:= links. + +*** =org-habit.el= now optionally inherits ~:STYLE: habit~ properties + +Currently, the ~STYLE~ property of habits is not inherited when searching +for entries. + +This change allows the property to be inherited optionally by customizing +the ~org-use-property-inheritance~ variable. + +This change aims to provide more flexibility in managing habits, allowing +users to dedicate separate subtrees or files to habits without manually +setting the ~STYLE~ property for each sub-task. + +The change is breaking when ~org-use-property-inheritance~ is set to ~t~. + +*** =ox-org= preserves header arguments in src blocks + +Previously, all the header arguments where stripped from src blocks +during export. Now, header arguments are preserved. + +*** =ox-org= now exports special table rows by default + +Previously, when exporting to Org, special table rows (for example, +width cookies) were not exported. Now, they are exported by default. + +You can customize new option ~org-org-with-special-rows~ to fall back to previous behavior. + +*** ~org-agenda-search-headline-for-time~ now ignores all the timestamp in headings + +Previously, ~org-agenda-search-headline-for-time~ made Org agenda +match anything resembling time inside headings. Even when the time +was a part of a timestamp. + +Now, all the timestamps in headings are ignored when searching the time. + +*** =org-crypt.el= now applies initial visibility settings to decrypted entries + +Previously, all the text was unfolded unconditionally, including property drawers. + +*** Blank lines after removed objects are now retained during export + +When certain objects in Org document are to be excluded from export, +spaces after these objects were previously removed as well. + +For example, if ~org-export-with-footnotes~ is set to nil, the footnote in + +: Pellentesque dapibus suscipit ligula.[fn:1] Donec posuere augue in quam. + +would be removed, leading to the following exported ASCII document + +: Pellentesque dapibus suscipit ligula.Donec posuere augue in quam. + +This is because spaces after footnote (and other markup) are +considered a part of the preceding AST object in Org. + +Now, unless there is a whitespace before an object to be removed, +spaces are preserved during export: + +: Pellentesque dapibus suscipit ligula. Donec posuere augue in quam. + +*** Remove undocumented ~:target~ header parameter in ~ob-clojure~ + +The ~:target~ header was only used internally to distinguish +from Clojure and ClojureScript. +This is now handled with an optional function parameter in +the respective functions that need this information. + +*** New org-entity alias: =\P= for =\para= + +For symmetry with =\S= and =\sect= for the section symbol, =\P= has +been added as an another form for the pilcrow symbol currently +available as =\para=. + +*** ~org-table-to-lisp~ no longer clobbers the regexp global state + +It does no longer use regexps. + +It is also faster. Large tables can be read quickly. + * Version 9.6 ** Important announcements and breaking changes @@ -74,6 +1755,9 @@ to the Org behavior. The new features and changes are listed below. **** Hidden parts of the links can now be searched and revealed during isearch +[2024-06-09 Sun] Since Org 9.7, this is no longer working. See +changes for Org 9.7. + In the past, hidden parts of the links could not be searched using isearch (=C-s=). Now, they are searchable by default. The hidden match is also revealed temporarily during isearch. @@ -220,7 +1904,13 @@ After: : ("simple" "list") #+end_src + ** New features +*** Column view: new commands to move rows up & down +You can move rows up & down in column view with +~org-columns-move-row-up~ and ~org-columns-move-row-down~. +Keybindings are the same as ~org-move-subtree-up~ and ~org-move-subtree-down~ +=M-= and =M-=. *** Clock table can now produce quarterly reports =:step= clock table parameter can now be set to =quarter=. @@ -320,7 +2010,7 @@ When ~org-latex-src-block-backend~ is set to ~engraved~, =engrave-faces-latex= from [[http://elpa.gnu.org/packages/engrave-faces.html][engrave-faces]] is used to transcode source blocks to LaTeX. This requires the =fvextra=, =float=, and (by default, but not necessarily) =tcolorbox= LaTeX packages be -installed. It uses Emacs' font-lock information, and so tends to +installed. It uses Emacs's font-lock information, and so tends to produce results superior to Minted or Listings. *** Support for =#+include=-ing URLs @@ -432,6 +2122,13 @@ following properties: ~:hook~, ~:prepare-finalize~, prior to their global counterparts for the selected template. ** New options +*** New option ~org-columns-checkbox-allowed-values~ + +This would allow to use more than two states ("[ ]", "[X]") in +columns with SUMMARY-TYPE that use checkbox ("X", "X/", "X%"). +For example you can add an intermediate state ("[-]"). +Or empty state ("") to remove checkbox. + *** A new option for custom setting ~org-refile-use-outline-path~ to show document title in refile targets Setting ~org-refile-use-outline-path~ to ~'title~ will show title @@ -731,8 +2428,8 @@ following snippet to allow multiple different ID formats in Org files. ;; `org-attach-id-uuid-folder-format'. (lambda (id) (and (or (org-uuidgen-p id) - (string-match-p "[0-9a-z]\\{12\\}" id)) - (org-attach-id-uuid-folder-format id))) + (string-match-p "[0-9a-z]\\{12\\}" id)) + (org-attach-id-uuid-folder-format id))) ;; When ID looks like a timestamp-based ID. Group by year-month ;; folders. (lambda (id) @@ -746,7 +2443,6 @@ following snippet to allow multiple different ID formats in Org files. org-attach-id-uuid-folder-format org-attach-id-ts-folder-format)) #+end_src - * Version 9.5 ** Important announcements and breaking changes @@ -1098,7 +2794,7 @@ 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 user to specify the preamble and code that precedes and proceeds the contents of the source block. *** New option ~org-html-meta-tags~ allows for HTML meta tags customization @@ -1346,7 +3042,7 @@ Go through the buffer and ask for the replacement." (goto-char (match-beginning 0)) (looking-at-p org-link-bracket-re)) (y-or-n-p "Fix link (remove TODO keyword)? ")) - (replace-match "[[*"))))) + (replace-match "[[*"))))) (visible-mode -1)) #+end_src @@ -2038,12 +3734,12 @@ removed. "Change properties for Org-Attach." (interactive) (org-with-point-at 1 - (while (outline-next-heading) - (let ((DIR (org--property-local-values "ATTACH_DIR" nil))) - (when DIR - (org-set-property "DIR" (car DIR)) - (org-delete-property "ATTACH_DIR")))) - (org-delete-property-globally "ATTACH_DIR_INHERIT"))) + (while (outline-next-heading) + (let ((DIR (org--property-local-values "ATTACH_DIR" nil))) + (when DIR + (org-set-property "DIR" (car DIR)) + (org-delete-property "ATTACH_DIR")))) + (org-delete-property-globally "ATTACH_DIR_INHERIT"))) #+end_src For those who hate breaking changes, even though the changes are made @@ -2568,14 +4264,14 @@ conditional on another entry. E.g. given this configuration: (defun custom/org-collect-confirmed (property) "Return `PROPERTY' for `CONFIRMED' entries" (let ((prop (org-entry-get nil property)) - (confirmed (org-entry-get nil "CONFIRMED"))) + (confirmed (org-entry-get nil "CONFIRMED"))) (if (and prop (string= "[X]" confirmed)) - prop - "0"))) + prop + "0"))) (setq org-columns-summary-types - '(("X+" org-columns--summary-sum - custom/org-collect-confirmed))) + '(("X+" org-columns--summary-sum + custom/org-collect-confirmed))) #+END_SRC You can have a file =bananas.org= containing: @@ -2810,11 +4506,11 @@ to the following #+BEGIN_SRC elisp (lambda (entry style project) (cond ((not (directory-name-p entry)) - (format "[[file:%s][%s]]" - (file-name-sans-extension entry) - (org-publish-find-title entry project))) - ((eq style 'tree) (file-name-nondirectory (directory-file-name entry))) - (t entry))) + (format "[[file:%s][%s]]" + (file-name-sans-extension entry) + (org-publish-find-title entry project))) + ((eq style 'tree) (file-name-nondirectory (directory-file-name entry))) + (t entry))) #+END_SRC *** Change signature for ~:sitemap-function~ @@ -6505,7 +8201,7 @@ that Calc formulas can operate on them. **** org-ctags.el (Paul Sexton) - Targets like =<>= can now be found by Emacs' etag + Targets like =<>= can now be found by Emacs's etag functionality, and Org-mode links can be used to link to etags, also in non-Org-mode files. For details, see the file /org-ctags.el/. diff --git a/elpa/org-9.6.7/etc/csl/README b/elpa/org-9.7.17/etc/csl/README similarity index 100% rename from elpa/org-9.6.7/etc/csl/README rename to elpa/org-9.7.17/etc/csl/README diff --git a/elpa/org-9.6.7/etc/csl/chicago-author-date.csl b/elpa/org-9.7.17/etc/csl/chicago-author-date.csl similarity index 100% rename from elpa/org-9.6.7/etc/csl/chicago-author-date.csl rename to elpa/org-9.7.17/etc/csl/chicago-author-date.csl diff --git a/elpa/org-9.6.7/etc/csl/locales-en-US.xml b/elpa/org-9.7.17/etc/csl/locales-en-US.xml similarity index 100% rename from elpa/org-9.6.7/etc/csl/locales-en-US.xml rename to elpa/org-9.7.17/etc/csl/locales-en-US.xml diff --git a/elpa/org-9.6.7/etc/styles/OrgOdtContentTemplate.xml b/elpa/org-9.7.17/etc/styles/OrgOdtContentTemplate.xml similarity index 100% rename from elpa/org-9.6.7/etc/styles/OrgOdtContentTemplate.xml rename to elpa/org-9.7.17/etc/styles/OrgOdtContentTemplate.xml diff --git a/elpa/org-9.6.7/etc/styles/OrgOdtStyles.xml b/elpa/org-9.7.17/etc/styles/OrgOdtStyles.xml similarity index 100% rename from elpa/org-9.6.7/etc/styles/OrgOdtStyles.xml rename to elpa/org-9.7.17/etc/styles/OrgOdtStyles.xml diff --git a/elpa/org-9.6.7/etc/styles/README b/elpa/org-9.7.17/etc/styles/README similarity index 95% rename from elpa/org-9.6.7/etc/styles/README rename to elpa/org-9.7.17/etc/styles/README index 3737c8df..7944bcb2 100644 --- a/elpa/org-9.6.7/etc/styles/README +++ b/elpa/org-9.7.17/etc/styles/README @@ -1,7 +1,7 @@ The files OrgOdtContentTemplate.xml and OrgOdtStyles.xml have the following copyright information: -Copyright (C) 2010-2023 Free Software Foundation, Inc. +Copyright (C) 2010-2024 Free Software Foundation, Inc. These files are part of GNU Emacs. diff --git a/elpa/org-9.6.7/local.mk b/elpa/org-9.7.17/local.mk similarity index 98% rename from elpa/org-9.6.7/local.mk rename to elpa/org-9.7.17/local.mk index 19b86205..d22c515c 100644 --- a/elpa/org-9.6.7/local.mk +++ b/elpa/org-9.7.17/local.mk @@ -57,7 +57,7 @@ BTEST_POST = # -L /ert # needed for Emacs23, Emacs24 has ert built in # -L /ess # needed for running R tests # -L /htmlize # need at least version 1.34 for source code formatting -BTEST_OB_LANGUAGES = awk C fortran maxima lilypond octave perl python java +BTEST_OB_LANGUAGES = awk C fortran maxima lilypond octave perl python java sqlite eshell calc # R # requires ESS to be installed and configured # ruby # requires inf-ruby to be installed and configured # extra packages to require for testing diff --git a/elpa/org-9.6.7/ob-C.el b/elpa/org-9.7.17/ob-C.el similarity index 89% rename from elpa/org-9.6.7/ob-C.el rename to elpa/org-9.7.17/ob-C.el index 7763c4c0..f7735ee7 100644 --- a/elpa/org-9.6.7/ob-C.el +++ b/elpa/org-9.7.17/ob-C.el @@ -1,6 +1,6 @@ ;;; ob-C.el --- Babel Functions for C and Similar Languages -*- lexical-binding: t; -*- -;; Copyright (C) 2010-2023 Free Software Foundation, Inc. +;; Copyright (C) 2010-2024 Free Software Foundation, Inc. ;; Author: Eric Schulte ;; Thierry Banel @@ -93,44 +93,45 @@ parameter may be used, like rdmd --chatty" is currently being evaluated.") (defun org-babel-execute:cpp (body params) - "Execute BODY according to PARAMS. + "Execute BODY according to its header arguments PARAMS. 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 C++ BODY with org-babel according to its header arguments PARAMS." (org-babel-expand-body:C++ body params)) (defun org-babel-execute:C++ (body params) - "Execute a block of C++ code with org-babel. + "Execute C++ BODY with org-babel according to its header arguments PARAMS. 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 C++ BODY with org-babel according to its header arguments PARAMS." (let ((org-babel-c-variant 'cpp)) (org-babel-C-expand-C++ body params))) (defun org-babel-execute:D (body params) - "Execute a block of D code with org-babel. + "Execute D BODY with org-babel according to its header arguments PARAMS. 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 D BODY with org-babel according to its header arguments PARAMS." (let ((org-babel-c-variant 'd)) (org-babel-C-expand-D body params))) (defun org-babel-execute:C (body params) - "Execute a block of C code with org-babel. + "Execute a C BODY according to its header arguments PARAMS. 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 C BODY according to its header arguments PARAMS." (let ((org-babel-c-variant 'c)) (org-babel-C-expand-C body params))) (defun org-babel-C-execute (body params) - "This function should only be called by `org-babel-execute:C' -or `org-babel-execute:C++' or `org-babel-execute:D'." + "Execute C/C++/D BODY according to its header arguments PARAMS. +This function should only be called by `org-babel-execute:C' or +`org-babel-execute:C++' or `org-babel-execute:D'." (let* ((tmp-src-file (org-babel-temp-file "C-src-" (pcase org-babel-c-variant @@ -196,11 +197,11 @@ or `org-babel-execute:C++' or `org-babel-execute:D'." ))) (defun org-babel-C-expand-C++ (body params) - "Expand a block of C/C++ code with org-babel according to its header arguments." + "Expand C/C++ BODY with according to its header arguments PARAMS." (org-babel-C-expand-C body params)) (defun org-babel-C-expand-C (body params) - "Expand a block of C/C++ code with org-babel according to its header arguments." + "Expand C/C++ BODY according to its header arguments PARAMS." (let ((vars (org-babel--get-vars params)) (colnames (cdr (assq :colname-names params))) (main-p (not (string= (cdr (assq :main params)) "no"))) @@ -212,7 +213,9 @@ or `org-babel-execute:C++' or `org-babel-execute:D'." nil)) (namespaces (org-babel-read (cdr (assq :namespaces params)) - nil))) + nil)) + (prologue (cdr (assq :prologue params))) + (epilogue (cdr (assq :epilogue params)))) (when (stringp includes) (setq includes (split-string includes))) (when (stringp namespaces) @@ -226,6 +229,11 @@ or `org-babel-execute:C++' or `org-babel-execute:D'." (nconc result (list (concat y " " x))) (setq y nil))) (setq defines (cdr result)))) + (setq body + (concat + (and prologue (concat prologue "\n")) + body + (and epilogue (concat "\n" epilogue "\n")))) (mapconcat 'identity (list ;; includes @@ -269,7 +277,7 @@ or `org-babel-execute:C++' or `org-babel-execute:D'." 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 D BODY according to its header arguments PARAMS." (let ((vars (org-babel--get-vars params)) (colnames (cdr (assq :colname-names params))) (main-p (not (string= (cdr (assq :main params)) "no"))) @@ -313,13 +321,15 @@ or `org-babel-execute:C++' or `org-babel-execute:D'." (format "int main() {\n%s\nreturn 0;\n}\n" body))) (defun org-babel-prep-session:C (_session _params) - "This function does nothing as C is a compiled language with no -support for sessions." + "Throw and error that sessions are not supported. +This function does nothing as C is a compiled language with no support +for sessions." (error "C is a compiled language -- no support for sessions")) (defun org-babel-load-session:C (_session _body _params) - "This function does nothing as C is a compiled language with no -support for sessions." + "Throw and error that sessions are not supported. +This function does nothing as C is a compiled language with no support +for sessions." (error "C is a compiled language -- no support for sessions")) ;; helper functions @@ -379,10 +389,11 @@ FORMAT can be either a format string or a function which is called with VAL." type)))) (defun org-babel-C-val-to-base-type (val) - "Determine the base type of VAL which may be -`integerp' if all base values are integers -`floatp' if all base values are either floating points or integers -`stringp' otherwise." + "Determine the base type of VAL. +The type is: +- `integerp' if all base values are integers; +- `floatp' if all base values are either floating points or integers; +- `stringp' otherwise." (cond ((integerp val) 'integerp) ((floatp val) 'floatp) @@ -401,7 +412,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 PAIR of (var . val) C variable assignment." ;; TODO list support (let ((var (car pair)) (val (cdr pair))) @@ -471,7 +482,7 @@ int get_column_num (int nbcols, const char** header, const char* column) (defun org-babel-C-header-to-C (head type) "Convert an elisp list of header table into a C or D vector specifying a variable with the name of the table." - (message "%S" type) + (unless noninteractive (message "%S" type)) (let ((table (car head)) (headers (cdr head)) (typename (pcase type diff --git a/elpa/org-9.6.7/ob-R.el b/elpa/org-9.7.17/ob-R.el similarity index 94% rename from elpa/org-9.6.7/ob-R.el rename to elpa/org-9.7.17/ob-R.el index f2cc069a..e9a1ce76 100644 --- a/elpa/org-9.6.7/ob-R.el +++ b/elpa/org-9.7.17/ob-R.el @@ -1,6 +1,6 @@ ;;; ob-R.el --- Babel Functions for R -*- lexical-binding: t; -*- -;; Copyright (C) 2009-2023 Free Software Foundation, Inc. +;; Copyright (C) 2009-2024 Free Software Foundation, Inc. ;; Author: Eric Schulte ;; Dan Davison @@ -64,6 +64,7 @@ (colormodel . :any) (useDingbats . :any) (horizontal . :any) + (async . ((yes no))) (results . ((file list vector table scalar verbatim) (raw html latex org code pp drawer) (replace silent none append prepend) @@ -91,15 +92,6 @@ this variable.") :version "24.1" :type 'string) -(defvar ess-current-process-name) ; dynamically scoped -(defvar ess-local-process-name) ; dynamically scoped -(defun org-babel-edit-prep:R (info) - (let ((session (cdr (assq :session (nth 2 info))))) - (when (and session - (string-prefix-p "*" session) - (string-suffix-p "*" session)) - (org-babel-R-initiate-session session nil)))) - ;; The usage of utils::read.table() ensures that the command ;; read.table() can be found even in circumstances when the utils ;; package is not in the search path from R. @@ -156,7 +148,7 @@ This function is used when the table does not contain a header.") "\n")) (defun org-babel-execute:R (body params) - "Execute a block of R code. + "Execute a block of R code BODY according to PARAMS. This function is called by `org-babel-execute-src-block'." (save-excursion (let* ((result-params (cdr (assq :result-params params))) @@ -215,7 +207,8 @@ This function is called by `org-babel-execute-src-block'." ;; helper functions (defun org-babel-variable-assignments:R (params) - "Return list of R statements assigning the block's variables." + "Return list of R statements assigning the block's variables. +Retrieve variables from PARAMS." (let ((vars (org-babel--get-vars params))) (mapcar (lambda (pair) @@ -261,42 +254,44 @@ This function is called by `org-babel-execute-src-block'." (t (format "%s <- %S" name (prin1-to-string value)))))) +(defvar ess-current-process-name) ; dynamically scoped +(defvar ess-local-process-name) ; dynamically scoped (defvar ess-ask-for-ess-directory) ; dynamically scoped +(defvar ess-gen-proc-buffer-name-function) ; defined in ess-inf.el (defun org-babel-R-initiate-session (session params) - "If there is not a current R process then create one." + "Create or return the current R SESSION buffer. +Use PARAMS to set default directory when creating a new session." (unless (string= session "none") - (let ((session (or session "*R*")) - (ess-ask-for-ess-directory - (and (boundp 'ess-ask-for-ess-directory) - ess-ask-for-ess-directory - (not (cdr (assq :dir params)))))) + (let* ((session (or session "*R*")) + (ess-ask-for-ess-directory + (and (boundp 'ess-ask-for-ess-directory) + ess-ask-for-ess-directory + (not (cdr (assq :dir params))))) + ;; Make ESS name the process buffer as SESSION. + (ess-gen-proc-buffer-name-function + (lambda (_) session))) (if (org-babel-comint-buffer-livep session) session (save-window-excursion (when (get-buffer session) ;; Session buffer exists, but with dead process (set-buffer session)) - (require 'ess-r-mode) + (org-require-package 'ess-r-mode "ESS") (set-buffer (run-ess-r)) (let ((R-proc (get-process (or ess-local-process-name ess-current-process-name)))) (while (process-get R-proc 'callbacks) (ess-wait-for-process R-proc))) - (rename-buffer - (if (bufferp session) - (buffer-name session) - (if (stringp session) - session - (buffer-name)))) (current-buffer)))))) (defun org-babel-R-associate-session (session) "Associate R code buffer with an R session. Make SESSION be the inferior ESS process associated with the current code buffer." - (setq ess-local-process-name - (process-name (get-buffer-process session))) - (ess-make-buffer-current)) + (when-let* ((process (get-buffer-process session))) + (setq ess-local-process-name (process-name process)) + (ess-make-buffer-current)) + (setq-local ess-gen-proc-buffer-name-function (lambda (_) session))) (defvar org-babel-R-graphics-devices '((:bmp "bmp" "filename") @@ -489,9 +484,10 @@ 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_\\(.+?\\)_\\(.+\\)\"$" + "^\\(?:[>.+] \\)*\\[1\\] \"ob_comint_async_R_\\(start\\|end\\|file\\)_\\(.+\\)\"$" 'org-babel-chomp - 'ob-session-async-R-value-callback) + 'ob-session-async-R-value-callback + 'disable-prompt-filtering) (cl-case result-type (value (let ((tmp-file (org-babel-temp-file "R-"))) @@ -520,7 +516,7 @@ by `org-babel-comint-async-filter'." (ess-eval-buffer nil))) tmp-file)) (output - (let ((uuid (md5 (number-to-string (random 100000000)))) + (let ((uuid (org-id-uuid)) (ess-local-process-name (process-name (get-buffer-process session))) (ess-eval-visibly-p nil)) diff --git a/elpa/org-9.6.7/ob-awk.el b/elpa/org-9.7.17/ob-awk.el similarity index 85% rename from elpa/org-9.6.7/ob-awk.el rename to elpa/org-9.7.17/ob-awk.el index e5e42a91..d94da405 100644 --- a/elpa/org-9.6.7/ob-awk.el +++ b/elpa/org-9.7.17/ob-awk.el @@ -1,6 +1,6 @@ ;;; ob-awk.el --- Babel Functions for Awk -*- lexical-binding: t; -*- -;; Copyright (C) 2011-2023 Free Software Foundation, Inc. +;; Copyright (C) 2011-2024 Free Software Foundation, Inc. ;; Author: Eric Schulte ;; Maintainer: Tyler Smith @@ -48,14 +48,20 @@ (defvar org-babel-awk-command "awk" "Name of the awk executable command.") -(defun org-babel-expand-body:awk (body _params) +(defun org-babel-expand-body:awk (body params) "Expand BODY according to PARAMS, return the expanded body." - body) + (let ((prologue (cdr (assq :prologue params))) + (epilogue (cdr (assq :epilogue params)))) + (concat + (and prologue (concat prologue "\n")) + body + (and epilogue (concat "\n" epilogue "\n"))))) (defun org-babel-execute:awk (body params) - "Execute a block of Awk code with org-babel. + "Execute a block of Awk code BODY with org-babel. +PARAMS is a plist of src block parameters . This function is called by `org-babel-execute-src-block'." - (message "Executing Awk source code block") + (unless noninteractive (message "Executing Awk source code block")) (let* ((result-params (cdr (assq :result-params params))) (cmd-line (cdr (assq :cmd-line params))) (in-file (cdr (assq :in-file params))) @@ -100,7 +106,9 @@ This function is called by `org-babel-execute-src-block'." (cdr (assq :rowname-names params)) (cdr (assq :rownames params)))))) (defun org-babel-awk-var-to-awk (var &optional sep) - "Return a printed value of VAR suitable for parsing with awk." + "Return a printed value of VAR suitable for parsing with awk. +SEP, when non-nil is a separator used when converting list values to awk +table." (let ((echo-var (lambda (v) (if (stringp v) v (format "%S" v))))) (cond ((and (listp var) (listp (car var))) diff --git a/elpa/org-9.6.7/ob-calc.el b/elpa/org-9.7.17/ob-calc.el similarity index 74% rename from elpa/org-9.6.7/ob-calc.el rename to elpa/org-9.7.17/ob-calc.el index 5572ce81..171fd1b0 100644 --- a/elpa/org-9.6.7/ob-calc.el +++ b/elpa/org-9.7.17/ob-calc.el @@ -1,6 +1,6 @@ ;;; ob-calc.el --- Babel Functions for Calc -*- lexical-binding: t; -*- -;; Copyright (C) 2010-2023 Free Software Foundation, Inc. +;; Copyright (C) 2010-2024 Free Software Foundation, Inc. ;; Author: Eric Schulte ;; Maintainer: Tom Gillespie @@ -44,13 +44,19 @@ (defvar org-babel-default-header-args:calc nil "Default arguments for evaluating a calc source block.") -(defun org-babel-expand-body:calc (body _params) - "Expand BODY according to PARAMS, return the expanded body." body) +(defun org-babel-expand-body:calc (body params) + "Expand BODY according to PARAMS, return the expanded body." + (let ((prologue (cdr (assq :prologue params))) + (epilogue (cdr (assq :epilogue params)))) + (concat + (and prologue (concat prologue "\n")) + body + (and epilogue (concat "\n" epilogue "\n"))))) (defvar org--var-syms) ; Dynamically scoped from org-babel-execute:calc (defun org-babel-execute:calc (body params) - "Execute a block of calc code with Babel." + "Execute BODY of calc code with Babel using PARAMS." (unless (get-buffer "*Calculator*") (save-window-excursion (calc) (calc-quit))) (let* ((vars (org-babel--get-vars params)) @@ -58,7 +64,23 @@ (var-names (mapcar #'symbol-name org--var-syms))) (mapc (lambda (pair) - (calc-push-list (list (cdr pair))) + (let ((val (cdr pair))) + (calc-push-list + (list + (cond + ;; For a vector, Calc follows the format (vec 1 2 3 ...) so + ;; a matrix becomes (vec (vec 1 2 3) (vec 4 5 6) ...). See + ;; the comments in "Arithmetic routines." section of + ;; calc.el. + ((listp val) + (cons 'vec + (if (null (cdr val)) + (car val) + (mapcar (lambda (x) (if (listp x) (cons 'vec x) x)) + val)))) + ((numberp val) + (math-read-number (number-to-string val))) + (t val))))) (calc-store-into (car pair))) vars) (mapc @@ -93,12 +115,14 @@ (mapcar #'org-trim (split-string (org-babel-expand-body:calc body params) "[\n\r]")))) (save-excursion - (with-current-buffer (get-buffer "*Calculator*") + (with-current-buffer "*Calculator*" (prog1 (calc-eval (calc-top 1)) (calc-pop 1))))) (defun org-babel-calc-maybe-resolve-var (el) +"Resolve user variables in EL. +EL is taken from the output of `math-read-exprs'." (if (consp el) (if (and (eq 'var (car el)) (member (cadr el) org--var-syms)) (progn diff --git a/elpa/org-9.6.7/ob-clojure.el b/elpa/org-9.7.17/ob-clojure.el similarity index 63% rename from elpa/org-9.6.7/ob-clojure.el rename to elpa/org-9.7.17/ob-clojure.el index d993e0cb..eb2d8c34 100644 --- a/elpa/org-9.6.7/ob-clojure.el +++ b/elpa/org-9.7.17/ob-clojure.el @@ -1,6 +1,6 @@ ;;; ob-clojure.el --- Babel Functions for Clojure -*- lexical-binding: t; -*- -;; Copyright (C) 2009-2023 Free Software Foundation, Inc. +;; Copyright (C) 2009-2024 Free Software Foundation, Inc. ;; Author: Joel Boehland, Eric Schulte, Oleh Krehel, Frederick Giasson ;; Maintainer: Daniel Kraus @@ -25,20 +25,21 @@ ;;; Commentary: -;; Support for evaluating Clojure code +;; Support for evaluating Clojure / ClojureScript code. ;; Requirements: ;; - Clojure (at least 1.2.0) ;; - clojure-mode -;; - inf-clojure, Cider, SLIME, babashka or nbb +;; - babashka, nbb, Clojure CLI tools, Cider, inf-clojure or SLIME ;; For clojure-mode, see https://github.com/clojure-emacs/clojure-mode -;; For inf-clojure, see https://github.com/clojure-emacs/inf-clojure -;; For Cider, see https://github.com/clojure-emacs/cider -;; For SLIME, see https://slime.common-lisp.dev ;; For babashka, see https://github.com/babashka/babashka ;; For nbb, see https://github.com/babashka/nbb +;; For Clojure CLI tools, see https://clojure.org/guides/deps_and_cli +;; For Cider, see https://github.com/clojure-emacs/cider +;; For inf-clojure, see https://github.com/clojure-emacs/inf-clojure +;; For SLIME, see https://slime.common-lisp.dev ;; For SLIME, the best way to install its components is by following ;; the directions as set out by Phil Hagelberg (Technomancy) on the @@ -78,20 +79,33 @@ (defcustom org-babel-clojure-backend (cond ((executable-find "bb") 'babashka) - ((executable-find "nbb") 'nbb) + ((executable-find "clojure") 'clojure-cli) ((featurep 'cider) 'cider) ((featurep 'inf-clojure) 'inf-clojure) ((featurep 'slime) 'slime) (t nil)) "Backend used to evaluate Clojure code blocks." :group 'org-babel - :package-version '(Org . "9.6") + :package-version '(Org . "9.7") :type '(choice - (const :tag "inf-clojure" inf-clojure) + (const :tag "babashka" babashka) + (const :tag "clojure-cli" clojure-cli) (const :tag "cider" cider) + (const :tag "inf-clojure" inf-clojure) (const :tag "slime" slime) - (const :tag "babashka" babashka) + (const :tag "Not configured yet" nil))) + +(defcustom org-babel-clojurescript-backend + (cond + ((or (executable-find "nbb") (executable-find "npx")) 'nbb) + ((featurep 'cider) 'cider) + (t nil)) + "Backend used to evaluate ClojureScript code blocks." + :group 'org-babel + :package-version '(Org . "9.7") + :type '(choice (const :tag "nbb" nbb) + (const :tag "cider" cider) (const :tag "Not configured yet" nil))) (defcustom org-babel-clojure-default-ns "user" @@ -100,19 +114,29 @@ :group 'org-babel) (defcustom ob-clojure-babashka-command (executable-find "bb") - "Path to the babashka executable." + "Babashka command used by the Clojure `babashka' backend." :type '(choice file (const nil)) :group 'org-babel :package-version '(Org . "9.6")) -(defcustom ob-clojure-nbb-command (executable-find "nbb") - "Path to the nbb executable." - :type '(choice file (const nil)) +(defcustom ob-clojure-nbb-command (or (executable-find "nbb") + (when-let* ((npx (executable-find "npx"))) + (concat npx " nbb"))) + "Nbb command used by the ClojureScript `nbb' backend." + :type '(choice string (const nil)) :group 'org-babel - :package-version '(Org . "9.6")) + :package-version '(Org . "9.7")) + +(defcustom ob-clojure-cli-command (when-let* ((cmd (executable-find "clojure"))) + (concat cmd " -M")) + "Clojure CLI command used by the Clojure `clojure-cli' backend." + :type '(choice string (const nil)) + :group 'org-babel + :package-version '(Org . "9.7")) -(defun org-babel-expand-body:clojure (body params) - "Expand BODY according to PARAMS, return the expanded body." +(defun org-babel-expand-body:clojure (body params &optional cljs-p) + "Expand BODY according to PARAMS, return the expanded body. +When CLJS-P is non-nil, expand in a cljs context instead of clj." (let* ((vars (org-babel--get-vars params)) (backend-override (cdr (assq :backend params))) (org-babel-clojure-backend @@ -146,10 +170,26 @@ or set the `:backend' header argument")))) vars "\n ") body)))))) - (if (or (member "code" result-params) - (member "pp" result-params)) - (format "(clojure.pprint/pprint (do %s))" body) - body))) + ;; If the result param is set to "output" we don't have to do + ;; anything special and just let the backend handle everything + (if (member "output" result-params) + body + + ;; If the result is not "output" (i.e. it's "value"), disable + ;; stdout output and print the last returned value. Use pprint + ;; instead of prn when results param is "pp" or "code". + (concat + (if (or (member "code" result-params) + (member "pp" result-params)) + (concat (if cljs-p + "(require '[cljs.pprint :refer [pprint]])" + "(require '[clojure.pprint :refer [pprint]])") + " (pprint ") + "(prn ") + (if cljs-p + "(binding [cljs.core/*print-fn* (constantly nil)]" + "(binding [*out* (java.io.StringWriter.)]") + body "))")))) (defvar ob-clojure-inf-clojure-filter-out) (defvar ob-clojure-inf-clojure-tmp-output) @@ -186,8 +226,7 @@ or set the `:backend' header argument")))) (defvar inf-clojure-comint-prompt-regexp) (defun ob-clojure-eval-with-inf-clojure (expanded params) "Evaluate EXPANDED code block with PARAMS using inf-clojure." - (condition-case nil (require 'inf-clojure) - (user-error "inf-clojure not available")) + (org-require-package 'inf-clojure) ;; Maybe initiate the inf-clojure session (unless (and inf-clojure-buffer (buffer-live-p (get-buffer inf-clojure-buffer))) @@ -198,7 +237,9 @@ or set the `:backend' header argument")))) "clojure" (format "clojure -A%s" alias) cmd0) cmd0))) - (setq comint-prompt-regexp inf-clojure-comint-prompt-regexp) + (setq + org-babel-comint-prompt-regexp-old comint-prompt-regexp + comint-prompt-regexp inf-clojure-comint-prompt-regexp) (funcall-interactively #'inf-clojure cmd) (goto-char (point-max)))) (sit-for 1)) @@ -226,38 +267,24 @@ or set the `:backend' header argument")))) s)) (reverse ob-clojure-inf-clojure-tmp-output))))) -(defun ob-clojure-eval-with-cider (expanded params) - "Evaluate EXPANDED code block with PARAMS using cider." - (condition-case nil (require 'cider) - (user-error "cider not available")) - (let ((connection (cider-current-connection (cdr (assq :target params)))) - (result-params (cdr (assq :result-params params))) - result0) +(defun ob-clojure-eval-with-cider (expanded _params &optional cljs-p) + "Evaluate EXPANDED code block using cider. +When CLJS-P is non-nil, use a cljs connection instead of clj. +The PARAMS from Babel are not used in this function." + (org-require-package 'cider "Cider") + (let ((connection (cider-current-connection (if cljs-p "cljs" "clj")))) (unless connection (sesman-start-session 'CIDER)) (if (not connection) ;; Display in the result instead of using `user-error' - (setq result0 "Please reevaluate when nREPL is connected") - (ob-clojure-with-temp-expanded expanded params - (let ((response (nrepl-sync-request:eval exp connection))) - (push (or (nrepl-dict-get response "root-ex") - (nrepl-dict-get response "ex") - (nrepl-dict-get - response (if (or (member "output" result-params) - (member "pp" result-params)) - "out" - "value"))) - result0))) - (ob-clojure-string-or-list - ;; Filter out s-expressions that return nil (string "nil" - ;; from nrepl eval) or comment forms (actual nil from nrepl) - (reverse (delete "" (mapcar (lambda (r) - (replace-regexp-in-string "nil" "" (or r ""))) - result0))))))) + "Please reevaluate when nREPL is connected" + (let ((response (nrepl-sync-request:eval expanded connection))) + (or (nrepl-dict-get response "root-ex") + (nrepl-dict-get response "ex") + (nrepl-dict-get response "out")))))) (defun ob-clojure-eval-with-slime (expanded params) "Evaluate EXPANDED code block with PARAMS using slime." - (condition-case nil (require 'slime) - (user-error "slime not available")) + (org-require-package 'slime "SLIME") (with-temp-buffer (insert expanded) (slime-eval @@ -265,39 +292,54 @@ or set the `:backend' header argument")))) ,(buffer-substring-no-properties (point-min) (point-max))) (cdr (assq :package params))))) -(defun ob-clojure-eval-with-babashka (bb expanded) - "Evaluate EXPANDED code block using BB (babashka or nbb)." - (let ((script-file (org-babel-temp-file "clojure-bb-script-" ".clj"))) +(defun ob-clojure-eval-with-cmd (cmd expanded) + "Evaluate EXPANDED code block using CMD (babashka, clojure or nbb)." + (let ((script-file (org-babel-temp-file "clojure-cmd-script-" ".clj"))) (with-temp-file script-file (insert expanded)) (org-babel-eval - (format "%s %s" bb (org-babel-process-file-name script-file)) + (format "%s %s" cmd (org-babel-process-file-name script-file)) ""))) -(defun org-babel-execute:clojure (body params) - "Execute the BODY block of Clojure code with PARAMS using Babel." +(defun org-babel-execute:clojure (body params &optional cljs-p) + "Execute the BODY block of Clojure code with PARAMS using Babel. +When CLJS-P is non-nil, execute with a ClojureScript backend +instead of Clojure." (let* ((backend-override (cdr (assq :backend params))) (org-babel-clojure-backend (cond (backend-override (intern backend-override)) - (org-babel-clojure-backend org-babel-clojure-backend) - (t (user-error "You need to customize `org-babel-clojure-backend' -or set the `:backend' header argument"))))) - (let* ((expanded (org-babel-expand-body:clojure body params)) + (org-babel-clojure-backend (if cljs-p + org-babel-clojurescript-backend + org-babel-clojure-backend)) + (t (user-error "You need to customize `%S' +or set the `:backend' header argument" + (if cljs-p + org-babel-clojurescript-backend + org-babel-clojure-backend))))) + ;; We allow a Clojure source block to be evaluated with the + ;; nbb backend and therefore have to expand the body with + ;; ClojureScript syntax when we either evaluate a + ;; ClojureScript source block or use the nbb backend. + (cljs-p (or cljs-p (eq org-babel-clojure-backend 'nbb)))) + (let* ((expanded (org-babel-expand-body:clojure body params cljs-p)) (result-params (cdr (assq :result-params params))) result) (setq result (cond ((eq org-babel-clojure-backend 'inf-clojure) (ob-clojure-eval-with-inf-clojure expanded params)) + ((eq org-babel-clojure-backend 'clojure-cli) + (ob-clojure-eval-with-cmd ob-clojure-cli-command expanded)) ((eq org-babel-clojure-backend 'babashka) - (ob-clojure-eval-with-babashka ob-clojure-babashka-command expanded)) + (ob-clojure-eval-with-cmd ob-clojure-babashka-command expanded)) ((eq org-babel-clojure-backend 'nbb) - (ob-clojure-eval-with-babashka ob-clojure-nbb-command expanded)) + (ob-clojure-eval-with-cmd ob-clojure-nbb-command expanded)) ((eq org-babel-clojure-backend 'cider) - (ob-clojure-eval-with-cider expanded params)) + (ob-clojure-eval-with-cider expanded params cljs-p)) ((eq org-babel-clojure-backend 'slime) - (ob-clojure-eval-with-slime expanded params)))) + (ob-clojure-eval-with-slime expanded params)) + (t (user-error "Invalid backend")))) (org-babel-result-cond result-params result (condition-case nil (org-babel-script-escape result) @@ -305,7 +347,7 @@ or set the `:backend' header argument"))))) (defun org-babel-execute:clojurescript (body params) "Evaluate BODY with PARAMS as ClojureScript code." - (org-babel-execute:clojure body (cons '(:target . "cljs") params))) + (org-babel-execute:clojure body params t)) (provide 'ob-clojure) diff --git a/elpa/org-9.6.7/ob-comint.el b/elpa/org-9.7.17/ob-comint.el similarity index 66% rename from elpa/org-9.6.7/ob-comint.el rename to elpa/org-9.7.17/ob-comint.el index adfe31c4..be5b4133 100644 --- a/elpa/org-9.6.7/ob-comint.el +++ b/elpa/org-9.7.17/ob-comint.el @@ -1,6 +1,6 @@ ;;; ob-comint.el --- Babel Functions for Interaction with Comint Buffers -*- lexical-binding: t; -*- -;; Copyright (C) 2009-2023 Free Software Foundation, Inc. +;; Copyright (C) 2009-2024 Free Software Foundation, Inc. ;; Author: Eric Schulte ;; Keywords: literate programming, reproducible research, comint @@ -58,6 +58,48 @@ executed inside the protection of `save-excursion' and (let ((comint-input-filter (lambda (_input) nil))) ,@body)))))) +(defvar-local org-babel-comint-prompt-regexp-old nil + "Fallback regexp used to detect prompt.") + +(defcustom org-babel-comint-fallback-regexp-threshold 5.0 + "Waiting time until trying to use fallback regexp to detect prompt. +This is useful when prompt unexpectedly changes." + :type 'float + :group 'org-babel + :package-version '(Org . "9.7")) + +(defun org-babel-comint--set-fallback-prompt () + "Swap `comint-prompt-regexp' and `org-babel-comint-prompt-regexp-old'." + (when org-babel-comint-prompt-regexp-old + (let ((tmp comint-prompt-regexp)) + (setq comint-prompt-regexp org-babel-comint-prompt-regexp-old + org-babel-comint-prompt-regexp-old tmp)))) + +(defun org-babel-comint--prompt-filter (string &optional prompt-regexp) + "Remove PROMPT-REGEXP from STRING. + +PROMPT-REGEXP defaults to `comint-prompt-regexp'." + (let* ((prompt-regexp (or prompt-regexp comint-prompt-regexp)) + ;; We need newline in case if we do progressive replacement + ;; of agglomerated comint prompts with `comint-prompt-regexp' + ;; containing ^. + (separator "org-babel-comint--prompt-filter-separator\n")) + (while (string-match-p prompt-regexp string) + (setq string + (replace-regexp-in-string + (format "\\(?:%s\\)?\\(?:%s\\)[ \t]*" separator prompt-regexp) + separator string))) + (delete "" (split-string string separator)))) + +(defun org-babel-comint--echo-filter (string &optional echo) + "Remove ECHO from STRING." + (and echo string + (string-match + (replace-regexp-in-string "\n" "[\r\n]+" (regexp-quote echo)) + string) + (setq string (substring string (match-end 0)))) + string) + (defmacro org-babel-comint-with-output (meta &rest body) "Evaluate BODY in BUFFER and return process output. Will wait until EOE-INDICATOR appears in the output, then return @@ -74,9 +116,7 @@ or user `keyboard-quit' during execution of body." (let ((buffer (nth 0 meta)) (eoe-indicator (nth 1 meta)) (remove-echo (nth 2 meta)) - (full-body (nth 3 meta)) - (org-babel-comint-prompt-separator - "org-babel-comint-prompt-separator")) + (full-body (nth 3 meta))) `(org-babel-comint-in-buffer ,buffer (let* ((string-buffer "") (comint-output-filter-functions @@ -93,43 +133,39 @@ or user `keyboard-quit' during execution of body." ;; pass FULL-BODY to process ,@body ;; wait for end-of-evaluation indicator - (while (progn - (goto-char comint-last-input-end) - (not (save-excursion - (and (re-search-forward - (regexp-quote ,eoe-indicator) nil t) - (re-search-forward - comint-prompt-regexp nil t))))) - (accept-process-output (get-buffer-process (current-buffer)))) + (let ((start-time (current-time))) + (while (progn + (goto-char comint-last-input-end) + (not (save-excursion + (and (re-search-forward + (regexp-quote ,eoe-indicator) nil t) + (re-search-forward + comint-prompt-regexp nil t))))) + (accept-process-output + (get-buffer-process (current-buffer)) + org-babel-comint-fallback-regexp-threshold) + (when (and org-babel-comint-prompt-regexp-old + (> (float-time (time-since start-time)) + org-babel-comint-fallback-regexp-threshold) + (progn + (goto-char comint-last-input-end) + (save-excursion + (and + (re-search-forward + (regexp-quote ,eoe-indicator) nil t) + (re-search-forward + org-babel-comint-prompt-regexp-old nil t))))) + (org-babel-comint--set-fallback-prompt)))) ;; replace cut dangling text (goto-char (process-mark (get-buffer-process (current-buffer)))) (insert dangling-text) + ;; remove echo'd FULL-BODY from input + (and ,remove-echo ,full-body + (setq string-buffer (org-babel-comint--echo-filter string-buffer ,full-body))) + ;; Filter out prompts. - (setq string-buffer - (replace-regexp-in-string - ;; Sometimes, we get multiple agglomerated - ;; prompts together in a single output: - ;; "prompt prompt prompt output" - ;; Remove them progressively, so that - ;; possible "^" in the prompt regexp gets to - ;; work as we remove the heading prompt - ;; instance. - (if (string-prefix-p "^" comint-prompt-regexp) - (format "^\\(%s\\)+" (substring comint-prompt-regexp 1)) - comint-prompt-regexp) - ,org-babel-comint-prompt-separator - string-buffer)) - ;; remove echo'd FULL-BODY from input - (when (and ,remove-echo ,full-body - (string-match - (replace-regexp-in-string - "\n" "[\r\n]+" (regexp-quote (or ,full-body ""))) - string-buffer)) - (setq string-buffer (substring string-buffer (match-end 0)))) - (delete "" (split-string - string-buffer - ,org-babel-comint-prompt-separator)))))) + (org-babel-comint--prompt-filter string-buffer))))) (defun org-babel-comint-input-command (buffer cmd) "Pass CMD to BUFFER. @@ -145,11 +181,23 @@ The input will not be echoed." Note: this is only safe when waiting for the result of a single statement (not large blocks of code)." (org-babel-comint-in-buffer buffer - (while (progn - (goto-char comint-last-input-end) - (not (and (re-search-forward comint-prompt-regexp nil t) - (goto-char (match-beginning 0))))) - (accept-process-output (get-buffer-process buffer))))) + (let ((start-time (current-time))) + (while (progn + (goto-char comint-last-input-end) + (not (and (re-search-forward comint-prompt-regexp nil t) + (goto-char (match-beginning 0))))) + (accept-process-output + (get-buffer-process buffer) + org-babel-comint-fallback-regexp-threshold) + (when (and org-babel-comint-prompt-regexp-old + (> (float-time (time-since start-time)) + org-babel-comint-fallback-regexp-threshold) + (progn + (goto-char comint-last-input-end) + (save-excursion + (re-search-forward + org-babel-comint-prompt-regexp-old nil t)))) + (org-babel-comint--set-fallback-prompt)))))) (defun org-babel-comint-eval-invisibly-and-wait-for-file (buffer file string &optional period) @@ -191,9 +239,12 @@ Its single argument is a string consisting of output from the comint process. It should return a string that will be passed to `org-babel-insert-result'.") +(defvar-local org-babel-comint-async-remove-prompts-p t + "Whether prompts should be detected and removed from async output.") + (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 + "Dangling piece of the last process output, as a string. +Used when `org-babel-comint-async-indicator' is spread across multiple comint outputs due to buffering.") (defun org-babel-comint-use-async (params) @@ -221,6 +272,8 @@ STRING contains the output originally inserted into the comint buffer." (file-callback org-babel-comint-async-file-callback) (combined-string (concat org-babel-comint-async-dangling string)) (new-dangling combined-string) + ;; Assumes comint filter called with session buffer current + (session-dir default-directory) ;; list of UUID's matched by `org-babel-comint-async-indicator' uuid-list) (with-temp-buffer @@ -245,7 +298,8 @@ STRING contains the output originally inserted into the comint buffer." (let* ((info (org-babel-get-src-block-info)) (params (nth 2 info)) (result-params - (cdr (assq :result-params params)))) + (cdr (assq :result-params params))) + (default-directory session-dir)) (org-babel-insert-result (funcall file-callback (nth @@ -268,16 +322,23 @@ STRING contains the output originally inserted into the comint buffer." (res-str-raw (buffer-substring ;; move point to beginning of indicator - (- (match-beginning 0) 1) + (match-beginning 0) ;; 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 + ;; Apply user callback (res-str (funcall org-babel-comint-async-chunk-callback - res-str-raw))) + (if org-babel-comint-async-remove-prompts-p + (org-trim (string-join + (mapcar #'org-trim + (org-babel-comint--prompt-filter + res-str-raw)) + "\n") + t) + 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 @@ -288,7 +349,8 @@ STRING contains the output originally inserted into the comint buffer." (let* ((info (org-babel-get-src-block-info)) (params (nth 2 info)) (result-params - (cdr (assq :result-params params)))) + (cdr (assq :result-params params))) + (default-directory session-dir)) (org-babel-insert-result res-str result-params info)) t)))) @@ -297,18 +359,31 @@ STRING contains the output originally inserted into the comint buffer." (defun org-babel-comint-async-register (session-buffer org-buffer indicator-regexp - chunk-callback file-callback) + chunk-callback file-callback + &optional prompt-handling) "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." +INDICATOR-REGEXP, CHUNK-CALLBACK, and FILE-CALLBACK respectively. +PROMPT-HANDLING may be either of the symbols `filter-prompts', in +which case prompts matching `comint-prompt-regexp' are filtered +from output before it is passed to CHUNK-CALLBACK, or +`disable-prompt-filtering', in which case this behavior is +disabled. For backward-compatibility, the default value of `nil' +is equivalent to `filter-prompts'." (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) + (setq org-babel-comint-async-remove-prompts-p + (cond + ((eq prompt-handling 'disable-prompt-filtering) nil) + ((eq prompt-handling 'filter-prompts) t) + ((eq prompt-handling nil) t) + (t (error (format "Unrecognized prompt handling behavior %s" + prompt-handling))))) (unless (memq org-buffer org-babel-comint-async-buffers) (setq org-babel-comint-async-buffers (cons org-buffer org-babel-comint-async-buffers))) diff --git a/elpa/org-9.6.7/ob-core.el b/elpa/org-9.7.17/ob-core.el similarity index 83% rename from elpa/org-9.6.7/ob-core.el rename to elpa/org-9.7.17/ob-core.el index e69ce4f1..c46efc9e 100644 --- a/elpa/org-9.6.7/ob-core.el +++ b/elpa/org-9.7.17/ob-core.el @@ -1,6 +1,6 @@ ;;; ob-core.el --- Working with Code Blocks -*- lexical-binding: t; -*- -;; Copyright (C) 2009-2023 Free Software Foundation, Inc. +;; Copyright (C) 2009-2024 Free Software Foundation, Inc. ;; Authors: Eric Schulte ;; Dan Davison @@ -22,6 +22,8 @@ ;; You should have received a copy of the GNU General Public License ;; along with GNU Emacs. If not, see . +;;; Commentary: + ;;; Code: (require 'org-macs) @@ -43,7 +45,6 @@ (defvar org-edit-src-content-indentation) (defvar org-link-file-path-type) (defvar org-src-lang-modes) -(defvar org-src-preserve-indentation) (defvar org-babel-tangle-uncomment-comments) (declare-function org-attach-dir "org-attach" (&optional create-if-not-exists-p no-fs-check)) @@ -60,16 +61,26 @@ (declare-function org-cycle "org-cycle" (&optional arg)) (declare-function org-edit-src-code "org-src" (&optional code edit-buffer-name)) (declare-function org-edit-src-exit "org-src" ()) +(declare-function org-src-preserve-indentation-p "org-src" (node)) (declare-function org-element-at-point "org-element" (&optional pom cached-only)) (declare-function org-element-at-point-no-context "org-element" (&optional pom)) (declare-function org-element-context "org-element" (&optional element)) (declare-function org-element-normalize-string "org-element" (s)) -(declare-function org-element-property "org-element" (property element)) -(declare-function org-element-type "org-element" (element)) +(declare-function org-element-property "org-element-ast" (property node)) +(declare-function org-element-begin "org-element" (node)) +(declare-function org-element-end "org-element" (node)) +(declare-function org-element-post-affiliated "org-element" (node)) +(declare-function org-element-contents-begin "org-element" (node)) +(declare-function org-element-contents-end "org-element" (node)) +(declare-function org-element-parent "org-element-ast" (node)) +(declare-function org-element-type "org-element-ast" (node &optional anonymous)) +(declare-function org-element-type-p "org-element-ast" (node &optional types)) +(declare-function org-element-interpret-data "org-element" (data)) (declare-function org-entry-get "org" (pom property &optional inherit literal-nil)) (declare-function org-escape-code-in-region "org-src" (beg end)) (declare-function org-forward-heading-same-level "org" (arg &optional invisible-ok)) (declare-function org-in-commented-heading-p "org" (&optional no-inheritance)) +(declare-function org-indent-block "org" ()) (declare-function org-indent-line "org" ()) (declare-function org-list-get-list-end "org-list" (item struct prevs)) (declare-function org-list-prevs-alist "org-list" (struct)) @@ -212,7 +223,7 @@ When matching, reference is stored in match group 1." ;; (4) header arguments "\\([^\n]*\\)\n" ;; (5) body - "\\([^\000]*?\n\\)??[ \t]*#\\+end_src") + "\\(\\(?:.\\|\n\\)*?\n\\)??[ \t]*#\\+end_src") "Regexp used to identify code blocks.") (defun org-babel--get-vars (params) @@ -305,11 +316,15 @@ environment, to override this check." ;;;###autoload (defun org-babel-execute-safely-maybe () + "Maybe `org-babel-execute-maybe'. +This function does nothing unless `org-babel-no-eval-on-ctrl-c-ctrl-c' +is non-nil." (unless org-babel-no-eval-on-ctrl-c-ctrl-c (org-babel-execute-maybe))) ;;;###autoload (defun org-babel-execute-maybe () +"Execute src block or babel call at point." (interactive) (or (org-babel-execute-src-block-maybe) (org-babel-lob-execute-maybe))) @@ -318,8 +333,7 @@ environment, to override this check." "Execute BODY if point is in a source block and return t. Otherwise do nothing and return nil." - `(if (memq (org-element-type (org-element-context)) - '(inline-src-block src-block)) + `(if (org-element-type-p (org-element-context) '(inline-src-block src-block)) (progn ,@body t) @@ -344,18 +358,27 @@ a window into the `org-babel-get-src-block-info' function." (full (lambda (it) (> (length it) 0))) (printf (lambda (fmt &rest args) (princ (apply #'format fmt args))))) (when info - (with-help-window (help-buffer) - (let ((name (nth 4 info)) - (lang (nth 0 info)) - (switches (nth 3 info)) - (header-args (nth 2 info))) + (let* ((name (nth 4 info)) + (language (nth 0 info)) + (switches (nth 3 info)) + (header-args (nth 2 info)) + (property-header-args + (org-entry-get (point) "header-args" t)) + (property-header-args-language + (org-entry-get (point) (concat "header-args:" language) t))) + (with-help-window (help-buffer) (when name (funcall printf "Name: %s\n" name)) - (when lang (funcall printf "Lang: %s\n" lang)) + (when language (funcall printf "Language: %s\n" language)) + ;; Show header arguments that have been set through + ;; properties (i.e. in property drawers or through + ;; #+PROPERTY) (funcall printf "Properties:\n") - (funcall printf "\t:header-args \t%s\n" (org-entry-get (point) "header-args" t)) - (funcall printf "\t:header-args:%s \t%s\n" lang (org-entry-get (point) (concat "header-args:" lang) t)) - + (funcall printf "\t:header-args \t%s\n" property-header-args) + (funcall printf "\t:header-args:%s \t%s\n" language property-header-args-language) + ;; Show switches (when (funcall full switches) (funcall printf "Switches: %s\n" switches)) + ;; Show default header arguments and header arguments that + ;; have been explicitly set in the current code block. (funcall printf "Header Arguments:\n") (dolist (pair (sort header-args (lambda (a b) (string< (symbol-name (car a)) @@ -434,7 +457,46 @@ then run `org-babel-switch-to-session'." (tangle . ((tangle yes no :any))) (tangle-mode . ((#o755 #o555 #o444 :any))) (var . :any) - (wrap . :any))) + (wrap . :any)) + "Alist defining common header args and their allowed values. + +Keys of the alist are header arg symbols. +Values of the alist are either a symbol `:any' or a list of allowed +values as symbols: + + (header-name . :any) + (header-name . ((value1 value2 value3 ...)) + (header-name . ((value1 value2 value3 ... :any)) + +When Org considers header-arg property inheritance, the innermost +value from the list is considered. + +Symbol `:any' in the value list implies that any value is allowed. +Yet the explicitly listed values from the list will be offered as +completion candidates. + +FIXME: This is currently just supported for `results' and `exports'. +Values in the alist can also be a list of lists. The inner lists +define exclusive groups of values that can be set at the same time for +a given header argument. + + (results . ((file list ...) + (raw html ...)) + +The above example allows multi-component header arguments like + + #+begin_src bash :results file raw + <:results will combine the two values \"file raw\".> + + #+begin_src bash :results file list + <:results will only use the last value \"list\".> + + #+property: header-args :results file html + ... + #+begin_src bash :results list + <:results will inherit with partial override \"list html\".> + +See info node `(org)Results of evaluation' for more details.") (defconst org-babel-header-arg-names (mapcar #'car org-babel-common-header-args-w-values) @@ -611,14 +673,12 @@ Remove final newline character and spurious indentation." (body (if (string-suffix-p "\n" value) (substring value 0 -1) value))) - (cond ((eq (org-element-type datum) 'inline-src-block) + (cond ((org-element-type-p datum 'inline-src-block) ;; Newline characters and indentation in an inline ;; src-block are not meaningful, since they could come from ;; some paragraph filling. Treat them as a white space. (replace-regexp-in-string "\n[ \t]*" " " body)) - ((or org-src-preserve-indentation - (org-element-property :preserve-indent datum)) - body) + ((org-src-preserve-indentation-p datum) body) (t (org-remove-indentation body))))) ;;; functions @@ -653,8 +713,9 @@ By default, consider the block at point. However, when optional argument DATUM is provided, extract information from that parsed object instead. -Return nil if point is not on a source block. Otherwise, return -a list with the following pattern: +Return nil if point is not on a source block (blank lines after a +source block are considered a part of that source block). +Otherwise, return a list with the following pattern: (language body arguments switches name start coderef)" (let* ((datum (or datum (org-element-context))) @@ -670,14 +731,22 @@ a list with the following pattern: lang (org-babel--normalize-body datum) (apply #'org-babel-merge-params - (if inline org-babel-default-inline-header-args - org-babel-default-header-args) - (and (boundp lang-headers) (eval lang-headers t)) + ;; Use `copy-tree' to avoid creating shared structure + ;; with the `org-babel-default-header-args-*' variables: + ;; modifications by `org-babel-generate-file-param' + ;; below would modify the shared structure, thereby + ;; modifying the variables. + (copy-tree + (if inline org-babel-default-inline-header-args + org-babel-default-header-args) + t) + (and (boundp lang-headers) + (copy-tree (eval lang-headers t) t)) (append ;; If DATUM is provided, make sure we get node ;; properties applicable to its location within ;; the document. - (org-with-point-at (org-element-property :begin datum) + (org-with-point-at (org-element-begin datum) (org-babel-params-from-properties lang no-eval)) (mapcar (lambda (h) (org-babel-parse-header-arguments h no-eval)) @@ -694,7 +763,9 @@ a list with the following pattern: info)))) (defun org-babel--expand-body (info) - "Expand noweb references in body and remove any coderefs." + "Expand noweb references in src block and remove any coderefs. +The src block is defined by its INFO, as returned by +`org-babel-get-src-block-info'." (let ((coderef (nth 6 info)) (expand (if (org-babel-noweb-p (nth 2 info) :eval) @@ -705,14 +776,43 @@ a list with the following pattern: (org-src-coderef-regexp coderef) "" expand nil nil 1)))) (defun org-babel--file-desc (params result) - "Retrieve file description." + "Retrieve description for file link result of evaluation. +PARAMS is header argument values. RESULT is the file link as returned +by the code block. + +When `:file-desc' header argument is provided use its value or +duplicate RESULT in the description. + +When `:file-desc' is missing, return nil." (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' +(defvar *this*) +;; Dynamically bound in `org-babel-execute-src-block' +;; and `org-babel-read' + +(defun org-babel-session-buffer (&optional info) + "Return buffer name for session associated with current code block. +Return nil when no such live buffer with process exists. +When INFO is non-nil, it should be a list returned by +`org-babel-get-src-block-info'. +This function uses org-babel-session-buffer: function to +retrieve backend-specific session buffer name." + (declare-function org-babel-comint-buffer-livep "ob-comint" (buffer)) + (when-let* ((info (or info (org-babel-get-src-block-info 'no-eval))) + (lang (nth 0 info)) + (session (cdr (assq :session (nth 2 info)))) + (cmd (intern (concat "org-babel-session-buffer:" lang))) + (buffer-name + (if (fboundp cmd) + (funcall cmd session info) + ;; Use session name as buffer name by default. + session))) + (require 'ob-comint) + (when (org-babel-comint-buffer-livep buffer-name) + buffer-name))) ;;;###autoload (defun org-babel-execute-src-block (&optional arg info params executor-type) @@ -774,8 +874,9 @@ guess will be made." (forward-line) (skip-chars-forward " \t") (let ((result (org-babel-read-result))) - (message (format "Cached: %s" - (replace-regexp-in-string "%" "%%" (format "%S" result)))) + (unless noninteractive + (message (format "Cached: %s" + (replace-regexp-in-string "%" "%%" (format "%S" result))))) result))) ((org-babel-confirm-evaluate info) (let* ((lang (nth 0 info)) @@ -784,33 +885,40 @@ guess will be made." (dir (cdr (assq :dir params))) (mkdirp (cdr (assq :mkdirp params))) (default-directory - (cond - ((not dir) default-directory) - ((member mkdirp '("no" "nil" nil)) - (file-name-as-directory (expand-file-name dir))) - (t - (let ((d (file-name-as-directory (expand-file-name dir)))) - (make-directory d 'parents) - d)))) + (cond + ((not dir) default-directory) + ((when-let* ((session (org-babel-session-buffer info))) + (buffer-local-value 'default-directory (get-buffer session)))) + ((member mkdirp '("no" "nil" nil)) + (file-name-as-directory (expand-file-name dir))) + (t + (let ((d (file-name-as-directory (expand-file-name dir)))) + (make-directory d 'parents) + d)))) (cmd (intern (concat "org-babel-execute:" lang))) result exec-start-time) (unless (fboundp cmd) (error "No org-babel-execute function for %s!" lang)) - (message "Executing %s %s %s..." - (capitalize lang) - (pcase executor-type - ('src-block "code block") - ('inline-src-block "inline code block") - ('babel-call "call") - ('inline-babel-call "inline call") - (e (symbol-name e))) - (let ((name (nth 4 info))) - (if name - (format "(%s)" name) - (format "at position %S" (nth 5 info))))) + (unless noninteractive + (message "Executing %s %s %s..." + (capitalize lang) + (pcase executor-type + ('src-block "code block") + ('inline-src-block "inline code block") + ('babel-call "call") + ('inline-babel-call "inline call") + (e (symbol-name e))) + (let ((name (nth 4 info))) + (if name + (format "(%s)" name) + (format "at position %S" (nth 5 info)))))) (setq exec-start-time (current-time) result - (let ((r (save-current-buffer (funcall cmd body params)))) + (let ((r + ;; Code block may move point in the buffer. + ;; Make sure that the point remains on the + ;; code block. + (save-excursion (funcall cmd body params)))) (if (and (eq (cdr (assq :result-type params)) 'value) (or (member "vector" result-params) (member "table" result-params)) @@ -826,7 +934,7 @@ guess will be made." ;; insert a link to `:file'. (when (and result (not (or (member "link" result-params) - (member "graphics" result-params)))) + (member "graphics" result-params)))) (with-temp-file file (insert (org-babel-format-result result @@ -849,10 +957,13 @@ guess will be made." (setq result (org-babel-ref-resolve post)) (when file (setq result-params (remove "file" result-params)))))) - (if (member "none" result-params) - (message "result silenced") + (unless (member "none" result-params) (org-babel-insert-result - result result-params info new-hash lang + result result-params info + ;; append/prepend cannot handle hash as we accumulate + ;; multiple outputs together. + (when (member "replace" result-params) new-hash) + lang (time-subtract (current-time) exec-start-time)))) (run-hooks 'org-babel-after-execute-hook) result))))))) @@ -862,7 +973,10 @@ guess will be made." Expand a block of code with org-babel according to its header arguments. This generic implementation of body expansion is called for languages which have not defined their own specific -org-babel-expand-body:lang function." +org-babel-expand-body:lang function. + +VAR-LINES is a list of lines that define variable environment. These +lines will be added after `:prologue' parameter and before BODY." (let ((pro (cdr (assq :prologue params))) (epi (cdr (assq :epilogue params)))) (mapconcat #'identity @@ -874,7 +988,10 @@ org-babel-expand-body:lang function." ;;;###autoload (defun org-babel-expand-src-block (&optional _arg info params) - "Expand the current source code block. + "Expand the current source code block or block specified by INFO. +INFO is the output of `org-babel-get-src-block-info'. +PARAMS defines inherited header arguments. + Expand according to the source code block's header arguments and pop open the results in a preview buffer." (interactive) @@ -901,7 +1018,7 @@ arguments and pop open the results in a preview buffer." expanded))) (defun org-babel-combine-header-arg-lists (original &rest others) - "Combine a number of lists of header argument names and arguments." + "Combine ORIGINAL and OTHERS lists of header argument names and arguments." (let ((results (copy-sequence original))) (dolist (new-list others) (dolist (arg-pair new-list) @@ -936,7 +1053,10 @@ arguments and pop open the results in a preview buffer." ;;;###autoload (defun org-babel-insert-header-arg (&optional header-arg value) - "Insert a header argument selecting from lists of common args and values." + "Insert a header argument and its value. +HEADER-ARG and VALUE, when provided, are the header argument name and +its value. When HEADER-ARG or VALUE are nil, offer interactive +completion from lists of common args and values." (interactive) (let* ((info (org-babel-get-src-block-info 'no-eval)) (lang (car info)) @@ -1000,6 +1120,9 @@ arguments and pop open the results in a preview buffer." ;;;###autoload (defun org-babel-load-in-session (&optional _arg info) "Load the body of the current source-code block. +When optional argument INFO is non-nil, use source block defined in +INFO, as returned by `org-babel-get-src-block-info'. + Evaluate the header arguments for the source block before entering the session. After loading the body this pops open the session." @@ -1025,8 +1148,8 @@ session." ;;;###autoload (defun org-babel-initiate-session (&optional arg info) - "Initiate session for current code block. -If called with a prefix argument then resolve any variable + "Initiate session for current code block or the block defined by INFO. +If called with a prefix argument ARG, then resolve any variable references in the header arguments and assign these variables in the session. Copy the body of the code block to the kill ring." (interactive "P") @@ -1054,9 +1177,9 @@ the session. Copy the body of the code block to the kill ring." ;;;###autoload (defun org-babel-switch-to-session (&optional arg info) - "Switch to the session of the current code block. + "Switch to the session of the current code block or block defined by INFO. Uses `org-babel-initiate-session' to start the session. If called -with a prefix argument then this is passed on to +with a prefix argument ARG, then this is passed on to `org-babel-initiate-session'." (interactive "P") (pop-to-buffer (org-babel-initiate-session arg info)) @@ -1068,7 +1191,8 @@ with a prefix argument then this is passed on to ;;;###autoload (defun org-babel-switch-to-session-with-code (&optional arg _info) - "Switch to code buffer and display session." + "Switch to code buffer and display session. +Prefix argument ARG is passed to `org-babel-switch-to-session'." (interactive "P") (let ((swap-windows (lambda () @@ -1096,18 +1220,23 @@ Return t if a code block was found at point, nil otherwise." ;; we want to restore this location after executing BODY. (outside-position (and (<= (line-beginning-position) - (org-element-property :post-affiliated element)) + (org-element-post-affiliated element)) (point-marker))) (org-src-window-setup 'switch-invisibly)) (when (and (org-babel-where-is-src-block-head element) - (org-edit-src-code)) + (condition-case nil + (org-edit-src-code) + (t + (org-edit-src-exit) + (when outside-position (goto-char outside-position)) + nil))) (unwind-protect (progn ,@body) (org-edit-src-exit) (when outside-position (goto-char outside-position))) t))) (defun org-babel-do-key-sequence-in-edit-buffer (key) - "Read key sequence and execute the command in edit buffer. + "Read key sequence KEY and execute the command in edit buffer. Enter a key sequence to be executed in the language major-mode edit buffer. For example, TAB will alter the contents of the Org code block according to the effect of TAB in the language @@ -1123,8 +1252,10 @@ evaluation mechanisms." (defvar org-link-bracket-re) (defun org-babel-active-location-p () - (memq (org-element-type (save-match-data (org-element-context))) - '(babel-call inline-babel-call inline-src-block src-block))) + "Return non-nil, when at executable element." + (org-element-type-p + (save-match-data (org-element-context)) + '(babel-call inline-babel-call inline-src-block src-block))) ;;;###autoload (defun org-babel-open-src-block-result (&optional re-run) @@ -1235,10 +1366,10 @@ buffer." (setq ,to-be-removed (current-buffer)) (goto-char (point-min)) (while (re-search-forward "src_\\S-" nil t) - (let ((,datum (save-match-data (org-element-context)))) - (when (eq (org-element-type ,datum) 'inline-src-block) - (goto-char (match-beginning 0)) - (let ((,end (copy-marker (org-element-property :end ,datum)))) + (let ((,datum (org-element-context))) + (when (org-element-type-p ,datum 'inline-src-block) + (goto-char (org-element-begin ,datum)) + (let ((,end (copy-marker (org-element-end ,datum)))) ,@body (goto-char ,end) (set-marker ,end nil)))))) @@ -1263,11 +1394,11 @@ buffer." (setq ,to-be-removed (current-buffer)) (goto-char (point-min)) (while (re-search-forward "call_\\S-\\|^[ \t]*#\\+CALL:" nil t) - (let ((,datum (save-match-data (org-element-context)))) - (when (memq (org-element-type ,datum) - '(babel-call inline-babel-call)) - (goto-char (match-beginning 0)) - (let ((,end (copy-marker (org-element-property :end ,datum)))) + (let ((,datum (org-element-context))) + (when (org-element-type-p ,datum '(babel-call inline-babel-call)) + (goto-char (or (org-element-post-affiliated datum) + (org-element-begin datum))) + (let ((,end (copy-marker (org-element-end ,datum)))) ,@body (goto-char ,end) (set-marker ,end nil)))))) @@ -1293,12 +1424,13 @@ buffer." (goto-char (point-min)) (while (re-search-forward "\\(call\\|src\\)_\\|^[ \t]*#\\+\\(BEGIN_SRC\\|CALL:\\)" nil t) - (let ((,datum (save-match-data (org-element-context)))) - (when (memq (org-element-type ,datum) - '(babel-call inline-babel-call inline-src-block - src-block)) - (goto-char (match-beginning 0)) - (let ((,end (copy-marker (org-element-property :end ,datum)))) + (let ((,datum (org-element-context))) + (when (org-element-type-p + ,datum + '(babel-call inline-babel-call inline-src-block src-block)) + (goto-char (or (org-element-post-affiliated ,datum) + (org-element-begin ,datum))) + (let ((,end (copy-marker (org-element-end ,datum)))) ,@body (goto-char ,end) (set-marker ,end nil)))))) @@ -1308,14 +1440,15 @@ buffer." ;;;###autoload (defun org-babel-execute-buffer (&optional arg) "Execute source code blocks in a buffer. +Prefix argument ARG is passed to `org-babel-execute-src-block'. Call `org-babel-execute-src-block' on every source block in the current buffer." (interactive "P") (org-babel-eval-wipe-error-buffer) (org-save-outline-visibility t (org-babel-map-executables nil - (if (memq (org-element-type (org-element-context)) - '(babel-call inline-babel-call)) + (if (org-element-type-p + (org-element-context) '(babel-call inline-babel-call)) (org-babel-lob-execute-maybe) (org-babel-execute-src-block arg))))) @@ -1323,7 +1456,7 @@ the current buffer." (defun org-babel-execute-subtree (&optional arg) "Execute source code blocks in a subtree. Call `org-babel-execute-src-block' on every source block in -the current subtree." +the current subtree, passing over the prefix argument ARG." (interactive "P") (save-restriction (save-excursion @@ -1391,9 +1524,9 @@ CONTEXT specifies the context of evaluation. It can be `:eval', (when (called-interactively-p 'interactive) (message hash)) hash)))) -(defun org-babel-current-result-hash (&optional info) +(defun org-babel-current-result-hash (&optional _info) "Return the current in-buffer hash." - (let ((result (org-babel-where-is-src-block-result nil info))) + (let ((result (org-babel-where-is-src-block-result nil))) (when result (org-with-point-at result (let ((case-fold-search t)) (looking-at org-babel-result-regexp)) @@ -1477,14 +1610,16 @@ portions of results lines." (progn (org-babel-hide-result-toggle) t)))) (defun org-babel-hide-result-toggle (&optional force) - "Toggle the visibility of the current result." + "Toggle the visibility of the current result. +When FORCE is symbol `off', unconditionally display the result. +Otherwise, when FORCE is non-nil, unconditionally hide the result." (interactive) (save-excursion - (beginning-of-line) + (forward-line 0) (let ((case-fold-search t)) (unless (re-search-forward org-babel-result-regexp nil t) (error "Not looking at a result line"))) - (let ((start (progn (beginning-of-line 2) (1- (point)))) + (let ((start (progn (forward-line 1) (1- (point)))) (end (progn (while (looking-at org-babel-multi-line-header-regexp) (forward-line 1)) @@ -1622,7 +1757,8 @@ balanced instances of \"[ \t]:\", set ALTS to ((32 9) . 58)." (nreverse result)))) (defun org-babel-join-splits-near-ch (ch list) - "Join splits where \"=\" is on either end of the split." + "Join strings in LIST where CH is on either end of the strings. +This function will join list elements like \"a=\" \"2\" into \"a=2\"." (let ((last= (lambda (str) (= ch (aref str (1- (length str)))))) (first= (lambda (str) (= ch (aref str 0))))) (reverse @@ -1659,13 +1795,17 @@ in parameters. Return an alist." This allows expression of multiple variables with one :var as shown below. -#+PROPERTY: var foo=1, bar=2" +#+PROPERTY: var foo=1, bar=2 + +HEADER-ARGUMENTS is an alist of all the arguments." (let (results) (mapc (lambda (pair) (if (eq (car pair) :var) - (mapcar (lambda (v) (push (cons :var (org-trim v)) results)) - (org-babel-join-splits-near-ch - 61 (org-babel-balanced-split (cdr pair) 32))) + (or + (mapcar (lambda (v) (push (cons :var (org-trim v)) results)) + (org-babel-join-splits-near-ch + 61 (org-babel-balanced-split (or (cdr pair) "") 32))) + (push `(:var) results)) (push pair results))) header-arguments) (nreverse results))) @@ -1719,6 +1859,8 @@ shown below. Return a cons cell, the `car' of which contains the TABLE less colnames, and the `cdr' of which contains a list of the column names." + ;; Skip over leading hlines. + (while (eq 'hline (car table)) (pop table)) (if (eq 'hline (nth 1 table)) (cons (cddr table) (car table)) (cons (cdr table) (car table)))) @@ -1780,9 +1922,16 @@ of the vars, cnames and rnames." (when (and (not (equal colnames "no")) ;; 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))))))) + (or colnames + ;; :colnames nil (default) + ;; Auto-assign column names when the table + ;; has hline as the second line after + ;; non-hline row. + (and (> (length (cdr var)) 1) + (not (eq (car (cdr var)) 'hline)) ; first row + (eq (nth 1 (cdr var)) 'hline) ; second row + (not (member 'hline (cddr (cdr var)))) ; other rows + ))) (let ((both (org-babel-get-colnames (cdr var)))) (setq cnames (cons (cons (car var) (cdr both)) cnames)) @@ -1818,18 +1967,18 @@ its current beginning instead. Return the point at the beginning of the current source block. Specifically at the beginning of the #+BEGIN_SRC line. Also set -match-data relatively to `org-babel-src-block-regexp', which see. +`match-data' relatively to `org-babel-src-block-regexp', which see. If the point is not on a source block or within blank lines after an src block, then return nil." (let ((element (or src-block (org-element-at-point)))) - (when (eq (org-element-type element) 'src-block) - (let ((end (org-element-property :end element))) + (when (org-element-type-p element 'src-block) + (let ((end (org-element-end element))) (org-with-wide-buffer ;; Ensure point is not on a blank line after the block. - (beginning-of-line) + (forward-line 0) (skip-chars-forward " \r\t\n" end) (when (< (point) end) - (prog1 (goto-char (org-element-property :post-affiliated element)) + (prog1 (goto-char (org-element-post-affiliated element)) (looking-at org-babel-src-block-regexp)))))))) ;;;###autoload @@ -1841,7 +1990,7 @@ src block, then return nil." ;;;###autoload (defun org-babel-goto-named-src-block (name) - "Go to a named source-code block." + "Go to a source-code block with NAME." (interactive (let ((completion-ignore-case t) (case-fold-search t) @@ -1894,14 +2043,14 @@ to `org-babel-named-src-block-regexp'." (names nil)) (while (re-search-forward regexp nil t) (let ((element (org-element-at-point))) - (when (eq 'src-block (org-element-type element)) + (when (org-element-type-p element 'src-block) (let ((name (org-element-property :name element))) (when name (push name names)))))) names)))) ;;;###autoload (defun org-babel-goto-named-result (name) - "Go to a named result." + "Go to a result with NAME." (interactive (let ((completion-ignore-case t)) (list (completing-read "Source-block name: " @@ -1925,19 +2074,19 @@ buffer or nil if no such result exists." (catch :found (while (re-search-forward re nil t) (let ((element (org-element-at-point))) - (when (or (eq (org-element-type element) 'keyword) + (when (or (org-element-type-p element 'keyword) (< (point) - (org-element-property :post-affiliated element))) + (org-element-post-affiliated element))) (throw :found (line-beginning-position))))))))) (defun org-babel-result-names (&optional file) "Return the names of results in FILE or the current buffer." - (save-excursion - (when file (find-file file)) (goto-char (point-min)) - (let ((case-fold-search t) names) + (with-current-buffer (if file (find-file-noselect file) (current-buffer)) + (org-with-point-at 1 + (let ((case-fold-search t) names) (while (re-search-forward org-babel-result-w-name-regexp nil t) (setq names (cons (match-string-no-properties 9) names))) - names))) + names)))) ;;;###autoload (defun org-babel-next-src-block (&optional arg) @@ -1968,48 +2117,86 @@ With optional prefix argument ARG, jump backward ARG many source blocks." (goto-char (match-beginning 5))))) (defun org-babel-demarcate-block (&optional arg) - "Wrap or split the code in the region or on the point. + "Wrap or split the code in an active region or at point. + +With prefix argument ARG, also create a new heading at point. + When called from inside of a code block the current block is split. When called from outside of a code block a new code block is created. In both cases if the region is demarcated and if the region is not active then the point is demarcated. When called within blank lines after a code block, create a new code -block of the same language with the previous." +block of the same language as the previous." (interactive "P") (let* ((info (org-babel-get-src-block-info 'no-eval)) (start (org-babel-where-is-src-block-head)) ;; `start' will be nil when within space lines after src block. (block (and start (match-string 0))) - (headers (and start (match-string 4))) + (body-beg (and start (match-beginning 5))) + (body-end (and start (match-end 5))) (stars (concat (make-string (or (org-current-level) 1) ?*) " ")) (upper-case-p (and block (let (case-fold-search) (string-match-p "#\\+BEGIN_SRC" block))))) (if (and info start) ;; At src block, but not within blank lines after it. - (mapc - (lambda (place) - (save-excursion - (goto-char place) - (let ((lang (nth 0 info)) - (indent (make-string (org-current-text-indentation) ?\s))) - (when (string-match "^[[:space:]]*$" - (buffer-substring (line-beginning-position) - (line-end-position))) - (delete-region (line-beginning-position) (line-end-position))) - (insert (concat - (if (looking-at "^") "" "\n") - indent (if upper-case-p "#+END_SRC\n" "#+end_src\n") - (if arg stars indent) "\n" - indent (if upper-case-p "#+BEGIN_SRC " "#+begin_src ") - lang - (if (> (length headers) 1) - (concat " " headers) headers) - (if (looking-at "[\n\r]") - "" - (concat "\n" (make-string (current-column) ? ))))))) - (move-end-of-line 2)) - (sort (if (org-region-active-p) (list (mark) (point)) (list (point))) #'>)) + (let* ((copy (org-element-copy (org-element-at-point))) + (before (org-element-begin copy)) + (beyond (org-element-end copy)) + (parts + (if (org-region-active-p) + (list body-beg (region-beginning) (region-end) body-end) + (list body-beg (point) body-end))) + (pads ;; To calculate left-side white-space padding. + (if (org-region-active-p) + (list (region-beginning) (region-end)) + (list (point)))) + (n (- (length parts) 2)) ;; 1 or 2 parts in `dolist' below. + ;; `post-blank' caches the property before setting it to 0. + (post-blank (org-element-property :post-blank copy))) + ;; Point or region are within body when parts is in increasing order. + (unless (apply #'<= parts) + (user-error "Select within the source block body to split it")) + (setq parts (mapcar (lambda (p) (buffer-substring (car p) (cdr p))) + (seq-mapn #'cons parts (cdr parts)))) + ;; Map positions to columns for white-space padding. + (setq pads (mapcar (lambda (p) (save-excursion + (goto-char p) + (current-column))) + pads)) + (push 0 pads) ;; The 1st part never requires white-space padding. + (setq parts (mapcar (lambda (p) (string-join + (list (make-string (car p) ?\s) + (cdr p)))) + (seq-mapn #'cons pads parts))) + (delete-region before beyond) + ;; Set `:post-blank' to 0. We take care of spacing between blocks. + (org-element-put-property copy :post-blank 0) + (org-element-put-property copy :value (car parts)) + (insert (org-element-interpret-data copy)) + ;; `org-indent-block' may see another `org-element' (e.g. paragraph) + ;; immediately after the block. Ensure to indent the inserted block + ;; and move point to its end. + (org-babel-previous-src-block 1) + (org-indent-block) + (goto-char (org-element-end (org-element-at-point))) + (org-element-put-property copy :caption nil) + (org-element-put-property copy :name nil) + ;; Insert the 2nd block, and the 3rd block when region is active. + (dolist (part (cdr parts)) + (org-element-put-property copy :value part) + (insert (if arg (concat stars "\n") "\n")) + (cl-decf n) + (when (= n 0) + ;; Use `post-blank' to reset the property of the last block. + (org-element-put-property copy :post-blank post-blank)) + (insert (org-element-interpret-data copy)) + ;; Ensure to indent the inserted block and move point to its end. + (org-babel-previous-src-block 1) + (org-indent-block) + (goto-char (org-element-end (org-element-at-point)))) + ;; Leave point at the last inserted block. + (goto-char (org-babel-previous-src-block 1))) (let ((start (point)) (lang (or (car info) ; Reuse language from previous block. (completing-read @@ -2059,7 +2246,7 @@ the results hash, or nil. Leave point before the keyword." ;; ;; : fixed-width area, unrelated to the above. (unless (looking-at "^[ \t]*$") (save-excursion (insert "\n"))) - (beginning-of-line 0) + (forward-line -1) (when hash (org-babel-hide-hash))) (defun org-babel--clear-results-maybe (hash) @@ -2074,11 +2261,11 @@ leave point where new results should be inserted." (let ((case-fold-search t)) (looking-at org-babel-result-regexp)) (unless (string= (match-string 1) hash) (let* ((e (org-element-at-point)) - (post (copy-marker (org-element-property :post-affiliated e)))) + (post (copy-marker (org-element-post-affiliated e)))) ;; Delete contents. (delete-region post (save-excursion - (goto-char (org-element-property :end e)) + (goto-char (org-element-end e)) (skip-chars-backward " \t\n") (line-beginning-position 2))) ;; Delete RESULT keyword. However, if RESULTS keyword is @@ -2113,32 +2300,29 @@ to HASH." ((or `inline-babel-call `inline-src-block) ;; Results for inline objects are located right after them. ;; There is no RESULTS line to insert either. - (let ((limit (pcase (org-element-type (org-element-property :parent context)) - (`section (org-element-property - :end (org-element-property :parent context))) - (_ (org-element-property - :contents-end (org-element-property :parent context)))))) - (goto-char (org-element-property :end context)) + (let ((limit (or (org-element-contents-end (org-element-parent context)) + (org-element-end (org-element-parent context))))) + (goto-char (org-element-end context)) (skip-chars-forward " \t\n" limit) (throw :found (and (< (point) limit) (let ((result (org-element-context))) - (and (eq (org-element-type result) 'macro) + (and (org-element-type-p result 'macro) (string= (org-element-property :key result) "results") (if (not insert) (point) (delete-region (point) (progn - (goto-char (org-element-property :end result)) + (goto-char (org-element-end result)) (skip-chars-backward " \t") (point))) (point)))))))) ((or `babel-call `src-block) (let* ((name (org-element-property :name context)) (named-results (and name (org-babel-find-named-result name)))) - (goto-char (or named-results (org-element-property :end context))) + (goto-char (or named-results (org-element-end context))) (cond ;; Existing results named after the current source. (named-results @@ -2150,23 +2334,23 @@ to HASH." ;; No possible anonymous results at the very end of ;; buffer or outside CONTEXT parent. ((eq (point) - (or (pcase (org-element-type (org-element-property :parent context)) - ((or `section `org-data) (org-element-property - :end (org-element-property :parent context))) - (_ (org-element-property - :contents-end (org-element-property :parent context)))) + (or (pcase (org-element-type (org-element-parent context)) + ((or `section `org-data) + (org-element-end (org-element-parent context))) + (_ (org-element-contents-end + (org-element-parent context)))) (point-max)))) ;; Check if next element is an anonymous result below ;; the current block. ((let* ((next (org-element-at-point)) (end (save-excursion (goto-char - (org-element-property :post-affiliated next)) + (org-element-post-affiliated next)) (line-end-position))) (empty-result-re (concat org-babel-result-regexp "$")) (case-fold-search t)) (re-search-forward empty-result-re end t)) - (beginning-of-line) + (forward-line 0) (when (org-babel--clear-results-maybe hash) (org-babel--insert-results-keyword nil hash)) (throw :found (point)))))) @@ -2177,7 +2361,7 @@ to HASH." ;; after the previous element. (when insert (save-excursion - (goto-char (min (org-element-property :end context) (point-max))) + (goto-char (min (org-element-end context) (point-max))) (skip-chars-backward " \t\n") (forward-line) (unless (bolp) (insert "\n")) @@ -2190,7 +2374,7 @@ to HASH." "Read ELEMENT into emacs-lisp. Return nil if ELEMENT cannot be read." (org-with-wide-buffer - (goto-char (org-element-property :post-affiliated element)) + (goto-char (org-element-post-affiliated element)) (pcase (org-element-type element) (`fixed-width (let ((v (org-trim (org-element-property :value element)))) @@ -2199,9 +2383,7 @@ Return nil if ELEMENT cannot be read." (`plain-list (org-babel-read-list)) ((or `example-block `src-block) (let ((v (org-element-property :value element))) - (if (or org-src-preserve-indentation - (org-element-property :preserve-indent element)) - v + (if (org-src-preserve-indentation-p element) v (org-remove-indentation v)))) (`export-block (org-remove-indentation (org-element-property :value element))) @@ -2212,24 +2394,24 @@ Return nil if ELEMENT cannot be read." (save-excursion (goto-char (match-end 0)) (skip-chars-forward " \r\t\n") - (<= (org-element-property :end element) + (<= (org-element-end element) (point)))) (org-babel-read-link) (buffer-substring-no-properties - (org-element-property :contents-begin element) - (org-element-property :contents-end element)))) + (org-element-contents-begin element) + (org-element-contents-end element)))) ((or `center-block `quote-block `verse-block `special-block) (org-remove-indentation (buffer-substring-no-properties - (org-element-property :contents-begin element) - (org-element-property :contents-end element)))) + (org-element-contents-begin element) + (org-element-contents-end element)))) (_ nil)))) (defun org-babel-read-result () "Read the result at point into emacs-lisp." (and (not (save-excursion - (beginning-of-line) - (looking-at-p "[ \t]*$"))) + (forward-line 0) + (looking-at-p "[ \t]*$"))) (org-babel-read-element (org-element-at-point)))) (defun org-babel-read-table () @@ -2269,7 +2451,9 @@ If the path of the link is a file path it is expanded using (t raw)))) (defun org-babel-format-result (result &optional sep) - "Format RESULT for writing to file." + "Format RESULT for writing to file. +When RESULT is a list, write it as a table, use tab or SEP as column +separator." (let ((echo-res (lambda (r) (if (stringp r) r (format "%S" r))))) (if (listp result) ;; table result @@ -2288,8 +2472,8 @@ the inline source block. The macro is stripped upon export. Multiline and non-scalar RESULTS from inline source blocks are not allowed. When EXEC-TIME is provided it may be included in a generated message. With optional argument RESULT-PARAMS controls -insertion of results in the Org mode file. RESULT-PARAMS can -take the following values: +insertion of results in the Org mode file. RESULT-PARAMS is a list +that can contain the following values: replace - (default option) insert results after the source block or inline source block replacing any previously @@ -2301,7 +2485,7 @@ silent -- no results are inserted into the Org buffer but process). none ---- no results are inserted into the Org buffer nor - echoed to the minibuffer. they are not processed into + 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 @@ -2348,17 +2532,19 @@ list ---- the results are rendered as a list. This option not table --- the results are rendered as a table. This option not allowed for inline source blocks. -INFO may provide the values of these header arguments (in the -`header-arguments-alist' see the docstring for -`org-babel-get-src-block-info'): +INFO is the src block info, as returned by +`org-babel-get-src-block-info' (which see). Some values from its +PARAMETERS part (header argument alist) can affect the inserted +result: -:file --- the name of the file to which output should be written. +:file-desc - when RESULT-PARAMS contains \"file\", use it as + description of the inserted link. -:wrap --- the effect is similar to `latex' in RESULT-PARAMS but - using the argument supplied to specify the export block - or snippet type." +:wrap the effect is similar to `latex' in RESULT-PARAMS but + using the argument supplied to specify the export block + or snippet type." (cond ((stringp result) - (setq result (org-no-properties result)) + (setq result (substring-no-properties result)) (when (member "file" result-params) (setq result (org-babel-result-to-file @@ -2372,12 +2558,13 @@ INFO may provide the values of these header arguments (in the (progn (message (replace-regexp-in-string "%" "%%" (format "%S" result))) result) (let ((inline (let ((context (org-element-context))) - (and (memq (org-element-type context) - '(inline-babel-call inline-src-block)) + (and (org-element-type-p + context '(inline-babel-call inline-src-block)) context)))) (when inline (let ((warning (or (and (member "table" result-params) "`:results table'") + (and (member "drawer" result-params) "`:results drawer'") (and result (listp result) "list result") (and result (string-match-p "\n." result) "multiline result") (and (member "list" result-params) "`:results list'")))) @@ -2386,10 +2573,6 @@ INFO may provide the values of these header arguments (in the (save-excursion (let* ((visible-beg (point-min-marker)) (visible-end (copy-marker (point-max) t)) - (inline (let ((context (org-element-context))) - (and (memq (org-element-type context) - '(inline-babel-call inline-src-block)) - context))) (existing-result (org-babel-where-is-src-block-result t nil hash)) (results-switches (cdr (assq :results_switches (nth 2 info)))) ;; When results exist outside of the current visible @@ -2409,7 +2592,7 @@ INFO may provide the values of these header arguments (in the (progn (when outside-scope (widen)) (if existing-result (goto-char existing-result) - (goto-char (org-element-property :end inline)) + (goto-char (org-element-end inline)) (skip-chars-backward " \t")) (unless inline (setq indent (current-indentation)) @@ -2602,25 +2785,29 @@ INFO may provide the values of these header arguments (in the (not (and (listp result) (member "append" result-params)))) (indent-rigidly beg end indent)) - (let ((time-info - ;; Only show the time when something other than - ;; 0s will be shown, i.e. check if the time is at - ;; least half of the displayed precision. - (if (and exec-time (> (float-time exec-time) 0.05)) - (format " (took %.1fs)" (float-time exec-time)) - ""))) - (if (null result) - (if (member "value" result-params) - (message "Code block returned no value%s." time-info) - (message "Code block produced no output%s." time-info)) - (message "Code block evaluation complete%s." time-info)))) + (unless noninteractive + (let ((time-info + ;; Only show the time when something other than + ;; 0s will be shown, i.e. check if the time is at + ;; least half of the displayed precision. + (if (and exec-time (> (float-time exec-time) 0.05)) + (format " (took %.1fs)" (float-time exec-time)) + ""))) + (if (null result) + (if (member "value" result-params) + (message "Code block returned no value%s." time-info) + (message "Code block produced no output%s." time-info)) + (message "Code block evaluation complete%s." time-info))))) (when end (set-marker end nil)) (when outside-scope (narrow-to-region visible-beg visible-end)) (set-marker visible-beg nil) (set-marker visible-end nil))))))) (defun org-babel-remove-result (&optional info keep-keyword) - "Remove the result of the current source block." + "Remove the result of the current source block. +INFO argument is currently ignored. +When KEEP-KEYWORD is non-nil, keep the #+RESULT keyword and just remove +the rest of the result." (interactive) (let ((location (org-babel-where-is-src-block-result nil info)) (case-fold-search t)) @@ -2636,35 +2823,35 @@ INFO may provide the values of these header arguments (in the (progn (forward-line) (org-babel-result-end)))))))) (defun org-babel-remove-inline-result (&optional datum) - "Remove the result of the current inline-src-block or babel call. + "Remove the result of DATUM or the current inline-src-block or babel call. The result must be wrapped in a `results' macro to be removed. Leading white space is trimmed." (interactive) (let* ((el (or datum (org-element-context)))) - (when (memq (org-element-type el) '(inline-src-block inline-babel-call)) + (when (org-element-type-p el '(inline-src-block inline-babel-call)) (org-with-wide-buffer - (goto-char (org-element-property :end el)) + (goto-char (org-element-end el)) (skip-chars-backward " \t") (let ((result (save-excursion (skip-chars-forward " \t\n" - (org-element-property - :contents-end (org-element-property :parent el))) + (org-element-contents-end + (org-element-parent el))) (org-element-context)))) - (when (and (eq (org-element-type result) 'macro) + (when (and (org-element-type-p result 'macro) (string= (org-element-property :key result) "results")) (delete-region ; And leading whitespace. (point) - (progn (goto-char (org-element-property :end result)) + (progn (goto-char (org-element-end result)) (skip-chars-backward " \t\n") (point))))))))) -(defun org-babel-remove-result-one-or-many (x) +(defun org-babel-remove-result-one-or-many (arg) "Remove the result of the current source block. -If called with a prefix argument, remove all result blocks -in the buffer." +If called with prefix argument ARG, remove all result blocks in the +buffer." (interactive "P") - (if x + (if arg (org-babel-map-src-blocks nil (org-babel-remove-result)) (org-babel-remove-result))) @@ -2675,14 +2862,15 @@ in the buffer." (line-beginning-position 2)) (t (let ((element (org-element-at-point))) - (if (memq (org-element-type element) - ;; Possible results types. - '(drawer example-block export-block fixed-width - special-block src-block item plain-list table - latex-environment)) + (if (org-element-type-p + element + ;; Possible results types. + '(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))) + (org-element-end element))) (skip-chars-backward " \r\t\n") (line-beginning-position 2)) (point)))))) @@ -2694,11 +2882,11 @@ file's directory then expand relative links. If the optional TYPE is passed as `attachment' and the path is a descendant of the DEFAULT-DIRECTORY, the generated link will be -specified as an an \"attachment:\" style link." +specified as an \"attachment:\" style link." (when (stringp result) (let* ((result-file-name (expand-file-name result)) (base-file-name (buffer-file-name (buffer-base-buffer))) - (base-directory (and buffer-file-name + (base-directory (and base-file-name (file-name-directory base-file-name))) (same-directory? (and base-file-name @@ -2735,7 +2923,10 @@ specified as an an \"attachment:\" style link." (if description (concat "[" description "]") ""))))) (defun org-babel-examplify-region (beg end &optional results-switches inline) - "Comment out region using the inline `==' or `: ' org example quote." + "Comment out region BEG..END using the inline `==' or `: ' org example quote. +When INLINE is non-nil, use the inline verbatim markup. +When INLINE is nil and RESULTS-SWITCHES is non-nil, RESULTS-SWITCHES is +used as a string to be appended to #+begin_example line." (interactive "*r") (let ((maybe-cap (lambda (str) @@ -2751,7 +2942,7 @@ specified as an an \"attachment:\" style link." ((< size org-babel-min-lines-for-block-output) (goto-char beg) (dotimes (_ size) - (beginning-of-line 1) (insert ": ") (forward-line 1))) + (forward-line 0) (insert ": ") (forward-line 1))) (t (goto-char beg) (insert (if results-switches @@ -2767,15 +2958,13 @@ specified as an an \"attachment:\" style link." (defun org-babel-update-block-body (new-body) "Update the body of the current code block to NEW-BODY." (let ((element (org-element-at-point))) - (unless (eq (org-element-type element) 'src-block) + (unless (org-element-type-p element 'src-block) (error "Not in a source block")) (goto-char (org-babel-where-is-src-block-head element)) (let* ((ind (org-current-text-indentation)) (body-start (line-beginning-position 2)) (body (org-element-normalize-string - (if (or org-src-preserve-indentation - (org-element-property :preserve-indent element)) - new-body + (if (org-src-preserve-indentation-p element) new-body (with-temp-buffer (insert (org-remove-indentation new-body)) (indent-rigidly @@ -2785,15 +2974,15 @@ specified as an an \"attachment:\" style link." (buffer-string)))))) (delete-region body-start (org-with-wide-buffer - (goto-char (org-element-property :end element)) + (goto-char (org-element-end element)) (skip-chars-backward " \t\n") (line-beginning-position))) (goto-char body-start) (insert body)))) -(defun org-babel-merge-params (&rest plists) - "Combine all parameter association lists in PLISTS. -Later elements of PLISTS override the values of previous elements. +(defun org-babel-merge-params (&rest alists) + "Combine all parameter association lists in ALISTS. +Later elements of ALISTS override the values of previous elements. This takes into account some special considerations for certain parameters when merging lists." (let* ((results-exclusive-groups @@ -2822,8 +3011,8 @@ parameters when merging lists." ;; Some keywords accept multiple values. We need to treat ;; them specially. vars results exports) - (dolist (plist plists) - (dolist (pair plist) + (dolist (alist alists) + (dolist (pair alist) (pcase pair (`(:var . ,value) (let ((name (cond @@ -2920,6 +3109,12 @@ See `org-babel-expand-noweb-references--cache'.") (defun org-babel-expand-noweb-references (&optional info parent-buffer) "Expand Noweb references in the body of the current source code block. +When optional argument INFO is non-nil, use the block defined by INFO +instead. + +The block is assumed to be located in PARENT-BUFFER or current buffer +\(when PARENT-BUFFER is nil). + For example the following reference would be replaced with the body of the source-code block named `example-block'. @@ -2969,47 +3164,47 @@ block but are passed literally to the \"example-block\"." (with-current-buffer parent-buffer (buffer-chars-modified-tick))))) (cl-macrolet ((c-wrap - (s) - ;; Comment string S, according to LANG mode. Return new - ;; string. - `(unless org-babel-tangle-uncomment-comments - (with-temp-buffer - (funcall (org-src-get-lang-mode lang)) - (comment-region (point) - (progn (insert ,s) (point))) - (org-trim (buffer-string))))) + (s) + ;; Comment string S, according to LANG mode. Return new + ;; string. + `(unless org-babel-tangle-uncomment-comments + (with-temp-buffer + (funcall (org-src-get-lang-mode lang)) + (comment-region (point) + (progn (insert ,s) (point))) + (org-trim (buffer-string))))) (expand-body - (i) - ;; Expand body of code represented by block info I. - `(let ((b (if (org-babel-noweb-p (nth 2 ,i) :eval) - (org-babel-expand-noweb-references ,i) - (nth 1 ,i)))) - (if (not comment) b - (let ((cs (org-babel-tangle-comment-links ,i))) - (concat (c-wrap (car cs)) "\n" - b "\n" - (c-wrap (cadr cs))))))) + (i) + ;; Expand body of code represented by block info I. + `(let ((b (if (org-babel-noweb-p (nth 2 ,i) :eval) + (org-babel-expand-noweb-references ,i) + (nth 1 ,i)))) + (if (not comment) b + (let ((cs (org-babel-tangle-comment-links ,i))) + (concat (c-wrap (car cs)) "\n" + b "\n" + (c-wrap (cadr cs)) "\n"))))) (expand-references - (ref) - `(pcase (gethash ,ref org-babel-expand-noweb-references--cache) - (`(,last . ,previous) - ;; Ignore separator for last block. - (let ((strings (list (expand-body last)))) - (dolist (i previous) - (let ((parameters (nth 2 i))) - ;; Since we're operating in reverse order, first - ;; push separator, then body. - (push (or (cdr (assq :noweb-sep parameters)) "\n") - strings) - (push (expand-body i) strings))) - (mapconcat #'identity strings ""))) - ;; Raise an error about missing reference, or return the - ;; empty string. - ((guard (or org-babel-noweb-error-all-langs - (member lang org-babel-noweb-error-langs))) - (error "Cannot resolve %s (see `org-babel-noweb-error-langs')" - (org-babel-noweb-wrap ,ref))) - (_ "")))) + (ref) + `(pcase (gethash ,ref org-babel-expand-noweb-references--cache) + (`(,last . ,previous) + ;; Ignore separator for last block. + (let ((strings (list (expand-body last)))) + (dolist (i previous) + (let ((parameters (nth 2 i))) + ;; Since we're operating in reverse order, first + ;; push separator, then body. + (push (or (cdr (assq :noweb-sep parameters)) "\n") + strings) + (push (expand-body i) strings))) + (mapconcat #'identity strings ""))) + ;; Raise an error about missing reference, or return the + ;; empty string. + ((guard (or org-babel-noweb-error-all-langs + (member lang org-babel-noweb-error-langs))) + (error "Cannot resolve %s (see `org-babel-noweb-error-langs')" + (org-babel-noweb-wrap ,ref))) + (_ "")))) (replace-regexp-in-string noweb-re (lambda (m) @@ -3193,10 +3388,22 @@ situations in which is it not appropriate." (string= cell "*this*"))) ;; FIXME: Arbitrary code evaluation. (eval (read cell) t)) - ((save-match-data - (and (string-match "^[[:space:]]*\"\\(.*\\)\"[[:space:]]*$" cell) - (not (string-match "[^\\]\"" (match-string 1 cell))))) - (read cell)) + ((let (read-val) + (and (string-match-p + (rx bos (0+ (any space ?\n)) + ?\" (0+ anychar) ?\" + (0+ (any space ?\n)) eos) + cell) + ;; CELL is a single string + (with-temp-buffer + (insert cell) + (goto-char 1) + (when (setq read-val + (ignore-errors + (read (current-buffer)))) + (skip-chars-forward "[:space:]") + (eobp))) + read-val))) (t (org-no-properties cell)))) (defun org-babel--string-to-number (string) @@ -3210,7 +3417,8 @@ Otherwise return nil." (defun org-babel-import-elisp-from-file (file-name &optional separator) "Read the results located at FILE-NAME into an elisp table. -If the table is trivial, then return it as a scalar." +If the table is trivial, then return it as a scalar. +SEPARATOR is passed to `org-table-convert-region', which see." (let ((result (with-temp-buffer (condition-case err @@ -3221,7 +3429,9 @@ If the table is trivial, then return it as a scalar." ;; If the file was empty, don't bother trying to ;; convert the table. (when (> pmax 1) - (org-table-convert-region (point-min) pmax separator) + (org-table-convert-region + (point-min) pmax + (or separator 'babel-auto)) (delq nil (mapcar (lambda (row) (and (not (eq row 'hline)) @@ -3239,7 +3449,8 @@ If the table is trivial, then return it as a scalar." (_ result)))) (defun org-babel-string-read (cell) - "Strip nested \"s from around strings." + "Strip nested \"s from around CELL string. +When CELL is not a string, return CELL." (org-babel-read (or (and (stringp cell) (string-match "^[[:space:]]*\"\\(.+\\)\"[[:space:]]*$" cell) (match-string 1 cell)) @@ -3291,7 +3502,10 @@ Emacs shutdown.") :type 'string) (defmacro org-babel-result-cond (result-params scalar-form &rest table-forms) - "Call the code to parse raw string results according to RESULT-PARAMS." + "Call the code to parse raw string results according to RESULT-PARAMS. +Do nothing with :results discard. +Execute SCALAR-FORM when result should be treated as a string. +Execute TABLE-FORMS when result should be considered sexp and parsed." (declare (indent 1) (debug t)) (org-with-gensyms (params) `(let ((,params ,result-params)) @@ -3323,8 +3537,8 @@ Emacs shutdown.") (defun org-babel-temp-file (prefix &optional suffix) "Create a temporary file in the `org-babel-temporary-directory'. Passes PREFIX and SUFFIX directly to `make-temp-file' with the -value of `temporary-file-directory' temporarily set to the value -of `org-babel-temporary-directory'." +value of function `temporary-file-directory' temporarily set to the +value of `org-babel-temporary-directory'." (make-temp-file (concat (file-name-as-directory (org-babel-temp-directory)) prefix) nil @@ -3338,13 +3552,13 @@ of `org-babel-temporary-directory'." (defun org-babel-temp-stable-file (data prefix &optional suffix) "Create a temporary file in the `org-babel-remove-temporary-stable-directory'. The file name is stable with respect to DATA. The file name is -constructed like the following: PREFIXDATAhashSUFFIX." +constructed like the following: ." (let ((path (format "%s%s%s%s" (file-name-as-directory (org-babel-temp-stable-directory)) prefix - (sxhash data) + (org-sxhash-safe data) (or suffix "")))) ;; Create file. (with-temp-file path) diff --git a/elpa/org-9.6.7/ob-css.el b/elpa/org-9.7.17/ob-css.el similarity index 94% rename from elpa/org-9.6.7/ob-css.el rename to elpa/org-9.7.17/ob-css.el index f93c576f..68f2e1f2 100644 --- a/elpa/org-9.6.7/ob-css.el +++ b/elpa/org-9.7.17/ob-css.el @@ -1,6 +1,6 @@ ;;; ob-css.el --- Babel Functions for CSS -*- lexical-binding: t; -*- -;; Copyright (C) 2009-2023 Free Software Foundation, Inc. +;; Copyright (C) 2009-2024 Free Software Foundation, Inc. ;; Author: Eric Schulte ;; Keywords: literate programming, reproducible research @@ -36,7 +36,7 @@ (defvar org-babel-default-header-args:css '()) (defun org-babel-execute:css (body _params) - "Execute a block of CSS code. + "Execute BODY of CSS code. This function is called by `org-babel-execute-src-block'." body) diff --git a/elpa/org-9.6.7/ob-ditaa.el b/elpa/org-9.7.17/ob-ditaa.el similarity index 92% rename from elpa/org-9.6.7/ob-ditaa.el rename to elpa/org-9.7.17/ob-ditaa.el index 62200082..715d8ddf 100644 --- a/elpa/org-9.6.7/ob-ditaa.el +++ b/elpa/org-9.7.17/ob-ditaa.el @@ -1,6 +1,6 @@ ;;; ob-ditaa.el --- Babel Functions for ditaa -*- lexical-binding: t; -*- -;; Copyright (C) 2009-2023 Free Software Foundation, Inc. +;; Copyright (C) 2009-2024 Free Software Foundation, Inc. ;; Author: Eric Schulte ;; Keywords: literate programming, reproducible research @@ -83,11 +83,11 @@ Do not leave leading or trailing spaces in this string." :type 'string) (defun org-babel-execute:ditaa (body params) - "Execute a block of Ditaa code with org-babel. + "Execute BODY of Ditaa code with org-babel according to PARAMS. This function is called by `org-babel-execute-src-block'." (let* ((out-file (or (cdr (assq :file params)) (error - "ditaa code block requires :file header argument"))) + "Ditaa code block requires :file header argument"))) (cmdline (cdr (assq :cmdline params))) (java (cdr (assq :java params))) (in-file (org-babel-temp-file "ditaa-")) @@ -113,8 +113,9 @@ This function is called by `org-babel-execute-src-block'." (unless (file-exists-p org-ditaa-jar-path) (error "Could not find ditaa.jar at %s" org-ditaa-jar-path)) (with-temp-file in-file (insert body)) - (message cmd) (shell-command cmd) - (when pdf-cmd (message pdf-cmd) (shell-command pdf-cmd)) + (unless noninteractive (message cmd)) + (shell-command cmd) + (when pdf-cmd (unless noninteractive (message pdf-cmd)) (shell-command pdf-cmd)) nil)) ;; signal that output has already been written to file (defun org-babel-prep-session:ditaa (_session _params) diff --git a/elpa/org-9.6.7/ob-dot.el b/elpa/org-9.7.17/ob-dot.el similarity index 88% rename from elpa/org-9.6.7/ob-dot.el rename to elpa/org-9.7.17/ob-dot.el index ecef071a..5a323951 100644 --- a/elpa/org-9.6.7/ob-dot.el +++ b/elpa/org-9.7.17/ob-dot.el @@ -1,6 +1,6 @@ ;;; ob-dot.el --- Babel Functions for dot -*- lexical-binding: t; -*- -;; Copyright (C) 2009-2023 Free Software Foundation, Inc. +;; Copyright (C) 2009-2024 Free Software Foundation, Inc. ;; Author: Eric Schulte ;; Maintainer: Justin Abrahms @@ -51,7 +51,9 @@ (defun org-babel-expand-body:dot (body params) "Expand BODY according to PARAMS, return the expanded body." - (let ((vars (org-babel--get-vars params))) + (let ((vars (org-babel--get-vars params)) + (prologue (cdr (assq :prologue params))) + (epilogue (cdr (assq :epilogue params)))) (mapc (lambda (pair) (let ((name (symbol-name (car pair))) @@ -64,10 +66,13 @@ t t)))) vars) - body)) + (concat + (and prologue (concat prologue "\n")) + body + (and epilogue (concat "\n" epilogue "\n"))))) (defun org-babel-execute:dot (body params) - "Execute a block of Dot code with org-babel. + "Execute Dot BODY with org-babel according to PARAMS. This function is called by `org-babel-execute-src-block'." (let* ((out-file (cdr (or (assq :file params) (error "You need to specify a :file parameter")))) diff --git a/elpa/org-9.6.7/ob-emacs-lisp.el b/elpa/org-9.7.17/ob-emacs-lisp.el similarity index 81% rename from elpa/org-9.6.7/ob-emacs-lisp.el rename to elpa/org-9.7.17/ob-emacs-lisp.el index f2111d64..e89bbae8 100644 --- a/elpa/org-9.6.7/ob-emacs-lisp.el +++ b/elpa/org-9.7.17/ob-emacs-lisp.el @@ -1,6 +1,6 @@ ;;; ob-emacs-lisp.el --- Babel Functions for Emacs-lisp Code -*- lexical-binding: t; -*- -;; Copyright (C) 2009-2023 Free Software Foundation, Inc. +;; Copyright (C) 2009-2024 Free Software Foundation, Inc. ;; Author: Eric Schulte ;; Keywords: literate programming, reproducible research @@ -53,18 +53,23 @@ by `org-edit-src-code'.") "Expand BODY according to PARAMS, return the expanded body." (let ((vars (org-babel--get-vars params)) (print-level nil) - (print-length nil)) + (print-length nil) + (prologue (cdr (assq :prologue params))) + (epilogue (cdr (assq :epilogue params)))) (if (null vars) (concat body "\n") - (format "(let (%s)\n%s\n)" + (format "(let (%s)\n%s%s%s\n)" (mapconcat (lambda (var) (format "%S" `(,(car var) ',(cdr var)))) vars "\n ") - body)))) + (if prologue (concat prologue "\n ") "") + body + (if epilogue (concat "\n " epilogue "\n") ""))))) (defun org-babel-execute:emacs-lisp (body params) - "Execute a block of emacs-lisp code with Babel." + "Execute emacs-lisp code BODY according to PARAMS." (let* ((lexical (cdr (assq :lexical params))) + (session (cdr (assq :session params))) (result-params (cdr (assq :result-params params))) (body (format (if (member "output" result-params) "(with-output-to-string %s\n)" @@ -75,6 +80,8 @@ by `org-edit-src-code'.") (concat "(pp " body ")") body)) (org-babel-emacs-lisp-lexical lexical)))) + (when (and session (not (equal session "none"))) + (error "ob-emacs-lisp backend does not support sessions")) (org-babel-result-cond result-params (let ((print-level nil) (print-length nil)) @@ -100,12 +107,17 @@ and the LEXICAL argument to `eval'." (defun org-babel-edit-prep:emacs-lisp (info) "Set `lexical-binding' in Org edit buffer. Set `lexical-binding' in Org edit buffer according to the -corresponding :lexical source block argument." +corresponding :lexical source block argument provide in the INFO +channel, as returned by `org-babel-get-src-block-info'." (setq lexical-binding (org-babel-emacs-lisp-lexical (org-babel-read (cdr (assq :lexical (nth 2 info))))))) +(defun org-babel-prep-session:emacs-lisp (_session _params) + "Return an error because we do not support sessions." + (error "ob-emacs-lisp backend does not support sessions")) + (org-babel-make-language-alias "elisp" "emacs-lisp") (provide 'ob-emacs-lisp) diff --git a/elpa/org-9.6.7/ob-eshell.el b/elpa/org-9.7.17/ob-eshell.el similarity index 87% rename from elpa/org-9.6.7/ob-eshell.el rename to elpa/org-9.7.17/ob-eshell.el index 95f5777a..940e5d76 100644 --- a/elpa/org-9.6.7/ob-eshell.el +++ b/elpa/org-9.7.17/ob-eshell.el @@ -1,6 +1,6 @@ ;;; ob-eshell.el --- Babel Functions for Eshell -*- lexical-binding: t; -*- -;; Copyright (C) 2018-2023 Free Software Foundation, Inc. +;; Copyright (C) 2018-2024 Free Software Foundation, Inc. ;; Author: stardiviner ;; Maintainer: stardiviner @@ -47,11 +47,12 @@ "Execute a block of Eshell code BODY with PARAMS. This function is called by `org-babel-execute-src-block'. -The BODY can be any code which allowed executed in Eshell. -Eshell allow to execute normal shell command and Elisp code. -More details please reference Eshell Info. +The BODY argument is code which can be executed in Eshell. +Eshell allows executing normal shell command and Elisp code. +For more details, see Info node `(eshell) Top'. -The PARAMS are variables assignments." +The PARAMS argument is passed to +`org-babel-expand-body:generic' (which see)." (let* ((session (org-babel-eshell-initiate-session (cdr (assq :session params)))) (full-body (org-babel-expand-body:generic @@ -94,10 +95,11 @@ The PARAMS are variables assignments." session)) (defun org-babel-variable-assignments:eshell (params) - "Convert ob-eshell :var specified variables into Eshell variables assignments." + "Convert ob-eshell variables from PARAMS into Eshell variables assignments." (mapcar (lambda (pair) - (format "(setq %s %S)" (car pair) (cdr pair))) + ;; Use `ignore' to suppress value in the command output. + (format "(ignore (setq %s %S))" (car pair) (cdr pair))) (org-babel--get-vars params))) (defun org-babel-load-session:eshell (session body params) diff --git a/elpa/org-9.6.7/ob-eval.el b/elpa/org-9.7.17/ob-eval.el similarity index 92% rename from elpa/org-9.6.7/ob-eval.el rename to elpa/org-9.7.17/ob-eval.el index 07e53077..64673938 100644 --- a/elpa/org-9.6.7/ob-eval.el +++ b/elpa/org-9.7.17/ob-eval.el @@ -1,6 +1,6 @@ ;;; ob-eval.el --- Babel Functions for External Code Evaluation -*- lexical-binding: t; -*- -;; Copyright (C) 2009-2023 Free Software Foundation, Inc. +;; Copyright (C) 2009-2024 Free Software Foundation, Inc. ;; Author: Eric Schulte ;; Keywords: literate programming, reproducible research, comint @@ -37,16 +37,21 @@ (declare-function org-babel-temp-file "ob-core" (prefix &optional suffix)) (defun org-babel-eval-error-notify (exit-code stderr) - "Open a buffer to display STDERR and a message with the value of EXIT-CODE." + "Open a buffer to display STDERR and a message with the value of EXIT-CODE. +If EXIT-CODE is nil, display the message without a code." (let ((buf (get-buffer-create org-babel-error-buffer-name))) (with-current-buffer buf (goto-char (point-max)) (save-excursion (unless (bolp) (insert "\n")) (insert stderr) - (insert (format "[ Babel evaluation exited with code %S ]" exit-code)))) + (if exit-code + (insert (format "[ Babel evaluation exited with code %S ]" exit-code)) + (insert "[ Babel evaluation exited abnormally ]")))) (display-buffer buf)) - (message "Babel evaluation exited with code %S" exit-code)) + (if exit-code + (message "Babel evaluation exited with code %S" exit-code) + (message "Babel evaluation exited abnormally"))) (defun org-babel-eval (command query) "Run COMMAND on QUERY. @@ -59,6 +64,7 @@ Writes QUERY into a temp-buffer that is processed with (let ((error-buffer (get-buffer-create " *Org-Babel Error*")) exit-code) (with-current-buffer error-buffer (erase-buffer)) (with-temp-buffer + ;; Ensure trailing newline. It is required for cmdproxy.exe. (insert query "\n") (setq exit-code (org-babel--shell-command-on-region @@ -100,11 +106,6 @@ returned." (error-file (if error-buffer (org-babel-temp-file "ob-error-") nil)) (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 - ;; workaround for now. - (unless (file-remote-p default-directory) - (delete-file error-file)) ;; we always call this with 'replace, remove conditional ;; Replace specified region with output from command. (org-babel--write-temp-buffer-input-file input-file) diff --git a/elpa/org-9.6.7/ob-exp.el b/elpa/org-9.7.17/ob-exp.el similarity index 51% rename from elpa/org-9.6.7/ob-exp.el rename to elpa/org-9.7.17/ob-exp.el index 4d1b084b..b9d5f288 100644 --- a/elpa/org-9.6.7/ob-exp.el +++ b/elpa/org-9.7.17/ob-exp.el @@ -1,6 +1,6 @@ ;;; ob-exp.el --- Exportation of Babel Source Blocks -*- lexical-binding: t; -*- -;; Copyright (C) 2009-2023 Free Software Foundation, Inc. +;; Copyright (C) 2009-2024 Free Software Foundation, Inc. ;; Authors: Eric Schulte ;; Dan Davison @@ -22,6 +22,8 @@ ;; You should have received a copy of the GNU General Public License ;; along with GNU Emacs. If not, see . +;;; Commentary: + ;;; Code: (require 'org-macs) @@ -32,8 +34,10 @@ (declare-function org-babel-lob-get-info "ob-lob" (&optional datum no-eval)) (declare-function org-element-at-point "org-element" (&optional pom cached-only)) (declare-function org-element-context "org-element" (&optional element)) -(declare-function org-element-property "org-element" (property element)) -(declare-function org-element-type "org-element" (element)) +(declare-function org-element-property "org-element-ast" (property node)) +(declare-function org-element-begin "org-element" (node)) +(declare-function org-element-end "org-element" (node)) +(declare-function org-element-type "org-element-ast" (node &optional anonymous)) (declare-function org-escape-code-in-string "org-src" (s)) (declare-function org-export-copy-buffer "ox" (&optional buffer drop-visibility @@ -41,8 +45,7 @@ drop-locals)) (declare-function org-in-commented-heading-p "org" (&optional no-inheritance element)) (declare-function org-in-archived-heading-p "org" (&optional no-inheritance element)) - -(defvar org-src-preserve-indentation) +(declare-function org-src-preserve-indentation-p "org-src" (node)) (defcustom org-export-use-babel t "Switch controlling code evaluation and header processing during export. @@ -140,217 +143,238 @@ this template." "Execute all Babel blocks in current buffer." (interactive) (when org-export-use-babel - (save-window-excursion - (let ((case-fold-search t) - (regexp "\\(call\\|src\\)_\\|^[ \t]*#\\+\\(BEGIN_SRC\\|CALL:\\)") - ;; Get a pristine copy of current buffer so Babel - ;; references are properly resolved and source block - ;; context is preserved. - (org-babel-exp-reference-buffer (org-export-copy-buffer)) - element) - (unwind-protect - (save-excursion - ;; First attach to every source block their original - ;; position, so that they can be retrieved within - ;; `org-babel-exp-reference-buffer', even after heavy - ;; modifications on current buffer. - ;; - ;; False positives are harmless, so we don't check if - ;; we're really at some Babel object. Moreover, - ;; `line-end-position' ensures that we propertize - ;; a noticeable part of the object, without affecting - ;; multiple objects on the same line. - (goto-char (point-min)) + (let ((case-fold-search t) + (regexp "\\(call\\|src\\)_\\|^[ \t]*#\\+\\(BEGIN_SRC\\|CALL:\\)") + ;; Get a pristine copy of current buffer so Babel + ;; references are properly resolved and source block + ;; context is preserved. + (org-babel-exp-reference-buffer (org-export-copy-buffer)) + element) + (unwind-protect + (save-excursion + ;; First attach to every source block their original + ;; position, so that they can be retrieved within + ;; `org-babel-exp-reference-buffer', even after heavy + ;; modifications on current buffer. + ;; + ;; False positives are harmless, so we don't check if + ;; we're really at some Babel object. Moreover, + ;; `line-end-position' ensures that we propertize + ;; a noticeable part of the object, without affecting + ;; multiple objects on the same line. + (goto-char (point-min)) + (while (re-search-forward regexp nil t) + (let ((s (match-beginning 0))) + (put-text-property s (line-end-position) 'org-reference s))) + ;; Evaluate from top to bottom every Babel block + ;; encountered. + (goto-char (point-min)) + ;; We are about to do a large number of changes in + ;; buffer, but we do not care about folding in this + ;; buffer. + (org-fold-core-ignore-modifications (while (re-search-forward regexp nil t) - (let ((s (match-beginning 0))) - (put-text-property s (line-end-position) 'org-reference s))) - ;; Evaluate from top to bottom every Babel block - ;; encountered. - (goto-char (point-min)) - ;; We are about to do a large number of changes in - ;; buffer, but we do not care about folding in this - ;; buffer. - (org-fold-core-ignore-modifications - (while (re-search-forward regexp nil t) - (setq element (org-element-at-point)) - (unless (save-match-data - (or (org-in-commented-heading-p nil element) - (org-in-archived-heading-p nil element))) - (let* ((object? (match-end 1)) - (element (save-match-data - (if object? - (org-element-context element) - ;; No deep inspection if we're - ;; just looking for an element. - element))) - (type - (pcase (org-element-type element) - ;; Discard block elements if we're looking - ;; for inline objects. False results - ;; happen when, e.g., "call_" syntax is - ;; located within affiliated keywords: - ;; - ;; #+name: call_src - ;; #+begin_src ... - ((and (or `babel-call `src-block) (guard object?)) - nil) - (type type))) - (begin - (copy-marker (org-element-property :begin element))) - (end - (copy-marker - (save-excursion - (goto-char (org-element-property :end element)) - (skip-chars-backward " \r\t\n") - (point))))) - (pcase type - (`inline-src-block - (let* ((info - (org-babel-get-src-block-info nil element)) - (params (nth 2 info))) - (setf (nth 1 info) - (if (and (cdr (assq :noweb params)) - (string= "yes" - (cdr (assq :noweb params)))) - (org-babel-expand-noweb-references - info org-babel-exp-reference-buffer) - (nth 1 info))) - (goto-char begin) - (let ((replacement - (org-babel-exp-do-export info 'inline))) - (if (equal replacement "") - ;; Replacement code is empty: remove - ;; inline source block, including extra - ;; white space that might have been - ;; created when inserting results. - (delete-region begin - (progn (goto-char end) - (skip-chars-forward " \t") - (point))) - ;; Otherwise: remove inline source block - ;; but preserve following white spaces. - ;; Then insert value. - (unless (string= replacement - (buffer-substring begin end)) - (delete-region begin end) - (insert replacement)))))) - ((or `babel-call `inline-babel-call) - (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 - `(("line" . - ,(org-element-property :value element)))))) - ;; If replacement is empty, completely remove - ;; the object/element, including any extra - ;; white space that might have been created - ;; when including results. - (if (equal rep "") - (delete-region - begin - (progn (goto-char end) - (if (not (eq type 'babel-call)) - (progn (skip-chars-forward " \t") - (point)) - (skip-chars-forward " \r\t\n") - (line-beginning-position)))) - ;; Otherwise, preserve trailing - ;; spaces/newlines and then, insert - ;; replacement string. - (goto-char begin) + (setq element (save-match-data (org-element-at-point))) + (unless (save-match-data + (or (org-in-commented-heading-p nil element) + (org-in-archived-heading-p nil element))) + (let* ((object? (match-end 1)) + (element (save-match-data + (if object? + (org-element-context element) + ;; No deep inspection if we're + ;; just looking for an element. + element))) + (type + (pcase (org-element-type element) + ;; Discard block elements if we're looking + ;; for inline objects. False results + ;; happen when, e.g., "call_" syntax is + ;; located within affiliated keywords: + ;; + ;; #+name: call_src + ;; #+begin_src ... + ((and (or `babel-call `src-block) (guard object?)) + nil) + (type type))) + (begin + (copy-marker (org-element-begin element))) + (end + (copy-marker + (save-excursion + (goto-char (org-element-end element)) + (skip-chars-backward " \r\t\n") + (point))))) + (pcase type + (`inline-src-block + (let* ((info + (org-babel-get-src-block-info nil element)) + (params (nth 2 info))) + (setf (nth 1 info) + (if (and (cdr (assq :noweb params)) + (string= "yes" + (cdr (assq :noweb params)))) + (org-babel-expand-noweb-references + info org-babel-exp-reference-buffer) + (nth 1 info))) + (goto-char begin) + (let ((replacement + (org-babel-exp-do-export info 'inline))) + (cond + ((equal replacement "") + ;; Replacement code is empty: remove + ;; inline source block, including extra + ;; white space that might have been + ;; created when inserting results. + (delete-region begin + (progn (goto-char end) + (skip-chars-forward " \t") + (point)))) + ((not replacement) + ;; Replacement code cannot be determined. + ;; Leave the code block as is. + (goto-char end)) + ;; Otherwise: remove inline source block + ;; but preserve following white spaces. + ;; Then insert value. + ((not (string= replacement + (buffer-substring begin end))) (delete-region begin end) - (insert rep)))) - (`src-block - (let ((match-start (copy-marker (match-beginning 0))) - (ind (org-current-text-indentation))) - ;; Take care of matched block: compute - ;; replacement string. In particular, a nil - ;; REPLACEMENT means the block is left as-is - ;; while an empty string removes the block. - (let ((replacement - (progn (goto-char match-start) - (org-babel-exp-src-block element)))) - (cond ((not replacement) (goto-char end)) - ((equal replacement "") - (goto-char end) + (insert replacement)) + ;; Replacement is the same as the source + ;; block. Continue onwards. + (t (goto-char end)))))) + ((or `babel-call `inline-babel-call) + (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 + `(("line" . + ,(org-element-property :value element)))))) + ;; If replacement is empty, completely remove + ;; the object/element, including any extra + ;; white space that might have been created + ;; when including results. + (cond + ((equal rep "") + (delete-region + begin + (progn (goto-char end) + (if (not (eq type 'babel-call)) + (progn (skip-chars-forward " \t") + (point)) + (unless (eobp) + (skip-chars-forward " \r\t\n") + (line-beginning-position)))))) + ((not rep) + ;; Replacement code cannot be determined. + ;; Leave the code block as is. + (goto-char end)) + (t + ;; Otherwise, preserve trailing + ;; spaces/newlines and then, insert + ;; replacement string. + (goto-char begin) + (delete-region begin end) + (insert rep))))) + (`src-block + (let ((match-start (copy-marker (match-beginning 0))) + (ind (org-current-text-indentation))) + ;; Take care of matched block: compute + ;; replacement string. In particular, a nil + ;; REPLACEMENT means the block is left as-is + ;; while an empty string removes the block. + (let ((replacement + (progn (goto-char match-start) + (org-babel-exp-src-block element)))) + (cond ((not replacement) (goto-char end)) + ((equal replacement "") + (goto-char end) + (unless (eobp) (skip-chars-forward " \r\t\n") - (beginning-of-line) - (delete-region begin (point))) - (t - (if (or org-src-preserve-indentation - (org-element-property - :preserve-indent element)) - ;; Indent only code block - ;; markers. - (with-temp-buffer - ;; Do not use tabs for block - ;; indentation. - (when (fboundp 'indent-tabs-mode) - (indent-tabs-mode -1) - ;; FIXME: Emacs 26 - ;; compatibility. - (setq-local indent-tabs-mode nil)) - (insert replacement) - (skip-chars-backward " \r\t\n") - (indent-line-to ind) - (goto-char 1) - (indent-line-to ind) - (setq replacement (buffer-string))) - ;; Indent everything. - (with-temp-buffer - ;; Do not use tabs for block - ;; indentation. - (when (fboundp 'indent-tabs-mode) - (indent-tabs-mode -1) - ;; FIXME: Emacs 26 - ;; compatibility. - (setq-local indent-tabs-mode nil)) - (insert replacement) - (indent-rigidly - 1 (point) ind) - (setq replacement (buffer-string)))) - (goto-char match-start) - (let ((rend (save-excursion - (goto-char end) - (line-end-position)))) - (if (string-equal replacement - (buffer-substring match-start rend)) - (goto-char rend) - (delete-region match-start - (save-excursion - (goto-char end) - (line-end-position))) - (insert replacement)))))) - (set-marker match-start nil)))) - (set-marker begin nil) - (set-marker end nil)))))) - (kill-buffer org-babel-exp-reference-buffer) - (remove-text-properties (point-min) (point-max) - '(org-reference nil))))))) + (forward-line 0)) + (delete-region begin (point))) + (t + (if (org-src-preserve-indentation-p element) + ;; Indent only code block + ;; markers. + (with-temp-buffer + ;; Do not use tabs for block + ;; indentation. + (when (fboundp 'indent-tabs-mode) + (indent-tabs-mode -1) + ;; FIXME: Emacs 26 + ;; compatibility. + (setq-local indent-tabs-mode nil)) + (insert replacement) + (skip-chars-backward " \r\t\n") + (indent-line-to ind) + (goto-char 1) + (indent-line-to ind) + (setq replacement (buffer-string))) + ;; Indent everything. + (with-temp-buffer + ;; Do not use tabs for block + ;; indentation. + (when (fboundp 'indent-tabs-mode) + (indent-tabs-mode -1) + ;; FIXME: Emacs 26 + ;; compatibility. + (setq-local indent-tabs-mode nil)) + (insert replacement) + (indent-rigidly + 1 (point) ind) + (setq replacement (buffer-string)))) + (goto-char match-start) + (let ((rend (save-excursion + (goto-char end) + (line-end-position)))) + (if (string-equal replacement + (buffer-substring match-start rend)) + (goto-char rend) + (delete-region match-start + (save-excursion + (goto-char end) + (line-end-position))) + (insert replacement)))))) + (set-marker match-start nil)))) + (set-marker begin nil) + (set-marker end nil)))))) + (kill-buffer org-babel-exp-reference-buffer) + (remove-text-properties (point-min) (point-max) + '(org-reference nil)))))) (defun org-babel-exp-do-export (info type &optional hash) - "Return a string with the exported content of a code block. + "Return a string with the exported content of a code block defined by INFO. +TYPE is the code block type: `block', `inline', or `lob'. HASH is the +result hash. + +Return nil when exported content cannot be determined. + 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)) ("results" (org-babel-exp-results info type nil hash) "") ("both" (org-babel-exp-results info type nil hash) - (org-babel-exp-code info type))))) + (org-babel-exp-code info type)) + (unknown-value + (warn "Unknown value of src block parameter :exports %S" unknown-value) + nil)))) (defcustom org-babel-exp-code-template - "#+begin_src %lang%switches%flags\n%body\n#+end_src" + "#+begin_src %lang%switches%header-args\n%body\n#+end_src" "Template used to export the body of code blocks. This template may be customized to include additional information such as the code block name, or the values of particular header @@ -361,17 +385,17 @@ and the following %keys may be used. name ------ the name of the code block body ------ the body of the code block switches -- the switches associated to the code block - flags ----- the flags passed to the code block + header-args the header arguments of the code block In addition to the keys mentioned above, every header argument defined for the code block may be used as a key and will be replaced with its value." :group 'org-babel :type 'string - :package-version '(Org . "9.6")) + :package-version '(Org . "9.7")) (defcustom org-babel-exp-inline-code-template - "src_%lang[%switches%flags]{%body}" + "src_%lang[%switches%header-args]{%body}" "Template used to export the body of inline code blocks. This template may be customized to include additional information such as the code block name, or the values of particular header @@ -382,18 +406,17 @@ and the following %keys may be used. name ------ the name of the code block body ------ the body of the code block switches -- the switches associated to the code block - flags ----- the flags passed to the code block + header-args the header arguments of the code block In addition to the keys mentioned above, every header argument defined for the code block may be used as a key and will be replaced with its value." :group 'org-babel :type 'string - :version "26.1" - :package-version '(Org . "8.3")) + :package-version '(Org . "9.7")) (defun org-babel-exp-code (info type) - "Return the original code block formatted for export." + "Return the original code block of TYPE defined by INFO, formatted for export." (setf (nth 1 info) (if (string= "strip-export" (cdr (assq :noweb (nth 2 info)))) (replace-regexp-in-string @@ -415,6 +438,11 @@ replaced with its value." (and (org-string-nw-p f) (concat " " f)))) ("flags" . ,(let ((f (assq :flags (nth 2 info)))) (and f (concat " " (cdr f))))) + ("header-args" + . + ,(org-babel-exp--at-source + (when-let* ((params (org-element-property :parameters (org-element-context)))) + (concat " " params)))) ,@(mapcar (lambda (pair) (cons (substring (symbol-name (car pair)) 1) (format "%S" (cdr pair)))) @@ -423,6 +451,9 @@ replaced with its value." (defun org-babel-exp-results (info type &optional silent hash) "Evaluate and return the results of the current code block for export. +INFO is as returned by `org-babel-get-src-block-info'. TYPE is the +code block type. HASH is the result hash. + Results are prepared in a manner suitable for export by Org mode. This function is called by `org-babel-exp-do-export'. The code block will be evaluated. Optional argument SILENT can be used to @@ -436,7 +467,8 @@ inhibit insertion of results into the buffer." (info (copy-sequence info)) (org-babel-current-src-block-location (point-marker))) ;; Skip code blocks which we can't evaluate. - (when (fboundp (intern (concat "org-babel-execute:" lang))) + (if (not (fboundp (intern (concat "org-babel-execute:" lang)))) + (warn "org-export: No org-babel-execute function for %s. Not updating exported results." lang) (org-babel-eval-wipe-error-buffer) (setf (nth 1 info) body) (setf (nth 2 info) diff --git a/elpa/org-9.6.7/ob-forth.el b/elpa/org-9.7.17/ob-forth.el similarity index 94% rename from elpa/org-9.6.7/ob-forth.el rename to elpa/org-9.7.17/ob-forth.el index e5dcad6d..07f00c2a 100644 --- a/elpa/org-9.6.7/ob-forth.el +++ b/elpa/org-9.7.17/ob-forth.el @@ -1,6 +1,6 @@ ;;; ob-forth.el --- Babel Functions for Forth -*- lexical-binding: t; -*- -;; Copyright (C) 2014-2023 Free Software Foundation, Inc. +;; Copyright (C) 2014-2024 Free Software Foundation, Inc. ;; Author: Eric Schulte ;; Keywords: literate programming, reproducible research, forth @@ -45,7 +45,7 @@ "Default header arguments for forth code blocks.") (defun org-babel-execute:forth (body params) - "Execute a block of Forth code with org-babel. + "Execute Forth BODY according to PARAMS. This function is called by `org-babel-execute-src-block'." (if (string= "none" (cdr (assq :session params))) (error "Non-session evaluation not supported for Forth code blocks") @@ -55,7 +55,8 @@ This function is called by `org-babel-execute-src-block'." (car (last all-results)))))) (defun org-babel-forth-session-execute (body params) - (require 'forth-mode) + "Execute Forth BODY in session defined via PARAMS." + (org-require-package 'forth-mode) (let ((proc (forth-proc)) (rx " \\(\n:\\|compiled\n\\|ok\n\\)") (result-start)) diff --git a/elpa/org-9.6.7/ob-fortran.el b/elpa/org-9.7.17/ob-fortran.el similarity index 83% rename from elpa/org-9.6.7/ob-fortran.el rename to elpa/org-9.7.17/ob-fortran.el index 2c050cb1..f2047d76 100644 --- a/elpa/org-9.6.7/ob-fortran.el +++ b/elpa/org-9.7.17/ob-fortran.el @@ -1,6 +1,6 @@ ;;; ob-fortran.el --- Babel Functions for Fortran -*- lexical-binding: t; -*- -;; Copyright (C) 2011-2023 Free Software Foundation, Inc. +;; Copyright (C) 2011-2024 Free Software Foundation, Inc. ;; Authors: Sergey Litvinov ;; Eric Schulte @@ -51,7 +51,8 @@ :type 'string) (defun org-babel-execute:fortran (body params) - "This function should only be called by `org-babel-execute:fortran'." + "Execute Fortran BODY according to PARAMS. +This function is called by `org-babel-execute-src-block'." (let* ((tmp-src-file (org-babel-temp-file "fortran-src-" ".F90")) (tmp-bin-file (org-babel-temp-file "fortran-bin-" org-babel-exeext)) (cmdline (cdr (assq :cmdline params))) @@ -82,9 +83,10 @@ (cdr (assq :rowname-names params)) (cdr (assq :rownames params))))))) (defun org-babel-expand-body:fortran (body params) - "Expand a block of fortran or fortran code with org-babel according to -its header arguments." + "Expand a fortran BODY according to its header arguments defined in PARAMS." (let ((vars (org-babel--get-vars params)) + (prologue (cdr (assq :prologue params))) + (epilogue (cdr (assq :epilogue params))) (main-p (not (string= (cdr (assq :main params)) "no"))) (includes (or (cdr (assq :includes params)) (org-babel-read (org-entry-get nil "includes" t)))) @@ -107,12 +109,20 @@ its header arguments." (concat ;; variables (mapconcat 'org-babel-fortran-var-to-fortran vars "\n") - body) + (and prologue (concat prologue "\n")) + body + (and prologue (concat prologue "\n"))) params) - body) "\n") "\n"))) + (concat + (and prologue (concat prologue "\n")) + body + (and epilogue (concat "\n" epilogue "\n")))) + "\n") + "\n"))) (defun org-babel-fortran-ensure-main-wrap (body params) - "Wrap body in a \"program ... end program\" block if none exists." + "Wrap BODY in a \"program ... end program\" block if none exists. +Variable assignments are derived from PARAMS." (if (string-match "^[ \t]*program\\>" (capitalize body)) (let ((vars (org-babel--get-vars params))) (when vars (error "Cannot use :vars if `program' statement is present")) @@ -120,20 +130,22 @@ its header arguments." (format "program main\n%s\nend program main\n" body))) (defun org-babel-prep-session:fortran (_session _params) - "This function does nothing as fortran is a compiled language with no + "Do nothing. +This function does nothing as fortran is a compiled language with no support for sessions." (error "Fortran is a compiled languages -- no support for sessions")) (defun org-babel-load-session:fortran (_session _body _params) - "This function does nothing as fortran is a compiled language with no + "Do nothing. +This function does nothing as fortran is a compiled language with no support for sessions." (error "Fortran is a compiled languages -- no support for sessions")) ;; helper functions (defun org-babel-fortran-var-to-fortran (pair) - "Convert an elisp val into a string of fortran code specifying a var -of the same value." + "Convert PAIR of (VAR . VAL) into a string of fortran code. +The fortran code will assign VAL to VAR variable." ;; TODO list support (let ((var (car pair)) (val (cdr pair))) @@ -164,7 +176,7 @@ of the same value." (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." + "Return a fortran representation of enclose syntactic list VAL." (if (listp val) (concat "(/" (mapconcat #'org-babel-fortran-transform-list val ", ") "/)") (format "%S" val))) diff --git a/elpa/org-9.6.7/ob-gnuplot.el b/elpa/org-9.7.17/ob-gnuplot.el similarity index 86% rename from elpa/org-9.6.7/ob-gnuplot.el rename to elpa/org-9.7.17/ob-gnuplot.el index e3e42918..10192cb9 100644 --- a/elpa/org-9.6.7/ob-gnuplot.el +++ b/elpa/org-9.7.17/ob-gnuplot.el @@ -1,9 +1,9 @@ ;;; ob-gnuplot.el --- Babel Functions for Gnuplot -*- lexical-binding: t; -*- -;; Copyright (C) 2009-2023 Free Software Foundation, Inc. +;; Copyright (C) 2009-2024 Free Software Foundation, Inc. ;; Author: Eric Schulte -;; Maintainer: Ihor Radchenko +;; Maintainer: Ihor Radchenko ;; Keywords: literate programming, reproducible research ;; URL: https://orgmode.org @@ -186,7 +186,7 @@ code." ;; value of the variable (mapc (lambda (pair) (setq body (replace-regexp-in-string - (format "\\$%s" (car pair)) (cdr pair) body))) + (format "\\$%s" (car pair)) (cdr pair) body t t))) vars) (when prologue (funcall add-to-body prologue)) (when epilogue (setq body (concat body "\n" epilogue))) @@ -196,9 +196,9 @@ code." body)) (defun org-babel-execute:gnuplot (body params) - "Execute a block of Gnuplot code. + "Execute Gnuplot BODY according to PARAMS. This function is called by `org-babel-execute-src-block'." - (require 'gnuplot) + (org-require-package 'gnuplot) (let ((session (cdr (assq :session params))) (result-type (cdr (assq :results params))) (body (org-babel-expand-body:gnuplot body params)) @@ -209,7 +209,7 @@ This function is called by `org-babel-execute-src-block'." (let ((script-file (org-babel-temp-file "gnuplot-script-"))) (with-temp-file script-file (insert (concat body "\n"))) - (message "gnuplot \"%s\"" script-file) + (unless noninteractive (message "gnuplot \"%s\"" script-file)) (setq output (shell-command-to-string (format @@ -218,7 +218,7 @@ This function is called by `org-babel-execute-src-block'." script-file (if (member system-type '(cygwin windows-nt ms-dos)) t nil))))) - (message "%s" output)) + (unless noninteractive (message "%s" output))) (with-temp-buffer (insert (concat body "\n")) (gnuplot-mode) @@ -231,7 +231,7 @@ This function is called by `org-babel-execute-src-block'." "Prepare SESSION according to the header arguments in PARAMS." (let* ((session (org-babel-gnuplot-initiate-session session)) (var-lines (org-babel-variable-assignments:gnuplot params))) - (message "%S" session) + (unless noninteractive (message "%S" session)) (org-babel-comint-in-buffer session (dolist (var-line var-lines) (insert var-line) @@ -251,7 +251,8 @@ This function is called by `org-babel-execute-src-block'." buffer))) (defun org-babel-variable-assignments:gnuplot (params) - "Return list of gnuplot statements assigning the block's variables." + "Return list of gnuplot statements assigning the block's variables. +PARAMS is src block parameters alist defining variable assignments." (mapcar (lambda (pair) (format "%s = \"%s\"" (car pair) (cdr pair))) (org-babel-gnuplot-process-vars params))) @@ -262,7 +263,7 @@ This function is called by `org-babel-execute-src-block'." If there is not a current inferior-process-buffer in SESSION then create one. Return the initialized session. The current `gnuplot-mode' doesn't provide support for multiple sessions." - (require 'gnuplot) + (org-require-package 'gnuplot) (unless (string= session "none") (save-window-excursion (gnuplot-send-string-to-gnuplot "" "line") @@ -293,16 +294,33 @@ then create one. Return the initialized session. The current "Export TABLE to DATA-FILE in a format readable by gnuplot. Pass PARAMS through to `orgtbl-to-generic' when exporting TABLE." (require 'ox-org) + (require 'ox-ascii) + (declare-function org-export-create-backend "ox") (with-temp-file data-file (insert (let ((org-babel-gnuplot-timestamp-fmt - (or (plist-get params :timefmt) "%Y-%m-%d-%H:%M:%S"))) + (or (plist-get params :timefmt) "%Y-%m-%d-%H:%M:%S")) + ;; Create custom limited backend that will disable + ;; advanced ASCII export features that may alter the + ;; original data. + (ob-gnuplot-data + (org-export-create-backend + :parent 'ascii + :transcoders + `(;; Do not try to resolve links. Export them verbatim. + (link . (lambda (link _ _) (org-element-interpret-data link))) + ;; Drop emphasis markers from verbatim and code. + ;; This way, data can use verbatim when escaping + ;; is necessary and yet be readable by Gnuplot, + ;; which is not aware about Org's markup. + (verbatim . (lambda (verbatim _ _) (org-element-property :value verbatim))) + (code . (lambda (code _ _) (org-element-property :value code))))))) (orgtbl-to-generic table (org-combine-plists - '( :sep "\t" :fmt org-babel-gnuplot-quote-tsv-field + `( :sep "\t" :fmt org-babel-gnuplot-quote-tsv-field ;; Two setting below are needed to make :fmt work. :raw t - :backend ascii) + :backend ,ob-gnuplot-data) params))))) data-file) diff --git a/elpa/org-9.6.7/ob-groovy.el b/elpa/org-9.7.17/ob-groovy.el similarity index 92% rename from elpa/org-9.6.7/ob-groovy.el rename to elpa/org-9.7.17/ob-groovy.el index c0da69fc..d87ef4bb 100644 --- a/elpa/org-9.6.7/ob-groovy.el +++ b/elpa/org-9.7.17/ob-groovy.el @@ -1,6 +1,6 @@ ;;; ob-groovy.el --- Babel Functions for Groovy -*- lexical-binding: t; -*- -;; Copyright (C) 2013-2023 Free Software Foundation, Inc. +;; Copyright (C) 2013-2024 Free Software Foundation, Inc. ;; Author: Miro Bezjak ;; Maintainer: Palak Mathur @@ -50,9 +50,9 @@ parameters may be used, like groovy -v" :type 'string) (defun org-babel-execute:groovy (body params) - "Execute a block of Groovy code with org-babel. + "Execute Groovy BODY according to PARAMS. This function is called by `org-babel-execute-src-block'." - (message "Executing Groovy source code block") + (unless noninteractive (message "Executing Groovy source code block")) (let* ((processed-params (org-babel-process-params params)) (session (org-babel-groovy-initiate-session (nth 0 processed-params))) (result-params (nth 2 processed-params)) @@ -81,6 +81,7 @@ println(new Runner().run()) (defun org-babel-groovy-evaluate (session body &optional result-type result-params) "Evaluate BODY in external Groovy process. +SESSION must be nil as sessions are not yet supported. 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." @@ -107,9 +108,8 @@ in BODY as elisp." (error "Sessions are not (yet) supported for Groovy")) (defun org-babel-groovy-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 Groovy." + "Do nothing. +Sessions are not supported in Groovy." nil) (provide 'ob-groovy) diff --git a/elpa/org-9.6.7/ob-haskell.el b/elpa/org-9.7.17/ob-haskell.el similarity index 52% rename from elpa/org-9.6.7/ob-haskell.el rename to elpa/org-9.7.17/ob-haskell.el index 7185ed61..05f340fa 100644 --- a/elpa/org-9.6.7/ob-haskell.el +++ b/elpa/org-9.7.17/ob-haskell.el @@ -1,6 +1,6 @@ ;;; ob-haskell.el --- Babel Functions for Haskell -*- lexical-binding: t; -*- -;; Copyright (C) 2009-2023 Free Software Foundation, Inc. +;; Copyright (C) 2009-2024 Free Software Foundation, Inc. ;; Author: Eric Schulte ;; Maintainer: Lawrence Bottorff @@ -61,7 +61,7 @@ (defvar org-babel-haskell-lhs2tex-command "lhs2tex") -(defvar org-babel-haskell-eoe "\"org-babel-haskell-eoe\"") +(defvar org-babel-haskell-eoe "org-babel-haskell-eoe") (defvar haskell-prompt-regexp) @@ -77,8 +77,35 @@ a parameter, such as \"ghc -v\"." (defconst org-babel-header-args:haskell '((compile . :any)) "Haskell-specific header arguments.") + +(defun org-babel-haskell-with-session--worker (params todo) + "See `org-babel-haskell-with-session'." + (let* ((sn (cdr (assq :session params))) + (session (org-babel-haskell-initiate-session sn params)) + (one-shot (equal sn "none"))) + (unwind-protect + (funcall todo session) + (when (and one-shot (buffer-live-p session)) + ;; As we don't control how the session temporary buffer is + ;; created, we need to explicitly work around the hooks and + ;; query functions. + (with-current-buffer session + (let ((kill-buffer-query-functions nil) + (kill-buffer-hook nil)) + (kill-buffer session))))))) + +(defmacro org-babel-haskell-with-session (session-symbol params &rest body) + "Get the session identified by PARAMS and run BODY with it. + +Get or create a session, as needed to match PARAMS. Assign the session to +SESSION-SYMBOL. Execute BODY. Destroy the session if needed. +Return the value of the last form of BODY." + (declare (indent 2) (debug (symbolp form body))) + `(org-babel-haskell-with-session--worker ,params (lambda (,session-symbol) ,@body))) + (defun org-babel-haskell-execute (body params) - "This function should only be called by `org-babel-execute:haskell'." + "Execute Haskell BODY according to PARAMS. +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 @@ -122,39 +149,63 @@ a parameter, such as \"ghc -v\"." (cdr (assq :rowname-names params)) (cdr (assq :rownames params)))))))) (defun org-babel-interpret-haskell (body params) - (require 'inf-haskell) + (org-require-package 'inf-haskell "haskell-mode") (add-hook 'inferior-haskell-hook (lambda () - (setq-local comint-prompt-regexp - (concat haskell-prompt-regexp "\\|^λ?> ")))) - (let* ((session (cdr (assq :session params))) - (result-type (cdr (assq :result-type params))) - (full-body (org-babel-expand-body:generic - body params - (org-babel-variable-assignments:haskell params))) - (session (org-babel-haskell-initiate-session session params)) - (comint-preoutput-filter-functions - (cons 'ansi-color-filter-apply comint-preoutput-filter-functions)) - (raw (org-babel-comint-with-output - (session org-babel-haskell-eoe nil full-body) - (insert (org-trim full-body)) - (comint-send-input nil t) - (insert org-babel-haskell-eoe) - (comint-send-input nil t))) - (results (mapcar #'org-strip-quotes - (cdr (member org-babel-haskell-eoe - (reverse (mapcar #'org-trim raw))))))) - (org-babel-reassemble-table - (let ((result - (pcase result-type - (`output (mapconcat #'identity (reverse results) "\n")) - (`value (car results))))) - (org-babel-result-cond (cdr (assq :result-params params)) - result (when result (org-babel-script-escape result)))) - (org-babel-pick-name (cdr (assq :colname-names params)) - (cdr (assq :colname-names params))) - (org-babel-pick-name (cdr (assq :rowname-names params)) - (cdr (assq :rowname-names params)))))) + (setq-local + org-babel-comint-prompt-regexp-old comint-prompt-regexp + comint-prompt-regexp + (concat haskell-prompt-regexp "\\|^λ?> ")))) + (org-babel-haskell-with-session session params + (cl-labels + ((send-txt-to-ghci (txt) + (insert txt) (comint-send-input nil t)) + (send-eoe () + (send-txt-to-ghci (concat "putStrLn \"" org-babel-haskell-eoe "\"\n"))) + (comint-with-output (todo) + (let ((comint-preoutput-filter-functions + (cons 'ansi-color-filter-apply + comint-preoutput-filter-functions))) + (org-babel-comint-with-output + (session org-babel-haskell-eoe nil nil) + (funcall todo))))) + (let* ((result-type (cdr (assq :result-type params))) + (full-body (org-babel-expand-body:generic + body params + (org-babel-variable-assignments:haskell params))) + (raw (pcase result-type + (`output + (comint-with-output + (lambda () (send-txt-to-ghci (org-trim full-body)) (send-eoe)))) + (`value + ;; We first compute the value and store it, + ;; ignoring any output. + (comint-with-output + (lambda () + (send-txt-to-ghci "__LAST_VALUE_IMPROBABLE_NAME__=()::()\n") + (send-txt-to-ghci (org-trim full-body)) + (send-txt-to-ghci "__LAST_VALUE_IMPROBABLE_NAME__=it\n") + (send-eoe))) + ;; We now display and capture the value. + (comint-with-output + (lambda() + (send-txt-to-ghci "__LAST_VALUE_IMPROBABLE_NAME__\n") + (send-eoe)))))) + (results (mapcar #'org-strip-quotes + (cdr (member org-babel-haskell-eoe + (reverse (mapcar #'org-trim raw))))))) + (org-babel-reassemble-table + (let ((result + (pcase result-type + (`output (mapconcat #'identity (reverse results) "\n")) + (`value (car results))))) + (org-babel-result-cond (cdr (assq :result-params params)) + result (when result (org-babel-script-escape result)))) + (org-babel-pick-name (cdr (assq :colname-names params)) + (cdr (assq :colname-names params))) + (org-babel-pick-name (cdr (assq :rowname-names params)) + (cdr (assq :rowname-names params)))))))) + (defun org-babel-execute:haskell (body params) "Execute a block of Haskell code." @@ -163,13 +214,65 @@ a parameter, such as \"ghc -v\"." (org-babel-interpret-haskell body params) (org-babel-haskell-execute body params)))) -(defun org-babel-haskell-initiate-session (&optional _session _params) + + + +;; Variable defined in inf-haskell (haskell-mode package). +(defvar inferior-haskell-buffer) +(defvar inferior-haskell-root-dir) + +(defun org-babel-haskell-initiate-session (&optional session-name _params) "Initiate a haskell session. -If there is not a current inferior-process-buffer in SESSION -then create one. Return the initialized session." - (require 'inf-haskell) - (or (get-buffer "*haskell*") - (save-window-excursion (run-haskell) (sleep-for 0.25) (current-buffer)))) +Return the initialized session, i.e. the buffer for this session. +When SESSION-NAME is nil, use a global session named +\"*ob-haskell*\". When SESSION-NAME is the string \"none\", use +a temporary buffer. Else, (re)use the session named +SESSION-NAME. The buffer name is the session name. See also +`org-babel-haskell-with-session'." + (org-require-package 'inf-haskell "haskell-mode") + (cond + ((equal "none" session-name) + ;; Temporary buffer name. + (setq session-name (generate-new-buffer-name " *ob-haskell-tmp*"))) + ((eq nil session-name) + ;; The global default session. As haskell-mode is using the buffer + ;; named "*haskell*", we stay away from it. + (setq session-name "*ob-haskell*")) + ((not (stringp session-name)) + (error "session-name must be a string"))) + (let ((session (get-buffer session-name))) + ;; NOTE: By construction, as SESSION-NAME is a string, session is + ;; either nil or a live buffer. + (save-window-excursion + (or (org-babel-comint-buffer-livep session) + (let ((inferior-haskell-buffer session)) + ;; As inferior-haskell expects the buffer to be named + ;; "*haskell*", we temporarily rename it while executing + ;; `run-haskell' (unless the user explicitly requested to + ;; use the name "*haskell*"). + (when (not (equal "*haskell*" session-name)) + (when (bufferp session) + (when (bufferp "*haskell*") + (user-error "Conflicting buffer '*haskell*', rename it or kill it")) + (with-current-buffer session (rename-buffer "*haskell*")))) + (unwind-protect + (let ((inferior-haskell-root-dir default-directory)) + (run-haskell) + (sleep-for 0.25) + (setq session inferior-haskell-buffer)) + (when (and (not (equal "*haskell*" session-name)) + (bufferp session)) + (with-current-buffer session (rename-buffer session-name)))) + ;; Disable secondary prompt: If we do not do this, + ;; org-comint may treat secondary prompts as a part of + ;; output. + (org-babel-comint-input-command + session + ":set prompt-cont \"\"") + session) + )) + session)) + (defun org-babel-load-session:haskell (session body params) "Load BODY into SESSION." @@ -226,7 +329,7 @@ constructs (header arguments, no-web syntax etc...) are ignored." (let* ((contents (buffer-string)) (haskell-regexp (concat "^\\([ \t]*\\)#\\+begin_src[ \t]haskell*\\(.*\\)[\r\n]" - "\\([^\000]*?\\)[\r\n][ \t]*#\\+end_src.*")) + "\\(\\(?:.\\|\n\\)*?\\)[\r\n][ \t]*#\\+end_src.*")) (base-name (file-name-sans-extension (buffer-file-name))) (tmp-file (org-babel-temp-file "haskell-")) (tmp-org-file (concat tmp-file ".org")) @@ -255,26 +358,27 @@ constructs (header arguments, no-web syntax etc...) are ignored." t t) (indent-code-rigidly (match-beginning 0) (match-end 0) indentation))) (save-excursion - ;; export to latex w/org and save as .lhs - (require 'ox-latex) - (find-file tmp-org-file) - ;; Ensure we do not clutter kill ring with incomplete results. - (let (org-export-copy-to-kill-ring) - (org-export-to-file 'latex tmp-tex-file)) - (kill-buffer nil) - (delete-file tmp-org-file) - (find-file tmp-tex-file) - (goto-char (point-min)) (forward-line 2) - (insert "%include polycode.fmt\n") - ;; ensure all \begin/end{code} statements start at the first column - (while (re-search-forward "^[ \t]+\\\\begin{code}[^\000]+\\\\end{code}" nil t) - (replace-match (save-match-data (org-remove-indentation (match-string 0))) - t t)) - (setq contents (buffer-string)) - (save-buffer) (kill-buffer nil)) - (delete-file tmp-tex-file) - ;; save org exported latex to a .lhs file - (with-temp-file lhs-file (insert contents)) + (unwind-protect + (with-temp-buffer + ;; Export to latex w/org and save as .lhs + (require 'ox-latex) + (insert-file-contents tmp-org-file) + ;; Ensure we do not clutter kill ring with incomplete results. + (let (org-export-copy-to-kill-ring) + (org-export-to-file 'latex tmp-tex-file))) + (delete-file tmp-org-file)) + (unwind-protect + (with-temp-buffer + (insert-file-contents tmp-tex-file) + (goto-char (point-min)) (forward-line 2) + (insert "%include polycode.fmt\n") + ;; ensure all \begin/end{code} statements start at the first column + (while (re-search-forward "^[ \t]+\\\\begin{code}\\(?:.\\|\n\\)+\\\\end{code}" nil t) + (replace-match (save-match-data (org-remove-indentation (match-string 0))) + t t)) + ;; save org exported latex to a .lhs file + (write-region nil nil lhs-file)) + (delete-file tmp-tex-file))) (if (not arg) (find-file lhs-file) ;; process .lhs file with lhs2tex diff --git a/elpa/org-9.6.7/ob-java.el b/elpa/org-9.7.17/ob-java.el similarity index 98% rename from elpa/org-9.6.7/ob-java.el rename to elpa/org-9.7.17/ob-java.el index 89386052..fd620635 100644 --- a/elpa/org-9.6.7/ob-java.el +++ b/elpa/org-9.7.17/ob-java.el @@ -1,6 +1,6 @@ ;;; ob-java.el --- org-babel functions for java evaluation -*- lexical-binding: t -*- -;; Copyright (C) 2011-2023 Free Software Foundation, Inc. +;; Copyright (C) 2011-2024 Free Software Foundation, Inc. ;; Authors: Eric Schulte ;; Dan Davison @@ -341,9 +341,13 @@ is simplest to expand the code block from the inside out." (imports-val (assq :imports params)) (imports (if imports-val (split-string (org-babel-read (cdr imports-val) nil) " ") - nil))) + nil)) + (prologue (cdr (assq :prologue params))) + (epilogue (cdr (assq :epilogue params)))) (with-temp-buffer + (when prologue (insert prologue "\n")) (insert body) + (when epilogue (insert "\n" epilogue)) ;; wrap main. If there are methods defined, but no main method ;; and no class, wrap everything in a generic main method. diff --git a/elpa/org-9.6.7/ob-js.el b/elpa/org-9.7.17/ob-js.el similarity index 93% rename from elpa/org-9.6.7/ob-js.el rename to elpa/org-9.7.17/ob-js.el index de7ea913..451a92eb 100644 --- a/elpa/org-9.6.7/ob-js.el +++ b/elpa/org-9.7.17/ob-js.el @@ -1,6 +1,6 @@ ;;; ob-js.el --- Babel Functions for Javascript -*- lexical-binding: t; -*- -;; Copyright (C) 2010-2023 Free Software Foundation, Inc. +;; Copyright (C) 2010-2024 Free Software Foundation, Inc. ;; Author: Eric Schulte ;; Keywords: literate programming, reproducible research, js @@ -76,7 +76,7 @@ "Javascript code to print value of body.") (defun org-babel-execute:js (body params) - "Execute a block of Javascript code with org-babel. + "Execute Javascript BODY according to PARAMS. This function is called by `org-babel-execute-src-block'." (let* ((org-babel-js-cmd (or (cdr (assq :cmd params)) org-babel-js-cmd)) (session (cdr (assq :session params))) @@ -99,7 +99,7 @@ This function is called by `org-babel-execute-src-block'." ;; Indium Node REPL. Separate case because Indium ;; REPL is not inherited from Comint mode. ((string= session "*JS REPL*") - (require 'indium-repl) + (org-require-package 'indium-repl "indium") (unless (get-buffer session) (indium-run-node org-babel-js-cmd)) (indium-eval full-body)) @@ -158,7 +158,8 @@ specifying a variable of the same value." session)) (defun org-babel-variable-assignments:js (params) - "Return list of Javascript statements assigning the block's variables." + "Return list of Javascript statements assigning the block's variables. +The variables are defined in PARAMS." (mapcar (lambda (pair) (format "var %s=%s;" (car pair) (org-babel-js-var-to-js (cdr pair)))) @@ -171,7 +172,7 @@ Return the initialized session." ((string= session "none") (warn "Session evaluation of ob-js is not supported")) ((string= "*skewer-repl*" session) - (require 'skewer-repl) + (org-require-package 'skewer-repl "skewer-mode") (let ((session-buffer (get-buffer "*skewer-repl*"))) (if (and session-buffer (org-babel-comint-buffer-livep (get-buffer session-buffer)) @@ -183,7 +184,7 @@ Return the initialized session." (skewer-repl) session-buffer))) ((string= "*Javascript REPL*" session) - (require 'js-comint) + (org-require-package 'js-comint) (let ((session-buffer "*Javascript REPL*")) (if (and (org-babel-comint-buffer-livep (get-buffer session-buffer)) (comint-check-proc session-buffer)) @@ -192,7 +193,9 @@ Return the initialized session." (sit-for .5) session-buffer))) ((string= "mozrepl" org-babel-js-cmd) - (require 'moz) + ;; FIXME: According to https://github.com/bard/mozrepl, this REPL + ;; is outdated and does not work for Firefox >54. + (org-require-package 'moz "mozrepl") (let ((session-buffer (save-window-excursion (run-mozilla nil) (rename-buffer session) diff --git a/elpa/org-9.6.7/ob-julia.el b/elpa/org-9.7.17/ob-julia.el similarity index 92% rename from elpa/org-9.6.7/ob-julia.el rename to elpa/org-9.7.17/ob-julia.el index cb5c7fa3..224a8ec7 100644 --- a/elpa/org-9.6.7/ob-julia.el +++ b/elpa/org-9.7.17/ob-julia.el @@ -1,6 +1,6 @@ ;;; ob-julia.el --- org-babel functions for julia code evaluation -*- lexical-binding: t; -*- -;; Copyright (C) 2013-2023 Free Software Foundation, Inc. +;; Copyright (C) 2013-2024 Free Software Foundation, Inc. ;; Authors: G. Jay Kerns ;; Maintainer: Pedro Bruel ;; Keywords: literate programming, reproducible research, scientific computing @@ -70,12 +70,15 @@ (defvar ess-local-process-name) ; dynamically scoped (defvar ess-eval-visibly-p) ; dynamically scoped (defvar ess-local-customize-alist); dynamically scoped -(defun org-babel-edit-prep:julia (info) - (let ((session (cdr (assq :session (nth 2 info))))) - (when (and session - (string-prefix-p "*" session) - (string-suffix-p "*" session)) - (org-babel-julia-initiate-session session nil)))) +(defvar ess-gen-proc-buffer-name-function) ; defined in ess-inf.el +(defun org-babel-julia-associate-session (session) + "Associate R code buffer with an R session. +Make SESSION be the inferior ESS process associated with the +current code buffer." + (when-let* ((process (get-buffer-process session))) + (setq ess-local-process-name (process-name process)) + (ess-make-buffer-current)) + (setq-local ess-gen-proc-buffer-name-function (lambda (_) session))) (defun org-babel-expand-body:julia (body params &optional _graphics-file) "Expand BODY according to PARAMS, return the expanded body." @@ -181,10 +184,13 @@ end" (defun org-babel-julia-initiate-session (session params) "If there is not a current julia process then create one." (unless (string= session "none") - (let ((session (or session "*Julia*")) - (ess-ask-for-ess-directory - (and (bound-and-true-p ess-ask-for-ess-directory) - (not (cdr (assq :dir params)))))) + (let* ((session (or session "*Julia*")) + (ess-ask-for-ess-directory + (and (bound-and-true-p ess-ask-for-ess-directory) + (not (cdr (assq :dir params))))) + ;; Make ESS name the process buffer as SESSION. + (ess-gen-proc-buffer-name-function + (lambda (_) session))) (if (org-babel-comint-buffer-livep session) session ;; FIXME: Depending on `display-buffer-alist', (julia) may end up @@ -196,13 +202,8 @@ end" (when (get-buffer session) ;; Session buffer exists, but with dead process (set-buffer session)) - (require 'ess) (set-buffer (julia)) - (rename-buffer - (if (bufferp session) - (buffer-name session) - (if (stringp session) - session - (buffer-name)))) + (org-require-package 'ess "ESS") + (set-buffer (julia)) (current-buffer)))))) (defun org-babel-julia-graphical-output-file (params) diff --git a/elpa/org-9.6.7/ob-latex.el b/elpa/org-9.7.17/ob-latex.el similarity index 89% rename from elpa/org-9.6.7/ob-latex.el rename to elpa/org-9.7.17/ob-latex.el index ce39628d..58051fae 100644 --- a/elpa/org-9.6.7/ob-latex.el +++ b/elpa/org-9.7.17/ob-latex.el @@ -1,6 +1,6 @@ ;;; ob-latex.el --- Babel Functions for LaTeX -*- lexical-binding: t; -*- -;; Copyright (C) 2009-2023 Free Software Foundation, Inc. +;; Copyright (C) 2009-2024 Free Software Foundation, Inc. ;; Author: Eric Schulte ;; Keywords: literate programming, reproducible research @@ -52,6 +52,7 @@ (defvar org-format-latex-options) ; From org.el (defvar org-latex-default-packages-alist) ; From org.el (defvar org-latex-packages-alist) ; From org.el +(defvar org-preview-latex-process-alist) ; From org.el (defvar org-babel-default-header-args:latex '((:results . "latex") (:exports . "results")) @@ -128,6 +129,18 @@ exporting the literal LaTeX source." :group 'org-babel :type '(repeat (string))) +(defcustom org-babel-latex-process-alist + `(,(cons 'png (alist-get 'dvipng org-preview-latex-process-alist))) + "Definitions of external processes for LaTeX result generation. +See `org-preview-latex-process-alist' for more details. + +The following process symbols are recognized: +- `png' :: Process used to produce .png output." + :group 'org-babel + :package-version '(Org . "9.7") + :type '(alist :tag "LaTeX to image backends" + :value-type (plist))) + (defun org-babel-expand-body:latex (body params) "Expand BODY according to PARAMS, return the expanded body." (mapc (lambda (pair) ;; replace variables @@ -136,12 +149,18 @@ exporting the literal LaTeX source." (regexp-quote (format "%S" (car pair))) (if (stringp (cdr pair)) (cdr pair) (format "%S" (cdr pair))) - body))) + body t t))) (org-babel--get-vars params)) - (org-trim body)) + (let ((prologue (cdr (assq :prologue params))) + (epilogue (cdr (assq :epilogue params)))) + (org-trim + (concat + (and prologue (concat prologue "\n")) + body + (and epilogue (concat "\n" epilogue "\n")))))) (defun org-babel-execute:latex (body params) - "Execute a block of LaTeX code with Babel. + "Execute LaTeX BODY according to PARAMS. This function is called by `org-babel-execute-src-block'." (setq body (org-babel-expand-body:latex body params)) (if (cdr (assq :file params)) @@ -163,9 +182,10 @@ This function is called by `org-babel-execute-src-block'." ((and (string-suffix-p ".png" out-file) (not imagemagick)) (let ((org-format-latex-header (concat org-format-latex-header "\n" - (mapconcat #'identity headers "\n")))) + (mapconcat #'identity headers "\n"))) + (org-preview-latex-process-alist org-babel-latex-process-alist)) (org-create-formula-image - body out-file org-format-latex-options in-buffer))) + body out-file org-format-latex-options in-buffer 'png))) ((string= "svg" extension) (with-temp-file tex-file (insert (concat (funcall org-babel-latex-preamble params) @@ -273,7 +293,9 @@ This function is called by `org-babel-execute-src-block'." body)) (defun org-babel-latex-convert-pdf (pdffile out-file im-in-options im-out-options) - "Generate a file from a pdf file using imagemagick." + "Generate OUT-FILE from PDFFILE using imagemagick. +IM-IN-OPTIONS are command line options for input file, as a string; +and IM-OUT-OPTIONS are the output file options." (let ((cmd (concat "convert " im-in-options " " pdffile " " im-out-options " " out-file))) (message "Converting pdffile file %s..." cmd) diff --git a/elpa/org-9.6.7/ob-lilypond.el b/elpa/org-9.7.17/ob-lilypond.el similarity index 82% rename from elpa/org-9.6.7/ob-lilypond.el rename to elpa/org-9.7.17/ob-lilypond.el index 9693b89e..ef747d9b 100644 --- a/elpa/org-9.6.7/ob-lilypond.el +++ b/elpa/org-9.7.17/ob-lilypond.el @@ -1,6 +1,6 @@ ;;; ob-lilypond.el --- Babel Functions for Lilypond -*- lexical-binding: t; -*- -;; Copyright (C) 2010-2023 Free Software Foundation, Inc. +;; Copyright (C) 2010-2024 Free Software Foundation, Inc. ;; Author: Martyn Jago ;; Keywords: babel language, literate programming @@ -40,10 +40,8 @@ (declare-function org-fold-show-all "org-fold" (&optional types)) -;; FIXME: Doesn't this rather belong in lilypond-mode.el? -(defalias 'lilypond-mode 'LilyPond-mode) - (add-to-list 'org-babel-tangle-lang-exts '("LilyPond" . "ly")) +(add-to-list 'org-src-lang-modes '("lilypond" . LilyPond)) (defvar org-babel-default-header-args:lilypond '() "Default header arguments for lilypond code blocks. @@ -60,23 +58,13 @@ and stored in `org-babel-default-header-args:lilypond' See `org-babel-lilypond-set-header-args'.") (defvar org-babel-lilypond-compile-post-tangle t - "Following the org-babel-tangle (C-c C-v t) command, -org-babel-lilypond-compile-post-tangle determines whether ob-lilypond should -automatically attempt to compile the resultant tangled file. -If the value is nil, no automated compilation takes place. -Default value is t.") + "When non-nil, compile tangled file after `org-babel-tangle'.") (defvar org-babel-lilypond-display-pdf-post-tangle t - "Following a successful LilyPond compilation -org-babel-lilypond-display-pdf-post-tangle determines whether to automate the -drawing / redrawing of the resultant pdf. If the value is nil, -the pdf is not automatically redrawn. Default value is t.") + "When non-nil, display pdf after successful LilyPond compilation.") (defvar org-babel-lilypond-play-midi-post-tangle t - "Following a successful LilyPond compilation -org-babel-lilypond-play-midi-post-tangle determines whether to automate the -playing of the resultant midi file. If the value is nil, -the midi file is not automatically played. Default value is t") + "When non-nil, play midi file after successful LilyPond compilation.") (defvar org-babel-lilypond-ly-command "" "Command to execute lilypond on your system. @@ -143,7 +131,9 @@ blocks.") (defun org-babel-expand-body:lilypond (body params) "Expand BODY according to PARAMS, return the expanded body." - (let ((vars (org-babel--get-vars params))) + (let ((vars (org-babel--get-vars params)) + (prologue (cdr (assq :prologue params))) + (epilogue (cdr (assq :epilogue params)))) (mapc (lambda (pair) (let ((name (symbol-name (car pair))) @@ -152,54 +142,75 @@ blocks.") (replace-regexp-in-string (concat "$" (regexp-quote name)) (if (stringp value) value (format "%S" value)) - body)))) + body t t)))) vars) - body)) + (concat + (and prologue (concat prologue "\n")) + body + (and epilogue (concat "\n" epilogue "\n"))))) (defun org-babel-execute:lilypond (body params) - "This function is called by `org-babel-execute-src-block'. -Depending on whether we are in arrange mode either: -1. Attempt to execute lilypond block according to header settings - (This is the default basic mode) -2. Tangle all lilypond blocks and process the result (arrange mode)" + "Execute LilyPond src block according to arrange mode. +See `org-babel-execute-src-block' for BODY and PARAMS. +When in arrange mode, tangle all blocks and process the result. +Otherwise, execute block according to header settings." (org-babel-lilypond-set-header-args org-babel-lilypond-arrange-mode) (if org-babel-lilypond-arrange-mode (org-babel-lilypond-tangle) (org-babel-lilypond-process-basic body params))) (defun org-babel-lilypond-tangle () - "ob-lilypond specific tangle, attempts to invoke -=ly-execute-tangled-ly= if tangle is successful. Also passes -specific arguments to =org-babel-tangle=." + "Tangle lilypond blocks, then `org-babel-lilypond-execute-tangled-ly'." (interactive) (if (org-babel-tangle nil "yes" "lilypond") (org-babel-lilypond-execute-tangled-ly) nil)) +;; https://lilypond.org/doc/v2.24/Documentation/usage/other-programs +(defvar org-babel-lilypond-paper-settings + "#(if (ly:get-option 'use-paper-size-for-page) + (begin (ly:set-option 'use-paper-size-for-page #f) + (ly:set-option 'tall-page-formats '%s))) +\\paper { + indent=0\\mm + tagline=\"\" + oddFooterMarkup=##f + oddHeaderMarkup=##f + bookTitleMarkup=##f + scoreTitleMarkup=##f +}\n" + "The paper settings required to generate music fragments. +They are needed for mixing music and text in basic-mode.") + (defun org-babel-lilypond-process-basic (body params) - "Execute a lilypond block in basic mode." + "Execute a lilypond block in basic mode. +See `org-babel-execute-src-block' for BODY and PARAMS." (let* ((out-file (cdr (assq :file params))) + (file-type (file-name-extension out-file)) (cmdline (or (cdr (assq :cmdline params)) "")) (in-file (org-babel-temp-file "lilypond-"))) (with-temp-file in-file - (insert (org-babel-expand-body:generic body params))) + (insert + (format org-babel-lilypond-paper-settings file-type) + (org-babel-expand-body:generic body params))) (org-babel-eval (concat org-babel-lilypond-ly-command " -dbackend=eps " "-dno-gs-load-fonts " "-dinclude-eps-fonts " - (or (cdr (assoc (file-name-extension out-file) - '(("pdf" . "--pdf ") - ("ps" . "--ps ") - ("png" . "--png ")))) + (or (assoc-default file-type + '(("pdf" . "--pdf ") + ("eps" . "--eps "))) "--png ") "--output=" (file-name-sans-extension out-file) " " cmdline - in-file) "")) nil) + in-file) + "")) + nil) (defun org-babel-prep-session:lilypond (_session _params) "Return an error because LilyPond exporter does not support sessions." @@ -219,7 +230,7 @@ If error in compilation, attempt to mark the error in lilypond org file." (delete-file org-babel-lilypond-temp-file)) (rename-file org-babel-lilypond-tangled-file org-babel-lilypond-temp-file)) - (org-switch-to-buffer-other-window "*lilypond*") + (switch-to-buffer-other-window "*lilypond*") (erase-buffer) (org-babel-lilypond-compile-lilyfile org-babel-lilypond-temp-file) (goto-char (point-min)) @@ -229,27 +240,20 @@ If error in compilation, attempt to mark the error in lilypond org file." (org-babel-lilypond-attempt-to-open-pdf org-babel-lilypond-temp-file) (org-babel-lilypond-attempt-to-play-midi org-babel-lilypond-temp-file))))) -(defun org-babel-lilypond-compile-lilyfile (file-name &optional test) - "Compile lilypond file and check for compile errors. -FILE-NAME is full path to lilypond (.ly) file." - (message "Compiling LilyPond...") - (let ((arg-1 org-babel-lilypond-ly-command) ;program - ;; (arg-2 nil) ;infile - (arg-3 "*lilypond*") ;buffer - (arg-4 t) ;display - (arg-5 (if org-babel-lilypond-gen-png "--png" "")) ;&rest... - (arg-6 (if org-babel-lilypond-gen-html "--html" "")) - (arg-7 (if org-babel-lilypond-gen-pdf "--pdf" "")) - (arg-8 (if org-babel-lilypond-use-eps "-dbackend=eps" "")) - (arg-9 (if org-babel-lilypond-gen-svg "-dbackend=svg" "")) - (arg-10 (concat "--output=" (file-name-sans-extension file-name))) - (arg-11 file-name)) - (if test - `(,arg-1 ,nil ,arg-3 ,arg-4 ,arg-5 ,arg-6 ;; arg-2 - ,arg-7 ,arg-8 ,arg-9 ,arg-10 ,arg-11) - (call-process - arg-1 nil arg-3 arg-4 arg-5 arg-6 ;; arg-2 - arg-7 arg-8 arg-9 arg-10 arg-11)))) +;;Ignoring second arg for pre Org 9.7 compatibility +(defun org-babel-lilypond-compile-lilyfile (filename &optional _) + "Compile Lilypond FILENAME and check for compile errors." + (message "Compiling %s..." filename) + (let ((args (delq nil (list + (and org-babel-lilypond-gen-png "--png") + (and org-babel-lilypond-gen-html "--html") + (and org-babel-lilypond-gen-pdf "--pdf") + (and org-babel-lilypond-use-eps "-dbackend=eps") + (and org-babel-lilypond-gen-svg "-dbackend=svg") + (concat "--output=" (file-name-sans-extension filename)) + filename)))) + (apply #'call-process org-babel-lilypond-ly-command nil + "*lilypond*" 'display args))) (defun org-babel-lilypond-check-for-compile-error (file-name &optional test) "Check for compile error. @@ -276,7 +280,7 @@ FILE-NAME is full path to lilypond file." "Mark the erroneous lines in the lilypond org buffer. FILE-NAME is full path to lilypond file. LINE is the erroneous line." - (org-switch-to-buffer-other-window + (switch-to-buffer-other-window (concat (file-name-nondirectory (org-babel-lilypond-switch-extension file-name ".org")))) (let ((temp (point))) @@ -290,7 +294,7 @@ LINE is the erroneous line." (goto-char temp)))) (defun org-babel-lilypond-parse-line-num (&optional buffer) - "Extract error line number." + "Extract error line number in BUFFER or `current-buffer'." (when buffer (set-buffer buffer)) (let ((start (and (search-backward ":" nil t) @@ -423,8 +427,7 @@ These depend upon whether we are in Arrange mode i.e. MODE is t." ob-lilypond-header-args))) (defun org-babel-lilypond-set-header-args (mode) - "Set org-babel-default-header-args:lilypond -dependent on ORG-BABEL-LILYPOND-ARRANGE-MODE." + "Set lilypond babel header according to MODE." (setq org-babel-default-header-args:lilypond (org-babel-lilypond-get-header-args mode))) diff --git a/elpa/org-9.6.7/ob-lisp.el b/elpa/org-9.7.17/ob-lisp.el similarity index 59% rename from elpa/org-9.6.7/ob-lisp.el rename to elpa/org-9.7.17/ob-lisp.el index 048ef883..0e416ad9 100644 --- a/elpa/org-9.6.7/ob-lisp.el +++ b/elpa/org-9.7.17/ob-lisp.el @@ -1,6 +1,6 @@ ;;; ob-lisp.el --- Babel Functions for Common Lisp -*- lexical-binding: t; -*- -;; Copyright (C) 2009-2023 Free Software Foundation, Inc. +;; Copyright (C) 2009-2024 Free Software Foundation, Inc. ;; Authors: Joel Boehland ;; Eric Schulte @@ -74,13 +74,19 @@ current directory string." (let* ((vars (org-babel--get-vars params)) (result-params (cdr (assq :result-params params))) (print-level nil) (print-length nil) + (prologue (cdr (assq :prologue params))) + (epilogue (cdr (assq :epilogue params))) (body (if (null vars) (org-trim body) (concat "(let (" (mapconcat (lambda (var) (format "(%S (quote %S))" (car var) (cdr var))) vars "\n ") - ")\n" body ")")))) + ")\n" + (and prologue (concat prologue "\n")) + body + (and epilogue (concat "\n" epilogue "\n")) + ")")))) (if (or (member "code" result-params) (member "pp" result-params)) (format "(pprint %s)" body) @@ -90,37 +96,41 @@ current directory string." "Execute a block of Common Lisp code with Babel. BODY is the contents of the block, as a string. PARAMS is a property list containing the parameters of the block." - (require (pcase org-babel-lisp-eval-fn - (`slime-eval 'slime) - (`sly-eval 'sly))) - (org-babel-reassemble-table - (let ((result - (funcall (if (member "output" (cdr (assq :result-params params))) - #'car #'cadr) - (with-temp-buffer - (insert (org-babel-expand-body:lisp body params)) - (funcall org-babel-lisp-eval-fn - `(swank:eval-and-grab-output - ,(let ((dir (if (assq :dir params) - (cdr (assq :dir params)) - default-directory))) - (format - (if dir (format org-babel-lisp-dir-fmt dir) - "(progn %s\n)") - (buffer-substring-no-properties - (point-min) (point-max))))) - (cdr (assq :package params))))))) - (org-babel-result-cond (cdr (assq :result-params params)) - (org-strip-quotes result) - (condition-case nil - (read (org-babel-lisp-vector-to-list result)) - (error 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))))) + (let (eval-and-grab-output) + (pcase org-babel-lisp-eval-fn + (`slime-eval (org-require-package 'slime "SLIME") + (setq eval-and-grab-output 'swank:eval-and-grab-output)) + (`sly-eval (org-require-package 'sly "SLY") + (setq eval-and-grab-output 'slynk:eval-and-grab-output))) + (org-babel-reassemble-table + (let ((result + (funcall (if (member "output" (cdr (assq :result-params params))) + #'car #'cadr) + (with-temp-buffer + (insert (org-babel-expand-body:lisp body params)) + (funcall org-babel-lisp-eval-fn + `(,eval-and-grab-output + ,(let ((dir (if (assq :dir params) + (cdr (assq :dir params)) + default-directory))) + (format + (if dir (format org-babel-lisp-dir-fmt dir) + "(progn %s\n)") + (buffer-substring-no-properties + (point-min) (point-max))))) + (cdr (assq :package params))))))) + (org-babel-result-cond (cdr (assq :result-params params)) + (org-strip-quotes result) + (condition-case nil + (read (org-babel-lisp-vector-to-list result)) + (error 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)))))) (defun org-babel-lisp-vector-to-list (results) + "Convert #(...) values in RESULTS string into a (...) list." ;; TODO: better would be to replace #(...) with [...] (replace-regexp-in-string "#(" "(" results)) diff --git a/elpa/org-9.6.7/ob-lob.el b/elpa/org-9.7.17/ob-lob.el similarity index 96% rename from elpa/org-9.6.7/ob-lob.el rename to elpa/org-9.7.17/ob-lob.el index f77bda73..eaa66872 100644 --- a/elpa/org-9.6.7/ob-lob.el +++ b/elpa/org-9.7.17/ob-lob.el @@ -1,6 +1,6 @@ ;;; ob-lob.el --- Functions Supporting the Library of Babel -*- lexical-binding: t; -*- -;; Copyright (C) 2009-2023 Free Software Foundation, Inc. +;; Copyright (C) 2009-2024 Free Software Foundation, Inc. ;; Authors: Eric Schulte ;; Dan Davison @@ -22,6 +22,8 @@ ;; You should have received a copy of the GNU General Public License ;; along with GNU Emacs. If not, see . +;;; Commentary: + ;;; Code: (require 'org-macs) @@ -34,8 +36,8 @@ (declare-function org-babel-ref-split-args "ob-ref" (arg-string)) (declare-function org-element-at-point "org-element" (&optional pom cached-only)) (declare-function org-element-context "org-element" (&optional element)) -(declare-function org-element-property "org-element" (property element)) -(declare-function org-element-type "org-element" (element)) +(declare-function org-element-property "org-element-ast" (property node)) +(declare-function org-element-type "org-element-ast" (node &optional anonymous)) (defvar org-babel-library-of-babel nil "Library of source-code blocks. diff --git a/elpa/org-9.6.7/ob-lua.el b/elpa/org-9.7.17/ob-lua.el similarity index 83% rename from elpa/org-9.6.7/ob-lua.el rename to elpa/org-9.7.17/ob-lua.el index 81521d9e..980a7109 100644 --- a/elpa/org-9.6.7/ob-lua.el +++ b/elpa/org-9.7.17/ob-lua.el @@ -1,6 +1,6 @@ ;;; ob-lua.el --- Org Babel functions for Lua evaluation -*- lexical-binding: t; -*- -;; Copyright (C) 2014, 2016-2023 Free Software Foundation, Inc. +;; Copyright (C) 2014, 2016-2024 Free Software Foundation, Inc. ;; Authors: Dieter Schoen ;; Keywords: literate programming, reproducible research @@ -23,12 +23,14 @@ ;;; Commentary: -;; Org-Babel support for evaluating lua source code. +;; Org-Babel support for evaluating Lua source code. ;; Requirements: ;; for session support, lua-mode is needed. +;; ;; lua-mode is not part of GNU Emacs/orgmode, but can be obtained -;; from marmalade or melpa. +;; from NonGNU ELPA (see `M-x list-packages'). +;; ;; The source repository is here: ;; https://github.com/immerrr/lua-mode @@ -68,21 +70,27 @@ This will typically be `lua-mode'." :type 'symbol) (defcustom org-babel-lua-hline-to "None" - "Replace hlines in incoming tables with this when translating to lua." + "Replace hlines in incoming tables with this when translating to Lua." :group 'org-babel :version "26.1" :package-version '(Org . "8.3") :type 'string) (defcustom org-babel-lua-None-to 'hline - "Replace `None' in lua tables with this before returning." + "Replace `None' in Lua tables with this before returning." :group 'org-babel :version "26.1" :package-version '(Org . "8.3") :type 'symbol) +(defcustom org-babel-lua-multiple-values-separator ", " + "Separate multiple values with this string." + :group 'org-babel + :package-version '(Org . "9.7") + :type 'string) + (defun org-babel-execute:lua (body params) - "Execute a block of Lua code with Babel. + "Execute Lua BODY according to PARAMS. This function is called by `org-babel-execute-src-block'." (let* ((session (org-babel-lua-initiate-session (cdr (assq :session params)))) @@ -129,7 +137,8 @@ VARS contains resolved variable references." ;; helper functions (defun org-babel-variable-assignments:lua (params) - "Return a list of Lua statements assigning the block's variables." + "Return a list of Lua statements assigning the block's variables. +The variable definitions are defining in PARAMS." (mapcar (lambda (pair) (format "%s=%s" @@ -138,8 +147,8 @@ VARS contains resolved variable references." (org-babel--get-vars params))) (defun org-babel-lua-var-to-lua (var) - "Convert an elisp value to a lua variable. -Convert an elisp value, VAR, into a string of lua source code + "Convert an Emacs Lisp value to a Lua variable. +Convert an Emacs Lisp value, VAR, into a string of Lua source code specifying a variable of the same value." (if (listp var) (if (and (= 1 (length var)) (not (listp (car var)))) @@ -176,13 +185,20 @@ Emacs-lisp table, otherwise return the results as a string." (cdr (assoc session org-babel-lua-buffers))) (defun org-babel-lua-with-earmuffs (session) + "Return buffer name for SESSION, as *SESSION*." (let ((name (if (stringp session) session (format "%s" session)))) (if (and (string= "*" (substring name 0 1)) (string= "*" (substring name (- (length name) 1)))) name (format "*%s*" name)))) +(defun org-babel-session-buffer:lua (session &optional _) + "Return session buffer name for SESSION." + (or (org-babel-lua-session-buffer session) + (org-babel-lua-with-earmuffs session))) + (defun org-babel-lua-without-earmuffs (session) +"Remove stars around *SESSION*, leaving SESSION." (let ((name (if (stringp session) session (format "%s" session)))) (if (and (string= "*" (substring name 0 1)) (string= "*" (substring name (- (length name) 1)))) @@ -193,7 +209,7 @@ Emacs-lisp table, otherwise return the results as a string." (defvar lua-which-bufname) (defvar lua-shell-buffer-name) (defun org-babel-lua-initiate-session-by-key (&optional session) - "Initiate a lua session. + "Initiate a Lua session. If there is not a current inferior-process-buffer in SESSION then create. Return the initialized session." ;; (require org-babel-lua-mode) @@ -243,45 +259,55 @@ function main() %s end -fd=io.open(\"%s\", \"w\") -fd:write( main() ) -fd:close()") -(defvar org-babel-lua-pp-wrapper-method - " --- table to string -function t2s(t, indent) +function dump(it, indent) if indent == nil then - indent = \"\" + indent = '' end - if type(t) == \"table\" then - ts = \"\" - for k,v in pairs(t) do - if type(v) == \"table\" then - ts = ts .. indent .. t2s(k,indent .. \" \") .. \" = \\n\" .. - t2s(v, indent .. \" \") - else - ts = ts .. indent .. t2s(k,indent .. \" \") .. \" = \" .. - t2s(v, indent .. \" \") .. \"\\n\" + if type(it) == 'table' and %s then + local count = 0 + for _ in pairs(it) do + count = count + 1 + end + local result = '' + if #indent ~= 0 then + result = result .. '\\n' + end + for key, value in pairs(it) do + result = result + .. indent + .. dump(key) + .. ' = ' + .. dump(value, indent .. ' ') + count = count - 1 + if count ~= 0 then + result = result .. '\\n' end end - return ts + return result else - return tostring(t) + return tostring(it) end end - -function main() -%s +function combine(...) + local result = {} + for index = 1, select('#', ...) do + result[index] = dump(select(index, ...)) + end + return table.concat(result, '%s') end -fd=io.open(\"%s\", \"w\") -fd:write(t2s(main())) -fd:close()") +output = io.open('%s', 'w') +output:write(combine(main())) +output:close()") (defun org-babel-lua-evaluate (session body &optional result-type result-params preamble) - "Evaluate BODY as Lua code." + "Evaluate BODY in SESSION as Lua code. +RESULT-TYPE and RESULT-PARAMS are passed to +`org-babel-lua-evaluate-session' or +`org-babel-lua-evaluate-external-process'. +PREAMBLE is passed to `org-babel-lua-evaluate-external-process'." (if session (org-babel-lua-evaluate-session session body result-type result-params) @@ -290,10 +316,12 @@ fd:close()") (defun org-babel-lua-evaluate-external-process (body &optional result-type result-params preamble) - "Evaluate BODY in external lua process. + "Evaluate BODY in external Lua 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." +last statement in BODY, as Emacs Lisp. +RESULT-PARAMS list all the :result header arg parameters. +PREAMBLE string is appended to BODY." (let ((raw (pcase result-type (`output (org-babel-eval org-babel-lua-command @@ -305,15 +333,17 @@ last statement in BODY, as elisp." (concat preamble (and preamble "\n") (format - (if (member "pp" result-params) - org-babel-lua-pp-wrapper-method - org-babel-lua-wrapper-method) + org-babel-lua-wrapper-method (mapconcat (lambda (line) (format "\t%s" line)) (split-string (org-remove-indentation (org-trim body)) - "[\r\n]") "\n") + "[\r\n]") + "\n") + (if (member "pp" result-params) + "true" "false") + org-babel-lua-multiple-values-separator (org-babel-process-file-name tmp-file 'noquote)))) (org-babel-eval-read-file tmp-file)))))) (org-babel-result-cond result-params @@ -325,8 +355,8 @@ last statement in BODY, as elisp." "Pass BODY to the Lua process in SESSION. 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." - (let* ((send-wait (lambda () (comint-send-input nil t) (sleep-for 0 5))) +last statement in BODY, as Emacs Lisp." + (let* ((send-wait (lambda () (comint-send-input nil t) (sleep-for 0.005))) (dump-last-value (lambda (tmp-file pp) @@ -399,7 +429,7 @@ fd:close()" (org-babel-lua-table-or-string results))))) (defun org-babel-lua-read-string (string) - "Strip single quotes from around Lua string." + "Strip single quotes from around Lua STRING." (org-unbracket-string "'" "'" string)) (provide 'ob-lua) diff --git a/elpa/org-9.6.7/ob-makefile.el b/elpa/org-9.7.17/ob-makefile.el similarity index 92% rename from elpa/org-9.6.7/ob-makefile.el rename to elpa/org-9.7.17/ob-makefile.el index 25306159..9ff545b7 100644 --- a/elpa/org-9.6.7/ob-makefile.el +++ b/elpa/org-9.7.17/ob-makefile.el @@ -1,6 +1,6 @@ ;;; ob-makefile.el --- Babel Functions for Makefile -*- lexical-binding: t; -*- -;; Copyright (C) 2009-2023 Free Software Foundation, Inc. +;; Copyright (C) 2009-2024 Free Software Foundation, Inc. ;; Author: Eric Schulte ;; Thomas S. Dye @@ -36,7 +36,8 @@ (defvar org-babel-default-header-args:makefile '()) (defun org-babel-execute:makefile (body _params) - "Execute a block of makefile code. + "Execute makefile BODY. +Second function argument is ignored. This function is called by `org-babel-execute-src-block'." body) diff --git a/elpa/org-9.6.7/ob-matlab.el b/elpa/org-9.7.17/ob-matlab.el similarity index 95% rename from elpa/org-9.6.7/ob-matlab.el rename to elpa/org-9.7.17/ob-matlab.el index 43344495..de8deadb 100644 --- a/elpa/org-9.6.7/ob-matlab.el +++ b/elpa/org-9.7.17/ob-matlab.el @@ -1,6 +1,6 @@ ;;; ob-matlab.el --- Babel support for Matlab -*- lexical-binding: t; -*- -;; Copyright (C) 2010-2023 Free Software Foundation, Inc. +;; Copyright (C) 2010-2024 Free Software Foundation, Inc. ;; Author: Dan Davison ;; Keywords: literate programming, reproducible research diff --git a/elpa/org-9.7.17/ob-maxima.el b/elpa/org-9.7.17/ob-maxima.el new file mode 100644 index 00000000..681154ad --- /dev/null +++ b/elpa/org-9.7.17/ob-maxima.el @@ -0,0 +1,194 @@ +;;; ob-maxima.el --- Babel Functions for Maxima -*- lexical-binding: t; -*- + +;; Copyright (C) 2009-2024 Free Software Foundation, Inc. + +;; Author: Eric S Fraga +;; Eric Schulte +;; Keywords: literate programming, reproducible research, maxima +;; URL: 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 maxima entries. +;; +;; This differs from most standard languages in that +;; 1) there is no such thing as a "session" in maxima +;; 2) we are adding the "cmdline" header argument + +;;; Code: + +(require 'org-macs) +(org-assert-version) + +(require 'ob) + +(defconst org-babel-header-args:maxima + '((batch . ((batchload batch load))) + (graphics-pkg . ((plot draw)))) + "Maxima-specific header arguments.") + +(defvar org-babel-tangle-lang-exts) +(add-to-list 'org-babel-tangle-lang-exts '("maxima" . "max")) + +(defvar org-babel-default-header-args:maxima '()) + +(defcustom org-babel-maxima-command + (if (boundp 'maxima-command) maxima-command "maxima") + "Command used to call maxima on the shell." + :group 'org-babel + :type 'string) + +(defvar org-babel-maxima--command-arguments-default + "--very-quiet" + "Command-line arguments sent to Maxima by default. +If the `:batch' header argument is set to `batchload' or unset, +then the `:cmdline' header argument is appended to this default; +otherwise, if the `:cmdline' argument is set, it over-rides this +default. See `org-babel-maxima-command' and +`org-babel-execute:maxima'.") + +(defvar org-babel-maxima--graphic-package-options + '((plot . "(set_plot_option ('[gnuplot_term, %s]), set_plot_option ('[gnuplot_out_file, %S]))$") + (draw . "(load(draw), set_draw_defaults(terminal='%s,file_name=%S))$")) + "An alist of graphics packages and Maxima code. +Each element is a cons (PACKAGE-NAME . FORMAT-STRING). +FORMAT-STRING contains Maxima code to configure the graphics +package; it must contain `%s' to set the terminal and `%S' to set +the filename, in that order. The default graphics package is +`plot'; `draw' is also supported. See +`org-babel-maxima-expand'.") + +(defvar org-babel-maxima--default-epilogue + '((graphical-output . "gnuplot_close ()$") + (non-graphical-output . "")) + "The final Maxima code executed in a source block. +An alist with the epilogue for graphical and non-graphical +output. See `org-babel-maxima-expand'.") + +(defun org-babel-maxima-expand (body params) + "Expand Maxima BODY according to its header arguments from PARAMS." + (let* ((vars (org-babel--get-vars params)) + (graphic-file (ignore-errors (org-babel-graphical-output-file params))) + (epilogue (cdr (assq :epilogue params))) + (prologue (cdr (assq :prologue params)))) + (mapconcat 'identity + (delq nil + (list + ;; Any code from the specified prologue at the start. + prologue + ;; graphic output + (if graphic-file + (let* ((graphics-pkg (intern (or (cdr (assq :graphics-pkg params)) "plot"))) + (graphic-format-string (cdr (assq graphics-pkg org-babel-maxima--graphic-package-options))) + (graphic-terminal (file-name-extension graphic-file)) + (graphic-file (if (eq graphics-pkg 'plot) graphic-file (file-name-sans-extension graphic-file)))) + (format graphic-format-string graphic-terminal graphic-file))) + ;; variables + (mapconcat 'org-babel-maxima-var-to-maxima vars "\n") + ;; body + body + ;; Any code from the specified epilogue at the end. + epilogue + (if graphic-file + (cdr (assq :graphical-output org-babel-maxima--default-epilogue)) + (cdr (assq :non-graphical-output org-babel-maxima--default-epilogue))))) + "\n"))) + +(defvar org-babel-maxima--output-filter-regexps + '("batch" ;; remove the `batch' or `batchload' line + "^rat: replaced .*$" ;; remove notices from `rat' + "^;;; Loading #P" ;; remove notices from the lisp implementation + "^read and interpret" ;; remove notice from `batch' + "^(%\\([i]-?[0-9]+\\))[ ]$" ;; remove empty input lines from `batch'-ing + ) + "Regexps to remove extraneous lines from Maxima's output. +See `org-babel-maxima--output-filter'.") + +(defun org-babel-maxima--output-filter (line) + "Filter empty or undesired lines from Maxima output. +Return nil if LINE is zero-length or it matches a regexp in +`org-babel-maxima--output-filter'; otherwise, return LINE." + (unless (or (= 0 (length line)) + (cl-some #'(lambda(r) (string-match r line)) + org-babel-maxima--output-filter-regexps)) + line)) + +(defun org-babel-execute:maxima (body params) + "Execute Maxima BODY according to PARAMS. +This function is called by `org-babel-execute-src-block'." + (unless noninteractive (message "Executing Maxima source code block")) + (let ((result-params (split-string (or (cdr (assq :results params)) ""))) + (result + (let* ((cmdline (or (cdr (assq :cmdline params)) "")) + (batch/load (or (cdr (assq :batch params)) "batchload")) + (cmdline (if (or (equal cmdline "") (equal batch/load "batchload")) + ;; legacy behavior: + ;; ensure that --very-quiet is on command-line by default + (concat cmdline " " org-babel-maxima--command-arguments-default) + ;; if using an alternate loader, :cmdline overwrites default + cmdline)) + (in-file (org-babel-temp-file "maxima-" ".max")) + (cmd (format "%s -r %s %s" + org-babel-maxima-command + (shell-quote-argument + ;; bind linenum to 0 so the first line + ;; of in-file has line number 1 + (format "(linenum:0, %s(%S))$" batch/load in-file)) + cmdline))) + (with-temp-file in-file (insert (org-babel-maxima-expand body params))) + (unless noninteractive (message cmd)) + ;; " | grep -v batch | grep -v 'replaced' | sed '/^$/d' " + (let ((raw (org-babel-eval cmd ""))) + (mapconcat + #'identity + (delq nil + (mapcar #'org-babel-maxima--output-filter + (split-string raw "[\r\n]"))) "\n"))))) + (if (ignore-errors (org-babel-graphical-output-file params)) + nil + (org-babel-result-cond result-params + result + (let ((tmp-file (org-babel-temp-file "maxima-res-"))) + (with-temp-file tmp-file (insert result)) + (org-babel-import-elisp-from-file tmp-file)))))) + + +(defun org-babel-prep-session:maxima (_session _params) +"Throw an error. Maxima does not support sessions." + (error "Maxima does not support sessions")) + +(defun org-babel-maxima-var-to-maxima (pair) + "Convert an elisp variable-value PAIR to maxima code." + (let ((var (car pair)) + (val (cdr pair))) + (when (symbolp val) + (setq val (symbol-name val)) + (when (= (length val) 1) + (setq val (string-to-char val)))) + (format "%S: %s$" var + (org-babel-maxima-elisp-to-maxima val)))) + +(defun org-babel-maxima-elisp-to-maxima (val) + "Return a string of maxima code which evaluates to VAL." + (if (listp val) + (concat "[" (mapconcat #'org-babel-maxima-elisp-to-maxima val ", ") "]") + (format "%s" val))) + +(provide 'ob-maxima) + +;;; ob-maxima.el ends here diff --git a/elpa/org-9.6.7/ob-ocaml.el b/elpa/org-9.7.17/ob-ocaml.el similarity index 97% rename from elpa/org-9.6.7/ob-ocaml.el rename to elpa/org-9.7.17/ob-ocaml.el index 09224b98..6554193a 100644 --- a/elpa/org-9.6.7/ob-ocaml.el +++ b/elpa/org-9.7.17/ob-ocaml.el @@ -1,6 +1,6 @@ ;;; ob-ocaml.el --- Babel Functions for Ocaml -*- lexical-binding: t; -*- -;; Copyright (C) 2009-2023 Free Software Foundation, Inc. +;; Copyright (C) 2009-2024 Free Software Foundation, Inc. ;; Author: Eric Schulte ;; Keywords: literate programming, reproducible research @@ -63,7 +63,7 @@ :type 'string) (defun org-babel-execute:ocaml (body params) - "Execute a block of Ocaml code with Babel." + "Execute Ocaml BODY according to PARAMS." (let* ((full-body (org-babel-expand-body:generic body params (org-babel-variable-assignments:ocaml params))) @@ -109,7 +109,7 @@ (defvar tuareg-interactive-buffer-name) (defun org-babel-prep-session:ocaml (session _params) "Prepare SESSION according to the header arguments in PARAMS." - (require 'tuareg) + (org-require-package 'tuareg) (let ((tuareg-interactive-buffer-name (if (and (not (string= session "none")) (not (string= session "default")) (stringp session)) @@ -121,7 +121,8 @@ (get-buffer tuareg-interactive-buffer-name))) (defun org-babel-variable-assignments:ocaml (params) - "Return list of ocaml statements assigning the block's variables." + "Return list of ocaml statements assigning the block's variables. +The variables are defined in PARAMS." (mapcar (lambda (pair) (format "let %s = %s;;" (car pair) (org-babel-ocaml-elisp-to-ocaml (cdr pair)))) diff --git a/elpa/org-9.6.7/ob-octave.el b/elpa/org-9.7.17/ob-octave.el similarity index 89% rename from elpa/org-9.6.7/ob-octave.el rename to elpa/org-9.7.17/ob-octave.el index 1de263a5..005990f2 100644 --- a/elpa/org-9.6.7/ob-octave.el +++ b/elpa/org-9.7.17/ob-octave.el @@ -1,6 +1,6 @@ ;;; ob-octave.el --- Babel Functions for Octave and Matlab -*- lexical-binding: t; -*- -;; Copyright (C) 2010-2023 Free Software Foundation, Inc. +;; Copyright (C) 2010-2024 Free Software Foundation, Inc. ;; Author: Dan Davison ;; Keywords: literate programming, reproducible research @@ -70,11 +70,12 @@ end") (defvar org-babel-octave-eoe-output "ans = org_babel_eoe") (defun org-babel-execute:matlab (body params) - "Execute a block of matlab code with Babel." + "Execute Matlab BODY according to PARAMS." (org-babel-execute:octave body params 'matlab)) (defun org-babel-execute:octave (body params &optional matlabp) - "Execute a block of octave code with Babel." + "Execute Octave or Matlab BODY according to PARAMS. +When MATLABP is non-nil, execute Matlab. Otherwise, execute Octave." (let* ((session (funcall (intern (format "org-babel-%s-initiate-session" (if matlabp "matlab" "octave"))) @@ -109,7 +110,8 @@ end") (org-babel-prep-session:octave session params 'matlab)) (defun org-babel-variable-assignments:octave (params) - "Return list of octave statements assigning the block's variables." + "Return list of octave statements assigning the block's variables. +The variables are taken from PARAMS." (mapcar (lambda (pair) (format "%s=%s;" @@ -120,21 +122,22 @@ end") (defalias 'org-babel-variable-assignments:matlab 'org-babel-variable-assignments:octave) -(defun org-babel-octave-var-to-octave (var) - "Convert an emacs-lisp value into an octave variable. +(defun org-babel-octave-var-to-octave (value) + "Convert an emacs-lisp VALUE into an octave variable. Converts an emacs-lisp variable into a string of octave code specifying a variable of the same value." - (if (listp var) - (concat "[" (mapconcat #'org-babel-octave-var-to-octave var - (if (listp (car var)) "; " ",")) "]") + (if (listp value) + (concat "[" (mapconcat #'org-babel-octave-var-to-octave value + (if (listp (car value)) "; " ",")) "]") (cond - ((stringp var) - (format "'%s'" var)) + ((stringp value) + (format "'%s'" value)) (t - (format "%s" var))))) + (format "%s" value))))) (defun org-babel-prep-session:octave (session params &optional matlabp) - "Prepare SESSION according to the header arguments specified in PARAMS." + "Prepare SESSION according to the header arguments specified in PARAMS. +The session will be an Octave session, unless MATLABP is non-nil." (let* ((session (org-babel-octave-initiate-session session params matlabp)) (var-lines (org-babel-variable-assignments:octave params))) (org-babel-comint-in-buffer session @@ -147,15 +150,18 @@ specifying a variable of the same value." (defun org-babel-matlab-initiate-session (&optional session params) "Create a matlab inferior process buffer. If there is not a current inferior-process-buffer in SESSION then -create. Return the initialized session." +create. Return the initialized session. PARAMS are src block parameters." (org-babel-octave-initiate-session session params 'matlab)) (defun org-babel-octave-initiate-session (&optional session _params matlabp) "Create an octave inferior process buffer. If there is not a current inferior-process-buffer in SESSION then -create. Return the initialized session." - (if matlabp (require 'matlab) (or (require 'octave-inf nil 'noerror) - (require 'octave))) +create. Return the initialized session. The session will be an +Octave session, unless MATLABP is non-nil." + (if matlabp + (org-require-package 'matlab "matlab-mode") + (or (require 'octave-inf nil 'noerror) + (require 'octave))) (unless (string= session "none") (let ((session (or session (if matlabp "*Inferior Matlab*" "*Inferior Octave*")))) @@ -178,7 +184,8 @@ value of the last statement in BODY, as elisp." (org-babel-octave-evaluate-external-process body result-type matlabp))) (defun org-babel-octave-evaluate-external-process (body result-type matlabp) - "Evaluate BODY in an external octave process." + "Evaluate BODY in an external Octave or Matalab process. +Process the result as RESULT-TYPE. Use Octave, unless MATLABP is non-nil." (let ((cmd (if matlabp org-babel-matlab-shell-command org-babel-octave-shell-command))) diff --git a/elpa/org-9.6.7/ob-org.el b/elpa/org-9.7.17/ob-org.el similarity index 81% rename from elpa/org-9.6.7/ob-org.el rename to elpa/org-9.7.17/ob-org.el index 1bf02b46..302f61bc 100644 --- a/elpa/org-9.6.7/ob-org.el +++ b/elpa/org-9.7.17/ob-org.el @@ -1,6 +1,6 @@ ;;; ob-org.el --- Babel Functions for Org Code Blocks -*- lexical-binding: t; -*- -;; Copyright (C) 2010-2023 Free Software Foundation, Inc. +;; Copyright (C) 2010-2024 Free Software Foundation, Inc. ;; Author: Eric Schulte ;; Keywords: literate programming, reproducible research @@ -45,15 +45,25 @@ "Default header inserted during export of org blocks.") (defun org-babel-expand-body:org (body params) + "Expand Org BODY according to PARAMS. +$VAR instances are replaced by VAR values defined in PARAMS." (dolist (var (org-babel--get-vars params)) (setq body (replace-regexp-in-string (regexp-quote (format "$%s" (car var))) (format "%s" (cdr var)) - body nil 'literal))) - body) + body 'fixedcase 'literal))) + + (let ((prologue (cdr (assq :prologue params))) + (epilogue (cdr (assq :epilogue params)))) + (concat + (and prologue (concat prologue "\n")) + body + (and epilogue (concat "\n" epilogue "\n"))))) (defun org-babel-execute:org (body params) - "Execute a block of Org code with. + "Execute a Org BODY according to PARAMS. +The BODY is returned expanded as is or exported, if PARAMS define +latex/html/ascii result type. This function is called by `org-babel-execute-src-block'." (let ((result-params (split-string (or (cdr (assq :results params)) ""))) (body (org-babel-expand-body:org diff --git a/elpa/org-9.6.7/ob-perl.el b/elpa/org-9.7.17/ob-perl.el similarity index 98% rename from elpa/org-9.6.7/ob-perl.el rename to elpa/org-9.7.17/ob-perl.el index c8cff5da..1006ffb1 100644 --- a/elpa/org-9.6.7/ob-perl.el +++ b/elpa/org-9.7.17/ob-perl.el @@ -1,6 +1,6 @@ ;;; ob-perl.el --- Babel Functions for Perl -*- lexical-binding: t; -*- -;; Copyright (C) 2009-2023 Free Software Foundation, Inc. +;; Copyright (C) 2009-2024 Free Software Foundation, Inc. ;; Authors: Dan Davison ;; Eric Schulte diff --git a/elpa/org-9.6.7/ob-plantuml.el b/elpa/org-9.7.17/ob-plantuml.el similarity index 96% rename from elpa/org-9.6.7/ob-plantuml.el rename to elpa/org-9.7.17/ob-plantuml.el index 3202c6e4..229b4bad 100644 --- a/elpa/org-9.6.7/ob-plantuml.el +++ b/elpa/org-9.7.17/ob-plantuml.el @@ -1,6 +1,6 @@ ;;; ob-plantuml.el --- Babel Functions for Plantuml -*- lexical-binding: t; -*- -;; Copyright (C) 2010-2023 Free Software Foundation, Inc. +;; Copyright (C) 2010-2024 Free Software Foundation, Inc. ;; Author: Zhang Weize ;; Keywords: literate programming, reproducible research @@ -57,7 +57,7 @@ The JAR can be configured via `org-plantuml-jar-path'. `plantuml' means to use the PlantUML executable. The executable can be configured via `org-plantuml-executable-path'. -You can also configure extra arguments via `org-plantuml-executable-args'." +You can also configure extra arguments via `org-plantuml-args'." :group 'org-babel :package-version '(Org . "9.4") :type 'symbol @@ -116,7 +116,7 @@ This function is called by `org-babel-execute-src-block'." (let* ((do-export (member "file" (cdr (assq :result-params params)))) (out-file (if do-export (or (cdr (assq :file params)) - (error "No :file provided but :results set to file. For plain text output, set :results to verbatim")) + (error "No :file provided but :results set to file. For plain text output, set :results to verbatim")) (org-babel-temp-file "plantuml-" ".txt"))) (cmdline (cdr (assq :cmdline params))) (in-file (org-babel-temp-file "plantuml-")) @@ -143,6 +143,7 @@ This function is called by `org-babel-execute-src-block'." ("eps" '("-teps")) ("pdf" '("-tpdf")) ("tex" '("-tlatex")) + ("tikz" '("-tlatex:nopreamble")) ("vdx" '("-tvdx")) ("xmi" '("-txmi")) ("scxml" '("-tscxml")) diff --git a/elpa/org-9.6.7/ob-processing.el b/elpa/org-9.7.17/ob-processing.el similarity index 97% rename from elpa/org-9.6.7/ob-processing.el rename to elpa/org-9.7.17/ob-processing.el index 4eeaf98e..2733b1d1 100644 --- a/elpa/org-9.6.7/ob-processing.el +++ b/elpa/org-9.7.17/ob-processing.el @@ -1,6 +1,6 @@ ;;; ob-processing.el --- Babel functions for processing -*- lexical-binding: t; -*- -;; Copyright (C) 2015-2023 Free Software Foundation, Inc. +;; Copyright (C) 2015-2024 Free Software Foundation, Inc. ;; Author: Jarmo Hurri (adapted from ob-asymptote.el written by Eric Schulte) ;; Maintainer: Jarmo Hurri @@ -78,7 +78,7 @@ (defun org-babel-processing-view-sketch () "Show the sketch of the Processing block under point in an external viewer." (interactive) - (require 'processing-mode) + (org-require-package 'processing-mode) (let ((info (org-babel-get-src-block-info))) (if (string= (nth 0 info) "processing") (let* ((body (nth 1 info)) @@ -118,7 +118,7 @@ (message "Not inside a Processing source block.")))) (defun org-babel-execute:processing (body params) - "Execute a block of Processing code. + "Execute Processing code BODY according to PARAMS. This function is called by `org-babel-execute-src-block'." (let ((sketch-code (org-babel-expand-body:generic @@ -144,7 +144,8 @@ Processing does not support sessions." (error "Processing does not support sessions")) (defun org-babel-variable-assignments:processing (params) - "Return list of processing statements assigning the block's variables." + "Return list of processing statements assigning the block's variables. +The variable assignments are defined in PARAMS." (mapcar #'org-babel-processing-var-to-processing (org-babel--get-vars params))) diff --git a/elpa/org-9.7.17/ob-python.el b/elpa/org-9.7.17/ob-python.el new file mode 100644 index 00000000..9975e83b --- /dev/null +++ b/elpa/org-9.7.17/ob-python.el @@ -0,0 +1,577 @@ +;;; ob-python.el --- Babel Functions for Python -*- lexical-binding: t; -*- + +;; Copyright (C) 2009-2024 Free Software Foundation, Inc. + +;; Authors: Eric Schulte +;; Dan Davison +;; Maintainer: Jack Kamm +;; Keywords: literate programming, reproducible research +;; URL: 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 python source code. + +;;; Code: + +(require 'org-macs) +(org-assert-version) + +(require 'ob) +(require 'org-macs) +(require 'python) + +(defvar org-babel-tangle-lang-exts) +(add-to-list 'org-babel-tangle-lang-exts '("python" . "py")) + +(defvar org-babel-default-header-args:python '()) + +(defconst org-babel-header-args:python + '((return . :any) + (python . :any) + (async . ((yes no)))) + "Python-specific header arguments.") + +(defcustom org-babel-python-command 'auto + "Command (including arguments) for interactive and non-interactive Python code. +When not `auto', it overrides `org-babel-python-command-session' +and `org-babel-python-command-nonsession'." + :package-version '(Org . "9.7") + :group 'org-babel + :type '(choice string (const auto))) + +(defcustom org-babel-python-command-session 'auto + "Command (including arguments) for starting interactive Python sessions. +If `auto' (the default), uses the values from +`python-shell-interpreter' and `python-shell-interpreter-args'. +If `org-babel-python-command' is set, then it overrides this +option." + :package-version '(Org . "9.7") + :group 'org-babel + :type '(choice string (const auto))) + +(defcustom org-babel-python-command-nonsession "python" + "Command (including arguments) for executing non-interactive Python code. +If `org-babel-python-command' is set, then it overrides this option." + :package-version '(Org . "9.7") + :group 'org-babel + :type 'string) + +(defcustom org-babel-python-hline-to "None" + "Replace hlines in incoming tables with this when translating to python." + :group 'org-babel + :package-version '(Org . "8.0") + :type 'string) + +(defcustom org-babel-python-None-to 'hline + "Replace `None' in python tables with this before returning." + :group 'org-babel + :package-version '(Org . "8.0") + :type 'symbol) + +(defun org-babel-python-associate-session (session) + "Associate Python code buffer with an Python session. +Make SESSION without earmuffs be the Python buffer name." + (setq-local python-shell-buffer-name + (org-babel-python-without-earmuffs session))) + +(defun org-babel-execute:python (body params) + "Execute Python BODY according to PARAMS. +This function is called by `org-babel-execute-src-block'." + (let* ((org-babel-python-command + (or (cdr (assq :python params)) + org-babel-python-command)) + (session (org-babel-python-initiate-session + (cdr (assq :session params)))) + (graphics-file (and (member "graphics" (assq :result-params params)) + (org-babel-graphical-output-file params))) + (result-params (cdr (assq :result-params params))) + (result-type (cdr (assq :result-type params))) + (return-val (when (eq result-type 'value) + (cdr (assq :return params)))) + (preamble (cdr (assq :preamble params))) + (async (org-babel-comint-use-async params)) + (full-body + (concat + (org-babel-expand-body:generic + body params + (org-babel-variable-assignments:python params)) + (when return-val + (format (if session "\n%s" "\nreturn %s") return-val)))) + (result (org-babel-python-evaluate + session full-body result-type + result-params preamble async graphics-file))) + (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)))))) + +(defun org-babel-prep-session:python (session params) + "Prepare SESSION according to the header arguments in PARAMS. +VARS contains resolved variable references." + (let* ((session (org-babel-python-initiate-session session)) + (var-lines + (org-babel-variable-assignments:python params))) + (org-babel-comint-in-buffer session + (mapc (lambda (var) + (end-of-line 1) (insert var) (comint-send-input) + (org-babel-comint-wait-for-output session)) + var-lines)) + session)) + +(defun org-babel-load-session:python (session body params) + "Load BODY into SESSION." + (save-window-excursion + (let ((buffer (org-babel-prep-session:python session params))) + (with-current-buffer buffer + (goto-char (process-mark (get-buffer-process (current-buffer)))) + (insert (org-babel-chomp body))) + buffer))) + +;; helper functions + +(defconst org-babel-python--output-graphics-wrapper "\ +import matplotlib.pyplot +matplotlib.pyplot.gcf().clear() +%s +matplotlib.pyplot.savefig('%s')" + "Format string for saving Python graphical output. +Has two %s escapes, for the Python code to be evaluated, and the +file to save the graphics to.") + +(defconst org-babel-python--def-format-value "\ +def __org_babel_python_format_value(result, result_file, result_params): + with open(result_file, 'w') as f: + if 'graphics' in result_params: + result.savefig(result_file) + elif 'pp' in result_params: + import pprint + f.write(pprint.pformat(result)) + elif 'list' in result_params and isinstance(result, dict): + f.write(str(['{} :: {}'.format(k, v) for k, v in result.items()])) + else: + if not set(result_params).intersection(\ +['scalar', 'verbatim', 'raw']): + def dict2table(res): + if isinstance(res, dict): + return [(k, dict2table(v)) for k, v in res.items()] + elif isinstance(res, list) or isinstance(res, tuple): + return [dict2table(x) for x in res] + else: + return res + if 'table' in result_params: + result = dict2table(result) + try: + import pandas + except ImportError: + pass + else: + if isinstance(result, pandas.DataFrame) and 'table' in result_params: + result = [[result.index.name or ''] + list(result.columns)] + \ +[None] + [[i] + list(row) for i, row in result.iterrows()] + elif isinstance(result, pandas.Series) and 'table' in result_params: + result = list(result.items()) + try: + import numpy + except ImportError: + pass + else: + if isinstance(result, numpy.ndarray): + if 'table' in result_params: + result = result.tolist() + else: + result = repr(result) + f.write(str(result))" + "Python function to format value result and save it to file.") + +(defun org-babel-variable-assignments:python (params) + "Return a list of Python statements assigning the block's variables. +The assignments are defined in PARAMS." + (mapcar + (lambda (pair) + (format "%s=%s" + (car pair) + (org-babel-python-var-to-python (cdr pair)))) + (org-babel--get-vars params))) + +(defun org-babel-python-var-to-python (var) + "Convert an elisp value to a python variable. +Convert an elisp value, VAR, into a string of python source code +specifying a variable of the same value." + (if (listp var) + (concat "[" (mapconcat #'org-babel-python-var-to-python var ", ") "]") + (if (eq var 'hline) + org-babel-python-hline-to + (format + (if (and (stringp var) (string-match "[\n\r]" var)) "\"\"%S\"\"" "%S") + (if (stringp var) (substring-no-properties var) var))))) + +(defun org-babel-python-table-or-string (results) + "Convert RESULTS into an appropriate elisp value. +If the results look like a list or tuple (but not a dict), then +convert them into an Emacs-lisp table. Otherwise return the +results as a string." + (let ((res (if (and (> (length results) 0) + (string-equal "{" (substring results 0 1))) + results ;don't convert dicts to elisp + (org-babel-script-escape results)))) + (if (listp res) + (mapcar (lambda (el) (if (eq el 'None) + org-babel-python-None-to el)) + res) + res))) + +(defvar org-babel-python-buffers '((:default . "*Python*"))) + +(defun org-babel-python-session-buffer (session) + "Return the buffer associated with SESSION." + (cdr (assoc session org-babel-python-buffers))) + +(defun org-babel-python-with-earmuffs (session) + "Return SESSION name as string, ensuring *...* around." + (let ((name (if (stringp session) session (format "%s" session)))) + (if (and (string= "*" (substring name 0 1)) + (string= "*" (substring name (- (length name) 1)))) + name + (format "*%s*" name)))) + +(defun org-babel-python-without-earmuffs (session) + "Return SESSION name as string, without *...* around." + (let ((name (if (stringp session) session (format "%s" session)))) + (if (and (string= "*" (substring name 0 1)) + (string= "*" (substring name (- (length name) 1)))) + (substring name 1 (- (length name) 1)) + name))) + +(defun org-babel-session-buffer:python (session &optional _) + "Return session buffer name for SESSION." + (or (org-babel-python-session-buffer session) + (org-babel-python-with-earmuffs session))) + +(defun org-babel-python--python-util-comint-end-of-output-p () + "Return non-nil if the last prompt matches input prompt. +Backport of `python-util-comint-end-of-output-p' to emacs28. To +be removed after minimum supported version reaches emacs29." + (when-let* ((prompt (python-util-comint-last-prompt))) + (python-shell-comint-end-of-output-p + (buffer-substring-no-properties + (car prompt) (cdr prompt))))) + +(defun org-babel-python--command (is-session) + "Helper function to return the Python command. +This checks `org-babel-python-command', and then +`org-babel-python-command-session' (if IS-SESSION) or +`org-babel-python-command-nonsession' (if not IS-SESSION). If +IS-SESSION, this might return nil, which means to use +`python-shell-calculate-command'." + (or (unless (eq org-babel-python-command 'auto) + org-babel-python-command) + (if is-session + (unless (eq org-babel-python-command-session 'auto) + org-babel-python-command-session) + org-babel-python-command-nonsession))) + +(defvar-local org-babel-python--initialized nil + "Flag used to mark that python session has been initialized.") +(defun org-babel-python--setup-session () + "Babel Python session setup code, to be run once per session. +Function should be run from within the Python session buffer. +This is often run as a part of `python-shell-first-prompt-hook', +unless the Python session was created outside Org." + (python-shell-send-string-no-output org-babel-python--def-format-value) + (setq-local org-babel-python--initialized t)) +(defun org-babel-python-initiate-session-by-key (&optional session) + "Initiate a python session. +If there is not a current inferior-process-buffer matching +SESSION then create it. If inferior process already +exists (e.g. if it was manually started with `run-python'), make +sure it's configured to work with ob-python. If session has +already been configured as such, do nothing. Return the +initialized session." + (save-window-excursion + (let* ((session (if session (intern session) :default)) + (py-buffer (org-babel-session-buffer:python session)) + (python-shell-buffer-name + (org-babel-python-without-earmuffs py-buffer)) + (existing-session-p (comint-check-proc py-buffer)) + (cmd (org-babel-python--command t))) + (if cmd + (let* ((cmd-split (split-string-and-unquote cmd)) + (python-shell-interpreter (car cmd-split)) + (python-shell-interpreter-args + (combine-and-quote-strings + (append (cdr cmd-split) + (when (member system-type + '(cygwin windows-nt ms-dos)) + (list "-i")))))) + (run-python)) + (run-python)) + (with-current-buffer py-buffer + (if existing-session-p + ;; Session was created outside Org. Assume first prompt + ;; already happened; run session setup code directly + (unless org-babel-python--initialized + ;; Ensure first prompt. Based on python-tests.el + ;; (`python-tests-shell-wait-for-prompt') + (while (not (org-babel-python--python-util-comint-end-of-output-p)) + (sit-for 0.1)) + (org-babel-python--setup-session)) + ;; Adding to `python-shell-first-prompt-hook' immediately + ;; after `run-python' should be safe from race conditions, + ;; because subprocess output only arrives when Emacs is + ;; waiting (see elisp manual, "Output from Processes") + (add-hook + 'python-shell-first-prompt-hook + #'org-babel-python--setup-session + nil 'local))) + ;; Wait until Python initializes + ;; This is more reliable compared to + ;; `org-babel-comint-wait-for-output' as python may emit + ;; multiple prompts during initialization. + (with-current-buffer py-buffer + (while (not org-babel-python--initialized) + (sleep-for 0.010))) + (setq org-babel-python-buffers + (cons (cons session py-buffer) + (assq-delete-all session org-babel-python-buffers))) + session))) + +(defun org-babel-python-initiate-session (&optional session _params) + "Initiate Python session named SESSION according to PARAMS. +If there is not a current inferior-process-buffer matching +SESSION then create it. If inferior process already +exists (e.g. if it was manually started with `run-python'), make +sure it's configured to work with ob-python. If session has +already been configured as such, do nothing." + (unless (string= session "none") + (org-babel-python-session-buffer + (org-babel-python-initiate-session-by-key session)))) + +(defvar org-babel-python-eoe-indicator "org_babel_python_eoe" + "A string to indicate that evaluation has completed.") + +(defun org-babel-python-format-session-value + (src-file result-file result-params) + "Return Python code to evaluate SRC-FILE and write result to RESULT-FILE. +RESULT-PARAMS defines the result type." + (format "\ +import ast +with open('%s') as __org_babel_python_tmpfile: + __org_babel_python_ast = ast.parse(__org_babel_python_tmpfile.read()) +__org_babel_python_final = __org_babel_python_ast.body[-1] +if isinstance(__org_babel_python_final, ast.Expr): + __org_babel_python_ast.body = __org_babel_python_ast.body[:-1] + exec(compile(__org_babel_python_ast, '', 'exec')) + __org_babel_python_final = eval(compile(ast.Expression( + __org_babel_python_final.value), '', 'eval')) +else: + exec(compile(__org_babel_python_ast, '', 'exec')) + __org_babel_python_final = None +__org_babel_python_format_value(__org_babel_python_final, '%s', %s)" + (org-babel-process-file-name src-file 'noquote) + (org-babel-process-file-name result-file 'noquote) + (org-babel-python-var-to-python result-params))) + +(defun org-babel-python-evaluate + (session body &optional result-type result-params preamble async graphics-file) + "Evaluate BODY as Python code." + (if session + (if async + (org-babel-python-async-evaluate-session + session body result-type result-params graphics-file) + (org-babel-python-evaluate-session + session body result-type result-params graphics-file)) + (org-babel-python-evaluate-external-process + body result-type result-params preamble graphics-file))) + +(defun org-babel-python--shift-right (body &optional count) + (with-temp-buffer + (python-mode) + (insert body) + (goto-char (point-min)) + (while (not (eobp)) + (unless (python-syntax-context 'string) + (python-indent-shift-right (line-beginning-position) + (line-end-position) + count)) + (forward-line 1)) + (buffer-string))) + +(defun org-babel-python-evaluate-external-process + (body &optional result-type result-params preamble graphics-file) + "Evaluate BODY in external python 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. If GRAPHICS-FILE is +non-nil, then save graphical results to that file instead." + (let ((raw + (pcase result-type + (`output (org-babel-eval (org-babel-python--command nil) + (concat preamble (and preamble "\n") + (if graphics-file + (format org-babel-python--output-graphics-wrapper + body graphics-file) + body)))) + (`value (let ((results-file (or graphics-file + (org-babel-temp-file "python-")))) + (org-babel-eval (org-babel-python--command nil) + (concat + preamble (and preamble "\n") + (format + (concat org-babel-python--def-format-value " +def main(): +%s + +__org_babel_python_format_value(main(), '%s', %s)") + (org-babel-python--shift-right body) + (org-babel-process-file-name results-file 'noquote) + (org-babel-python-var-to-python result-params)))) + (org-babel-eval-read-file results-file)))))) + (org-babel-result-cond result-params + raw + (org-babel-python-table-or-string raw)))) + +(defun org-babel-python-send-string (session body) + "Pass BODY to the Python process in SESSION. +Return output." + (with-current-buffer session + (let* ((string-buffer "") + (comint-output-filter-functions + (cons (lambda (text) (setq string-buffer + (concat string-buffer text))) + comint-output-filter-functions)) + (body (format "\ +try: +%s +except: + raise +finally: + print('%s')" + (org-babel-python--shift-right body 4) + org-babel-python-eoe-indicator))) + (let ((python-shell-buffer-name + (org-babel-python-without-earmuffs session))) + (python-shell-send-string body)) + ;; same as `python-shell-comint-end-of-output-p' in emacs-25.1+ + (while (not (and (python-shell-comint-end-of-output-p string-buffer) + (string-match + org-babel-python-eoe-indicator + string-buffer))) + (accept-process-output (get-buffer-process (current-buffer)))) + (org-babel-chomp (substring string-buffer 0 (match-beginning 0)))))) + +(defun org-babel-python-evaluate-session + (session body &optional result-type result-params graphics-file) + "Pass BODY to the Python process in SESSION. +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. If GRAPHICS-FILE is +non-nil, then save graphical results to that file instead." + (let* ((tmp-src-file (org-babel-temp-file "python-")) + (results + (progn + (with-temp-file tmp-src-file + (insert (if (and graphics-file (eq result-type 'output)) + (format org-babel-python--output-graphics-wrapper + body graphics-file) + body))) + (pcase result-type + (`output + (let ((body (format "\ +with open('%s') as f: + exec(compile(f.read(), f.name, 'exec'))" + (org-babel-process-file-name + tmp-src-file 'noquote)))) + (org-babel-python-send-string session body))) + (`value + (let* ((results-file (or graphics-file + (org-babel-temp-file "python-"))) + (body (org-babel-python-format-session-value + tmp-src-file results-file result-params))) + (org-babel-python-send-string session body) + (sleep-for 0.010) + (org-babel-eval-read-file results-file))))))) + (org-babel-result-cond result-params + results + (org-babel-python-table-or-string results)))) + +(defun org-babel-python-read-string (string) + "Strip \\='s from around Python STRING." + (if (and (string-prefix-p "'" string) + (string-suffix-p "'" string)) + (substring string 1 -1) + string)) + +;; Async session eval + +(defconst org-babel-python-async-indicator "print ('ob_comint_async_python_%s_%s')") + +(defun org-babel-python-async-value-callback (params tmp-file) + (let ((result-params (cdr (assq :result-params params))) + (results (org-babel-eval-read-file tmp-file))) + (org-babel-result-cond result-params + results + (org-babel-python-table-or-string results)))) + +(defun org-babel-python-async-evaluate-session + (session body &optional result-type result-params graphics-file) + "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) + "ob_comint_async_python_\\(start\\|end\\|file\\)_\\(.+\\)" + 'org-babel-chomp 'org-babel-python-async-value-callback + 'disable-prompt-filtering) + (pcase result-type + (`output + (let ((uuid (org-id-uuid))) + (with-temp-buffer + (insert (format org-babel-python-async-indicator "start" uuid)) + (insert "\n") + (insert (if graphics-file + (format org-babel-python--output-graphics-wrapper + body graphics-file) + body)) + (insert "\n") + (insert (format org-babel-python-async-indicator "end" uuid)) + (let ((python-shell-buffer-name + (org-babel-python-without-earmuffs session))) + (python-shell-send-buffer))) + uuid)) + (`value + (let ((results-file (or graphics-file + (org-babel-temp-file "python-"))) + (tmp-src-file (org-babel-temp-file "python-"))) + (with-temp-file tmp-src-file (insert body)) + (with-temp-buffer + (insert (org-babel-python-format-session-value + tmp-src-file results-file result-params)) + (insert "\n") + (unless graphics-file + (insert (format org-babel-python-async-indicator "file" results-file))) + (let ((python-shell-buffer-name + (org-babel-python-without-earmuffs session))) + (python-shell-send-buffer))) + results-file)))) + +(provide 'ob-python) + +;;; ob-python.el ends here diff --git a/elpa/org-9.6.7/ob-ref.el b/elpa/org-9.7.17/ob-ref.el similarity index 95% rename from elpa/org-9.6.7/ob-ref.el rename to elpa/org-9.7.17/ob-ref.el index 2eae3690..f6327a36 100644 --- a/elpa/org-9.6.7/ob-ref.el +++ b/elpa/org-9.7.17/ob-ref.el @@ -1,6 +1,6 @@ ;;; ob-ref.el --- Babel Functions for Referencing External Data -*- lexical-binding: t; -*- -;; Copyright (C) 2009-2023 Free Software Foundation, Inc. +;; Copyright (C) 2009-2024 Free Software Foundation, Inc. ;; Authors: Eric Schulte ;; Dan Davison @@ -59,8 +59,9 @@ (declare-function org-babel-lob-get-info "ob-lob" (&optional datum no-eval)) (declare-function org-element-at-point "org-element" (&optional pom cached-only)) -(declare-function org-element-property "org-element" (property element)) -(declare-function org-element-type "org-element" (element)) +(declare-function org-element-property "org-element-ast" (property node)) +(declare-function org-element-post-affiliated "org-element" (node)) +(declare-function org-element-type "org-element-ast" (node &optional anonymous)) (declare-function org-end-of-meta-data "org" (&optional full)) (declare-function org-find-property "org" (property &optional value)) (declare-function org-id-find-id-file "org-id" (id)) @@ -155,8 +156,9 @@ Emacs Lisp representation of the value of the variable." (when (string-match "^\\(.+\\):\\(.+\\)$" ref) (setq split-file (match-string 1 ref)) (setq split-ref (match-string 2 ref)) - (find-file split-file) - (setq ref split-ref)) + (when (file-exists-p split-file) + (find-file split-file) + (setq ref split-ref))) (org-with-wide-buffer (goto-char (point-min)) (let* ((params (append args '((:results . "none")))) @@ -171,7 +173,7 @@ Emacs Lisp representation of the value of the variable." (let ((e (org-element-at-point))) (when (equal (org-element-property :name e) ref) (goto-char - (org-element-property :post-affiliated e)) + (org-element-post-affiliated e)) (pcase (org-element-type e) (`babel-call (throw :found diff --git a/elpa/org-9.6.7/ob-ruby.el b/elpa/org-9.7.17/ob-ruby.el similarity index 85% rename from elpa/org-9.6.7/ob-ruby.el rename to elpa/org-9.7.17/ob-ruby.el index b94bc73d..d920fb58 100644 --- a/elpa/org-9.6.7/ob-ruby.el +++ b/elpa/org-9.7.17/ob-ruby.el @@ -1,6 +1,6 @@ ;;; ob-ruby.el --- Babel Functions for Ruby -*- lexical-binding: t; -*- -;; Copyright (C) 2009-2023 Free Software Foundation, Inc. +;; Copyright (C) 2009-2024 Free Software Foundation, Inc. ;; Author: Eric Schulte ;; Keywords: literate programming, reproducible research @@ -73,7 +73,7 @@ It's possible to override it by using a header argument `:ruby'") :type 'symbol) (defun org-babel-execute:ruby (body params) - "Execute a block of Ruby code with Babel. + "Execute Ruby BODY according to PARAMS. This function is called by `org-babel-execute-src-block'." (let* ((session (org-babel-ruby-initiate-session (cdr (assq :session params)) params)) @@ -86,7 +86,7 @@ This function is called by `org-babel-execute-src-block'." body params (org-babel-variable-assignments:ruby params))) (result (if (member "xmp" result-params) (with-temp-buffer - (require 'rcodetools) + (org-require-package 'rcodetools "rcodetools (gem package)") (insert full-body) (xmp (cdr (assq :xmp-option params))) (buffer-string)) @@ -127,7 +127,8 @@ This function is called by `org-babel-execute-src-block'." ;; helper functions (defun org-babel-variable-assignments:ruby (params) - "Return list of ruby statements assigning the block's variables." + "Return list of ruby statements assigning the block's variables. +The assignments are defined in PARAMS." (mapcar (lambda (pair) (format "%s=%s" @@ -140,7 +141,7 @@ This function is called by `org-babel-execute-src-block'." Convert an elisp value into a string of ruby source code specifying a variable of the same value." (if (listp var) - (concat "[" (mapconcat #'org-babel-ruby-var-to-ruby var ", ") "]") + (concat "[" (mapconcat #'org-babel-ruby-var-to-ruby var ", \n") "]") (if (eq var 'hline) org-babel-ruby-hline-to (format "%S" var)))) @@ -152,20 +153,28 @@ Emacs-lisp table, otherwise return the results as a string." (let ((res (org-babel-script-escape results))) (if (listp res) (mapcar (lambda (el) (if (not el) - org-babel-ruby-nil-to el)) + org-babel-ruby-nil-to el)) res) res))) +(defvar org-babel-ruby-prompt "_org_babel_ruby_prompt " + "String used for unique prompt.") + +(defvar org-babel-ruby-define-prompt + (format "IRB.conf[:PROMPT][:CUSTOM] = { :PROMPT_I => \"%s\" }" org-babel-ruby-prompt)) + (defun org-babel-ruby-initiate-session (&optional session params) "Initiate a ruby session. If there is not a current inferior-process-buffer in SESSION -then create one. Return the initialized session." +then create one. Return the initialized session. +Session settings (`:ruby' header arg value) are taken from PARAMS." (unless (string= session "none") - (require 'inf-ruby) + (org-require-package 'inf-ruby) (let* ((command (cdr (or (assq :ruby params) (assoc inf-ruby-default-implementation inf-ruby-implementations)))) (buffer (get-buffer (format "*%s*" session))) + (new-session? (not buffer)) (session-buffer (or buffer (save-window-excursion (run-ruby-or-pop-to-buffer (if (functionp command) @@ -176,16 +185,32 @@ then create one. Return the initialized session." (inf-ruby-buffer))) (current-buffer))))) (if (org-babel-comint-buffer-livep session-buffer) - (progn (sit-for .25) session-buffer) + (progn + (sit-for .25) + ;; Setup machine-readable prompt: no echo, prompts matching + ;; uniquely by regexp. + (when new-session? + (with-current-buffer session-buffer + (setq-local + org-babel-comint-prompt-regexp-old comint-prompt-regexp + comint-prompt-regexp (concat "^" org-babel-ruby-prompt)) + (insert org-babel-ruby-define-prompt ";") + (insert "_org_prompt_mode=conf.prompt_mode;conf.prompt_mode=:CUSTOM;") + (insert "conf.echo=false\n") + (comint-send-input nil t))) + session-buffer) (sit-for .5) (org-babel-ruby-initiate-session session))))) (defvar org-babel-ruby-eoe-indicator ":org_babel_ruby_eoe" "String to indicate that evaluation has completed.") + (defvar org-babel-ruby-f-write "File.open('%s','w'){|f| f.write((_.class == String) ? _ : _.inspect)}") + (defvar org-babel-ruby-pp-f-write "File.open('%s','w'){|f| $stdout = f; pp(results); $stdout = orig_out}") + (defvar org-babel-ruby-wrapper-method " def main() @@ -194,6 +219,7 @@ end results = main() File.open('%s', 'w'){ |f| f.write((results.class == String) ? results : results.inspect) } ") + (defvar org-babel-ruby-pp-wrapper-method " require 'pp' @@ -237,7 +263,6 @@ return the value of the last statement in BODY, as elisp." (org-babel-comint-with-output (buffer org-babel-ruby-eoe-indicator t eoe-string) (insert eoe-string) (comint-send-input nil t)) - ;; Now we can start the evaluation. (mapconcat #'identity (butlast @@ -246,14 +271,9 @@ return the value of the last statement in BODY, as elisp." #'org-trim (org-babel-comint-with-output (buffer org-babel-ruby-eoe-indicator t body) - (mapc - (lambda (line) - (insert (org-babel-chomp line)) (comint-send-input nil t)) - (list "conf.echo=false;_org_prompt_mode=conf.prompt_mode;conf.prompt_mode=:NULL" - body - "conf.prompt_mode=_org_prompt_mode;conf.echo=true" - eoe-string))) - "\n") "[\r\n]") 4) "\n"))) + (insert (org-babel-chomp body) "\n" eoe-string) + (comint-send-input nil t)) + "\n") "[\r\n]")) "\n"))) (`value (let* ((tmp-file (org-babel-temp-file "ruby-")) (ppp (or (member "code" result-params) @@ -273,7 +293,7 @@ return the value of the last statement in BODY, as elisp." "results=_" "require 'pp'" "orig_out = $stdout" (format org-babel-ruby-pp-f-write (org-babel-process-file-name tmp-file 'noquote)))) - (list org-babel-ruby-eoe-indicator))) + (list (format "puts \"%s\"" org-babel-ruby-eoe-indicator)))) (comint-send-input nil t)) (org-babel-eval-read-file tmp-file)))))) diff --git a/elpa/org-9.6.7/ob-sass.el b/elpa/org-9.7.17/ob-sass.el similarity index 97% rename from elpa/org-9.6.7/ob-sass.el rename to elpa/org-9.7.17/ob-sass.el index 1498b931..a6b4a646 100644 --- a/elpa/org-9.6.7/ob-sass.el +++ b/elpa/org-9.7.17/ob-sass.el @@ -1,6 +1,6 @@ ;;; ob-sass.el --- Babel Functions for the Sass CSS generation language -*- lexical-binding: t; -*- -;; Copyright (C) 2009-2023 Free Software Foundation, Inc. +;; Copyright (C) 2009-2024 Free Software Foundation, Inc. ;; Author: Eric Schulte ;; Keywords: literate programming, reproducible research diff --git a/elpa/org-9.6.7/ob-scheme.el b/elpa/org-9.7.17/ob-scheme.el similarity index 68% rename from elpa/org-9.6.7/ob-scheme.el rename to elpa/org-9.7.17/ob-scheme.el index ef41a2ec..29fdcd1e 100644 --- a/elpa/org-9.6.7/ob-scheme.el +++ b/elpa/org-9.7.17/ob-scheme.el @@ -1,6 +1,6 @@ ;;; ob-scheme.el --- Babel Functions for Scheme -*- lexical-binding: t; -*- -;; Copyright (C) 2010-2023 Free Software Foundation, Inc. +;; Copyright (C) 2010-2024 Free Software Foundation, Inc. ;; Authors: Eric Schulte ;; Michael Gauland @@ -54,7 +54,7 @@ (defvar geiser-debug-jump-to-debug-p) ; Defined in geiser-debug.el (defvar geiser-repl-use-other-window) ; Defined in geiser-repl.el (defvar geiser-repl-window-allow-split) ; Defined in geiser-repl.el - +(declare-function geiser-connect "ext:geiser-repl" (impl &optional host port)) (declare-function run-geiser "ext:geiser-repl" (impl)) (declare-function geiser "ext:geiser-repl" (impl)) (declare-function geiser-mode "ext:geiser-mode" ()) @@ -65,6 +65,9 @@ (declare-function geiser-repl-exit "ext:geiser-repl" (&optional arg)) (declare-function geiser-eval--retort-output "ext:geiser-eval" (ret)) (declare-function geiser-eval--retort-result-str "ext:geiser-eval" (ret prefix)) +(declare-function geiser-eval--retort-error "ext:geiser-eval" (ret)) +(declare-function geiser-eval--retort-error-msg "ext:geiser-eval" (err)) +(declare-function geiser-eval--error-msg "ext:geiser-eval" (err)) (defcustom org-babel-scheme-null-to 'hline "Replace `null' and empty lists in scheme tables with this before returning." @@ -75,6 +78,17 @@ (defvar org-babel-default-header-args:scheme '() "Default header arguments for scheme code blocks.") +(defconst org-babel-header-args:scheme '((host . :any) + (port . :any)) + "Header arguments supported in Scheme.") + +(defun org-babel-scheme-expand-header-arg-vars (vars) + "Expand :var header arguments given as VARS." + (mapconcat + (lambda (var) + (format "(define %S %S)" (car var) (cdr var))) + vars + "\n")) (defun org-babel-expand-body:scheme (body params) "Expand BODY according to PARAMS, return the expanded body." @@ -83,13 +97,7 @@ (postpends (cdr (assq :epilogue params)))) (concat (and prepends (concat prepends "\n")) (if (null vars) body - (format "(let (%s)\n%s\n)" - (mapconcat - (lambda (var) - (format "%S" (print `(,(car var) ',(cdr var))))) - vars - "\n ") - body)) + (concat (org-babel-scheme-expand-header-arg-vars vars) "\n" body)) (and postpends (concat "\n" postpends))))) @@ -116,13 +124,17 @@ (with-current-buffer (set-buffer buffer) geiser-impl--implementation)) -(defun org-babel-scheme-get-repl (impl name) - "Switch to a scheme REPL, creating it if it doesn't exist." +(defun org-babel-scheme-get-repl (impl name &optional host port) + "Switch to a Scheme REPL, creating it if it doesn't exist. + +If the variables HOST and PORT are set, connect to the running Scheme REPL." (let ((buffer (org-babel-scheme-get-session-buffer name))) (or buffer (progn (if (fboundp 'geiser) - (geiser impl) + (if (and host port) + (geiser-connect impl host port) + (geiser impl)) ;; Obsolete since Geiser 0.26. (run-geiser impl)) (when name @@ -131,14 +143,14 @@ (current-buffer))))) (defun org-babel-scheme-make-session-name (buffer name impl) - "Generate a name for the session buffer. + "Generate a NAME for the session BUFFER. For a named session, the buffer name will be the session name. If the session is unnamed (nil), generate a name. If the session is `none', use nil for the session name, and -org-babel-scheme-execute-with-geiser will use a temporary session." +`org-babel-scheme-execute-with-geiser' will use a temporary session." (cond ((not name) (concat buffer " " (symbol-name impl) " REPL")) ((string= name "none") nil) (name))) @@ -159,7 +171,7 @@ org-babel-scheme-execute-with-geiser will use a temporary session." ,@body (current-message)))) -(defun org-babel-scheme-execute-with-geiser (code output impl repl) +(defun org-babel-scheme-execute-with-geiser (code output impl repl &optional host port) "Execute code in specified REPL. If the REPL doesn't exist, create it using the given scheme implementation. @@ -170,45 +182,58 @@ is true; otherwise returns the last value." (with-temp-buffer (insert (format ";; -*- geiser-scheme-implementation: %s -*-" impl)) (newline) - (insert code) - (geiser-mode) - (let ((geiser-repl-window-allow-split nil) - (geiser-repl-use-other-window nil)) - (let ((repl-buffer (save-current-buffer - (org-babel-scheme-get-repl impl repl)))) - (when (not (eq impl (org-babel-scheme-get-buffer-impl + (let ((beg (point))) + (insert code) + (geiser-mode) + (let ((geiser-repl-window-allow-split nil) + (geiser-repl-use-other-window nil)) + (let ((repl-buffer (save-current-buffer + (org-babel-scheme-get-repl impl repl host port)))) + (when (not (eq impl (org-babel-scheme-get-buffer-impl (current-buffer)))) - (message "Implementation mismatch: %s (%s) %s (%s)" impl (symbolp impl) - (org-babel-scheme-get-buffer-impl (current-buffer)) - (symbolp (org-babel-scheme-get-buffer-impl - (current-buffer))))) - (setq geiser-repl--repl repl-buffer) - (setq geiser-impl--implementation nil) - (let ((geiser-debug-jump-to-debug-p nil) - (geiser-debug-show-debug-p nil)) - ;; `geiser-eval-region/wait' was introduced to await the - ;; result of async evaluation in geiser version 0.22. - (let ((ret (funcall (if (fboundp 'geiser-eval-region/wait) - #'geiser-eval-region/wait - #'geiser-eval-region) - (point-min) - (point-max)))) - (setq result (if output - (or (geiser-eval--retort-output ret) - "Geiser Interpreter produced no output") - (geiser-eval--retort-result-str ret ""))))) - (when (not repl) - (save-current-buffer (set-buffer repl-buffer) - (geiser-repl-exit)) - (set-process-query-on-exit-flag (get-buffer-process repl-buffer) nil) - (kill-buffer repl-buffer))))) + (message "Implementation mismatch: %s (%s) %s (%s)" impl (symbolp impl) + (org-babel-scheme-get-buffer-impl (current-buffer)) + (symbolp (org-babel-scheme-get-buffer-impl + (current-buffer))))) + (setq geiser-repl--repl repl-buffer) + (setq geiser-impl--implementation nil) + (let ((geiser-debug-jump-to-debug-p nil) + (geiser-debug-show-debug-p nil)) + ;; `geiser-eval-region/wait' was introduced to await the + ;; result of async evaluation in geiser version 0.22. + (let ((ret (funcall (if (fboundp 'geiser-eval-region/wait) + #'geiser-eval-region/wait + #'geiser-eval-region) + ;; Do not include top comment into evaluation. + ;; Apparently, mit-scheme has + ;; problems with the top comment we add: + ;; "Unexpected read restart on: #[textual-i/o-port 27 for console]" + beg + (point-max)))) + (let ((err (geiser-eval--retort-error ret))) + (setq result (cond + (output + (or (geiser-eval--retort-output ret) + "Geiser Interpreter produced no output")) + (err nil) + (t (geiser-eval--retort-result-str ret "")))) + (when (not repl) + (save-current-buffer (set-buffer repl-buffer) + (geiser-repl-exit)) + (set-process-query-on-exit-flag (get-buffer-process repl-buffer) nil) + (kill-buffer repl-buffer)) + (when err + (let ((msg (geiser-eval--error-msg err))) + (org-babel-eval-error-notify + nil + (concat (if (listp msg) (car msg) msg) "\n"))))))))))) result)) (defun org-babel-scheme--table-or-string (results) "Convert RESULTS into an appropriate elisp value. If the results look like a list or tuple, then convert them into an Emacs-lisp table, otherwise return the results as a string." - (let ((res (org-babel-script-escape results))) + (let ((res (and results (org-babel-script-escape results)))) (cond ((listp res) (mapcar (lambda (el) (if (or (null el) (eq el 'null)) @@ -231,6 +256,8 @@ This function is called by `org-babel-execute-src-block'." geiser-scheme-implementation geiser-default-implementation (car geiser-active-implementations))) + (host (cdr (assq :host params))) + (port (cdr (assq :port params))) (session (org-babel-scheme-make-session-name source-buffer-name (cdr (assq :session params)) impl)) (full-body (org-babel-expand-body:scheme body params)) @@ -240,7 +267,9 @@ This function is called by `org-babel-execute-src-block'." full-body ; code (string= result-type "output") ; output? impl ; implementation - (and (not (string= session "none")) session)))) ; session + (and (not (string= session "none")) session) ; session + host ; REPL host + port))) ; REPL port (let ((table (org-babel-reassemble-table result diff --git a/elpa/org-9.6.7/ob-screen.el b/elpa/org-9.7.17/ob-screen.el similarity index 94% rename from elpa/org-9.6.7/ob-screen.el rename to elpa/org-9.7.17/ob-screen.el index 269538e7..a56afc70 100644 --- a/elpa/org-9.6.7/ob-screen.el +++ b/elpa/org-9.7.17/ob-screen.el @@ -1,6 +1,6 @@ ;;; ob-screen.el --- Babel Support for Interactive Terminal -*- lexical-binding: t; -*- -;; Copyright (C) 2009-2023 Free Software Foundation, Inc. +;; Copyright (C) 2009-2024 Free Software Foundation, Inc. ;; Author: Benjamin Andresen ;; Maintainer: Ken Mankoff @@ -50,9 +50,9 @@ In case you want to use a different screen than one selected by your $PATH") "Default arguments to use when running screen source blocks.") (defun org-babel-execute:screen (body params) - "Send a block of code via screen to a terminal using Babel. -\"default\" session is used when none is specified." - (message "Sending source code block to interactive terminal session...") + "Send BODY via screen to a terminal using Babel, according to PARAMS. +\"default\" session is used when none is specified in the PARAMS." + (unless noninteractive (message "Sending source code block to interactive terminal session...")) (save-window-excursion (let* ((session (cdr (assq :session params))) (socket (org-babel-screen-session-socketname session))) diff --git a/elpa/org-9.6.7/ob-sed.el b/elpa/org-9.7.17/ob-sed.el similarity index 96% rename from elpa/org-9.6.7/ob-sed.el rename to elpa/org-9.7.17/ob-sed.el index 6469901f..83d9684a 100644 --- a/elpa/org-9.6.7/ob-sed.el +++ b/elpa/org-9.7.17/ob-sed.el @@ -1,6 +1,6 @@ ;;; ob-sed.el --- Babel Functions for Sed Scripts -*- lexical-binding: t; -*- -;; Copyright (C) 2015-2023 Free Software Foundation, Inc. +;; Copyright (C) 2015-2024 Free Software Foundation, Inc. ;; Author: Bjarte Johansen ;; Keywords: literate programming, reproducible research @@ -65,7 +65,7 @@ BODY is the source inside a sed source block and PARAMS is an association list over the source block configurations. This function is called by `org-babel-execute-src-block'." - (message "Executing sed source code block") + (unless noninteractive (message "Executing sed source code block")) (let* ((result-params (cdr (assq :result-params params))) (cmd-line (cdr (assq :cmd-line params))) (in-file (cdr (assq :in-file params))) diff --git a/elpa/org-9.6.7/ob-shell.el b/elpa/org-9.7.17/ob-shell.el similarity index 73% rename from elpa/org-9.6.7/ob-shell.el rename to elpa/org-9.7.17/ob-shell.el index 2c30a260..1f3c0f9c 100644 --- a/elpa/org-9.6.7/ob-shell.el +++ b/elpa/org-9.7.17/ob-shell.el @@ -1,8 +1,9 @@ ;;; ob-shell.el --- Babel Functions for Shell Evaluation -*- lexical-binding: t; -*- -;; Copyright (C) 2009-2023 Free Software Foundation, Inc. +;; Copyright (C) 2009-2024 Free Software Foundation, Inc. ;; Author: Eric Schulte +;; Maintainer: Matthew Trzcinski ;; Keywords: literate programming, reproducible research ;; URL: https://orgmode.org @@ -44,6 +45,11 @@ (declare-function orgtbl-to-generic "org-table" (table params)) (defvar org-babel-default-header-args:shell '()) + +(defconst org-babel-header-args:shell + '((async . ((yes no)))) + "Shell-specific header arguments.") + (defvar org-babel-shell-names) (defconst org-babel-shell-set-prompt-commands @@ -51,8 +57,6 @@ ("fish" . "function fish_prompt\n\techo \"%s\"\nend") ;; prompt2 is like PS2 in POSIX shells. ("csh" . "set prompt=\"%s\"\nset prompt2=\"\"") - ;; PowerShell, similar to fish, does not have PS2 equivalent. - ("posh" . "function prompt { \"%s\" }") ;; PROMPT_COMMAND can override PS1 settings. Disable it. ;; Disable PS2 to avoid garbage in multi-line inputs. (t . "PROMPT_COMMAND=;PS1=\"%s\";PS2=")) @@ -66,28 +70,32 @@ that will be called with a single additional argument: prompt string. The fallback association template is defined in (t . \"template\") alist element.") -(defvar org-babel-prompt-command) - (defun org-babel-shell-initialize () "Define execution functions associated to shell names. This function has to be called whenever `org-babel-shell-names' is modified outside the Customize interface." (interactive) (dolist (name org-babel-shell-names) - (eval `(defun ,(intern (concat "org-babel-execute:" name)) - (body params) - ,(format "Execute a block of %s commands with Babel." name) - (let ((shell-file-name ,name) - (org-babel-prompt-command - (or (cdr (assoc ,name org-babel-shell-set-prompt-commands)) - (alist-get t org-babel-shell-set-prompt-commands)))) - (org-babel-execute:shell body params)))) - (eval `(defalias ',(intern (concat "org-babel-variable-assignments:" name)) - 'org-babel-variable-assignments:shell - ,(format "Return list of %s statements assigning to the block's \ + (let ((fname (intern (concat "org-babel-execute:" name)))) + (defalias fname + (lambda (body params) + (:documentation + (format "Execute a block of %s commands with Babel." name)) + (let ((explicit-shell-file-name name) + (shell-file-name name)) + (org-babel-execute:shell body params)))) + (put fname 'definition-name 'org-babel-shell-initialize)) + (defalias (intern (concat "org-babel-variable-assignments:" name)) + #'org-babel-variable-assignments:shell + (format "Return list of %s statements assigning to the block's \ variables." - name))) - (eval `(defvar ,(intern (concat "org-babel-default-header-args:" name)) '())))) + name)) + (funcall (if (fboundp 'defvar-1) #'defvar-1 #'set) ;Emacs-29 + (intern (concat "org-babel-default-header-args:" name)) + org-babel-default-header-args:shell) + (funcall (if (fboundp 'defvar-1) #'defvar-1 #'set) ;Emacs-29 + (intern (concat "org-babel-header-args:" name)) + org-babel-header-args:shell))) (defcustom org-babel-shell-names '("sh" "bash" "zsh" "fish" "csh" "ash" "dash" "ksh" "mksh" "posh") @@ -114,7 +122,7 @@ a shell execution being its exit code." :package-version '(Org . "9.4")) (defun org-babel-execute:shell (body params) - "Execute a block of Shell commands with Babel. + "Execute Shell BODY according to PARAMS. This function is called by `org-babel-execute-src-block'." (let* ((session (org-babel-sh-initiate-session (cdr (assq :session params)))) @@ -166,6 +174,11 @@ This function is called by `org-babel-execute-src-block'." "Return a list of statements declaring the values as a generic variable." (format "%s=%s" varname (org-babel-sh-var-to-sh values sep hline))) +(defun org-babel--variable-assignments:fish + (varname values &optional sep hline) + "Return a list of statements declaring the values as a fish variable." + (format "set %s %s" varname (org-babel-sh-var-to-sh values sep hline))) + (defun org-babel--variable-assignments:bash_array (varname values &optional sep hline) "Return a list of statements declaring the values as a bash array." @@ -211,8 +224,11 @@ This function is called by `org-babel-execute-src-block'." (if (string-suffix-p "bash" shell-file-name) (org-babel--variable-assignments:bash (car pair) (cdr pair) sep hline) - (org-babel--variable-assignments:sh-generic - (car pair) (cdr pair) sep hline))) + (if (string-suffix-p "fish" shell-file-name) + (org-babel--variable-assignments:fish + (car pair) (cdr pair) sep hline) + (org-babel--variable-assignments:sh-generic + (car pair) (cdr pair) sep hline)))) (org-babel--get-vars params)))) (defun org-babel-sh-var-to-sh (var &optional sep hline) @@ -253,22 +269,38 @@ var of the same value." (org-babel-comint-wait-for-output (current-buffer)) (org-babel-comint-input-command (current-buffer) - (format org-babel-prompt-command org-babel-sh-prompt)) - (setq-local comint-prompt-regexp - (concat "^" (regexp-quote org-babel-sh-prompt) - " *")) + (format + (or (cdr (assoc (file-name-nondirectory shell-file-name) + org-babel-shell-set-prompt-commands)) + (alist-get t org-babel-shell-set-prompt-commands)) + org-babel-sh-prompt)) + (setq-local + org-babel-comint-prompt-regexp-old comint-prompt-regexp + comint-prompt-regexp + (concat "^" (regexp-quote org-babel-sh-prompt) + " *")) ;; Needed for Emacs 23 since the marker is initially ;; undefined and the filter functions try to use it without ;; checking. (set-marker comint-last-output-start (point)) (get-buffer (current-buffer))))))) +(defconst ob-shell-async-indicator "echo 'ob_comint_async_shell_%s_%s'" + "Session output delimiter template. +See `org-babel-comint-async-indicator'.") + +(defun ob-shell-async-chunk-callback (string) + "Filter applied to results before insertion. +See `org-babel-comint-async-chunk-callback'." + (replace-regexp-in-string comint-prompt-regexp "" string)) + (defun org-babel-sh-evaluate (session body &optional params stdin cmdline) "Pass BODY to the Shell process in BUFFER. If RESULT-TYPE equals `output' then return a list of the outputs of the statements in BODY, if RESULT-TYPE equals `value' then return the value of the last statement in BODY." (let* ((shebang (cdr (assq :shebang params))) + (async (org-babel-comint-use-async params)) (results-params (cdr (assq :result-params params))) (value-is-exit-status (or (and @@ -300,19 +332,37 @@ return the value of the last statement in BODY." (concat (file-local-name script-file) " " cmdline))))) (buffer-string)))) (session ; session evaluation - (mapconcat - #'org-babel-sh-strip-weird-long-prompt - (mapcar - #'org-trim - (butlast ; Remove eoe indicator - (org-babel-comint-with-output - (session org-babel-sh-eoe-output t body) - (insert (org-trim body) "\n" - org-babel-sh-eoe-indicator) - (comint-send-input nil t)) - ;; Remove `org-babel-sh-eoe-indicator' output line. - 1)) - "\n")) + (if async + (progn + (let ((uuid (org-id-uuid))) + (org-babel-comint-async-register + session + (current-buffer) + "ob_comint_async_shell_\\(start\\|end\\|file\\)_\\(.+\\)" + 'ob-shell-async-chunk-callback + nil) + (org-babel-comint-async-delete-dangling-and-eval + session + (insert (format ob-shell-async-indicator "start" uuid)) + (comint-send-input nil t) + (insert (org-trim body)) + (comint-send-input nil t) + (insert (format ob-shell-async-indicator "end" uuid)) + (comint-send-input nil t)) + uuid)) + (mapconcat + #'org-babel-sh-strip-weird-long-prompt + (mapcar + #'org-trim + (butlast ; Remove eoe indicator + (org-babel-comint-with-output + (session org-babel-sh-eoe-output t body) + (insert (org-trim body) "\n" + org-babel-sh-eoe-indicator) + (comint-send-input nil t)) + ;; Remove `org-babel-sh-eoe-indicator' output line. + 1)) + "\n"))) ;; External shell script, with or without a predefined ;; shebang. ((org-string-nw-p shebang) @@ -323,7 +373,13 @@ return the value of the last statement in BODY." (when padline (insert "\n")) (insert body)) (set-file-modes script-file #o755) - (org-babel-eval script-file ""))) + (if (file-remote-p script-file) + ;; Run remote script using its local path as COMMAND. + ;; The remote execution is ensured by setting + ;; correct `default-directory'. + (let ((default-directory (file-name-directory script-file))) + (org-babel-eval (file-local-name script-file) "")) + (org-babel-eval script-file "")))) (t (org-babel-eval shell-file-name (org-trim body)))))) (when (and results value-is-exit-status) (setq results (car (reverse (split-string results "\n" t))))) diff --git a/elpa/org-9.6.7/ob-sql.el b/elpa/org-9.7.17/ob-sql.el similarity index 93% rename from elpa/org-9.6.7/ob-sql.el rename to elpa/org-9.7.17/ob-sql.el index c13de756..5ece354e 100644 --- a/elpa/org-9.6.7/ob-sql.el +++ b/elpa/org-9.7.17/ob-sql.el @@ -1,6 +1,6 @@ ;;; ob-sql.el --- Babel Functions for SQL -*- lexical-binding: t; -*- -;; Copyright (C) 2009-2023 Free Software Foundation, Inc. +;; Copyright (C) 2009-2024 Free Software Foundation, Inc. ;; Author: Eric Schulte ;; Maintainer: Daniel Kraus @@ -113,9 +113,7 @@ Set `sql-product' in Org edit buffer according to the corresponding :engine source block header argument." (let ((product (cdr (assq :engine (nth 2 info))))) - (condition-case nil - (sql-set-product product) - (user-error "Cannot set `sql-product' in Org Src edit buffer")))) + (sql-set-product product))) (defun org-babel-sql-dbstring-mysql (host port user password database) "Make MySQL cmd line args for database connection. Pass nil to omit that arg." @@ -124,7 +122,7 @@ corresponding :engine source block header argument." (list (when host (concat "-h" host)) (when port (format "-P%d" port)) (when user (concat "-u" user)) - (when password (concat "-p'" password "'")) + (when password (concat "-p" password)) (when database (concat "-D" database)))))) (defun org-babel-sql-dbstring-postgresql (host port user database) @@ -210,7 +208,7 @@ Pass nil to omit that arg." "Convert FILE to OS standard file name. If in Cygwin environment, uses Cygwin specific function to convert the file name. In a Windows-NT environment, do nothing. -Otherwise, use Emacs' standard conversion function." +Otherwise, use Emacs's standard conversion function." (cond ((fboundp 'cygwin-convert-file-name-to-windows) (format "%S" (cygwin-convert-file-name-to-windows file))) ((string= "windows-nt" system-type) file) @@ -231,14 +229,10 @@ database connections." (:dbuser . sql-user) (:dbpassword . sql-password) (:dbinstance . sql-dbinstance) - (:database . sql-database) - (:engine . sql-product))) + (:database . sql-database))) (mapped-name (cdr (assq name name-mapping)))) - (if (string-equal ":engine" name) - (symbol-name (cadr (cadr (assq mapped-name - (cdr (assoc-string dbconnection sql-connection-alist t)))))) - (cadr (assq mapped-name - (cdr (assoc-string dbconnection sql-connection-alist t))))))))) + (cadr (assq mapped-name + (cdr (assoc-string dbconnection sql-connection-alist t)))))))) (defun org-babel-execute:sql (body params) "Execute a block of Sql code with Babel. @@ -251,7 +245,7 @@ This function is called by `org-babel-execute-src-block'." (dbpassword (org-babel-find-db-connection-param params :dbpassword)) (dbinstance (org-babel-find-db-connection-param params :dbinstance)) (database (org-babel-find-db-connection-param params :database)) - (engine (org-babel-find-db-connection-param params :engine)) + (engine (cdr (assq :engine params))) (colnames-p (not (equal "no" (cdr (assq :colnames params))))) (in-file (org-babel-temp-file "sql-in-")) (out-file (or (cdr (assq :out-file params)) @@ -413,11 +407,11 @@ argument mechanism." val (if sqlite nil '(:fmt (lambda (el) (if (stringp el) - el - (format "%S" el)))))))) + el + (format "%S" el)))))))) data-file) (if (stringp val) val (format "%S" val)))) - body))) + body t t))) vars) body) diff --git a/elpa/org-9.6.7/ob-sqlite.el b/elpa/org-9.7.17/ob-sqlite.el similarity index 89% rename from elpa/org-9.6.7/ob-sqlite.el rename to elpa/org-9.7.17/ob-sqlite.el index 526b73eb..96d93b81 100644 --- a/elpa/org-9.6.7/ob-sqlite.el +++ b/elpa/org-9.7.17/ob-sqlite.el @@ -1,6 +1,6 @@ ;;; ob-sqlite.el --- Babel Functions for SQLite Databases -*- lexical-binding: t; -*- -;; Copyright (C) 2010-2023 Free Software Foundation, Inc. +;; Copyright (C) 2010-2024 Free Software Foundation, Inc. ;; Author: Eric Schulte ;; Maintainer: Nick Savage @@ -57,13 +57,20 @@ (defun org-babel-expand-body:sqlite (body params) "Expand BODY according to the values of PARAMS." - (org-babel-sql-expand-vars - body (org-babel--get-vars params) t)) + (let ((prologue (cdr (assq :prologue params))) + (epilogue (cdr (assq :epilogue params)))) + (mapconcat 'identity + (list + prologue + (org-babel-sql-expand-vars + body (org-babel--get-vars params) t) + epilogue) + "\n"))) (defvar org-babel-sqlite3-command "sqlite3") (defun org-babel-execute:sqlite (body params) - "Execute a block of Sqlite code with Babel. + "Execute Sqlite BODY according to PARAMS. This function is called by `org-babel-execute-src-block'." (let ((result-params (split-string (or (cdr (assq :results params)) ""))) (db (cdr (assq :db params))) @@ -74,7 +81,6 @@ This function is called by `org-babel-execute-src-block'." (lambda (arg) (car (assq arg params))) (list :header :echo :bail :column :csv :html :line :list))))) - (unless db (error "ob-sqlite: can't evaluate without a database")) (with-temp-buffer (insert (org-babel-eval @@ -97,7 +103,7 @@ This function is called by `org-babel-execute-src-block'." (member :html others) separator) "" "-csv")) - (cons "db " db))) + (cons "db" (or db "")))) ;; body of the code block (org-babel-expand-body:sqlite body params))) (org-babel-result-cond result-params @@ -122,7 +128,8 @@ This function is called by `org-babel-execute-src-block'." (org-babel-sql-expand-vars body vars t)) (defun org-babel-sqlite-table-or-scalar (result) - "If RESULT looks like a trivial table, then unwrap it." + "Cleanup cells in the RESULT table. +If RESULT is a trivial 1x1 table, then unwrap it." (if (and (equal 1 (length result)) (equal 1 (length (car result)))) (org-babel-read (caar result) t) @@ -133,7 +140,7 @@ This function is called by `org-babel-execute-src-block'." result))) (defun org-babel-sqlite-offset-colnames (table headers-p) - "If HEADERS-P is non-nil then offset the first row as column names." + "If HEADERS-P is non-nil then offset the first row as column names in TABLE." (if headers-p (cons (car table) (cons 'hline (cdr table))) table)) diff --git a/elpa/org-9.6.7/ob-table.el b/elpa/org-9.7.17/ob-table.el similarity index 86% rename from elpa/org-9.6.7/ob-table.el rename to elpa/org-9.7.17/ob-table.el index 5c91f33f..1ebf10dd 100644 --- a/elpa/org-9.6.7/ob-table.el +++ b/elpa/org-9.7.17/ob-table.el @@ -1,6 +1,6 @@ ;;; ob-table.el --- Support for Calling Babel Functions from Tables -*- lexical-binding: t; -*- -;; Copyright (C) 2009-2023 Free Software Foundation, Inc. +;; Copyright (C) 2009-2024 Free Software Foundation, Inc. ;; Author: Eric Schulte ;; Keywords: literate programming, reproducible research @@ -87,18 +87,20 @@ is the equivalent of the following source code block: results #+end_src -NOTE: The quotation marks around the function name, -`source-block', are optional. +The quotation marks around the function name, `source-block', are +optional. -NOTE: By default, string variable names are interpreted as -references to source-code blocks, to force interpretation of a -cell's value as a string, prefix the identifier a \"$\" (e.g., -\"$$2\" instead of \"$2\" or \"$@2$2\" instead of \"@2$2\"). +By default, string variable names are interpreted as references to +source-code blocks, to force interpretation of a cell's value as a +string, prefix the identifier a \"$\" (e.g., \"$$2\" instead of \"$2\" +or \"$@2$2\" instead of \"@2$2\"). \"$\" will also force interpreting +string value literally: $\"value\" will refer to a string, not a +source block name. -NOTE: It is also possible to pass header arguments to the code -block. In this case a table cell should hold the string value of -the header argument which can then be passed before all variables -as shown in the example below. +It is also possible to pass header arguments to the code block. In +this case a table cell should hold the string value of the header +argument which can then be passed before all variables as shown in the +example below. | 1 | 2 | :file nothing.png | nothing.png | #+TBLFM: @1$4=\\='(org-sbe test-sbe $3 (x $1) (y $2))" @@ -117,7 +119,7 @@ as shown in the example below. (prog1 nil (setq quote t)) (prog1 (cond - (quote (format "\"%s\"" el)) + (quote (format "%S" el)) ((stringp el) (org-no-properties el)) (t el)) (setq quote nil)))) diff --git a/elpa/org-9.6.7/ob-tangle.el b/elpa/org-9.7.17/ob-tangle.el similarity index 84% rename from elpa/org-9.6.7/ob-tangle.el rename to elpa/org-9.7.17/ob-tangle.el index 0b816a7c..fe143b03 100644 --- a/elpa/org-9.6.7/ob-tangle.el +++ b/elpa/org-9.7.17/ob-tangle.el @@ -1,6 +1,6 @@ ;;; ob-tangle.el --- Extract Source Code From Org Files -*- lexical-binding: t; -*- -;; Copyright (C) 2009-2023 Free Software Foundation, Inc. +;; Copyright (C) 2009-2024 Free Software Foundation, Inc. ;; Author: Eric Schulte ;; Keywords: literate programming, reproducible research @@ -40,11 +40,11 @@ (declare-function org-babel-update-block-body "ob-core" (new-body)) (declare-function org-back-to-heading "org" (&optional invisible-ok)) (declare-function org-before-first-heading-p "org" ()) -(declare-function org-element--cache-active-p "org-element" ()) -(declare-function org-element-lineage "org-element" (datum &optional types with-self)) -(declare-function org-element-property "org-element" (property element)) +(declare-function org-element-lineage "org-element-ast" (datum &optional types with-self)) +(declare-function org-element-property "org-element-ast" (property node)) +(declare-function org-element-begin "org-element" (node)) (declare-function org-element-at-point "org-element" (&optional pom cached-only)) -(declare-function org-element-type "org-element" (element)) +(declare-function org-element-type-p "org-element-ast" (node types)) (declare-function org-heading-components "org" ()) (declare-function org-in-commented-heading-p "org" (&optional no-inheritance)) (declare-function org-in-archived-heading-p "org" (&optional no-inheritance)) @@ -166,9 +166,25 @@ read-write permissions for the user, read-only for everyone else." :package-version '(Org . "9.6") :type 'integer) +(defcustom org-babel-tangle-remove-file-before-write 'auto + "How to overwrite the existing tangle target. +When set to nil, `org-babel-tangle' will replace contents of an existing +tangle target (and fail when tangle target is read-only). +When set to t, the tangle target (including read-only) will be deleted +first and a new file, possibly with different ownership and +permissions, will be created. +When set to symbol `auto', overwrite read-only tangle targets and +replace contents otherwise." + :group 'org-babel-tangle + :package-version '(Org . "9.7") + :type '(choice + (const :tag "Replace contents, but keep the same file" nil) + (const :tag "Re-create file" t) + (const :tag "Re-create when read-only" auto)) + :safe t) + (defun org-babel-find-file-noselect-refresh (file) - "Find file ensuring that the latest changes on disk are -represented in the file." + "Find file ensuring that the latest changes on disk are represented in the file." (find-file-noselect file 'nowarn) (with-current-buffer (get-file-buffer file) (revert-buffer t t t))) @@ -205,21 +221,20 @@ source code blocks by languages matching a regular expression. Return list of the tangled file names." (interactive "fFile to tangle: \nP") - (let* ((visited (find-buffer-visiting file)) - (buffer (or visited (find-file-noselect file)))) - (prog1 - (with-current-buffer buffer - (org-with-wide-buffer - (mapcar #'expand-file-name - (org-babel-tangle nil target-file lang-re)))) - (unless visited (kill-buffer buffer))))) + (org-with-file-buffer file + (org-with-wide-buffer + (mapcar #'expand-file-name + (org-babel-tangle nil target-file lang-re))))) (defun org-babel-tangle-publish (_ filename pub-dir) "Tangle FILENAME and place the results in PUB-DIR." (unless (file-exists-p pub-dir) (make-directory pub-dir t)) (setq pub-dir (file-name-as-directory pub-dir)) - (mapc (lambda (el) (copy-file el pub-dir t)) (org-babel-tangle-file filename))) + ;; Rename files to avoid copying to same file when publishing to ./ + ;; `copy-file' would throw an error when copying file to self. + (mapc (lambda (el) (rename-file el pub-dir t)) + (org-babel-tangle-file filename))) ;;;###autoload (defun org-babel-tangle (&optional arg target-file lang-re) @@ -253,7 +268,8 @@ matching a regular expression." (when (equal arg '(16)) (or (cdr (assq :tangle (nth 2 (org-babel-get-src-block-info 'no-eval)))) (user-error "Point is not in a source code block")))) - path-collector) + path-collector + (source-file buffer-file-name)) (mapc ;; map over file-names (lambda (by-fn) (let ((file-name (car by-fn))) @@ -310,10 +326,28 @@ matching a regular expression." (compare-buffer-substrings nil nil nil tangle-buf nil nil))))))) - ;; erase previous file - (when (file-exists-p file-name) + (when (equal (if (file-name-absolute-p file-name) + file-name + (expand-file-name file-name)) + (if (file-name-absolute-p source-file) + source-file + (expand-file-name source-file))) + (error "Not allowed to tangle into the same file as self")) + ;; We do not erase, but overwrite previous file + ;; to preserve any existing symlinks. + ;; This behavior is modified using + ;; `org-babel-tangle-remove-file-before-write' to + ;; tangle to read-only files. + (when (and + (file-exists-p file-name) + (pcase org-babel-tangle-remove-file-before-write + (`auto (not (file-writable-p file-name))) + (`t t) + (`nil nil) + (_ (error "Invalid value of `org-babel-tangle-remove-file-before-write': %S" + org-babel-tangle-remove-file-before-write)))) (delete-file file-name)) - (write-region nil nil file-name) + (write-region nil nil file-name) (mapc (lambda (mode) (set-file-modes file-name mode)) modes)) (push file-name path-collector)))))) (if (equal arg '(4)) @@ -351,13 +385,13 @@ The following forms are currently recognized: ((integerp mode) (if (string-match-p "^[0-7][0-7][0-7]$" (format "%o" mode)) mode - (user-error "%1$o is not a valid file mode octal. \ + (user-error "%1$o is not a valid file mode octal. \ Did you give the decimal value %1$d by mistake?" mode))) ((not (stringp mode)) - (error "File mode %S not recognized as a valid format." mode)) + (error "File mode %S not recognized as a valid format" mode)) ((string-match-p "^o0?[0-7][0-7][0-7]$" mode) (string-to-number (replace-regexp-in-string "^o" "" mode) 8)) - ((string-match-p "^[ugoa]*\\(?:[+-=][rwxXstugo]*\\)+\\(,[ugoa]*\\(?:[+-=][rwxXstugo]*\\)+\\)*$" mode) + ((string-match-p "^[ugoa]*\\(?:[+=-][rwxXstugo]*\\)+\\(,[ugoa]*\\(?:[+=-][rwxXstugo]*\\)+\\)*$" mode) ;; Match regexp taken from `file-modes-symbolic-to-number'. (file-modes-symbolic-to-number mode org-babel-tangle-default-file-mode)) ((string-match-p "^[r-][w-][xs-][r-][w-][xs-][r-][w-][x-]$" mode) @@ -365,7 +399,7 @@ Did you give the decimal value %1$d by mistake?" mode))) ",g=" (delete ?- (substring mode 3 6)) ",o=" (delete ?- (substring mode 6 9))) 0)) - (t (error "File mode %S not recognized as a valid format. See `org-babel-interpret-file-mode'." mode)))) + (t (error "File mode %S not recognized as a valid format. See `org-babel-interpret-file-mode'" mode)))) (defun org-babel-tangle-clean () "Remove comments inserted by `org-babel-tangle'. @@ -378,7 +412,7 @@ references." (goto-char (point-min)) (while (or (re-search-forward "\\[\\[file:.*\\]\\[.*\\]\\]" nil t) (re-search-forward (org-babel-noweb-wrap) nil t)) - (delete-region (save-excursion (beginning-of-line 1) (point)) + (delete-region (save-excursion (forward-line) (point)) (save-excursion (end-of-line 1) (forward-char 1) (point))))) (defun org-babel-spec-to-string (spec) @@ -427,17 +461,19 @@ that the appropriate major-mode is set. SPEC has the form: org-babel-tangle-comment-format-end link-data))))) (defun org-babel-effective-tangled-filename (buffer-fn src-lang src-tfile) - "Return effective tangled filename of a source-code block. -BUFFER-FN is the name of the buffer, SRC-LANG the language of the -block and SRC-TFILE is the value of the :tangle header argument, -as computed by `org-babel-tangle-single-block'." - (let ((base-name (cond - ((string= "yes" src-tfile) - ;; Use the buffer name - (file-name-sans-extension buffer-fn)) - ((string= "no" src-tfile) nil) - ((> (length src-tfile) 0) src-tfile))) - (ext (or (cdr (assoc src-lang org-babel-tangle-lang-exts)) src-lang))) + "Return effective tangled absolute filename of a source-code block. +BUFFER-FN is the absolute file name of the buffer, SRC-LANG the +language of the block and SRC-TFILE is the value of the :tangle +header argument, as computed by `org-babel-tangle-single-block'." + (let* ((fnd (file-name-directory buffer-fn)) + (base-name (cond + ((string= "yes" src-tfile) + ;; Use the buffer name + (file-name-sans-extension buffer-fn)) + ((string= "no" src-tfile) nil) + ((> (length src-tfile) 0) + (expand-file-name src-tfile fnd)))) + (ext (or (cdr (assoc src-lang org-babel-tangle-lang-exts)) src-lang))) (when base-name ;; decide if we want to add ext to base-name (if (and ext (string= "yes" src-tfile)) @@ -454,13 +490,16 @@ source code blocks by languages matching a regular expression. Optional argument TANGLE-FILE can be used to limit the collected code blocks by target file." - (let ((counter 0) last-heading-pos blocks) + (let ((counter 0) + (buffer-fn (buffer-file-name (buffer-base-buffer))) + last-heading-pos blocks) (org-babel-map-src-blocks (buffer-file-name) (let ((current-heading-pos - (if (org-element--cache-active-p) - (or (org-element-property :begin (org-element-lineage (org-element-at-point) '(headline) t)) 1) - (org-with-wide-buffer - (org-with-limited-levels (outline-previous-heading)))))) + (or (org-element-begin + (org-element-lineage + (org-element-at-point) + 'headline t)) + 1))) (if (eq last-heading-pos current-heading-pos) (cl-incf counter) (setq counter 1) (setq last-heading-pos current-heading-pos))) @@ -470,6 +509,7 @@ code blocks by target file." (src-lang (nth 0 info)) (src-tfile (cdr (assq :tangle (nth 2 info))))) (unless (or (string= src-tfile "no") + (not src-lang) ;; src block without lang (and tangle-file (not (equal tangle-file src-tfile))) (and lang-re (not (string-match-p lang-re src-lang)))) ;; Add the spec for this block to blocks under its tangled @@ -477,7 +517,7 @@ code blocks by target file." (let* ((block (org-babel-tangle-single-block counter)) (src-tfile (cdr (assq :tangle (nth 4 block)))) (file-name (org-babel-effective-tangled-filename - (nth 1 block) src-lang src-tfile)) + buffer-fn src-lang src-tfile)) (by-fn (assoc file-name blocks))) (if by-fn (setcdr by-fn (cons (cons src-lang block) (cdr by-fn))) (push (cons file-name (list (cons src-lang block))) blocks))))))) @@ -491,12 +531,7 @@ code blocks by target file." The PARAMS are the 3rd element of the info for the same src block." (unless (string= "no" (cdr (assq :comments params))) (save-match-data - (let* (;; The created link is transient. Using ID is not necessary, - ;; but could have side-effects if used. An ID property may - ;; be added to existing entries thus creating unexpected file - ;; modifications. - (org-id-link-to-org-use-id nil) - (l (org-no-properties + (let* ((l (org-no-properties (cl-letf (((symbol-function 'org-store-link-functions) (lambda () nil))) (org-store-link nil)))) @@ -589,13 +624,12 @@ non-nil, return the full association list to be used by link source-name params - (if org-src-preserve-indentation - (org-trim body t) + (if (org-src-preserve-indentation-p) (org-trim body t) (org-trim (org-remove-indentation body))) comment))) (if only-this-block (let* ((file-name (org-babel-effective-tangled-filename - (nth 1 result) src-lang src-tfile))) + file src-lang src-tfile))) (list (cons file-name (list (cons src-lang result))))) result))) @@ -616,9 +650,12 @@ by `org-babel-get-src-block-info'." ;; de-tangling functions (defun org-babel-detangle (&optional source-code-file) - "Propagate changes in source file back original to Org file. + "Propagate changes from current source buffer back to the original Org file. This requires that code blocks were tangled with link comments -which enable the original code blocks to be found." +which enable the original code blocks to be found. + +Optional argument SOURCE-CODE-FILE is the file path to be used instead +of the current buffer." (interactive) (save-excursion (when source-code-file (find-file source-code-file)) @@ -673,8 +710,7 @@ which enable the original code blocks to be found." (org-back-to-heading t)) ;; Do not skip the first block if it begins at point min. (cond ((or (org-at-heading-p) - (not (eq (org-element-type (org-element-at-point)) - 'src-block))) + (not (org-element-type-p (org-element-at-point) 'src-block))) (org-babel-next-src-block n)) ((= n 1)) (t (org-babel-next-src-block (1- n))))) diff --git a/elpa/org-9.6.7/ob.el b/elpa/org-9.7.17/ob.el similarity index 94% rename from elpa/org-9.6.7/ob.el rename to elpa/org-9.7.17/ob.el index 4444ced5..064faafd 100644 --- a/elpa/org-9.6.7/ob.el +++ b/elpa/org-9.7.17/ob.el @@ -1,6 +1,6 @@ ;;; ob.el --- Working with Code Blocks in Org -*- lexical-binding: t; -*- -;; Copyright (C) 2009-2023 Free Software Foundation, Inc. +;; Copyright (C) 2009-2024 Free Software Foundation, Inc. ;; Authors: Eric Schulte ;; Keywords: literate programming, reproducible research @@ -21,6 +21,8 @@ ;; You should have received a copy of the GNU General Public License ;; along with GNU Emacs. If not, see . +;;; Commentary: + ;;; Code: (require 'org-macs) diff --git a/elpa/org-9.6.7/oc-basic.el b/elpa/org-9.7.17/oc-basic.el similarity index 85% rename from elpa/org-9.6.7/oc-basic.el rename to elpa/org-9.7.17/oc-basic.el index 1c8c37aa..e207a199 100644 --- a/elpa/org-9.6.7/oc-basic.el +++ b/elpa/org-9.7.17/oc-basic.el @@ -1,6 +1,6 @@ -;;; oc-basic.el --- basic back-end for citations -*- lexical-binding: t; -*- +;;; oc-basic.el --- basic backend for citations -*- lexical-binding: t; -*- -;; Copyright (C) 2021-2023 Free Software Foundation, Inc. +;; Copyright (C) 2021-2024 Free Software Foundation, Inc. ;; Author: Nicolas Goaziou @@ -24,7 +24,7 @@ ;; The `basic' citation processor provides "activate", "follow", "export" and ;; "insert" capabilities. -;; "activate" capability re-uses default fontification, but provides additional +;; "activate" capability reuses default fontification, but provides additional ;; features on both correct and wrong keys according to the bibliography ;; defined in the document. @@ -78,9 +78,19 @@ (declare-function org-open-at-point "org" (&optional arg)) (declare-function org-open-file "org" (path &optional in-emacs line search)) +(declare-function org-element-create "org-element-ast" (type &optional props &rest children)) +(declare-function org-element-set "org-element-ast" (old new &optional keep-props)) + (declare-function org-element-interpret-data "org-element" (data)) -(declare-function org-element-property "org-element" (property element)) -(declare-function org-element-type "org-element" (element)) +(declare-function org-element-parse-secondary-string "org-element" (string restriction &optional parent)) +(declare-function org-element-map "org-element" + ( data types fun + &optional + info first-match no-recursion + with-affiliated no-undefer)) +(declare-function org-element-property "org-element-ast" (property node)) +(declare-function org-element-type-p "org-element-ast" (node types)) +(declare-function org-element-contents "org-element-ast" (node)) (declare-function org-export-data "org-export" (data info)) (declare-function org-export-derived-backend-p "org-export" (backend &rest backends)) @@ -162,7 +172,7 @@ Return a hash table with citation references as keys and fields alist as values. (puthash (cdr (assq 'id item)) (mapcar (pcase-lambda (`(,field . ,value)) (pcase field - ((or 'author 'editors) + ((or 'author 'editor) ;; Author and editors are arrays of ;; objects, each of them designing a ;; person. These objects may contain @@ -272,6 +282,9 @@ Optional argument INFO is the export state, as a property list." (plist-get info :cite-basic/bibliography) (let ((results nil)) (dolist (file (org-cite-list-bibliography-files)) + ;; Follow symlinks, to look into modification time of the + ;; actual file, not its symlink. + (setq file (file-truename file)) (when (file-readable-p file) (with-temp-buffer (when (or (org-file-has-changed-p file) @@ -330,9 +343,11 @@ FIELD is a symbol. ENTRY-OR-KEY is either an association list, as returned by Optional argument INFO is the export state, as a property list. -Return value may be nil or a string. If current export back-end is derived -from `latex', return a raw string instead, unless optional argument RAW is -non-nil." +Return value may be nil or a string. If current export backend is derived +from `latex', return a raw string object instead, unless optional +argument RAW is non-nil. + +Throw an error if the field value is non-string and non-nil." (let ((value (cdr (assq field @@ -343,6 +358,8 @@ non-nil." entry-or-key) (_ (error "Wrong value for ENTRY-OR-KEY: %S" entry-or-key))))))) + (when (and value (not (stringp value))) + (error "Non-string bibliography field value: %S" value)) (if (and value (not raw) (org-export-derived-backend-p (plist-get info :back-end) 'latex)) @@ -351,17 +368,27 @@ non-nil." (defun org-cite-basic--shorten-names (names) "Return a list of family names from a list of full NAMES. +NAMES can be a string or raw string object. To better accomomodate corporate names, this will only shorten personal names of the form \"family, given\"." - (when (stringp names) - (mapconcat - (lambda (name) - (if (eq 1 (length name)) - (cdr (split-string name)) - (car (split-string name ", ")))) - (split-string names " and ") - ", "))) + (let (names-string raw-p) + (cond + ((stringp names) (setq names-string names)) + ((org-element-type-p names 'raw) + (setq names-string (mapconcat #'identity (org-element-contents names) "") + raw-p t))) + (when names-string + (setq names-string + (mapconcat + (lambda (name) + (if (eq 1 (length name)) + (cdr (split-string name)) + (car (split-string name ", ")))) + (split-string names-string " and ") + ", ")) + (if raw-p (org-export-raw-string names-string) + names-string)))) (defun org-cite-basic--number-to-suffix (n) "Compute suffix associated to number N. @@ -417,7 +444,7 @@ necessary, unless optional argument NO-SUFFIX is non-nil." (year (or (org-cite-basic--get-field 'year entry-or-key info 'raw) (let ((date - (org-cite-basic--get-field 'date entry-or-key info t))) + (org-cite-basic--get-field 'date entry-or-key info 'raw))) (and (stringp date) (string-match (rx string-start (group (= 4 digit)) @@ -445,6 +472,38 @@ necessary, unless optional argument NO-SUFFIX is non-nil." new)))) (if no-suffix year (concat year suffix))))))) +(defun org-cite-basic--print-bibtex-string (element &optional info) + "Print Bibtex formatted string ELEMENT, according to Bibtex syntax. +Remove all the {...} that are not a part of LaTeX macros and parse the +LaTeX fragments. Do nothing when current backend is derived from +LaTeX, according to INFO. + +Return updated ELEMENT." + (if (org-export-derived-backend-p (plist-get info :back-end) 'latex) + ;; Derived from LaTeX, no need to use manual ad-hoc LaTeX + ;; parser. + element + ;; Convert ELEMENT to anonymous when ELEMENT is string. + ;; Otherwise, we cannot modify ELEMENT by side effect. + (when (org-element-type-p element 'plain-text) + (setq element (org-element-create 'anonymous nil element))) + ;; Approximately parse LaTeX fragments, assuming Org mode syntax + ;; (it is close to original LaTeX, and we do not want to + ;; re-implement complete LaTeX parser here)) + (org-element-map element t + (lambda (str) + (when (stringp str) + (org-element-set + str + (org-element-parse-secondary-string + str '(latex-fragment entity)))))) + ;; Strip the remaining { and }. + (org-element-map element t + (lambda (str) + (when (stringp str) + (org-element-set str (replace-regexp-in-string "[{}]" "" str))))) + element)) + (defun org-cite-basic--print-entry (entry style &optional info) "Format ENTRY according to STYLE string. ENTRY is an alist, as returned by `org-cite-basic--get-entry'. @@ -456,27 +515,29 @@ Optional argument INFO is the export state, as a property list." (org-cite-basic--get-field 'journal entry info) (org-cite-basic--get-field 'institution entry info) (org-cite-basic--get-field 'school entry info)))) - (pcase style - ("plain" - (let ((year (org-cite-basic--get-year entry info 'no-suffix))) - (org-cite-concat - (org-cite-basic--shorten-names author) ". " - title (and from (list ", " from)) ", " year "."))) - ("numeric" - (let ((n (org-cite-basic--key-number (cdr (assq 'id entry)) info)) - (year (org-cite-basic--get-year entry info 'no-suffix))) - (org-cite-concat - (format "[%d] " n) author ", " - (org-cite-emphasize 'italic title) - (and from (list ", " from)) ", " - year "."))) - ;; Default to author-year. Use year disambiguation there. - (_ - (let ((year (org-cite-basic--get-year entry info))) - (org-cite-concat - author " (" year "). " - (org-cite-emphasize 'italic title) - (and from (list ", " from)) ".")))))) + (org-cite-basic--print-bibtex-string + (pcase style + ("plain" + (let ((year (org-cite-basic--get-year entry info 'no-suffix))) + (org-cite-concat + (org-cite-basic--shorten-names author) ". " + title (and from (list ", " from)) ", " year "."))) + ("numeric" + (let ((n (org-cite-basic--key-number (cdr (assq 'id entry)) info)) + (year (org-cite-basic--get-year entry info 'no-suffix))) + (org-cite-concat + (format "[%d] " n) author ", " + (org-cite-emphasize 'italic title) + (and from (list ", " from)) ", " + year "."))) + ;; Default to author-year. Use year disambiguation there. + (_ + (let ((year (org-cite-basic--get-year entry info))) + (org-cite-concat + author " (" year "). " + (org-cite-emphasize 'italic title) + (and from (list ", " from)) ".")))) + info))) ;;; "Activate" capability @@ -580,8 +641,8 @@ INFO is the export state, as a property list." (suffix (org-element-property :suffix ref))) (funcall format-ref prefix - (org-cite-basic--get-author k info) - (org-cite-basic--get-year k info) + (or (org-cite-basic--get-author k info) "??") + (or (org-cite-basic--get-year k info) "????") suffix))) (org-cite-get-references citation) org-cite-basic-author-year-separator) @@ -619,7 +680,7 @@ INFO is the export state as a property list." INFO is the export state, as a property list." (and field (lambda (a b) - (string-collate-lessp + (org-string< (org-cite-basic--get-field field a info 'raw) (org-cite-basic--get-field field b info 'raw) nil t)))) @@ -649,20 +710,30 @@ export communication channel, as a property list." ;; "author" style. (`(,(or "author" "a") . ,variant) (let ((caps (member variant '("caps" "c")))) - (org-export-data - (mapconcat - (lambda (key) - (let ((author (org-cite-basic--get-author key info))) - (if caps (capitalize author) author))) - (org-cite-get-references citation t) - org-cite-basic-author-year-separator) + (org-cite-basic--format-author-year + citation + (lambda (p c s) (org-cite-concat p c s)) + (lambda (prefix author _ suffix) + (org-cite-concat + prefix + (if caps (org-cite-capitalize author) author) + suffix)) info))) ;; "noauthor" style. (`(,(or "noauthor" "na") . ,variant) - (format (if (funcall has-variant-p variant 'bare) "%s" "(%s)") - (mapconcat (lambda (key) (org-cite-basic--get-year key info)) - (org-cite-get-references citation t) - org-cite-basic-author-year-separator))) + (let ((bare? (funcall has-variant-p variant 'bare))) + (org-cite-basic--format-author-year + citation + (lambda (prefix contents suffix) + (org-cite-concat + (unless bare? "(") + prefix + contents + suffix + (unless bare? ")"))) + (lambda (prefix _ year suffix) + (org-cite-concat prefix year suffix)) + info))) ;; "nocite" style. (`(,(or "nocite" "n") . ,_) nil) ;; "text" and "note" styles. @@ -678,10 +749,11 @@ export communication channel, as a property list." (lambda (p c s) (org-cite-concat p c s)) (lambda (p a y s) (org-cite-concat p - (if caps (capitalize a) a) + (if caps (org-cite-capitalize a) a) (if bare " " " (") - y s - (and (not bare) ")"))) + y + (and (not bare) ")") + s)) info))) ;; "numeric" style. ;; @@ -702,7 +774,7 @@ export communication channel, as a property list." (lambda (p c s) (org-cite-concat (and (not bare) "(") p c s (and (not bare) ")"))) (lambda (p a y s) - (org-cite-concat p (if caps (capitalize a) a) ", " y s)) + (org-cite-concat p (if caps (org-cite-capitalize a) a) ", " y s)) info))) ;; This should not happen. (_ (error "Invalid style: %S" style))))) @@ -710,7 +782,7 @@ export communication channel, as a property list." (defun org-cite-basic-export-bibliography (keys _files style _props backend info) "Generate bibliography. KEYS is the list of cited keys, as strings. STYLE is the expected bibliography -style, as a string. BACKEND is the export back-end, as a symbol. INFO is the +style, as a string. BACKEND is the export backend, as a symbol. INFO is the export state, as a property list." (mapconcat (lambda (entry) @@ -734,7 +806,7 @@ When DATUM is a citation reference, open bibliography entry referencing the citation key. Otherwise, select which key to follow among all keys present in the citation." (let* ((key - (if (eq 'citation-reference (org-element-type datum)) + (if (org-element-type-p datum 'citation-reference) (org-element-property :key datum) (pcase (org-cite-get-references datum t) (`(,key) key) @@ -806,7 +878,7 @@ Return nil if there are no bibliography files or no entries." (let ((date (org-cite-basic--get-year entry nil 'no-suffix))) (format "%4s" (or date ""))) org-cite-basic-column-separator - (org-cite-basic--get-field 'title entry nil t)))) + (org-cite-basic--get-field 'title entry nil 'raw)))) (puthash completion key org-cite-basic--completion-cache))) (unless (map-empty-p org-cite-basic--completion-cache) ;no key (puthash entries t org-cite-basic--completion-cache) diff --git a/elpa/org-9.6.7/oc-biblatex.el b/elpa/org-9.7.17/oc-biblatex.el similarity index 92% rename from elpa/org-9.6.7/oc-biblatex.el rename to elpa/org-9.7.17/oc-biblatex.el index b2d31f0f..4755ac6b 100644 --- a/elpa/org-9.6.7/oc-biblatex.el +++ b/elpa/org-9.7.17/oc-biblatex.el @@ -1,6 +1,6 @@ ;;; oc-biblatex.el --- biblatex citation processor for Org -*- lexical-binding: t; -*- -;; Copyright (C) 2021-2023 Free Software Foundation, Inc. +;; Copyright (C) 2021-2024 Free Software Foundation, Inc. ;; Author: Nicolas Goaziou @@ -26,7 +26,7 @@ ;; The processor relies on "biblatex" LaTeX package. As such it ensures that ;; the package is properly required in the document's preamble. More -;; accurately, it will re-use any "\usepackage{biblatex}" already present in +;; accurately, it will reuse any "\usepackage{biblatex}" already present in ;; the document (e.g., through `org-latex-packages-alist'), or insert one using ;; options defined in `org-cite-biblatex-options'. @@ -70,7 +70,8 @@ (require 'org-macs) (require 'oc) -(declare-function org-element-property "org-element" (property element)) +(declare-function org-element-property "org-element-ast" (property node)) +(declare-function org-element-parent "org-element-ast" (node)) (declare-function org-export-data "org-export" (data info)) @@ -189,20 +190,23 @@ INITIAL is an initial style of comma-separated options, as a string or nil. STYLE is the style definition as a string or nil. Return a string." - (let ((options-no-style - (and initial - (let ((re (rx string-start (or "bibstyle" "citestyle" "style")))) - (seq-filter - (lambda (option) (not (string-match re option))) - (split-string (org-unbracket-string "[" "]" initial) - "," t " \t"))))) - (style-options - (cond - ((null style) nil) - ((not (string-match "/" style)) (list (concat "style=" style))) - (t - (list (concat "bibstyle=" (substring style nil (match-beginning 0))) - (concat "citestyle=" (substring style (match-end 0)))))))) + (let* ((options-no-style + (and initial + (let ((re (rx string-start (or "bibstyle" "citestyle" "style")))) + (seq-filter + (lambda (option) (not (string-match re option))) + (split-string (org-unbracket-string "[" "]" initial) + "," t " \t"))))) + ;; Check whether the string is in key=val,... + (biblatex-options-p (and (stringp style) (string-match-p "\\`[^,=]+=[^,]+\\(,[^=]+=[^,]+\\)\\'" style))) + (style-options + (cond + ((null style) nil) + ;; Assume it is a valid options string for biblatex if it is in key=val,... format + ((not (string-match "/" style)) (list (if biblatex-options-p style (concat "style=" style)))) + (t + (list (concat "bibstyle=" (substring style nil (match-beginning 0))) + (concat "citestyle=" (substring style (match-end 0)))))))) (if (or options-no-style style-options) (format "[%s]" (mapconcat #'identity @@ -231,7 +235,7 @@ When NO-OPT argument is non-nil, only provide mandatory arguments." (let* ((origin (pcase references (`(,reference) reference) (`(,reference . ,_) - (org-element-property :parent reference)))) + (org-element-parent reference)))) (suffix (org-element-property :suffix origin)) (prefix (org-element-property :prefix origin))) (concat (and prefix diff --git a/elpa/org-9.6.7/oc-bibtex.el b/elpa/org-9.7.17/oc-bibtex.el similarity index 95% rename from elpa/org-9.6.7/oc-bibtex.el rename to elpa/org-9.7.17/oc-bibtex.el index d5e5490e..5e65df5f 100644 --- a/elpa/org-9.6.7/oc-bibtex.el +++ b/elpa/org-9.7.17/oc-bibtex.el @@ -1,6 +1,6 @@ ;;; oc-bibtex.el --- Vanilla citation processor for LaTeX -*- lexical-binding: t; -*- -;; Copyright (C) 2021-2023 Free Software Foundation, Inc. +;; Copyright (C) 2021-2024 Free Software Foundation, Inc. ;; Author: Nicolas Goaziou @@ -41,7 +41,7 @@ (require 'oc) -(declare-function org-element-property "org-element" (property element)) +(declare-function org-element-property "org-element-ast" (property node)) (declare-function org-export-data "org-export" (data info)) diff --git a/elpa/org-9.6.7/oc-csl.el b/elpa/org-9.7.17/oc-csl.el similarity index 80% rename from elpa/org-9.6.7/oc-csl.el rename to elpa/org-9.7.17/oc-csl.el index 2b00cb59..b8691bf6 100644 --- a/elpa/org-9.6.7/oc-csl.el +++ b/elpa/org-9.7.17/oc-csl.el @@ -1,6 +1,6 @@ ;;; oc-csl.el --- csl citation processor for Org -*- lexical-binding: t; -*- -;; Copyright (C) 2021-2023 Free Software Foundation, Inc. +;; Copyright (C) 2021-2024 Free Software Foundation, Inc. ;; Author: Nicolas Goaziou ;; Maintainer: András Simonyi @@ -134,11 +134,12 @@ (declare-function citeproc-render-bib "ext:citeproc") (declare-function citeproc-hash-itemgetter-from-any "ext:citeproc") (declare-function citeproc-add-subbib-filters "ext:citeproc") +(declare-function citeproc-style-cite-superscript-p "ext:citeproc") (declare-function org-element-interpret-data "org-element" (data)) (declare-function org-element-map "org-element" (data types fun &optional info first-match no-recursion with-affiliated)) -(declare-function org-element-property "org-element" (property element)) -(declare-function org-element-put-property "org-element" (element property value)) +(declare-function org-element-property "org-element-ast" (property node)) +(declare-function org-element-put-property "org-element-ast" (node property value)) (declare-function org-export-data "org-export" (data info)) (declare-function org-export-derived-backend-p "org-export" (backend &rest backends)) @@ -184,8 +185,8 @@ looks for style files in this directory, too." :safe #'booleanp) (defcustom org-cite-csl-no-citelinks-backends '(ascii) - "List of export back-ends for which cite linking is disabled. -Cite linking for export back-ends derived from any of the back-ends listed here, + "List of export backends for which cite linking is disabled. +Cite linking for export backends derived from any of the backends listed here, is also disabled." :group 'org-cite :package-version '(Org . "9.5") @@ -214,6 +215,112 @@ Used only when `second-field-align' is activated by the used CSL style." :type 'string :safe #'stringp) +(defcustom org-cite-csl-latex-label-separator "0.6em" + "Distance between citation label and bibliography item for LaTeX output. +The value is a string representing the distance in valid LaTeX units. +Used only when `second-field-align' is activated by the used CSL +style. + +The indentation length in these cases is computed as the sum of +`org-cite-csl-latex-label-separator' and the maximal label width, for +example, + + indentation length +<-------------------------> +max. label width separator +<---------------><--------> +[Doe22] John Doe. A title... +[DoeSmithJones19] John Doe, Jane Smith and... +[SmithDoe02] Jane Smith and John Doe... + +The maximal label width, in turn, is calculated as the product of +`org-cite-csl-latex-label-width-per-char' and the maximal label +length measured in characters." + :group 'org-cite + :package-version '(Org . "9.7") + :type 'string + :safe #'stringp) + +(defcustom org-cite-csl-latex-label-width-per-char "0.45em" + "Character width in LaTeX units for calculating entry label widths. +Used only when `second-field-align' is activated by the used CSL +style. + +See the documentation of `org-cite-csl-latex-label-separator' for +details." + :group 'org-cite + :package-version '(Org . "9.7") + :type 'string + :safe #'stringp) + +;; The following was inspired by and in many details follows how +;; Pandoc's () default LaTeX template +;; handles CSL output. Many thanks to the author, John MacFarlane! +(defcustom org-cite-csl-latex-preamble + "\\usepackage{calc} +\\newlength{\\cslhangindent} +\\setlength{\\cslhangindent}{[CSL-HANGINDENT]} +\\newlength{\\csllabelsep} +\\setlength{\\csllabelsep}{[CSL-LABELSEP]} +\\newlength{\\csllabelwidth} +\\setlength{\\csllabelwidth}{[CSL-LABELWIDTH-PER-CHAR] * [CSL-MAXLABEL-CHARS]} +\\newenvironment{cslbibliography}[2] % 1st arg. is hanging-indent, 2nd entry spacing. + {% By default, paragraphs are not indented. + \\setlength{\\parindent}{0pt} + % Hanging indent is turned on when first argument is 1. + \\ifodd #1 + \\let\\oldpar\\par + \\def\\par{\\hangindent=\\cslhangindent\\oldpar} + \\fi + % Set entry spacing based on the second argument. + \\setlength{\\parskip}{\\parskip + #2\\baselineskip} + }% + {} +\\newcommand{\\cslblock}[1]{#1\\hfill\\break} +\\newcommand{\\cslleftmargin}[1]{\\parbox[t]{\\csllabelsep + \\csllabelwidth}{#1}} +\\newcommand{\\cslrightinline}[1] + {\\parbox[t]{\\linewidth - \\csllabelsep - \\csllabelwidth}{#1}\\break} +\\newcommand{\\cslindent}[1]{\\hspace{\\cslhangindent}#1} +\\newcommand{\\cslbibitem}[2] + {\\leavevmode\\vadjust pre{\\hypertarget{citeproc_bib_item_#1}{}}#2} +\\makeatletter +\\newcommand{\\cslcitation}[2] + {\\protect\\hyper@linkstart{cite}{citeproc_bib_item_#1}#2\\hyper@linkend} +\\makeatother" + "LaTeX preamble content inserted by the `csl' citation processor. + +This preamble can be anything as long as it provides definitions +for the environment and commands that Citeproc's `org-latex' +formatter uses for formatting citations and bibliographies. In +particular, it has to define +- the commands \\cslblock{}, \\cslleftmargin{}, + \\cslrightinline{} and \\cslindent{} for formatting + text that have, respectively, the CSL display attributes + `block', `left-margin', `right-inline' and `indent'; +- the commands \\cslcitation{}{} and + \\cslbibitem{}{}, which are used to + format individual citations and bibliography items, including + hyperlinking citations to the corresponding bibliography entry + using their numerical id, which is passed as the first, + argument; +- and the environment \\cslbibliography{}{}, + in which bibliographies are wrapped; the value of the + argument is 1 if hanging indent should be + applied and 0 if not, while the argument is an + integer specifying the number of extra line-heights + required between bibliography entries in addition to normal + line spacing. + +When present, the placeholders [CSL-HANGINDENT], [CSL-LABELSEP], +[CSL-LABELWIDTH-PER-CHAR] and [CSL-MAXLABEL-CHARS] are replaced, +respectively, by the contents of the customizable variables +`org-cite-csl-latex-hanging-indent', `org-cite-csl-latex-label-separator', +`org-cite-csl-latex-label-width-per-char', and the maximal label length +in the bibliography measured in characters." + :group 'org-cite + :type 'string + :package-version '(Org . "9.7")) + ;;; Internal variables (defconst org-cite-csl--etc-dir @@ -277,13 +384,17 @@ If nil then the Chicago author-date style is used as a fallback.") ("paragraph" . "paragraph") ("para." . "paragraph") ("paras." . "paragraph") + ("\\P" . "paragraph") ("¶" . "paragraph") + ("\\P\\P" . "paragraph") ("¶¶" . "paragraph") ("part" . "part") ("pt." . "part") ("pts." . "part") ("§" . "section") + ("\\S" . "section") ("§§" . "section") + ("\\S\\S" . "section") ("section" . "section") ("sec." . "section") ("secs." . "section") @@ -312,10 +423,6 @@ Label is in match group 1.") ;;; Internal functions -(defun org-cite-csl--barf-without-citeproc () - "Raise an error if Citeproc library is not loaded." - (unless (featurep 'citeproc) - (error "Citeproc library is not loaded"))) (defun org-cite-csl--note-style-p (info) "Non-nil when bibliography style implies wrapping citations in footnotes. @@ -324,6 +431,13 @@ INFO is the export state, as a property list." (citeproc-proc-style (org-cite-csl--processor info)))) +(defun org-cite-csl--style-cite-superscript-p (info) + "Non-nil when bibliography style produces citations in superscript. +INFO is the export state, as a property list." + (citeproc-style-cite-superscript-p + (citeproc-proc-style + (org-cite-csl--processor info)))) + (defun org-cite-csl--nocite-p (citation info) "Non-nil when CITATION object's style is nocite. INFO is the export state, as a property list." @@ -332,8 +446,8 @@ INFO is the export state, as a property list." (defun org-cite-csl--create-structure-params (citation info) "Return citeproc structure creation params for CITATION object. -STYLE is the citation style, as a string or nil. INFO is the export state, as -a property list." +STYLE is the citation style, as a string or nil. INFO is the export +state, as a property list." (let ((style (org-cite-citation-style citation info))) (pcase style ;; "author" style. @@ -393,7 +507,8 @@ a property list." (_ (error "Invalid style: %S" style))))) (defun org-cite-csl--no-citelinks-p (info) - "Non-nil when export BACKEND should not create cite-reference links." + "Non-nil when export backend should not create cite-reference links. +INFO is the info channel plist." (or (not org-cite-csl-link-cites) (and org-cite-csl-no-citelinks-backends (apply #'org-export-derived-backend-p @@ -413,7 +528,7 @@ corresponding to one of the output formats supported by Citeproc: `html', (let ((backend (plist-get info :back-end))) (cond ((org-export-derived-backend-p backend 'html) 'html) - ((org-export-derived-backend-p backend 'latex) 'latex) + ((org-export-derived-backend-p backend 'latex) 'org-latex) (t 'org)))) (defun org-cite-csl--style-file (info) @@ -569,6 +684,9 @@ INFO is the export state, as a property list." (when (and (not footnote) (org-cite-csl--note-style-p info)) (org-cite-adjust-note citation info) (setq footnote (org-cite-wrap-citation citation info))) + ;; Remove white space before CITATION when it is in superscript. + (when (org-cite-csl--style-cite-superscript-p info) + (org-cite--set-previous-post-blank citation 0 info)) ;; Return structure. (apply #'citeproc-citation-create `(:note-index @@ -670,12 +788,27 @@ value is the bibliography as rendered by Citeproc." (plist-put info :cite-citeproc-rendered-bibliographies result) result))))) +(defun org-cite-csl--generate-latex-preamble (info) + "Generate the CSL-related part of the LaTeX preamble. +INFO is the export state, as a property list." + (let* ((parameters (cadr (org-cite-csl--rendered-bibliographies info))) + (max-offset (cdr (assq 'max-offset parameters))) + (result org-cite-csl-latex-preamble)) + (map-do (lambda (placeholder replacement) + (when (string-match placeholder result) + (setq result (replace-match replacement t t result)))) + `("\\[CSL-HANGINDENT\\]" ,org-cite-csl-latex-hanging-indent + "\\[CSL-LABELSEP\\]" ,org-cite-csl-latex-label-separator + "\\[CSL-LABELWIDTH-PER-CHAR\\]" ,org-cite-csl-latex-label-width-per-char + "\\[CSL-MAXLABEL-CHARS\\]" ,(number-to-string max-offset))) + result)) + ;;; Export capability (defun org-cite-csl-render-citation (citation _style _backend info) "Export CITATION object. INFO is the export state, as a property list." - (org-cite-csl--barf-without-citeproc) + (org-require-package 'citeproc) (let ((output (cdr (assq citation (org-cite-csl--rendered-citations info))))) (if (not (eq 'org (org-cite-csl--output-format info))) output @@ -686,10 +819,10 @@ INFO is the export state, as a property list." (defun org-cite-csl-render-bibliography (_keys _files _style props _backend info) "Export bibliography. INFO is the export state, as a property list." - (org-cite-csl--barf-without-citeproc) + (org-require-package 'citeproc) (pcase-let* ((format (org-cite-csl--output-format info)) - (`(,outputs ,parameters) (org-cite-csl--rendered-bibliographies info)) - (output (cdr (assoc props outputs)))) + (`(,outputs ,parameters) (org-cite-csl--rendered-bibliographies info)) + (output (cdr (assoc props outputs)))) (pcase format ('html (concat @@ -714,12 +847,7 @@ INFO is the export state, as a property list." org-cite-csl-html-hanging-indent org-cite-csl-html-hanging-indent)) output)) - ('latex - (if (cdr (assq 'hanging-indent parameters)) - (format "\\begin{hangparas}{%s}{1}\n%s\n\\end{hangparas}" - org-cite-csl-latex-hanging-indent - output) - output)) + ('org-latex output) (_ ;; Parse Org output to re-export it during the regular export ;; process. @@ -729,19 +857,15 @@ INFO is the export state, as a property list." "Add \"hanging\" package if missing from LaTeX output. OUTPUT is the export document, as a string. INFO is the export state, as a property list." - (org-cite-csl--barf-without-citeproc) - (if (not (eq 'latex (org-cite-csl--output-format info))) + (org-require-package 'citeproc) + (if (not (eq 'org-latex (org-cite-csl--output-format info))) output (with-temp-buffer (save-excursion (insert output)) (when (search-forward "\\begin{document}" nil t) - (goto-char (match-beginning 0)) - ;; Ensure that \citeprocitem is defined for citeproc-el. - (insert "\\makeatletter\n\\newcommand{\\citeprocitem}[2]{\\hyper@linkstart{cite}{citeproc_bib_item_#1}#2\\hyper@linkend}\n\\makeatother\n\n") - ;; Ensure there is a \usepackage{hanging} somewhere or add one. - (let ((re (rx "\\usepackage" (opt "[" (*? nonl) "]") "{hanging}"))) - (unless (re-search-backward re nil t) - (insert "\\usepackage[notquote]{hanging}\n")))) + (goto-char (match-beginning 0)) + ;; Insert the CSL-specific parts of the LaTeX preamble. + (insert (org-cite-csl--generate-latex-preamble info))) (buffer-string)))) diff --git a/elpa/org-9.6.7/oc-natbib.el b/elpa/org-9.7.17/oc-natbib.el similarity index 92% rename from elpa/org-9.6.7/oc-natbib.el rename to elpa/org-9.7.17/oc-natbib.el index 855be2a5..e6b971c0 100644 --- a/elpa/org-9.6.7/oc-natbib.el +++ b/elpa/org-9.7.17/oc-natbib.el @@ -1,6 +1,6 @@ ;;; oc-natbib.el --- Citation processor using natbib LaTeX package -*- lexical-binding: t; -*- -;; Copyright (C) 2021-2023 Free Software Foundation, Inc. +;; Copyright (C) 2021-2024 Free Software Foundation, Inc. ;; Author: Nicolas Goaziou @@ -48,7 +48,7 @@ (require 'oc) -(declare-function org-element-property "org-element" (property element)) +(declare-function org-element-property "org-element-ast" (property node)) (declare-function org-export-data "org-export" (data info)) @@ -77,6 +77,15 @@ If \"natbib\" package is already required in the document, e.g., through (const :tag "redefine \\thebibliography to issue \\section* instead of \\chapter*" sectionbib) (const :tag "keep all the authors' names in a citation on one line" nonamebreak))) +(defcustom org-cite-natbib-bibliography-style 'unsrtnat + "Default bibliography style." + :group 'org-cite + :package-version '(Org . "9.7") + :type + '(choice + (const unsrtnat) + (symbol :tag "Other"))) + ;;; Internal functions (defun org-cite-natbib--style-to-command (style) @@ -143,11 +152,13 @@ CITATION is the citation object. INFO is the export state, as a property list." "Print references from bibliography FILES. FILES is a list of absolute file names. STYLE is the bibliography style, as a string or nil." - (concat (and style (format "\\bibliographystyle{%s}\n" style)) - (format "\\bibliography{%s}" - (mapconcat #'file-name-sans-extension - files - ",")))) + (concat + (format "\\bibliographystyle{%s}\n" + (or style org-cite-natbib-bibliography-style)) + (format "\\bibliography{%s}" + (mapconcat #'file-name-sans-extension + files + ",")))) (defun org-cite-natbib-export-citation (citation style _ info) "Export CITATION object. diff --git a/elpa/org-9.6.7/oc.el b/elpa/org-9.7.17/oc.el similarity index 90% rename from elpa/org-9.6.7/oc.el rename to elpa/org-9.7.17/oc.el index 8a7b6620..af7f3802 100644 --- a/elpa/org-9.6.7/oc.el +++ b/elpa/org-9.7.17/oc.el @@ -1,6 +1,6 @@ ;;; oc.el --- Org Cite library -*- lexical-binding: t; -*- -;; Copyright (C) 2021-2023 Free Software Foundation, Inc. +;; Copyright (C) 2021-2024 Free Software Foundation, Inc. ;; Author: Nicolas Goaziou @@ -46,13 +46,13 @@ ;; The "export" capability is slightly more involved as one need to ;; select the processor providing it, but may also provide a default ;; style for citations and bibliography. Also, the choice of an -;; export processor may depend of the current export back-end. The -;; association between export back-ends and triplets of parameters can +;; export processor may depend of the current export backend. The +;; association between export backends and triplets of parameters can ;; be set in `org-cite-export-processors' variable, or in a document, ;; through the "cite_export" keyword. ;; Eventually, this library provides some tools, mainly targeted at -;; processor implementors. Most are export-specific and are located +;; processor implementers. Most are export-specific and are located ;; in the "Tools only available during export" and "Tools generating ;; or operating on parsed data" sections. @@ -71,25 +71,33 @@ (declare-function org-at-heading-p "org" (&optional _)) (declare-function org-collect-keywords "org" (keywords &optional unique directory)) -(declare-function org-element-adopt-elements "org-element" (parent &rest children)) +(declare-function org-element-adopt "org-element-ast" (parent &rest children)) (declare-function org-element-citation-parser "org-element" ()) (declare-function org-element-citation-reference-parser "org-element" ()) (declare-function org-element-class "org-element" (datum &optional parent)) -(declare-function org-element-contents "org-element" (element)) -(declare-function org-element-create "org-element" (type &optional props &rest children)) -(declare-function org-element-extract-element "org-element" (element)) -(declare-function org-element-insert-before "org-element" (element location)) -(declare-function org-element-lineage "org-element" (datum &optional types with-self)) +(declare-function org-element-contents "org-element-ast" (node)) +(declare-function org-element-create "org-element-ast" (type &optional props &rest children)) +(declare-function org-element-extract "org-element-ast" (node)) +(declare-function org-element-insert-before "org-element-ast" (node location)) +(declare-function org-element-lineage "org-element-ast" (datum &optional types with-self)) (declare-function org-element-map "org-element" (data types fun &optional info first-match no-recursion with-affiliated)) (declare-function org-element-normalize-string "org-element" (s)) -(declare-function org-element-parse-buffer "org-element" (&optional granularity visible-only)) +(declare-function org-element-parse-buffer "org-element" (&optional granularity visible-only keep-deferred)) (declare-function org-element-parse-secondary-string "org-element" (string restriction &optional parent)) (declare-function org-element-context "org-element" (&optional element)) -(declare-function org-element-property "org-element" (property element)) -(declare-function org-element-put-property "org-element" (element property value)) +(declare-function org-element-property "org-element-ast" (property node)) +(declare-function org-element-begin "org-element" (node)) +(declare-function org-element-end "org-element" (node)) +(declare-function org-element-post-affiliated "org-element" (node)) +(declare-function org-element-post-blank "org-element" (node)) +(declare-function org-element-contents-begin "org-element" (node)) +(declare-function org-element-contents-end "org-element" (node)) +(declare-function org-element-parent "org-element-ast" (node)) +(declare-function org-element-put-property "org-element-ast" (node property value)) (declare-function org-element-restriction "org-element" (element)) -(declare-function org-element-set-element "org-element" (old new)) -(declare-function org-element-type "org-element" (element)) +(declare-function org-element-set "org-element-ast" (old new)) +(declare-function org-element-type "org-element-ast" (node &optional anonymous)) +(declare-function org-element-type-p "org-element-ast" (node types)) (declare-function org-export-derived-backend-p "org-export" (backend &rest backends)) (declare-function org-export-get-next-element "org-export" (blob info &optional n)) @@ -143,12 +151,12 @@ File names must be absolute." When nil, citations and bibliography are not exported. -When non-nil, the value is an association list between export back-ends and +When non-nil, the value is an association list between export backends and citation export processors: - (BACK-END . PROCESSOR) + (BACKEND . PROCESSOR) -where BACK-END is the name of an export back-end or t, and PROCESSOR is a +where BACKEND is the name of an export backend or t, and PROCESSOR is a triplet following the pattern (NAME BIBLIOGRAPHY-STYLE CITATION-STYLE) @@ -160,7 +168,7 @@ exporting a citation), as a string or nil. Both BIBLIOGRAPHY-STYLE and CITATION-STYLE are optional. NAME is mandatory. The export process selects the citation processor associated to the current -export back-end, or the most specific back-end the current one is derived from, +export backend, or the most specific backend the current one is derived from, or, if all are inadequate, to the processor associated to t. For example, with the following value @@ -168,9 +176,9 @@ the following value (latex biblatex) (t csl)) -exporting with `beamer' or any back-end derived from it will use `natbib', -whereas exporting with `latex' or any back-end derived from it but different -from `beamer' will use `biblatex' processor. Any other back-end, such as +exporting with `beamer' or any backend derived from it will use `natbib', +whereas exporting with `latex' or any backend derived from it but different +from `beamer' will use `biblatex' processor. Any other backend, such as `html', will use `csl' processor. CITATION-STYLE is overridden by adding a style to any citation object. A nil @@ -187,7 +195,7 @@ or #+CITE_EXPORT: basic In that case, `basic' processor is used on every export, independently on the -back-end." +backend." :group 'org-cite :package-version '(Org . "9.5") :type '(choice (const :tag "No export" nil) @@ -345,7 +353,7 @@ optional keys can be set: arguments: the list of citation keys used in the document, as strings, a list of bibliography files, the style, as a string or nil, the local properties, as a property list, the export - back-end, as a symbol, and the communication channel, as a + backend, as a symbol, and the communication channel, as a property list. It is called at each \"print_bibliography\" keyword in the @@ -358,7 +366,7 @@ optional keys can be set: Function rendering citations. It is called with four arguments: a citation object, the style, as a pair, the - export back-end, as a symbol, and the communication channel, + export backend, as a symbol, and the communication channel, as a property list. It is called on each citation object in the parse tree. It @@ -373,7 +381,7 @@ optional keys can be set: six arguments: the output, as a string, a list of citation keys used in the document, a list of bibliography files, the expected bibliography style, as a string or nil, the export - back-end, as a symbol, and the communication channel, as a + backend, as a symbol, and the communication channel, as a property list. It must return a string, which will become the final output @@ -468,11 +476,11 @@ PROCESSOR is the name of a cite processor, as a symbol. CAPABILITY is "Set `:post-blank' property from element or object before DATUM to BLANKS. DATUM is an element or object. BLANKS is an integer. DATUM is modified by side-effect." - (if (not (eq 'plain-text (org-element-type datum))) + (if (not (org-element-type-p datum 'plain-text)) (org-element-put-property datum :post-blank blanks) ;; Remove any blank from string before DATUM so it is exported ;; with exactly BLANKS white spaces. - (org-element-set-element + (org-element-set datum (replace-regexp-in-string "[ \t\n]*\\'" (make-string blanks ?\s) datum)))) @@ -492,11 +500,11 @@ S is split at beginning of match group N upon matching REGEXP against it. This function assumes S precedes CITATION." ;; When extracting the citation, remove white spaces before it, but ;; preserve those after it. - (let ((post-blank (org-element-property :post-blank citation))) + (let ((post-blank (org-element-post-blank citation))) (when (and post-blank (> post-blank 0)) (org-element-insert-before (make-string post-blank ?\s) citation))) (org-element-insert-before - (org-element-put-property (org-element-extract-element citation) + (org-element-put-property (org-element-extract citation) :post-blank 0) s) (string-match regexp s) @@ -510,21 +518,21 @@ This function assumes S precedes CITATION." (substring s split)))) (when (org-string-nw-p first-part) (org-element-insert-before first-part citation)) - (org-element-set-element s last-part))) + (org-element-set s last-part))) (defun org-cite--move-punct-before (punct citation s info) "Move punctuation PUNCT before CITATION object. String S contains PUNCT. INFO is the export state, as a property list. The function assumes S follows CITATION. Parse tree is modified by side-effect." (if (equal s punct) - (org-element-extract-element s) ;it would be empty anyway - (org-element-set-element s (substring s (length punct)))) + (org-element-extract s) ;it would be empty anyway + (org-element-set s (substring s (length punct)))) ;; Remove blanks before citation. (org-cite--set-previous-post-blank citation 0 info) (org-element-insert-before ;; Blanks between citation and punct are now before punct and ;; citation. - (concat (make-string (or (org-element-property :post-blank citation) 0) ?\s) + (concat (make-string (or (org-element-post-blank citation) 0) ?\s) punct) citation)) @@ -602,7 +610,18 @@ to (adaptive outside after)." (append (mapcar (lambda (value) (pcase value (`(,f . ,d) - (expand-file-name (org-strip-quotes f) d)))) + (setq f (org-strip-quotes f)) + (if (or (file-name-absolute-p f) + (file-remote-p f) + (equal d default-directory)) + ;; Keep absolute paths, remote paths, and + ;; local relative paths. + f + ;; Adjust relative bibliography path for + ;; #+SETUP files located in other directory. + ;; Also, see `org-export--update-included-link'. + (file-relative-name + (expand-file-name f d) default-directory))))) (pcase (org-collect-keywords '("BIBLIOGRAPHY") nil '("BIBLIOGRAPHY")) (`(("BIBLIOGRAPHY" . ,pairs)) pairs))) @@ -619,12 +638,12 @@ or from the current buffer." (let ((contents (org-element-contents citation))) (cond ((null contents) - (org-with-point-at (org-element-property :contents-begin citation) - (narrow-to-region (point) (org-element-property :contents-end citation)) + (org-with-point-at (org-element-contents-begin citation) + (narrow-to-region (point) (org-element-contents-end citation)) (let ((references nil)) (while (not (eobp)) (let ((reference (org-element-citation-reference-parser))) - (goto-char (org-element-property :end reference)) + (goto-char (org-element-end reference)) (push (if keys-only (org-element-property :key reference) reference) @@ -636,8 +655,8 @@ or from the current buffer." (defun org-cite-boundaries (citation) "Return the beginning and end strict position of CITATION. Returns a (BEG . END) pair." - (let ((beg (org-element-property :begin citation)) - (end (org-with-point-at (org-element-property :end citation) + (let ((beg (org-element-begin citation)) + (end (org-with-point-at (org-element-end citation) (skip-chars-backward " \t") (point)))) (cons beg end))) @@ -646,15 +665,15 @@ Returns a (BEG . END) pair." "Return citation REFERENCE's key boundaries as buffer positions. The function returns a pair (START . END) where START and END denote positions in the current buffer. Positions include leading \"@\" character." - (org-with-point-at (org-element-property :begin reference) - (let ((end (org-element-property :end reference))) + (org-with-point-at (org-element-begin reference) + (let ((end (org-element-end reference))) (re-search-forward org-element-citation-key-re end t) (cons (match-beginning 0) (match-end 0))))) (defun org-cite-main-affixes (citation) "Return main affixes for CITATION object. -Some export back-ends only support a single pair of affixes per +Some export backends only support a single pair of affixes per citation, even if it contains multiple keys. This function decides what affixes are the most appropriate. @@ -730,7 +749,7 @@ When removing the last reference, also remove the whole citation." (org-with-point-at begin (skip-chars-backward " \t") (point))) - (pos-after-blank (org-element-property :end datum)) + (pos-after-blank (org-element-end datum)) (first-on-line? (= pos-before-blank (line-beginning-position))) (last-on-line? @@ -753,22 +772,22 @@ When removing the last reference, also remove the whole citation." (when (= pos-after-blank end) (org-with-point-at pos-before-blank (insert " "))))))) ('citation-reference - (let* ((citation (org-element-property :parent datum)) + (let* ((citation (org-element-parent datum)) (references (org-cite-get-references citation)) - (begin (org-element-property :begin datum)) - (end (org-element-property :end datum))) + (begin (org-element-begin datum)) + (end (org-element-end datum))) (cond ;; Single reference. ((= 1 (length references)) (org-cite-delete-citation citation)) ;; First reference, no prefix. - ((and (= begin (org-element-property :contents-begin citation)) + ((and (= begin (org-element-contents-begin citation)) (not (org-element-property :prefix citation))) - (org-with-point-at (org-element-property :begin datum) + (org-with-point-at (org-element-begin datum) (skip-chars-backward " \t") (delete-region (point) end))) ;; Last reference, no suffix. - ((and (= end (org-element-property :contents-end citation)) + ((and (= end (org-element-contents-end citation)) (not (org-element-property :suffix citation))) (delete-region (1- begin) (1- (cdr (org-cite-boundaries citation))))) ;; Somewhere in-between. @@ -838,6 +857,11 @@ tokens. Spurious spaces are ignored." s)) (nreverse result)))) +(defun org-cite-processor (info) + "Return expected citation/bibliography processor. +INFO is a plist used as a communication channel." + (car (plist-get info :cite-export))) + (defun org-cite-bibliography-style (info) "Return expected bibliography style. INFO is a plist used as a communication channel." @@ -937,11 +961,12 @@ the sole contents of the footnote, e.g., after calling `org-cite-wrap-citation'. When non-nil, the return value if the footnote container." (let ((footnote - (org-element-lineage citation - '(footnote-definition footnote-reference)))) + (org-element-lineage + citation + '(footnote-definition footnote-reference)))) (and footnote (or (not strict) - (equal (org-element-contents (org-element-property :parent citation)) + (equal (org-element-contents (org-element-parent citation)) (list citation))) ;; Return value. footnote))) @@ -959,15 +984,15 @@ Return newly created footnote object." (list 'footnote-reference (list :label nil :type 'inline - :contents-begin (org-element-property :begin citation) - :contents-end (org-element-property :end citation) - :post-blank (org-element-property :post-blank citation))))) + :contents-begin (org-element-begin citation) + :contents-end (org-element-end citation) + :post-blank (org-element-post-blank citation))))) ;; Remove any white space before citation. (org-cite--set-previous-post-blank citation 0 info) ;; Footnote swallows citation. (org-element-insert-before footnote citation) - (org-element-adopt-elements footnote - (org-element-extract-element citation)))) + (org-element-adopt footnote + (org-element-extract citation)))) (defun org-cite-adjust-note (citation info &optional rule punct) "Adjust note number location for CITATION object, and punctuation around it. @@ -1046,8 +1071,8 @@ the same object, call `org-cite-adjust-note' first." ;; as an argument is not available. (rx-to-string `(seq string-start ,final-punct) t) "" next))) - (org-element-set-element previous new-prev) - (org-element-set-element next new-next) + (org-element-set previous new-prev) + (org-element-set next new-next) (setq previous new-prev) (setq next new-next) (setq punct final-punct) @@ -1066,15 +1091,15 @@ the same object, call `org-cite-adjust-note' first." (replace-regexp-in-string previous-punct-re "" previous nil nil 1)) (new-next (if (stringp next) (concat punct next) punct))) - (org-element-set-element previous new-prev) + (org-element-set previous new-prev) (cond ((stringp next) - (org-element-set-element next new-next)) + (org-element-set next new-next)) (next (org-element-insert-before new-next next)) (t - (org-element-adopt-elements - (org-element-property :parent citation) + (org-element-adopt + (org-element-parent citation) new-next))) (setq previous new-prev) (setq next new-next) @@ -1141,7 +1166,7 @@ raises an error if S contains a headline." (insert s) (pcase (org-element-contents (org-element-parse-buffer)) ('nil nil) - (`(,(and section (guard (eq 'section (org-element-type section))))) + (`(,(and section (guard (org-element-type-p section 'section)))) (org-element-contents section)) (_ (error "Headlines cannot replace a keyword"))))) @@ -1201,14 +1226,23 @@ and must return either a string, an object, or a secondary string." (org-cite-concat result separator (funcall function datum)))) result))) +(defun org-cite-capitalize (str) + "Capitalize string of raw string object STR." + (cond + ((stringp str) (capitalize str)) + ((org-element-type-p str 'raw) + (org-export-raw-string + (capitalize (mapconcat #'identity (org-element-contents str) "")))) + (t (error "%S must be either a string or raw string object" str)))) + ;;; Internal interface with fontification (activate capability) (defun org-cite-fontify-default (cite) "Fontify CITE with `org-cite' and `org-cite-key' faces. CITE is a citation object. The function applies `org-cite' face on the whole citation, and `org-cite-key' face on each key." - (let ((beg (org-element-property :begin cite)) - (end (org-with-point-at (org-element-property :end cite) + (let ((beg (org-element-begin cite)) + (end (org-with-point-at (org-element-end cite) (skip-chars-backward " \t") (point)))) (add-text-properties beg end '(font-lock-multiline t)) @@ -1237,7 +1271,7 @@ from the processor set in `org-cite-activate-processor'." (save-match-data (funcall activate cite)) ;; Move after cite object and make sure to return ;; a non-nil value. - (goto-char (org-element-property :end cite))))))) + (goto-char (org-element-end cite))))))) ;;; Internal interface with Org Export library (export capability) @@ -1274,12 +1308,12 @@ side-effect." ;; Value is an alist. It must come from ;; `org-cite-export-processors' variable. Find the most ;; appropriate processor according to current export - ;; back-end. + ;; backend. ((and (pred consp) alist) (let* ((backend (plist-get info :back-end)) (candidates ;; Limit candidates to processors associated to - ;; back-ends derived from or equal to the current + ;; backends derived from or equal to the current ;; one. (sort (seq-filter (pcase-lambda (`(,key . ,_)) @@ -1331,7 +1365,7 @@ selected citation processor." (defun org-cite-export-bibliography (keyword _ info) "Return bibliography associated to \"print_bibliography\" KEYWORD. -BACKEND is the export back-end, as a symbol. INFO is a plist +BACKEND is the export backend, as a symbol. INFO is a plist used as a communication channel." (pcase (plist-get info :cite-export) ('nil nil) @@ -1355,7 +1389,7 @@ INFO is the communication channel, as a plist. Parse tree is modified by side-effect." (dolist (cite (org-cite-list-citations info)) (let ((replacement (org-cite-export-citation cite nil info)) - (blanks (or (org-element-property :post-blank cite) 0))) + (blanks (or (org-element-post-blank cite) 0))) (if (null replacement) ;; Before removing the citation, transfer its `:post-blank' ;; property to the object before, if any. @@ -1389,7 +1423,7 @@ by side-effect." (_ (error "Invalid return value from citation export processor: %S" replacement)))) - (org-element-extract-element cite)))) + (org-element-extract cite)))) (defun org-cite-process-bibliography (info) "Replace all \"print_bibliography\" keywords in the parse tree. @@ -1400,18 +1434,18 @@ by side effect." (lambda (keyword) (when (equal "PRINT_BIBLIOGRAPHY" (org-element-property :key keyword)) (let ((replacement (org-cite-export-bibliography keyword nil info)) - (blanks (or (org-element-property :post-blank keyword) 0))) + (blanks (or (org-element-post-blank keyword) 0))) (pcase replacement ;; Before removing the citation, transfer its ;; `:post-blank' property to the element before, if any. ('nil (org-cite--set-previous-post-blank keyword blanks info) - (org-element-extract-element keyword)) + (org-element-extract keyword)) ;; Handle `:post-blank' before replacing keyword with string. ((pred stringp) (let ((output (concat (org-element-normalize-string replacement) (make-string blanks ?\n)))) - (org-element-set-element keyword (org-export-raw-string output)))) + (org-element-set keyword (org-export-raw-string output)))) ;; List of elements: splice contents before keyword and ;; remove the latter. Transfer `:post-blank' to last ;; element. @@ -1421,11 +1455,11 @@ by side effect." (setq last datum) (org-element-insert-before datum keyword)) (org-cite--set-post-blank last blanks) - (org-element-extract-element keyword))) + (org-element-extract keyword))) ;; Single element: replace the keyword. (`(,(pred symbolp) . ,_) (org-cite--set-post-blank replacement blanks) - (org-element-set-element keyword replacement)) + (org-element-set keyword replacement)) (_ (error "Invalid return value from citation export processor: %S" replacement)))))) @@ -1481,7 +1515,7 @@ CONTEXT is the element or object at point, as returned by `org-element-context'. ;; ;; XXX: Inserting citation in a secondary value is not allowed ;; yet. Is it useful? - ((let ((post (org-element-property :post-affiliated context))) + ((let ((post (org-element-post-affiliated context))) (and post (< (point) post))) (let ((case-fold-search t)) (looking-back @@ -1497,14 +1531,14 @@ CONTEXT is the element or object at point, as returned by `org-element-context'. ((memq type '(nil paragraph))) ;; So are contents of verse blocks. ((eq type 'verse-block) - (and (>= (point) (org-element-property :contents-begin context)) - (< (point) (org-element-property :contents-end context)))) + (and (>= (point) (org-element-contents-begin context)) + (< (point) (org-element-contents-end context)))) ;; In an headline or inlinetask, point must be either on the ;; heading itself or on the blank lines below. ((memq type '(headline inlinetask)) (or (not (org-at-heading-p)) (and (save-excursion - (beginning-of-line) + (forward-line 0) (and (let ((case-fold-search t)) (not (looking-at-p "\\*+ END[ \t]*$"))) (let ((case-fold-search nil)) @@ -1523,43 +1557,43 @@ CONTEXT is the element or object at point, as returned by `org-element-context'. ;; White spaces after an object or blank lines after an element ;; are OK. ((>= (point) - (save-excursion (goto-char (org-element-property :end context)) - (skip-chars-backward " \r\t\n") - (if (eq (org-element-class context) 'object) (point) - (line-beginning-position 2))))) + (save-excursion (goto-char (org-element-end context)) + (skip-chars-backward " \r\t\n") + (if (eq (org-element-class context) 'object) (point) + (line-beginning-position 2))))) ;; At the beginning of a footnote definition, right after the ;; label, is OK. ((eq type 'footnote-definition) (looking-at (rx space))) ;; At the start of a list item is fine, as long as the bullet is ;; unaffected. ((eq type 'item) - (> (point) (+ (org-element-property :begin context) + (> (point) (+ (org-element-begin context) (org-current-text-indentation) (if (org-element-property :checkbox context) 5 1)))) ;; Other elements are invalid. ((eq (org-element-class context) 'element) nil) ;; Just before object is fine. - ((= (point) (org-element-property :begin context))) + ((= (point) (org-element-begin context))) ;; Within recursive object too, but not in a link. ((eq type 'link) nil) ((eq type 'table-cell) ;; :contents-begin is not reliable on empty cells, so special ;; case it. (<= (save-excursion (skip-chars-backward " \t") (point)) - (org-element-property :contents-end context))) - ((let ((cbeg (org-element-property :contents-begin context)) - (cend (org-element-property :contents-end context))) + (org-element-contents-end context))) + ((let ((cbeg (org-element-contents-begin context)) + (cend (org-element-contents-end context))) (and cbeg (>= (point) cbeg) (<= (point) cend))))))) (defun org-cite--insert-string-before (string reference) "Insert STRING before citation REFERENCE object." - (org-with-point-at (org-element-property :begin reference) + (org-with-point-at (org-element-begin reference) (insert string ";"))) (defun org-cite--insert-string-after (string reference) "Insert STRING after citation REFERENCE object." - (org-with-point-at (org-element-property :end reference) + (org-with-point-at (org-element-end reference) ;; Make sure to move forward when we're inserting at point, so the ;; insertion can happen multiple times. (if (char-equal ?\; (char-before)) @@ -1630,7 +1664,7 @@ More specifically, ;; action depends on the point. (if arg (org-cite-delete-citation context) - (let* ((begin (org-element-property :begin context)) + (let* ((begin (org-element-begin context)) (style-end (1- (org-with-point-at begin (search-forward ":"))))) (if (>= style-end (point)) ;; On style part, edit the style. @@ -1644,7 +1678,7 @@ More specifically, ;; point. (let* ((references (org-cite-get-references context)) (key (concat "@" (funcall select-key nil)))) - (if (< (point) (org-element-property :contents-begin context)) + (if (< (point) (org-element-contents-begin context)) (org-cite--insert-string-before key (car references)) (org-cite--insert-string-after key (org-last references)))))))) ;; On a citation reference. If ARG is not nil, remove the @@ -1699,7 +1733,7 @@ ARG is the prefix argument received when calling interactively the function." (let ((context (org-element-context)) (insert (org-cite-processor-insert (org-cite-get-processor name)))) (cond - ((memq (org-element-type context) '(citation citation-reference)) + ((org-element-type-p context '(citation citation-reference)) (funcall insert context arg)) ((org-cite--allowed-p context) (funcall insert nil arg)) diff --git a/elpa/org-9.6.7/ol-bbdb.el b/elpa/org-9.7.17/ol-bbdb.el similarity index 98% rename from elpa/org-9.6.7/ol-bbdb.el rename to elpa/org-9.7.17/ol-bbdb.el index 47bd9d98..573e1ee8 100644 --- a/elpa/org-9.6.7/ol-bbdb.el +++ b/elpa/org-9.7.17/ol-bbdb.el @@ -1,10 +1,10 @@ ;;; ol-bbdb.el --- Links to BBDB entries -*- lexical-binding: t; -*- -;; Copyright (C) 2004-2023 Free Software Foundation, Inc. +;; Copyright (C) 2004-2024 Free Software Foundation, Inc. ;; Authors: Carsten Dominik ;; Thomas Baumann -;; Keywords: outlines, hypermedia, calendar, wp +;; Keywords: outlines, hypermedia, calendar, text ;; URL: https://orgmode.org ;; ;; This file is part of GNU Emacs. @@ -226,7 +226,7 @@ date year)." ;;; Implementation -(defun org-bbdb-store-link () +(defun org-bbdb-store-link (&optional _interactive?) "Store a link to a BBDB database entry." (when (eq major-mode 'bbdb-mode) ;; This is BBDB, we make this link! @@ -255,7 +255,7 @@ italicized, in all other cases it is left unchanged." (defun org-bbdb-open (name _) "Follow a BBDB link to NAME." - (require 'bbdb-com) + (org-require-package 'bbdb-com "bbdb") (let ((inhibit-redisplay (not debug-on-error))) (if (fboundp 'bbdb-name) (org-bbdb-open-old name) @@ -369,7 +369,7 @@ This is used by Org to re-create the anniversary hash table." "Extract anniversaries from BBDB for display in the agenda. When called programmatically, this function expects the `date' variable to be globally bound." - (require 'bbdb) + (org-require-package 'bbdb) (require 'diary-lib) (unless (hash-table-p org-bbdb-anniv-hash) (setq org-bbdb-anniv-hash @@ -500,7 +500,7 @@ must be positive")) (defun org-bbdb-complete-link () "Read a bbdb link with name completion." - (require 'bbdb-com) + (org-require-package 'bbdb-com "bbdb") (let ((rec (bbdb-completing-read-record "Name: "))) (concat "bbdb:" (bbdb-record-name (if (listp rec) @@ -509,7 +509,7 @@ must be positive")) (defun org-bbdb-anniv-export-ical () "Extract anniversaries from BBDB and convert them to icalendar format." - (require 'bbdb) + (org-require-package 'bbdb) (require 'diary-lib) (unless (hash-table-p org-bbdb-anniv-hash) (setq org-bbdb-anniv-hash diff --git a/elpa/org-9.6.7/ol-bibtex.el b/elpa/org-9.7.17/ol-bibtex.el similarity index 94% rename from elpa/org-9.6.7/ol-bibtex.el rename to elpa/org-9.7.17/ol-bibtex.el index fd951723..850a2fc2 100644 --- a/elpa/org-9.6.7/ol-bibtex.el +++ b/elpa/org-9.7.17/ol-bibtex.el @@ -1,11 +1,11 @@ ;;; ol-bibtex.el --- Links to BibTeX entries -*- lexical-binding: t; -*- ;; -;; Copyright (C) 2007-2023 Free Software Foundation, Inc. +;; Copyright (C) 2007-2024 Free Software Foundation, Inc. ;; ;; Authors: Bastien Guerry ;; Carsten Dominik ;; Eric Schulte -;; Keywords: org, wp, capture +;; Keywords: org, text, capture ;; ;; This file is part of GNU Emacs. ;; @@ -266,7 +266,7 @@ a missing title field." :type 'boolean) (defcustom org-bibtex-headline-format-function - (lambda (entry) (cdr (assq :title entry))) + #'org-bibtex-headline-format-default "Function returning the headline text for `org-bibtex-write'. It should take a single argument, the bibtex entry (an alist as returned by `org-bibtex-read'). The default value simply returns @@ -507,7 +507,7 @@ ARG, when non-nil, is a universal prefix argument. See `org-open-file' for details." (org-link-open-as-file path arg)) -(defun org-bibtex-store-link () +(defun org-bibtex-store-link (&optional _interactive?) "Store a link to a BibTeX entry." (when (eq major-mode 'bibtex-mode) (let* ((search (org-create-file-search-in-bibtex)) @@ -636,22 +636,27 @@ With prefix argument OPTIONAL also prompt for optional fields." With prefix argument OPTIONAL also prompt for optional fields." (interactive) (org-map-entries (lambda () (org-bibtex-check optional)))) -(defun org-bibtex-create (&optional arg nonew) +(defun org-bibtex-headline-format-default (entry) + "Return headline text according to ENTRY title." + (cdr (assq :title entry))) + +(defun org-bibtex-create (&optional arg update-heading) "Create a new entry at the given level. -With a prefix arg, query for optional fields as well. -If nonew is t, add data to the headline of the entry at point." +With a prefix ARG, query for optional fields as well. +If UPDATE-HEADING is non-nil, add data to the headline of the entry at +point." (interactive "P") (let* ((type (completing-read "Type: " (mapcar (lambda (type) (substring (symbol-name (car type)) 1)) org-bibtex-types) - nil nil (when nonew - (org-bibtex-get org-bibtex-type-property-name)))) + nil nil (when update-heading + (org-bibtex-get org-bibtex-type-property-name)))) (type (if (keywordp type) type (intern (concat ":" type)))) - (org-bibtex-treat-headline-as-title (if nonew nil t))) + (org-bibtex-treat-headline-as-title (if update-heading nil t))) (unless (assoc type org-bibtex-types) (error "Type:%s is not known" type)) - (if nonew + (if update-heading (org-back-to-heading) (org-insert-heading) (let ((title (org-bibtex-ask :title))) @@ -718,29 +723,32 @@ Return the number of saved entries." (interactive "fFile: ") (org-bibtex-read-buffer (find-file-noselect file 'nowarn 'rawfile))) -(defun org-bibtex-write (&optional noindent) +(defun org-bibtex-write (&optional noindent update-heading) "Insert a heading built from the first element of `org-bibtex-entries'. When optional argument NOINDENT is non-nil, do not indent the properties -drawer." +drawer. If UPDATE-HEADING is non-nil, add data to the headline of the +entry at point." (interactive) (unless org-bibtex-entries (error "No entries in `org-bibtex-entries'")) (let* ((entry (pop org-bibtex-entries)) (org-special-properties nil) ; avoids errors with `org-entry-put' (val (lambda (field) (cdr (assoc field entry)))) - (togtag (lambda (tag) (org-toggle-tag tag 'on)))) - (org-insert-heading) - (insert (funcall org-bibtex-headline-format-function entry)) - (insert "\n:PROPERTIES:\n") - (org-bibtex-put "TITLE" (funcall val :title) 'insert) + (togtag (lambda (tag) (org-toggle-tag tag 'on))) + (insert-raw (not update-heading))) + (unless update-heading + (org-insert-heading) + (insert (funcall org-bibtex-headline-format-function entry)) + (insert "\n:PROPERTIES:\n")) + (org-bibtex-put "TITLE" (funcall val :title) insert-raw) (org-bibtex-put org-bibtex-type-property-name (downcase (funcall val :type)) - 'insert) + insert-raw) (dolist (pair entry) (pcase (car pair) (:title nil) (:type nil) - (:key (org-bibtex-put org-bibtex-key-property (cdr pair) 'insert)) + (:key (org-bibtex-put org-bibtex-key-property (cdr pair) insert-raw)) (:keywords (if org-bibtex-tags-are-keywords (dolist (kw (split-string (cdr pair) ", *")) (funcall @@ -748,22 +756,28 @@ drawer." (replace-regexp-in-string "[^[:alnum:]_@#%]" "" (replace-regexp-in-string "[ \t]+" "_" kw)))) - (org-bibtex-put (car pair) (cdr pair) 'insert))) - (_ (org-bibtex-put (car pair) (cdr pair) 'insert)))) - (insert ":END:\n") + (org-bibtex-put (car pair) (cdr pair) insert-raw))) + (_ (org-bibtex-put (car pair) (cdr pair) insert-raw)))) + (unless update-heading + (insert ":END:\n")) (mapc togtag org-bibtex-tags) (unless noindent (org-indent-region (save-excursion (org-back-to-heading t) (point)) (point))))) -(defun org-bibtex-yank () - "If kill ring holds a bibtex entry yank it as an Org headline." - (interactive) +(defun org-bibtex-yank (&optional update-heading) + "If kill ring holds a bibtex entry yank it as an Org headline. +When called with non-nil prefix argument UPDATE-HEADING, add data to the +headline of the entry at point." + (interactive "P") (let (entry) - (with-temp-buffer (yank 1) (setf entry (org-bibtex-read))) + (with-temp-buffer + (yank 1) + (bibtex-mode) + (setf entry (org-bibtex-read))) (if entry - (org-bibtex-write) + (org-bibtex-write nil update-heading) (error "Yanked text does not appear to contain a BibTeX entry")))) (defun org-bibtex-import-from-file (file) diff --git a/elpa/org-9.6.7/ol-docview.el b/elpa/org-9.7.17/ol-docview.el similarity index 86% rename from elpa/org-9.6.7/ol-docview.el rename to elpa/org-9.7.17/ol-docview.el index a9cd9b99..383e3fba 100644 --- a/elpa/org-9.6.7/ol-docview.el +++ b/elpa/org-9.7.17/ol-docview.el @@ -1,9 +1,9 @@ ;;; ol-docview.el --- Links to Docview mode buffers -*- lexical-binding: t; -*- -;; Copyright (C) 2009-2023 Free Software Foundation, Inc. +;; Copyright (C) 2009-2024 Free Software Foundation, Inc. ;; Author: Jan Böcker -;; Keywords: outlines, hypermedia, calendar, wp +;; Keywords: outlines, hypermedia, calendar, text ;; URL: https://orgmode.org ;; ;; This file is part of GNU Emacs. @@ -57,20 +57,21 @@ :export #'org-docview-export :store #'org-docview-store-link) -(defun org-docview-export (link description format) - "Export a docview link from Org files." +(defun org-docview-export (link description backend _info) + "Export a docview LINK with DESCRIPTION for BACKEND." (let ((path (if (string-match "\\(.+\\)::.+" link) (match-string 1 link) link)) (desc (or description link))) (when (stringp path) (setq path (expand-file-name path)) (cond - ((eq format 'html) (format "%s" path desc)) - ((eq format 'latex) (format "\\href{%s}{%s}" path desc)) - ((eq format 'ascii) (format "%s (%s)" desc path)) + ((eq backend 'html) (format "%s" path desc)) + ((eq backend 'latex) (format "\\href{%s}{%s}" path desc)) + ((eq backend 'ascii) (format "[%s] (<%s>)" desc path)) (t path))))) (defun org-docview-open (link _) + "Open docview: LINK." (string-match "\\(.*?\\)\\(?:::\\([0-9]+\\)\\)?$" link) (let ((path (match-string 1 link)) (page (and (match-beginning 2) @@ -82,7 +83,7 @@ (error "No such file: %s" path)) (when page (doc-view-goto-page page)))) -(defun org-docview-store-link () +(defun org-docview-store-link (&optional _interactive?) "Store a link to a docview buffer." (when (eq major-mode 'doc-view-mode) ;; This buffer is in doc-view-mode diff --git a/elpa/org-9.6.7/ol-doi.el b/elpa/org-9.7.17/ol-doi.el similarity index 94% rename from elpa/org-9.6.7/ol-doi.el rename to elpa/org-9.7.17/ol-doi.el index 971b0508..64eb6869 100644 --- a/elpa/org-9.6.7/ol-doi.el +++ b/elpa/org-9.7.17/ol-doi.el @@ -1,6 +1,6 @@ ;;; ol-doi.el --- DOI links support in Org -*- lexical-binding: t; -*- -;; Copyright (C) 2021-2023 Free Software Foundation, Inc. +;; Copyright (C) 2021-2024 Free Software Foundation, Inc. ;; Author: Nicolas Goaziou @@ -40,7 +40,8 @@ (defun org-link-doi-open (path arg) "Open a \"doi\" type link. -PATH is a the path to search for, as a string." +PATH is a the path to search for, as a string. +ARG is passed to `browse-url'." (browse-url (url-encode-url (concat org-link-doi-server-url path)) arg)) (defun org-link-doi-export (path desc backend info) diff --git a/elpa/org-9.6.7/ol-eshell.el b/elpa/org-9.7.17/ol-eshell.el similarity index 85% rename from elpa/org-9.6.7/ol-eshell.el rename to elpa/org-9.7.17/ol-eshell.el index b7d3baf3..595dd0ee 100644 --- a/elpa/org-9.6.7/ol-eshell.el +++ b/elpa/org-9.7.17/ol-eshell.el @@ -1,6 +1,6 @@ ;;; ol-eshell.el --- Links to Working Directories in Eshell -*- lexical-binding: t; -*- -;; Copyright (C) 2011-2023 Free Software Foundation, Inc. +;; Copyright (C) 2011-2024 Free Software Foundation, Inc. ;; Author: Konrad Hinsen @@ -37,8 +37,8 @@ :store #'org-eshell-store-link) (defun org-eshell-open (link _) - "Switch to an eshell buffer and execute a command line. -The link can be just a command line (executed in the default + "Switch to an eshell buffer and execute a command line for LINK. +The LINK can be just a command line (executed in the default eshell buffer) or a command line prefixed by a buffer name followed by a colon." (let* ((buffer-and-command @@ -60,9 +60,10 @@ followed by a colon." (insert command) (eshell-send-input))) -(defun org-eshell-store-link () - "Store a link that, when opened, switches back to the current eshell buffer -and the current working directory." +(defun org-eshell-store-link (&optional _interactive?) + "Store eshell link. +When opened, the link switches back to the current eshell buffer and +the current working directory." (when (eq major-mode 'eshell-mode) (let* ((command (concat "cd " (eshell/pwd))) (link (concat (buffer-name) ":" command))) diff --git a/elpa/org-9.6.7/ol-eww.el b/elpa/org-9.7.17/ol-eww.el similarity index 97% rename from elpa/org-9.6.7/ol-eww.el rename to elpa/org-9.7.17/ol-eww.el index ee970b6a..c13dbf33 100644 --- a/elpa/org-9.6.7/ol-eww.el +++ b/elpa/org-9.7.17/ol-eww.el @@ -1,6 +1,6 @@ ;;; ol-eww.el --- Store URL and kill from Eww mode -*- lexical-binding: t -*- -;; Copyright (C) 2014-2023 Free Software Foundation, Inc. +;; Copyright (C) 2014-2024 Free Software Foundation, Inc. ;; Author: Marco Wahl a ;; Keywords: link, eww @@ -62,7 +62,7 @@ "Open URL with Eww in the current buffer." (eww url)) -(defun org-eww-store-link () +(defun org-eww-store-link (&optional _interactive?) "Store a link to the url of an EWW buffer." (when (eq major-mode 'eww-mode) (org-link-store-props @@ -162,6 +162,7 @@ keep the structure of the Org file." ;; Additional keys for eww-mode (defun org-eww-extend-eww-keymap () + "Add ol-eww bindings to `eww-mode-map'." (define-key eww-mode-map "\C-c\C-x\M-w" 'org-eww-copy-for-org-mode) (define-key eww-mode-map "\C-c\C-x\C-w" 'org-eww-copy-for-org-mode)) diff --git a/elpa/org-9.6.7/ol-gnus.el b/elpa/org-9.7.17/ol-gnus.el similarity index 91% rename from elpa/org-9.6.7/ol-gnus.el rename to elpa/org-9.7.17/ol-gnus.el index 7c07ce04..278c59ed 100644 --- a/elpa/org-9.6.7/ol-gnus.el +++ b/elpa/org-9.7.17/ol-gnus.el @@ -1,10 +1,10 @@ ;;; ol-gnus.el --- Links to Gnus Groups and Messages -*- lexical-binding: t; -*- -;; Copyright (C) 2004-2023 Free Software Foundation, Inc. +;; Copyright (C) 2004-2024 Free Software Foundation, Inc. ;; Author: Carsten Dominik ;; Tassilo Horn -;; Keywords: outlines, hypermedia, calendar, wp +;; Keywords: outlines, hypermedia, calendar, text ;; URL: https://orgmode.org ;; ;; This file is part of GNU Emacs. @@ -123,7 +123,7 @@ If `org-store-link' was called with a prefix arg the meaning of (url-encode-url message-id)) (concat "gnus:" group "#" message-id))) -(defun org-gnus-store-link () +(defun org-gnus-store-link (&optional _interactive?) "Store a link to a Gnus folder or message." (pcase major-mode (`gnus-group-mode @@ -137,27 +137,23 @@ If `org-store-link' was called with a prefix arg the meaning of (let* ((group (pcase (gnus-find-method-for-group gnus-newsgroup-name) (`(nnvirtual . ,_) - (save-excursion - (car (nnvirtual-map-article (gnus-summary-article-number))))) + (with-current-buffer gnus-summary-buffer + (save-excursion + (car (nnvirtual-map-article (gnus-summary-article-number)))))) (`(,(or `nnselect `nnir) . ,_) ; nnir is for Emacs < 28. - (save-excursion - (cond - ((fboundp 'nnselect-article-group) - (nnselect-article-group (gnus-summary-article-number))) - ((fboundp 'nnir-article-group) - (nnir-article-group (gnus-summary-article-number))) - (t - (error "No article-group variant bound"))))) + (with-current-buffer gnus-summary-buffer + (save-excursion + (cond + ((fboundp 'nnselect-article-group) + (nnselect-article-group (gnus-summary-article-number))) + ((fboundp 'nnir-article-group) + (nnir-article-group (gnus-summary-article-number))) + (t + (error "No article-group variant bound")))))) (_ gnus-newsgroup-name))) - (header (if (eq major-mode 'gnus-article-mode) - ;; When in an article, first move to summary - ;; buffer, with point on the summary of the - ;; current article before extracting headers. - (save-window-excursion - (save-excursion - (gnus-article-show-summary) - (gnus-summary-article-header))) - (gnus-summary-article-header))) + (header (with-current-buffer gnus-summary-buffer + (save-excursion + (gnus-summary-article-header)))) (from (mail-header-from header)) (message-id (org-unbracket-string "<" ">" (mail-header-id header))) (date (org-trim (mail-header-date header))) diff --git a/elpa/org-9.6.7/ol-info.el b/elpa/org-9.7.17/ol-info.el similarity index 85% rename from elpa/org-9.6.7/ol-info.el rename to elpa/org-9.7.17/ol-info.el index ad9e4a12..fa9b23b8 100644 --- a/elpa/org-9.6.7/ol-info.el +++ b/elpa/org-9.7.17/ol-info.el @@ -1,9 +1,9 @@ ;;; ol-info.el --- Links to Info Nodes -*- lexical-binding: t; -*- -;; Copyright (C) 2004-2023 Free Software Foundation, Inc. +;; Copyright (C) 2004-2024 Free Software Foundation, Inc. ;; Author: Carsten Dominik -;; Keywords: outlines, hypermedia, calendar, wp +;; Keywords: outlines, hypermedia, calendar, text ;; URL: https://orgmode.org ;; ;; This file is part of GNU Emacs. @@ -50,7 +50,7 @@ :insert-description #'org-info-description-as-command) ;; Implementation -(defun org-info-store-link () +(defun org-info-store-link (&optional _interactive?) "Store a link to an Info file and node." (when (eq major-mode 'Info-mode) (let ((link (concat "info:" @@ -129,23 +129,27 @@ If LINK is not an info link then DESC is returned." (defconst org-info-emacs-documents '("ada-mode" "auth" "autotype" "bovine" "calc" "ccmode" "cl" "dbus" "dired-x" - "ebrowse" "ede" "ediff" "edt" "efaq-w32" "efaq" "eieio" "eintr" "elisp" - "emacs-gnutls" "emacs-mime" "emacs" "epa" "erc" "ert" "eshell" "eudc" "eww" - "flymake" "forms" "gnus" "htmlfontify" "idlwave" "ido" "info" "mairix-el" - "message" "mh-e" "newsticker" "nxml-mode" "octave-mode" "org" "pcl-cvs" - "pgg" "rcirc" "reftex" "remember" "sasl" "sc" "semantic" "ses" "sieve" - "smtpmail" "speedbar" "srecode" "todo-mode" "tramp" "url" "vip" "viper" - "widget" "wisent" "woman") + "ebrowse" "ede" "ediff" "edt" "efaq-w32" "efaq" "eglot" "eieio" "eintr" + "elisp" "emacs-gnutls" "emacs-mime" "emacs" "epa" "erc" "ert" "eshell" + "eudc" "eww" "flymake" "forms" "gnus" "htmlfontify" "idlwave" "ido" "info" + "mairix-el" "message" "mh-e" "modus-themes" "newsticker" "nxml-mode" "octave-mode" + "org" "pcl-cvs" "pgg" "rcirc" "reftex" "remember" "sasl" "sc" "semantic" + "ses" "sieve" "smtpmail" "speedbar" "srecode" "todo-mode" "tramp" "transient" + "url" "use-package" "vhdl-mode" "vip" "viper" "vtable" "widget" "wisent" "woman") "List of Emacs documents available. Taken from ") -(defconst org-info-other-documents +(defcustom org-info-other-documents '(("dir" . "https://www.gnu.org/manual/manual.html") ; index ("libc" . "https://www.gnu.org/software/libc/manual/html_mono/libc.html") ("make" . "https://www.gnu.org/software/make/manual/make.html")) "Alist of documents generated from Texinfo source. When converting info links to HTML, links to any one of these manuals are -converted to use these URL.") +converted to use these URL." + :group 'org-link + :type '(alist :key-type string :value-type string) + :package-version '(Org . "9.7") + :safe t) (defun org-info-map-html-url (filename) "Return URL or HTML file associated to Info FILENAME. @@ -153,11 +157,11 @@ If FILENAME refers to an official GNU document, return a URL pointing to the official page for that document, e.g., use \"gnu.org\" for all Emacs related documents. Otherwise, append \".html\" extension to FILENAME. See `org-info-emacs-documents' and `org-info-other-documents' for details." - (cond ((member filename org-info-emacs-documents) - (format "https://www.gnu.org/software/emacs/manual/html_mono/%s.html" - filename)) - ((cdr (assoc filename org-info-other-documents))) - (t (concat filename ".html")))) + (cond ((cdr (assoc filename org-info-other-documents))) + ((member filename org-info-emacs-documents) + (format "https://www.gnu.org/software/emacs/manual/html_mono/%s.html" + filename)) + (t (concat filename ".html")))) (defun org-info--expand-node-name (node) "Expand Info NODE to HTML cross reference." diff --git a/elpa/org-9.6.7/ol-irc.el b/elpa/org-9.7.17/ol-irc.el similarity index 98% rename from elpa/org-9.6.7/ol-irc.el rename to elpa/org-9.7.17/ol-irc.el index 3760644e..b263e52d 100644 --- a/elpa/org-9.6.7/ol-irc.el +++ b/elpa/org-9.7.17/ol-irc.el @@ -1,6 +1,6 @@ ;;; ol-irc.el --- Links to IRC Sessions -*- lexical-binding: t; -*- ;; -;; Copyright (C) 2008-2023 Free Software Foundation, Inc. +;; Copyright (C) 2008-2024 Free Software Foundation, Inc. ;; ;; Author: Philip Jackson ;; Keywords: erc, irc, link, org @@ -103,7 +103,7 @@ attributes that are found." parts)) ;;;###autoload -(defun org-irc-store-link () +(defun org-irc-store-link (&optional _interactive?) "Dispatch to the appropriate function to store a link to an IRC session." (cond ((eq major-mode 'erc-mode) diff --git a/elpa/org-9.6.7/ol-man.el b/elpa/org-9.7.17/ol-man.el similarity index 60% rename from elpa/org-9.6.7/ol-man.el rename to elpa/org-9.7.17/ol-man.el index 40fdc8f9..7070f48a 100644 --- a/elpa/org-9.6.7/ol-man.el +++ b/elpa/org-9.7.17/ol-man.el @@ -1,9 +1,9 @@ ;;; ol-man.el --- Links to man pages -*- lexical-binding: t; -*- ;; -;; Copyright (C) 2020-2023 Free Software Foundation, Inc. +;; Copyright (C) 2020-2024 Free Software Foundation, Inc. ;; Author: Carsten Dominik ;; Maintainer: Bastien Guerry -;; Keywords: outlines, hypermedia, calendar, wp +;; Keywords: outlines, hypermedia, calendar, text ;; URL: https://orgmode.org ;; ;; This file is part of GNU Emacs. @@ -24,12 +24,17 @@ ;; ;;; Commentary: +;; This file implements links to man pages from within Org mode. + +;;; Code: + (require 'org-macs) (org-assert-version) (require 'ol) (org-link-set-parameters "man" + :complete #'org-man-complete :follow #'org-man-open :export #'org-man-export :store #'org-man-store-link) @@ -37,15 +42,29 @@ (defcustom org-man-command 'man "The Emacs command to be used to display a man page." :group 'org-link - :type '(choice (const man) (const woman))) + :type '(choice (const man) (const :tag "WoMan (obsolete)" woman))) +(declare-function Man-translate-references "man" (ref)) (defun org-man-open (path _) "Visit the manpage on PATH. PATH should be a topic that can be thrown at the man command. If PATH contains extra ::STRING which will use `occur' to search matched strings in man buffer." + (require 'man) ; For `Man-translate-references' (string-match "\\(.*?\\)\\(?:::\\(.*\\)\\)?$" path) (let* ((command (match-string 1 path)) + ;; FIXME: Remove after we drop Emacs 29 support. + ;; Working around security bug #66390. + (command (if (not (equal (Man-translate-references ";id") ";id")) + ;; We are on Emacs that escapes man command args + ;; (see Emacs commit 820f0793f0b). + command + ;; Older Emacs without the fix - escape the + ;; arguments ourselves. + (mapconcat 'identity + (mapcar #'shell-quote-argument + (split-string command "\\s-+")) + " "))) (search (match-string 2 path)) (buffer (funcall org-man-command command))) (when search @@ -63,7 +82,7 @@ matched strings in man buffer." (set-window-point window point) (set-window-start window point))))))) -(defun org-man-store-link () +(defun org-man-store-link (&optional _interactive?) "Store a link to a README file." (when (memq major-mode '(Man-mode woman-mode)) ;; This is a man page, we do make this link @@ -82,18 +101,31 @@ matched strings in man buffer." (match-string 1 (buffer-name)) (error "Cannot create link to this man page"))) -(defun org-man-export (link description format) - "Export a man page link from Org files." +(defun org-man-export (link description backend) + "Export a man page LINK with DESCRIPTION. +BACKEND is the current export backend." (let ((path (format "http://man.he.net/?topic=%s§ion=all" link)) (desc (or description link))) (cond - ((eq format 'html) (format "%s" path desc)) - ((eq format 'latex) (format "\\href{%s}{%s}" path desc)) - ((eq format 'texinfo) (format "@uref{%s,%s}" path desc)) - ((eq format 'ascii) (format "%s (%s)" desc path)) - ((eq format 'md) (format "[%s](%s)" desc path)) + ((eq backend 'html) (format "%s" path desc)) + ((eq backend 'latex) (format "\\href{%s}{%s}" path desc)) + ((eq backend 'texinfo) (format "@uref{%s,%s}" path desc)) + ((eq backend 'ascii) (format "[%s] (<%s>)" desc path)) + ((eq backend 'md) (format "[%s](%s)" desc path)) (t path)))) +(defvar Man-completion-cache) ; Defined in `man'. +(defun org-man-complete (&optional _arg) + "Complete man pages for `org-insert-link'." + (require 'man) + (concat + "man:" + (let ((completion-ignore-case t) ; See `man' comments. + (Man-completion-cache)) ; See `man' implementation. + (completing-read + "Manual entry: " + 'Man-completion-table)))) + (provide 'ol-man) ;;; ol-man.el ends here diff --git a/elpa/org-9.6.7/ol-mhe.el b/elpa/org-9.7.17/ol-mhe.el similarity index 97% rename from elpa/org-9.6.7/ol-mhe.el rename to elpa/org-9.7.17/ol-mhe.el index 403b5a25..b715f6a0 100644 --- a/elpa/org-9.6.7/ol-mhe.el +++ b/elpa/org-9.7.17/ol-mhe.el @@ -1,9 +1,9 @@ ;;; ol-mhe.el --- Links to MH-E Messages -*- lexical-binding: t; -*- -;; Copyright (C) 2004-2023 Free Software Foundation, Inc. +;; Copyright (C) 2004-2024 Free Software Foundation, Inc. ;; Author: Thomas Baumann -;; Keywords: outlines, hypermedia, calendar, wp +;; Keywords: outlines, hypermedia, calendar, text ;; URL: https://orgmode.org ;; ;; This file is part of GNU Emacs. @@ -80,7 +80,7 @@ supported by MH-E." (org-link-set-parameters "mhe" :follow #'org-mhe-open :store #'org-mhe-store-link) ;; Implementation -(defun org-mhe-store-link () +(defun org-mhe-store-link (&optional _interactive?) "Store a link to an MH-E folder or message." (when (or (eq major-mode 'mh-folder-mode) (eq major-mode 'mh-show-mode)) diff --git a/elpa/org-9.6.7/ol-rmail.el b/elpa/org-9.7.17/ol-rmail.el similarity index 96% rename from elpa/org-9.6.7/ol-rmail.el rename to elpa/org-9.7.17/ol-rmail.el index 28777982..fb32a450 100644 --- a/elpa/org-9.6.7/ol-rmail.el +++ b/elpa/org-9.7.17/ol-rmail.el @@ -1,9 +1,9 @@ ;;; ol-rmail.el --- Links to Rmail Messages -*- lexical-binding: t; -*- -;; Copyright (C) 2004-2023 Free Software Foundation, Inc. +;; Copyright (C) 2004-2024 Free Software Foundation, Inc. ;; Author: Carsten Dominik -;; Keywords: outlines, hypermedia, calendar, wp +;; Keywords: outlines, hypermedia, calendar, text ;; URL: https://orgmode.org ;; ;; This file is part of GNU Emacs. @@ -51,7 +51,7 @@ :store #'org-rmail-store-link) ;; Implementation -(defun org-rmail-store-link () +(defun org-rmail-store-link (&optional _interactive?) "Store a link to an Rmail folder or message." (when (or (eq major-mode 'rmail-mode) (eq major-mode 'rmail-summary-mode)) diff --git a/elpa/org-9.6.7/ol-w3m.el b/elpa/org-9.7.17/ol-w3m.el similarity index 98% rename from elpa/org-9.6.7/ol-w3m.el rename to elpa/org-9.7.17/ol-w3m.el index 6fb01a60..e8981173 100644 --- a/elpa/org-9.6.7/ol-w3m.el +++ b/elpa/org-9.7.17/ol-w3m.el @@ -1,9 +1,9 @@ ;;; ol-w3m.el --- Copy and Paste From W3M -*- lexical-binding: t; -*- -;; Copyright (C) 2008-2023 Free Software Foundation, Inc. +;; Copyright (C) 2008-2024 Free Software Foundation, Inc. ;; Author: Andy Stewart -;; Keywords: outlines, hypermedia, calendar, wp +;; Keywords: outlines, hypermedia, calendar, text ;; URL: https://orgmode.org ;; ;; This file is part of GNU Emacs. diff --git a/elpa/org-9.6.7/ol.el b/elpa/org-9.7.17/ol.el similarity index 76% rename from elpa/org-9.6.7/ol.el rename to elpa/org-9.7.17/ol.el index 9ad191c8..c3101254 100644 --- a/elpa/org-9.6.7/ol.el +++ b/elpa/org-9.7.17/ol.el @@ -1,9 +1,9 @@ ;;; ol.el --- Org links library -*- lexical-binding: t; -*- -;; Copyright (C) 2018-2023 Free Software Foundation, Inc. +;; Copyright (C) 2018-2024 Free Software Foundation, Inc. ;; Author: Carsten Dominik -;; Keywords: outlines, hypermedia, calendar, wp +;; Keywords: outlines, hypermedia, calendar, text ;; This file is part of GNU Emacs. @@ -52,17 +52,19 @@ (declare-function org-do-occur "org" (regexp &optional cleanup)) (declare-function org-element-at-point "org-element" (&optional pom cached-only)) (declare-function org-element-cache-refresh "org-element" (pos)) +(declare-function org-element-cache-reset "org-element" (&optional all no-persistence)) (declare-function org-element-context "org-element" (&optional element)) -(declare-function org-element-lineage "org-element" (datum &optional types with-self)) +(declare-function org-element-lineage "org-element-ast" (datum &optional types with-self)) (declare-function org-element-link-parser "org-element" ()) -(declare-function org-element-property "org-element" (property element)) -(declare-function org-element-type "org-element" (element)) +(declare-function org-element-property "org-element-ast" (property node)) +(declare-function org-element-begin "org-element" (node)) +(declare-function org-element-end "org-element" (node)) +(declare-function org-element-type-p "org-element-ast" (node types)) (declare-function org-element-update-syntax "org-element" ()) (declare-function org-entry-get "org" (pom property &optional inherit literal-nil)) (declare-function org-find-property "org" (property &optional value)) (declare-function org-get-heading "org" (&optional no-tags no-todo no-priority no-comment)) (declare-function org-id-find-id-file "org-id" (id)) -(declare-function org-id-store-link "org-id" ()) (declare-function org-insert-heading "org" (&optional arg invisible-ok top)) (declare-function org-load-modules-maybe "org" (&optional force)) (declare-function org-mark-ring-push "org" (&optional pos buffer)) @@ -114,11 +116,11 @@ below. Function that accepts four arguments: - the path, as a string, - the description as a string, or nil, - - the export back-end, + - the export backend, - the export communication channel, as a plist. When nil, export for that type of link is delegated to the - back-end. + backend. `:store' @@ -196,6 +198,16 @@ link. :type '(alist :tag "Link display parameters" :value-type plist)) +(defun org-link--set-link-display (symbol value) + "Set `org-link-descriptive' (SYMBOL) to VALUE. +Also, ensure that links are updated in current buffer. + +This function is intended to be used as a :set function." + (set symbol value) + (dolist (buf (org-buffer-list)) + (with-current-buffer buf + (org-restart-font-lock)))) + (defcustom org-link-descriptive t "Non-nil means Org displays descriptive links. @@ -207,6 +219,7 @@ literally. You can interactively set the value of this variable by calling `org-toggle-link-display' or from the \"Org > Hyperlinks\" menu." :group 'org-link + :set #'org-link--set-link-display :type 'boolean :safe #'booleanp) @@ -234,7 +247,7 @@ adaptive Use relative path for files in the current directory and sub- directories of it. For other files, use an absolute path. Alternatively, users may supply a custom function that takes the -full filename as an argument and returns the path." +filename in the link as an argument and returns the path." :group 'org-link :type '(choice (const relative) @@ -274,10 +287,14 @@ See the manual for examples." (choice (string :tag "Format") (function)))) - :safe (lambda (val) - (pcase val - (`(,(pred stringp) . ,(pred stringp)) t) - (_ nil)))) + :safe (lambda (alist) + (when (listp alist) + (catch :unsafe + (dolist (val alist) + (pcase val + (`(,(pred stringp) . ,(pred stringp)) t) + (_ (throw :unsafe nil)))) + t)))) (defgroup org-link-follow nil "Options concerning following links in Org mode." @@ -291,10 +308,7 @@ or emacs-wiki packages to Org syntax. The function must accept two parameters, a TYPE containing the link protocol name like \"rmail\" or \"gnus\" as a string, and the linked path, which is everything after the link protocol. It should return a cons -with possibly modified values of type and path. -Org contains a function for this, so if you set this variable to -`org-translate-link-from-planner', you should be able follow many -links created by planner." +with possibly modified values of type and path." :group 'org-link-follow :type '(choice (const nil) (function)) :safe #'null) @@ -355,14 +369,17 @@ another window." (const wl-other-frame))))) (defcustom org-link-search-must-match-exact-headline 'query-to-create - "Non-nil means internal fuzzy links can only match headlines. + "Control fuzzy link behavior when specific matches not found. -When nil, the fuzzy link may point to a target or a named -construct in the document. When set to the special value -`query-to-create', offer to create a new headline when none -matched. +When nil, if a fuzzy link does not match a more specific +target (such as a heading, named block, target, or code ref), +attempt a regular text search. When set to the special value +`query-to-create', offer to create a new heading matching the +link instead. Otherwise, signal an error rather than attempting +a regular text search. -Spaces and statistics cookies are ignored during heading searches." +This option only affects behavior in Org buffers. Spaces and +statistics cookies are ignored during heading searches." :group 'org-link-follow :version "24.1" :type '(choice @@ -516,6 +533,16 @@ links more efficient." (defvar-local org-target-link-regexp nil "Regular expression matching radio targets in plain text.") +(defconst org-target-link-regexp-limit (ash 2 12) + "Maximum allowed length of regexp. +The number should generally be ~order of magnitude smaller than +MAX_BUF_SIZE in src/regex-emacs.c. The number of regexp-emacs.c is +for processed regexp, which appears to be larger compared to the +original string length.") +(defvar-local org-target-link-regexps nil + "List of regular expressions matching radio targets in plain text. +This list is non-nil, when a single regexp would be too long to match +all the possible targets, exceeding Emacs's regexp length limit.") (defvar org-link-types-re nil "Matches a link that has a url-like prefix like \"http:\".") @@ -563,9 +590,9 @@ taken to make the search successful, another function should be added to the companion hook `org-execute-file-search-functions', which see. -A function in this hook may also use `setq' to set the variable -`description' to provide a suggestion for the descriptive text to -be used for this link when it gets inserted into an Org buffer +A function in this hook may also use `org-link-store-props' and set +`:description' property to provide a suggestion for the descriptive +text to be used for this link when it gets inserted into an Org buffer with \\[org-insert-link].") (defvar org-execute-file-search-functions nil @@ -622,22 +649,6 @@ exact and fuzzy text search.") (defvar org-link--search-failed nil "Non-nil when last link search failed.") - -(defvar-local org-link--link-folding-spec '(org-link - (:global t) - (:ellipsis . nil) - (:isearch-open . t) - (:fragile . org-link--reveal-maybe)) - "Folding spec used to hide invisible parts of links.") - -(defvar-local org-link--description-folding-spec '(org-link-description - (:global t) - (:ellipsis . nil) - (:visible . t) - (:isearch-open . nil) - (:fragile . org-link--reveal-maybe)) - "Folding spec used to reveal link description.") - ;;; Internal Functions @@ -750,8 +761,8 @@ White spaces are not significant." (while (re-search-forward re nil t) (forward-char -1) (let ((object (org-element-context))) - (when (eq (org-element-type object) 'radio-target) - (goto-char (org-element-property :begin object)) + (when (org-element-type-p object 'radio-target) + (goto-char (org-element-begin object)) (org-fold-show-context 'link-search) (throw :radio-match nil)))) (goto-char origin) @@ -802,6 +813,74 @@ spec." (org-with-point-at (car region) (not (org-in-regexp org-link-any-re)))) +(defun org-link--try-link-store-functions (interactive?) + "Try storing external links, prompting if more than one is possible. + +Each function returned by `org-store-link-functions' is called in +turn. If multiple functions return non-nil, prompt for which +link should be stored. + +Argument INTERACTIVE? indicates whether `org-store-link' was +called interactively and is passed to the link store functions. + +Return t when a link has been stored in `org-link-store-props'." + (let ((results-alist nil)) + (dolist (f (org-store-link-functions)) + (when (condition-case nil + (funcall f interactive?) + ;; FIXME: The store function used (< Org 9.7) to accept + ;; no arguments; provide backward compatibility support + ;; for them. + (wrong-number-of-arguments + (funcall f))) + ;; FIXME: return value is not link's plist, so we store the + ;; new value before it is modified. It would be cleaner to + ;; ask store link functions to return the plist instead. + (push (cons f (copy-sequence org-store-link-plist)) + results-alist))) + (pcase results-alist + (`nil nil) + (`((,_ . ,_)) t) ;single choice: nothing to do + (`((,name . ,_) . ,_) + ;; Reinstate link plist associated to the chosen + ;; function. + (apply #'org-link-store-props + (cdr (assoc-string + (completing-read + (format "Store link with (default %s): " name) + (mapcar #'car results-alist) + nil t nil nil (symbol-name name)) + results-alist))) + t)))) + +(defun org-link--add-to-stored-links (link desc) + "Add LINK to `org-stored-links' with description DESC." + (cond + ((not (member (list link desc) org-stored-links)) + (push (list link desc) org-stored-links) + (message "Stored: %s" (or desc link))) + ((equal (list link desc) (car org-stored-links)) + (message "This link has already been stored")) + (t + (setq org-stored-links + (delete (list link desc) org-stored-links)) + (push (list link desc) org-stored-links) + (message "Link moved to front: %s" (or desc link))))) + +(defun org-link--file-link-to-here () + "Return as (LINK . DESC) a file link with search string to here." + (let ((link (concat "file:" + (abbreviate-file-name + (buffer-file-name (buffer-base-buffer))))) + desc) + (when org-link-context-for-files + (pcase (org-link-precise-link-target) + (`nil nil) + (`(,search-string ,search-desc ,_position) + (setq link (format "%s::%s" link search-string)) + (setq desc search-desc)))) + (cons link desc))) + ;;; Public API @@ -828,6 +907,13 @@ PARAMETERS should be keyword value pairs. See (org-link-make-regexps) (when (featurep 'org-element) (org-element-update-syntax))))) +;; This way, one can add multiple functions as, say, :follow parameter. +;; For example, +;; (add-function :before-until (org-link-get-parameter "id" :follow) #'my-function) +;; See https://orgmode.org/list/a123389c-8f86-4836-a4fe-1e3f4281d33b@app.fastmail.com +(gv-define-setter org-link-get-parameter (value type key) + `(org-link-set-parameters ,type ,key ,value)) + (defun org-link-make-regexps () "Update the link regular expressions. This should be called after the variable `org-link-parameters' has changed." @@ -840,12 +926,12 @@ This should be called after the variable `org-link-parameters' has changed." org-link-plain-re (let* ((non-space-bracket "[^][ \t\n()<>]") (parenthesis - `(seq "(" + `(seq (any "<([") (0+ (or (regex ,non-space-bracket) - (seq "(" + (seq (any "<([") (0+ (regex ,non-space-bracket)) - ")"))) - ")"))) + (any "])>")))) + (any "])>")))) ;; Heuristics for an URL link inspired by ;; https://daringfireball.net/2010/07/improved_regex_for_matching_urls (rx-to-string @@ -878,7 +964,8 @@ This should be called after the variable `org-link-parameters' has changed." org-link-plain-re "\\)")))) (defun org-link-complete-file (&optional arg) - "Create a file link using completion." + "Create a file link using completion. +With optional ARG \\='(16), abbreviate the file name in the link." (let ((file (read-file-name "File: ")) (pwd (file-name-as-directory (expand-file-name "."))) (pwd1 (file-name-as-directory (abbreviate-file-name @@ -923,7 +1010,7 @@ according to FMT (default from `org-link-email-description-format')." (org-replace-escapes fmt table))) (defun org-link-store-props (&rest plist) - "Store link properties. + "Store link properties PLIST. The properties are pre-processed by extracting names, addresses and dates." (let ((x (plist-get plist :from))) @@ -955,7 +1042,7 @@ and dates." (setq org-store-link-plist plist)) (defun org-link-add-props (&rest plist) - "Add these properties to the link property list." + "Add these properties to the link property list PLIST." (let (key value) (while plist (setq key (pop plist) value (pop plist)) @@ -1027,14 +1114,16 @@ LINK is escaped with backslashes for inclusion in buffer." "List of functions that are called to create and store a link. The functions are defined in the `:store' property of -`org-link-parameters'. +`org-link-parameters'. Each function should accept an argument +INTERACTIVE? which indicates whether the user has initiated +`org-store-link' interactively. -Each function will be called in turn until one returns a non-nil -value. Each function should check if it is responsible for -creating this link (for example by looking at the major mode). -If not, it must exit and return nil. If yes, it should return -a non-nil value after calling `org-link-store-props' with a list -of properties and values. Special properties are: +Each function will be called in turn with a single argument +INTERACTIVE? - non-nil when user interaction is allowed. Each function +should check if it is responsible for creating this link (for example +by looking at the major mode). If not, it must return nil. If yes, +it should return a non-nil value after calling `org-link-store-props' +with a list of properties and values. Special properties are: :type The link prefix, like \"http\". This must be given. :link The link, like \"http://www.astro.uva.nl/~dominik\". @@ -1063,17 +1152,35 @@ Abbreviations are defined in `org-link-abbrev-alist'." (if (not as) link (setq rpl (cdr as)) - (cond - ((symbolp rpl) (funcall rpl tag)) - ((string-match "%(\\([^)]+\\))" rpl) - (replace-match - (save-match-data - (funcall (intern-soft (match-string 1 rpl)) tag)) - t t rpl)) - ((string-match "%s" rpl) (replace-match (or tag "") t t rpl)) - ((string-match "%h" rpl) - (replace-match (url-hexify-string (or tag "")) t t rpl)) - (t (concat rpl tag))))))) + ;; Drop any potentially dangerous text properties like + ;; `modification-hooks' that may be used as an attack vector. + (substring-no-properties + (cond + ((symbolp rpl) (funcall rpl tag)) + ((string-match "%(\\([^)]+\\))" rpl) + (let ((rpl-fun-symbol (intern-soft (match-string 1 rpl)))) + ;; Using `unsafep-function' is not quite enough because + ;; Emacs considers functions like `genenv' safe, while + ;; they can potentially be used to expose private system + ;; data to attacker if abbreviated link is clicked. + (if (or (eq t (get rpl-fun-symbol 'org-link-abbrev-safe)) + (eq t (get rpl-fun-symbol 'pure))) + (replace-match + (save-match-data + (funcall (intern-soft (match-string 1 rpl)) tag)) + t t rpl) + (org-display-warning + (format "Disabling unsafe link abbrev: %s +You may mark function safe via (put '%s 'org-link-abbrev-safe t)" + rpl (match-string 1 rpl))) + (setq org-link-abbrev-alist-local (delete as org-link-abbrev-alist-local) + org-link-abbrev-alist (delete as org-link-abbrev-alist)) + link + ))) + ((string-match "%s" rpl) (replace-match (or tag "") t t rpl)) + ((string-match "%h" rpl) + (replace-match (url-hexify-string (or tag "")) t t rpl)) + (t (concat rpl tag)))))))) (defun org-link-open (link &optional arg) "Open a link object LINK. @@ -1114,7 +1221,7 @@ for internal and \"file\" links, or stored as a parameter in (_ path)) ;; Prevent fuzzy links from matching themselves. (and (equal type "fuzzy") - (+ 2 (org-element-property :begin link))))) + (+ 2 (org-element-begin link))))) (point)))) (unless (and (<= (point-min) destination) (>= (point-max) destination)) @@ -1128,14 +1235,14 @@ for internal and \"file\" links, or stored as a parameter in ;; argument, as it was mandatory before Org 9.4. This is ;; deprecated, but support it for now. (condition-case nil - (funcall (org-link-get-parameter type :follow) path arg) + (funcall f path arg) (wrong-number-of-arguments - (funcall (org-link-get-parameter type :follow) path))))))))) + (funcall f path))))))))) (defun org-link-open-from-string (s &optional arg) "Open a link in the string S, as if it was in Org mode. -Optional argument is passed to `org-open-file' when S is -a \"file\" link." +Optional argument ARG is passed to `org-open-file' when S is a +\"file\" link." (interactive "sLink: \nP") (pcase (with-temp-buffer (let ((org-inhibit-startup nil)) @@ -1146,8 +1253,8 @@ a \"file\" link." (`nil (user-error "No valid link in %S" s)) (link (org-link-open link arg)))) -(defun org-link-search (s &optional avoid-pos stealth) - "Search for a search string S. +(defun org-link-search (s &optional avoid-pos stealth new-heading-container) + "Search for a search string S in the accessible part of the buffer. If S starts with \"#\", it triggers a custom ID search. @@ -1166,8 +1273,16 @@ When optional argument STEALTH is non-nil, do not modify visibility around point, thus ignoring `org-show-context-detail' variable. +When optional argument NEW-HEADING-CONTAINER is an element, any +new heading that is created (see +`org-link-search-must-match-exact-headline') will be added as a +subheading of NEW-HEADING-CONTAINER. Otherwise, new headings are +created at level 1 at the end of the accessible part of the +buffer. + Search is case-insensitive and ignores white spaces. Return type -of matched result, which is either `dedicated' or `fuzzy'." +of matched result, which is either `dedicated' or `fuzzy'. Search +respects buffer narrowing." (unless (org-string-nw-p s) (error "Invalid search string \"%s\"" s)) (let* ((case-fold-search t) (origin (point)) @@ -1194,8 +1309,7 @@ of matched result, which is either `dedicated' or `fuzzy'." (catch :coderef-match (while (re-search-forward re nil t) (let ((element (org-element-at-point))) - (when (and (memq (org-element-type element) - '(example-block src-block)) + (when (and (org-element-type-p element '(example-block src-block)) (org-match-line (concat ".*?" (org-src-coderef-regexp (org-src-coderef-format element) @@ -1219,9 +1333,9 @@ of matched result, which is either `dedicated' or `fuzzy'." (while (re-search-forward target nil t) (backward-char) (let ((context (org-element-context))) - (when (eq (org-element-type context) 'target) + (when (org-element-type-p context 'target) (setq type 'dedicated) - (goto-char (org-element-property :begin context)) + (goto-char (org-element-begin context)) (throw :target-match t)))) nil)))) ;; Look for elements named after S, only if not in a headline @@ -1233,9 +1347,9 @@ of matched result, which is either `dedicated' or `fuzzy'." (while (re-search-forward name nil t) (let* ((element (org-element-at-point)) (name (org-element-property :name element))) - (when (and name (equal words (split-string name))) + (when (and name (equal (mapcar #'upcase words) (mapcar #'upcase (split-string name)))) (setq type 'dedicated) - (beginning-of-line) + (forward-line 0) (throw :name-match t)))) nil)))) ;; Regular text search. Prefer headlines in Org mode buffers. @@ -1250,24 +1364,38 @@ of matched result, which is either `dedicated' or `fuzzy'." (goto-char (point-min)) (catch :found (while (re-search-forward title-re nil t) - (when (equal words - (split-string - (org-link--normalize-string - (org-get-heading t t t t)))) + (when (equal (mapcar #'upcase words) + (mapcar #'upcase + (split-string + (org-link--normalize-string + (org-get-heading t t t t))))) (throw :found t))) nil))) - (beginning-of-line) + (forward-line 0) (setq type 'dedicated)) ;; Offer to create non-existent headline depending on ;; `org-link-search-must-match-exact-headline'. ((and (derived-mode-p 'org-mode) (eq org-link-search-must-match-exact-headline 'query-to-create) (yes-or-no-p "No match - create this as a new heading? ")) - (goto-char (point-max)) - (unless (bolp) (newline)) - (org-insert-heading nil t t) - (insert s "\n") - (beginning-of-line 0)) + (let* ((container-ok (and new-heading-container + (org-element-type-p new-heading-container '(headline)))) + (new-heading-position (if container-ok + (- (org-element-end new-heading-container) 1) + (point-max))) + (new-heading-level (if container-ok + (+ 1 (org-element-property :level new-heading-container)) + 1))) + ;; Need to widen when target is outside accessible portion of + ;; buffer, since the we want the user to end up there. + (unless (and (<= (point-min) new-heading-position) + (>= (point-max) new-heading-position)) + (widen)) + (goto-char new-heading-position) + (unless (bolp) (newline)) + (org-insert-heading nil t new-heading-level) + (insert (if starred (substring s 1) s) "\n") + (forward-line -1))) ;; Only headlines are looked after. No need to process ;; further: throw an error. ((and (derived-mode-p 'org-mode) @@ -1290,7 +1418,7 @@ of matched result, which is either `dedicated' or `fuzzy'." (<= (match-end 3) (point))) (org-element-lineage (save-match-data (org-element-context)) - '(link) t))) + 'link t))) (goto-char (match-beginning 0)) (setq type 'fuzzy) (throw :fuzzy-match t))) @@ -1317,9 +1445,75 @@ priority cookie or tag." (org-link--normalize-string (or string (org-get-heading t t t t))))) -(defun org-link-open-as-file (path arg) +(defun org-link-precise-link-target () + "Determine search string and description for storing a link. + +If a search string (see `org-link-search') is found, return +list (SEARCH-STRING DESC POSITION). Otherwise, return nil. + +If there is an active region, the contents (or a part of it, see +`org-link-context-for-files') is used as the search string. + +In Org buffers, if point is at a named element (such as a source +block), the name is used for the search string. If at a heading, +its CUSTOM_ID is used to form a search string of the form +\"#id\", if present, otherwise the current heading text is used +in the form \"*Heading\". + +If none of those finds a suitable search string, the current line +is used as the search string. + +The description DESC is nil (meaning the user will be prompted +for a description when inserting the link) for search strings +based on a region or the current line. For other cases, DESC is +a cleaned-up version of the name or heading at point. + +POSITION is the buffer position at which the search string +matches." + (let* ((region (org-link--context-from-region)) + (result + (cond + (region + (list (org-link--normalize-string region t) + nil + (region-beginning))) + + ((derived-mode-p 'org-mode) + (let* ((element (org-element-at-point)) + (name (org-element-property :name element)) + (heading (org-element-lineage element '(headline inlinetask) t)) + (custom-id (org-entry-get heading "CUSTOM_ID"))) + (cond + (name + (list name + name + (org-element-begin element))) + ((org-before-first-heading-p) + (list (org-link--normalize-string (org-current-line-string) t) + nil + (line-beginning-position))) + (heading + (list (if custom-id (concat "#" custom-id) + (org-link-heading-search-string)) + (org-link--normalize-string + (org-get-heading t t t t)) + (org-element-begin heading)))))) + + ;; Not in an org-mode buffer, no region + (t + (list (org-link--normalize-string (org-current-line-string) t) + nil + (line-beginning-position)))))) + + ;; Only use search option if there is some text. + (when (org-string-nw-p (car result)) + result))) + +(defun org-link-open-as-file (path in-emacs) "Pretend PATH is a file name and open it. +IN-EMACS is passed to `org-open-file'. + According to \"file\"-link syntax, PATH may include additional search options, separated from the file name with \"::\". @@ -1329,11 +1523,12 @@ This function is meant to be used as a possible tool for (match-string 1 path))) (file-name (if (not option) path (substring path 0 (match-beginning 0))))) - (if (string-match "[*?{]" (file-name-nondirectory file-name)) - (dired file-name) + (if (and (string-match "[*?{]" (file-name-nondirectory file-name)) + (not (file-exists-p file-name))) + (dired file-name) (apply #'org-open-file file-name - arg + in-emacs (cond ((not option) nil) ((string-match-p "\\`[0-9]+\\'" option) (list (string-to-number option))) @@ -1387,7 +1582,7 @@ PATH is a symbol name, as a string." ((and (pred boundp) variable) (describe-variable variable)) (name (user-error "Unknown function or variable: %s" name)))) -(defun org-link--store-help () +(defun org-link--store-help (&optional _interactive?) "Store \"help\" type link." (when (eq major-mode 'help-mode) (let ((symbol @@ -1469,10 +1664,10 @@ is non-nil, move backward." (let ((context (save-excursion (unless search-backward (forward-char -1)) (org-element-context)))) - (pcase (org-element-lineage context '(link) t) + (pcase (org-element-lineage context 'link t) (`nil nil) (link - (goto-char (org-element-property :begin link)) + (goto-char (org-element-begin link)) (when (org-invisible-p) (org-fold-show-context 'link-search)) (throw :found t))))) (goto-char pos) @@ -1486,18 +1681,12 @@ If the link is in hidden text, expose it." (interactive) (org-next-link t)) -(defun org-link-descriptive-ensure () - "Toggle the literal or descriptive display of links in current buffer if needed." - (org-fold-core-set-folding-spec-property - (car org-link--link-folding-spec) - :visible (not org-link-descriptive))) - ;;;###autoload (defun org-toggle-link-display () "Toggle the literal or descriptive display of links in current buffer." (interactive) (setq org-link-descriptive (not org-link-descriptive)) - (org-link-descriptive-ensure)) + (org-restart-font-lock)) ;;;###autoload (defun org-store-link (arg &optional interactive?) @@ -1505,10 +1694,12 @@ If the link is in hidden text, expose it." \\ This link is added to `org-stored-links' and can later be inserted into an Org buffer with `org-insert-link' (`\\[org-insert-link]'). +When optional argument INTERACTIVE? is nil, the link is not stored in +`org-stored-links', but returned as a string. For some link types, a `\\[universal-argument]' prefix ARG is interpreted. \ A single -`\\[universal-argument]' negates `org-context-in-file-links' for file links or +`\\[universal-argument]' negates `org-link-context-for-files' for file links or `org-gnus-prefer-web-links' for links to Usenet articles. A `\\[universal-argument] \\[universal-argument]' prefix ARG forces \ @@ -1520,7 +1711,12 @@ prefix ARG forces storing a link for each line in the active region. Assume the function is called interactively if INTERACTIVE? is -non-nil." +non-nil. + +In Org buffers, an additional \"human-readable\" simple file link +is stored as an alternative to persistent org-id or other links, +if at a heading with a CUSTOM_ID property or an element with a +NAME." (interactive "P\np") (org-load-modules-maybe) (if (and (equal arg '(64)) (org-region-active-p)) @@ -1535,36 +1731,19 @@ non-nil." (move-beginning-of-line 2) (set-mark (point))))) (setq org-store-link-plist nil) - (let (link cpltxt desc search custom-id agenda-link) ;; description + ;; Negate `org-context-in-file-links' when given a single universal arg. + (let ((org-link-context-for-files (org-xor org-link-context-for-files + (equal arg '(4)))) + link desc search agenda-link) ;; description (cond ;; Store a link using an external link type, if any function is - ;; available. If more than one can generate a link from current - ;; location, ask which one to use. + ;; available, unless external link types are skipped for this + ;; call using two universal args. If more than one function + ;; can generate a link from current location, ask the user + ;; which one to use. ((and (not (equal arg '(16))) - (let ((results-alist nil)) - (dolist (f (org-store-link-functions)) - (when (funcall f) - ;; XXX: return value is not link's plist, so we - ;; store the new value before it is modified. It - ;; would be cleaner to ask store link functions to - ;; return the plist instead. - (push (cons f (copy-sequence org-store-link-plist)) - results-alist))) - (pcase results-alist - (`nil nil) - (`((,_ . ,_)) t) ;single choice: nothing to do - (`((,name . ,_) . ,_) - ;; Reinstate link plist associated to the chosen - ;; function. - (apply #'org-link-store-props - (cdr (assoc-string - (completing-read - (format "Store link with (default %s): " name) - (mapcar #'car results-alist) - nil t nil nil (symbol-name name)) - results-alist))) - t)))) - (setq link (plist-get org-store-link-plist :link)) + (org-link--try-link-store-functions interactive?)) + (setq link (plist-get org-store-link-plist :link)) ;; If store function actually set `:description' property, use ;; it, even if it is nil. Otherwise, fallback to nil (ask user). (setq desc (plist-get org-store-link-plist :description))) @@ -1586,7 +1765,7 @@ non-nil." (setq link nil)) ;; A code reference exists. Use it. ((save-excursion - (beginning-of-line) + (forward-line 0) (re-search-forward (org-src-coderef-regexp coderef-format) (line-end-position) t)) @@ -1615,6 +1794,7 @@ non-nil." (org-with-point-at m (setq agenda-link (org-store-link nil interactive?)))))) + ;; Calendar mode ((eq major-mode 'calendar-mode) (let ((cd (calendar-cursor-to-date))) (setq link @@ -1623,10 +1803,10 @@ non-nil." (org-encode-time 0 0 0 (nth 1 cd) (nth 0 cd) (nth 2 cd)))) (org-link-store-props :type "calendar" :date cd))) + ;; Image mode ((eq major-mode 'image-mode) - (setq cpltxt (concat "file:" - (abbreviate-file-name buffer-file-name)) - link cpltxt) + (setq link (concat "file:" + (abbreviate-file-name buffer-file-name))) (org-link-store-props :type "image" :file buffer-file-name)) ;; In dired, store a link to the file of the current line @@ -1637,18 +1817,21 @@ non-nil." (expand-file-name (dired-get-filename nil t))) ;; Otherwise, no file so use current directory. default-directory)) - (setq cpltxt (concat "file:" file) - link cpltxt))) + (setq link (concat "file:" file)))) + ;; Try `org-create-file-search-functions`. If any are + ;; successful, create a file link to the current buffer with + ;; the provided search string. ((setq search (run-hook-with-args-until-success 'org-create-file-search-functions)) (setq link (concat "file:" (abbreviate-file-name buffer-file-name) - "::" search)) - (setq cpltxt (or link))) ;; description + "::" search) + desc (plist-get org-store-link-plist :description))) + ;; Main logic for storing built-in link types in org-mode + ;; buffers ((and (buffer-file-name (buffer-base-buffer)) (derived-mode-p 'org-mode)) (org-with-limited-levels - (setq custom-id (org-entry-get nil "CUSTOM_ID")) (cond ;; Store a link using the target at point ((org-in-regexp "[^<]<<\\([^<>]+\\)>>[^>]" 1) @@ -1661,75 +1844,19 @@ non-nil." ;; Avoid [[target][file:~/org/test.org::target]] ;; links. Maybe the case of identical target and ;; description should be handled by `org-insert-link'. - cpltxt nil - desc nil - ;; Do not append #CUSTOM_ID link below. - custom-id nil)) - ((and (featurep 'org-id) - (or (eq org-id-link-to-org-use-id t) - (and interactive? - (or (eq org-id-link-to-org-use-id 'create-if-interactive) - (and (eq org-id-link-to-org-use-id - 'create-if-interactive-and-no-custom-id) - (not custom-id)))) - (and org-id-link-to-org-use-id (org-entry-get nil "ID")))) - ;; Store a link using the ID at point - (setq link (condition-case nil - (prog1 (org-id-store-link) - (setq desc (plist-get org-store-link-plist :description))) - (error - ;; Probably before first headline, link only to file - (concat "file:" - (abbreviate-file-name - (buffer-file-name (buffer-base-buffer)))))))) - (t + desc nil)) + (t ;; Just link to current headline. - (setq cpltxt (concat "file:" - (abbreviate-file-name - (buffer-file-name (buffer-base-buffer))))) - ;; Add a context search string. - (when (org-xor org-link-context-for-files (equal arg '(4))) - (let* ((element (org-element-at-point)) - (name (org-element-property :name element)) - (context - (cond - ((let ((region (org-link--context-from-region))) - (and region (org-link--normalize-string region t)))) - (name) - ((org-before-first-heading-p) - (org-link--normalize-string (org-current-line-string) t)) - (t (org-link-heading-search-string))))) - (when (org-string-nw-p context) - (setq cpltxt (format "%s::%s" cpltxt context)) - (setq desc - (or name - ;; Although description is not a search - ;; string, use `org-link--normalize-string' - ;; to prettify it (contiguous white spaces) - ;; and remove volatile contents (statistics - ;; cookies). - (and (not (org-before-first-heading-p)) - (org-link--normalize-string - (org-get-heading t t t t))) - "NONE"))))) - (setq link cpltxt))))) + (let ((here (org-link--file-link-to-here))) + (setq link (car here)) + (setq desc (cdr here))))))) + ;; Buffer linked to file, but not an org-mode buffer. ((buffer-file-name (buffer-base-buffer)) ;; Just link to this file here. - (setq cpltxt (concat "file:" - (abbreviate-file-name - (buffer-file-name (buffer-base-buffer))))) - ;; Add a context search string. - (when (org-xor org-link-context-for-files (equal arg '(4))) - (let ((context (org-link--normalize-string - (or (org-link--context-from-region) - (org-current-line-string)) - t))) - ;; Only use search option if there is some text. - (when (org-string-nw-p context) - (setq cpltxt (format "%s::%s" cpltxt context)) - (setq desc "NONE")))) - (setq link cpltxt)) + (let ((here (org-link--file-link-to-here))) + (setq link (car here)) + (setq desc (cdr here)))) (interactive? (user-error "No method for storing a link from this buffer")) @@ -1737,25 +1864,25 @@ non-nil." (t (setq link nil))) ;; We're done setting link and desc, clean up - (when (consp link) (setq cpltxt (car link) link (cdr link))) - (setq link (or link cpltxt)) + (when (consp link) (setq link (or (cdr link) (car link)))) (cond ((not desc)) ((equal desc "NONE") (setq desc nil)) (t (setq desc (org-link-display-format desc)))) ;; Store and return the link (if (not (and interactive? link)) (or agenda-link (and link (org-link-make-string link desc))) - (if (member (list link desc) org-stored-links) - (message "This link has already been stored") - (push (list link desc) org-stored-links) - (message "Stored: %s" (or desc link)) - (when custom-id - (setq link (concat "file:" - (abbreviate-file-name - (buffer-file-name (buffer-base-buffer))) - "::#" custom-id)) - (push (list link desc) org-stored-links))) - (car org-stored-links))))) + (org-link--add-to-stored-links link desc) + ;; In org buffers, store an additional "human-readable" link + ;; using custom id, if available. + (when (and (buffer-file-name (buffer-base-buffer)) + (derived-mode-p 'org-mode) + (org-entry-get nil "CUSTOM_ID")) + (let ((here (org-link--file-link-to-here))) + (setq link (car here)) + (setq desc (cdr here))) + (unless (equal (list link desc) (car org-stored-links)) + (org-link--add-to-stored-links link desc))) + (car org-stored-links))))) ;;;###autoload (defun org-insert-link (&optional complete-file link-location description) @@ -1803,7 +1930,7 @@ generate a description as described in `org-link-parameters' docstring. Otherwise, if `org-link-make-description-function' is non-nil, this function will be called with the link target, and the result will be the default link description. When called -non-interactively, don't allow to edit the default description." +non-interactively, don't allow editing the default description." (interactive "P") (let* ((wcf (current-window-configuration)) (origbuf (current-buffer)) @@ -1816,7 +1943,7 @@ non-interactively, don't allow to edit the default description." (all-prefixes (append (mapcar #'car abbrevs) (mapcar #'car org-link-abbrev-alist) (org-link-types))) - entry) + entry link-original) (cond (link-location) ; specified by arg, just use it. ((org-in-regexp org-link-bracket-re 1) @@ -1838,18 +1965,34 @@ non-interactively, don't allow to edit the default description." (t ;; Read link, with completion for stored links. (org-link--fontify-links-to-this-file) - (org-switch-to-buffer-other-window "*Org Links*") + (switch-to-buffer-other-window "*Org Links*") (with-current-buffer "*Org Links*" - (erase-buffer) - (insert "Insert a link. -Use TAB to complete link prefixes, then RET for type-specific completion support\n") - (when org-stored-links - (insert "\nStored links are available with / or M-p/n \ -\(most recent with RET):\n\n") - (insert (mapconcat #'org-link--prettify - (reverse org-stored-links) - "\n"))) - (goto-char (point-min))) + (read-only-mode 1) + (let ((inhibit-read-only t) + ;; FIXME Duplicate: Also in 'ox.el'. + (propertize-help-key + (lambda (key) + ;; Add `face' *and* `font-lock-face' to "work + ;; reliably in any buffer", per a comment in + ;; `help--key-description-fontified'. + (propertize key + 'font-lock-face 'help-key-binding + 'face 'help-key-binding)))) + (erase-buffer) + (insert + (apply #'format "Type %s to complete link type, then %s to complete destination.\n" + (mapcar propertize-help-key + (list "TAB" "RET")))) + (when org-stored-links + (insert (apply #'format "\nStored links accessible with %s/%s or %s/%s are:\n\n" + (mapcar propertize-help-key + (list "" "" + "M-p" "M-n" + "RET")))) + (insert (mapconcat #'org-link--prettify + (reverse org-stored-links) + "\n")))) + (goto-char (point-min))) (when (get-buffer-window "*Org Links*" 'visible) (let ((cw (selected-window))) (select-window (get-buffer-window "*Org Links*" 'visible)) @@ -1864,14 +2007,13 @@ Use TAB to complete link prefixes, then RET for type-specific completion support org-link--insert-history))) (setq link (org-completing-read - "Link: " + (org-format-prompt "Insert link" (caar org-stored-links)) (append (mapcar (lambda (x) (concat x ":")) all-prefixes) (mapcar #'car org-stored-links) ;; Allow description completion. Avoid "nil" option - ;; in the case of `completing-read-default' and - ;; an error in `ido-completing-read' when some links - ;; have no description. + ;; in the case of `completing-read-default' when + ;; some links have no description. (delq nil (mapcar 'cadr org-stored-links))) nil nil nil 'org-link--history @@ -1886,17 +2028,16 @@ Use TAB to complete link prefixes, then RET for type-specific completion support (setq link (substring link 0 -1)))) (setq link (with-current-buffer origbuf (org-link--try-special-completion link))))) + (when-let* ((window (get-buffer-window "*Org Links*" t))) + (quit-window 'kill window)) (set-window-configuration wcf) - (kill-buffer "*Org Links*")) + (when (get-buffer "*Org Links*") + (kill-buffer "*Org Links*"))) (setq entry (assoc link org-stored-links)) (or entry (push link org-link--insert-history)) (setq desc (or desc (nth 1 entry))))) - (when (funcall (if (equal complete-file '(64)) 'not 'identity) - (not org-link-keep-stored-after-insertion)) - (setq org-stored-links (delq (assoc link org-stored-links) - org-stored-links))) - + (setq link-original link) (when (and (string-match org-link-plain-re link) (not (string-match org-ts-regexp link))) ;; URL-like link, normalize the use of angular brackets. @@ -1939,8 +2080,7 @@ Use TAB to complete link prefixes, then RET for type-specific completion support ((eq org-link-file-path-type 'relative) (setq path (file-relative-name path))) ((functionp org-link-file-path-type) - (setq path (funcall org-link-file-path-type - (expand-file-name path)))) + (setq path (funcall org-link-file-path-type path))) (t (save-match-data (if (string-match (concat "^" (regexp-quote @@ -1991,6 +2131,10 @@ Use TAB to complete link prefixes, then RET for type-specific completion support (read-string "Description: " initial-input) initial-input))) + (when (funcall (if (equal complete-file '(64)) 'not 'identity) + (not org-link-keep-stored-after-insertion)) + (setq org-stored-links (delq (assoc link-original org-stored-links) + org-stored-links))) (unless (org-string-nw-p desc) (setq desc nil)) (when remove (apply #'delete-region remove)) (insert (org-link-make-string link desc)) @@ -2035,6 +2179,39 @@ This command can be called in any mode to insert a link in Org syntax." (org-load-modules-maybe) (org-run-like-in-org-mode 'org-insert-link)) +(defun org--re-list-search-forward (regexp-list &optional bound noerror count) + "Like `re-search-forward', but REGEXP-LIST is a list of regexps. +BOUND, NOERROR, and COUNT are passed to `re-search-forward'." + (let (result (min-found most-positive-fixnum) + (pos-found nil) + (min-found-data nil) + (tail regexp-list)) + (while tail + (setq result (save-excursion (re-search-forward (pop tail) bound t count))) + (when (and result (< result min-found)) + (setq min-found result + pos-found (match-end 0) + min-found-data (match-data)))) + (if (= most-positive-fixnum min-found) + (pcase noerror + (`t nil) + (_ (re-search-forward (car regexp-list) bound noerror count))) + (set-match-data min-found-data) + (goto-char pos-found)))) + +(defun org--re-list-looking-at (regexp-list &optional inhibit-modify) + "Like `looking-at', but REGEXP-LIST is a list of regexps. +INHIBIT-MODIFY is passed to `looking-at'." + (catch :found + (while regexp-list + (when + (if inhibit-modify + (looking-at-p (pop regexp-list)) + ;; FIXME: In Emacs <29, `looking-at' does not accept + ;; optional INHIBIT-MODIFY argument. + (looking-at (pop regexp-list))) + (throw :found t))))) + ;;;###autoload (defun org-update-radio-target-regexp () "Find all radio targets in this file and update the regular expression. @@ -2042,7 +2219,7 @@ Also refresh fontification if needed." (interactive) (let ((old-regexp org-target-link-regexp) ;; Some languages, e.g., Chinese, do not use spaces to - ;; separate words. Also allow to surround radio targets with + ;; separate words. Also allow surrounding radio targets with ;; line-breakable characters. (before-re "\\(?:^\\|[^[:alnum:]]\\|\\c|\\)\\(") (after-re "\\)\\(?:$\\|[^[:alnum:]]\\|\\c|\\)") @@ -2054,7 +2231,7 @@ Also refresh fontification if needed." ;; Make sure point is really within the object. (backward-char) (let ((obj (org-element-context))) - (when (eq (org-element-type obj) 'radio-target) + (when (org-element-type-p obj 'radio-target) (cl-pushnew (org-element-property :value obj) rtn :test #'equal)))) rtn)))) @@ -2072,6 +2249,30 @@ Also refresh fontification if needed." targets "\\|") after-re))) + (setq org-target-link-regexps nil) + (let (current-length sub-targets) + (when (<= org-target-link-regexp-limit (length org-target-link-regexp)) + (while (or targets sub-targets) + (when (and sub-targets + (or (not targets) + (>= (+ current-length (length (car targets))) + org-target-link-regexp-limit))) + (push (concat before-re + (mapconcat + (lambda (x) + (replace-regexp-in-string + " +" "\\s-+" (regexp-quote x) t t)) + (nreverse sub-targets) + "\\|") + after-re) + org-target-link-regexps) + (setq current-length nil + sub-targets nil)) + (unless current-length + (setq current-length (+ (length before-re) (length after-re)))) + (when targets (push (pop targets) sub-targets)) + (cl-incf current-length (length (car sub-targets)))) + (setq org-target-link-regexps (nreverse org-target-link-regexps)))) (unless (equal old-regexp org-target-link-regexp) ;; Clean-up cache. (let ((regexp (cond ((not old-regexp) org-target-link-regexp) @@ -2087,9 +2288,11 @@ Also refresh fontification if needed." after-re))))) (when (and (featurep 'org-element) (not (bound-and-true-p org-mode-loading))) - (org-with-point-at 1 - (while (re-search-forward regexp nil t) - (org-element-cache-refresh (match-beginning 1)))))) + (if org-target-link-regexps + (org-element-cache-reset) + (org-with-point-at 1 + (while (re-search-forward regexp nil t) + (org-element-cache-refresh (match-beginning 1))))))) ;; Re fontify buffer. (when (memq 'radio org-highlight-links) (org-restart-font-lock))))) diff --git a/elpa/org-9.6.7/org-agenda.el b/elpa/org-9.7.17/org-agenda.el similarity index 88% rename from elpa/org-9.6.7/org-agenda.el rename to elpa/org-9.7.17/org-agenda.el index d3e61643..011884d5 100644 --- a/elpa/org-9.6.7/org-agenda.el +++ b/elpa/org-9.7.17/org-agenda.el @@ -1,9 +1,9 @@ ;;; org-agenda.el --- Dynamic task and appointment lists for Org -*- lexical-binding: t; -*- -;; Copyright (C) 2004-2023 Free Software Foundation, Inc. +;; Copyright (C) 2004-2024 Free Software Foundation, Inc. ;; Author: Carsten Dominik -;; Keywords: outlines, hypermedia, calendar, wp +;; Keywords: outlines, hypermedia, calendar, text ;; URL: https://orgmode.org ;; ;; This file is part of GNU Emacs. @@ -85,7 +85,7 @@ "org-habit" (&optional line)) (declare-function org-is-habit-p "org-habit" (&optional pom)) (declare-function org-habit-parse-todo "org-habit" (&optional pom)) -(declare-function org-habit-get-priority "org-habit" (habit &optional moment)) +(declare-function org-habit-get-urgency "org-habit" (habit &optional moment)) (declare-function org-agenda-columns "org-colview" ()) (declare-function org-add-archive-files "org-archive" (files)) (declare-function org-capture "org-capture" (&optional goto keys)) @@ -267,6 +267,7 @@ you can \"misuse\" it to also add other text to the header." (const category-keep) (const category-up) (const category-down) (const tag-down) (const tag-up) (const priority-up) (const priority-down) + (const urgency-up) (const urgency-down) (const todo-state-up) (const todo-state-down) (const effort-up) (const effort-down) (const habit-up) (const habit-down) @@ -893,17 +894,14 @@ the entry is scheduled today or was scheduled previously is not shown. When set to the symbol `not-today', skip scheduled previously, -but not scheduled today. - -When set to the symbol `repeated-after-deadline', skip scheduled -items if they are repeated beyond the current deadline." +but not scheduled today." :group 'org-agenda-skip :group 'org-agenda-daily/weekly :type '(choice (const :tag "Never" nil) (const :tag "Always" t) - (const :tag "Not when scheduled today" not-today) - (const :tag "When repeated past deadline" repeated-after-deadline))) + (const :tag "Not when scheduled today" not-today)) + :package-version '(Org . "9.7")) (defcustom org-agenda-skip-timestamp-if-deadline-is-shown nil "Non-nil means skip timestamp line if same entry shows because of deadline. @@ -1043,7 +1041,7 @@ headlines as the agenda display heavily relies on them." :type 'hook) (defcustom org-agenda-mouse-1-follows-link nil - "Non-nil means mouse-1 on a link will follow the link in the agenda. + "Non-nil means \\`mouse-1' on a link will follow the link in the agenda. A longer mouse click will still set point. Needs to be set before org.el is loaded." :group 'org-agenda-startup @@ -1101,6 +1099,14 @@ removed from entry text before it is shown in the agenda." :group 'org-agenda :type 'string) +(defcustom org-agenda-start-with-archives-mode nil + "Initial value of archive mode in a newly created agenda window. +See `org-agenda-archives-mode' for acceptable values and their +meaning." + :group 'org-agenda-startup + :package-version '(Org . "9.7") + :type 'symbol) + (defvar org-agenda-entry-text-cleanup-hook nil "Hook that is run after basic cleanup of entry text to be shown in agenda. This cleanup is done in a temporary buffer, so the function may inspect and @@ -1332,16 +1338,22 @@ When set to the symbol `next' only the first future repeat is shown." (const :tag "Show all repeated entries" t) (const :tag "Show next repeated entry" next) (const :tag "Do not show repeated entries" nil)) - :version "26.1" :package-version '(Org . "9.1") :safe #'symbolp) +(defcustom org-agenda-skip-scheduled-repeats-after-deadline nil + "Non-nil hides scheduled repeated entries past deadline." + :group 'org-agenda-daily/weekly + :type 'boolean + :package-version '(Org . "9.7") + :safe t) + (defcustom org-agenda-prefer-last-repeat nil "Non-nil sets date for repeated entries to their last repeat. When nil, display SCHEDULED and DEADLINE dates at their base date, and in today's agenda, as a reminder. Display plain -time-stamps, on the other hand, at every repeat date in the past +timestamps, on the other hand, at every repeat date in the past in addition to the base date. When non-nil, show a repeated entry at its latest repeat date, @@ -1536,10 +1548,7 @@ value, don't limit agenda view by outline level." "Non-nil means search headline for a time-of-day. If the headline contains a time-of-day in one format or another, it will be used to sort the entry into the time sequence of items for a day. -Some people have time stamps in the headline that refer to the creation -time or so, and then this produces an unwanted side effect. If this is -the case for your, use this variable to turn off searching the headline -for a time." +Timestamps in the headline will be ignored." :group 'org-agenda-time-grid :type 'boolean) @@ -1617,9 +1626,9 @@ will align with agenda items." :group 'org-agenda) (defcustom org-agenda-sorting-strategy - '((agenda habit-down time-up priority-down category-keep) - (todo priority-down category-keep) - (tags priority-down category-keep) + '((agenda habit-down time-up urgency-down category-keep) + (todo urgency-down category-keep) + (tags urgency-down category-keep) (search category-keep)) "Sorting structure for the agenda items of a single day. This is a list of symbols which will be used in sequence to determine @@ -1646,6 +1655,12 @@ tag-up Sort alphabetically by last tag, A-Z. tag-down Sort alphabetically by last tag, Z-A. priority-up Sort numerically by priority, high priority last. priority-down Sort numerically by priority, high priority first. +urgency-up Sort numerically by urgency, high urgency last. + Urgency is calculated based on item's priority, + and proximity to scheduled time and deadline. See + info node `(org)Sorting of agenda items' for + details. +urgency-down Sort numerically by urgency, high urgency first. todo-state-up Sort by todo state, tasks that are done last. todo-state-down Sort by todo state, tasks that are done first. effort-up Sort numerically by estimated effort, high effort last. @@ -1687,7 +1702,8 @@ Custom commands can bind this variable in the options section." (cons (const :tag "Strategy for Tags matches" tags) (repeat ,org-sorting-choice)) (cons (const :tag "Strategy for search matches" search) - (repeat ,org-sorting-choice))))) + (repeat ,org-sorting-choice)))) + :package-version '(Org . "9.7")) (defcustom org-agenda-cmp-user-defined nil "A function to define the comparison `user-defined'. @@ -2032,6 +2048,9 @@ the normal rules apply." (defcustom org-agenda-category-icon-alist nil "Alist of category icon to be displayed in agenda views. +The icons are displayed in place of the %i placeholders in +`org-agenda-prefix-format', which see. + Each entry should have the following format: (CATEGORY-REGEXP FILE-OR-DATA TYPE DATA-P PROPS) @@ -2211,7 +2230,7 @@ This is an internal flag indicating either temporary or extended agenda restriction. Specifically, it is set to t if the agenda is restricted to an entire file, and is set to the corresponding buffer if the agenda is restricted to a part of a file, e.g. a -region or a substree. In the latter case, +region or a subtree. In the latter case, `org-agenda-restrict-begin' and `org-agenda-restrict-end' are set to the beginning and the end of the part. @@ -2368,10 +2387,10 @@ The following commands are available: (setq org-agenda-follow-mode org-agenda-start-with-follow-mode org-agenda-entry-text-mode org-agenda-start-with-entry-text-mode org-agenda-show-log org-agenda-start-with-log-mode - org-agenda-clockreport-mode org-agenda-start-with-clockreport-mode)) + org-agenda-clockreport-mode org-agenda-start-with-clockreport-mode + org-agenda-archives-mode org-agenda-start-with-archives-mode)) (add-to-invisibility-spec '(org-filtered)) - (org-fold-core-initialize `(,org-link--description-folding-spec - ,org-link--link-folding-spec)) + (add-to-invisibility-spec '(org-link)) (easy-menu-change '("Agenda") "Agenda Files" (append @@ -3025,7 +3044,7 @@ Pressing `<' twice means to restrict to the current subtree or region (`todo-tree (org-check-for-org-mode) (org-occur (concat "^" org-outline-regexp "[ \t]*" - (regexp-quote org-match) "\\>"))) + (regexp-quote org-match) "\\(?:[\t ]\\|$\\)"))) (`occur-tree (org-check-for-org-mode) (org-occur org-match)) @@ -3108,8 +3127,7 @@ Agenda views are separated by `org-agenda-block-separator'." c entry key type match prefixes rmheader header-end custom1 desc line lines left right n n1) (save-window-excursion - (delete-other-windows) - (org-switch-to-buffer-other-window " *Agenda Commands*") + (pop-to-buffer " *Agenda Commands*" '(org-display-buffer-split)) (erase-buffer) (insert (eval-when-compile (let ((header @@ -3117,10 +3135,10 @@ Agenda views are separated by `org-agenda-block-separator'." "Press key for an agenda command: -------------------------------- < Buffer, subtree/region restriction a Agenda for current week or day > Remove restriction -t List of all TODO entries e Export agenda views -m Match a TAGS/PROP/TODO query T Entries with special TODO kwd -s Search for keywords M Like m, but only TODO entries -/ Multi-occur S Like s, but only TODO entries +/ Multi-occur e Export agenda views +t List of all TODO entries T Entries with special TODO kwd +m Match a TAGS/PROP/TODO query M Like m, but only TODO entries +s Search for keywords S Like s, but only TODO entries ? Find :FLAGGED: entries C Configure custom agenda commands * Toggle sticky agenda views # List stuck projects (!=configure) ")) @@ -3133,169 +3151,172 @@ s Search for keywords M Like m, but only TODO entries '(face bold) header)) header))) (setq header-end (point-marker)) - (while t - (setq custom1 custom) - (when (eq rmheader t) - (org-goto-line 1) - (re-search-forward ":" nil t) - (delete-region (match-end 0) (line-end-position)) - (forward-char 1) - (looking-at "-+") - (delete-region (match-end 0) (line-end-position)) - (move-marker header-end (match-end 0))) - (goto-char header-end) - (delete-region (point) (point-max)) - - ;; Produce all the lines that describe custom commands and prefixes - (setq lines nil) - (while (setq entry (pop custom1)) - (setq key (car entry) desc (nth 1 entry) - type (nth 2 entry) - match (nth 3 entry)) - (if (> (length key) 1) - (cl-pushnew (string-to-char key) prefixes :test #'equal) - (setq line - (format - "%-4s%-14s" - (org-add-props (copy-sequence key) - '(face bold)) - (cond - ((string-match "\\S-" desc) desc) - ((eq type 'agenda) "Agenda for current week or day") - ((eq type 'agenda*) "Appointments for current week or day") - ((eq type 'alltodo) "List of all TODO entries") - ((eq type 'search) "Word search") - ((eq type 'stuck) "List of stuck projects") - ((eq type 'todo) "TODO keyword") - ((eq type 'tags) "Tags query") - ((eq type 'tags-todo) "Tags (TODO)") - ((eq type 'tags-tree) "Tags tree") - ((eq type 'todo-tree) "TODO kwd tree") - ((eq type 'occur-tree) "Occur tree") - ((functionp type) (if (symbolp type) - (symbol-name type) - "Lambda expression")) - (t "???")))) + (unwind-protect + (while t + (setq custom1 custom) + (when (eq rmheader t) + (org-goto-line 1) + (re-search-forward ":" nil t) + (delete-region (match-end 0) (line-end-position)) + (forward-char 1) + (looking-at "-+") + (delete-region (match-end 0) (line-end-position)) + (move-marker header-end (match-end 0))) + (goto-char header-end) + (delete-region (point) (point-max)) + + ;; Produce all the lines that describe custom commands and prefixes + (setq lines nil) + (while (setq entry (pop custom1)) + (setq key (car entry) desc (nth 1 entry) + type (nth 2 entry) + match (nth 3 entry)) + (if (> (length key) 1) + (cl-pushnew (string-to-char key) prefixes :test #'equal) + (setq line + (format + "%-4s%-14s" + (org-add-props (copy-sequence key) + '(face bold)) + (cond + ((string-match "\\S-" desc) desc) + ((eq type 'agenda) "Agenda for current week or day") + ((eq type 'agenda*) "Appointments for current week or day") + ((eq type 'alltodo) "List of all TODO entries") + ((eq type 'search) "Word search") + ((eq type 'stuck) "List of stuck projects") + ((eq type 'todo) "TODO keyword") + ((eq type 'tags) "Tags query") + ((eq type 'tags-todo) "Tags (TODO)") + ((eq type 'tags-tree) "Tags tree") + ((eq type 'todo-tree) "TODO kwd tree") + ((eq type 'occur-tree) "Occur tree") + ((functionp type) (if (symbolp type) + (symbol-name type) + "Lambda expression")) + (t "???")))) + (cond + ((not (org-string-nw-p match)) nil) + (org-agenda-menu-show-matcher + (setq line + (concat line ": " + (cond + ((stringp match) + (propertize match 'face 'org-warning)) + ((listp type) + (format "set of %d commands" (length type))))))) + (t + (org-add-props line nil 'help-echo (concat "Matcher: " match)))) + (push line lines))) + (setq lines (nreverse lines)) + (when prefixes + (mapc (lambda (x) + (push + (format "%s %s" + (org-add-props (char-to-string x) + nil 'face 'bold) + (or (cdr (assoc (concat selstring + (char-to-string x)) + prefix-descriptions)) + "Prefix key")) + lines)) + prefixes)) + + ;; Check if we should display in two columns + (if org-agenda-menu-two-columns + (progn + (setq n (length lines) + n1 (+ (/ n 2) (mod n 2)) + right (nthcdr n1 lines) + left (copy-sequence lines)) + (setcdr (nthcdr (1- n1) left) nil)) + (setq left lines right nil)) + (while left + (insert "\n" (pop left)) + (when right + (if (< (current-column) 40) + (move-to-column 40 t) + (insert " ")) + (insert (pop right)))) + + ;; Make the window the right size + (goto-char (point-min)) + (if second-time + (when (not (pos-visible-in-window-p (point-max))) + (org-fit-window-to-buffer)) + (setq second-time t) + (org-fit-window-to-buffer)) + + ;; Hint to navigation if window too small for all information + (setq header-line-format + (when (not (pos-visible-in-window-p (point-max))) + "Use C-v, M-v, C-n or C-p to navigate.")) + + ;; Ask for selection + (cl-loop + do (progn + (message "Press key for agenda command%s:" + (if (or restrict-ok org-agenda-overriding-restriction) + (if org-agenda-overriding-restriction + " (restriction lock active)" + (if restriction + (format " (restricted to %s)" restriction) + " (unrestricted)")) + "")) + (setq c (read-char-exclusive))) + until (not (memq c '(14 16 22 134217846))) + do (org-scroll c)) + + (message "") (cond - ((not (org-string-nw-p match)) nil) - (org-agenda-menu-show-matcher - (setq line - (concat line ": " - (cond - ((stringp match) - (propertize match 'face 'org-warning)) - ((listp type) - (format "set of %d commands" (length type))))))) - (t - (org-add-props line nil 'help-echo (concat "Matcher: " match)))) - (push line lines))) - (setq lines (nreverse lines)) - (when prefixes - (mapc (lambda (x) - (push - (format "%s %s" - (org-add-props (char-to-string x) - nil 'face 'bold) - (or (cdr (assoc (concat selstring - (char-to-string x)) - prefix-descriptions)) - "Prefix key")) - lines)) - prefixes)) - - ;; Check if we should display in two columns - (if org-agenda-menu-two-columns - (progn - (setq n (length lines) - n1 (+ (/ n 2) (mod n 2)) - right (nthcdr n1 lines) - left (copy-sequence lines)) - (setcdr (nthcdr (1- n1) left) nil)) - (setq left lines right nil)) - (while left - (insert "\n" (pop left)) - (when right - (if (< (current-column) 40) - (move-to-column 40 t) - (insert " ")) - (insert (pop right)))) - - ;; Make the window the right size - (goto-char (point-min)) - (if second-time - (when (not (pos-visible-in-window-p (point-max))) - (org-fit-window-to-buffer)) - (setq second-time t) - (org-fit-window-to-buffer)) - - ;; Hint to navigation if window too small for all information - (setq header-line-format - (when (not (pos-visible-in-window-p (point-max))) - "Use C-v, M-v, C-n or C-p to navigate.")) - - ;; Ask for selection - (cl-loop - do (progn - (message "Press key for agenda command%s:" - (if (or restrict-ok org-agenda-overriding-restriction) - (if org-agenda-overriding-restriction - " (restriction lock active)" - (if restriction - (format " (restricted to %s)" restriction) - " (unrestricted)")) - "")) - (setq c (read-char-exclusive))) - until (not (memq c '(14 16 22 134217846))) - do (org-scroll c)) - - (message "") - (cond - ((assoc (char-to-string c) custom) - (setq selstring (concat selstring (char-to-string c))) - (throw 'exit (cons selstring restriction))) - ((memq c prefixes) - (setq selstring (concat selstring (char-to-string c)) - prefixes nil - rmheader (or rmheader t) - custom (delq nil (mapcar - (lambda (x) - (if (or (= (length (car x)) 1) - (/= (string-to-char (car x)) c)) - nil - (cons (substring (car x) 1) (cdr x)))) - custom)))) - ((eq c ?*) - (call-interactively 'org-toggle-sticky-agenda) - (sit-for 2)) - ((and (not restrict-ok) (memq c '(?1 ?0 ?<))) - (message "Restriction is only possible in Org buffers") - (ding) (sit-for 1)) - ((eq c ?1) - (org-agenda-remove-restriction-lock 'noupdate) - (setq restriction 'buffer)) - ((eq c ?0) - (org-agenda-remove-restriction-lock 'noupdate) - (setq restriction (if region-p 'region 'subtree))) - ((eq c ?<) - (org-agenda-remove-restriction-lock 'noupdate) - (setq restriction - (cond - ((eq restriction 'buffer) - (if region-p 'region 'subtree)) - ((memq restriction '(subtree region)) - nil) - (t 'buffer)))) - ((eq c ?>) - (org-agenda-remove-restriction-lock 'noupdate) - (setq restriction nil)) - ((and (equal selstring "") (memq c '(?s ?S ?a ?t ?m ?L ?C ?e ?T ?M ?# ?! ?/ ??))) - (throw 'exit (cons (setq selstring (char-to-string c)) restriction))) - ((and (> (length selstring) 0) (eq c ?\d)) - (delete-window) - (org-agenda-get-restriction-and-command prefix-descriptions)) - - ((equal c ?q) (user-error "Abort")) - (t (user-error "Invalid key %c" c)))))))) + ((assoc (char-to-string c) custom) + (setq selstring (concat selstring (char-to-string c))) + (throw 'exit (cons selstring restriction))) + ((memq c prefixes) + (setq selstring (concat selstring (char-to-string c)) + prefixes nil + rmheader (or rmheader t) + custom (delq nil (mapcar + (lambda (x) + (if (or (= (length (car x)) 1) + (/= (string-to-char (car x)) c)) + nil + (cons (substring (car x) 1) (cdr x)))) + custom)))) + ((eq c ?*) + (call-interactively 'org-toggle-sticky-agenda) + (sit-for 2)) + ((and (not restrict-ok) (memq c '(?1 ?0 ?<))) + (message "Restriction is only possible in Org buffers") + (ding) (sit-for 1)) + ((eq c ?1) + (org-agenda-remove-restriction-lock 'noupdate) + (setq restriction 'buffer)) + ((eq c ?0) + (org-agenda-remove-restriction-lock 'noupdate) + (setq restriction (if region-p 'region 'subtree))) + ((eq c ?<) + (org-agenda-remove-restriction-lock 'noupdate) + (setq restriction + (cond + ((eq restriction 'buffer) + (if region-p 'region 'subtree)) + ((memq restriction '(subtree region)) + nil) + (t 'buffer)))) + ((eq c ?>) + (org-agenda-remove-restriction-lock 'noupdate) + (setq restriction nil)) + ((and (equal selstring "") (memq c '(?s ?S ?a ?t ?m ?L ?C ?e ?T ?M ?# ?! ?/ ??))) + (throw 'exit (cons (setq selstring (char-to-string c)) restriction))) + ((and (> (length selstring) 0) (eq c ?\d)) + (delete-window) + (org-agenda-get-restriction-and-command prefix-descriptions)) + + ((equal c ?q) (user-error "Abort")) + (t (user-error "Invalid key %c" c)))) + ;; Close *Agenda Commands* window. + (quit-window 'kill)))))) (defun org-agenda-fit-window-to-buffer () "Fit the window to the buffer size." @@ -3303,7 +3324,7 @@ s Search for keywords M Like m, but only TODO entries (fboundp 'fit-window-to-buffer) (if (and (= (cdr org-agenda-window-frame-fractions) 1.0) (= (car org-agenda-window-frame-fractions) 1.0)) - (delete-other-windows) + (display-buffer (current-buffer) '(org-display-buffer-full-frame)) (org-fit-window-to-buffer nil (floor (* (frame-height) (cdr org-agenda-window-frame-fractions))) @@ -3525,7 +3546,8 @@ This ensures the export commands can easily use it." (let ((cmds (org-agenda-normalize-custom-commands org-agenda-custom-commands)) (pop-up-frames nil) (dir default-directory) - cmd thiscmdkey thiscmdcmd match files opts cmd-or-set bufname) + cmd thiscmdkey thiscmdcmd match files opts cmd-or-set + seriesp bufname) (save-window-excursion (while cmds (setq cmd (pop cmds) @@ -3537,9 +3559,12 @@ This ensures the export commands can easily use it." (format "*Org Agenda(%s:%s)*" thiscmdkey match)) (format "*Org Agenda(%s)*" thiscmdkey)) org-agenda-buffer-name) + ;; series: (0:key 1:desc 2:(cmd1 cmd2 ...) 3:general-settings 4:files) + ;; non-series: (0:key 1:desc 2:type 3:match 4:settings 5:files) cmd-or-set (nth 2 cmd) - opts (nth (if (listp cmd-or-set) 3 4) cmd) - files (nth (if (listp cmd-or-set) 4 5) cmd)) + seriesp (not (or (symbolp cmd-or-set) (functionp cmd-or-set))) + opts (nth (if seriesp 3 4) cmd) + files (nth (if seriesp 4 5) cmd)) (if (stringp files) (setq files (list files))) (when files (let* ((opts (append org-agenda-exporter-settings opts)) @@ -3619,11 +3644,12 @@ the agenda to write." (goto-char p) (setq m (get-text-property (point) 'org-hd-marker)) (when m - (push (with-current-buffer (marker-buffer m) - (goto-char m) - (org-copy-subtree 1 nil t t) - org-subtree-clip) - content))) + (cl-pushnew (with-current-buffer (marker-buffer m) + (goto-char m) + (org-copy-subtree 1 nil t t) + org-subtree-clip) + content + :test #'equal))) (find-file file) (erase-buffer) (dolist (s content) (org-paste-subtree 1 s)) @@ -3631,8 +3657,7 @@ the agenda to write." (kill-buffer (current-buffer)) (message "Org file written to %s" file))) ((member extension '("html" "htm")) - (or (require 'htmlize nil t) - (error "Please install htmlize from https://github.com/hniksic/emacs-htmlize")) + (org-require-package 'htmlize) (declare-function htmlize-buffer "htmlize" (&optional buffer)) (set-buffer (htmlize-buffer (current-buffer))) (when org-agenda-export-html-style @@ -3664,13 +3689,8 @@ the agenda to write." "ox-icalendar" (file)) (org-icalendar-export-current-agenda (expand-file-name file))) (t - (let ((bs (buffer-string))) - (find-file file) - (erase-buffer) - (insert bs) - (save-buffer 0) - (kill-buffer (current-buffer)) - (message "Plain text written to %s" file)))))))) + (write-region nil nil file) + (message "Plain text written to %s" file))))))) (set-buffer (or agenda-bufname ;; FIXME: I'm pretty sure called-interactively-p ;; doesn't do what we want here! @@ -3700,7 +3720,7 @@ Drawers will be excluded, also the line with scheduling/deadline info." (goto-char (point-min)) (while (not (eobp)) (if (not (setq m (org-get-at-bol 'org-hd-marker))) - (beginning-of-line 2) + (forward-line 1) (setq txt (org-agenda-get-some-entry-text m org-agenda-add-entry-text-maxlines " > ")) (end-of-line 1) @@ -3768,13 +3788,13 @@ removed from the entry content. Currently only `planning' is allowed here." (while (not (eobp)) (unless (looking-at "[ \t]*$") (setq ind (min ind (org-current-text-indentation)))) - (beginning-of-line 2)) + (forward-line 1)) (goto-char (point-min)) (while (not (eobp)) (unless (looking-at "[ \t]*$") (move-to-column ind) (delete-region (line-beginning-position) (point))) - (beginning-of-line 2)) + (forward-line 1)) (run-hooks 'org-agenda-entry-text-cleanup-hook) @@ -3883,7 +3903,7 @@ generating a new one." ;; buffer found (get-buffer org-agenda-buffer-name) ;; C-u parameter is same as last call - (with-current-buffer (get-buffer org-agenda-buffer-name) + (with-current-buffer org-agenda-buffer-name (and (equal current-prefix-arg org-agenda-last-prefix-arg) @@ -3913,7 +3933,7 @@ FILTER-ALIST is an alist of filters we need to apply when ((eq org-agenda-window-setup 'current-window) (pop-to-buffer-same-window abuf)) ((eq org-agenda-window-setup 'other-window) - (org-switch-to-buffer-other-window abuf)) + (switch-to-buffer-other-window abuf)) ((eq org-agenda-window-setup 'other-frame) (switch-to-buffer-other-frame abuf)) ((eq org-agenda-window-setup 'other-tab) @@ -3921,11 +3941,9 @@ FILTER-ALIST is an alist of filters we need to apply when (switch-to-buffer-other-tab abuf) (user-error "Your version of Emacs does not have tab bar support"))) ((eq org-agenda-window-setup 'only-window) - (delete-other-windows) - (pop-to-buffer-same-window abuf)) + (pop-to-buffer abuf '(org-display-buffer-full-frame))) ((eq org-agenda-window-setup 'reorganize-frame) - (delete-other-windows) - (org-switch-to-buffer-other-window abuf))) + (pop-to-buffer abuf '(org-display-buffer-split)))) (setq org-agenda-tag-filter (cdr (assq 'tag filter-alist))) (setq org-agenda-category-filter (cdr (assq 'cat filter-alist))) (setq org-agenda-effort-filter (cdr (assq 'effort filter-alist))) @@ -3953,7 +3971,6 @@ FILTER-ALIST is an alist of filters we need to apply when (message "Sticky Agenda buffer, use `r' to refresh") (or org-agenda-multi (org-agenda-fit-window-to-buffer)) (throw 'exit "Sticky Agenda buffer, use `r' to refresh")) - (setq org-todo-keywords-for-agenda nil) (if org-agenda-multi (progn (setq buffer-read-only nil) @@ -3966,6 +3983,7 @@ FILTER-ALIST is an alist of filters we need to apply when (make-string (window-max-chars-per-line) org-agenda-block-separator)) "\n")) (narrow-to-region (point) (point-max))) + (setq org-todo-keywords-for-agenda nil) (setq org-done-keywords-for-agenda nil) ;; Setting any org variables that are in org-agenda-local-vars ;; list need to be done after the prepare call @@ -4166,7 +4184,9 @@ dimming them." ;FIXME: The arg isn't used, actually! (line-beginning-position)) (line-end-position)))) (when todo-blocked - (overlay-put ov 'face 'org-agenda-dimmed-todo-face)) + (overlay-put ov 'face 'org-agenda-dimmed-todo-face) + ;; Override other overlays. + (overlay-put ov 'priority 50)) (when invisible (org-agenda-filter-hide-line 'todo-blocked))) (if (= (point-max) (line-end-position)) @@ -4233,25 +4253,26 @@ Also moves point to the end of the skipped region, so that search can continue from there. Optional argument ELEMENT contains element at point." - (when (or - (if element - (eq (org-element-type element) 'comment) - (save-excursion - (goto-char (line-beginning-position)) - (looking-at comment-start-skip))) - (and org-agenda-skip-archived-trees (not org-agenda-archives-mode) - (or (and (save-match-data (org-in-archived-heading-p nil element)) - (org-end-of-subtree t element)) - (and (member org-archive-tag org-file-tags) - (goto-char (point-max))))) - (and org-agenda-skip-comment-trees - (org-in-commented-heading-p nil element) - (org-end-of-subtree t element)) - (let ((to (or (org-agenda-skip-eval org-agenda-skip-function-global) - (org-agenda-skip-eval org-agenda-skip-function)))) - (and to (goto-char to))) - (org-in-src-block-p t element)) - (throw :skip t))) + (save-match-data + (when (or + (if element + (org-element-type-p element 'comment) + (save-excursion + (goto-char (line-beginning-position)) + (looking-at comment-start-skip))) + (and org-agenda-skip-archived-trees (not org-agenda-archives-mode) + (or (and (save-match-data (org-in-archived-heading-p nil element)) + (org-end-of-subtree t element)) + (and (member org-archive-tag org-file-tags) + (goto-char (point-max))))) + (and org-agenda-skip-comment-trees + (org-in-commented-heading-p nil element) + (org-end-of-subtree t element)) + (let ((to (or (org-agenda-skip-eval org-agenda-skip-function-global) + (org-agenda-skip-eval org-agenda-skip-function)))) + (and to (goto-char to))) + (org-in-src-block-p t element)) + (throw :skip t)))) (defun org-agenda-skip-eval (form) "If FORM is a function or a list, call (or eval) it and return the result. @@ -4322,11 +4343,11 @@ This check for agenda markers in all agenda buffers currently active." (interactive) (save-excursion (goto-char (point-max)) - (beginning-of-line 1) + (forward-line 0) (while (not (bobp)) (when (org-get-at-bol 'org-hd-marker) (org-agenda-entry-text-show-here)) - (beginning-of-line 0)))) + (forward-line -1)))) (defun org-agenda-entry-text-hide () "Remove any shown entry context." @@ -4879,6 +4900,7 @@ is active." 'org-todo-regexp org-todo-regexp 'level level 'org-complex-heading-regexp org-complex-heading-regexp + 'urgency 1000 'priority 1000 'type "search") (push txt ee) @@ -4931,7 +4953,10 @@ Press `\\[org-agenda-manipulate-query-add]', \ "|")) "\n")) -(defvar org-select-this-todo-keyword nil) +(defvar org-select-this-todo-keyword nil + "Keyword selector for todo agenda. +Should either be a keyword, \"*\", or \"|\"-separated list of todo +keywords.") (defvar org-last-arg nil) (defvar crm-separator) @@ -4946,48 +4971,48 @@ for a keyword. A numeric prefix directly selects the Nth keyword in (interactive "P") (when org-agenda-overriding-arguments (setq arg org-agenda-overriding-arguments)) - (when (and (stringp arg) (not (string-match "\\S-" arg))) (setq arg nil)) - (let* ((today (org-today)) - (date (calendar-gregorian-from-absolute today)) + (when (and (stringp arg) (not (string-match "\\S-" arg))) + (setq arg nil)) + (let* ((today (calendar-gregorian-from-absolute (org-today))) (completion-ignore-case t) - kwds org-select-this-todo-keyword rtn rtnall files file pos) + todo-keywords org-select-this-todo-keyword todo-entries all-todo-entries files file pos) (catch 'exit (setq org-agenda-buffer-name (org-agenda--get-buffer-name - (and org-agenda-sticky + (when org-agenda-sticky (if (stringp org-select-this-todo-keyword) (format "*Org Agenda(%s:%s)*" (or org-keys "t") org-select-this-todo-keyword) (format "*Org Agenda(%s)*" (or org-keys "t")))))) (org-agenda-prepare "TODO") - (setq kwds org-todo-keywords-for-agenda - org-select-this-todo-keyword (if (stringp arg) arg - (and (integerp arg) - (> arg 0) - (nth (1- arg) kwds)))) + (setq todo-keywords org-todo-keywords-for-agenda + org-select-this-todo-keyword (cond ((stringp arg) arg) + ((and (integerp arg) (> arg 0)) + (nth (1- arg) todo-keywords)))) (when (equal arg '(4)) (setq org-select-this-todo-keyword (mapconcat #'identity (let ((crm-separator "|")) (completing-read-multiple "Keyword (or KWD1|KWD2|...): " - (mapcar #'list kwds) nil nil)) + (mapcar #'list todo-keywords) nil nil)) "|"))) - (and (equal 0 arg) (setq org-select-this-todo-keyword nil)) + (when (equal arg 0) + (setq org-select-this-todo-keyword nil)) (org-compile-prefix-format 'todo) (org-set-sorting-strategy 'todo) (setq org-agenda-redo-command - `(org-todo-list (or (and (numberp current-prefix-arg) - current-prefix-arg) + `(org-todo-list (or (and (numberp current-prefix-arg) current-prefix-arg) ,org-select-this-todo-keyword - current-prefix-arg ,arg))) + current-prefix-arg + ,arg))) (setq files (org-agenda-files nil 'ifmode) - rtnall nil) + all-todo-entries nil) (while (setq file (pop files)) (catch 'nextfile (org-check-agenda-file file) - (setq rtn (org-agenda-get-day-entries file date :todo)) - (setq rtnall (append rtnall rtn)))) + (setq todo-entries (org-agenda-get-day-entries file today :todo)) + (setq all-todo-entries (append all-todo-entries todo-entries)))) (org-agenda--insert-overriding-header (with-temp-buffer (insert "Global list of TODO items of type: ") @@ -5005,7 +5030,7 @@ for a keyword. A numeric prefix directly selects the Nth keyword in \\`N \\[org-agenda-redo]' (e.g. `0 \\[org-agenda-redo]') \ to search again: (0)[ALL]")) (let ((n 0)) - (dolist (k kwds) + (dolist (k todo-keywords) (let ((s (format "(%d)%s" (cl-incf n) k))) (when (> (+ (current-column) (string-width s) 1) (window-max-chars-per-line)) (insert "\n ")) @@ -5014,8 +5039,8 @@ to search again: (0)[ALL]")) (add-text-properties pos (1- (point)) (list 'face 'org-agenda-structure-secondary)) (buffer-string))) (org-agenda-mark-header-line (point-min)) - (when rtnall - (insert (org-agenda-finalize-entries rtnall 'todo) "\n")) + (when all-todo-entries + (insert (org-agenda-finalize-entries all-todo-entries 'todo) "\n")) (goto-char (point-min)) (or org-agenda-multi (org-agenda-fit-window-to-buffer)) (add-text-properties (point-min) (point-max) @@ -5290,8 +5315,8 @@ of what a project is and how to check if it stuck, customize the variable (org-delete-all org-done-keywords-for-agenda (copy-sequence org-todo-keywords-for-agenda)))) (todo-re (and todo - (format "^\\*+[ \t]+\\(%s\\)\\>" - (mapconcat #'identity todo-wds "\\|")))) + (format "^\\*+[ \t]+\\(%s\\)\\(?:[ \t]\\|$\\)" + (mapconcat #'regexp-quote todo-wds "\\|")))) (tags-re (cond ((null tags) nil) ((member "*" tags) org-tag-line-re) (tags @@ -5575,35 +5600,35 @@ the documentation of `org-diary'." (defvar org-heading-keyword-regexp-format) ; defined in org.el (defvar org-agenda-sorting-strategy-selected nil) -(defun org-agenda-entry-get-agenda-timestamp (pom) +(defun org-agenda-entry-get-agenda-timestamp (epom) "Retrieve timestamp information for sorting agenda views. -Given a point or marker POM, returns a cons cell of the timestamp -and the timestamp type relevant for the sorting strategy in +Given an element, point, or marker EPOM, returns a cons cell of the +timestamp and the timestamp type relevant for the sorting strategy in `org-agenda-sorting-strategy-selected'." (let (ts ts-date-type) (save-match-data (cond ((org-em 'scheduled-up 'scheduled-down org-agenda-sorting-strategy-selected) - (setq ts (org-entry-get pom "SCHEDULED") + (setq ts (org-entry-get epom "SCHEDULED") ts-date-type " scheduled")) ((org-em 'deadline-up 'deadline-down org-agenda-sorting-strategy-selected) - (setq ts (org-entry-get pom "DEADLINE") + (setq ts (org-entry-get epom "DEADLINE") ts-date-type " deadline")) ((org-em 'ts-up 'ts-down org-agenda-sorting-strategy-selected) - (setq ts (org-entry-get pom "TIMESTAMP") + (setq ts (org-entry-get epom "TIMESTAMP") ts-date-type " timestamp")) ((org-em 'tsia-up 'tsia-down org-agenda-sorting-strategy-selected) - (setq ts (org-entry-get pom "TIMESTAMP_IA") + (setq ts (org-entry-get epom "TIMESTAMP_IA") ts-date-type " timestamp_ia")) ((org-em 'timestamp-up 'timestamp-down org-agenda-sorting-strategy-selected) - (setq ts (or (org-entry-get pom "SCHEDULED") - (org-entry-get pom "DEADLINE") - (org-entry-get pom "TIMESTAMP") - (org-entry-get pom "TIMESTAMP_IA")) + (setq ts (or (org-entry-get epom "SCHEDULED") + (org-entry-get epom "DEADLINE") + (org-entry-get epom "TIMESTAMP") + (org-entry-get epom "TIMESTAMP_IA")) ts-date-type "")) (t (setq ts-date-type ""))) (cons (when ts (ignore-errors (org-time-string-to-absolute ts))) @@ -5628,14 +5653,14 @@ and the timestamp type relevant for the sorting strategy in org-todo-regexp) (org-select-this-todo-keyword (concat "\\(" - (mapconcat #'identity - (org-split-string - org-select-this-todo-keyword - "|") - "\\|") + (mapconcat #'regexp-quote + (org-split-string + org-select-this-todo-keyword + "|") + "\\|") "\\)")) (t org-not-done-regexp)))) - marker priority category level tags todo-state + marker priority urgency category level tags todo-state ts-date ts-date-type ts-date-pair ee txt beg end inherited-tags todo-state-end-pos effort effort-minutes) @@ -5643,7 +5668,7 @@ and the timestamp type relevant for the sorting strategy in (while (re-search-forward regexp nil t) (catch :skip (save-match-data - (beginning-of-line) + (forward-line 0) (org-agenda-skip) (setq beg (point) end (save-excursion (outline-next-heading) (point))) (unless (and (setq todo-state (org-get-todo-state)) @@ -5656,7 +5681,7 @@ and the timestamp type relevant for the sorting strategy in (throw :skip nil))) (goto-char (match-beginning 2)) (setq marker (org-agenda-new-marker (match-beginning 0)) - category (org-get-category) + category (save-match-data (org-get-category)) effort (save-match-data (or (get-text-property (point) 'effort) (org-entry-get (point) org-effort-property))) effort-minutes (when effort (save-match-data (org-duration-to-minutes effort))) @@ -5673,15 +5698,18 @@ and the timestamp type relevant for the sorting strategy in (memq 'todo org-agenda-use-tag-inheritance)))) tags (org-get-tags nil (not inherited-tags)) level (make-string (org-reduced-level (org-outline-level)) ? ) - txt (org-agenda-format-item "" - (org-add-props txt nil - 'effort effort - 'effort-minutes effort-minutes) - level category tags t) - priority (1+ (org-get-priority txt))) + txt (org-agenda-format-item + "" + (org-add-props txt nil + 'effort effort + 'effort-minutes effort-minutes) + level category tags t) + urgency (1+ (org-get-priority txt)) + priority (org-get-priority txt)) (org-add-props txt props 'org-marker marker 'org-hd-marker marker 'priority priority + 'urgency urgency 'effort effort 'effort-minutes effort-minutes 'level level 'ts-date ts-date @@ -5697,7 +5725,7 @@ and the timestamp type relevant for the sorting strategy in This function is invoked if `org-agenda-todo-ignore-deadlines', `org-agenda-todo-ignore-scheduled' or `org-agenda-todo-ignore-timestamp' is set to an integer." - (let ((days (org-time-stamp-to-now + (let ((days (org-timestamp-to-now time org-agenda-todo-ignore-time-comparison-use-seconds))) (if (>= n 0) (>= days n) @@ -5719,13 +5747,13 @@ This function is invoked if `org-agenda-todo-ignore-deadlines', (re-search-forward org-scheduled-time-regexp end t) (cond ((eq org-agenda-todo-ignore-scheduled 'future) - (> (org-time-stamp-to-now + (> (org-timestamp-to-now (match-string 1) org-agenda-todo-ignore-time-comparison-use-seconds) 0)) ((eq org-agenda-todo-ignore-scheduled 'past) - (<= (org-time-stamp-to-now - (match-string 1) org-agenda-todo-ignore-time-comparison-use-seconds) - 0)) + (<= (org-timestamp-to-now + (match-string 1) org-agenda-todo-ignore-time-comparison-use-seconds) + 0)) ((numberp org-agenda-todo-ignore-scheduled) (org-agenda-todo-custom-ignore-p (match-string 1) org-agenda-todo-ignore-scheduled)) @@ -5737,13 +5765,13 @@ This function is invoked if `org-agenda-todo-ignore-deadlines', ((eq org-agenda-todo-ignore-deadlines 'far) (not (org-deadline-close-p (match-string 1)))) ((eq org-agenda-todo-ignore-deadlines 'future) - (> (org-time-stamp-to-now + (> (org-timestamp-to-now (match-string 1) org-agenda-todo-ignore-time-comparison-use-seconds) 0)) ((eq org-agenda-todo-ignore-deadlines 'past) - (<= (org-time-stamp-to-now - (match-string 1) org-agenda-todo-ignore-time-comparison-use-seconds) - 0)) + (<= (org-timestamp-to-now + (match-string 1) org-agenda-todo-ignore-time-comparison-use-seconds) + 0)) ((numberp org-agenda-todo-ignore-deadlines) (org-agenda-todo-custom-ignore-p (match-string 1) org-agenda-todo-ignore-deadlines)) @@ -5766,13 +5794,13 @@ This function is invoked if `org-agenda-todo-ignore-deadlines', (when (re-search-forward org-ts-regexp nil t) (cond ((eq org-agenda-todo-ignore-timestamp 'future) - (> (org-time-stamp-to-now + (> (org-timestamp-to-now (match-string 1) org-agenda-todo-ignore-time-comparison-use-seconds) 0)) ((eq org-agenda-todo-ignore-timestamp 'past) - (<= (org-time-stamp-to-now - (match-string 1) org-agenda-todo-ignore-time-comparison-use-seconds) - 0)) + (<= (org-timestamp-to-now + (match-string 1) org-agenda-todo-ignore-time-comparison-use-seconds) + 0)) ((numberp org-agenda-todo-ignore-timestamp) (org-agenda-todo-custom-ignore-p (match-string 1) org-agenda-todo-ignore-timestamp)) @@ -5798,30 +5826,28 @@ displayed in agenda view." (let ((m (get-text-property 0 'org-hd-marker d))) (and m (marker-position m)))) deadlines)) - ;; Match time-stamps set to current date, time-stamps with - ;; a repeater, and S-exp time-stamps. + ;; Match timestamps set to current date, timestamps with + ;; a repeater, and S-exp timestamps. (regexp (concat (if org-agenda-include-inactive-timestamps "[[<]" "<") (regexp-quote - (substring - (format-time-string - (org-time-stamp-format) - (org-encode-time ; DATE bound by calendar - 0 0 0 (nth 1 date) (car date) (nth 2 date))) - 1 11)) + (format-time-string + "%Y-%m-%d" ; We do not use `org-time-stamp-format' to not demand day name in timestamps. + (org-encode-time ; DATE bound by calendar + 0 0 0 (nth 1 date) (car date) (nth 2 date)))) "\\|\\(<[0-9]+-[0-9]+-[0-9]+[^>\n]+?\\+[0-9]+[hdwmy]>\\)" - "\\|\\(<%%\\(([^>\n]+)\\)>\\)")) + "\\|\\(<%%\\(([^>\n]+)\\)\\([^\n>]*\\)>\\)")) timestamp-items) (goto-char (point-min)) (while (re-search-forward regexp nil t) ;; Skip date ranges, scheduled and deadlines, which are handled - ;; specially. Also skip time-stamps before first headline as + ;; specially. Also skip timestamps before first headline as ;; there would be no entry to add to the agenda. Eventually, ;; ignore clock entries. (catch :skip (save-match-data - (when (or (org-at-date-range-p) + (when (or (org-at-date-range-p t) (org-at-planning-p) (org-before-first-heading-p) (and org-agenda-include-inactive-timestamps @@ -5832,13 +5858,13 @@ displayed in agenda view." (let* ((pos (match-beginning 0)) (repeat (match-string 1)) (sexp-entry (match-string 3)) - (time-stamp (if (or repeat sexp-entry) (match-string 0) - (save-excursion - (goto-char pos) - (looking-at org-ts-regexp-both) - (match-string 0)))) + (timestamp (if (or repeat sexp-entry) (match-string 0) + (save-excursion + (goto-char pos) + (looking-at org-ts-regexp-both) + (match-string 0)))) (todo-state (org-get-todo-state)) - (warntime (get-text-property (point) 'org-appt-warntime)) + (warntime (org-entry-get (point) "APPT_WARNTIME" 'selective)) (done? (member todo-state org-done-keywords))) ;; Possibly skip done tasks. (when (and done? org-agenda-skip-timestamp-if-done) @@ -5881,7 +5907,7 @@ displayed in agenda view." (throw :skip nil)))) (save-excursion (re-search-backward org-outline-regexp-bol nil t) - ;; Possibly skip time-stamp when a deadline is set. + ;; Possibly skip timestamp when a deadline is set. (when (and org-agenda-skip-timestamp-if-deadline-is-shown (assq (point) deadline-position-alist)) (throw :skip nil)) @@ -5909,11 +5935,12 @@ displayed in agenda view." (org-add-props head nil 'effort effort 'effort-minutes effort-minutes) - level category tags time-stamp org-ts-regexp habit?))) + level category tags timestamp org-ts-regexp habit?))) (org-add-props item props - 'priority (if habit? - (org-habit-get-priority (org-habit-parse-todo)) - (org-get-priority item)) + 'urgency (if habit? + (org-habit-get-urgency (org-habit-parse-todo)) + (org-get-priority item)) + 'priority (org-get-priority item) 'org-marker (org-agenda-new-marker pos) 'org-hd-marker (org-agenda-new-marker) 'date date @@ -5983,7 +6010,7 @@ displayed in agenda view." (memq 'agenda org-agenda-use-tag-inheritance)))) tags (org-get-tags nil (not inherited-tags)) todo-state (org-get-todo-state) - warntime (get-text-property (point) 'org-appt-warntime) + warntime (org-entry-get (point) "APPT_WARNTIME" 'selective) extra nil) (setq effort-minutes (when effort (save-match-data (org-duration-to-minutes effort)))) @@ -5998,10 +6025,10 @@ displayed in agenda view." (setq txt r) (setq txt "SEXP entry returned empty string")) (setq txt (org-agenda-format-item extra - (org-add-props txt nil - 'effort effort - 'effort-minutes effort-minutes) - level category tags 'time)) + (org-add-props txt nil + 'effort effort + 'effort-minutes effort-minutes) + level category tags 'time)) (org-add-props txt props 'org-marker marker 'date date 'todo-state todo-state 'effort effort 'effort-minutes effort-minutes @@ -6087,12 +6114,10 @@ then those holidays will be skipped." "\\(" parts-re "\\)" " *\\[" (regexp-quote - (substring - (format-time-string - (org-time-stamp-format) - (org-encode-time ; DATE bound by calendar - 0 0 0 (nth 1 date) (car date) (nth 2 date))) - 1 11)))) + (format-time-string + "%Y-%m-%d" ; We do not use `org-time-stamp-format' to not demand day name in timestamps. + (org-encode-time ; DATE bound by calendar + 0 0 0 (nth 1 date) (car date) (nth 2 date)))))) (org-agenda-search-headline-for-time nil) marker hdmarker priority category level tags closedp type statep clockp state ee txt extra timestr rest clocked inherited-tags @@ -6106,12 +6131,12 @@ then those holidays will be skipped." statep (equal (string-to-char (match-string 1)) ?-) clockp (not (or closedp statep)) state (and statep (match-string 2)) - category (org-get-category (match-beginning 0)) + category (save-match-data (org-get-category (match-beginning 0))) timestr (buffer-substring (match-beginning 0) (line-end-position)) effort (save-match-data (or (get-text-property (point) 'effort) (org-entry-get (point) org-effort-property)))) (setq effort-minutes (when effort (save-match-data (org-duration-to-minutes effort)))) - (when (string-match "\\]" timestr) + (when (string-match org-ts-regexp-inactive timestr) ;; substring should only run to end of time stamp (setq rest (substring timestr (match-end 0)) timestr (substring timestr 0 (match-end 0))) @@ -6167,7 +6192,7 @@ then those holidays will be skipped." (setq priority 100000) (org-add-props txt props 'org-marker marker 'org-hd-marker hdmarker 'face 'org-agenda-done - 'priority priority 'level level + 'urgency priority 'priority priority 'level level 'effort effort 'effort-minutes effort-minutes 'type type 'date date 'undone-face 'org-warning 'done-face 'org-agenda-done) @@ -6315,315 +6340,180 @@ specification like [h]h:mm." (today (org-today)) (today? (org-agenda-today-p date)) ; DATE bound by calendar. (current (calendar-absolute-from-gregorian date)) - deadline-items) - (goto-char (point-min)) - (if (org-element--cache-active-p) - (org-element-cache-map - (lambda (el) - (when (and (org-element-property :deadline el) - (or (not with-hour) - (org-element-property - :hour-start - (org-element-property :deadline el)) - (org-element-property - :hour-end - (org-element-property :deadline el)))) - (goto-char (org-element-property :contents-begin el)) - (catch :skip - (org-agenda-skip el) - (let* ((s (substring (org-element-property - :raw-value - (org-element-property :deadline el)) - 1 -1)) - (pos (save-excursion - (goto-char (org-element-property :contents-begin el)) - ;; We intentionally leave NOERROR - ;; argument in `re-search-forward' nil. If - ;; the search fails here, something went - ;; wrong and we are looking at - ;; non-matching headline. - (re-search-forward regexp (line-end-position)) - (1- (match-beginning 1)))) - (todo-state (org-element-property :todo-keyword el)) - (done? (eq 'done (org-element-property :todo-type el))) - (sexp? (eq 'diary - (org-element-property - :type (org-element-property :deadline el)))) - ;; DEADLINE is the deadline date for the entry. It is - ;; either the base date or the last repeat, according - ;; to `org-agenda-prefer-last-repeat'. - (deadline - (cond - (sexp? (org-agenda--timestamp-to-absolute s current)) - ((or (eq org-agenda-prefer-last-repeat t) - (member todo-state org-agenda-prefer-last-repeat)) - (org-agenda--timestamp-to-absolute - s today 'past (current-buffer) pos)) - (t (org-agenda--timestamp-to-absolute s)))) - ;; REPEAT is the future repeat closest from CURRENT, - ;; according to `org-agenda-show-future-repeats'. If - ;; the latter is nil, or if the time stamp has no - ;; repeat part, default to DEADLINE. - (repeat + deadline-items) + (org-element-cache-map + (lambda (el) + (when (and (org-element-property :deadline el) + ;; Only consider active timestamp values. + (memq (org-element-property + :type + (org-element-property :deadline el)) + '(diary active active-range)) + (or (not with-hour) + (org-element-property + :hour-start + (org-element-property :deadline el)) + (org-element-property + :hour-end + (org-element-property :deadline el)))) + (goto-char (org-element-contents-begin el)) + (catch :skip + (org-agenda-skip el) + (let* ((s (substring (org-element-property + :raw-value + (org-element-property :deadline el)) + 1 -1)) + (pos (save-excursion + (goto-char (org-element-contents-begin el)) + ;; We intentionally leave NOERROR + ;; argument in `re-search-forward' nil. If + ;; the search fails here, something went + ;; wrong and we are looking at + ;; non-matching headline. + (re-search-forward regexp (line-end-position)) + (1- (match-beginning 1)))) + (todo-state (org-element-property :todo-keyword el)) + (done? (eq 'done (org-element-property :todo-type el))) + (sexp? (eq 'diary + (org-element-property + :type (org-element-property :deadline el)))) + ;; DEADLINE is the deadline date for the entry. It is + ;; either the base date or the last repeat, according + ;; to `org-agenda-prefer-last-repeat'. + (deadline + (cond + (sexp? (org-agenda--timestamp-to-absolute s current)) + ((or (eq org-agenda-prefer-last-repeat t) + (member todo-state org-agenda-prefer-last-repeat)) + (org-agenda--timestamp-to-absolute + s today 'past (current-buffer) pos)) + (t (org-agenda--timestamp-to-absolute s)))) + ;; REPEAT is the future repeat closest from CURRENT, + ;; according to `org-agenda-show-future-repeats'. If + ;; the latter is nil, or if the time stamp has no + ;; repeat part, default to DEADLINE. + (repeat + (cond + (sexp? deadline) + ((<= current today) deadline) + ((not org-agenda-show-future-repeats) deadline) + (t + (let ((base (if (eq org-agenda-show-future-repeats 'next) + (1+ today) + current))) + (org-agenda--timestamp-to-absolute + s base 'future (current-buffer) pos))))) + (diff (- deadline current)) + (max-warning-days + (let ((scheduled + (and org-agenda-skip-deadline-prewarning-if-scheduled + (org-element-property + :raw-value + (org-element-property :scheduled el))))) + (cond + ((not scheduled) most-positive-fixnum) + ;; The current item has a scheduled date, so + ;; evaluate its prewarning lead time. + ((integerp org-agenda-skip-deadline-prewarning-if-scheduled) + ;; Use global prewarning-restart lead time. + org-agenda-skip-deadline-prewarning-if-scheduled) + ((eq org-agenda-skip-deadline-prewarning-if-scheduled + 'pre-scheduled) + ;; Set pre-warning to no earlier than SCHEDULED. + (min (- deadline + (org-agenda--timestamp-to-absolute scheduled)) + org-deadline-warning-days)) + ;; Set pre-warning to deadline. + (t 0)))) + (warning-days (min max-warning-days (org-get-wdays s)))) + (cond + ;; Only display deadlines at their base date, at future + ;; repeat occurrences or in today agenda. + ((= current deadline) nil) + ((= current repeat) nil) + ((not today?) (throw :skip nil)) + ;; Upcoming deadline: display within warning period WARNING-DAYS. + ((> deadline current) (when (> diff warning-days) (throw :skip nil))) + ;; Overdue deadline: warn about it for + ;; `org-deadline-past-days' duration. + (t (when (< org-deadline-past-days (- diff)) (throw :skip nil)))) + ;; Possibly skip done tasks. + (when (and done? + (or org-agenda-skip-deadline-if-done + (/= deadline current))) + (throw :skip nil)) + (save-excursion + (goto-char (org-element-begin el)) + (let* ((category (org-get-category)) + (effort (save-match-data (or (get-text-property (point) 'effort) + (org-element-property (intern (concat ":" (upcase org-effort-property))) el)))) + (effort-minutes (when effort (save-match-data (org-duration-to-minutes effort)))) + (level (make-string (org-element-property :level el) + ?\s)) + (head (save-excursion + (goto-char (org-element-begin el)) + (re-search-forward org-outline-regexp-bol) + (buffer-substring-no-properties (point) (line-end-position)))) + (inherited-tags + (or (eq org-agenda-show-inherited-tags 'always) + (and (listp org-agenda-show-inherited-tags) + (memq 'agenda org-agenda-show-inherited-tags)) + (and (eq org-agenda-show-inherited-tags t) + (or (eq org-agenda-use-tag-inheritance t) + (memq 'agenda + org-agenda-use-tag-inheritance))))) + (tags (org-get-tags el (not inherited-tags))) + (time (cond - (sexp? deadline) - ((<= current today) deadline) - ((not org-agenda-show-future-repeats) deadline) - (t - (let ((base (if (eq org-agenda-show-future-repeats 'next) - (1+ today) - current))) - (org-agenda--timestamp-to-absolute - s base 'future (current-buffer) pos))))) - (diff (- deadline current)) - (suppress-prewarning - (let ((scheduled - (and org-agenda-skip-deadline-prewarning-if-scheduled - (org-element-property - :raw-value - (org-element-property :scheduled el))))) - (cond - ((not scheduled) nil) - ;; The current item has a scheduled date, so - ;; evaluate its prewarning lead time. - ((integerp org-agenda-skip-deadline-prewarning-if-scheduled) - ;; Use global prewarning-restart lead time. - org-agenda-skip-deadline-prewarning-if-scheduled) - ((eq org-agenda-skip-deadline-prewarning-if-scheduled - 'pre-scheduled) - ;; Set pre-warning to no earlier than SCHEDULED. - (min (- deadline - (org-agenda--timestamp-to-absolute scheduled)) - org-deadline-warning-days)) - ;; Set pre-warning to deadline. - (t 0)))) - (wdays (or suppress-prewarning (org-get-wdays s)))) - (cond - ;; Only display deadlines at their base date, at future - ;; repeat occurrences or in today agenda. - ((= current deadline) nil) - ((= current repeat) nil) - ((not today?) (throw :skip nil)) - ;; Upcoming deadline: display within warning period WDAYS. - ((> deadline current) (when (> diff wdays) (throw :skip nil))) - ;; Overdue deadline: warn about it for - ;; `org-deadline-past-days' duration. - (t (when (< org-deadline-past-days (- diff)) (throw :skip nil)))) - ;; Possibly skip done tasks. - (when (and done? - (or org-agenda-skip-deadline-if-done - (/= deadline current))) - (throw :skip nil)) - (save-excursion - (goto-char (org-element-property :begin el)) - (let* ((category (org-get-category)) - (effort (save-match-data (or (get-text-property (point) 'effort) - (org-element-property (intern (concat ":" (upcase org-effort-property))) el)))) - (effort-minutes (when effort (save-match-data (org-duration-to-minutes effort)))) - (level (make-string (org-element-property :level el) - ?\s)) - (head (save-excursion - (goto-char (org-element-property :begin el)) - (re-search-forward org-outline-regexp-bol) - (buffer-substring-no-properties (point) (line-end-position)))) - (inherited-tags - (or (eq org-agenda-show-inherited-tags 'always) - (and (listp org-agenda-show-inherited-tags) - (memq 'agenda org-agenda-show-inherited-tags)) - (and (eq org-agenda-show-inherited-tags t) - (or (eq org-agenda-use-tag-inheritance t) - (memq 'agenda - org-agenda-use-tag-inheritance))))) - (tags (org-get-tags el (not inherited-tags))) - (time - (cond - ;; No time of day designation if it is only - ;; a reminder. - ((and (/= current deadline) (/= current repeat)) nil) - ((string-match " \\([012]?[0-9]:[0-9][0-9]\\)" s) - (concat (substring s (match-beginning 1)) " ")) - (t 'time))) - (item - (org-agenda-format-item - ;; Insert appropriate suffixes before deadlines. - ;; Those only apply to today agenda. - (pcase-let ((`(,now ,future ,past) - org-agenda-deadline-leaders)) - (cond - ((and today? (< deadline today)) (format past (- diff))) - ((and today? (> deadline today)) (format future diff)) - (t now))) - (org-add-props head nil - 'effort effort - 'effort-minutes effort-minutes) - level category tags time)) - (face (org-agenda-deadline-face - (- 1 (/ (float diff) (max wdays 1))))) - (upcoming? (and today? (> deadline today))) - (warntime (get-text-property (point) 'org-appt-warntime))) - (org-add-props item props - 'org-marker (org-agenda-new-marker pos) - 'org-hd-marker (org-agenda-new-marker (line-beginning-position)) - 'warntime warntime - 'level level - 'effort effort 'effort-minutes effort-minutes - 'ts-date deadline - 'priority - ;; Adjust priority to today reminders about deadlines. - ;; Overdue deadlines get the highest priority - ;; increase, then imminent deadlines and eventually - ;; more distant deadlines. - (let ((adjust (if today? (- diff) 0))) - (+ adjust (org-get-priority item))) - 'todo-state todo-state - 'type (if upcoming? "upcoming-deadline" "deadline") - 'date (if upcoming? date deadline) - 'face (if done? 'org-agenda-done face) - 'undone-face face - 'done-face 'org-agenda-done) - (push item deadline-items))))))) - :next-re regexp - :fail-re regexp - :narrow t) - (while (re-search-forward regexp nil t) - (catch :skip - (unless (save-match-data (org-at-planning-p)) (throw :skip nil)) - (org-agenda-skip) - (let* ((s (match-string 1)) - (pos (1- (match-beginning 1))) - (todo-state (save-match-data (org-get-todo-state))) - (done? (member todo-state org-done-keywords)) - (sexp? (string-prefix-p "%%" s)) - ;; DEADLINE is the deadline date for the entry. It is - ;; either the base date or the last repeat, according - ;; to `org-agenda-prefer-last-repeat'. - (deadline - (cond - (sexp? (org-agenda--timestamp-to-absolute s current)) - ((or (eq org-agenda-prefer-last-repeat t) - (member todo-state org-agenda-prefer-last-repeat)) - (org-agenda--timestamp-to-absolute - s today 'past (current-buffer) pos)) - (t (org-agenda--timestamp-to-absolute s)))) - ;; REPEAT is the future repeat closest from CURRENT, - ;; according to `org-agenda-show-future-repeats'. If - ;; the latter is nil, or if the time stamp has no - ;; repeat part, default to DEADLINE. - (repeat - (cond - (sexp? deadline) - ((<= current today) deadline) - ((not org-agenda-show-future-repeats) deadline) - (t - (let ((base (if (eq org-agenda-show-future-repeats 'next) - (1+ today) - current))) - (org-agenda--timestamp-to-absolute - s base 'future (current-buffer) pos))))) - (diff (- deadline current)) - (suppress-prewarning - (let ((scheduled - (and org-agenda-skip-deadline-prewarning-if-scheduled - (org-entry-get nil "SCHEDULED")))) - (cond - ((not scheduled) nil) - ;; The current item has a scheduled date, so - ;; evaluate its prewarning lead time. - ((integerp org-agenda-skip-deadline-prewarning-if-scheduled) - ;; Use global prewarning-restart lead time. - org-agenda-skip-deadline-prewarning-if-scheduled) - ((eq org-agenda-skip-deadline-prewarning-if-scheduled - 'pre-scheduled) - ;; Set pre-warning to no earlier than SCHEDULED. - (min (- deadline - (org-agenda--timestamp-to-absolute scheduled)) - org-deadline-warning-days)) - ;; Set pre-warning to deadline. - (t 0)))) - (wdays (or suppress-prewarning (org-get-wdays s)))) - (cond - ;; Only display deadlines at their base date, at future - ;; repeat occurrences or in today agenda. - ((= current deadline) nil) - ((= current repeat) nil) - ((not today?) (throw :skip nil)) - ;; Upcoming deadline: display within warning period WDAYS. - ((> deadline current) (when (> diff wdays) (throw :skip nil))) - ;; Overdue deadline: warn about it for - ;; `org-deadline-past-days' duration. - (t (when (< org-deadline-past-days (- diff)) (throw :skip nil)))) - ;; Possibly skip done tasks. - (when (and done? - (or org-agenda-skip-deadline-if-done - (/= deadline current))) - (throw :skip nil)) - (save-excursion - (re-search-backward "^\\*+[ \t]+" nil t) - (goto-char (match-end 0)) - (let* ((category (org-get-category)) - (effort (save-match-data (or (get-text-property (point) 'effort) - (org-entry-get (point) org-effort-property)))) - (effort-minutes (when effort (save-match-data (org-duration-to-minutes effort)))) - (level (make-string (org-reduced-level (org-outline-level)) - ?\s)) - (head (buffer-substring-no-properties - (point) (line-end-position))) - (inherited-tags - (or (eq org-agenda-show-inherited-tags 'always) - (and (listp org-agenda-show-inherited-tags) - (memq 'agenda org-agenda-show-inherited-tags)) - (and (eq org-agenda-show-inherited-tags t) - (or (eq org-agenda-use-tag-inheritance t) - (memq 'agenda - org-agenda-use-tag-inheritance))))) - (tags (org-get-tags nil (not inherited-tags))) - (time - (cond - ;; No time of day designation if it is only - ;; a reminder. - ((and (/= current deadline) (/= current repeat)) nil) - ((string-match " \\([012]?[0-9]:[0-9][0-9]\\)" s) - (concat (substring s (match-beginning 1)) " ")) - (t 'time))) - (item - (org-agenda-format-item - ;; Insert appropriate suffixes before deadlines. - ;; Those only apply to today agenda. - (pcase-let ((`(,now ,future ,past) - org-agenda-deadline-leaders)) - (cond - ((and today? (< deadline today)) (format past (- diff))) - ((and today? (> deadline today)) (format future diff)) - (t now))) - (org-add-props head nil - 'effort effort - 'effort-minutes effort-minutes) - level category tags time)) - (face (org-agenda-deadline-face - (- 1 (/ (float diff) (max wdays 1))))) - (upcoming? (and today? (> deadline today))) - (warntime (get-text-property (point) 'org-appt-warntime))) - (org-add-props item props - 'org-marker (org-agenda-new-marker pos) - 'org-hd-marker (org-agenda-new-marker (line-beginning-position)) - 'warntime warntime - 'level level - 'effort effort 'effort-minutes effort-minutes - 'ts-date deadline - 'priority - ;; Adjust priority to today reminders about deadlines. - ;; Overdue deadlines get the highest priority - ;; increase, then imminent deadlines and eventually - ;; more distant deadlines. - (let ((adjust (if today? (- diff) 0))) - (+ adjust (org-get-priority item))) - 'todo-state todo-state - 'type (if upcoming? "upcoming-deadline" "deadline") - 'date (if upcoming? date deadline) - 'face (if done? 'org-agenda-done face) - 'undone-face face - 'done-face 'org-agenda-done) - (push item deadline-items))))))) + ;; No time of day designation if it is only + ;; a reminder. + ((and (/= current deadline) (/= current repeat)) nil) + ((string-match " \\([012]?[0-9]:[0-9][0-9]\\)" s) + (concat (substring s (match-beginning 1)) " ")) + (t 'time))) + (item + (org-agenda-format-item + ;; Insert appropriate suffixes before deadlines. + ;; Those only apply to today agenda. + (pcase-let ((`(,now ,future ,past) + org-agenda-deadline-leaders)) + (cond + ((and today? (< deadline today)) (format past (- diff))) + ((and today? (> deadline today)) (format future diff)) + (t now))) + (org-add-props head nil + 'effort effort + 'effort-minutes effort-minutes) + level category tags time)) + (face (org-agenda-deadline-face + (- 1 (/ (float diff) (max warning-days 1))))) + (upcoming? (and today? (> deadline today))) + (warntime (org-entry-get (point) "APPT_WARNTIME" 'selective))) + (org-add-props item props + 'org-marker (org-agenda-new-marker pos) + 'org-hd-marker (org-agenda-new-marker (line-beginning-position)) + 'warntime warntime + 'level level + 'effort effort 'effort-minutes effort-minutes + 'ts-date deadline + 'urgency + ;; Adjust urgency to today reminders about deadlines. + ;; Overdue deadlines get the highest urgency + ;; increase, then imminent deadlines and eventually + ;; more distant deadlines. + (let ((adjust (if today? (- diff) 0))) + (+ adjust (org-get-priority item))) + 'priority (org-get-priority item) + 'todo-state todo-state + 'type (if upcoming? "upcoming-deadline" "deadline") + 'date (if upcoming? date deadline) + 'face (if done? 'org-agenda-done face) + 'undone-face face + 'done-face 'org-agenda-done) + (push item deadline-items))))))) + :next-re regexp + :fail-re regexp + :narrow t) (nreverse deadline-items))) (defun org-agenda-deadline-face (fraction) @@ -6656,429 +6546,257 @@ scheduled items with an hour specification like [h]h:mm." (let ((m (get-text-property 0 'org-hd-marker d))) (and m (marker-position m)))) deadlines)) - scheduled-items) - (goto-char (point-min)) - (if (org-element--cache-active-p) - (org-element-cache-map - (lambda (el) - (when (and (org-element-property :scheduled el) - (or (not with-hour) - (org-element-property - :hour-start - (org-element-property :scheduled el)) - (org-element-property - :hour-end - (org-element-property :scheduled el)))) - (goto-char (org-element-property :contents-begin el)) - (catch :skip - (org-agenda-skip el) - (let* ((s (substring (org-element-property - :raw-value - (org-element-property :scheduled el)) - 1 -1)) - (pos (save-excursion - (goto-char (org-element-property :contents-begin el)) - ;; We intentionally leave NOERROR - ;; argument in `re-search-forward' nil. If - ;; the search fails here, something went - ;; wrong and we are looking at - ;; non-matching headline. - (re-search-forward regexp (line-end-position)) - (1- (match-beginning 1)))) - (todo-state (org-element-property :todo-keyword el)) - (donep (eq 'done (org-element-property :todo-type el))) - (sexp? (eq 'diary - (org-element-property - :type (org-element-property :scheduled el)))) - ;; SCHEDULE is the scheduled date for the entry. It is - ;; either the bare date or the last repeat, according - ;; to `org-agenda-prefer-last-repeat'. - (schedule - (cond - (sexp? (org-agenda--timestamp-to-absolute s current)) - ((or (eq org-agenda-prefer-last-repeat t) - (member todo-state org-agenda-prefer-last-repeat)) - (org-agenda--timestamp-to-absolute - s today 'past (current-buffer) pos)) - (t (org-agenda--timestamp-to-absolute s)))) - ;; REPEAT is the future repeat closest from CURRENT, - ;; according to `org-agenda-show-future-repeats'. If - ;; the latter is nil, or if the time stamp has no - ;; repeat part, default to SCHEDULE. - (repeat - (cond - (sexp? schedule) - ((<= current today) schedule) - ((not org-agenda-show-future-repeats) schedule) - (t - (let ((base (if (eq org-agenda-show-future-repeats 'next) - (1+ today) - current))) - (org-agenda--timestamp-to-absolute - s base 'future (current-buffer) pos))))) - (diff (- current schedule)) - (warntime (get-text-property (point) 'org-appt-warntime)) - (pastschedp (< schedule today)) - (futureschedp (> schedule today)) - (habitp (and (fboundp 'org-is-habit-p) - (string= "habit" (org-element-property :STYLE el)))) - (suppress-delay - (let ((deadline (and org-agenda-skip-scheduled-delay-if-deadline - (org-element-property - :raw-value - (org-element-property :deadline el))))) - (cond - ((not deadline) nil) - ;; The current item has a deadline date, so - ;; evaluate its delay time. - ((integerp org-agenda-skip-scheduled-delay-if-deadline) - ;; Use global delay time. - (- org-agenda-skip-scheduled-delay-if-deadline)) - ((eq org-agenda-skip-scheduled-delay-if-deadline - 'post-deadline) - ;; Set delay to no later than DEADLINE. - (min (- schedule - (org-agenda--timestamp-to-absolute deadline)) - org-scheduled-delay-days)) - (t 0)))) - (ddays + scheduled-items) + (org-element-cache-map + (lambda (el) + (when (and (org-element-property :scheduled el) + ;; Only consider active timestamp values. + (memq (org-element-property + :type + (org-element-property :scheduled el)) + '(diary active active-range)) + (or (not with-hour) + (org-element-property + :hour-start + (org-element-property :scheduled el)) + (org-element-property + :hour-end + (org-element-property :scheduled el)))) + (goto-char (org-element-contents-begin el)) + (catch :skip + (org-agenda-skip el) + (let* ((s (substring (org-element-property + :raw-value + (org-element-property :scheduled el)) + 1 -1)) + (pos (save-excursion + (goto-char (org-element-contents-begin el)) + ;; We intentionally leave NOERROR + ;; argument in `re-search-forward' nil. If + ;; the search fails here, something went + ;; wrong and we are looking at + ;; non-matching headline. + (re-search-forward regexp (line-end-position)) + (1- (match-beginning 1)))) + (todo-state (org-element-property :todo-keyword el)) + (donep (eq 'done (org-element-property :todo-type el))) + (sexp? (eq 'diary + (org-element-property + :type (org-element-property :scheduled el)))) + ;; SCHEDULE is the scheduled date for the entry. It is + ;; either the bare date or the last repeat, according + ;; to `org-agenda-prefer-last-repeat'. + (schedule + (cond + (sexp? (org-agenda--timestamp-to-absolute s current)) + ((or (eq org-agenda-prefer-last-repeat t) + (member todo-state org-agenda-prefer-last-repeat)) + (org-agenda--timestamp-to-absolute + s today 'past (current-buffer) pos)) + (t (org-agenda--timestamp-to-absolute s)))) + ;; REPEAT is the future repeat closest from CURRENT, + ;; according to `org-agenda-show-future-repeats'. If + ;; the latter is nil, or if the time stamp has no + ;; repeat part, default to SCHEDULE. + (repeat + (cond + (sexp? schedule) + ((<= current today) schedule) + ((not org-agenda-show-future-repeats) schedule) + (t + (let ((base (if (eq org-agenda-show-future-repeats 'next) + (1+ today) + current))) + (org-agenda--timestamp-to-absolute + s base 'future (current-buffer) pos))))) + (diff (- current schedule)) + (warntime (org-entry-get (point) "APPT_WARNTIME" 'selective)) + (pastschedp (< schedule today)) + (futureschedp (> schedule today)) + (habitp (and (fboundp 'org-is-habit-p) + (string= "habit" (org-element-property :STYLE el)))) + (max-delay-days + (let ((deadline (and org-agenda-skip-scheduled-delay-if-deadline + (org-element-property + :raw-value + (org-element-property :deadline el))))) + (cond + ((not deadline) most-positive-fixnum) + ;; The current item has a deadline date, so + ;; evaluate its delay time. + ((integerp org-agenda-skip-scheduled-delay-if-deadline) + ;; Use global delay time. + (- org-agenda-skip-scheduled-delay-if-deadline)) + ((eq org-agenda-skip-scheduled-delay-if-deadline + 'post-deadline) + ;; Set delay to no later than DEADLINE. + (min (- schedule + (org-agenda--timestamp-to-absolute deadline)) + org-scheduled-delay-days)) + (t 0)))) + (delay-days + (cond + ;; Nullify delay when a repeater triggered already + ;; and the delay is of the form --Xd. + ((and (string-match-p "--[0-9]+[hdwmy]" s) + (> schedule (org-agenda--timestamp-to-absolute s))) + 0) + (t (min max-delay-days (org-get-wdays s t)))))) + ;; Display scheduled items at base date (SCHEDULE), today if + ;; scheduled before the current date, and at any repeat past + ;; today. However, skip delayed items and items that have + ;; been displayed for more than `org-scheduled-past-days'. + (unless (and todayp + habitp + (bound-and-true-p org-habit-show-all-today)) + (when (or (and (> delay-days 0) (< diff delay-days)) + (> diff (or (and habitp org-habit-scheduled-past-days) + org-scheduled-past-days)) + (> schedule current) + (and (/= current schedule) + (/= current today) + (/= current repeat))) + (throw :skip nil))) + ;; Possibly skip done tasks. + (when (and donep + (or org-agenda-skip-scheduled-if-done + (/= schedule current))) + (throw :skip nil)) + ;; Skip entry if it already appears as a deadline, per + ;; `org-agenda-skip-scheduled-if-deadline-is-shown'. This + ;; doesn't apply to habits. + (when (or org-agenda-skip-scheduled-repeats-after-deadline + ;; FIXME: Backwards-compatibility. + (eq org-agenda-skip-scheduled-if-deadline-is-shown + 'repeated-after-deadline)) + (let ((deadline + (time-to-days + (when (org-element-property :deadline el) + (org-time-string-to-time + (org-element-interpret-data + (org-element-property :deadline el))))))) + (when (and (or (<= (org-agenda--timestamp-to-absolute s) deadline) + (not (= schedule current))) + (> current deadline)) + (throw :skip nil)))) + (when (pcase org-agenda-skip-scheduled-if-deadline-is-shown + ((guard + (or (not (memq (line-beginning-position 0) deadline-pos)) + habitp)) + nil) + (`not-today pastschedp) + (`t t) + (_ nil)) + (throw :skip nil)) + ;; Skip habits if `org-habit-show-habits' is nil, or if we + ;; only show them for today. Also skip done habits. + (when (and habitp + (or donep + (not (bound-and-true-p org-habit-show-habits)) + (and (not todayp) + (bound-and-true-p + org-habit-show-habits-only-for-today)))) + (throw :skip nil)) + (save-excursion + (goto-char (org-element-begin el)) + (let* ((category (org-get-category)) + (effort (save-match-data + (or (get-text-property (point) 'effort) + (org-element-property (intern (concat ":" (upcase org-effort-property))) el)))) + (effort-minutes (when effort (save-match-data (org-duration-to-minutes effort)))) + (inherited-tags + (or (eq org-agenda-show-inherited-tags 'always) + (and (listp org-agenda-show-inherited-tags) + (memq 'agenda org-agenda-show-inherited-tags)) + (and (eq org-agenda-show-inherited-tags t) + (or (eq org-agenda-use-tag-inheritance t) + (memq 'agenda + org-agenda-use-tag-inheritance))))) + (tags (org-get-tags el (not inherited-tags))) + (level (make-string (org-element-property :level el) + ?\s)) + (head (save-excursion + (goto-char (org-element-begin el)) + (re-search-forward org-outline-regexp-bol) + (buffer-substring (point) (line-end-position)))) + (time (cond - ;; Nullify delay when a repeater triggered already - ;; and the delay is of the form --Xd. - ((and (string-match-p "--[0-9]+[hdwmy]" s) - (> schedule (org-agenda--timestamp-to-absolute s))) - 0) - (suppress-delay - (let ((org-scheduled-delay-days suppress-delay)) - (org-get-wdays s t t))) - (t (org-get-wdays s t))))) - ;; Display scheduled items at base date (SCHEDULE), today if - ;; scheduled before the current date, and at any repeat past - ;; today. However, skip delayed items and items that have - ;; been displayed for more than `org-scheduled-past-days'. - (unless (and todayp - habitp - (bound-and-true-p org-habit-show-all-today)) - (when (or (and (> ddays 0) (< diff ddays)) - (> diff (or (and habitp org-habit-scheduled-past-days) - org-scheduled-past-days)) - (> schedule current) - (and (/= current schedule) - (/= current today) - (/= current repeat))) - (throw :skip nil))) - ;; Possibly skip done tasks. - (when (and donep - (or org-agenda-skip-scheduled-if-done - (/= schedule current))) - (throw :skip nil)) - ;; Skip entry if it already appears as a deadline, per - ;; `org-agenda-skip-scheduled-if-deadline-is-shown'. This - ;; doesn't apply to habits. - (when (pcase org-agenda-skip-scheduled-if-deadline-is-shown - ((guard - (or (not (memq (line-beginning-position 0) deadline-pos)) - habitp)) - nil) - (`repeated-after-deadline - (let ((deadline (time-to-days - (when (org-element-property :deadline el) - (org-time-string-to-time - (org-element-property :deadline el)))))) - (and (<= schedule deadline) (> current deadline)))) - (`not-today pastschedp) - (`t t) - (_ nil)) - (throw :skip nil)) - ;; Skip habits if `org-habit-show-habits' is nil, or if we - ;; only show them for today. Also skip done habits. - (when (and habitp - (or donep - (not (bound-and-true-p org-habit-show-habits)) - (and (not todayp) - (bound-and-true-p - org-habit-show-habits-only-for-today)))) - (throw :skip nil)) - (save-excursion - (goto-char (org-element-property :begin el)) - (let* ((category (org-get-category)) - (effort (save-match-data - (or (get-text-property (point) 'effort) - (org-element-property (intern (concat ":" (upcase org-effort-property))) el)))) - (effort-minutes (when effort (save-match-data (org-duration-to-minutes effort)))) - (inherited-tags - (or (eq org-agenda-show-inherited-tags 'always) - (and (listp org-agenda-show-inherited-tags) - (memq 'agenda org-agenda-show-inherited-tags)) - (and (eq org-agenda-show-inherited-tags t) - (or (eq org-agenda-use-tag-inheritance t) - (memq 'agenda - org-agenda-use-tag-inheritance))))) - (tags (org-get-tags el (not inherited-tags))) - (level (make-string (org-element-property :level el) - ?\s)) - (head (save-excursion - (goto-char (org-element-property :begin el)) - (re-search-forward org-outline-regexp-bol) - (buffer-substring (point) (line-end-position)))) - (time - (cond - ;; No time of day designation if it is only a - ;; reminder, except for habits, which always show - ;; the time of day. Habits are an exception - ;; because if there is a time of day, that is - ;; interpreted to mean they should usually happen - ;; then, even if doing the habit was missed. - ((and - (not habitp) - (/= current schedule) - (/= current repeat)) - nil) - ((string-match " \\([012]?[0-9]:[0-9][0-9]\\)" s) - (concat (substring s (match-beginning 1)) " ")) - (t 'time))) - (item - (org-agenda-format-item - (pcase-let ((`(,first ,past) org-agenda-scheduled-leaders)) - ;; Show a reminder of a past scheduled today. - (if (and todayp pastschedp) - (format past diff) - first)) - (org-add-props head nil - 'effort effort - 'effort-minutes effort-minutes) - level category tags time nil habitp)) - (face (cond ((and (not habitp) pastschedp) - 'org-scheduled-previously) - ((and habitp futureschedp) - 'org-agenda-done) - (todayp 'org-scheduled-today) - (t 'org-scheduled))) - (habitp (and habitp (org-habit-parse-todo (org-element-property :begin el))))) - (org-add-props item props - 'undone-face face - 'face (if donep 'org-agenda-done face) - 'org-marker (org-agenda-new-marker pos) - 'org-hd-marker (org-agenda-new-marker (line-beginning-position)) - 'type (if pastschedp "past-scheduled" "scheduled") - 'date (if pastschedp schedule date) - 'ts-date schedule - 'warntime warntime - 'level level - 'effort effort 'effort-minutes effort-minutes - 'priority (if habitp (org-habit-get-priority habitp) - (+ 99 diff (org-get-priority item))) - 'org-habit-p habitp - 'todo-state todo-state) - (push item scheduled-items))))))) - :next-re regexp - :fail-re regexp - :narrow t) - (while (re-search-forward regexp nil t) - (catch :skip - (unless (save-match-data (org-at-planning-p)) (throw :skip nil)) - (org-agenda-skip) - (let* ((s (match-string 1)) - (pos (1- (match-beginning 1))) - (todo-state (save-match-data (org-get-todo-state))) - (donep (member todo-state org-done-keywords)) - (sexp? (string-prefix-p "%%" s)) - ;; SCHEDULE is the scheduled date for the entry. It is - ;; either the bare date or the last repeat, according - ;; to `org-agenda-prefer-last-repeat'. - (schedule - (cond - (sexp? (org-agenda--timestamp-to-absolute s current)) - ((or (eq org-agenda-prefer-last-repeat t) - (member todo-state org-agenda-prefer-last-repeat)) - (org-agenda--timestamp-to-absolute - s today 'past (current-buffer) pos)) - (t (org-agenda--timestamp-to-absolute s)))) - ;; REPEAT is the future repeat closest from CURRENT, - ;; according to `org-agenda-show-future-repeats'. If - ;; the latter is nil, or if the time stamp has no - ;; repeat part, default to SCHEDULE. - (repeat - (cond - (sexp? schedule) - ((<= current today) schedule) - ((not org-agenda-show-future-repeats) schedule) - (t - (let ((base (if (eq org-agenda-show-future-repeats 'next) - (1+ today) - current))) - (org-agenda--timestamp-to-absolute - s base 'future (current-buffer) pos))))) - (diff (- current schedule)) - (warntime (get-text-property (point) 'org-appt-warntime)) - (pastschedp (< schedule today)) - (futureschedp (> schedule today)) - (habitp (and (fboundp 'org-is-habit-p) (org-is-habit-p))) - (suppress-delay - (let ((deadline (and org-agenda-skip-scheduled-delay-if-deadline - (org-entry-get nil "DEADLINE")))) - (cond - ((not deadline) nil) - ;; The current item has a deadline date, so - ;; evaluate its delay time. - ((integerp org-agenda-skip-scheduled-delay-if-deadline) - ;; Use global delay time. - (- org-agenda-skip-scheduled-delay-if-deadline)) - ((eq org-agenda-skip-scheduled-delay-if-deadline - 'post-deadline) - ;; Set delay to no later than DEADLINE. - (min (- schedule - (org-agenda--timestamp-to-absolute deadline)) - org-scheduled-delay-days)) - (t 0)))) - (ddays - (cond - ;; Nullify delay when a repeater triggered already - ;; and the delay is of the form --Xd. - ((and (string-match-p "--[0-9]+[hdwmy]" s) - (> schedule (org-agenda--timestamp-to-absolute s))) - 0) - (suppress-delay - (let ((org-scheduled-delay-days suppress-delay)) - (org-get-wdays s t t))) - (t (org-get-wdays s t))))) - ;; Display scheduled items at base date (SCHEDULE), today if - ;; scheduled before the current date, and at any repeat past - ;; today. However, skip delayed items and items that have - ;; been displayed for more than `org-scheduled-past-days'. - (unless (and todayp - habitp - (bound-and-true-p org-habit-show-all-today)) - (when (or (and (> ddays 0) (< diff ddays)) - (> diff (or (and habitp org-habit-scheduled-past-days) - org-scheduled-past-days)) - (> schedule current) - (and (/= current schedule) - (/= current today) - (/= current repeat))) - (throw :skip nil))) - ;; Possibly skip done tasks. - (when (and donep - (or org-agenda-skip-scheduled-if-done - (/= schedule current))) - (throw :skip nil)) - ;; Skip entry if it already appears as a deadline, per - ;; `org-agenda-skip-scheduled-if-deadline-is-shown'. This - ;; doesn't apply to habits. - (when (pcase org-agenda-skip-scheduled-if-deadline-is-shown - ((guard - (or (not (memq (line-beginning-position 0) deadline-pos)) - habitp)) - nil) - (`repeated-after-deadline - (let ((deadline (time-to-days - (org-get-deadline-time (point))))) - (and (<= schedule deadline) (> current deadline)))) - (`not-today pastschedp) - (`t t) - (_ nil)) - (throw :skip nil)) - ;; Skip habits if `org-habit-show-habits' is nil, or if we - ;; only show them for today. Also skip done habits. - (when (and habitp - (or donep - (not (bound-and-true-p org-habit-show-habits)) - (and (not todayp) - (bound-and-true-p - org-habit-show-habits-only-for-today)))) - (throw :skip nil)) - (save-excursion - (re-search-backward "^\\*+[ \t]+" nil t) - (goto-char (match-end 0)) - (let* ((category (org-get-category)) - (effort (save-match-data (or (get-text-property (point) 'effort) - (org-entry-get (point) org-effort-property)))) - (effort-minutes (when effort (save-match-data (org-duration-to-minutes effort)))) - (inherited-tags - (or (eq org-agenda-show-inherited-tags 'always) - (and (listp org-agenda-show-inherited-tags) - (memq 'agenda org-agenda-show-inherited-tags)) - (and (eq org-agenda-show-inherited-tags t) - (or (eq org-agenda-use-tag-inheritance t) - (memq 'agenda - org-agenda-use-tag-inheritance))))) - (tags (org-get-tags nil (not inherited-tags))) - (level (make-string (org-reduced-level (org-outline-level)) - ?\s)) - (head (buffer-substring (point) (line-end-position))) - (time - (cond - ;; No time of day designation if it is only a - ;; reminder, except for habits, which always show - ;; the time of day. Habits are an exception - ;; because if there is a time of day, that is - ;; interpreted to mean they should usually happen - ;; then, even if doing the habit was missed. - ((and - (not habitp) - (/= current schedule) - (/= current repeat)) - nil) - ((string-match " \\([012]?[0-9]:[0-9][0-9]\\)" s) - (concat (substring s (match-beginning 1)) " ")) - (t 'time))) - (item - (org-agenda-format-item - (pcase-let ((`(,first ,past) org-agenda-scheduled-leaders)) - ;; Show a reminder of a past scheduled today. - (if (and todayp pastschedp) - (format past diff) - first)) - (org-add-props head nil - 'effort effort - 'effort-minutes effort-minutes) - level category tags time nil habitp)) - (face (cond ((and (not habitp) pastschedp) - 'org-scheduled-previously) - ((and habitp futureschedp) - 'org-agenda-done) - (todayp 'org-scheduled-today) - (t 'org-scheduled))) - (habitp (and habitp (org-habit-parse-todo)))) - (org-add-props item props - 'undone-face face - 'face (if donep 'org-agenda-done face) - 'org-marker (org-agenda-new-marker pos) - 'org-hd-marker (org-agenda-new-marker (line-beginning-position)) - 'type (if pastschedp "past-scheduled" "scheduled") - 'date (if pastschedp schedule date) - 'ts-date schedule - 'warntime warntime - 'level level - 'effort effort 'effort-minutes effort-minutes - 'priority (if habitp (org-habit-get-priority habitp) + ;; No time of day designation if it is only a + ;; reminder, except for habits, which always show + ;; the time of day. Habits are an exception + ;; because if there is a time of day, that is + ;; interpreted to mean they should usually happen + ;; then, even if doing the habit was missed. + ((and + (not habitp) + (/= current schedule) + (/= current repeat)) + nil) + ((string-match " \\([012]?[0-9]:[0-9][0-9]\\)" s) + (concat (substring s (match-beginning 1)) " ")) + (t 'time))) + (item + (org-agenda-format-item + (pcase-let ((`(,first ,past) org-agenda-scheduled-leaders)) + ;; Show a reminder of a past scheduled today. + (if (and todayp pastschedp) + (format past diff) + first)) + (org-add-props head nil + 'effort effort + 'effort-minutes effort-minutes) + level category tags time nil habitp)) + (face (cond ((and (not habitp) pastschedp) + 'org-scheduled-previously) + ((and habitp futureschedp) + 'org-agenda-done) + (todayp 'org-scheduled-today) + (t 'org-scheduled))) + (habitp (and habitp (org-habit-parse-todo (org-element-begin el))))) + (org-add-props item props + 'undone-face face + 'face (if donep 'org-agenda-done face) + 'org-marker (org-agenda-new-marker pos) + 'org-hd-marker (org-agenda-new-marker (line-beginning-position)) + 'type (if pastschedp "past-scheduled" "scheduled") + 'date (if pastschedp schedule date) + 'ts-date schedule + 'warntime warntime + 'level level + 'effort effort 'effort-minutes effort-minutes + 'urgency (if habitp (org-habit-get-urgency habitp) (+ 99 diff (org-get-priority item))) - 'org-habit-p habitp - 'todo-state todo-state) - (push item scheduled-items))))))) + 'priority (org-get-priority item) + 'org-habit-p habitp + 'todo-state todo-state) + (push item scheduled-items))))))) + :next-re regexp + :fail-re regexp + :narrow t) (nreverse scheduled-items))) (defun org-agenda-get-blocks () "Return the date-range information for agenda display." (with-no-warnings (defvar date)) - (let* ((props (list 'face nil - 'org-not-done-regexp org-not-done-regexp + (let* ((props (list 'org-not-done-regexp org-not-done-regexp 'org-todo-regexp org-todo-regexp 'org-complex-heading-regexp org-complex-heading-regexp 'mouse-face 'highlight 'help-echo (format "mouse-2 or RET jump to org file %s" (abbreviate-file-name buffer-file-name)))) - (regexp org-tr-regexp) + (regexp (if org-agenda-include-inactive-timestamps + org-tr-regexp-both org-tr-regexp)) (d0 (calendar-absolute-from-gregorian date)) - marker hdmarker ee txt d1 d2 s1 s2 category - level todo-state tags pos head donep inherited-tags - effort effort-minutes) + face marker hdmarker ee txt d1 d2 s1 s2 category level + todo-state tags pos head donep inherited-tags effort + effort-minutes inactive?) (goto-char (point-min)) (while (re-search-forward regexp nil t) (catch :skip (org-agenda-skip) (setq pos (point)) + (setq inactive? (eq ?\[ (char-after (match-beginning 0)))) (let ((start-time (match-string 1)) (end-time (match-string 2))) (setq s1 (match-string 1) @@ -7111,6 +6829,9 @@ scheduled items with an hour specification like [h]h:mm." (setq donep (member todo-state org-done-keywords)) (when (and donep org-agenda-skip-timestamp-if-done) (throw :skip t)) + (setq face (if (= d1 d2) + 'org-agenda-calendar-event + 'org-agenda-calendar-daterange)) (setq marker (org-agenda-new-marker (point)) category (org-get-category)) (setq effort (save-match-data (or (get-text-property (point) 'effort) @@ -7139,34 +6860,32 @@ scheduled items with an hour specification like [h]h:mm." "<" (regexp-quote s2) ".*?>") nil))) (setq txt (org-agenda-format-item - (format - (nth (if (= d1 d2) 0 1) - org-agenda-timerange-leaders) - (1+ (- d0 d1)) (1+ (- d2 d1))) + (concat + (when inactive? org-agenda-inactive-leader) + (format + (nth (if (= d1 d2) 0 1) + org-agenda-timerange-leaders) + (1+ (- d0 d1)) (1+ (- d2 d1)))) (org-add-props head nil 'effort effort 'effort-minutes effort-minutes) level category tags - (save-match-data - (let ((hhmm1 (and (string-match org-ts-regexp1 s1) - (match-string 6 s1))) - (hhmm2 (and (string-match org-ts-regexp1 s2) - (match-string 6 s2)))) - (cond ((string= hhmm1 hhmm2) - (concat "<" start-time ">--<" end-time ">")) - ((and (= d1 d0) (= d2 d0)) - (concat "<" start-time ">--<" end-time ">")) - ((= d1 d0) - (concat "<" start-time ">")) - ((= d2 d0) - (concat "<" end-time ">"))))) + (cond + ((and (= d1 d0) (= d2 d0)) + (concat "<" start-time ">--<" end-time ">")) + ((= d1 d0) + (concat "<" start-time ">")) + ((= d2 d0) + (concat "<" end-time ">"))) remove-re)))) (org-add-props txt props + 'face face 'org-marker marker 'org-hd-marker hdmarker 'type "block" 'date date 'level level 'effort effort 'effort-minutes effort-minutes 'todo-state todo-state + 'urgency (org-get-priority txt) 'priority (org-get-priority txt)) (push txt ee)))) (goto-char pos))) @@ -7249,6 +6968,7 @@ Any match of REMOVE-RE will be removed from TXT." (file-name-sans-extension (file-name-nondirectory buffer-file-name)) ""))) + (full-category category) (category-icon (org-agenda-get-category-icon category)) (category-icon (if category-icon (propertize " " 'display category-icon) @@ -7261,7 +6981,13 @@ Any match of REMOVE-RE will be removed from TXT." time (ts (when dotime (concat (if (stringp dotime) dotime "") - (and org-agenda-search-headline-for-time txt)))) + (and org-agenda-search-headline-for-time + ;; Do not search inside + ;; timestamps. They are handled + ;; separately. + (replace-regexp-in-string + org-ts-regexp-both "" + txt))))) (time-of-day (and dotime (org-get-time-of-day ts))) stamp plain s0 s1 s2 rtn srp l duration breadcrumbs) @@ -7326,11 +7052,21 @@ Any match of REMOVE-RE will be removed from TXT." ;; Prepare the variables needed in the eval of the compiled format (when org-prefix-has-breadcrumbs - (setq breadcrumbs (org-with-point-at (org-get-at-bol 'org-marker) - (let ((s (org-format-outline-path (org-get-outline-path) - (1- (frame-width)) - nil org-agenda-breadcrumbs-separator))) - (if (equal "" s) "" (concat s org-agenda-breadcrumbs-separator)))))) + (setq breadcrumbs + ;; When called from Org buffer, remain in position. + ;; When called from Agenda buffer, jump to headline position first. + (org-with-point-at (org-get-at-bol 'org-marker) + (let ((s (if (derived-mode-p 'org-mode) + (org-format-outline-path (org-get-outline-path) + (1- (frame-width)) + nil org-agenda-breadcrumbs-separator) + ;; Not in Org buffer. This can happen, + ;; for example, in + ;; `org-agenda-add-time-grid-maybe' where + ;; time grid does not correspond to a + ;; particular heading. + ""))) + (if (equal "" s) "" (concat s org-agenda-breadcrumbs-separator)))))) (setq time (cond (s2 (concat (org-agenda-time-of-day-to-ampm-maybe s1) "-" (org-agenda-time-of-day-to-ampm-maybe s2) @@ -7360,7 +7096,9 @@ Any match of REMOVE-RE will be removed from TXT." ;; And finally add the text properties (remove-text-properties 0 (length rtn) '(line-prefix t wrap-prefix t) rtn) (org-add-props rtn nil - 'org-category category + ;; CATEGORY might be truncated. Store the full category in + ;; the properties. + 'org-category full-category 'tags tags 'org-priority-highest org-priority-highest 'org-priority-lowest org-priority-lowest @@ -7427,7 +7165,11 @@ TODAYP is t when the current agenda view is on today." (gridtimes (nth 1 org-agenda-time-grid)) (req (car org-agenda-time-grid)) (remove (member 'remove-match req)) - new time) + new time + ;; We abuse `org-agenda-format-item' to format grid lines + ;; here. Prevent it from adding default duration, if any + ;; to the grid lines. + (org-agenda-default-appointment-duration nil)) (when (and (member 'require-timed req) (not have)) ;; don't show empty grid (throw 'exit list)) @@ -7528,7 +7270,7 @@ and stored in the variable `org-prefix-format-compiled'." org-agenda-sorting-strategy (or (cdr (assq key org-agenda-sorting-strategy)) (cdr (assq 'agenda org-agenda-sorting-strategy)) - '(time-up category-keep priority-down))))) + '(time-up category-keep urgency-down))))) (defun org-get-time-of-day (s &optional string) "Check string S for a time of day. @@ -7681,7 +7423,7 @@ The optional argument TYPE tells the agenda type." re) (if (eq x 'line) (save-excursion - (beginning-of-line 1) + (forward-line 0) (setq re (org-get-at-bol 'org-todo-regexp)) (goto-char (or (text-property-any (line-beginning-position) (line-end-position) @@ -7753,8 +7495,8 @@ The optional argument TYPE tells the agenda type." "Compare the string values of categories of strings A and B." (let ((ca (or (get-text-property (1- (length a)) 'org-category a) "")) (cb (or (get-text-property (1- (length b)) 'org-category b) ""))) - (cond ((string-lessp ca cb) -1) - ((string-lessp cb ca) +1)))) + (cond ((org-string< ca cb) -1) + ((org-string< cb ca) +1)))) (defsubst org-cmp-todo-state (a b) "Compare the todo states of strings A and B." @@ -7800,8 +7542,8 @@ The optional argument TYPE tells the agenda type." (cond ((not (or ta tb)) nil) ((not ta) +1) ((not tb) -1) - ((string-lessp ta tb) -1) - ((string-lessp tb ta) +1)))) + ((org-string< ta tb) -1) + ((org-string< tb ta) +1)))) (defsubst org-cmp-tag (a b) "Compare the string values of the first tags of A and B." @@ -7810,8 +7552,8 @@ The optional argument TYPE tells the agenda type." (cond ((not (or ta tb)) nil) ((not ta) +1) ((not tb) -1) - ((string-lessp ta tb) -1) - ((string-lessp tb ta) +1)))) + ((funcall (or org-tags-sort-function #'org-string<) ta tb) -1) + ((funcall (or org-tags-sort-function #'org-string<) tb ta) +1)))) (defsubst org-cmp-time (a b) "Compare the time-of-day values of strings A and B." @@ -7874,6 +7616,9 @@ their type." (priority-up (and (org-em 'priority-up 'priority-down ss) (org-cmp-values a b 'priority))) (priority-down (if priority-up (- priority-up) nil)) + (urgency-up (and (org-em 'urgency-up 'urgency-down ss) + (org-cmp-values a b 'urgency))) + (urgency-down (if urgency-up (- urgency-up) nil)) (effort-up (and (org-em 'effort-up 'effort-down ss) (org-cmp-effort a b))) (effort-down (if effort-up (- effort-up) nil)) @@ -8450,10 +8195,12 @@ which see." (confirm (lambda (x) (stringp x))) (prefix "") (operator "") - table) + table + begin) (when (string-match "^\\(.*\\([-+<>=]\\)\\)\\([^-+<>=]*\\)$" string) (setq prefix (match-string 1 string) operator (match-string 2 string) + begin (match-beginning 3) string (match-string 3 string))) (cond ((member operator '("+" "-" "" nil)) @@ -8470,6 +8217,11 @@ which see." (pcase flag (`t (all-completions string table confirm)) (`lambda (assoc string table)) ;exact match? + (`(boundaries . ,suffix) + (let ((end (if (string-match "[-+<>=]" suffix) + (match-string 0 suffix) + (length suffix)))) + `(boundaries ,(or begin 0) . ,end))) (`nil (pcase (try-completion string table confirm) ((and completion (pred stringp)) @@ -8762,7 +8514,7 @@ grouptags." (txt (or (org-get-at-bol 'txt) ""))) (unless (eval org-agenda-filter-form t) (org-agenda-filter-hide-line type)))) - (beginning-of-line 2))) + (forward-line 1))) (when (get-char-property (point) 'invisible) (ignore-errors (org-agenda-previous-line)))) @@ -8777,7 +8529,7 @@ grouptags." (when (and tophl (funcall (if negative 'identity 'not) (string= hl tophl))) (org-agenda-filter-hide-line 'top-headline))) - (beginning-of-line 2))) + (forward-line 1))) (when (get-char-property (point) 'invisible) (org-agenda-previous-line)) (setq org-agenda-top-headline-filter hl @@ -8847,6 +8599,14 @@ Negative selection means regexp must not match for selection of an entry." (org-agenda-redo)) (message "Display now includes inactive timestamps as well")) ((eq org-agenda-type 'search) + ;; Previous calls to `org-agenda-manipulate-query' could already + ;; add trailing text to the query. Prevent duplicating it. + ;; Trim the trailing spaces and +/. + (setq org-agenda-query-string + (replace-regexp-in-string + (rx (or (1+ " ") (seq (1+ " ") (any "+-") (opt "{}"))) eos) + "" + org-agenda-query-string)) (org-add-to-string 'org-agenda-query-string (if org-agenda-last-search-view-search-was-boolean @@ -8885,31 +8645,31 @@ See also: (list (let ((org-read-date-prefer-future org-agenda-jump-prefer-future)) (org-read-date)))) + (org-agenda-check-type t 'agenda) (let* ((day (time-to-days (org-time-string-to-time date))) - (org-agenda-sticky-orig org-agenda-sticky) - (org-agenda-buffer-tmp-name (buffer-name)) - (args (get-text-property (min (1- (point-max)) (point)) 'org-last-args)) - (0-arg (or current-prefix-arg (car args))) - (2-arg (nth 2 args)) - (with-hour-p (nth 4 org-agenda-redo-command)) - (newcmd (list 'org-agenda-list 0-arg date - (org-agenda-span-to-ndays - 2-arg (org-time-string-to-absolute date)) - with-hour-p)) - (newargs (cdr newcmd)) - (inhibit-read-only t) - org-agenda-sticky) - (if (not (org-agenda-check-type t 'agenda)) - (error "Not available in non-agenda views") - (add-text-properties (point-min) (point-max) - `(org-redo-cmd ,newcmd org-last-args ,newargs)) - (org-agenda-redo) - (goto-char (point-min)) - (while (not (or (= (or (get-text-property (point) 'day) 0) day) - (save-excursion (move-beginning-of-line 2) (eobp)))) - (move-beginning-of-line 2)) - (setq org-agenda-sticky org-agenda-sticky-orig - org-agenda-this-buffer-is-sticky org-agenda-sticky)))) + (org-agenda-sticky-orig org-agenda-sticky) + (org-agenda-buffer-tmp-name (buffer-name)) + (args (get-text-property (min (1- (point-max)) (point)) + 'org-last-args)) + (0-arg (or current-prefix-arg (car args))) + (2-arg (nth 2 args)) + (with-hour-p (nth 4 org-agenda-redo-command)) + (newcmd (list 'org-agenda-list 0-arg date + (org-agenda-span-to-ndays + 2-arg (org-time-string-to-absolute date)) + with-hour-p)) + (newargs (cdr newcmd)) + (inhibit-read-only t) + org-agenda-sticky) + (add-text-properties (point-min) (point-max) + `(org-redo-cmd ,newcmd org-last-args ,newargs)) + (org-agenda-redo) + (goto-char (point-min)) + (while (not (or (= (or (get-text-property (point) 'day) 0) day) + (save-excursion (move-beginning-of-line 2) (eobp)))) + (move-beginning-of-line 2)) + (setq org-agenda-sticky org-agenda-sticky-orig + org-agenda-this-buffer-is-sticky org-agenda-sticky))) (defun org-agenda-goto-today () "Go to today's date in the agenda buffer. @@ -9187,7 +8947,7 @@ so that the date SD will be in that range." "Jump to the next line indicating a date in agenda buffer." (interactive "p") (org-agenda-check-type t 'agenda) - (beginning-of-line 1) + (forward-line 0) ;; This does not work if user makes date format that starts with a blank (when (looking-at-p "^\\S-") (forward-char 1)) (unless (re-search-forward "^\\S-" nil t arg) @@ -9199,7 +8959,7 @@ so that the date SD will be in that range." "Jump to the previous line indicating a date in agenda buffer." (interactive "p") (org-agenda-check-type t 'agenda) - (beginning-of-line 1) + (forward-line 0) (unless (re-search-backward "^\\S-" nil t arg) (error "No previous date before this line in this buffer"))) @@ -9433,7 +9193,7 @@ When called with a prefix argument, include all archive files as well." (org-agenda-do-context-action)) (defun org-agenda-previous-line () - "Move cursor to the previous line, and show if follow-mode is active." + "Move cursor to the previous line, and show if follow mode is active." (interactive) (call-interactively 'previous-line) (org-agenda-do-context-action)) @@ -9467,7 +9227,8 @@ When called with a prefix argument, include all archive files as well." (when (and (markerp m) (marker-buffer m)) (and org-agenda-follow-mode (if org-agenda-follow-indirect - (org-agenda-tree-to-indirect-buffer nil) + (let ((org-indirect-buffer-display 'other-window)) + (org-agenda-tree-to-indirect-buffer nil)) (org-agenda-show))) (and org-agenda-show-outline-path (org-with-point-at m (org-display-outline-path org-agenda-show-outline-path)))))) @@ -9488,7 +9249,6 @@ When called with a prefix argument, include all archive files as well." (org-agenda-error))) (buffer (marker-buffer marker)) (pos (marker-position marker))) - ;; FIXME: use `org-switch-to-buffer-other-window'? (switch-to-buffer-other-window buffer) (widen) (push-mark) @@ -9560,20 +9320,17 @@ Pass ARG, FORCE-ARG, DELETE and BODY to `org-agenda-do-in-region'." (marker (or (org-get-at-bol 'org-marker) (org-agenda-error))) (buffer (marker-buffer marker)) - (pos (marker-position marker)) (type (org-get-at-bol 'type)) dbeg dend (n 0)) (org-with-remote-undo buffer - (with-current-buffer buffer - (save-excursion - (goto-char pos) - (if (and (derived-mode-p 'org-mode) (not (member type '("sexp")))) - (setq dbeg (progn (org-back-to-heading t) (point)) - dend (org-end-of-subtree t t)) - (setq dbeg (line-beginning-position) - dend (min (point-max) (1+ (line-end-position))))) - (goto-char dbeg) - (while (re-search-forward "^[ \t]*\\S-" dend t) (setq n (1+ n))))) + (org-with-point-at marker + (if (and (derived-mode-p 'org-mode) (not (member type '("sexp")))) + (setq dbeg (progn (org-back-to-heading t) (point)) + dend (org-end-of-subtree t t)) + (setq dbeg (line-beginning-position) + dend (min (point-max) (1+ (line-end-position))))) + (goto-char dbeg) + (while (re-search-forward "^[ \t]*\\S-" dend t) (setq n (1+ n)))) (when (or (eq t org-agenda-confirm-kill) (and (numberp org-agenda-confirm-kill) (> n org-agenda-confirm-kill))) @@ -9590,7 +9347,7 @@ Pass ARG, FORCE-ARG, DELETE and BODY to `org-agenda-do-in-region'." (set-window-configuration win-conf)))) (let ((org-agenda-buffer-name bufname-orig)) (org-remove-subtree-entries-from-agenda buffer dbeg dend)) - (with-current-buffer buffer (delete-region dbeg dend)) + (org-with-point-at marker (delete-region dbeg dend)) (message "Agenda item and source killed"))))) (defvar org-archive-default-command) ; defined in org-archive.el @@ -9653,26 +9410,26 @@ Pass ARG, FORCE-ARG, DELETE and BODY to `org-agenda-do-in-region'." The subtree is the one in buffer BUF, starting at BEG and ending at END. If this information is not given, the function uses the tree at point." (let ((buf (or buf (current-buffer))) m p) - (save-excursion - (unless (and beg end) - (org-back-to-heading t) - (setq beg (point)) - (org-end-of-subtree t) - (setq end (point))) - (set-buffer (get-buffer org-agenda-buffer-name)) - (save-excursion - (goto-char (point-max)) - (beginning-of-line 1) - (while (not (bobp)) - (when (and (setq m (org-get-at-bol 'org-marker)) - (equal buf (marker-buffer m)) - (setq p (marker-position m)) - (>= p beg) - (< p end)) - (let ((inhibit-read-only t)) - (delete-region (line-beginning-position) - (1+ (line-end-position))))) - (beginning-of-line 0)))))) + (org-with-wide-buffer + (unless (and beg end) + (org-back-to-heading t) + (setq beg (point)) + (org-end-of-subtree t) + (setq end (point))) + (set-buffer (get-buffer org-agenda-buffer-name)) + (save-excursion + (goto-char (point-max)) + (forward-line 0) + (while (not (bobp)) + (when (and (setq m (org-get-at-bol 'org-marker)) + (equal buf (marker-buffer m)) + (setq p (marker-position m)) + (>= p beg) + (< p end)) + (let ((inhibit-read-only t)) + (delete-region (line-beginning-position) + (1+ (line-end-position))))) + (forward-line -1)))))) (defun org-agenda-refile (&optional goto rfloc no-update) "Refile the item at point. @@ -9743,9 +9500,8 @@ It also looks at the text of the entry itself." (when (search-forward l nil lkend) (goto-char (match-beginning 0)) (org-open-at-point))) - ;; This is an internal link, widen the buffer - ;; FIXME: use `org-switch-to-buffer-other-window'? (switch-to-buffer-other-window buffer) + ;; This is an internal link, widen the buffer (widen) (goto-char marker) (when (search-forward l nil lkend) @@ -9754,7 +9510,7 @@ It also looks at the text of the entry itself." lk)) ((or (org-in-regexp (concat "\\(" org-link-bracket-re "\\)")) (save-excursion - (beginning-of-line 1) + (forward-line 0) (looking-at (concat ".*?\\(" org-link-bracket-re "\\)")))) (org-link-open-from-string (match-string 1))) (t (message "No link to open here"))))) @@ -9782,7 +9538,8 @@ displayed Org file fills the frame." (pos (marker-position marker))) (unless buffer (user-error "Trying to switch to non-existent buffer")) (pop-to-buffer-same-window buffer) - (when delete-other-windows (delete-other-windows)) + (when delete-other-windows + (display-buffer (current-buffer) '(org-display-buffer-full-frame))) (widen) (goto-char pos) (when (derived-mode-p 'org-mode) @@ -9941,27 +9698,6 @@ With a `\\[universal-argument]' prefix, make a separate frame for this tree, \ i.e. don't use the dedicated frame." (interactive "P") - (if current-prefix-arg - (org-agenda-do-tree-to-indirect-buffer arg) - (let ((agenda-buffer (buffer-name)) - (agenda-window (selected-window)) - (indirect-window - (and org-last-indirect-buffer - (get-buffer-window org-last-indirect-buffer)))) - (save-window-excursion (org-agenda-do-tree-to-indirect-buffer arg)) - (unless (or (eq org-indirect-buffer-display 'new-frame) - (eq org-indirect-buffer-display 'dedicated-frame)) - (unwind-protect - (unless (and indirect-window (window-live-p indirect-window)) - (setq indirect-window (split-window agenda-window))) - (and indirect-window (select-window indirect-window)) - (switch-to-buffer org-last-indirect-buffer :norecord) - (fit-window-to-buffer indirect-window))) - (select-window (get-buffer-window agenda-buffer)) - (setq org-agenda-last-indirect-buffer org-last-indirect-buffer)))) - -(defun org-agenda-do-tree-to-indirect-buffer (arg) - "Same as `org-agenda-tree-to-indirect-buffer' without saving window." (org-agenda-check-no-diary) (let* ((marker (or (org-get-at-bol 'org-marker) (org-agenda-error))) @@ -9970,7 +9706,8 @@ the dedicated frame." (with-current-buffer buffer (save-excursion (goto-char pos) - (org-tree-to-indirect-buffer arg))))) + (org-tree-to-indirect-buffer arg)))) + (setq org-agenda-last-indirect-buffer org-last-indirect-buffer)) (defvar org-last-heading-marker (make-marker) "Marker pointing to the headline that last changed its TODO state @@ -10021,14 +9758,14 @@ the same tree node, and the headline of the tree node in the Org file." (setq newhead (org-get-heading)) (when (and org-agenda-headline-snapshot-before-repeat (not (equal org-agenda-headline-snapshot-before-repeat - newhead)) + newhead)) todayp) (setq newhead org-agenda-headline-snapshot-before-repeat just-one t)) (save-excursion (org-back-to-heading) (move-marker org-last-heading-marker (point)))) - (beginning-of-line 1) + (forward-line 0) (save-window-excursion (org-agenda-change-all-lines newhead hdmarker 'fixface just-one)) (when (bound-and-true-p org-clock-out-when-done) @@ -10073,7 +9810,7 @@ If FORCE-TAGS is non-nil, the car of it returns the new tags." effort effort-minutes) ;; pl (save-excursion (goto-char (point-max)) - (beginning-of-line 1) + (forward-line 0) (while (not finish) (setq finish (bobp)) (when (and (setq m (org-get-at-bol 'org-hd-marker)) @@ -10094,15 +9831,15 @@ If FORCE-TAGS is non-nil, the car of it returns the new tags." (with-current-buffer (marker-buffer hdmarker) (org-with-wide-buffer (org-agenda-format-item extra - (org-add-props newhead nil - 'effort effort - 'effort-minutes effort-minutes) - level cat tags dotime)))) + (org-add-props newhead nil + 'effort effort + 'effort-minutes effort-minutes) + level cat tags dotime)))) ;; pl (text-property-any (line-beginning-position) ;; (line-end-position) 'org-heading t) undone-face (org-get-at-bol 'undone-face) done-face (org-get-at-bol 'done-face)) - (beginning-of-line 1) + (forward-line 0) (cond ((equal new "") (delete-region (point) (line-beginning-position 2))) ((looking-at ".*") @@ -10114,7 +9851,7 @@ If FORCE-TAGS is non-nil, the car of it returns the new tags." 'org-marked-entry-overlay) (throw :overlay o)))))) (replace-match new t t) - (beginning-of-line) + (forward-line 0) (when mark (move-overlay mark (point) (+ 2 (point))))) (add-text-properties (line-beginning-position) (line-end-position) props) @@ -10125,12 +9862,12 @@ If FORCE-TAGS is non-nil, the car of it returns the new tags." (if org-last-todo-state-is-todo undone-face done-face)))) (org-agenda-highlight-todo 'line) - (beginning-of-line 1)) + (forward-line 0)) (t (error "Line update did not work"))) (save-restriction (narrow-to-region (line-beginning-position) (line-end-position)) (org-agenda-finalize))) - (beginning-of-line 0))))) + (forward-line -1))))) (defun org-agenda-align-tags (&optional line) "Align all tags in agenda items to `org-agenda-tags-column'. @@ -10234,7 +9971,7 @@ When called programmatically, FORCE-DIRECTION can be `set', `up', (end-of-line 1) (setq newhead (org-get-heading))) (org-agenda-change-all-lines newhead hdmarker) - (beginning-of-line 1))))) + (forward-line 0))))) (defun org-agenda-set-property () "Set a property for the current headline." @@ -10298,7 +10035,7 @@ When called programmatically, FORCE-DIRECTION can be `set', `up', (end-of-line 1) (setq newhead (org-get-heading))) (org-agenda-change-all-lines newhead hdmarker) - (beginning-of-line 1))))) + (forward-line 0))))) (defun org-agenda-do-date-later (arg) (interactive "P") @@ -10375,15 +10112,15 @@ When called programmatically, FORCE-DIRECTION can be `set', `up', (org-agenda-date-later (- arg) what)) (defun org-agenda-date-later-minutes (arg) - "Change the time of this item, in units of `org-time-stamp-rounding-minutes'." + "Change the time of this item, in units of `org-timestamp-rounding-minutes'." (interactive "p") - (setq arg (* arg (cadr org-time-stamp-rounding-minutes))) + (setq arg (* arg (cadr org-timestamp-rounding-minutes))) (org-agenda-date-later arg 'minute)) (defun org-agenda-date-earlier-minutes (arg) - "Change the time of this item, in units of `org-time-stamp-rounding-minutes'." + "Change the time of this item, in units of `org-timestamp-rounding-minutes'." (interactive "p") - (setq arg (* arg (cadr org-time-stamp-rounding-minutes))) + (setq arg (* arg (cadr org-timestamp-rounding-minutes))) (org-agenda-date-earlier arg 'minute)) (defun org-agenda-date-later-hours (arg) @@ -10409,19 +10146,21 @@ When called programmatically, FORCE-DIRECTION can be `set', `up', (line-end-position) '(display nil)) (org-move-to-column - (- (window-max-chars-per-line) - (length stamp)) + (max + 1 ;; narrow buffer and wide timestamp + (- (window-max-chars-per-line) + (length stamp))) t) (add-text-properties (1- (point)) (line-end-position) (list 'display (org-add-props stamp nil 'face '(secondary-selection default)))) - (beginning-of-line 1)) - (beginning-of-line 0))))) + (forward-line 0)) + (forward-line -1))))) (defun org-agenda-date-prompt (arg) "Change the date of this item. Date is prompted for, with default today. -The prefix ARG is passed to the `org-time-stamp' command and can therefore +The prefix ARG is passed to the `org-timestamp' command and can therefore be used to request time specification in the time stamp." (interactive "P") (org-agenda-check-type t 'agenda) @@ -10437,7 +10176,7 @@ be used to request time specification in the time stamp." (widen) (goto-char pos) (unless (org-at-timestamp-p 'lax) (error "Cannot find time stamp")) - (org-time-stamp arg (equal (char-after (match-beginning 0)) ?\[))) + (org-timestamp arg (equal (char-after (match-beginning 0)) ?\[))) (org-agenda-show-new-time marker org-last-changed-timestamp)) (message "Time stamp changed to %s" org-last-changed-timestamp)))) @@ -10532,7 +10271,8 @@ ARG is passed through to `org-deadline'." (unless (marker-buffer org-clock-marker) (user-error "No running clock")) (org-with-remote-undo (marker-buffer org-clock-marker) - (org-clock-cancel))) + (org-clock-cancel)) + (org-agenda-unmark-clocking-task)) (defun org-agenda-clock-goto () "Jump to the currently clocked in task within the agenda. @@ -10548,13 +10288,13 @@ buffer, display it in another window." ;; If the currently clocked entry is not in the agenda ;; buffer, we visit it in another window: ((bound-and-true-p org-clock-current-task) - (org-switch-to-buffer-other-window (org-clock-goto))) + (switch-to-buffer-other-window (org-clock-goto))) (t (message "No running clock, use `C-c C-x C-j' to jump to the most recent one"))))) (defun org-agenda-diary-entry-in-org-file () "Make a diary entry in the file `org-agenda-diary-file'." (let (d1 d2 char (text "") dp1 dp2) - (if (equal (buffer-name) "*Calendar*") + (if (equal (buffer-name) calendar-buffer) (setq d1 (calendar-cursor-to-date t) d2 (car calendar-mark-ring)) (setq dp1 (get-text-property (line-beginning-position) 'day)) @@ -10586,7 +10326,7 @@ buffer, display it in another window." (org-agenda-add-entry-to-org-agenda-diary-file 'block text d1 d2) (and (equal (buffer-name) org-agenda-buffer-name) (org-agenda-redo))) ((equal char ?j) - (org-switch-to-buffer-other-window + (switch-to-buffer-other-window (find-file-noselect org-agenda-diary-file)) (require 'org-datetree) (org-datetree-find-date-create d1) @@ -10624,7 +10364,7 @@ If TEXT is not empty, it will become the headline of the new entry, and the resulting entry will not be shown. When TEXT is empty, switch to `org-agenda-diary-file' and let the user finish the entry there." (let ((cw (current-window-configuration))) - (org-switch-to-buffer-other-window + (switch-to-buffer-other-window (find-file-noselect org-agenda-diary-file)) (widen) (goto-char (point-min)) @@ -10636,7 +10376,7 @@ the resulting entry will not be shown. When TEXT is empty, switch to (progn (outline-next-heading) (insert "* Anniversaries\n\n") - (beginning-of-line -1))))) + (forward-line -2))))) (outline-next-heading) (org-back-over-empty-lines) (backward-char 1) @@ -10665,9 +10405,9 @@ the resulting entry will not be shown. When TEXT is empty, switch to (require 'org-datetree) (org-datetree-find-date-create d1) (org-agenda-insert-diary-make-new-entry text)) - (org-insert-time-stamp (org-time-from-absolute - (calendar-absolute-from-gregorian d1)) - nil nil nil nil time2)) + (org-insert-timestamp (org-time-from-absolute + (calendar-absolute-from-gregorian d1)) + nil nil nil nil time2)) (end-of-line 0)) ((block) ;; Wrap this in (strictly unnecessary) parens because ;; otherwise the indentation gets confused by the @@ -10680,11 +10420,11 @@ the resulting entry will not be shown. When TEXT is empty, switch to (require 'org-datetree) (org-datetree-find-date-create d1) (org-agenda-insert-diary-make-new-entry text)) - (org-insert-time-stamp (org-time-from-absolute - (calendar-absolute-from-gregorian d1))) + (org-insert-timestamp (org-time-from-absolute + (calendar-absolute-from-gregorian d1))) (insert "--") - (org-insert-time-stamp (org-time-from-absolute - (calendar-absolute-from-gregorian d2))) + (org-insert-timestamp (org-time-from-absolute + (calendar-absolute-from-gregorian d2))) (end-of-line 0))) (if (string-match "\\S-" text) (progn @@ -10913,16 +10653,23 @@ When ARG is greater than one mark ARG lines." (push m org-agenda-bulk-marked-entries) (setq ov (make-overlay (line-beginning-position) (+ 2 (line-beginning-position)))) - (org-overlay-display ov (concat org-agenda-bulk-mark-char " ") - (org-get-todo-face "TODO") - 'evaporate) + ;; Display using 'before-string to make the overlay + ;; compatible with column view in agenda that uses an + ;; overlay with higher priority. + (overlay-put ov 'before-string + (propertize org-agenda-bulk-mark-char + 'face (org-get-todo-face "TODO"))) + ;; We cannot completely hide the overlay to make point + ;; adjustment not move point out of overlay (to previous + ;; line) when moving lines with n/p. + (org-overlay-display ov " " nil 'evaporate) (overlay-put ov 'type 'org-marked-entry-overlay)) (end-of-line 1) (or (ignore-errors (goto-char (next-single-property-change (point) 'org-hd-marker))) - (beginning-of-line 2)) + (forward-line 1)) (while (and (get-char-property (point) 'invisible) (not (eobp))) - (beginning-of-line 2))))) + (forward-line 1))))) (message "%d entries marked for bulk action" (length org-agenda-bulk-marked-entries))) @@ -10942,7 +10689,7 @@ When ARG is greater than one mark ARG lines." (setq txt-at-point (get-text-property (match-beginning 0) 'txt))) (if (get-char-property (point) 'invisible) - (beginning-of-line 2) + (forward-line 1) (when (string-match-p regexp txt-at-point) (setq entries-marked (1+ entries-marked)) (call-interactively 'org-agenda-bulk-mark))))) @@ -10963,9 +10710,9 @@ When ARG is greater than one mark ARG lines." (end-of-line 1) (or (ignore-errors (goto-char (next-single-property-change (point) 'txt))) - (beginning-of-line 2)) + (forward-line 1)) (while (and (get-char-property (point) 'invisible) (not (eobp))) - (beginning-of-line 2)) + (forward-line 1)) (message "%d entries left marked for bulk action" (length org-agenda-bulk-marked-entries))) (t (message "No entry to unmark here"))))) @@ -11313,7 +11060,7 @@ tag and (if present) the flagging note." (unless note (user-error "No flagging note")) (org-kill-new note) - (org-switch-to-buffer-other-window "*Flagging Note*") + (switch-to-buffer-other-window "*Flagging Note*") (erase-buffer) (insert note) (goto-char (point-min)) @@ -11420,10 +11167,16 @@ to override `appt-message-warning-time'." (string-match cat-filter cat)) (and (stringp evt-filter) (string-match evt-filter evt))))))) - (wrn (get-text-property 1 'warntime x))) + (wrn (get-text-property 1 'warntime x)) + (todo-regexp (get-text-property 1 'org-todo-regexp x)) + (not-done-regexp (get-text-property 1 'org-not-done-regexp x))) ;; FIXME: Shall we remove text-properties for the appt text? ;; (setq evt (set-text-properties 0 (length evt) nil evt)) - (when (and ok tod (not (string-match "\\`DONE\\|CANCELLED" evt))) + (when (and ok tod + ;; Exclude done items unconditionally. + (or (not (and todo-regexp (string-match-p todo-regexp evt))) ; no todo keyword + (and not-done-regexp (string-match-p not-done-regexp evt)) ; or not done + )) (setq tod (concat "00" (number-to-string tod))) (setq tod (when (string-match "\\([0-9]\\{1,2\\}\\)\\([0-9]\\{2\\}\\)\\'" tod) diff --git a/elpa/org-9.6.7/org-archive.el b/elpa/org-9.7.17/org-archive.el similarity index 97% rename from elpa/org-9.6.7/org-archive.el rename to elpa/org-9.7.17/org-archive.el index e74c59a5..53c825ed 100644 --- a/elpa/org-9.6.7/org-archive.el +++ b/elpa/org-9.7.17/org-archive.el @@ -1,9 +1,9 @@ ;;; org-archive.el --- Archiving for Org -*- lexical-binding: t; -*- -;; Copyright (C) 2004-2023 Free Software Foundation, Inc. +;; Copyright (C) 2004-2024 Free Software Foundation, Inc. ;; Author: Carsten Dominik -;; Keywords: outlines, hypermedia, calendar, wp +;; Keywords: outlines, hypermedia, calendar, text ;; URL: https://orgmode.org ;; ;; This file is part of GNU Emacs. @@ -34,9 +34,9 @@ (require 'org) (require 'cl-lib) -(declare-function org-element-type "org-element" (element)) (declare-function org-datetree-find-date-create "org-datetree" (date &optional keep-restriction)) (declare-function org-inlinetask-remove-END-maybe "org-inlinetask" ()) +(declare-function org-timestamp-to-now "org" (timestamp-string &optional seconds)) ;; From org-element.el (defvar org-element--cache-avoid-synchronous-headline-re-parsing) @@ -154,10 +154,10 @@ archive location, but not yet deleted from the original file.") ;;;###autoload (defun org-add-archive-files (files) - "Splice the archive files into the list of files. + "Splice the archive FILES into the list of files. This implies visiting all these files and finding out what the archive file is." - (org-uniquify + (seq-uniq (apply 'append (mapcar @@ -166,7 +166,9 @@ archive file is." nil (with-current-buffer (org-get-agenda-file-buffer f) (cons f (org-all-archive-files))))) - files)))) + files)) + #'file-equal-p + )) (defun org-all-archive-files () "List of all archive files used in the current buffer." @@ -252,8 +254,7 @@ direct children of this heading." (newfile-p (and (org-string-nw-p afile) (not (file-exists-p afile)))) (buffer (cond ((not (org-string-nw-p afile)) this-buffer) - ((find-buffer-visiting afile)) - ((find-file-noselect afile)) + ((find-file-noselect afile 'nowarn)) (t (error "Cannot access file \"%s\"" afile)))) (org-odd-levels-only (if (local-variable-p 'org-odd-levels-only (current-buffer)) @@ -477,9 +478,9 @@ Archiving time is retained in the ARCHIVE_TIME node property." (goto-char e) (or (bolp) (newline)) (insert leader org-archive-sibling-heading "\n") - (beginning-of-line 0) + (forward-line -1) (org-toggle-tag org-archive-tag 'on)) - (beginning-of-line 1) + (forward-line 0) (if org-archive-reversed-order (outline-next-heading) (org-end-of-subtree t t)) @@ -524,12 +525,12 @@ When TAG is non-nil, don't move trees, but mark them with the ARCHIVE tag." (let (ts) (and (re-search-forward org-ts-regexp end t) (setq ts (match-string 0)) - (< (org-time-stamp-to-now ts) 0) + (< (org-timestamp-to-now ts) 0) (if (not (looking-at - (concat "--\\(" org-ts-regexp "\\)"))) + (concat "--\\(" org-ts-regexp "\\)"))) (concat "old timestamp " ts) (setq ts (concat "old timestamp " ts (match-string 0))) - (and (< (org-time-stamp-to-now (match-string 1)) 0) + (and (< (org-timestamp-to-now (match-string 1)) 0) ts))))) tag)) @@ -590,8 +591,9 @@ don't move trees, but mark them with the ARCHIVE tag." ;;;###autoload (defun org-toggle-archive-tag (&optional find-done) "Toggle the archive tag for the current headline. -With prefix ARG, check all children of current headline and offer tagging -the children that do not contain any open TODO items." +With prefix argument FIND-DONE, check all children of current headline +and offer tagging the children that do not contain any open TODO +items." (interactive "P") (if (and (org-region-active-p) org-loop-over-headlines-in-active-region) (let ((cl (if (eq org-loop-over-headlines-in-active-region 'start-level) @@ -608,7 +610,7 @@ the children that do not contain any open TODO items." (org-back-to-heading t) (setq set (org-toggle-tag org-archive-tag)) (when set (org-fold-subtree t))) - (and set (beginning-of-line 1)) + (and set (forward-line 0)) (message "Subtree %s" (if set "archived" "unarchived")))))) (defun org-archive-set-tag () diff --git a/elpa/org-9.6.7/org-attach-git.el b/elpa/org-9.7.17/org-attach-git.el similarity index 98% rename from elpa/org-9.6.7/org-attach-git.el rename to elpa/org-9.7.17/org-attach-git.el index 4763aefd..48b21984 100644 --- a/elpa/org-9.6.7/org-attach-git.el +++ b/elpa/org-9.7.17/org-attach-git.el @@ -1,6 +1,6 @@ ;;; org-attach-git.el --- Automatic git commit extension to org-attach -*- lexical-binding: t; -*- -;; Copyright (C) 2019-2023 Free Software Foundation, Inc. +;; Copyright (C) 2019-2024 Free Software Foundation, Inc. ;; Original Author: John Wiegley ;; Restructurer: Gustav Wikström diff --git a/elpa/org-9.6.7/org-attach.el b/elpa/org-9.7.17/org-attach.el similarity index 88% rename from elpa/org-9.6.7/org-attach.el rename to elpa/org-9.7.17/org-attach.el index e8b27751..a4419712 100644 --- a/elpa/org-9.6.7/org-attach.el +++ b/elpa/org-9.7.17/org-attach.el @@ -1,6 +1,6 @@ ;;; org-attach.el --- Manage file attachments to Org outlines -*- lexical-binding: t; -*- -;; Copyright (C) 2008-2023 Free Software Foundation, Inc. +;; Copyright (C) 2008-2024 Free Software Foundation, Inc. ;; Author: John Wiegley ;; Keywords: org data attachment @@ -44,8 +44,12 @@ (declare-function dired-dwim-target-directory "dired-aux") (declare-function dired-get-marked-files "dired" (&optional localp arg filter distinguish-one-marked error)) -(declare-function org-element-property "org-element" (property element)) -(declare-function org-element-type "org-element" (element)) +(declare-function org-element-property "org-element-ast" (property node)) +(declare-function org-element-begin "org-element" (node)) +(declare-function org-element-end "org-element" (node)) +(declare-function org-element-contents-begin "org-element" (node)) +(declare-function org-element-contents-end "org-element" (node)) +(declare-function org-element-type-p "org-element-ast" (node types)) (declare-function org-inlinetask-goto-beginning "org-inlinetask" ()) (declare-function org-inlinetask-in-task-p "org-inlinetask" ()) @@ -138,13 +142,13 @@ Selective means to respect the inheritance setting in (const :tag "Inherit parent node attachments" t) (const :tag "Respect org-use-property-inheritance" selective))) -(defcustom org-attach-store-link-p nil +(defcustom org-attach-store-link-p 'attached "Non-nil means store a link to a file when attaching it. When t, store the link to original file location. When `file', store link to the attached file location. When `attached', store attach: link to the attached file." :group 'org-attach - :version "24.1" + :package-version '(Org . "9.7") :type '(choice (const :tag "Don't store link" nil) (const :tag "Link to origin location" t) @@ -297,67 +301,71 @@ ask the user instead, else remove without asking." "The dispatcher for attachment commands. Shows a list of commands and prompts for another key to execute a command." (interactive) - (let ((dir (org-attach-dir nil 'no-fs-check)) - c marker) + (let (c marker) (when (eq major-mode 'org-agenda-mode) (setq marker (or (get-text-property (point) 'org-hd-marker) (get-text-property (point) 'org-marker))) (unless marker (error "No item in current line"))) (org-with-point-at marker - (if (and (featurep 'org-inlinetask) - (not (org-inlinetask-in-task-p))) - (org-with-limited-levels - (org-back-to-heading-or-point-min t)) + (let ((dir (org-attach-dir nil 'no-fs-check))) (if (and (featurep 'org-inlinetask) - (org-inlinetask-in-task-p)) - (org-inlinetask-goto-beginning) - (org-back-to-heading-or-point-min t))) - (save-excursion - (save-window-excursion - (unless org-attach-expert - (org-switch-to-buffer-other-window "*Org Attach*") - (erase-buffer) - (setq cursor-type nil - header-line-format "Use C-v, M-v, C-n or C-p to navigate.") - (insert - (concat "Attachment folder:\n" - (or dir - "Can't find an existing attachment-folder") - (unless (and dir (file-directory-p dir)) - "\n(Not yet created)") - "\n\n" - (format "Select an Attachment Command:\n\n%s" - (mapconcat - (lambda (entry) - (pcase entry - (`((,key . ,_) ,_ ,docstring) - (format "%c %s" - key - (replace-regexp-in-string "\n\\([\t ]*\\)" - " " - docstring - nil nil 1))) - (_ - (user-error - "Invalid `org-attach-commands' item: %S" - entry)))) - org-attach-commands - "\n"))))) - (org-fit-window-to-buffer (get-buffer-window "*Org Attach*")) - (let ((msg (format "Select command: [%s]" - (concat (mapcar #'caar org-attach-commands))))) - (message msg) - (while (and (setq c (read-char-exclusive)) - (memq c '(?\C-n ?\C-p ?\C-v ?\M-v))) - (org-scroll c t))) - (and (get-buffer "*Org Attach*") (kill-buffer "*Org Attach*")))) - (let ((command (cl-some (lambda (entry) - (and (memq c (nth 0 entry)) (nth 1 entry))) - org-attach-commands))) - (if (commandp command) - (command-execute command) - (error "No such attachment command: %c" c)))))) + (not (org-inlinetask-in-task-p))) + (org-with-limited-levels + (org-back-to-heading-or-point-min t)) + (if (and (featurep 'org-inlinetask) + (org-inlinetask-in-task-p)) + (org-inlinetask-goto-beginning) + (org-back-to-heading-or-point-min t))) + (save-excursion + (save-window-excursion + (unless org-attach-expert + (switch-to-buffer-other-window "*Org Attach*") + (erase-buffer) + (setq cursor-type nil + header-line-format "Use C-v, M-v, C-n or C-p to navigate.") + (insert + (concat "Attachment folder:\n" + (or dir + "Can't find an existing attachment-folder") + (unless (and dir (file-directory-p dir)) + "\n(Not yet created)") + "\n\n" + (format "Select an Attachment Command:\n\n%s" + (mapconcat + (lambda (entry) + (pcase entry + (`((,key . ,_) ,_ ,docstring) + (format "%c %s" + key + (replace-regexp-in-string "\n\\([\t ]*\\)" + " " + docstring + nil nil 1))) + (_ + (user-error + "Invalid `org-attach-commands' item: %S" + entry)))) + org-attach-commands + "\n")))) + (goto-char (point-min))) + (org-fit-window-to-buffer (get-buffer-window "*Org Attach*")) + (unwind-protect + (let ((msg (format "Select command: [%s]" + (concat (mapcar #'caar org-attach-commands))))) + (message msg) + (while (and (setq c (read-char-exclusive)) + (memq c '(?\C-n ?\C-p ?\C-v ?\M-v))) + (org-scroll c t))) + (when-let* ((window (get-buffer-window "*Org Attach*" t))) + (quit-window 'kill window)) + (and (get-buffer "*Org Attach*") (kill-buffer "*Org Attach*"))))) + (let ((command (cl-some (lambda (entry) + (and (memq c (nth 0 entry)) (nth 1 entry))) + org-attach-commands))) + (if (commandp command) + (command-execute command) + (error "No such attachment command: %c" c))))))) ;;;###autoload (defun org-attach-dir (&optional create-if-not-exists-p no-fs-check) @@ -432,17 +440,26 @@ ignoring nils. If EXISTING is non-nil, then return the first path found in the filesystem. Otherwise return the first non-nil value." (let ((fun-list org-attach-id-to-path-function-list) (base-dir (expand-file-name org-attach-id-dir)) + (default-base-dir (expand-file-name "data/")) preferred first) (while (and fun-list (not preferred)) (let* ((name (funcall (car fun-list) id)) - (candidate (and name (expand-file-name name base-dir)))) + (candidate (and name (expand-file-name name base-dir))) + ;; Try the default value `org-attach-id-dir' as a fallback. + (candidate2 (and name (not (equal base-dir default-base-dir)) + (expand-file-name name default-base-dir)))) (setq fun-list (cdr fun-list)) (when candidate (if (or (not existing) (file-directory-p candidate)) (setq preferred candidate) (unless first - (setq first candidate)))))) + (setq first candidate))) + (when (and existing + candidate2 + (not (file-directory-p candidate)) + (file-directory-p candidate2)) + (setq preferred candidate2))))) (or preferred first))) (defun org-attach-check-absolute-path (dir) @@ -512,9 +529,13 @@ DIR-property exists (that is different from the unset one)." (defun org-attach-tag (&optional off) "Turn the autotag on or (if OFF is set) off." (when org-attach-auto-tag - (save-excursion - (org-back-to-heading t) - (org-toggle-tag org-attach-auto-tag (if off 'off 'on))))) + ;; FIXME: There is currently no way to set #+FILETAGS + ;; programmatically. Do nothing when before first heading + ;; (attaching to file) to avoid blocking error. + (unless (org-before-first-heading-p) + (save-excursion + (org-back-to-heading t) + (org-toggle-tag org-attach-auto-tag (if off 'off 'on)))))) (defun org-attach-untag () "Turn the autotag off." @@ -573,7 +594,7 @@ METHOD may be `cp', `mv', `ln', `lns' or `url' default taken from ((eq method 'url) (if (org--should-fetch-remote-resource-p file) (url-copy-file file attach-file) - (error "The remote resource %S is considered unsafe, and will not be downloaded." + (error "The remote resource %S is considered unsafe, and will not be downloaded" file)))) (run-hook-with-args 'org-attach-after-change-hook attach-dir) (org-attach-tag) @@ -736,20 +757,20 @@ It is meant to be added to `org-export-before-parsing-hook'." (save-excursion (while (re-search-forward "attachment:" nil t) (let ((link (org-element-context))) - (when (and (eq 'link (org-element-type link)) + (when (and (org-element-type-p link 'link) (string-equal "attachment" (org-element-property :type link))) - (let* ((description (and (org-element-property :contents-begin link) + (let* ((description (and (org-element-contents-begin link) (buffer-substring-no-properties - (org-element-property :contents-begin link) - (org-element-property :contents-end link)))) + (org-element-contents-begin link) + (org-element-contents-end link)))) (file (org-element-property :path link)) (new-link (org-link-make-string (concat "file:" (org-attach-expand file)) description))) - (goto-char (org-element-property :end link)) + (goto-char (org-element-end link)) (skip-chars-backward " \t") - (delete-region (org-element-property :begin link) (point)) + (delete-region (org-element-begin link) (point)) (insert new-link))))))) (defun org-attach-follow (file arg) diff --git a/elpa/org-9.6.7/org-autoloads.el b/elpa/org-9.7.17/org-autoloads.el similarity index 77% rename from elpa/org-9.6.7/org-autoloads.el rename to elpa/org-9.7.17/org-autoloads.el index 2cddcddd..6403c308 100644 --- a/elpa/org-9.6.7/org-autoloads.el +++ b/elpa/org-9.7.17/org-autoloads.el @@ -1,320 +1,249 @@ -;;; org-autoloads.el --- automatically extracted autoloads -*- lexical-binding: t -*- -;; +;;; org-autoloads.el --- automatically extracted autoloads (do not edit) -*- lexical-binding: t -*- +;; Generated by the `loaddefs-generate' function. + +;; This file is part of GNU Emacs. + ;;; Code: -(add-to-list 'load-path (directory-file-name - (or (file-name-directory #$) (car load-path)))) +(add-to-list 'load-path (or (and load-file-name (directory-file-name (file-name-directory load-file-name))) (car load-path))) + -;;;### (autoloads nil "ob-C" "ob-C.el" (0 0 0 0)) ;;; Generated autoloads from ob-C.el (register-definition-prefixes "ob-C" '("org-babel-")) -;;;*** -;;;### (autoloads nil "ob-R" "ob-R.el" (0 0 0 0)) ;;; Generated autoloads from ob-R.el (register-definition-prefixes "ob-R" '("ob-" "org-babel-")) -;;;*** -;;;### (autoloads nil "ob-awk" "ob-awk.el" (0 0 0 0)) ;;; Generated autoloads from ob-awk.el (register-definition-prefixes "ob-awk" '("org-babel-")) -;;;*** -;;;### (autoloads nil "ob-calc" "ob-calc.el" (0 0 0 0)) ;;; Generated autoloads from ob-calc.el (register-definition-prefixes "ob-calc" '("org-babel-")) -;;;*** -;;;### (autoloads nil "ob-clojure" "ob-clojure.el" (0 0 0 0)) ;;; Generated autoloads from ob-clojure.el (register-definition-prefixes "ob-clojure" '("ob-clojure-" "org-babel-")) -;;;*** -;;;### (autoloads nil "ob-comint" "ob-comint.el" (0 0 0 0)) ;;; Generated autoloads from ob-comint.el (register-definition-prefixes "ob-comint" '("org-babel-comint-")) -;;;*** -;;;### (autoloads nil "ob-css" "ob-css.el" (0 0 0 0)) +;;; Generated autoloads from ob-core.el + +(register-definition-prefixes "ob-core" '("org-")) + + ;;; Generated autoloads from ob-css.el (register-definition-prefixes "ob-css" '("org-babel-")) -;;;*** -;;;### (autoloads nil "ob-ditaa" "ob-ditaa.el" (0 0 0 0)) ;;; Generated autoloads from ob-ditaa.el (register-definition-prefixes "ob-ditaa" '("org-")) -;;;*** -;;;### (autoloads nil "ob-dot" "ob-dot.el" (0 0 0 0)) ;;; Generated autoloads from ob-dot.el (register-definition-prefixes "ob-dot" '("org-babel-")) -;;;*** -;;;### (autoloads nil "ob-emacs-lisp" "ob-emacs-lisp.el" (0 0 0 0)) ;;; Generated autoloads from ob-emacs-lisp.el (register-definition-prefixes "ob-emacs-lisp" '("org-babel-")) -;;;*** -;;;### (autoloads nil "ob-eshell" "ob-eshell.el" (0 0 0 0)) ;;; Generated autoloads from ob-eshell.el (register-definition-prefixes "ob-eshell" '("ob-eshell-session-live-p" "org-babel-")) -;;;*** -;;;### (autoloads nil "ob-eval" "ob-eval.el" (0 0 0 0)) ;;; Generated autoloads from ob-eval.el (register-definition-prefixes "ob-eval" '("org-babel-")) -;;;*** -;;;### (autoloads nil "ob-exp" "ob-exp.el" (0 0 0 0)) ;;; Generated autoloads from ob-exp.el (register-definition-prefixes "ob-exp" '("org-")) -;;;*** -;;;### (autoloads nil "ob-forth" "ob-forth.el" (0 0 0 0)) ;;; Generated autoloads from ob-forth.el (register-definition-prefixes "ob-forth" '("org-babel-")) -;;;*** -;;;### (autoloads nil "ob-fortran" "ob-fortran.el" (0 0 0 0)) ;;; Generated autoloads from ob-fortran.el (register-definition-prefixes "ob-fortran" '("org-babel-")) -;;;*** -;;;### (autoloads nil "ob-gnuplot" "ob-gnuplot.el" (0 0 0 0)) ;;; Generated autoloads from ob-gnuplot.el (register-definition-prefixes "ob-gnuplot" '("*org-babel-gnuplot-" "org-babel-")) -;;;*** -;;;### (autoloads nil "ob-groovy" "ob-groovy.el" (0 0 0 0)) ;;; Generated autoloads from ob-groovy.el (register-definition-prefixes "ob-groovy" '("org-babel-")) -;;;*** -;;;### (autoloads nil "ob-haskell" "ob-haskell.el" (0 0 0 0)) ;;; Generated autoloads from ob-haskell.el (register-definition-prefixes "ob-haskell" '("org-babel-")) -;;;*** -;;;### (autoloads nil "ob-java" "ob-java.el" (0 0 0 0)) ;;; Generated autoloads from ob-java.el (register-definition-prefixes "ob-java" '("org-babel-")) -;;;*** -;;;### (autoloads nil "ob-js" "ob-js.el" (0 0 0 0)) ;;; Generated autoloads from ob-js.el (register-definition-prefixes "ob-js" '("org-babel-")) -;;;*** -;;;### (autoloads nil "ob-julia" "ob-julia.el" (0 0 0 0)) ;;; Generated autoloads from ob-julia.el (register-definition-prefixes "ob-julia" '("org-babel-")) -;;;*** -;;;### (autoloads nil "ob-latex" "ob-latex.el" (0 0 0 0)) ;;; Generated autoloads from ob-latex.el (register-definition-prefixes "ob-latex" '("org-babel-")) -;;;*** -;;;### (autoloads nil "ob-lilypond" "ob-lilypond.el" (0 0 0 0)) ;;; Generated autoloads from ob-lilypond.el -(register-definition-prefixes "ob-lilypond" '("lilypond-mode" "ob-lilypond-header-args" "org-babel-")) +(register-definition-prefixes "ob-lilypond" '("ob-lilypond-header-args" "org-babel-")) -;;;*** -;;;### (autoloads nil "ob-lisp" "ob-lisp.el" (0 0 0 0)) ;;; Generated autoloads from ob-lisp.el (register-definition-prefixes "ob-lisp" '("org-babel-")) -;;;*** -;;;### (autoloads nil "ob-lua" "ob-lua.el" (0 0 0 0)) +;;; Generated autoloads from ob-lob.el + +(register-definition-prefixes "ob-lob" '("org-babel-")) + + ;;; Generated autoloads from ob-lua.el (register-definition-prefixes "ob-lua" '("org-babel-")) -;;;*** -;;;### (autoloads nil "ob-makefile" "ob-makefile.el" (0 0 0 0)) ;;; Generated autoloads from ob-makefile.el (register-definition-prefixes "ob-makefile" '("org-babel-")) -;;;*** -;;;### (autoloads nil "ob-maxima" "ob-maxima.el" (0 0 0 0)) ;;; Generated autoloads from ob-maxima.el (register-definition-prefixes "ob-maxima" '("org-babel-")) -;;;*** -;;;### (autoloads nil "ob-ocaml" "ob-ocaml.el" (0 0 0 0)) ;;; Generated autoloads from ob-ocaml.el (register-definition-prefixes "ob-ocaml" '("org-babel-")) -;;;*** -;;;### (autoloads nil "ob-octave" "ob-octave.el" (0 0 0 0)) ;;; Generated autoloads from ob-octave.el (register-definition-prefixes "ob-octave" '("org-babel-")) -;;;*** -;;;### (autoloads nil "ob-org" "ob-org.el" (0 0 0 0)) ;;; Generated autoloads from ob-org.el (register-definition-prefixes "ob-org" '("org-babel-")) -;;;*** -;;;### (autoloads nil "ob-perl" "ob-perl.el" (0 0 0 0)) ;;; Generated autoloads from ob-perl.el (register-definition-prefixes "ob-perl" '("org-babel-")) -;;;*** -;;;### (autoloads nil "ob-plantuml" "ob-plantuml.el" (0 0 0 0)) ;;; Generated autoloads from ob-plantuml.el (register-definition-prefixes "ob-plantuml" '("org-")) -;;;*** -;;;### (autoloads nil "ob-processing" "ob-processing.el" (0 0 0 0)) ;;; Generated autoloads from ob-processing.el (register-definition-prefixes "ob-processing" '("org-babel-")) -;;;*** -;;;### (autoloads nil "ob-python" "ob-python.el" (0 0 0 0)) ;;; Generated autoloads from ob-python.el (register-definition-prefixes "ob-python" '("org-babel-")) -;;;*** -;;;### (autoloads nil "ob-ref" "ob-ref.el" (0 0 0 0)) ;;; Generated autoloads from ob-ref.el (register-definition-prefixes "ob-ref" '("org-babel-")) -;;;*** -;;;### (autoloads nil "ob-ruby" "ob-ruby.el" (0 0 0 0)) ;;; Generated autoloads from ob-ruby.el (register-definition-prefixes "ob-ruby" '("org-babel-")) -;;;*** -;;;### (autoloads nil "ob-sass" "ob-sass.el" (0 0 0 0)) ;;; Generated autoloads from ob-sass.el (register-definition-prefixes "ob-sass" '("org-babel-")) -;;;*** -;;;### (autoloads nil "ob-scheme" "ob-scheme.el" (0 0 0 0)) ;;; Generated autoloads from ob-scheme.el (register-definition-prefixes "ob-scheme" '("org-babel-")) -;;;*** -;;;### (autoloads nil "ob-screen" "ob-screen.el" (0 0 0 0)) ;;; Generated autoloads from ob-screen.el (register-definition-prefixes "ob-screen" '("org-babel-")) -;;;*** -;;;### (autoloads nil "ob-sed" "ob-sed.el" (0 0 0 0)) ;;; Generated autoloads from ob-sed.el (register-definition-prefixes "ob-sed" '("org-babel-")) -;;;*** -;;;### (autoloads nil "ob-shell" "ob-shell.el" (0 0 0 0)) ;;; Generated autoloads from ob-shell.el -(register-definition-prefixes "ob-shell" '("org-babel-")) +(register-definition-prefixes "ob-shell" '("ob-shell-async-" "org-babel-")) -;;;*** -;;;### (autoloads nil "ob-sql" "ob-sql.el" (0 0 0 0)) ;;; Generated autoloads from ob-sql.el (register-definition-prefixes "ob-sql" '("org-babel-")) -;;;*** -;;;### (autoloads nil "ob-sqlite" "ob-sqlite.el" (0 0 0 0)) ;;; Generated autoloads from ob-sqlite.el (register-definition-prefixes "ob-sqlite" '("org-babel-")) -;;;*** -;;;### (autoloads nil "ob-table" "ob-table.el" (0 0 0 0)) ;;; Generated autoloads from ob-table.el (register-definition-prefixes "ob-table" '("org-")) -;;;*** -;;;### (autoloads nil "oc" "oc.el" (0 0 0 0)) +;;; Generated autoloads from ob-tangle.el + +(register-definition-prefixes "ob-tangle" '("org-babel-")) + + ;;; Generated autoloads from oc.el (autoload 'org-cite-insert "oc" "\ @@ -322,132 +251,111 @@ Insert a citation at point. Insertion is done according to the processor set in `org-cite-insert-processor'. ARG is the prefix argument received when calling interactively the function. -\(fn ARG)" t nil) - +(fn ARG)" t) (register-definition-prefixes "oc" '("org-cite-")) -;;;*** -;;;### (autoloads nil "oc-basic" "oc-basic.el" (0 0 0 0)) ;;; Generated autoloads from oc-basic.el (register-definition-prefixes "oc-basic" '("org-cite-basic-")) -;;;*** -;;;### (autoloads nil "oc-biblatex" "oc-biblatex.el" (0 0 0 0)) ;;; Generated autoloads from oc-biblatex.el (register-definition-prefixes "oc-biblatex" '("org-cite-biblatex-")) -;;;*** -;;;### (autoloads nil "oc-bibtex" "oc-bibtex.el" (0 0 0 0)) ;;; Generated autoloads from oc-bibtex.el (register-definition-prefixes "oc-bibtex" '("org-cite-bibtex-export-")) -;;;*** -;;;### (autoloads nil "oc-csl" "oc-csl.el" (0 0 0 0)) ;;; Generated autoloads from oc-csl.el (register-definition-prefixes "oc-csl" '("org-cite-csl-")) -;;;*** -;;;### (autoloads nil "oc-natbib" "oc-natbib.el" (0 0 0 0)) ;;; Generated autoloads from oc-natbib.el (register-definition-prefixes "oc-natbib" '("org-cite-natbib-")) -;;;*** -;;;### (autoloads nil "ol-bibtex" "ol-bibtex.el" (0 0 0 0)) +;;; Generated autoloads from ol.el + +(register-definition-prefixes "ol" '("org-")) + + +;;; Generated autoloads from ol-bbdb.el + +(register-definition-prefixes "ol-bbdb" '("org-bbdb-")) + + ;;; Generated autoloads from ol-bibtex.el (register-definition-prefixes "ol-bibtex" '("org-")) -;;;*** -;;;### (autoloads nil "ol-docview" "ol-docview.el" (0 0 0 0)) ;;; Generated autoloads from ol-docview.el (register-definition-prefixes "ol-docview" '("org-docview-")) -;;;*** -;;;### (autoloads nil "ol-doi" "ol-doi.el" (0 0 0 0)) ;;; Generated autoloads from ol-doi.el (register-definition-prefixes "ol-doi" '("org-link-doi-")) -;;;*** -;;;### (autoloads nil "ol-eshell" "ol-eshell.el" (0 0 0 0)) ;;; Generated autoloads from ol-eshell.el (register-definition-prefixes "ol-eshell" '("org-eshell-")) -;;;*** -;;;### (autoloads nil "ol-eww" "ol-eww.el" (0 0 0 0)) ;;; Generated autoloads from ol-eww.el (register-definition-prefixes "ol-eww" '("org-eww-")) -;;;*** -;;;### (autoloads nil "ol-gnus" "ol-gnus.el" (0 0 0 0)) ;;; Generated autoloads from ol-gnus.el (register-definition-prefixes "ol-gnus" '("org-gnus-")) -;;;*** -;;;### (autoloads nil "ol-info" "ol-info.el" (0 0 0 0)) ;;; Generated autoloads from ol-info.el (register-definition-prefixes "ol-info" '("org-info-")) -;;;*** -;;;### (autoloads nil "ol-man" "ol-man.el" (0 0 0 0)) +;;; Generated autoloads from ol-irc.el + +(register-definition-prefixes "ol-irc" '("org-irc-")) + + ;;; Generated autoloads from ol-man.el (register-definition-prefixes "ol-man" '("org-man-")) -;;;*** -;;;### (autoloads nil "ol-mhe" "ol-mhe.el" (0 0 0 0)) ;;; Generated autoloads from ol-mhe.el (register-definition-prefixes "ol-mhe" '("org-mhe-")) -;;;*** -;;;### (autoloads nil "ol-rmail" "ol-rmail.el" (0 0 0 0)) ;;; Generated autoloads from ol-rmail.el (register-definition-prefixes "ol-rmail" '("org-rmail-")) -;;;*** -;;;### (autoloads nil "ol-w3m" "ol-w3m.el" (0 0 0 0)) ;;; Generated autoloads from ol-w3m.el (register-definition-prefixes "ol-w3m" '("org-w3m-")) -;;;*** -;;;### (autoloads nil "org" "org.el" (0 0 0 0)) ;;; Generated autoloads from org.el (autoload 'org-babel-do-load-languages "org" "\ Load the languages defined in `org-babel-load-languages'. -\(fn SYM VALUE)" nil nil) - +(fn SYM VALUE)") (autoload 'org-babel-load-file "org" "\ Load Emacs Lisp source code blocks in the Org FILE. This function exports the source code using `org-babel-tangle' @@ -455,8 +363,7 @@ and then loads the resulting file using `load-file'. With optional prefix argument COMPILE, the tangled Emacs Lisp file is byte-compiled before it is loaded. -\(fn FILE &optional COMPILE)" t nil) - +(fn FILE &optional COMPILE)" t) (autoload 'org-version "org" "\ Show the Org version. Interactively, or when MESSAGE is non-nil, show it in echo area. @@ -464,16 +371,13 @@ With prefix argument, or when HERE is non-nil, insert it at point. In non-interactive uses, a reduced version string is output unless FULL is given. -\(fn &optional HERE FULL MESSAGE)" t nil) - +(fn &optional HERE FULL MESSAGE)" t) (autoload 'org-load-modules-maybe "org" "\ Load all extensions listed in `org-modules'. -\(fn &optional FORCE)" nil nil) - +(fn &optional FORCE)") (autoload 'org-clock-persistence-insinuate "org" "\ -Set up hooks for clock persistence." nil nil) - +Set up hooks for clock persistence.") (autoload 'org-mode "org" "\ Outline-based notes management and organizer, alias \"Carsten's outline-mode for keeping track of everything.\" @@ -493,16 +397,14 @@ The following commands are available: \\{org-mode-map} -\(fn)" t nil) - +(fn)" t) (autoload 'org-run-like-in-org-mode "org" "\ Run a command, pretending that the current buffer is in Org mode. This will temporarily bind local variables that are typically bound in Org mode to the values they have in Org mode, and then interactively call CMD. -\(fn CMD)" nil nil) - +(fn CMD)") (autoload 'org-open-file "org" "\ Open the file at PATH. First, this expands any special file name abbreviations. Then the @@ -525,16 +427,14 @@ link, please customize `org-link-frame-setup'. If the file does not exist, throw an error. -\(fn PATH &optional IN-EMACS LINE SEARCH)" nil nil) - +(fn PATH &optional IN-EMACS LINE SEARCH)") (autoload 'org-open-at-point-global "org" "\ -Follow a link or a time-stamp like Org mode does. +Follow a link or a timestamp like Org mode does. Also follow links and emails as seen by `thing-at-point'. This command can be called in any mode to follow an external -link or a time-stamp that has Org mode syntax. Its behavior +link or a timestamp that has Org mode syntax. Its behavior is undefined when called on internal links like fuzzy links. -Raise a user error when there is nothing to follow." t nil) - +Raise a user error when there is nothing to follow." t) (autoload 'org-offer-links-in-entry "org" "\ Offer links in the current entry and return the selected link. If there is only one link, return it. @@ -542,8 +442,7 @@ If NTH is an integer, return the NTH link found. If ZERO is a string, check also this string for a link, and if there is one, return it. -\(fn BUFFER MARKER &optional NTH ZERO)" nil nil) - +(fn BUFFER MARKER &optional NTH ZERO)") (autoload 'org-switchb "org" "\ Switch between Org buffers. @@ -551,13 +450,11 @@ With `\\[universal-argument]' prefix, restrict available buffers to files. With `\\[universal-argument] \\[universal-argument]' prefix, restrict available buffers to agenda files. -\(fn &optional ARG)" t nil) - +(fn &optional ARG)" t) (autoload 'org-cycle-agenda-files "org" "\ Cycle through the files in `org-agenda-files'. If the current buffer visits an agenda file, find the next one in the list. -If the current buffer does not, find the first agenda file." t nil) - +If the current buffer does not, find the first agenda file." t) (autoload 'org-submit-bug-report "org" "\ Submit a bug report on Org via mail. @@ -565,29 +462,23 @@ Don't hesitate to report any problems or inaccurate documentation. If you don't have setup sending mail from (X)Emacs, please copy the output buffer into your mail program, as it gives us important -information about your Org version and configuration." t nil) - +information about your Org version and configuration." t) (autoload 'org-reload "org" "\ Reload all Org Lisp files. With prefix arg UNCOMPILED, load the uncompiled versions. -\(fn &optional UNCOMPILED)" t nil) - +(fn &optional UNCOMPILED)" t) (autoload 'org-customize "org" "\ -Call the customize function with org as argument." t nil) - +Call the customize function with org as argument." t) (register-definition-prefixes "org" '("org-" "turn-on-org-cdlatex")) -;;;*** -;;;### (autoloads nil "org-agenda" "org-agenda.el" (0 0 0 0)) ;;; Generated autoloads from org-agenda.el (autoload 'org-toggle-sticky-agenda "org-agenda" "\ Toggle `org-agenda-sticky'. -\(fn &optional ARG)" t nil) - +(fn &optional ARG)" t) (autoload 'org-agenda "org-agenda" "\ Dispatch agenda commands to collect entries to the agenda buffer. Prompts for a command to execute. Any prefix arg will be passed @@ -618,12 +509,11 @@ searches can be pre-defined in this way. If the current buffer is in Org mode and visiting a file, you can also first press `<' once to indicate that the agenda should be temporarily -\(until the next use of `\\[org-agenda]') restricted to the current file. +(until the next use of `\\[org-agenda]') restricted to the current file. Pressing `<' twice means to restrict to the current subtree or region -\(if active). - -\(fn &optional ARG KEYS RESTRICTION)" t nil) +(if active). +(fn &optional ARG KEYS RESTRICTION)" t) (autoload 'org-batch-agenda "org-agenda" "\ Run an agenda command in batch mode and send the result to STDOUT. If CMD-KEY is a string of length 1, it is used as a key in @@ -632,8 +522,7 @@ longer string it is used as a tags/todo match string. Parameters are alternating variable names and values that will be bound before running the agenda command. -\(fn CMD-KEY &rest PARAMETERS)" nil t) - +(fn CMD-KEY &rest PARAMETERS)" nil t) (autoload 'org-batch-agenda-csv "org-agenda" "\ Run an agenda command in batch mode and send the result to STDOUT. If CMD-KEY is a string of length 1, it is used as a key in @@ -669,18 +558,15 @@ priority-l The priority letter if any was given priority-n The computed numerical priority agenda-day The day in the agenda where this is listed -\(fn CMD-KEY &rest PARAMETERS)" nil t) - +(fn CMD-KEY &rest PARAMETERS)" nil t) (autoload 'org-store-agenda-views "org-agenda" "\ Store agenda views. -\(fn &rest PARAMETERS)" t nil) - +(fn &rest PARAMETERS)" t) (autoload 'org-batch-store-agenda-views "org-agenda" "\ Run all custom agenda commands that have a file argument. -\(fn &rest PARAMETERS)" nil t) - +(fn &rest PARAMETERS)" nil t) (autoload 'org-agenda-list "org-agenda" "\ Produce a daily/weekly view from all files in variable `org-agenda-files'. The view will be for the current day or week, but from the overview buffer @@ -696,8 +582,7 @@ given in `org-agenda-start-on-weekday'. When WITH-HOUR is non-nil, only include scheduled and deadline items if they have an hour specification like [h]h:mm. -\(fn &optional ARG START-DAY SPAN WITH-HOUR)" t nil) - +(fn &optional ARG START-DAY SPAN WITH-HOUR)" t) (autoload 'org-search-view "org-agenda" "\ Show all entries that contain a phrase or words or regular expressions. @@ -743,8 +628,7 @@ This command searches the agenda files, and in addition the files listed in `org-agenda-text-search-extra-files' unless a restriction lock is active. -\(fn &optional TODO-ONLY STRING EDIT-AT)" t nil) - +(fn &optional TODO-ONLY STRING EDIT-AT)" t) (autoload 'org-todo-list "org-agenda" "\ Show all (not done) TODO entries from all agenda files in a single list. The prefix arg can be used to select a specific TODO keyword and limit @@ -752,22 +636,19 @@ the list to these. When using `\\[universal-argument]', you will be prompted for a keyword. A numeric prefix directly selects the Nth keyword in `org-todo-keywords-1'. -\(fn &optional ARG)" t nil) - +(fn &optional ARG)" t) (autoload 'org-tags-view "org-agenda" "\ Show all headlines for all `org-agenda-files' matching a TAGS criterion. The prefix arg TODO-ONLY limits the search to TODO entries. -\(fn &optional TODO-ONLY MATCH)" t nil) - +(fn &optional TODO-ONLY MATCH)" t) (autoload 'org-agenda-list-stuck-projects "org-agenda" "\ Create agenda view for projects that are stuck. Stuck projects are project that have no next actions. For the definitions of what a project is and how to check if it stuck, customize the variable `org-stuck-projects'. -\(fn &rest IGNORE)" t nil) - +(fn &rest IGNORE)" t) (autoload 'org-diary "org-agenda" "\ Return diary information from org files. This function can be used in a \"sexp\" diary entry in the Emacs calendar. @@ -795,13 +676,11 @@ The function expects the lisp variables `entry' and `date' to be provided by the caller, because this is how the calendar works. Don't use this function from a program - use `org-agenda-get-day-entries' instead. -\(fn &rest ARGS)" nil nil) - +(fn &rest ARGS)") (autoload 'org-agenda-check-for-timestamp-as-reason-to-ignore-todo-item "org-agenda" "\ Do we have a reason to ignore this TODO entry because it has a time stamp? -\(fn &optional END)" nil nil) - +(fn &optional END)") (autoload 'org-agenda-set-restriction-lock "org-agenda" "\ Set restriction lock for agenda to current subtree or file. When in a restricted subtree, remove it. @@ -811,12 +690,10 @@ or if TYPE is (4), or if the cursor is before the first headline in the file. Otherwise, only apply the restriction to the current subtree. -\(fn &optional TYPE)" t nil) - +(fn &optional TYPE)" t) (autoload 'org-calendar-goto-agenda "org-agenda" "\ Compute the Org agenda for the calendar date displayed at the cursor. -This is a command that has to be installed in `calendar-mode-map'." t nil) - +This is a command that has to be installed in `calendar-mode-map'." t) (autoload 'org-agenda-to-appt "org-agenda" "\ Activate appointments found in `org-agenda-files'. @@ -843,35 +720,38 @@ belonging to the \"Work\" category. ARGS are symbols indicating what kind of entries to consider. By default `org-agenda-to-appt' will use :deadline*, :scheduled* -\(i.e., deadlines and scheduled items with a hh:mm specification) +(i.e., deadlines and scheduled items with a hh:mm specification) and :timestamp entries. See the docstring of `org-diary' for details and examples. If an entry has a APPT_WARNTIME property, its value will be used to override `appt-message-warning-time'. -\(fn &optional REFRESH FILTER &rest ARGS)" t nil) - +(fn &optional REFRESH FILTER &rest ARGS)" t) (register-definition-prefixes "org-agenda" '("org-")) -;;;*** -;;;### (autoloads nil "org-attach-git" "org-attach-git.el" (0 0 0 -;;;;;; 0)) +;;; Generated autoloads from org-archive.el + +(register-definition-prefixes "org-archive" '("org-a")) + + +;;; Generated autoloads from org-attach.el + +(register-definition-prefixes "org-attach" '("org-attach-")) + + ;;; Generated autoloads from org-attach-git.el (register-definition-prefixes "org-attach-git" '("org-attach-git-")) -;;;*** -;;;### (autoloads nil "org-capture" "org-capture.el" (0 0 0 0)) ;;; Generated autoloads from org-capture.el (autoload 'org-capture-string "org-capture" "\ Capture STRING with the template selected by KEYS. -\(fn STRING &optional KEYS)" t nil) - +(fn STRING &optional KEYS)" t) (autoload 'org-capture "org-capture" "\ Capture something. \\ @@ -901,45 +781,47 @@ agenda will use the date at point as the default date. Then, a `C-1' prefix will tell the capture process to use the HH:MM time of the day at point (if any) or the current HH:MM time. -\(fn &optional GOTO KEYS)" t nil) - +(fn &optional GOTO KEYS)" t) (autoload 'org-capture-import-remember-templates "org-capture" "\ -Set `org-capture-templates' to be similar to `org-remember-templates'." t nil) - +Set `org-capture-templates' to be similar to `org-remember-templates'." t) (register-definition-prefixes "org-capture" '("org-capture-")) -;;;*** -;;;### (autoloads nil "org-crypt" "org-crypt.el" (0 0 0 0)) +;;; Generated autoloads from org-clock.el + +(register-definition-prefixes "org-clock" '("org-")) + + +;;; Generated autoloads from org-colview.el + +(register-definition-prefixes "org-colview" '("org-")) + + +;;; Generated autoloads from org-compat.el + +(register-definition-prefixes "org-compat" '("org-" "outline-")) + + ;;; Generated autoloads from org-crypt.el (autoload 'org-encrypt-entry "org-crypt" "\ -Encrypt the content of the current headline." t nil) - +Encrypt the content of the current headline." t) (autoload 'org-decrypt-entry "org-crypt" "\ -Decrypt the content of the current headline." t nil) - +Decrypt the content of the current headline." t) (autoload 'org-encrypt-entries "org-crypt" "\ -Encrypt all top-level entries in the current buffer." t nil) - +Encrypt all top-level entries in the current buffer." t) (autoload 'org-decrypt-entries "org-crypt" "\ -Decrypt all entries in the current buffer." t nil) - +Decrypt all entries in the current buffer." t) (autoload 'org-crypt-use-before-save-magic "org-crypt" "\ -Add a hook to automatically encrypt entries before a file is saved to disk." nil nil) - +Add a hook to automatically encrypt entries before a file is saved to disk.") (register-definition-prefixes "org-crypt" '("org-")) -;;;*** -;;;### (autoloads nil "org-ctags" "org-ctags.el" (0 0 0 0)) ;;; Generated autoloads from org-ctags.el (register-definition-prefixes "org-ctags" '("org-")) -;;;*** -;;;### (autoloads nil "org-cycle" "org-cycle.el" (0 0 0 0)) ;;; Generated autoloads from org-cycle.el (autoload 'org-cycle "org-cycle" "\ @@ -992,126 +874,211 @@ there is no headline there, and if the variable `org-cycle-global-at-bob' is non-nil, this function acts as if called with prefix argument (`\\[universal-argument] TAB', same as `S-TAB') also when called without prefix argument. -\(fn &optional ARG)" t nil) - +(fn &optional ARG)" t) (autoload 'org-cycle-global "org-cycle" "\ Cycle the global visibility. For details see `org-cycle'. With `\\[universal-argument]' prefix ARG, switch to startup visibility. With a numeric prefix, show all headlines up to that level. -\(fn &optional ARG)" t nil) +(fn &optional ARG)" t) +(register-definition-prefixes "org-cycle" '("org-")) + + +;;; Generated autoloads from org-datetree.el + +(register-definition-prefixes "org-datetree" '("org-datetree-")) + + +;;; Generated autoloads from org-duration.el + +(register-definition-prefixes "org-duration" '("org-duration-")) + + +;;; Generated autoloads from org-element.el + +(register-definition-prefixes "org-element" '("org-element-")) + + +;;; Generated autoloads from org-element-ast.el -(register-definition-prefixes "org-cycle" '("org-cycle-")) +(register-definition-prefixes "org-element-ast" '("org-element-")) -;;;*** -;;;### (autoloads nil "org-entities" "org-entities.el" (0 0 0 0)) ;;; Generated autoloads from org-entities.el (register-definition-prefixes "org-entities" '("org-entit")) -;;;*** -;;;### (autoloads nil "org-faces" "org-faces.el" (0 0 0 0)) ;;; Generated autoloads from org-faces.el (register-definition-prefixes "org-faces" '("org-")) -;;;*** -;;;### (autoloads nil "org-fold" "org-fold.el" (0 0 0 0)) +;;; Generated autoloads from org-feed.el + +(register-definition-prefixes "org-feed" '("org-feed-")) + + ;;; Generated autoloads from org-fold.el (register-definition-prefixes "org-fold" '("org-fold-")) -;;;*** -;;;### (autoloads nil "org-fold-core" "org-fold-core.el" (0 0 0 0)) ;;; Generated autoloads from org-fold-core.el (register-definition-prefixes "org-fold-core" '("org-fold-core-")) -;;;*** -;;;### (autoloads nil "org-habit" "org-habit.el" (0 0 0 0)) +;;; Generated autoloads from org-footnote.el + +(register-definition-prefixes "org-footnote" '("org-footnote-")) + + +;;; Generated autoloads from org-goto.el + +(register-definition-prefixes "org-goto" '("org-goto-")) + + ;;; Generated autoloads from org-habit.el (register-definition-prefixes "org-habit" '("org-")) -;;;*** -;;;### (autoloads nil "org-inlinetask" "org-inlinetask.el" (0 0 0 -;;;;;; 0)) +;;; Generated autoloads from org-id.el + +(register-definition-prefixes "org-id" '("org-id-")) + + +;;; Generated autoloads from org-indent.el + +(register-definition-prefixes "org-indent" '("org-indent-")) + + ;;; Generated autoloads from org-inlinetask.el (register-definition-prefixes "org-inlinetask" '("org-inlinetask-")) -;;;*** -;;;### (autoloads nil "org-macro" "org-macro.el" (0 0 0 0)) +;;; Generated autoloads from org-keys.el + +(register-definition-prefixes "org-keys" '("org-")) + + +;;; Generated autoloads from org-lint.el + +(register-definition-prefixes "org-lint" '("org-lint-")) + + +;;; Generated autoloads from org-list.el + +(register-definition-prefixes "org-list" '("org-")) + + ;;; Generated autoloads from org-macro.el (register-definition-prefixes "org-macro" '("org-macro-")) -;;;*** -;;;### (autoloads nil "org-mouse" "org-mouse.el" (0 0 0 0)) +;;; Generated autoloads from org-macs.el + +(register-definition-prefixes "org-macs" '("org-")) + + +;;; Generated autoloads from org-mobile.el + +(register-definition-prefixes "org-mobile" '("org-mobile-")) + + ;;; Generated autoloads from org-mouse.el (register-definition-prefixes "org-mouse" '("org-")) -;;;*** -;;;### (autoloads nil "org-pcomplete" "org-pcomplete.el" (0 0 0 0)) +;;; Generated autoloads from org-num.el + +(register-definition-prefixes "org-num" '("org-num-")) + + ;;; Generated autoloads from org-pcomplete.el (register-definition-prefixes "org-pcomplete" '("org-" "pcomplete/org-mode/")) -;;;*** -;;;### (autoloads nil "org-persist" "org-persist.el" (0 0 0 0)) ;;; Generated autoloads from org-persist.el (register-definition-prefixes "org-persist" '("org-persist-")) -;;;*** -;;;### (autoloads nil "org-protocol" "org-protocol.el" (0 0 0 0)) +;;; Generated autoloads from org-plot.el + +(register-definition-prefixes "org-plot" '("org-")) + + ;;; Generated autoloads from org-protocol.el (register-definition-prefixes "org-protocol" '("org-")) -;;;*** -;;;### (autoloads nil "org-src" "org-src.el" (0 0 0 0)) +;;; Generated autoloads from org-refile.el + +(register-definition-prefixes "org-refile" '("org-")) + + ;;; Generated autoloads from org-src.el (register-definition-prefixes "org-src" '("org-")) -;;;*** -;;;### (autoloads nil "org-tempo" "org-tempo.el" (0 0 0 0)) +;;; Generated autoloads from org-table.el + +(register-definition-prefixes "org-table" '("org")) + + ;;; Generated autoloads from org-tempo.el (register-definition-prefixes "org-tempo" '("org-tempo-")) -;;;*** -;;;### (autoloads nil "org-version" "org-version.el" (0 0 0 0)) +;;; Generated autoloads from org-timer.el + +(register-definition-prefixes "org-timer" '("org-timer-")) + + ;;; Generated autoloads from org-version.el (autoload 'org-release "org-version" "\ The release version of Org. -Inserted by installing Org mode or when a release is made." nil nil) - +Inserted by installing Org mode or when a release is made.") (autoload 'org-git-version "org-version" "\ The Git version of Org mode. -Inserted by installing Org or when a release is made." nil nil) +Inserted by installing Org or when a release is made.") + + +;;; Generated autoloads from ox.el + +(register-definition-prefixes "ox" '("org-")) + + +;;; Generated autoloads from ox-ascii.el + +(register-definition-prefixes "ox-ascii" '("org-")) + + +;;; Generated autoloads from ox-beamer.el + +(register-definition-prefixes "ox-beamer" '("org-beamer-")) + + +;;; Generated autoloads from ox-html.el + +(register-definition-prefixes "ox-html" '("org-")) + + +;;; Generated autoloads from ox-icalendar.el + +(register-definition-prefixes "ox-icalendar" '("org-icalendar-")) -;;;*** -;;;### (autoloads nil "ox-koma-letter" "ox-koma-letter.el" (0 0 0 -;;;;;; 0)) ;;; Generated autoloads from ox-koma-letter.el (autoload 'org-koma-letter-export-as-latex "ox-koma-letter" "\ @@ -1144,8 +1111,7 @@ Export is done in a buffer named \"*Org KOMA-LETTER Export*\". It will be displayed if `org-export-show-temporary-export-buffer' is non-nil. -\(fn &optional ASYNC SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST)" t nil) - +(fn &optional ASYNC SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST)" t) (autoload 'org-koma-letter-export-to-latex "ox-koma-letter" "\ Export current buffer as a KOMA Scrlttr2 letter (tex). @@ -1177,8 +1143,7 @@ directory. Return output file's name. -\(fn &optional ASYNC SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST)" t nil) - +(fn &optional ASYNC SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST)" t) (autoload 'org-koma-letter-export-to-pdf "ox-koma-letter" "\ Export current buffer as a KOMA Scrlttr2 letter (pdf). @@ -1207,37 +1172,54 @@ file-local settings. Return PDF file's name. -\(fn &optional ASYNC SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST)" t nil) - +(fn &optional ASYNC SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST)" t) (register-definition-prefixes "ox-koma-letter" '("org-koma-letter-")) -;;;*** -;;;### (autoloads nil "ox-man" "ox-man.el" (0 0 0 0)) +;;; Generated autoloads from ox-latex.el + +(register-definition-prefixes "ox-latex" '("org-")) + + ;;; Generated autoloads from ox-man.el (register-definition-prefixes "ox-man" '("org-man-")) -;;;*** -;;;### (autoloads nil nil ("ob-core.el" "ob-lob.el" "ob-matlab.el" -;;;;;; "ob-tangle.el" "ob.el" "ol-bbdb.el" "ol-irc.el" "ol.el" "org-archive.el" -;;;;;; "org-attach.el" "org-clock.el" "org-colview.el" "org-compat.el" -;;;;;; "org-datetree.el" "org-duration.el" "org-element.el" "org-feed.el" -;;;;;; "org-footnote.el" "org-goto.el" "org-id.el" "org-indent.el" -;;;;;; "org-keys.el" "org-lint.el" "org-list.el" "org-loaddefs.el" -;;;;;; "org-macs.el" "org-mobile.el" "org-num.el" "org-pkg.el" "org-plot.el" -;;;;;; "org-refile.el" "org-table.el" "org-timer.el" "ox-ascii.el" -;;;;;; "ox-beamer.el" "ox-html.el" "ox-icalendar.el" "ox-latex.el" -;;;;;; "ox-md.el" "ox-odt.el" "ox-org.el" "ox-publish.el" "ox-texinfo.el" -;;;;;; "ox.el") (0 0 0 0)) +;;; Generated autoloads from ox-md.el + +(register-definition-prefixes "ox-md" '("org-")) -;;;*** +;;; Generated autoloads from ox-odt.el + +(register-definition-prefixes "ox-odt" '("org-odt-")) + + +;;; Generated autoloads from ox-org.el + +(register-definition-prefixes "ox-org" '("org-org-")) + + +;;; Generated autoloads from ox-publish.el + +(register-definition-prefixes "ox-publish" '("org-publish-")) + + +;;; Generated autoloads from ox-texinfo.el + +(register-definition-prefixes "ox-texinfo" '("org-")) + +;;; End of scraped data + +(provide 'org-autoloads) + ;; Local Variables: ;; version-control: never ;; no-byte-compile: t ;; no-update-autoloads: t -;; coding: utf-8 +;; no-native-compile: t +;; coding: utf-8-emacs-unix ;; End: + ;;; org-autoloads.el ends here diff --git a/elpa/org-9.6.7/org-capture.el b/elpa/org-9.7.17/org-capture.el similarity index 96% rename from elpa/org-9.6.7/org-capture.el rename to elpa/org-9.7.17/org-capture.el index a696c615..f10e3693 100644 --- a/elpa/org-9.6.7/org-capture.el +++ b/elpa/org-9.7.17/org-capture.el @@ -1,9 +1,9 @@ ;;; org-capture.el --- Fast note taking in Org -*- lexical-binding: t; -*- -;; Copyright (C) 2010-2023 Free Software Foundation, Inc. +;; Copyright (C) 2010-2024 Free Software Foundation, Inc. ;; Author: Carsten Dominik -;; Keywords: outlines, hypermedia, calendar, wp +;; Keywords: outlines, hypermedia, calendar, text ;; URL: https://orgmode.org ;; ;; This file is part of GNU Emacs. @@ -58,11 +58,13 @@ (declare-function org-at-table-p "org-table" (&optional table-type)) (declare-function org-clock-update-mode-line "org-clock" (&optional refresh)) (declare-function org-datetree-find-date-create "org-datetree" (date &optional keep-restriction)) -(declare-function org-datetree-find-month-create (d &optional keep-restriction)) +(declare-function org-datetree-find-month-create "org-datetree" (d &optional keep-restriction)) (declare-function org-decrypt-entry "org-crypt" ()) (declare-function org-element-at-point "org-element" (&optional pom cached-only)) -(declare-function org-element-lineage "org-element" (datum &optional types with-self)) -(declare-function org-element-property "org-element" (property element)) +(declare-function org-element-lineage "org-element-ast" (datum &optional types with-self)) +(declare-function org-element-property "org-element-ast" (property node)) +(declare-function org-element-contents-end "org-element" (node)) +(declare-function org-element-post-affiliated "org-element" (node)) (declare-function org-encrypt-entry "org-crypt" ()) (declare-function org-insert-link "ol" (&optional complete-file link-location default-description)) (declare-function org-link-make-string "ol" (link &optional description)) @@ -220,6 +222,9 @@ target Specification of where the captured item should be placed. (clock) File to the entry that is currently being clocked + (here) + The position of point + (function function-finding-location) Most general way: write your own function which both visits the file and moves point to the right location @@ -366,6 +371,10 @@ be replaced with content and expanded: %^{prompt} Prompt the user for a string and replace this sequence with it. A default value and a completion table can be specified like this: %^{prompt|default|completion2|completion3|...}. + %^{prompt}X where X is one of g, G, t, T, u, U, C, or L. + Same as %^X (see above), but also supply custom + prompt/completions. Default value and completions as in + %^{prompt|default|...}X are allowed. %? After completing the template, position cursor here. %\\1 ... %\\N Insert the text entered at the nth %^{prompt}, where N is a number, starting from 1. @@ -393,14 +402,13 @@ calendar | %:type %:date When you need to insert a literal percent sign in the template, you can escape ambiguous cases with a backward slash, e.g., \\%i." :group 'org-capture - :package-version '(Org . "9.6") + :package-version '(Org . "9.7") :set (lambda (s v) (set-default-toplevel-value s (org-capture-upgrade-templates v))) :type (let ((file-variants '(choice :tag "Filename " (file :tag "Literal") (function :tag "Function") - (variable :tag "Variable") - (sexp :tag "Form")))) + (variable :tag "Variable")))) `(repeat (choice :value ("" "" entry (file "~/org/notes.org") "") (list :tag "Multikey description" @@ -443,12 +451,12 @@ you can escape ambiguous cases with a backward slash, e.g., \\%i." (list :tag "File & function" (const :format "" file+function) ,file-variants - (sexp :tag " Function")) + (function :tag " Function")) (list :tag "Current clocking task" (const :format "" clock)) (list :tag "Function" (const :format "" function) - (sexp :tag " Function"))) + (function :tag " Function"))) (choice :tag "Template " (string) (list :tag "File" @@ -496,12 +504,6 @@ The capture buffer is current and still narrowed." :version "24.1" :type 'hook) -(defcustom org-capture-bookmark t - "When non-nil, add bookmark pointing at the last stored position when capturing." - :group 'org-capture - :version "24.3" - :type 'boolean) - ;;; The property list for keeping information about the capture process (defvar org-capture-plist nil @@ -579,7 +581,9 @@ this template to be accessible only from `message-mode' buffers, use this: (setq org-capture-templates-contexts - \\='((\"c\" ((in-mode . \"message-mode\"))))) + \\='((\"c\" ((in-mode . \"message-mode\"))) + (\"d\" (my-context-function + (in-mode . \"org-mode\"))))) Here are the available contexts definitions: @@ -889,10 +893,16 @@ captured item after finalizing." (goto-char (+ size pos)) (goto-char (if (< ipt pos) (+ size pos) pos)))))) - ;; Kill the target buffer if that is desired - (when (and base-buffer new-buffer kill-buffer) - (with-current-buffer base-buffer (save-buffer)) - (kill-buffer base-buffer)) + (if (and base-buffer org-note-abort new-buffer) + ;; Unconditionally kill the new buffer when capture is + ;; aborted. + (with-current-buffer base-buffer + (set-buffer-modified-p nil) + (kill-buffer)) + ;; Kill the target buffer if that is desired + (when (and base-buffer new-buffer kill-buffer) + (with-current-buffer base-buffer (save-buffer)) + (kill-buffer base-buffer))) ;; Restore the window configuration before capture (set-window-configuration return-wconf)) @@ -985,14 +995,15 @@ Store them in the capture property list." (let ((target-entry-p t)) (save-excursion (pcase (or target (org-capture-get :target)) - (`here + ((or `here + `(here)) (org-capture-put :exact-position (point) :insert-here t)) (`(file ,path) (set-buffer (org-capture-target-buffer path)) (org-capture-put-target-region-and-position) (widen) (setq target-entry-p nil)) - (`(id ,id) + (`(id ,(and id (or (pred stringp) (pred symbolp)))) (pcase (org-id-find id) (`(,path . ,position) (set-buffer (org-capture-target-buffer path)) @@ -1000,7 +1011,7 @@ Store them in the capture property list." (org-capture-put-target-region-and-position) (goto-char position)) (_ (error "Cannot find target ID \"%s\"" id)))) - (`(file+headline ,path ,headline) + (`(file+headline ,path ,(and headline (pred stringp))) (set-buffer (org-capture-target-buffer path)) ;; Org expects the target file to be in Org mode, otherwise ;; it throws an error. However, the default notes files @@ -1017,12 +1028,12 @@ Store them in the capture property list." (if (re-search-forward (format org-complex-heading-regexp-format (regexp-quote headline)) nil t) - (beginning-of-line) + (forward-line 0) (goto-char (point-max)) (unless (bolp) (insert "\n")) (insert "* " headline "\n") - (beginning-of-line 0))) - (`(file+olp ,path . ,outline-path) + (forward-line -1))) + (`(file+olp ,path . ,(and outline-path (guard outline-path))) (let ((m (org-find-olp (cons (org-capture-expand-file path) outline-path)))) (set-buffer (marker-buffer m)) @@ -1030,7 +1041,7 @@ Store them in the capture property list." (widen) (goto-char m) (set-marker m nil))) - (`(file+regexp ,path ,regexp) + (`(file+regexp ,path ,(and regexp (pred stringp))) (set-buffer (org-capture-target-buffer path)) (org-capture-put-target-region-and-position) (widen) @@ -1098,7 +1109,7 @@ Store them in the capture property list." ;; the following is the keep-restriction argument for ;; org-datetree-find-date-create (when outline-path 'subtree-at-point)))) - (`(file+function ,path ,function) + (`(file+function ,path ,(and function (pred functionp))) (set-buffer (org-capture-target-buffer path)) (org-capture-put-target-region-and-position) (widen) @@ -1106,7 +1117,7 @@ Store them in the capture property list." (org-capture-put :exact-position (point)) (setq target-entry-p (and (derived-mode-p 'org-mode) (org-at-heading-p)))) - (`(function ,fun) + (`(function ,(and fun (pred functionp))) (funcall fun) (org-capture-put :exact-position (point)) (setq target-entry-p @@ -1162,9 +1173,9 @@ When INHIBIT-WCONF-STORE is non-nil, don't store the window configuration, as it may have been stored before." (unless inhibit-wconf-store (org-capture-put :return-to-wconf (current-window-configuration))) - (delete-other-windows) - (org-switch-to-buffer-other-window - (org-capture-get-indirect-buffer (org-capture-get :buffer) "CAPTURE")) + (pop-to-buffer + (org-capture-get-indirect-buffer (org-capture-get :buffer) "CAPTURE") + '(org-display-buffer-split)) (widen) (org-fold-show-all) (goto-char (org-capture-get :pos)) @@ -1262,7 +1273,7 @@ may have been stored before." (catch :found (while (re-search-forward item-regexp end t) (when (setq item (org-element-lineage - (org-element-at-point) '(plain-list) t)) + (org-element-at-point) 'plain-list t)) (goto-char (org-element-property (if prepend? :post-affiliated :contents-end) item)) @@ -1304,7 +1315,7 @@ may have been stored before." (point-marker)))) (when item (let ((i (save-excursion - (goto-char (org-element-property :post-affiliated item)) + (goto-char (org-element-post-affiliated item)) (org-current-text-indentation)))) (save-excursion (goto-char beg) @@ -1312,7 +1323,7 @@ may have been stored before." (while (< (point) end) (indent-to i) (forward-line))) - ;; Pre-pending an item could change the type of the list + ;; Prepending an item could change the type of the list ;; if there is a mismatch. In this situation, ;; prioritize the existing list. (when prepend? @@ -1367,13 +1378,13 @@ may have been stored before." ;; Narrow to the table, possibly creating one if necessary. (catch :found (while (re-search-forward org-table-dataline-regexp end t) - (pcase (org-element-lineage (org-element-at-point) '(table) t) + (pcase (org-element-lineage (org-element-at-point) 'table t) (`nil nil) ((pred (lambda (e) (eq 'table.el (org-element-property :type e)))) nil) (table - (goto-char (org-element-property :contents-end table)) - (narrow-to-region (org-element-property :post-affiliated table) + (goto-char (org-element-contents-end table)) + (narrow-to-region (org-element-post-affiliated table) (point)) (throw :found t)))) ;; No table found. Create it with an empty header. @@ -1403,7 +1414,7 @@ may have been stored before." (goto-char (point-min)) (cond ((not (re-search-forward org-table-hline-regexp nil t))) - ((re-search-forward org-table-dataline-regexp nil t) (beginning-of-line)) + ((re-search-forward org-table-dataline-regexp nil t) (forward-line 0)) (t (goto-char (org-table-end))))) (t (goto-char (org-table-end)))) @@ -1492,10 +1503,15 @@ Of course, if exact position has been required, just put it there." (point)))))) (with-current-buffer (buffer-base-buffer (current-buffer)) (org-with-point-at pos - (when org-capture-bookmark + ;; FIXME: `org-capture-bookmark' is obsolete. To be removed + ;; in future Org releases. + (when (with-no-warnings org-capture-bookmark) (let ((bookmark (plist-get org-bookmark-names-plist :last-capture))) - (when bookmark (with-demoted-errors "Bookmark set error: %S" - (bookmark-set bookmark))))) + (when bookmark + (condition-case err + (bookmark-set bookmark) + (error + (message "Bookmark set error: %S" err)))))) (move-marker org-capture-last-stored-marker (point)))))) (defun org-capture-narrow (beg end) @@ -1658,12 +1674,12 @@ Expansion occurs in a temporary Org mode buffer." (org-no-properties org-clock-heading) "")) (v-K (if (marker-buffer org-clock-marker) - (org-link-make-string - (format "%s::*%s" - (buffer-file-name (marker-buffer org-clock-marker)) - v-k) - v-k) - "")) + (let ((original-link-plist org-store-link-plist) + (clocked-task-link (org-with-point-at org-clock-marker + (org-store-link nil nil)))) + (setq org-store-link-plist original-link-plist) + clocked-task-link) + "")) (v-f (or (org-capture-get :original-file-nondirectory) "")) (v-F (or (org-capture-get :original-file) "")) (org-capture--clipboards @@ -1680,7 +1696,7 @@ Expansion occurs in a temporary Org mode buffer." (message "no template") (ding) (sit-for 1)) (save-window-excursion - (org-switch-to-buffer-other-window (get-buffer-create "*Capture*")) + (switch-to-buffer-other-window (get-buffer-create "*Capture*")) (erase-buffer) (setq buffer-file-name nil) (setq mark-active nil) @@ -1852,7 +1868,7 @@ Expansion occurs in a temporary Org mode buffer." (let* ((upcase? (equal (upcase key) key)) (org-end-time-was-given nil) (time (org-read-date upcase? t nil prompt))) - (org-insert-time-stamp + (org-insert-timestamp time (or org-time-was-given upcase?) (member key '("u" "U")) nil nil (list org-end-time-was-given)))) diff --git a/elpa/org-9.6.7/org-clock.el b/elpa/org-9.7.17/org-clock.el similarity index 91% rename from elpa/org-9.6.7/org-clock.el rename to elpa/org-9.7.17/org-clock.el index d7fe14cd..7ac4f27a 100644 --- a/elpa/org-9.6.7/org-clock.el +++ b/elpa/org-9.7.17/org-clock.el @@ -1,9 +1,9 @@ ;;; org-clock.el --- The time clocking code for Org mode -*- lexical-binding: t; -*- -;; Copyright (C) 2004-2023 Free Software Foundation, Inc. +;; Copyright (C) 2004-2024 Free Software Foundation, Inc. ;; Author: Carsten Dominik -;; Keywords: outlines, hypermedia, calendar, wp +;; Keywords: outlines, hypermedia, calendar, text ;; URL: https://orgmode.org ;; ;; This file is part of GNU Emacs. @@ -36,9 +36,11 @@ (declare-function calendar-iso-to-absolute "cal-iso" (date)) (declare-function notifications-notify "notifications" (&rest params)) -(declare-function org-element-property "org-element" (property element)) -(declare-function org-element-type "org-element" (element)) -(declare-function org-element--cache-active-p "org-element" ()) +(declare-function org-element-property "org-element-ast" (property node)) +(declare-function org-element-contents-end "org-element" (node)) +(declare-function org-element-end "org-element" (node)) +(declare-function org-element-type "org-element-ast" (node &optional anonymous)) +(declare-function org-element-type-p "org-element-ast" (node types)) (defvar org-element-use-cache) (declare-function org-inlinetask-at-task-p "org-inlinetask" ()) (declare-function org-inlinetask-goto-beginning "org-inlinetask" ()) @@ -51,6 +53,11 @@ (declare-function org-dynamic-block-define "org" (type func)) (declare-function w32-notification-notify "w32fns.c" (&rest params)) (declare-function w32-notification-close "w32fns.c" (&rest params)) +(declare-function dbus-list-activatable-names "dbus" (&optional bus)) +(declare-function dbus-call-method "dbus" (bus service path interface method &rest args)) +(declare-function dbus-get-property "dbus" (bus service path interface property)) +(declare-function haiku-notifications-notify "haikuselect.c") +(declare-function android-notifications-notify "androidselect.c") (defvar org-frame-title-format-backup nil) (defvar org-state) @@ -125,7 +132,7 @@ clocking out." "Rounding minutes when clocking in or out. The default value is 0 so that no rounding is done. When set to a non-integer value, use the car of -`org-time-stamp-rounding-minutes', like for setting a time-stamp. +`org-timestamp-rounding-minutes', like for setting a timestamp. E.g. if `org-clock-rounding-minutes' is set to 5, time is 14:47 and you clock in: then the clock starts at 14:45. If you clock @@ -344,14 +351,16 @@ For more information, see `org-clocktable-write-default'." :version "24.1" :type 'function) -;; FIXME: translate es and nl last string "Clock summary at" (defcustom org-clock-clocktable-language-setup - '(("en" "File" "L" "Timestamp" "Headline" "Time" "ALL" "Total time" "File time" "Clock summary at") - ("es" "Archivo" "N" "Fecha y hora" "Tarea" "Tiempo" "TODO" "Tiempo total" "Tiempo archivo" "Clock summary at") - ("fr" "Fichier" "N" "Horodatage" "En-tête" "Durée" "TOUT" "Durée totale" "Durée fichier" "Horodatage sommaire à") - ("nl" "Bestand" "N" "Tijdstip" "Hoofding" "Duur" "ALLES" "Totale duur" "Bestandstijd" "Clock summary at") - ("de" "Datei" "E" "Zeitstempel" "Kopfzeile" "Dauer" "GESAMT" - "Gesamtdauer" "Dateizeit" "Erstellt am")) + '(("en" "File" "L" "Timestamp" "Headline" "Time" "ALL" "Total time" "File time" "Clock summary at") + ("de" "Datei" "E" "Zeitstempel" "Kopfzeile" "Dauer" "GESAMT" "Gesamtdauer" "Dateizeit" "Erstellt am") + ("es" "Archivo" "N" "Fecha y hora" "Tarea" "Duración" "TODO" "Duración total" "Tiempo archivo" "Generado el") + ("fr" "Fichier" "N" "Horodatage" "En-tête" "Durée" "TOUT" "Durée totale" "Durée fichier" "Horodatage sommaire à") + ("nl" "Bestand" "N" "Tijdstip" "Rubriek" "Duur" "ALLES" "Totale duur" "Bestandstijd" "Klok overzicht op") + ("nn" "Fil" "N" "Tidspunkt" "Overskrift" "Tid" "ALLE" "Total tid" "Filtid" "Tidsoversyn") + ("pl" "Plik" "P" "Data i godzina" "Nagłówek" "Czas" "WSZYSTKO" "Czas całkowity" "Czas pliku" "Poddumowanie zegara na") + ("pt-BR" "Arquivo" "N" "Data e hora" "Título" "Hora" "TODOS" "Hora total" "Hora do arquivo" "Resumo das horas em") + ("sk" "Súbor" "L" "Časová značka" "Záhlavie" "Čas" "VÅ ETKO" "Celkový čas" "Čas súboru" "Časový súhrn pre")) "Terms used in clocktable, translated to different languages." :group 'org-clocktable :version "24.1" @@ -411,8 +420,8 @@ play with them." :type 'string) (defcustom org-clock-clocked-in-display 'mode-line - "When clocked in for a task, Org can display the current -task and accumulated time in the mode line and/or frame title. + "Where to display clocked in task and accumulated time when clocked in. + Allowed values are: both displays in both mode line and frame title @@ -438,7 +447,9 @@ This uses the same format as `frame-title-format', which see." :group 'org-clock :type 'sexp) -(defcustom org-clock-x11idle-program-name "x11idle" +(defcustom org-clock-x11idle-program-name + (if (executable-find "xprintidle") + "xprintidle" "x11idle") "Name of the program which prints X11 idle time in milliseconds. you can do \"~$ sudo apt-get install xprintidle\" if you are using @@ -447,8 +458,7 @@ a Debian-based distribution. Alternatively, can find x11idle.c in https://orgmode.org/worg/code/scripts/x11idle.c" :group 'org-clock - :version "24.4" - :package-version '(Org . "8.0") + :package-version '(Org . "9.7") :type 'string) (defcustom org-clock-goto-before-context 2 @@ -506,7 +516,11 @@ to add an effort property.") (defvar org-clock-in-hook nil "Hook run when starting the clock.") (defvar org-clock-out-hook nil - "Hook run when stopping the current clock.") + "Hook run when stopping the current clock. +The point is at the current clock line when the hook is executed. + +The hook functions can access `org-clock-out-removed-last-clock' to +check whether the latest CLOCK line has been cleared.") (defvar org-clock-cancel-hook nil "Hook run when canceling the current clock.") @@ -560,6 +574,10 @@ of a different task.") Assume S in the English term to translate. Return S as-is if it cannot be translated." (or (nth (pcase s + ;; "L" stands for "Level" + ;; "ALL" stands for a line summarizing clock data across + ;; all the files, when the clocktable includes multiple + ;; files. ("File" 1) ("L" 2) ("Timestamp" 3) ("Headline" 4) ("Time" 5) ("ALL" 6) ("Total time" 7) ("File time" 8) ("Clock summary at" 9)) (assoc-string language org-clock-clocktable-language-setup t)) @@ -574,6 +592,7 @@ cannot be translated." (org-no-properties (org-get-heading t t t t)))))) (defun org-clock-menu () + "Pop up org-clock menu." (interactive) (popup-menu '("Clock" @@ -583,7 +602,12 @@ cannot be translated." ["Switch task" (lambda () (interactive) (org-clock-in '(4))) :active t :keys "C-u C-c C-x C-i"]))) (defun org-clock-history-push (&optional pos buffer) - "Push a marker to the clock history." + "Push point marker to the clock history. +When POS is provided, use it as marker point. +When BUFFER and POS are provided, use marker at POS in base buffer of +BUFFER." + ;; When buffer is provided, POS must be provided. + (cl-assert (or (not buffer) pos)) (setq org-clock-history-length (max 1 org-clock-history-length)) (let ((m (move-marker (make-marker) (or pos (point)) (org-base-buffer @@ -603,7 +627,10 @@ cannot be translated." (push m org-clock-history))) (defun org-clock-save-markers-for-cut-and-paste (beg end) - "Save relative positions of markers in region." + "Save relative positions of markers in region BEG..END. +Save `org-clock-marker', `org-clock-hd-marker', +`org-clock-default-task', `org-clock-interrupted-task', and the +markers in `org-clock-history'." (org-check-and-save-marker org-clock-marker beg end) (org-check-and-save-marker org-clock-hd-marker beg end) (org-check-and-save-marker org-clock-default-task beg end) @@ -629,6 +656,7 @@ cannot be translated." (defun org-clock-select-task (&optional prompt) "Select a task that was recently associated with clocking. +PROMPT is the prompt text to be used, as a string. Return marker position of the selected task. Raise an error if there is no recent clock to choose from." (let (och chl sel-list rpl (i 0) s) @@ -639,7 +667,7 @@ there is no recent clock to choose from." (if (zerop chl) (user-error "No recent clock") (save-window-excursion - (org-switch-to-buffer-other-window + (switch-to-buffer-other-window (get-buffer-create "*Clock Task Select*")) (erase-buffer) (when (marker-buffer org-clock-default-task) @@ -669,8 +697,11 @@ there is no recent clock to choose from." ;; `fit-window-to-buffer' (fit-window-to-buffer nil nil (if (< chl 10) chl (+ 5 chl))) (message (or prompt "Select task for clocking:")) - (setq cursor-type nil rpl (read-char-exclusive)) - (kill-buffer) + (unwind-protect (setq cursor-type nil rpl (read-char-exclusive)) + (when-let* ((window (get-buffer-window "*Clock Task Select*" t))) + (quit-window 'kill window)) + (when (get-buffer "*Clock Task Select*") + (kill-buffer "*Clock Task Select*"))) (cond ((eq rpl ?q) nil) ((eq rpl ?x) nil) @@ -779,6 +810,7 @@ previous clocking intervals." 60))) (+ currently-clocked-time (or org-clock-total-time 0)))) +;;;###autoload (defun org-clock-modify-effort-estimate (&optional value) "Add to or set the effort estimate of the item currently being clocked. VALUE can be a number of minutes, or a string with format hh:mm or mm. @@ -855,6 +887,18 @@ use libnotify if available, or fall back on a message." ((stringp org-show-notification-handler) (start-process "emacs-timer-notification" nil org-show-notification-handler notification)) + ((fboundp 'haiku-notifications-notify) + ;; N.B. timeouts are not available under Haiku. + (haiku-notifications-notify :title "Org mode message" + :body notification + :urgency 'low)) + ((fboundp 'android-notifications-notify) + ;; N.B. timeouts are not available under Haiku or Android. + (android-notifications-notify :title "Org mode message" + :body notification + ;; Low urgency notifications + ;; are by default hidden. + :urgency 'normal)) ((fboundp 'w32-notification-notify) (let ((id (w32-notification-notify :title "Org mode message" @@ -897,7 +941,7 @@ If CLOCK-SOUND is non-nil, it overrides `org-clock-sound'." (if (executable-find "aplay") (start-process "org-clock-play-notification" nil "aplay" file) - (condition-case nil + (condition-case-unless-debug nil (play-sound-file file) (error (beep t) (beep t)))))))))) @@ -914,9 +958,11 @@ If CLOCK-SOUND is non-nil, it overrides `org-clock-sound'." (save-excursion (goto-char (point-min)) (while (re-search-forward org-clock-re nil t) - (push (cons (copy-marker (match-end 1) t) - (org-time-string-to-time (match-string 1))) - clocks)))) + (when (save-match-data + (org-element-type-p (org-element-at-point) 'clock)) + (push (cons (copy-marker (match-end 1) t) + (org-time-string-to-time (match-string 1))) + clocks))))) clocks)) (defsubst org-is-active-clock (clock) @@ -930,7 +976,7 @@ If CLOCK-SOUND is non-nil, it overrides `org-clock-sound'." `(with-current-buffer (marker-buffer (car ,clock)) (org-with-wide-buffer (goto-char (car ,clock)) - (beginning-of-line) + (forward-line 0) ,@forms))) (defmacro org-with-clock (clock &rest forms) @@ -1036,8 +1082,8 @@ CLOCK is a cons cell of the form (MARKER START-TIME)." (catch 'exit (while (re-search-backward drawer-re beg t) (let ((element (org-element-at-point))) - (when (eq (org-element-type element) 'drawer) - (when (> (org-element-property :end element) (car clock)) + (when (org-element-type-p element 'drawer) + (when (> (org-element-end element) (car clock)) (org-fold-hide-drawer-toggle 'off nil element)) (throw 'exit nil))))))))))) @@ -1212,6 +1258,27 @@ If `only-dangling-p' is non-nil, only ask to resolve dangling "Return the current X11 idle time in seconds." (/ (string-to-number (shell-command-to-string org-clock-x11idle-program-name)) 1000)) +(defvar org-logind-dbus-session-path + (when (and (boundp 'dbus-runtime-version) + (require 'dbus nil t) + (member "org.freedesktop.login1" (dbus-list-activatable-names))) + (ignore-errors + (dbus-call-method + :system "org.freedesktop.login1" + "/org/freedesktop/login1" + "org.freedesktop.login1.Manager" + "GetSessionByPID" (emacs-pid)))) + "D-Bus session path for the elogind interface.") + +(defun org-logind-user-idle-seconds () + "Return the number of idle seconds for the user according to logind." + (- (float-time) + (/ (dbus-get-property + :system "org.freedesktop.login1" + org-logind-dbus-session-path + "org.freedesktop.login1.Session" "IdleSinceHint") + 1e6))) + (defun org-user-idle-seconds () "Return the number of seconds the user has been idle for. This routine returns a floating point number." @@ -1220,6 +1287,13 @@ This routine returns a floating point number." (org-mac-idle-seconds)) ((and (eq window-system 'x) org-x11idle-exists-p) (org-x11-idle-seconds)) + ((and + org-logind-dbus-session-path + (dbus-get-property + :system "org.freedesktop.login1" + org-logind-dbus-session-path + "org.freedesktop.login1.Session" "IdleHint")) + (org-logind-user-idle-seconds)) (t (org-emacs-idle-seconds)))) @@ -1277,8 +1351,6 @@ time as the start time. See `org-clock-continuously' to make this the default behavior." (interactive "P") (setq org-clock-notification-was-shown nil) - (unless org-element-use-cache - (org-refresh-effort-properties)) (catch 'abort (let ((interrupting (and (not org-clock-resolving-clocks-due-to-idleness) (org-clocking-p))) @@ -1356,8 +1428,8 @@ the default behavior." (when newstate (org-todo newstate)))) ((and org-clock-in-switch-to-state (not (looking-at (concat org-outline-regexp "[ \t]*" - org-clock-in-switch-to-state - "\\>")))) + org-clock-in-switch-to-state + "\\(?:[ \t]\\|$\\)")))) (org-todo org-clock-in-switch-to-state))) (setq org-clock-heading (org-clock--mode-line-heading)) (org-clock-find-position org-clock-in-resume) @@ -1383,12 +1455,15 @@ the default behavior." (sit-for 2) (throw 'abort nil)) (t + ;; Make sure that point moves after clock line upon + ;; inserting it. Then, users can continue typing even if + ;; point was right where the clock is inserted. (insert-before-markers-and-inherit "\n") (backward-char 1) (when (and (save-excursion (end-of-line 0) (org-in-item-p))) - (beginning-of-line 1) + (forward-line 0) (indent-line-to (max 0 (- (current-indentation) 2)))) (insert-and-inherit org-clock-string " ") (setq org-clock-effort (org-entry-get (point) org-effort-property)) @@ -1408,8 +1483,8 @@ the default behavior." leftover) start-time (org-current-time org-clock-rounding-minutes t))) - (setq ts (org-insert-time-stamp org-clock-start-time - 'with-hm 'inactive)) + (setq ts (org-insert-timestamp org-clock-start-time + 'with-hm 'inactive)) (org-indent-line))) (move-marker org-clock-marker (point) (buffer-base-buffer)) (move-marker org-clock-hd-marker @@ -1445,6 +1520,33 @@ the default behavior." (message "Clock starts at %s - %s" ts org--msg-extra) (run-hooks 'org-clock-in-hook)))))) +(defvar org-clock--auto-clockout-timer-obj nil + "Timer object holding the existing clockout timer.") +(defun org-clock--auto-clockout-maybe () + "Clock out the currently clocked in task when idle. +See `org-clock-auto-clockout-timer' to set the idle time span. + +This function is to be called by a timer." + (when (and (numberp org-clock-auto-clockout-timer) + org-clock-current-task) + (let ((user-idle-seconds (org-user-idle-seconds))) + (cond + ;; Already idle. Clock out. + ((>= user-idle-seconds org-clock-auto-clockout-timer) + (setq org-clock--auto-clockout-timer-obj nil) + (org-clock-out)) + ;; Emacs is idle but system is not. Retry assuming that system will remain idle. + ((>= (org-emacs-idle-seconds) org-clock-auto-clockout-timer) + (setq org-clock--auto-clockout-timer-obj + (run-with-timer + (- org-clock-auto-clockout-timer user-idle-seconds) + nil #'org-clock--auto-clockout-maybe))) + ;; Emacs is not idle. Check again next time we are idle. + (t + (setq org-clock--auto-clockout-timer-obj + (run-with-idle-timer + org-clock-auto-clockout-timer nil #'org-clock--auto-clockout-maybe))))))) + (defun org-clock-auto-clockout () "Clock out the currently clocked in task if Emacs is idle. See `org-clock-auto-clockout-timer' to set the idle time span. @@ -1452,9 +1554,11 @@ See `org-clock-auto-clockout-timer' to set the idle time span. This is only effective when `org-clock-auto-clockout-insinuate' is present in the user configuration." (when (and (numberp org-clock-auto-clockout-timer) - org-clock-current-task) - (run-with-idle-timer - org-clock-auto-clockout-timer nil #'org-clock-out))) + org-clock-current-task + (not (timerp org-clock--auto-clockout-timer-obj))) + (setq org-clock--auto-clockout-timer-obj + (run-with-idle-timer + org-clock-auto-clockout-timer nil #'org-clock--auto-clockout-maybe)))) ;;;###autoload (defun org-clock-toggle-auto-clockout () @@ -1562,9 +1666,9 @@ line and position cursor in that line." " *\\sw+ +[012][0-9]:[0-5][0-9]\\)\\][ \t]*$"))) (while (re-search-forward open-clock-re end t) (let ((element (org-element-at-point))) - (when (and (eq (org-element-type element) 'clock) + (when (and (org-element-type-p element 'clock) (eq (org-element-property :status element) 'running)) - (beginning-of-line) + (forward-line 0) (throw 'exit t)))))) ;; Look for an existing clock drawer. (when drawer @@ -1572,8 +1676,8 @@ line and position cursor in that line." (let ((drawer-re (concat "^[ \t]*:" (regexp-quote drawer) ":[ \t]*$"))) (while (re-search-forward drawer-re end t) (let ((element (org-element-at-point))) - (when (eq (org-element-type element) 'drawer) - (let ((cend (org-element-property :contents-end element))) + (when (org-element-type-p element 'drawer) + (let ((cend (org-element-contents-end element))) (if (and (not org-log-states-order-reversed) cend) (goto-char cend) (forward-line)) @@ -1586,7 +1690,7 @@ line and position cursor in that line." (save-excursion (while (re-search-forward clock-re end t) (let ((element (org-element-at-point))) - (when (eq (org-element-type element) 'clock) + (when (org-element-type-p element 'clock) (setq positions (cons (line-beginning-position) positions) count (1+ count)))))) (cond @@ -1594,19 +1698,18 @@ line and position cursor in that line." (org-fold-core-ignore-modifications ;; Skip planning line and property drawer, if any. (org-end-of-meta-data) - (unless (bolp) (insert-and-inherit "\n")) + (unless (bolp) (insert-before-markers-and-inherit "\n")) ;; Create a new drawer if necessary. (when (and org-clock-into-drawer (or (not (wholenump org-clock-into-drawer)) (< org-clock-into-drawer 2))) (let ((beg (point))) - (insert-and-inherit ":" drawer ":\n:END:\n") + ;; Make sure that point moves after drawer upon + ;; inserting it. Then, users can continue typing even + ;; if point was right where the clock is inserted. + (insert-before-markers-and-inherit ":" drawer ":\n:END:\n") (org-indent-region beg (point)) - (if (eq org-fold-core-style 'text-properties) - (org-fold-region - (line-end-position -1) (1- (point)) t 'drawer) - (org-fold-region - (line-end-position -1) (1- (point)) t 'outline)) + (org-fold-region (line-end-position -1) (1- (point)) t 'drawer) (forward-line -1))))) ;; When a clock drawer needs to be created because of the ;; number of clock items or simply if it is missing, collect @@ -1631,13 +1734,13 @@ line and position cursor in that line." "\n:END:\n") (let ((end (point-marker))) (goto-char beg) - (save-excursion (insert-and-inherit ":" drawer ":\n")) + (save-excursion (insert-before-markers-and-inherit ":" drawer ":\n")) (org-fold-region (line-end-position) (1- end) t 'outline) (org-indent-region (point) end) (forward-line) (unless org-log-states-order-reversed (goto-char end) - (beginning-of-line -1)) + (forward-line -2)) (set-marker end nil))))) (org-log-states-order-reversed (goto-char (car (last positions)))) (t (goto-char (car positions)))))))) @@ -1650,6 +1753,11 @@ and current `frame-title-format' is equal to `org-clock-frame-title-format'." (equal frame-title-format org-clock-frame-title-format)) (setq frame-title-format org-frame-title-format-backup))) +(defvar org-clock-out-removed-last-clock nil + "When non-nil, the last `org-clock-out' removed the clock line. +This can happen when `org-clock-out-remove-zero-time-clocks' is set to +non-nil and the latest clock took 0 minutes.") + ;;;###autoload (defun org-clock-out (&optional switch-to-state fail-quietly at-time) "Stop the currently running clock. @@ -1680,7 +1788,7 @@ to, overriding the existing value of `org-clock-out-switch-to-state'." (save-restriction (widen) (goto-char org-clock-marker) - (beginning-of-line 1) + (forward-line 0) (if (and (looking-at (concat "[ \t]*" org-keyword-time-regexp)) (equal (match-string 1) org-clock-string)) (setq ts (match-string 2)) @@ -1689,7 +1797,7 @@ to, overriding the existing value of `org-clock-out-switch-to-state'." (delete-region (point) (line-end-position)) (org-fold-core-ignore-modifications (insert-and-inherit "--") - (setq te (org-insert-time-stamp (or at-time now) 'with-hm 'inactive)) + (setq te (org-insert-timestamp (or at-time now) 'with-hm 'inactive)) (setq s (org-time-convert-to-integer (time-subtract (org-time-string-to-time te) @@ -1728,10 +1836,10 @@ to, overriding the existing value of `org-clock-out-switch-to-state'." (when newstate (org-todo newstate)))) ((and org-clock-out-switch-to-state (not (looking-at - (concat - org-outline-regexp "[ \t]*" - org-clock-out-switch-to-state - "\\>")))) + (concat + org-outline-regexp "[ \t]*" + org-clock-out-switch-to-state + "\\(?:[ \t]\\|$\\)")))) (org-todo org-clock-out-switch-to-state)))))) (force-mode-line-update) (message (if remove @@ -1740,6 +1848,7 @@ to, overriding the existing value of `org-clock-out-switch-to-state'." te (org-duration-from-minutes (+ (* 60 h) m))) (unless (org-clocking-p) (setq org-clock-current-task nil)) + (setq org-clock-out-removed-last-clock remove) (run-hooks 'org-clock-out-hook) ;; Add a note, but only if we didn't remove the clock line. (when (and org-log-note-clock-out (not remove)) @@ -1934,20 +2043,36 @@ PROPNAME lets you set a custom text property instead of :org-clock-minutes." (save-excursion (goto-char (point-max)) (while (re-search-backward re nil t) - (let ((element-type - (org-element-type - (save-match-data - (org-element-at-point))))) + (let* ((element (save-match-data (org-element-at-point))) + (element-type (org-element-type element))) (cond ((and (eq element-type 'clock) (match-end 2)) ;; Two time stamps. - (let* ((ss (match-string 2)) - (se (match-string 3)) - (ts (org-time-string-to-seconds ss)) - (te (org-time-string-to-seconds se)) - (dt (- (if tend (min te tend) te) - (if tstart (max ts tstart) ts)))) - (when (> dt 0) (cl-incf t1 (floor dt 60))))) + (condition-case nil + (let* ((timestamp (org-element-property :value element)) + (ts (float-time + (org-encode-time + (list 0 + (org-element-property :minute-start timestamp) + (org-element-property :hour-start timestamp) + (org-element-property :day-start timestamp) + (org-element-property :month-start timestamp) + (org-element-property :year-start timestamp) + nil -1 nil)))) + (te (float-time + (org-encode-time + (list 0 + (org-element-property :minute-end timestamp) + (org-element-property :hour-end timestamp) + (org-element-property :day-end timestamp) + (org-element-property :month-end timestamp) + (org-element-property :year-end timestamp) + nil -1 nil)))) + (dt (- (if tend (min te tend) te) + (if tstart (max ts tstart) ts)))) + (when (> dt 0) (cl-incf t1 (floor dt 60)))) + (error + (org-display-warning (format "org-clock-sum: Ignoring invalid %s" (org-current-line-string)))))) ((match-end 4) ;; A naked time. (setq t1 (+ t1 (string-to-number (match-string 5)) @@ -2069,6 +2194,7 @@ Use `\\[org-clock-remove-overlays]' to remove the subtree times." h m)))) (defvar-local org-clock-overlays nil) +(put 'org-clock-overlays 'permanent-local t) (defun org-clock-put-overlay (time) "Put an overlay on the headline at point, displaying TIME. @@ -2343,7 +2469,7 @@ have priority." d (+ d shift))) ((or `week `thisweek) (let* ((ws (or wstart 1)) - (diff (+ (* -7 shift) (if (= dow 0) (- 7 ws) (- dow ws))))) + (diff (+ (* -7 shift) (mod (+ dow 7 (- ws)) 7)))) (setq m 0 h org-extend-today-until d (- d diff) d1 (+ 7 d)))) ((or `month `thismonth) (setq h org-extend-today-until m 0 d (or mstart 1) @@ -2494,7 +2620,7 @@ the currently selected interval size." (goto-char b) (insert ins) (delete-region (point) (+ (point) (- e b))) - (beginning-of-line 1) + (forward-line 0) (org-update-dblock) t))))) @@ -2796,13 +2922,13 @@ from the dynamic block definition." (if timestamp (concat ts "|") "") ;timestamp, maybe (if tags (concat (mapconcat #'identity tgs ", ") "|") "") ;tags, maybe (if properties ;properties columns, maybe - (concat (mapconcat (lambda (p) (or (cdr (assoc p props)) "")) - properties - "|") - "|") + (concat (mapconcat (lambda (p) (or (cdr (assoc p props)) "")) + properties + "|") + "|") "") (if indent ;indentation - (org-clocktable-indent-string level) + (org-clocktable-indent-string level) "") (format-field headline) ;; Empty fields for higher levels. @@ -2810,7 +2936,7 @@ from the dynamic block definition." (format-field (org-duration-from-minutes time)) (make-string (max 0 (- time-columns level)) ?|) (if (eq formula '%) - (format "%.1f |" (* 100 (/ time (float total-time)))) + (format "%.1f |" (* 100 (/ time (float total-time)))) "") "\n"))))))) (delete-char -1) @@ -2821,7 +2947,7 @@ from the dynamic block definition." (when (and contents (string-match "^\\([ \t]*#\\+tblfm:.*\\)" contents)) (setq recalc t) (insert "\n" (match-string 1 contents)) - (beginning-of-line 0)))) + (forward-line -1)))) ;; Insert specified formula line. ((stringp formula) (insert "\n#+TBLFM: " formula) @@ -3003,8 +3129,9 @@ PROPERTIES: The list properties specified in the `:properties' parameter (let* ((todo (org-get-todo-state)) (tags-list (org-get-tags)) (org-scanner-tags tags-list) - (org-trust-scanner-tags t)) - (funcall matcher todo tags-list nil))))) + (org-trust-scanner-tags t) + (level (org-current-level))) + (funcall matcher todo tags-list level))))) (goto-char (point-min)) (setq st t) (while (or (and (bobp) (prog1 st (setq st nil)) @@ -3064,7 +3191,7 @@ Otherwise, return nil." (let ((origin (point))) ;; `save-excursion' may not work when deleting. (prog1 (save-excursion - (beginning-of-line 1) + (forward-line 0) (skip-chars-forward " \t") (when (looking-at org-clock-string) (let ((re (concat "[ \t]*" org-clock-string @@ -3134,7 +3261,7 @@ The details of what will be saved are regulated by the variable (and (buffer-live-p b) (buffer-file-name b) (or (not org-clock-persist-query-save) - (y-or-n-p (format "Save current clock (%s) " + (y-or-n-p (format "Save current clock (%s)?" org-clock-heading)))))) (insert (format "(setq org-clock-stored-resume-clock '(%S . %d))\n" @@ -3174,7 +3301,7 @@ The details of what will be saved are regulated by the variable (`(,(and file (pred file-exists-p)) . ,position) (with-current-buffer (find-file-noselect file) (when (or (not org-clock-persist-query-resume) - (y-or-n-p (format "Resume clock (%s) " + (y-or-n-p (format "Resume clock (%s)?" (save-excursion (goto-char position) (org-get-heading t t))))) diff --git a/elpa/org-9.6.7/org-colview.el b/elpa/org-9.7.17/org-colview.el similarity index 89% rename from elpa/org-9.6.7/org-colview.el rename to elpa/org-9.7.17/org-colview.el index 92a3b473..bc93941e 100644 --- a/elpa/org-9.6.7/org-colview.el +++ b/elpa/org-9.7.17/org-colview.el @@ -1,9 +1,9 @@ ;;; org-colview.el --- Column View in Org -*- lexical-binding: t; -*- -;; Copyright (C) 2004-2023 Free Software Foundation, Inc. +;; Copyright (C) 2004-2024 Free Software Foundation, Inc. ;; Author: Carsten Dominik -;; Keywords: outlines, hypermedia, calendar, wp +;; Keywords: outlines, hypermedia, calendar, text ;; URL: https://orgmode.org ;; ;; This file is part of GNU Emacs. @@ -37,13 +37,13 @@ (declare-function org-agenda-redo "org-agenda" (&optional all)) (declare-function org-agenda-do-context-action "org-agenda" ()) (declare-function org-clock-sum-today "org-clock" (&optional headline-filter)) -(declare-function org-element-extract-element "org-element" (element)) +(declare-function org-element-extract "org-element-ast" (node)) (declare-function org-element-interpret-data "org-element" (data)) (declare-function org-element-map "org-element" (data types fun &optional info first-match no-recursion with-affiliated)) (declare-function org-element-parse-secondary-string "org-element" (string restriction &optional parent)) -(declare-function org-element-property "org-element" (property element)) +(declare-function org-element-property "org-element-ast" (property node)) (declare-function org-element-restriction "org-element" (element)) -(declare-function org-element-type "org-element" (element)) +(declare-function org-element-type-p "org-element-ast" (node types)) (declare-function org-dynamic-block-define "org" (type func)) (declare-function org-link-display-format "ol" (s)) (declare-function org-link-open-from-string "ol" (s &optional arg)) @@ -59,6 +59,19 @@ ;;; Configuration +(defcustom org-columns-checkbox-allowed-values '("[ ]" "[X]") + "Allowed values for columns with SUMMARY-TYPE that uses checkbox. +The affected summary types are \"X%\", \"X/\", and \"X\" (see info +node `(org)Column attributes')." + :group 'org-properties + :package-version '(Org . "9.6") + :type '(repeat (choice + (const :tag "Unchecked [ ]" "[ ]") + (const :tag "Checked [X]" "[X]") + (const :tag "No checkbox" "") + (const :tag "Intermediate state [-]" "[-]") + (string :tag "Arbitrary string")))) + (defcustom org-columns-modify-value-for-display-function nil "Function that modifies values for display in column view. For example, it can be used to cut out a certain part from a time stamp. @@ -110,12 +123,22 @@ in `org-columns-summary-types-default', which see." (function :tag "Summarize") (function :tag "Collect"))))) +(defcustom org-columns-dblock-formatter #'org-columns-dblock-write-default + "Function to format data in column view dynamic blocks. +For more information, see `org-columns-dblock-write-default'." + :group 'org-properties + :package-version '(Org . "9.7") + :type 'function) ;;; Column View (defvar-local org-columns-overlays nil "Holds the list of current column overlays.") +(put 'org-columns-overlays 'permanent-local t) + +(defvar-local org-columns-global nil + "Local variable, holds non-nil when current columns are global.") (defvar-local org-columns-current-fmt nil "Local variable, holds the currently active column format.") @@ -179,28 +202,10 @@ See `org-columns-summary-types' for details.") (org-defkey org-columns-map "\M-b" #'backward-char) (org-defkey org-columns-map "a" #'org-columns-edit-allowed) (org-defkey org-columns-map "s" #'org-columns-edit-attributes) -(org-defkey org-columns-map "\M-f" - (lambda () (interactive) (goto-char (1+ (point))))) -(org-defkey org-columns-map [right] - (lambda () (interactive) (goto-char (1+ (point))))) -(org-defkey org-columns-map [down] - (lambda () (interactive) - (let ((col (current-column))) - (beginning-of-line 2) - (while (and (org-invisible-p2) (not (eobp))) - (beginning-of-line 2)) - (move-to-column col) - (if (derived-mode-p 'org-agenda-mode) - (org-agenda-do-context-action))))) -(org-defkey org-columns-map [up] - (lambda () (interactive) - (let ((col (current-column))) - (beginning-of-line 0) - (while (and (org-invisible-p2) (not (bobp))) - (beginning-of-line 0)) - (move-to-column col) - (if (eq major-mode 'org-agenda-mode) - (org-agenda-do-context-action))))) +(org-defkey org-columns-map "\M-f" #'forward-char) +(org-defkey org-columns-map [right] #'forward-char) +(org-defkey org-columns-map [up] #'org-columns-move-up) +(org-defkey org-columns-map [down] #'org-columns-move-down) (org-defkey org-columns-map [(shift right)] #'org-columns-next-allowed-value) (org-defkey org-columns-map "n" #'org-columns-next-allowed-value) (org-defkey org-columns-map [(shift left)] #'org-columns-previous-allowed-value) @@ -209,6 +214,8 @@ See `org-columns-summary-types' for details.") (org-defkey org-columns-map ">" #'org-columns-widen) (org-defkey org-columns-map [(meta right)] #'org-columns-move-right) (org-defkey org-columns-map [(meta left)] #'org-columns-move-left) +(org-defkey org-columns-map [(meta down)] #'org-columns-move-row-down) +(org-defkey org-columns-map [(meta up)] #'org-columns-move-row-up) (org-defkey org-columns-map [(shift meta right)] #'org-columns-new) (org-defkey org-columns-map [(shift meta left)] #'org-columns-delete) (dotimes (i 10) @@ -230,6 +237,8 @@ See `org-columns-summary-types' for details.") "--" ["Move column right" org-columns-move-right t] ["Move column left" org-columns-move-left t] + ["Move row up" org-columns-move-row-up t] + ["Move row down" org-columns-move-row-down t] ["Add column" org-columns-new t] ["Delete column" org-columns-delete t] "--" @@ -375,17 +384,19 @@ ORIGINAL is the real string, i.e., before it is modified by "Store the relative remapping of column header-line. This is needed to later remove this relative remapping.") +(defvar org-columns--read-only-string nil) (defun org-columns--display-here (columns &optional dateline) "Overlay the current line with column display. COLUMNS is an alist (SPEC VALUE DISPLAYED). Optional argument DATELINE is non-nil when the face used should be `org-agenda-column-dateline'." - (when (and (ignore-errors (require 'face-remap)) - org-columns-header-line-remap) + (when (and (not org-columns-header-line-remap) + (or (fboundp 'face-remap-add-relative) + (ignore-errors (require 'face-remap)))) (setq org-columns-header-line-remap (face-remap-add-relative 'header-line '(:inherit default)))) (save-excursion - (beginning-of-line) + (forward-line 0) (let* ((level-face (and (looking-at "\\(\\**\\)\\(\\* \\)") (org-get-level-face 2))) (ref-face (or level-face @@ -448,18 +459,36 @@ DATELINE is non-nil when the face used should be (line-end-position 0) (line-beginning-position 2) 'read-only - (substitute-command-keys - "Type \\`\\[org-columns-edit-value]' \ -to edit property"))))))) + (or org-columns--read-only-string + (setq org-columns--read-only-string + (substitute-command-keys + "Type \\`\\[org-columns-edit-value]' \ +to edit property"))))))))) + +(defun org-columns--truncate-below-width (string width) + "Return a substring of STRING no wider than WIDTH. +This substring must start at 0, and must be the longest possible +substring whose `string-width' does not exceed WIDTH." + (declare (side-effect-free t)) + (let ((end (min width (length string))) res) + (while (and end (>= end 0)) + (let* ((curr (string-width (substring string 0 end))) + (excess (- curr width))) + (if (> excess 0) + (cl-decf end (max 1 (/ excess 2))) + (setq res (substring string 0 end) end nil)))) + res)) (defun org-columns-add-ellipses (string width) "Truncate STRING with WIDTH characters, with ellipses." (cond - ((<= (length string) width) string) - ((<= width (length org-columns-ellipses)) - (substring org-columns-ellipses 0 width)) - (t (concat (substring string 0 (- width (length org-columns-ellipses))) - org-columns-ellipses)))) + ((<= (string-width string) width) string) + ((<= width (string-width org-columns-ellipses)) + (org-columns--truncate-below-width org-columns-ellipses width)) + (t (concat + (org-columns--truncate-below-width + string (- width (string-width org-columns-ellipses))) + org-columns-ellipses)))) (defvar org-columns-full-header-line-format nil "The full header line format, will be shifted by horizontal scrolling." ) @@ -524,7 +553,8 @@ for the duration of the command.") (setq header-line-format org-previous-header-line-format) (kill-local-variable 'org-previous-header-line-format) (remove-hook 'post-command-hook #'org-columns-hscroll-title 'local)) - (set-marker org-columns-begin-marker nil) + (when (markerp org-columns-begin-marker) + (set-marker org-columns-begin-marker nil)) (when (markerp org-columns-top-level-marker) (set-marker org-columns-top-level-marker nil)) (with-silent-modifications @@ -726,7 +756,7 @@ an integer, select that value." (let ((all (or (org-property-get-allowed-values pom key) (pcase (nth column org-columns-current-fmt-compiled) - (`(,_ ,_ ,_ ,(or "X" "X/" "X%") ,_) '("[ ]" "[X]"))) + (`(,_ ,_ ,_ ,(or "X" "X/" "X%") ,_) org-columns-checkbox-allowed-values)) (org-colview-construct-allowed-dates value)))) (if previous (reverse all) all)))) (when (equal key "ITEM") (error "Cannot edit item headline from here")) @@ -816,7 +846,7 @@ current specifications. This function also sets (let ((case-fold-search t)) (while (re-search-forward "^[ \t]*#\\+COLUMNS: .+$" nil t) (let ((element (org-element-at-point))) - (when (eq (org-element-type element) 'keyword) + (when (org-element-type-p element 'keyword) (throw :found (org-element-property :value element))))) nil))) org-columns-default-format))) @@ -849,6 +879,7 @@ turn on column view for the whole buffer unconditionally. When COLUMNS-FMT-STRING is non-nil, use it as the column format." (interactive "P") (org-columns-remove-overlays) + (setq-local org-columns-global global) (save-excursion (when global (goto-char (point-min))) (if (markerp org-columns-begin-marker) @@ -871,7 +902,7 @@ When COLUMNS-FMT-STRING is non-nil, use it as the column format." ;; Collect contents of columns ahead of time so as to ;; compute their maximum width. (org-scan-tags - (lambda () (cons (point) (org-columns--collect-values))) t org--matcher-tags-todo-only))) + (lambda () (cons (point-marker) (org-columns--collect-values))) t org--matcher-tags-todo-only))) (when cache (org-columns--set-widths cache) (org-columns--display-here-title) @@ -969,6 +1000,30 @@ details." (interactive "p") (org-columns-widen (- arg))) +(defun org-columns-move-up () + "In column view, move cursor up one row. +When in agenda column view, also call `org-agenda-do-context-action'." + (interactive) + (let ((col (current-column))) + (forward-line -1) + (while (and (org-invisible-p2) (not (bobp))) + (forward-line -1)) + (move-to-column col) + (if (eq major-mode 'org-agenda-mode) + (org-agenda-do-context-action)))) + +(defun org-columns-move-down () + "In column view, move cursor down one row. +When in agenda column view, also call `org-agenda-do-context-action'." + (interactive) + (let ((col (current-column))) + (forward-line 1) + (while (and (org-invisible-p2) (not (eobp))) + (forward-line 1)) + (move-to-column col) + (if (derived-mode-p 'org-agenda-mode) + (org-agenda-do-context-action)))) + (defun org-columns-move-right () "Swap this column with the one to the right." (interactive) @@ -1003,6 +1058,27 @@ details." (org-columns-move-right) (backward-char 1))) +(defun org-columns--move-row (&optional up) + "Move the current table row down. +With non-nil optional argument UP, move it up." + (let ((inhibit-read-only t) + (col (current-column))) + (if up (org-move-subtree-up) + (org-move-subtree-down)) + (let ((org-columns-inhibit-recalculation t)) + (org-columns-redo) + (move-to-column col)))) + +(defun org-columns-move-row-down () + "Move the current table row down." + (interactive) + (org-columns--move-row)) + +(defun org-columns-move-row-up () + "Move the current table row up." + (interactive) + (org-columns--move-row 'up)) + (defun org-columns-store-format () "Store the text version of the current columns format. The format is stored either in the COLUMNS property of the node @@ -1020,7 +1096,7 @@ the current buffer." (catch :found (while (re-search-forward "^[ \t]*#\\+COLUMNS:\\(.*\\)" nil t) (let ((element (save-match-data (org-element-at-point)))) - (when (and (eq (org-element-type element) 'keyword) + (when (and (org-element-type-p element 'keyword) (equal (org-element-property :key element) "COLUMNS")) (replace-match (concat " " fmt) t t nil 1) @@ -1070,7 +1146,7 @@ the current buffer." (if (derived-mode-p 'org-mode) ;; Since we already know the columns format, provide it ;; instead of computing again. - (call-interactively #'org-columns org-columns-current-fmt) + (funcall-interactively #'org-columns org-columns-global org-columns-current-fmt) (org-agenda-redo) (call-interactively #'org-agenda-columns))) (message "Recomputing columns...done"))) @@ -1130,7 +1206,7 @@ This function updates `org-columns-current-fmt-compiled'." (defun org-columns--age-to-minutes (s) "Turn age string S into a number of minutes. -An age is either computed from a given time-stamp, or indicated +An age is either computed from a given timestamp, or indicated as a canonical duration, i.e., using units defined in `org-duration-canonical-units'." (cond @@ -1159,8 +1235,8 @@ Return the result as a duration." SPEC is a column format specification. When optional argument UPDATE is non-nil, summarized values can replace existing ones in properties drawers." - (let* ((lmax (if (bound-and-true-p org-inlinetask-min-level) - org-inlinetask-min-level + (let* ((lmax (if (bound-and-true-p org-inlinetask-max-level) + org-inlinetask-max-level 29)) ;Hard-code deepest level. (lvals (make-vector (1+ lmax) nil)) (level 0) @@ -1196,9 +1272,9 @@ properties drawers." ;; property `org-summaries', in alist whose key is SPEC. (let* ((summary (and summarize - (let ((values (append (and (/= last-level inminlevel) - (aref lvals last-level)) - (aref lvals inminlevel)))) + (let ((values + (cl-loop for l from (1+ level) to lmax + append (aref lvals l)))) (and values (funcall summarize values printf)))))) ;; Leaf values are not summaries: do not mark them. (when summary @@ -1372,9 +1448,13 @@ that will be excluded from the resulting view. FORMAT is a format string for columns, or nil. When LOCAL is non-nil, only capture headings in current subtree. -This function returns a list containing the title row and all -other rows. Each row is a list of fields, as strings, or -`hline'." +This function returns a list containing the title row and all other +rows. Each row is either a list, or the symbol `hline'. The first list +is the heading row as a list of strings with the column titles according +to FORMAT. All subsequent lists each represent a body row as a list +whose first element is an integer indicating the outline level of the +entry, and whose remaining elements are strings with the contents for +the columns according to FORMAT." (org-columns (not local) format) (goto-char org-columns-top-level-marker) (let ((columns (length org-columns-current-fmt-compiled)) @@ -1387,11 +1467,10 @@ other rows. Each row is a list of fields, as strings, or (dotimes (i columns) (let* ((col (+ (line-beginning-position) i)) (p (get-char-property col 'org-columns-key))) - (push (org-quote-vert - (get-char-property col - (if (string= p "ITEM") - 'org-columns-value - 'org-columns-value-modified))) + (push (get-char-property col + (if (string= p "ITEM") + 'org-columns-value + 'org-columns-value-modified)) row))) (unless (or (and skip-empty @@ -1422,8 +1501,10 @@ an inline src-block." (org-element-map data '(footnote-reference inline-babel-call inline-src-block target radio-target statistics-cookie) - #'org-element-extract-element) - (org-no-properties (org-element-interpret-data data)))) + #'org-element-extract) + (org-quote-vert + (org-no-properties + (org-element-interpret-data data))))) ;;;###autoload (defun org-dblock-write:columnview (params) @@ -1475,7 +1556,17 @@ PARAMS is a property list of parameters: `:vlines' When non-nil, make each column a column group to enforce - vertical lines." + vertical lines. + +`:link' + + Link the item headlines in the table to their origins. + +`:formatter' + + A function to format the data and insert it into the + buffer. Overrides the default formatting function set in + `org-columns-dblock-formatter'." (let ((table (let ((id (plist-get params :id)) view-file view-pos) @@ -1493,7 +1584,7 @@ PARAMS is a property list of parameters: (setq view-file filename) (setq view-pos position)) (_ (user-error "Cannot find entry with :ID: %s" id))) - (with-current-buffer (if view-file (get-file-buffer view-file) + (with-current-buffer (if view-file (org-get-agenda-file-buffer view-file) (current-buffer)) (org-with-wide-buffer (when view-pos (goto-char view-pos)) @@ -1502,7 +1593,21 @@ PARAMS is a property list of parameters: (plist-get params :skip-empty-rows) (plist-get params :exclude-tags) (plist-get params :format) - view-pos)))))) + view-pos))))) + (formatter (or (plist-get params :formatter) + org-columns-dblock-formatter + #'org-columns-dblock-write-default))) + (funcall formatter (point) table params))) + +(defun org-columns-dblock-write-default (ipos table params) + "Write out a columnview table at position IPOS in the current buffer. +TABLE is a table with data as produced by `org-columns--capture-view'. +PARAMS is the parameter property list obtained from the dynamic block +definition." + (let ((link (plist-get params :link)) + (width-specs + (mapcar (lambda (spec) (nth 2 spec)) + org-columns-current-fmt-compiled))) (when table ;; Prune level information from the table. Also normalize ;; headings: remove stars, add indentation entities, if @@ -1526,7 +1631,14 @@ PARAMS is a property list of parameters: (and (numberp hlines) (<= level hlines)))) (push 'hline new-table)) (when item-index - (let ((item (org-columns--clean-item (nth item-index (cdr row))))) + (let* ((raw (nth item-index (cdr row))) + (cleaned (org-columns--clean-item raw)) + (item (if (not link) cleaned + (let ((search (org-link-heading-search-string raw))) + (org-link-make-string + (if (not (buffer-file-name)) search + (format "file:%s::%s" (buffer-file-name) search)) + cleaned))))) (setf (nth item-index (cdr row)) (if (and indent (> level 1)) (concat "\\_" (make-string (* 2 (1- level)) ?\s) item) @@ -1538,12 +1650,19 @@ PARAMS is a property list of parameters: (append (mapcar (lambda (x) (if (eq 'hline x) x (cons "" x))) table) (list (cons "/" (make-list size "<>"))))))) + (when (seq-find #'identity width-specs) + ;; There are width specifiers in column format. Pass them + ;; to the resulting table, adding alignment field as the first + ;; row. + (push (mapcar (lambda (width) (when width (format "<%d>" width))) width-specs) table)) + ;; now insert the table into the buffer + (goto-char ipos) (let ((content-lines (org-split-string (plist-get params :content) "\n")) recalc) ;; Insert affiliated keywords before the table. (when content-lines (while (string-match-p "\\`[ \t]*#\\+" (car content-lines)) - (insert (pop content-lines) "\n"))) + (insert (string-trim-left (pop content-lines)) "\n"))) (save-excursion ;; Insert table at point. (insert @@ -1556,10 +1675,12 @@ PARAMS is a property list of parameters: (let ((case-fold-search t)) (dolist (line content-lines) (when (string-match-p "\\`[ \t]*#\\+TBLFM:" line) - (insert "\n" line) + (insert "\n" (string-trim-left line)) (unless recalc (setq recalc t)))))) (when recalc (org-table-recalculate 'all t)) - (org-table-align))))) + (org-table-align) + (when (seq-find #'identity width-specs) + (org-table-shrink)))))) ;;;###autoload (defun org-columns-insert-dblock () diff --git a/elpa/org-9.6.7/org-compat.el b/elpa/org-9.7.17/org-compat.el similarity index 86% rename from elpa/org-9.6.7/org-compat.el rename to elpa/org-9.7.17/org-compat.el index d5bf2191..e92b8d71 100644 --- a/elpa/org-9.6.7/org-compat.el +++ b/elpa/org-9.7.17/org-compat.el @@ -1,9 +1,9 @@ ;;; org-compat.el --- Compatibility Code for Older Emacsen -*- lexical-binding: t; -*- -;; Copyright (C) 2004-2023 Free Software Foundation, Inc. +;; Copyright (C) 2004-2024 Free Software Foundation, Inc. ;; Author: Carsten Dominik -;; Keywords: outlines, hypermedia, calendar, wp +;; Keywords: outlines, hypermedia, calendar, text ;; URL: https://orgmode.org ;; ;; This file is part of GNU Emacs. @@ -52,9 +52,15 @@ (declare-function org-element-at-point "org-element" (&optional pom cached-only)) (declare-function org-element-at-point-no-context "org-element" (&optional pom)) (declare-function org-element-context "org-element" (&optional element)) -(declare-function org-element-lineage "org-element" (blob &optional types with-self)) -(declare-function org-element-type "org-element" (element)) -(declare-function org-element-property "org-element" (property element)) +(declare-function org-element-lineage "org-element-ast" (blob &optional types with-self)) +(declare-function org-element-type "org-element-ast" (node &optional anonymous)) +(declare-function org-element-type-p "org-element-ast" (node types)) +(declare-function org-element-property "org-element-ast" (property node)) +(declare-function org-element-begin "org-element" (node)) +(declare-function org-element-end "org-element" (node)) +(declare-function org-element-contents-begin "org-element" (node)) +(declare-function org-element-contents-end "org-element" (node)) +(declare-function org-element-post-affiliated "org-element" (node)) (declare-function org-end-of-subtree "org" (&optional invisible-ok to-heading)) (declare-function org-get-heading "org" (&optional no-tags no-todo no-priority no-comment)) (declare-function org-get-tags "org" (&optional pos local)) @@ -71,6 +77,7 @@ (declare-function outline-next-heading "outline" ()) (declare-function speedbar-line-directory "speedbar" (&optional depth)) (declare-function table--at-cell-p "table" (position &optional object at-column)) +(declare-function ob-clojure-eval-with-cmd "ob-clojure" (cmd expanded)) (declare-function org-fold-folded-p "org-fold" (&optional pos spec-or-alias)) (declare-function org-fold-hide-sublevels "org-fold" (levels)) (declare-function org-fold-hide-subtree "org-fold" ()) @@ -96,6 +103,25 @@ ;;; Emacs < 29 compatibility +(if (fboundp 'display-buffer-full-frame) + (defalias 'org-display-buffer-full-frame #'display-buffer-full-frame) + (defun org-display-buffer-full-frame (buffer alist) + "Display BUFFER in the current frame, taking the entire frame. +ALIST is an association list of action symbols and values. See +Info node `(elisp) Buffer Display Action Alists' for details of +such alists. + +This is an action function for buffer display, see Info +node `(elisp) Buffer Display Action Functions'. It should be +called only by `display-buffer' or a function directly or +indirectly called by the latter." + (when-let* ((window (or (display-buffer-reuse-window buffer alist) + (display-buffer-same-window buffer alist) + (display-buffer-pop-up-window buffer alist) + (display-buffer-use-some-window buffer alist)))) + (delete-other-windows window) + window))) + (defvar org-file-has-changed-p--hash-table (make-hash-table :test #'equal) "Internal variable used by `org-file-has-changed-p'.") @@ -130,9 +156,41 @@ Upper-case and lower-case letters are treated as equal. Unibyte strings are converted to multibyte for comparison." (eq t (compare-strings string1 0 nil string2 0 nil t)))) +(defun org-buffer-text-pixel-width () + "Return pixel width of text in current buffer. +This function uses `buffer-text-pixel-size', when available, and falls +back to `window-text-pixel-size' otherwise." + (if (fboundp 'buffer-text-pixel-size) + (car (buffer-text-pixel-size nil nil t)) + (if (get-buffer-window (current-buffer)) + ;; FIXME: 10000 because `most-positive-fixnum' ain't working + ;; (tests failing) and this call will be removed after we drop + ;; Emacs 28 support anyway. + (car (window-text-pixel-size + nil (point-min) (point-max) 10000)) + (let ((dedicatedp (window-dedicated-p)) + (oldbuffer (window-buffer))) + (unwind-protect + (progn + ;; Do not throw error in dedicated windows. + (set-window-dedicated-p nil nil) + (set-window-buffer nil (current-buffer)) + (car (window-text-pixel-size + nil (point-min) (point-max) 10000))) + (set-window-buffer nil oldbuffer) + (set-window-dedicated-p nil dedicatedp)))))) + ;;; Emacs < 28.1 compatibility +(if (= 2 (cdr (subr-arity (symbol-function 'get-buffer-create)))) + ;; Emacs >27. + (defalias 'org-get-buffer-create #'get-buffer-create) + (defun org-get-buffer-create (buffer-or-name &optional _) + "Call `get-buffer-create' with BUFFER-OR-NAME argument. +Ignore optional argument." + (get-buffer-create buffer-or-name))) + (if (fboundp 'file-name-concat) (defalias 'org-file-name-concat #'file-name-concat) (defun org-file-name-concat (directory &rest components) @@ -141,7 +199,7 @@ Unibyte strings are converted to multibyte for comparison." Elements in COMPONENTS must be a string or nil. DIRECTORY or the non-final elements in COMPONENTS may or may not end with a slash -- if they don't end with a slash, a slash will be -inserted before contatenating." +inserted before concatenating." (save-match-data (mapconcat #'identity @@ -193,6 +251,17 @@ removed." default))) ": "))) +(if (fboundp 'list-of-strings-p) + (defalias 'org-list-of-strings-p #'list-of-strings-p) + ;; From Emacs subr.el. +;;;###autoload + (defun org-list-of-strings-p (object) + "Return t if OBJECT is nil or a list of strings." + (declare (pure t) (side-effect-free error-free)) + (while (and (consp object) (stringp (car object))) + (setq object (cdr object))) + (null object))) + ;;; Emacs < 27.1 compatibility @@ -204,6 +273,25 @@ removed." `(progn ,@body)) (defalias 'org-combine-change-calls 'combine-change-calls)) +;; `flatten-tree' was added in Emacs 27.1. +(if (fboundp 'flatten-tree) + (defalias 'org--flatten-tree #'flatten-tree) + ;; The implementation is taken from Emacs subr.el 8664ba18c7c5. + (defun org--flatten-tree (tree) + "Return a \"flattened\" copy of TREE. + +A `flatten-tree' polyfill for compatibility with Emacs versions +older than 27.1" + (let (elems) + (while (consp tree) + (let ((elem (pop tree))) + (while (consp elem) + (push (cdr elem) tree) + (setq elem (car elem))) + (if elem (push elem elems)))) + (if tree (push tree elems)) + (nreverse elems)))) + (if (version< emacs-version "27.1") (defsubst org-replace-buffer-contents (source &optional _max-secs _max-costs) (replace-buffer-contents source)) @@ -290,6 +378,24 @@ Execute BODY, and unwind connection-local variables." `(with-connection-local-profiles (connection-local-get-profiles nil) ,@body))) +;; assoc-delete-all missing from 26.1 +(if (fboundp 'assoc-delete-all) + (defalias 'org-assoc-delete-all 'assoc-delete-all) + ;; from compat/compat-27.el + (defun org-assoc-delete-all (key alist &optional test) + "Delete all matching key from alist, default test equal" + (unless test (setq test #'equal)) + (while (and (consp (car alist)) + (funcall test (caar alist) key)) + (setq alist (cdr alist))) + (let ((tail alist) tail-cdr) + (while (setq tail-cdr (cdr tail)) + (if (and (consp (car tail-cdr)) + (funcall test (caar tail-cdr) key)) + (setcdr tail (cdr tail-cdr)) + (setq tail tail-cdr)))) + alist)) + ;;; Emacs < 26.1 compatibility @@ -386,6 +492,10 @@ Counting starts at 1." (define-obsolete-function-alias 'org-string-match-p 'string-match-p "9.0") ;;;; Functions and variables from previous releases now obsolete. +(define-obsolete-variable-alias 'org-export-ignored-local-variables + 'org-element-ignored-local-variables "Org 9.7") +(define-obsolete-function-alias 'org-habit-get-priority + 'org-habit-get-urgency "Org 9.7") (define-obsolete-function-alias 'org-timestamp-format 'org-format-timestamp "Org 9.6") (define-obsolete-variable-alias 'org-export-before-processing-hook @@ -411,7 +521,7 @@ Counting starts at 1." 'completing-read "9.0") (define-obsolete-function-alias 'org-iread-file-name 'read-file-name "9.0") (define-obsolete-function-alias 'org-days-to-time - 'org-time-stamp-to-now "8.2") + 'org-timestamp-to-now "8.2") (define-obsolete-variable-alias 'org-agenda-ignore-drawer-properties 'org-agenda-ignore-properties "9.0") (define-obsolete-function-alias 'org-preview-latex-fragment @@ -549,10 +659,51 @@ Counting starts at 1." (define-obsolete-function-alias 'org-file-url-p 'org-url-p "9.6") (define-obsolete-variable-alias 'org-plantuml-executable-args 'org-plantuml-args "Org 9.6") + +(defvar org-cached-props nil) +(defvar org-use-property-inheritance) +(declare-function org-entry-get "org" (epom property &optional inherit literal-nil)) +(declare-function org-entry-properties "org" (&optional epom which)) +(defun org-cached-entry-get (pom property) + (if (or (eq t org-use-property-inheritance) + (and (stringp org-use-property-inheritance) + (let ((case-fold-search t)) + (string-match-p org-use-property-inheritance property))) + (and (listp org-use-property-inheritance) + (member-ignore-case property org-use-property-inheritance))) + ;; Caching is not possible, check it directly. + (org-entry-get pom property 'inherit) + ;; Get all properties, so we can do complicated checks easily. + (cdr (assoc-string property + (or org-cached-props + (setq org-cached-props (org-entry-properties pom))) + t)))) + +(make-obsolete 'org-cached-entry-get + "Performs badly. Instead use `org-entry-get' with the argument INHERIT set to `selective'" + "9.7") + +(defconst org-latex-line-break-safe "\\\\[0pt]" + "Linebreak protecting the following [...]. + +Without \"[0pt]\" it would be interpreted as an optional argument to +the \\\\. + +This constant, for example, makes the below code not err: + +\\begin{tabular}{c|c} + [t] & s\\\\[0pt] + [I] & A\\\\[0pt] + [m] & kg +\\end{tabular}") +(make-obsolete 'org-latex-line-break-safe + "should not be used - it is not safe in all the scenarios." + "9.7") + (defun org-in-fixed-width-region-p () "Non-nil if point in a fixed-width region." (save-match-data - (eq 'fixed-width (org-element-type (org-element-at-point))))) + (org-element-type-p (org-element-at-point) 'fixed-width))) (make-obsolete 'org-in-fixed-width-region-p "use `org-element' library" "9.0") @@ -570,6 +721,26 @@ Counting starts at 1." (make-obsolete 'org-let "to be removed" "9.6") (make-obsolete 'org-let2 "to be removed" "9.6") +(define-obsolete-function-alias 'org--math-always-on + 'org--math-p "9.7") + +(defmacro org-no-popups (&rest body) + "Suppress popup windows and evaluate BODY." + `(let (pop-up-frames pop-up-windows) + ,@body)) +(make-obsolete 'org-no-popups "no longer used" "9.7") + +(defun org-switch-to-buffer-other-window (&rest args) + "Switch to buffer in a second window on the current frame. +In particular, do not allow pop-up frames. +Returns the newly created buffer." + (let (pop-up-frames pop-up-windows) + (apply #'switch-to-buffer-other-window args))) + (make-obsolete 'org-switch-to-buffer-other-window "no longer used" "9.7") + +(make-obsolete 'org-refresh-category-properties "no longer used" "9.7") +(make-obsolete 'org-refresh-effort-properties "no longer used" "9.7") + (defun org-compatible-face (inherits specs) "Make a compatible face specification. If INHERITS is an existing face and if the Emacs version supports @@ -616,7 +787,7 @@ See `org-link-parameters' for documentation on the other parameters." (defun org-table-recognize-table.el () "If there is a table.el table nearby, recognize it and move into it." (when (org-at-table.el-p) - (beginning-of-line) + (forward-line 0) (unless (or (looking-at org-table-dataline-regexp) (not (looking-at org-table1-hline-regexp))) (forward-line) @@ -658,13 +829,23 @@ See `org-link-parameters' for documentation on the other parameters." (org-unbracket-string "<" ">" s)) (make-obsolete 'org-remove-angle-brackets 'org-unbracket-string "9.0") +(defcustom org-capture-bookmark t + "When non-nil, add bookmark pointing at the last stored position when capturing." + :group 'org-capture + :version "24.3" + :type 'boolean) +(make-obsolete-variable + 'org-capture-bookmark + "use `org-bookmark-names-plist' instead." + "9.7") + (defcustom org-publish-sitemap-file-entry-format "%t" "Format string for site-map file entry. You could use brackets to delimit on what part the link will be. %t is the title. %a is the author. -%d is the date formatted using `org-publish-sitemap-date-format'." +%d is the date." :group 'org-export-publish :type 'string) (make-obsolete-variable @@ -881,21 +1062,21 @@ When optional argument ELEMENT is a parsed drawer, as returned by When buffer positions BEG and END are provided, hide or show that region as a drawer without further ado." (declare (obsolete "use `org-hide-drawer-toggle' instead." "9.4")) - (if (and beg end) (org-fold-region beg end flag (if (eq org-fold-core-style 'text-properties) 'drawer 'outline)) + (if (and beg end) (org-fold-region beg end flag 'drawer) (let ((drawer (or element (and (save-excursion - (beginning-of-line) + (forward-line 0) (looking-at-p "^[ \t]*:\\(\\(?:\\w\\|[-_]\\)+\\):[ \t]*$")) (org-element-at-point))))) - (when (memq (org-element-type drawer) '(drawer property-drawer)) - (let ((post (org-element-property :post-affiliated drawer))) + (when (org-element-type-p drawer '(drawer property-drawer)) + (let ((post (org-element-post-affiliated drawer))) (org-fold-region (save-excursion (goto-char post) (line-end-position)) - (save-excursion (goto-char (org-element-property :end drawer)) + (save-excursion (goto-char (org-element-end drawer)) (skip-chars-backward " \t\n") (line-end-position)) - flag (if (eq org-fold-core-style 'text-properties) 'drawer 'outline)) + flag 'drawer) ;; When the drawer is hidden away, make sure point lies in ;; a visible part of the buffer. (when (invisible-p (max (1- (point)) (point-min))) @@ -919,7 +1100,7 @@ an error. Return a non-nil value when toggling is successful." (goto-char start) (while (and (< (point) end) (re-search-forward "^[ \t]*#\\+begin_?\ -\\([^ \n]+\\)\\(\\([^\n]+\\)\\)?\n\\([^\000]+?\\)#\\+end_?\\1[ \t]*$" end t)) +\\([^ \n]+\\)\\(\\([^\n]+\\)\\)?\n\\(\\(?:.\\|\n\\)+?\\)#\\+end_?\\1[ \t]*$" end t)) (save-excursion (save-match-data (goto-char (match-beginning 0)) @@ -1116,6 +1297,26 @@ context. See the individual commands for more information." (make-obsolete-variable 'org-latex-polyglossia-language-alist "set `org-latex-language-alist' instead." "9.6") +(defconst org-babel-python-mode 'python + "Python mode for use in running python interactively.") + +(make-obsolete-variable + 'org-babel-python-mode + "Only the built-in Python mode is supported in ob-python now." + "9.7") + +(define-obsolete-function-alias 'ob-clojure-eval-with-babashka + #'ob-clojure-eval-with-cmd "9.7") + +(define-obsolete-function-alias 'org-export-get-parent + 'org-element-parent "9.7") +(define-obsolete-function-alias 'org-export-get-parent-element + 'org-element-parent-element "9.7") + +(define-obsolete-function-alias 'org-print-speed-command + 'org--print-speed-command "9.7" + "Internal function. Subject of unannounced changes.") + ;;;; Obsolete link types (eval-after-load 'ol @@ -1366,7 +1567,7 @@ ELEMENT is the element at point." ;; Only in inline footnotes, within the definition. (and (eq (org-element-property :type object) 'inline) (< (save-excursion - (goto-char (org-element-property :begin object)) + (goto-char (org-element-begin object)) (search-forward ":" nil t 2)) (point)))) (otherwise t)))) @@ -1375,7 +1576,7 @@ ELEMENT is the element at point." "Function used for `flyspell-generic-check-word-predicate'." (if (org-at-heading-p) ;; At a headline or an inlinetask, check title only. - (and (save-excursion (beginning-of-line) + (and (save-excursion (forward-line 0) (and (let ((case-fold-search t)) (not (looking-at-p "\\*+ END[ \t]*$"))) (let ((case-fold-search nil)) @@ -1387,19 +1588,19 @@ ELEMENT is the element at point." ;; Ignore checks in code, verbatim and others. (org--flyspell-object-check-p (org-element-at-point-no-context))) (let* ((element (org-element-at-point-no-context)) - (post-affiliated (org-element-property :post-affiliated element))) + (post-affiliated (org-element-post-affiliated element))) (cond ;; Ignore checks in all affiliated keywords but captions. ((< (point) post-affiliated) (and (save-excursion - (beginning-of-line) + (forward-line 0) (let ((case-fold-search t)) (looking-at "[ \t]*#\\+CAPTION:"))) (> (point) (match-end 0)) (org--flyspell-object-check-p element))) ;; Ignore checks in LOGBOOK (or equivalent) drawer. ((let ((log (org-log-into-drawer))) (and log - (let ((drawer (org-element-lineage element '(drawer)))) + (let ((drawer (org-element-lineage element 'drawer))) (and drawer (org-string-equal-ignore-case log (org-element-property :drawer-name drawer)))))) @@ -1413,7 +1614,7 @@ ELEMENT is the element at point." (save-excursion (end-of-line) (skip-chars-forward " \r\t\n") - (< (point) (org-element-property :end element))))) + (< (point) (org-element-end element))))) ;; Arbitrary list of keywords where checks are meaningful. ;; Make sure point is on the value part of the element. (keyword @@ -1425,8 +1626,8 @@ ELEMENT is the element at point." ;; table rows (after affiliated keywords) but some objects ;; must not be affected. ((paragraph table-row verse-block) - (let ((cbeg (org-element-property :contents-begin element)) - (cend (org-element-property :contents-end element))) + (let ((cbeg (org-element-contents-begin element)) + (cend (org-element-contents-end element))) (and cbeg (>= (point) cbeg) (< (point) cend) (org--flyspell-object-check-p element)))))))))) (put 'org-mode 'flyspell-mode-predicate 'org-mode-flyspell-verify) @@ -1561,7 +1762,7 @@ key." "Run `org-back-to-heading' when in org-mode." (if (derived-mode-p 'org-mode) (progn - (beginning-of-line) + (forward-line 0) (or (org-at-heading-p (not invisible-ok)) (let (found) (save-excursion diff --git a/elpa/org-9.6.7/org-crypt.el b/elpa/org-9.7.17/org-crypt.el similarity index 82% rename from elpa/org-9.6.7/org-crypt.el rename to elpa/org-9.7.17/org-crypt.el index b5df115c..797f8a99 100644 --- a/elpa/org-9.6.7/org-crypt.el +++ b/elpa/org-9.7.17/org-crypt.el @@ -1,6 +1,6 @@ ;;; org-crypt.el --- Public Key Encryption for Org Entries -*- lexical-binding: t; -*- ;; -;; Copyright (C) 2007-2023 Free Software Foundation, Inc. +;; Copyright (C) 2007-2024 Free Software Foundation, Inc. ;; Author: John Wiegley @@ -71,16 +71,18 @@ (defvar epg-context) (declare-function org-back-over-empty-lines "org" ()) +(declare-function org-current-level "org" ()) (declare-function org-back-to-heading "org" (&optional invisible-ok)) (declare-function org-before-first-heading-p "org" ()) (declare-function org-end-of-meta-data "org" (&optional full)) -(declare-function org-end-of-subtree "org" (&optional invisible-ok to-heading)) +(declare-function org-end-of-subtree "org" (&optional invisible-ok to-heading element)) (declare-function org-entry-get "org" (pom property &optional inherit literal-nil)) (declare-function org-fold-subtree "org-fold" (flag)) -(declare-function org-make-tags-matcher "org" (match)) +(declare-function org-make-tags-matcher "org" (match &optional only-local-tags)) (declare-function org-previous-visible-heading "org" (arg)) (declare-function org-scan-tags "org" (action matcher todo-only &optional start-level)) (declare-function org-set-property "org" (property value)) +(declare-function org-cycle-set-startup-visibility "org-cycle" ()) (defgroup org-crypt nil "Org Crypt." @@ -113,16 +115,16 @@ This setting can be overridden in the CRYPTKEY property." (defcustom org-crypt-disable-auto-save 'ask "What org-decrypt should do if `auto-save-mode' is enabled. -t : Disable auto-save-mode for the current buffer +t : Disable `auto-save-mode' for the current buffer prior to decrypting an entry. -nil : Leave auto-save-mode enabled. +nil : Leave `auto-save-mode' enabled. This may cause data to be written to disk unencrypted! -`ask' : Ask user whether or not to disable auto-save-mode +`ask' : Ask user whether or not to disable `auto-save-mode' for the current buffer. -`encrypt': Leave auto-save-mode enabled for the current buffer, +`encrypt': Leave `auto-save-mode' enabled for the current buffer, but automatically re-encrypt all decrypted entries *before* auto-saving. NOTE: This only works for entries which have a tag @@ -165,7 +167,7 @@ and END are buffer positions delimiting the encrypted area." (cons start (line-beginning-position 2))))))))) (defun org-crypt-check-auto-save () - "Check whether auto-save-mode is enabled for the current buffer. + "Check whether `auto-save-mode' is enabled for the current buffer. `auto-save-mode' may cause leakage when decrypting entries, so check whether it's enabled, and decide what to do about it. @@ -177,7 +179,7 @@ See `org-crypt-disable-auto-save'." (eq org-crypt-disable-auto-save t) (and (eq org-crypt-disable-auto-save 'ask) - (y-or-n-p "org-decrypt: auto-save-mode may cause leakage. Disable it for current buffer? "))) + (y-or-n-p "`org-decrypt': auto-save-mode may cause leakage. Disable it for current buffer? "))) (message "org-decrypt: Disabling auto-save-mode for %s" (or (buffer-file-name) (current-buffer))) ;; The argument to auto-save-mode has to be "-1", since @@ -244,12 +246,13 @@ Assume `epg-context' is set." ;; contents in the buffer. (error (insert contents) - (error (error-message-string err))))) + (error "%s" (error-message-string err))))) (when folded-heading (goto-char folded-heading) (org-fold-subtree t)) nil))))) +(defvar org-outline-regexp-bol) ;;;###autoload (defun org-decrypt-entry () "Decrypt the content of the current headline." @@ -265,23 +268,44 @@ Assume `epg-context' is set." (save-excursion (org-previous-visible-heading 1) (point)))) + (level (org-current-level)) (encrypted-text (org-crypt--encrypted-text beg end)) (decrypted-text (decode-coding-string (epg-decrypt-string epg-context encrypted-text) - 'utf-8))) + 'utf-8)) + origin-marker) ;; Delete region starting just before point, because the ;; outline property starts at the \n of the heading. (delete-region (1- (point)) end) - ;; Store a checksum of the decrypted and the encrypted text - ;; value. This allows reusing the same encrypted text if the - ;; text does not change, and therefore avoid a re-encryption - ;; process. - (insert "\n" - (propertize decrypted-text - 'org-crypt-checksum (sha1 decrypted-text) - 'org-crypt-key (org-crypt-key-for-heading) - 'org-crypt-text encrypted-text)) + (setq origin-marker (point-marker)) + (if (string-match (org-headline-re level) decrypted-text) + ;; If decrypted text contains other headings with levels + ;; below LEVEL, adjust the subtree. + (let ((start 0) (min-level level)) + (while (string-match (org-headline-re level) decrypted-text start) + (setq min-level (min min-level (1- (length (match-string 0 decrypted-text)))) + start (match-end 0))) + (insert "\n" + (replace-regexp-in-string + org-outline-regexp-bol + (concat (make-string (1+ (- level min-level)) ?*) "\\&") + decrypted-text))) + ;; Store a checksum of the decrypted and the encrypted text + ;; value. This allows reusing the same encrypted text if the + ;; text does not change, and therefore avoid a re-encryption + ;; process. + (insert "\n" + (propertize decrypted-text + 'org-crypt-checksum (sha1 decrypted-text) + 'org-crypt-key (org-crypt-key-for-heading) + 'org-crypt-text encrypted-text))) + ;; Apply initial visibility. + (save-restriction + (narrow-to-region origin-marker (point)) + (set-marker origin-marker nil) + (org-cycle-set-startup-visibility)) + ;; ... but keep the previous folded state. (when folded-heading (goto-char folded-heading) (org-fold-subtree t)) diff --git a/elpa/org-9.6.7/org-ctags.el b/elpa/org-9.7.17/org-ctags.el similarity index 85% rename from elpa/org-9.6.7/org-ctags.el rename to elpa/org-9.7.17/org-ctags.el index 5dd2bfd5..98a00d2c 100644 --- a/elpa/org-9.6.7/org-ctags.el +++ b/elpa/org-9.7.17/org-ctags.el @@ -1,9 +1,9 @@ ;;; org-ctags.el --- Integrate Emacs "tags" Facility with Org -*- lexical-binding: t; -*- -;; Copyright (C) 2007-2023 Free Software Foundation, Inc. +;; Copyright (C) 2007-2024 Free Software Foundation, Inc. ;; Author: Paul Sexton -;; Keywords: org, wp +;; Keywords: org, text ;; This file is part of GNU Emacs. ;; @@ -28,7 +28,7 @@ ;; ;; Allows Org mode to make use of the Emacs `etags' system. Defines ;; tag destinations in Org files as any text between <>. This allows the tags-generation program `exuberant +;; brackets>>. This allows the tags-generation program `exuberant ;; ctags' to parse these files and create tag tables that record where ;; these destinations are found. Plain [[links]] in org mode files ;; which do not have <> within the same file @@ -57,6 +57,12 @@ ;; (add-hook 'org-mode-hook ;; (lambda () ;; (define-key org-mode-map "\C-co" 'org-ctags-find-tag-interactive))) +;; (with-eval-after-load "org-ctags" +;; (org-ctags-enable)) +;; +;; To activate the library, you need to call `org-ctags-enable' explicitly. +;; It used to be invoked during library loading, but it was against Emacs +;; policy and caused inconvenience of Org users who do not use `org-ctags'. ;; ;; By default, with org-ctags loaded, org will first try and visit the tag ;; with the same name as the link; then, if unsuccessful, ask the user if @@ -66,7 +72,7 @@ ;; search the entire text of the current buffer for 'tag'. ;; ;; This behavior can be modified by changing the value of -;; ORG-CTAGS-OPEN-LINK-FUNCTIONS. For example I have the following in my +;; ORG-CTAGS-OPEN-LINK-FUNCTIONS. For example, I have the following in my ;; .emacs, which describes the same behavior as the above paragraph with ;; one difference: ;; @@ -149,18 +155,36 @@ (defvar org-ctags-enabled-p t "Activate ctags support in org mode?") -(defvar org-ctags-tag-regexp "/<<([^>]+)>>/\\1/d,definition/" +(defvar org-ctags-tag-regexp "/<<([^<>]+)>>/\\1/d,definition/" "Regexp expression used by ctags external program. The regexp matches tag destinations in Org files. Format is: /REGEXP/TAGNAME/FLAGS,TAGTYPE/ See the ctags documentation for more information.") (defcustom org-ctags-path-to-ctags - (if (executable-find "ctags-exuberant") "ctags-exuberant" "ctags") + (cond ((executable-find "ctags-exuberant") + "ctags-exuberant") + ((boundp 'ctags-program-name) + ctags-program-name) + (t "ctags")) ; Emacs < 30 "Name of the ctags executable file." :version "24.1" :type 'file) +(defconst org-ctags--open-link-functions-list + (list + #'org-ctags-find-tag + #'org-ctags-ask-rebuild-tags-file-then-find-tag + #'org-ctags-rebuild-tags-file-then-find-tag + #'org-ctags-ask-append-topic + #'org-ctags-append-topic + #'org-ctags-ask-visit-buffer-or-file + #'org-ctags-visit-buffer-or-file + #'org-ctags-fail-silently) + "Options for `org-open-link-functions'. +Ensure that the user option and `unload-feature' +use the same set of functions.") + (defcustom org-ctags-open-link-functions '(org-ctags-find-tag org-ctags-ask-rebuild-tags-file-then-find-tag @@ -168,14 +192,7 @@ See the ctags documentation for more information.") "List of functions to be prepended to ORG-OPEN-LINK-FUNCTIONS by ORG-CTAGS." :version "24.1" :type 'hook - :options '(org-ctags-find-tag - org-ctags-ask-rebuild-tags-file-then-find-tag - org-ctags-rebuild-tags-file-then-find-tag - org-ctags-ask-append-topic - org-ctags-append-topic - org-ctags-ask-visit-buffer-or-file - org-ctags-visit-buffer-or-file - org-ctags-fail-silently)) + :options org-ctags--open-link-functions-list) (defvar org-ctags-tag-list nil @@ -191,21 +208,21 @@ The following patterns are replaced in the string: :type 'string) -(add-hook 'org-mode-hook - (lambda () - (when (and org-ctags-enabled-p - (buffer-file-name)) - ;; Make sure this file's directory is added to default - ;; directories in which to search for tags. - (let ((tags-filename - (expand-file-name - (concat (file-name-directory (buffer-file-name)) - "/TAGS")))) - (when (file-exists-p tags-filename) - (visit-tags-table tags-filename)))))) +(defun org-ctags--visit-tags-table () + "Load tags for current file. +A function for `org-mode-hook." + (when (and org-ctags-enabled-p + (buffer-file-name)) + ;; Make sure this file's directory is added to default + ;; directories in which to search for tags. + (let ((tags-filename + (expand-file-name + (concat (file-name-directory (buffer-file-name)) + "/TAGS")))) + (when (file-exists-p tags-filename) + (visit-tags-table tags-filename))))) -(advice-add 'visit-tags-table :after #'org--ctags-load-tag-list) (defun org--ctags-load-tag-list (&rest _) (when (and org-ctags-enabled-p tags-file-name) (setq-local org-ctags-tag-list @@ -213,12 +230,28 @@ The following patterns are replaced in the string: (defun org-ctags-enable () + (add-hook 'org-mode-hook #'org-ctags--visit-tags-table) + (advice-add 'visit-tags-table :after #'org--ctags-load-tag-list) + (advice-add 'xref-find-definitions :before + #'org--ctags-set-org-mark-before-finding-tag) + (put 'org-mode 'find-tag-default-function 'org-ctags-find-tag-at-point) (setq org-ctags-enabled-p t) (dolist (fn org-ctags-open-link-functions) (add-hook 'org-open-link-functions fn t))) +(defun org-ctags-unload-function () + "Disable `org-ctags' library. +Called by `unload-feature'." + (put 'org-mode 'find-tag-default-function nil) + (advice-remove 'visit-tags-table #'org--ctags-load-tag-list) + (advice-remove 'xref-find-definitions + #'org--ctags-set-org-mark-before-finding-tag) + (dolist (fn org-ctags--open-link-functions-list) + (remove-hook 'org-open-link-functions fn nil))) + + ;;; General utility functions. =============================================== ;; These work outside org-ctags mode. @@ -294,8 +327,6 @@ The new topic will be titled NAME (or TITLE if supplied)." ;;;; Misc interoperability with etags system ================================= -(advice-add 'xref-find-definitions :before - #'org--ctags-set-org-mark-before-finding-tag) (defun org--ctags-set-org-mark-before-finding-tag (&rest _) "Before trying to find a tag, save our current position on org mark ring." (save-excursion @@ -477,18 +508,21 @@ function may take several seconds to finish if the directory or its subdirectories contain large numbers of taggable files." (interactive) (cl-assert (buffer-file-name)) - (let ((dir-name (or directory-name - (file-name-directory (buffer-file-name)))) + (let ((dir-name (shell-quote-argument + (expand-file-name + (if directory-name + (file-name-as-directory directory-name) + (file-name-directory (buffer-file-name)))))) (exitcode nil)) (save-excursion (setq exitcode (shell-command (format (concat "%s --langdef=orgmode --langmap=orgmode:.org " - "--regex-orgmode=\"%s\" -f \"%s\" -e -R \"%s\"") + "--regex-orgmode=%s -f %sTAGS -e -R %s*") org-ctags-path-to-ctags - org-ctags-tag-regexp - (expand-file-name (concat dir-name "/TAGS")) - (expand-file-name (concat dir-name "/*"))))) + (shell-quote-argument org-ctags-tag-regexp) + dir-name + dir-name))) (cond ((eql 0 exitcode) (setq-local org-ctags-tag-list @@ -506,12 +540,11 @@ its subdirectories contain large numbers of taggable files." (defun org-ctags-find-tag-interactive () "Prompt for the name of a tag, with autocompletion, then visit the named tag. -Uses `ido-mode' if available. If the user enters a string that does not match an existing tag, create a new topic." (interactive) - (let* ((tag (ido-completing-read "Topic: " org-ctags-tag-list - nil 'confirm nil 'org-ctags-find-tag-history))) + (let* ((tag (completing-read "Topic: " org-ctags-tag-list + nil 'confirm nil 'org-ctags-find-tag-history))) (when tag (cond ((member tag org-ctags-tag-list) @@ -524,8 +557,6 @@ a new topic." 'org-open-link-functions tag)))))) -(org-ctags-enable) - (provide 'org-ctags) ;;; org-ctags.el ends here diff --git a/elpa/org-9.6.7/org-cycle.el b/elpa/org-9.7.17/org-cycle.el similarity index 93% rename from elpa/org-9.6.7/org-cycle.el rename to elpa/org-9.7.17/org-cycle.el index 90fc95f4..8a39bdb8 100644 --- a/elpa/org-9.6.7/org-cycle.el +++ b/elpa/org-9.7.17/org-cycle.el @@ -1,8 +1,8 @@ ;;; org-cycle.el --- Visibility cycling of Org entries -*- lexical-binding: t; -*- ;; -;; Copyright (C) 2020-2023 Free Software Foundation, Inc. +;; Copyright (C) 2020-2024 Free Software Foundation, Inc. ;; -;; Maintainer: Ihor Radchenko +;; Maintainer: Ihor Radchenko ;; Keywords: folding, visibility cycling, invisible text ;; URL: https://orgmode.org ;; @@ -35,9 +35,10 @@ (require 'org-macs) (require 'org-fold) -(declare-function org-element-type "org-element" (element)) -(declare-function org-element-property "org-element" (property element)) -(declare-function org-element-lineage "org-element" (datum &optional types with-self)) +(declare-function org-element-type-p "org-element-ast" (node types)) +(declare-function org-element-property "org-element-ast" (property node)) +(declare-function org-element-post-affiliated "org-element" (node)) +(declare-function org-element-lineage "org-element-ast" (datum &optional types with-self)) (declare-function org-element-at-point "org-element" (&optional pom cached-only)) (declare-function org-display-inline-images "org" (&optional include-linked refresh beg end)) (declare-function org-get-tags "org" (&optional pos local fontify)) @@ -115,6 +116,7 @@ than its value." (const :tag "No limit" nil) (integer :tag "Maximum level"))) +(defvaralias 'org-hide-block-startup 'org-cycle-hide-block-startup) (defcustom org-cycle-hide-block-startup nil "Non-nil means entering Org mode will fold all blocks. This can also be set in on a per-file basis with @@ -125,6 +127,7 @@ This can also be set in on a per-file basis with :group 'org-cycle :type 'boolean) +(defvaralias 'org-hide-drawer-startup 'org-cycle-hide-drawer-startup) (defcustom org-cycle-hide-drawer-startup t "Non-nil means entering Org mode will fold all drawers. This can also be set in on a per-file basis with @@ -200,6 +203,7 @@ Special case: when 0, never leave empty lines in collapsed view." :type 'integer) (put 'org-cycle-separator-lines 'safe-local-variable 'integerp) +(defvaralias 'org-pre-cycle-hook 'org-cycle-pre-hook) (defcustom org-cycle-pre-hook nil "Hook that is run before visibility cycling is happening. The function(s) in this hook must accept a single argument which indicates @@ -240,6 +244,7 @@ normal outline commands like `show-all', but not with the cycling commands." :package-version '(Org . "9.6") :type 'boolean) +(defvaralias 'org-tab-first-hook 'org-cycle-tab-first-hook) (defvar org-cycle-tab-first-hook nil "Hook for functions to attach themselves to TAB. See `org-ctrl-c-ctrl-c-hook' for more information. @@ -335,6 +340,10 @@ same as `S-TAB') also when called without prefix argument." (and org-cycle-level-after-item/entry-creation (or (org-cycle-level) (org-cycle-item-indentation)))) + (when (and org-cycle-max-level + (or (not (integerp org-cycle-max-level)) + (< org-cycle-max-level 1))) + (user-error "`org-cycle-max-level' must be a positive integer")) (let* ((limit-level (or org-cycle-max-level (and (boundp 'org-inlinetask-min-level) @@ -388,8 +397,8 @@ same as `S-TAB') also when called without prefix argument." ((org-fold-hide-drawer-toggle nil t element)) ;; Table: enter it or move to the next field. ((and (org-match-line "[ \t]*[|+]") - (org-element-lineage element '(table) t)) - (if (and (eq 'table (org-element-type element)) + (org-element-lineage element 'table t)) + (if (and (org-element-type-p element 'table) (eq 'table.el (org-element-property :type element))) (message (substitute-command-keys "\\\ Use `\\[org-edit-special]' to edit table.el tables")) @@ -404,8 +413,8 @@ Use `\\[org-edit-special]' to edit table.el tables")) t))) (and item (= (line-beginning-position) - (org-element-property :post-affiliated - item))))) + (org-element-post-affiliated + item))))) (org-match-line org-outline-regexp)) (or (bolp) (not (eq org-cycle-emulate-tab 'exc-hl-bol)))) (org-cycle-internal-local)) @@ -421,7 +430,7 @@ Use `\\[org-edit-special]' to edit table.el tables")) (call-interactively (global-key-binding (kbd "TAB")))) ((or (eq org-cycle-emulate-tab t) (and (memq org-cycle-emulate-tab '(white whitestart)) - (save-excursion (beginning-of-line 1) (looking-at "[ \t]*")) + (save-excursion (forward-line 0) (looking-at "[ \t]*")) (or (and (eq org-cycle-emulate-tab 'white) (= (match-end 0) (line-end-position))) (and (eq org-cycle-emulate-tab 'whitestart) @@ -480,7 +489,7 @@ Use `\\[org-edit-special]' to edit table.el tables")) (save-excursion (if (org-at-item-p) (progn - (beginning-of-line) + (forward-line 0) (setq struct (org-list-struct)) (setq eoh (line-end-position)) (setq eos (org-list-get-item-end-before-blank (point) struct)) @@ -502,16 +511,16 @@ Use `\\[org-edit-special]' to edit table.el tables")) (save-excursion (org-list-search-forward (org-item-beginning-re) eos t)))))) ;; Determine end invisible part of buffer (EOL) - (beginning-of-line 2) + (forward-line 1) (if (eq org-fold-core-style 'text-properties) (while (and (not (eobp)) ;this is like `next-line' (org-fold-folded-p (1- (point)))) (goto-char (org-fold-next-visibility-change nil nil t)) - (and (eolp) (beginning-of-line 2))) + (and (eolp) (forward-line 1))) (while (and (not (eobp)) ;this is like `next-line' (get-char-property (1- (point)) 'invisible)) (goto-char (next-single-char-property-change (point) 'invisible)) - (and (eolp) (beginning-of-line 2)))) + (and (eolp) (forward-line 1)))) (setq eol (point))) ;; Find out what to do next and set `this-command' (cond @@ -545,7 +554,7 @@ Use `\\[org-edit-special]' to edit table.el tables")) (save-excursion (org-back-to-heading) (while (org-list-search-forward (org-item-beginning-re) eos t) - (beginning-of-line 1) + (forward-line 0) (let* ((struct (org-list-struct)) (prevs (org-list-prevs-alist struct)) (end (org-list-get-bottom-point struct))) @@ -608,7 +617,9 @@ With a numeric prefix, show all headlines up to that level." (defun org-cycle-set-startup-visibility () "Set the visibility required by startup options and properties." (cond - ((eq org-startup-folded t) + ;; `fold' is technically not allowed value, but it is often + ;; intuitively tried by users by analogy with #+STARTUP: fold. + ((memq org-startup-folded '(t fold overview)) (org-cycle-overview)) ((eq org-startup-folded 'content) (org-cycle-content)) @@ -620,8 +631,10 @@ With a numeric prefix, show all headlines up to that level." (org-cycle-content 4)) ((eq org-startup-folded 'show5levels) (org-cycle-content 5)) - ((or (eq org-startup-folded 'showeverything) - (eq org-startup-folded nil)) + ;; `nofold' and `showall' are technically not allowed values, but + ;; they are often intuitively tried by users by analogy with + ;; #+STARTUP: nofold or #STARTUP: showall. + ((memq org-startup-folded '(showeverything nil nofold showall)) (org-fold-show-all))) (unless (eq org-startup-folded 'showeverything) (when org-cycle-hide-block-startup (org-fold-hide-block-all)) @@ -634,20 +647,21 @@ With a numeric prefix, show all headlines up to that level." "Switch subtree visibility according to VISIBILITY property." (interactive) (let ((regexp (org-re-property "VISIBILITY"))) - (org-with-point-at 1 + (save-excursion + (goto-char (point-min)) (while (re-search-forward regexp nil t) - (let ((state (match-string 3))) + (let ((state (match-string 3))) (if (not (org-at-property-p)) (outline-next-heading) (save-excursion (org-back-to-heading t) (org-fold-subtree t) (pcase state - ("folded" + ("folded" (org-fold-subtree t)) - ("children" + ("children" (org-fold-show-hidden-entry) (org-fold-show-children)) - ("content" + ("content" ;; Newline before heading will be outside the ;; narrowing. Make sure that it is revealed. (org-fold-heading nil) @@ -655,10 +669,9 @@ With a numeric prefix, show all headlines up to that level." (save-restriction (org-narrow-to-subtree) (org-cycle-content)))) - ((or "all" "showall") + ((or "all" "showall") (org-fold-show-subtree)) - (_ nil))) - (org-end-of-subtree))))))) + (_ nil))))))))) (defun org-cycle-overview () "Switch to overview mode, showing only top-level headlines." @@ -683,7 +696,7 @@ With a numeric prefix, show all headlines up to that level." (defun org-cycle-content (&optional arg) "Show all headlines in the buffer, like a table of contents. -With numerical argument N, show content up to level N." +With numerical argument ARG, show content up to level ARG." (interactive "p") (org-fold-show-all '(headings)) (save-excursion @@ -705,7 +718,9 @@ With numerical argument N, show content up to level N." "Temporarily store scroll position to restore.") (defun org-cycle-optimize-window-after-visibility-change (state) "Adjust the window after a change in outline visibility. -This function is the default value of the hook `org-cycle-hook'." +This function is the default value of the hook `org-cycle-hook'. +STATE is the current outline visibility state. It should be one of +symbols `content', `all', `folded', `children', or `subtree'." (when (get-buffer-window (current-buffer)) (let ((repeat (eq last-command this-command))) (unless repeat @@ -791,7 +806,9 @@ STATE should be one of the symbols listed in the docstring of (defun org-cycle-display-inline-images (state) "Auto display inline images under subtree when cycling. -It works when `org-cycle-inline-images-display' is non-nil." +It works when `org-cycle-inline-images-display' is non-nil. +STATE is the current outline visibility state. It should be one of +symbols `content', `all', `folded', `children', or `subtree'." (when org-cycle-inline-images-display (pcase state ('children diff --git a/elpa/org-9.6.7/org-datetree.el b/elpa/org-9.7.17/org-datetree.el similarity index 84% rename from elpa/org-9.6.7/org-datetree.el rename to elpa/org-9.7.17/org-datetree.el index 035ef047..d0cc1fab 100644 --- a/elpa/org-9.6.7/org-datetree.el +++ b/elpa/org-9.7.17/org-datetree.el @@ -1,9 +1,9 @@ ;;; org-datetree.el --- Create date entries in a tree -*- lexical-binding: t; -*- -;; Copyright (C) 2009-2023 Free Software Foundation, Inc. +;; Copyright (C) 2009-2024 Free Software Foundation, Inc. ;; Author: Carsten Dominik -;; Keywords: outlines, hypermedia, calendar, wp +;; Keywords: outlines, hypermedia, calendar, text ;; URL: https://orgmode.org ;; ;; This file is part of GNU Emacs. @@ -99,16 +99,15 @@ If time-period is month, then group entries by month." (month (calendar-extract-month d)) (day (calendar-extract-day d))) (org-datetree--find-create - "^\\*+[ \t]+\\([12][0-9]\\{3\\}\\)\\(\\s-*?\ -\\([ \t]:[[:alnum:]:_@#%%]+:\\)?\\s-*$\\)" - year) + "\\([12][0-9]\\{3\\}\\)" + year nil nil nil t) (org-datetree--find-create - "^\\*+[ \t]+%d-\\([01][0-9]\\) \\w+$" - year month) + "%d-\\([01][0-9]\\) \\w+" + year month nil nil t) (when (eq time-grouping 'day) (org-datetree--find-create - "^\\*+[ \t]+%d-%02d-\\([0123][0-9]\\) \\w+$" - year month day))))) + "%d-%02d-\\([0123][0-9]\\) \\w+" + year month day nil t))))) ;;;###autoload (defun org-datetree-find-iso-week-create (d &optional keep-restriction) @@ -147,33 +146,51 @@ will be built under the headline at point." (week (nth 0 iso-date))) ;; ISO 8601 week format is %G-W%V(-%u) (org-datetree--find-create - "^\\*+[ \t]+\\([12][0-9]\\{3\\}\\)\\(\\s-*?\ -\\([ \t]:[[:alnum:]:_@#%%]+:\\)?\\s-*$\\)" - weekyear nil nil - (format-time-string "%G" time)) + "\\([12][0-9]\\{3\\}\\)" + weekyear nil nil (format-time-string "%G" time) t) (org-datetree--find-create - "^\\*+[ \t]+%d-W\\([0-5][0-9]\\)$" - weekyear week nil - (format-time-string "%G-W%V" time)) + "%d-W\\([0-5][0-9]\\)" + weekyear week nil (format-time-string "%G-W%V" time) t) ;; For the actual day we use the regular date instead of ISO week. (org-datetree--find-create - "^\\*+[ \t]+%d-%02d-\\([0123][0-9]\\) \\w+$" - year month day)))) + "%d-%02d-\\([0123][0-9]\\) \\w+" year month day nil t)))) (defun org-datetree--find-create - (regex-template year &optional month day insert) + (regex-template year &optional month day insert match-title) "Find the datetree matched by REGEX-TEMPLATE for YEAR, MONTH, or DAY. REGEX-TEMPLATE is passed to `format' with YEAR, MONTH, and DAY as -arguments. Match group 1 is compared against the specified date +arguments. + +If MATCH-TITLE is non-nil, REGEX-TEMPLATE is matched against +heading title and the exact regexp matched against heading line is: + + (format org-complex-heading-regexp-format + (format regex-template year month day)) + +If MATCH-TITLE is nil, the regexp matched against heading line is +REGEX-TEMPLATE: + + (format regex-template year month day) + +Match group 1 in REGEX-TEMPLATE is compared against the specified date component. If INSERT is non-nil and there is no match then it is inserted into the buffer." (when (or month day) (org-narrow-to-subtree)) - (let ((re (format regex-template year month day)) + ;; ensure that the first match group in REGEX-TEMPLATE + ;; is the first inside `org-complex-heading-regexp-format' + (when (and match-title + (not (string-match-p "\\\\(\\?1:" regex-template)) + (string-match "\\\\(" regex-template)) + (setq regex-template (replace-match "\\(?1:" nil t regex-template))) + (let ((re (if match-title + (format org-complex-heading-regexp-format + (format regex-template year month day)) + (format regex-template year month day))) match) (goto-char (point-min)) (while (and (setq match (re-search-forward re nil t)) - (goto-char (match-beginning 1)) + (goto-char (match-beginning 1)) (< (string-to-number (match-string 1)) (or day month year)))) (cond ((not match) @@ -181,9 +198,9 @@ inserted into the buffer." (unless (bolp) (insert "\n")) (org-datetree-insert-line year month day insert)) ((= (string-to-number (match-string 1)) (or day month year)) - (beginning-of-line)) + (forward-line 0)) (t - (beginning-of-line) + (forward-line 0) (org-datetree-insert-line year month day insert))))) (defun org-datetree-insert-line (year &optional month day text) @@ -205,11 +222,11 @@ inserted into the buffer." (save-excursion (insert "\n") (org-indent-line) - (org-insert-time-stamp + (org-insert-timestamp (org-encode-time 0 0 0 day month year) nil (eq org-datetree-add-timestamp 'inactive)))) - (beginning-of-line)) + (forward-line 0)) (defun org-datetree-file-entry-under (txt d) "Insert a node TXT into the date tree under date D." diff --git a/elpa/org-9.6.7/org-duration.el b/elpa/org-9.7.17/org-duration.el similarity index 73% rename from elpa/org-9.6.7/org-duration.el rename to elpa/org-9.7.17/org-duration.el index 2919efd4..662a94bd 100644 --- a/elpa/org-9.6.7/org-duration.el +++ b/elpa/org-9.7.17/org-duration.el @@ -1,9 +1,9 @@ ;;; org-duration.el --- Library handling durations -*- lexical-binding: t; -*- -;; Copyright (C) 2017-2023 Free Software Foundation, Inc. +;; Copyright (C) 2017-2024 Free Software Foundation, Inc. ;; Author: Nicolas Goaziou -;; Keywords: outlines, hypermedia, calendar, wp +;; Keywords: outlines, hypermedia, calendar, text ;; This file is part of GNU Emacs. @@ -324,109 +324,110 @@ When optional argument CANONICAL is non-nil, ignore `org-duration-units' and use standard time units value. Raise an error if expected format is unknown." - (pcase (or fmt org-duration-format) - (`h:mm - (format "%d:%02d" (/ minutes 60) (mod minutes 60))) - (`h:mm:ss - (let* ((whole-minutes (floor minutes)) - (seconds (mod (* 60 minutes) 60))) - (format "%s:%02d" - (org-duration-from-minutes whole-minutes 'h:mm) - seconds))) - ((pred atom) (error "Invalid duration format specification: %S" fmt)) - ;; Mixed format. Call recursively the function on both parts. - ((and duration-format - (let `(special . ,(and mode (or `h:mm:ss `h:mm))) - (assq 'special duration-format))) - (let* ((truncated-format - ;; Remove "special" mode from duration format in order to - ;; recurse properly. Also remove units smaller or equal - ;; to an hour since H:MM part takes care of it. - (cl-remove-if-not - (lambda (pair) - (pcase pair - (`(,(and unit (pred stringp)) . ,_) - (> (org-duration--modifier unit canonical) 60)) - (_ nil))) - duration-format)) - (min-modifier ;smallest modifier above hour - (and truncated-format - (apply #'min - (mapcar (lambda (p) - (org-duration--modifier (car p) canonical)) - truncated-format))))) - (if (or (null min-modifier) (< minutes min-modifier)) - ;; There is not unit above the hour or the smallest unit - ;; above the hour is too large for the number of minutes we - ;; need to represent. Use H:MM or H:MM:SS syntax. - (org-duration-from-minutes minutes mode canonical) - ;; Represent minutes above hour using provided units and H:MM - ;; or H:MM:SS below. - (let* ((units-part (* min-modifier (/ (floor minutes) min-modifier))) - (minutes-part (- minutes units-part)) - (compact (memq 'compact duration-format))) - (concat - (org-duration-from-minutes units-part truncated-format canonical) - (and (not compact) " ") - (org-duration-from-minutes minutes-part mode)))))) - ;; Units format. - (duration-format - (let* ((fractional - (let ((digits (cdr (assq 'special duration-format)))) - (and digits - (or (wholenump digits) - (error "Unknown formatting directive: %S" digits)) - (format "%%.%df" digits)))) - (selected-units - (sort (cl-remove-if - ;; Ignore special format cells and compact option. - (lambda (pair) - (pcase pair - ((or `compact `(special . ,_)) t) - (_ nil))) - duration-format) - (lambda (a b) - (> (org-duration--modifier (car a) canonical) - (org-duration--modifier (car b) canonical))))) - (separator (if (memq 'compact duration-format) "" " "))) - (cond - ;; Fractional duration: use first unit that is either required - ;; or smaller than MINUTES. - (fractional - (let* ((unit (car - (or (cl-find-if - (lambda (pair) - (pcase pair - (`(,u . ,req?) - (or req? - (<= (org-duration--modifier u canonical) - minutes))))) - selected-units) - ;; Fall back to smallest unit. - (org-last selected-units)))) - (modifier (org-duration--modifier unit canonical))) - (concat (format fractional (/ (float minutes) modifier)) unit))) - ;; Otherwise build duration string according to available - ;; units. - ((org-string-nw-p - (org-trim - (mapconcat - (lambda (units) - (pcase-let* ((`(,unit . ,required?) units) - (modifier (org-duration--modifier unit canonical))) - (cond ((<= modifier minutes) - (let ((value (floor minutes modifier))) - (cl-decf minutes (* value modifier)) - (format "%s%d%s" separator value unit))) - (required? (concat separator "0" unit)) - (t "")))) - selected-units - "")))) - ;; No unit can properly represent MINUTES. Use the smallest - ;; one anyway. - (t - (pcase-let ((`((,unit . ,_)) (last selected-units))) - (concat "0" unit)))))))) + (if (< minutes 0) (concat "-" (org-duration-from-minutes (abs minutes) fmt canonical)) + (pcase (or fmt org-duration-format) + (`h:mm + (format "%d:%02d" (/ minutes 60) (mod minutes 60))) + (`h:mm:ss + (let* ((whole-minutes (floor minutes)) + (seconds (mod (* 60 minutes) 60))) + (format "%s:%02d" + (org-duration-from-minutes whole-minutes 'h:mm) + seconds))) + ((pred atom) (error "Invalid duration format specification: %S" fmt)) + ;; Mixed format. Call recursively the function on both parts. + ((and duration-format + (let `(special . ,(and mode (or `h:mm:ss `h:mm))) + (assq 'special duration-format))) + (let* ((truncated-format + ;; Remove "special" mode from duration format in order to + ;; recurse properly. Also remove units smaller or equal + ;; to an hour since H:MM part takes care of it. + (cl-remove-if-not + (lambda (pair) + (pcase pair + (`(,(and unit (pred stringp)) . ,_) + (> (org-duration--modifier unit canonical) 60)) + (_ nil))) + duration-format)) + (min-modifier ;smallest modifier above hour + (and truncated-format + (apply #'min + (mapcar (lambda (p) + (org-duration--modifier (car p) canonical)) + truncated-format))))) + (if (or (null min-modifier) (< minutes min-modifier)) + ;; There is not unit above the hour or the smallest unit + ;; above the hour is too large for the number of minutes we + ;; need to represent. Use H:MM or H:MM:SS syntax. + (org-duration-from-minutes minutes mode canonical) + ;; Represent minutes above hour using provided units and H:MM + ;; or H:MM:SS below. + (let* ((units-part (* min-modifier (/ (floor minutes) min-modifier))) + (minutes-part (- minutes units-part)) + (compact (memq 'compact duration-format))) + (concat + (org-duration-from-minutes units-part truncated-format canonical) + (and (not compact) " ") + (org-duration-from-minutes minutes-part mode)))))) + ;; Units format. + (duration-format + (let* ((fractional + (let ((digits (cdr (assq 'special duration-format)))) + (and digits + (or (wholenump digits) + (error "Unknown formatting directive: %S" digits)) + (format "%%.%df" digits)))) + (selected-units + (sort (cl-remove-if + ;; Ignore special format cells and compact option. + (lambda (pair) + (pcase pair + ((or `compact `(special . ,_)) t) + (_ nil))) + duration-format) + (lambda (a b) + (> (org-duration--modifier (car a) canonical) + (org-duration--modifier (car b) canonical))))) + (separator (if (memq 'compact duration-format) "" " "))) + (cond + ;; Fractional duration: use first unit that is either required + ;; or smaller than MINUTES. + (fractional + (let* ((unit (car + (or (cl-find-if + (lambda (pair) + (pcase pair + (`(,u . ,req?) + (or req? + (<= (org-duration--modifier u canonical) + minutes))))) + selected-units) + ;; Fall back to smallest unit. + (org-last selected-units)))) + (modifier (org-duration--modifier unit canonical))) + (concat (format fractional (/ (float minutes) modifier)) unit))) + ;; Otherwise build duration string according to available + ;; units. + ((org-string-nw-p + (org-trim + (mapconcat + (lambda (units) + (pcase-let* ((`(,unit . ,required?) units) + (modifier (org-duration--modifier unit canonical))) + (cond ((<= modifier minutes) + (let ((value (floor minutes modifier))) + (cl-decf minutes (* value modifier)) + (format "%s%d%s" separator value unit))) + (required? (concat separator "0" unit)) + (t "")))) + selected-units + "")))) + ;; No unit can properly represent MINUTES. Use the smallest + ;; one anyway. + (t + (pcase-let ((`((,unit . ,_)) (last selected-units))) + (concat "0" unit))))))))) ;;;###autoload (defun org-duration-h:mm-only-p (times) diff --git a/elpa/org-9.7.17/org-element-ast.el b/elpa/org-9.7.17/org-element-ast.el new file mode 100644 index 00000000..e96b129f --- /dev/null +++ b/elpa/org-9.7.17/org-element-ast.el @@ -0,0 +1,1150 @@ +;;; org-element-ast.el --- Abstract syntax tree for Org -*- lexical-binding: t; -*- + +;; Copyright (C) 2023-2024 Free Software Foundation, Inc. + +;; Author: Ihor Radchenko +;; Keywords: data, lisp + +;; 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 implements Org abstract syntax tree (AST) data structure. +;; +;; Only the most generic aspects of the syntax tree are considered +;; below. The fine details of Org syntax are implemented elsewhere. +;; +;; Org AST is composed of nested syntax nodes. +;; Within actual Org syntax, the nodes can be either headings, +;; elements, or objects. However, historically, we often call syntax +;; nodes simply "elements", unless the context requires clarification +;; about the node type. In particular, many functions below will have +;; naming pattern `org-element-X', implying `org-element-node-X' -- +;; they will apply to all the node types, not just to elements. +;; +;; 1. Syntax nodes +;; ------------------ +;; Each Org syntax node can be represented as a string or list. +;; +;; The main node representation follows the pattern +;; (TYPE PROPERTIES CONTENTS), where +;; TYPE is a symbol describing the node type. +;; PROPERTIES is the property list attached to it. +;; CONTENTS is a list of child syntax nodes contained within the +;; current node, when applicable. +;; +;;; For example, "*bold text* " node can be represented as +;; +;; (bold (:begin 1 :end 14 :post-blank 2 ...) "bold text") +;; +;; TYPE can be any symbol, including symbol not explicitly defined by +;; Org syntax. If TYPE is not a part of the syntax, the syntax +;; node is called "pseudo element/object", but otherwise considered a +;; valid part of Org syntax tree. Search "Pseudo objects and +;; elements" in lisp/ox-latex.el for an example of using pseudo +;; elements. +;; +;; PROPERTIES is a property list (:property1 value1 :property2 value2 ...) +;; holding properties and value. +;; +;; `:standard-properties', `:parent', `:deferred', and `:secondary' +;; properties are treated specially in the code below. +;; +;; `:standard-properties' holds an array with +;; `org-element--standard-properties' values, in the same order. The +;; values in the array have priority over the same properties +;; specified in the property list. You should not rely on the value +;; of `org-element--standard-properties' in the code. +;; `:standard-properties' may or may not be actually present in +;; PROPERTIES. It is mostly used to speed up property access in +;; performance-critical code, as most of the code requesting property +;; values by constant name is inlined. +;; +;; The previous example can also be presented in more compact form as: +;; +;; (bold (:standard-properties [1 10 ... 2 ...]) "bold text") +;; +;; Using an array allows faster access to frequently used properties. +;; +;; `:parent' holds the containing node, for a child node within the +;; AST. It may or may not be present in PROPERTIES. +;; +;; `:secondary' holds a list of properties that may contain extra AST +;; nodes, in addition to the node contents. +;; +;; `:deferred' property describes how to update not-yet-calculated +;; properties on request. +;; +;; +;; Syntax node can also be represented by a string. Strings always +;; represent syntax node of `plain-text' type with contents being nil +;; and properties represented as string properties at position 0. +;; `:standard-properties' are not considered for `plain-text' nodes as +;; `plain-text' nodes tend to hold much fewer properties. +;; +;; In the above example, `plain-text' node "bold text" is more +;; accurately represented as +;; +;; #("bold text" 0 9 (:parent (bold ...))) +;; +;; with :parent property value pointing back to the containing `bold' +;; node. +;; +;; `anonymous' syntax node is represented as a list with `car' +;; containing another syntax node. Such node has nil type, does not +;; have properties, and its contents is a list of the contained syntax +;; node. `:parent' property of the contained nodes point back to the +;; list itself, except when `anonymous' node holds secondary value +;; (see below), in which case the `:parent' property is set to be the +;; containing node in the AST. +;; +;; Any node representation other then described above is not +;; considered as Org syntax node. +;; +;; 2. Deferred values +;; ------------------ +;; Sometimes, it is computationally expensive or even not possible to +;; calculate property values when creating an AST node. The value +;; calculation can be deferred to the time the value is requested. +;; +;; Property values and contained nodes may have a special value of +;; `org-element-deferred' type. Such values are computed dynamically. +;; Either every time the property value is requested or just the first +;; time. In the latter case, the `org-element-deferred' property +;; value is auto-replaced with the dynamically computed result. +;; +;; Sometimes, even property names (not just property values) cannot, or +;; should not be computed in advance. If a special property +;; `:deferred' has the value of `org-element-deferred-type', it is +;; first resolved for side effects of setting the missing properties. +;; The resolved value is re-assigned to the `:deferred' property. +;; +;; Note that `org-element-copy' unconditionally resolves deferred +;; properties. This is useful to generate pure (in functional sense) +;; AST. +;; +;; The properties listed in `org-element--standard-properties', except +;; `:deferred' and `:parent' are never considered to have deferred value. +;; This constraint makes org-element API significantly faster. +;; +;; 3. Org document representation +;; ------------------------------ +;; Document AST is represented by nested Org syntax nodes. +;; +;; Each node in the AST can hold the contained node in its CONTENTS or +;; as values of properties. +;; +;; For example, (bold (...) "bold text") `bold' node contains +;; `plain-text' node in CONTENTS. +;; +;; The containing node is called "parent node". +;; +;; The contained nodes held inside CONTENTS are called "child nodes". +;; They must have their `:parent' property set to the containing +;; parent node. +;; +;; The contained nodes can also be held as property values. Such +;; nodes are called "secondary nodes". Only certain properties +;; can contribute to AST - the property names listed as the value of +;; special property `:secondary' +;; +;; For example, +;; +;; (headline ((:secondary (:title) +;; :title (#("text" 0 4 (:parent (headline ...))))))) +;; +;; is a parent headline node containing "text" secondary string node +;; inside `:title' property. Note that `:title' is listed in +;; `:secondary' value. +;; +;; The following example illustrates AST structure for an Org document: +;; +;; ---- Org document -------- +;; * Heading with *bold* text +;; Paragraph. +;; ---- end ----------------- +;; +;; (org-data (...) ; `org-data' node. +;; (headline +;; ( +;; ;; `:secondary' property lists property names that contain other +;; ;; syntax tree nodes. +;; +;; :secondary (:title) +;; +;; ;; `:title' property is set to anonymous node containing: +;; ;; `plain-text', `bold', `plain-text'. +;; +;; :title ("Heading with " (bold (:post-blank 1 ...) "bold") "text")) +;; +;; ;; `headline' contents +;; (section (...) +;; (paragraph +;; ;; `:parent' property set to the containing section. +;; (:parent (section ...)) +;; ;; paragraph contents is a `plain-text' node. +;; "Paragraph1.")))) +;; +;; Try calling M-: (org-element-parse-buffer) on the above example Org +;; document to explore a more complete version of Org AST. + +;;; Code: + +(require 'org-macs) +(require 'inline) ; load indentation rules +(require 'subr-x) ;; FIXME: Required for Emacs 27 + +;;;; Syntax node type + +(defun org-element-type (node &optional anonymous) + "Return type of NODE. + +The function returns the type of the node provided. +It can also return the following special value: + `plain-text' for a string + nil in any other case. + +When optional argument ANONYMOUS is non-nil, return symbol `anonymous' +when NODE is an anonymous node." + (declare (pure t)) + (cond + ((stringp node) 'plain-text) + ((null node) nil) + ((not (consp node)) nil) + ((symbolp (car node)) (car node)) + ((and anonymous (car node) (org-element-type (car node) t)) + 'anonymous) + (t nil))) + +(define-inline org-element-type-p (node types) + "Return non-nil when NODE type is one of TYPES. +TYPES can be a type symbol or a list of symbols." + (inline-letevals (node types) + (if (listp (inline-const-val types)) + (inline-quote (memq (org-element-type ,node t) ,types)) + (inline-quote (eq (org-element-type ,node t) ,types))))) + +(defun org-element-secondary-p (node) + "Non-nil when NODE directly belongs to a secondary node. +Return value is the containing property name, as a keyword, or nil." + (declare (pure t)) + (let* ((parent (org-element-property :parent node)) + (properties (org-element-property :secondary parent)) + val) + (catch 'exit + (dolist (p properties) + (setq val (org-element-property-raw p parent)) + (when (or (eq node val) (memq node val)) + (throw 'exit p)))))) + +;;;; Deferred values + +(cl-defstruct (org-element-deferred + (:constructor nil) + (:constructor org-element-deferred-create + ( auto-undefer-p function &rest arg-value + &aux (args arg-value))) + (:constructor org-element-deferred-create-alias + ( keyword &optional auto-undefer-p + &aux + (function #'org-element-property-2) + (args (list keyword)))) + (:constructor org-element-deferred-create-list + ( args &optional auto-undefer-p + &aux + (function #'org-element--deferred-resolve-list))) + (:type vector) :named) + "Dynamically computed value. + +The value can be obtained by calling FUNCTION with containing syntax +node as first argument and ARGS list as remaining arguments. + +If the function throws `:org-element-deferred-retry' signal, assume +that the syntax node has been modified by side effect and retry +retrieving the value that was previously deferred. + +AUTO-UNDEFER slot flags if the property value should be replaced upon +resolution. Some functions may ignore this flag." + function args auto-undefer-p) + +(defsubst org-element--deferred-resolve-once (deferred-value &optional node) + "Resolve DEFERRED-VALUE for NODE. +Throw `:org-element-deferred-retry' if NODE has been modified and we +need to re-read the value again." + (apply (org-element-deferred-function deferred-value) + node + (org-element-deferred-args deferred-value))) + +(defsubst org-element--deferred-resolve (value &optional node force-undefer) + "Resolve VALUE for NODE recursively. +Return a cons cell of the resolved value and the value to store. +When no value should be stored, return `org-element-ast--nil' as cdr. +When FORCE-UNDEFER is non-nil, resolve all the deferred values, ignoring +their `auto-undefer-p' slot. + +Throw `:org-element-deferred-retry' if NODE has been modified and we +need to re-read the value again." + (let ((value-to-store 'org-element-ast--nil) undefer) + (while (org-element-deferred-p value) + (setq undefer (or force-undefer (org-element-deferred-auto-undefer-p value)) + value (org-element--deferred-resolve-once value node)) + (when undefer (setq value-to-store value))) + (cons value value-to-store))) + +(defsubst org-element--deferred-resolve-force (value &optional node) + "Resolve VALUE for NODE recursively, ignoring `auto-undefer-p'. +Return the resolved value. + +Throw `:org-element-deferred-retry' if NODE has been modified and we +need to re-read the value again." + (car (org-element--deferred-resolve value node 'force))) + +(defsubst org-element--deferred-resolve-list (node &rest list) + "Unconditionally resolve all the deferred values in LIST for NODE. +Return a new list with all the values resolved. + +Throw `:org-element-deferred-retry' if NODE has been modified and we +need to re-read the value again." + (mapcar + (lambda (value) + (if (org-element-deferred-p value) + (org-element--deferred-resolve-force value node) + value)) + list)) + +;;;; Object properties + +(eval-and-compile ; make available during inline expansion + + (defconst org-element--standard-properties + '( :begin :post-affiliated :contents-begin :contents-end :end :post-blank + :secondary :mode :granularity + :cached :org-element--cache-sync-key + :robust-begin :robust-end + :true-level + :buffer :deferred + :structure :parent) + "Standard properties stored in every syntax node structure. +These properties are stored in an array pre-allocated every time a new +object is created. Two exceptions are `anonymous' and `plain-text' +node types.") + + (defconst org-element--standard-properties-idxs + (let (plist) + (seq-do-indexed + (lambda (property idx) + (setq plist (plist-put plist property idx))) + org-element--standard-properties) + plist) + "Property list holding standard indexes for `org-element--standard-properties'.") + + (define-inline org-element--property-idx (property) + "Return standard property index or nil." + (declare (pure t)) + (inline-letevals (property) + (plist-get + org-element--standard-properties-idxs + (inline-const-val property))))) + +(define-inline org-element--parray (node) + "Return standard property array for NODE." + (declare (pure t)) + (inline-letevals (node) + (inline-quote + (pcase (org-element-type ,node) + (`nil nil) + ;; Do not use property array for strings - they usually hold + ;; `:parent' property and nothing more. + (`plain-text nil) + (_ + ;; (type (:standard-properties val ...) ...) + (if (eq :standard-properties (car (nth 1 ,node))) + (cadr (nth 1 ,node)) + ;; Non-standard order. Go long way. + (plist-get (nth 1 ,node) :standard-properties))))))) + +(define-inline org-element--plist-property (property node &optional dflt) + "Extract the value for PROPERTY from NODE's property list. +Ignore standard property array." + (declare (pure t)) + (inline-letevals (property node dflt) + (inline-quote + (pcase (org-element-type ,node) + (`nil ,dflt) + (`plain-text + (or (get-text-property 0 ,property ,node) + (when ,dflt + (if + ;; FIXME: Byte-compiler throws false positives in Emacs 27. + (with-no-warnings + (plist-member (text-properties-at 0 ,node) ,property)) + nil ,dflt)))) + (_ + (or (plist-get (nth 1 ,node) ,property) + (when ,dflt + (if + ;; FIXME: Byte-compiler throws false positives in Emacs 27. + (with-no-warnings + (plist-member (nth 1 ,node) ,property)) + nil ,dflt)))))))) + +(define-inline org-element-property-raw (property node &optional dflt) + "Extract the value for PROPERTY of an NODE. +Do not resolve deferred values. +If PROPERTY is not present, return DFLT." + (declare (pure t)) + (inline-letevals (node property) + (let ((idx (org-element--property-idx (inline-const-val property)))) + (inline-quote + (let ((idx (or ,idx (org-element--property-idx ,property)))) + (if-let* ((parray (and idx (org-element--parray ,node)))) + (pcase (aref parray idx) + (`org-element-ast--nil ,dflt) + (val val)) + ;; No property array exists. Fall back to `plist-get'. + (org-element--plist-property ,property ,node ,dflt))))))) + +(define-inline org-element--put-parray (node &optional parray) + "Initialize standard property array in NODE. +Return the array or nil when NODE is `plain-text'." + (inline-letevals (node parray) + (inline-quote + (let ((parray ,parray)) + (unless (or parray (memq (org-element-type ,node) '(plain-text nil))) + (setq parray (make-vector ,(length org-element--standard-properties) nil)) + ;; Copy plist standard properties back to parray. + (let ((stdplist org-element--standard-properties-idxs)) + (while stdplist + (aset parray (cadr stdplist) + (org-element--plist-property (car stdplist) ,node)) + (setq stdplist (cddr stdplist)))) + (setcar (cdr ,node) + (nconc (list :standard-properties parray) + (cadr ,node))) + parray))))) + +(define-inline org-element-put-property (node property value) + "In NODE, set PROPERTY to VALUE. +Return modified NODE." + (let ((idx (and (inline-const-p property) + (org-element--property-idx property)))) + (if idx + (inline-letevals (node value) + (inline-quote + (if (org-element-type-p ,node 'plain-text) + ;; Special case: Do not use parray for plain-text. + (org-add-props ,node nil ,property ,value) + (let ((parray + (or (org-element--parray ,node) + (org-element--put-parray ,node)))) + (when parray (aset parray ,idx ,value)) + ,node)))) + (inline-letevals (node property value) + (inline-quote + (let ((idx (org-element--property-idx ,property))) + (if (and idx (not (org-element-type-p ,node 'plain-text))) + (when-let* + ((parray + (or (org-element--parray ,node) + (org-element--put-parray ,node)))) + (aset parray idx ,value)) + (pcase (org-element-type ,node) + (`nil nil) + (`plain-text + (org-add-props ,node nil ,property ,value)) + (_ + ;; Note that `plist-put' adds new elements at the end, + ;; thus keeping `:standard-properties' as the first element. + (setcar (cdr ,node) (plist-put (nth 1 ,node) ,property ,value))))) + ,node)))))) + +(define-inline org-element-put-property-2 (property value node) + "Like `org-element-put-property', but NODE is the last argument. +See `org-element-put-property' for the meaning of PROPERTY and VALUE." + (inline-quote (org-element-put-property ,node ,property ,value))) + +(defun org-element--property (property node &optional dflt force-undefer) + "Extract the value from the PROPERTY of a NODE. +Return DFLT when PROPERTY is not present. +When FORCE-UNDEFER is non-nil, unconditionally resolve deferred +properties, replacing their values in NODE." + (let ((value (org-element-property-raw property node 'org-element-ast--nil))) + ;; PROPERTY not present. + (when (and (eq 'org-element-ast--nil value) + (org-element-deferred-p + (org-element-property-raw :deferred node))) + ;; If :deferred has `org-element-deferred' type, resolve it for + ;; side-effects, and re-assign the new value. + (org-element--property :deferred node nil 'force-undefer) + ;; Try to retrieve the value again. + (setq value (org-element-property-raw property node dflt))) + ;; Deferred property. Resolve it recursively. + (when (org-element-deferred-p value) + (let ((retry t) (firstiter t)) + (while retry + (if firstiter (setq firstiter nil) ; avoid extra call to `org-element-property-raw'. + (setq value (org-element-property-raw property node 'org-element-ast--nil))) + (catch :org-element-deferred-retry + (pcase-let + ((`(,resolved . ,value-to-store) + (org-element--deferred-resolve value node force-undefer))) + (setq value resolved) + ;; Store the resolved property value, if needed. + (unless (eq value-to-store 'org-element-ast--nil) + (org-element-put-property node property value-to-store))) + ;; Finished resolving. + (setq retry nil))))) + ;; Return the resolved value. + (if (eq value 'org-element-ast--nil) dflt value))) + +(define-inline org-element-property (property node &optional dflt force-undefer) + "Extract the value from the PROPERTY of a NODE. +Return DFLT when PROPERTY is not present. +When FORCE-UNDEFER is non-nil and the property value is computed +dynamically, unconditionally replace the dynamic deferred value, +modifying NODE by side effect. + +Note: The properties listed in `org-element--standard-properties', +except `:deferred', may not be resolved." + (if (and (inline-const-p property) + (not (memq (inline-const-val property) '(:deferred :parent))) + (org-element--property-idx (inline-const-val property))) + ;; This is an important optimization, making common org-element + ;; API calls much faster. + (inline-quote (org-element-property-raw ,property ,node ,dflt)) + (inline-quote (org-element--property ,property ,node ,dflt ,force-undefer)))) + +(define-inline org-element-property-2 (node property &optional dflt force-undefer) + "Like `org-element-property', but reverse the order of NODE and PROPERTY." + (inline-quote (org-element-property ,property ,node ,dflt ,force-undefer))) + +(defsubst org-element-parent (node) + "Return `:parent' property of NODE." + (org-element-property :parent node)) + +(gv-define-setter org-element-parent (value node) + `(org-element-put-property ,node :parent ,value)) + +(gv-define-setter org-element-property (value property node &optional _) + `(org-element-put-property ,node ,property ,value)) + +(gv-define-setter org-element-property-raw (value property node &optional _) + `(org-element-put-property ,node ,property ,value)) + +(defun org-element--properties-mapc (fun node &optional collect no-standard) + "Apply FUN for each property of NODE. +FUN will be called with three arguments: property name, property +value, and node. If FUN accepts only 2 arguments, it will be called +with two arguments: property name and property value. If FUN accepts +only a single argument, it will be called with a single argument - +property value. + +Do not resolve deferred values, except `:deferred'. +`:standard-properties' internal property will be skipped. + +When NO-STANDARD is non-nil, do no map over +`org-element--standard-properties'. + +When COLLECT is symbol `set', set the property values to the return +values (except the values equal to `org-element-ast--nil') and finally +return nil. When COLLECT is non-nil and not symbol `set', collect the +return values into a list and return it. +Otherwise, return nil." + (let ( acc rtn (fun-arity (cdr (func-arity fun))) + (type (org-element-type node))) + (when type + ;; Compute missing properties. + (org-element-property :deferred node) + ;; Map over parray. + (unless no-standard + (let ((standard-idxs + org-element--standard-properties-idxs) + (parray (org-element--parray node))) + (when parray + (while standard-idxs + (setq + rtn + (pcase fun-arity + (1 (funcall fun (aref parray (cadr standard-idxs)))) + (2 (funcall + fun + (car standard-idxs) + (aref parray (cadr standard-idxs)))) + (_ (funcall + fun + (car standard-idxs) + (aref parray (cadr standard-idxs)) + node)))) + (when collect + (unless (eq rtn (aref parray (cadr standard-idxs))) + (if (and (eq collect 'set) (not (eq rtn 'org-element-ast--nil))) + (setf (aref parray (cadr standard-idxs)) rtn) + (push rtn acc)))) + (setq standard-idxs (cddr standard-idxs)))))) + ;; Map over plist. + (let ((props + (if (eq type 'plain-text) + (text-properties-at 0 node) + (nth 1 node)))) + (while props + (unless (eq :standard-properties (car props)) + (setq rtn + (pcase fun-arity + (1 (funcall fun (cadr props))) + (2 (funcall fun (car props) (cadr props))) + (_ (funcall fun (car props) (cadr props) node)))) + (when collect + (if (and (eq collect 'set) + (not (eq rtn 'org-element-ast--nil))) + (unless (eq rtn (cadr props)) + (if (eq type 'plain-text) + (org-add-props node nil (car props) rtn) + (setf (cadr props) rtn))) + (push rtn acc)))) + (setq props (cddr props))))) + ;; Return. + (when collect (nreverse acc)))) + +(defun org-element--deferred-resolve-force-rec (property val node) + "Resolve deferred PROPERTY VAL in NODE recursively. Force undefer." + (catch :found + (catch :org-element-deferred-retry + (throw :found (org-element--deferred-resolve-force val node))) + ;; Caught `:org-element-deferred-retry'. Go long way. + (org-element-property property node nil t))) + +(defun org-element--deferred-resolve-rec (property val node) + "Resolve deferred PROPERTY VAL in NODE recursively. +Return the value to be stored." + (catch :found + (catch :org-element-deferred-retry + (throw :found (cdr (org-element--deferred-resolve val node)))) + ;; Caught `:org-element-deferred-retry'. Go long way. + (org-element-property property node))) + +(defsubst org-element-properties-resolve (node &optional force-undefer) + "Resolve all the deferred properties in NODE, modifying the NODE. +When FORCE-UNDEFER is non-nil, resolve unconditionally. +Return the modified NODE." + ;; Compute all the available properties. + (org-element-property :deferred node nil force-undefer) + (org-element--properties-mapc + (if force-undefer + #'org-element--deferred-resolve-force-rec + #'org-element--deferred-resolve-rec) + node 'set 'no-standard) + node) + +(defsubst org-element-properties-mapc (fun node &optional undefer) + "Apply FUN for each property of NODE for side effect. +FUN will be called with three arguments: property name, property +value, and node. If FUN accepts only 2 arguments, it will be called +with two arguments: property name and property value. If FUN accepts +only a single argument, it will be called with a single argument - +property value. + +When UNDEFER is non-nil, undefer deferred properties. +When UNDEFER is symbol `force', unconditionally replace the property +values with undeferred values. + +Return nil." + (when undefer + (org-element-properties-resolve node (eq 'force undefer))) + (org-element--properties-mapc fun node)) + +;; There is purposely no function like `org-element-properties' that +;; returns a list of properties. Such function would tempt the users +;; to (1) run it, creating a whole new list; (2) filter over that list +;; - the process requiring a lot of extra consing, adding a load onto +;; Emacs GC, memory used, and slowing things up as creating new lists +;; is not free for CPU. +(defsubst org-element-properties-map (fun node &optional undefer) + "Apply FUN for each property of NODE and return a list of the results. +FUN will be called with three arguments: property name, property +value, and node. If FUN accepts only 2 arguments, it will be called +with two arguments: property name and property value. If FUN accepts +only a single argument, it will be called with a single argument - +property value. + +When UNDEFER is non-nil, undefer deferred properties unconditionally. +When UNDEFER is symbol `force', unconditionally replace the property +values with undeferred values." + (when undefer + (org-element-properties-resolve node (eq 'force undefer))) + (org-element--properties-mapc fun node 'collect)) + +;;;; Node contents. + +(defsubst org-element-contents (node) + "Extract contents from NODE. +Do not resolve deferred values." + (declare (pure t)) + (cond ((not (consp node)) nil) + ((symbolp (car node)) (nthcdr 2 node)) + (t node))) + +(defsubst org-element-set-contents (node &rest contents) + "Set NODE's contents to CONTENTS. +Return modified NODE. +If NODE cannot have contents, return CONTENTS." + (pcase (org-element-type node t) + (`plain-text contents) + ((guard (null node)) contents) + ;; Anonymous node. + (`anonymous + (setcar node (car contents)) + (setcdr node (cdr contents)) + node) + ;; Node with type. + (_ (setf (cddr node) contents) + node))) + +(defalias 'org-element-resolve-deferred #'org-element-properties-resolve) + +;;;; Constructor and copier + +(defun org-element-create (type &optional props &rest children) + "Create a new syntax node of TYPE. +Optional argument PROPS, when non-nil, is a plist defining the +properties of the node. CHILDREN can be elements, objects or +strings. + +When CHILDREN is a single anonymous node, use its contents as children +nodes. This way, + (org-element-create \\='section nil (org-element-contents node)) +will yield expected results with contents of another node adopted into +a newly created one. + +When TYPE is `plain-text', CHILDREN must contain a single node - +string. Alternatively, TYPE can be a string. When TYPE is nil or +`anonymous', PROPS must be nil." + (cl-assert + ;; FIXME: Just use `plistp' from Emacs 29 when available. + (let ((len (proper-list-p props))) + (and len (zerop (% len 2))))) + ;; Assign parray. + (when (and props (not (stringp type)) (not (eq type 'plain-text))) + (let ((node (list 'dummy props))) + (org-element--put-parray node) + (setq props (nth 1 node)) + ;; Remove standard properties from PROPS plist by side effect. + (let ((ptail props)) + (while ptail + (if (not (and (keywordp (car ptail)) + (org-element--property-idx (car ptail)))) + (setq ptail (cddr ptail)) + (if (null (cddr ptail)) ; last property + (setq props (nbutlast props 2) + ptail nil) + (setcar ptail (nth 2 ptail)) + (setcdr ptail (seq-drop ptail 3)))))))) + (pcase type + ((or `nil `anonymous) + (cl-assert (null props)) + (apply #'org-element-adopt nil children)) + (`plain-text + (cl-assert (= (length children) 1)) + (org-add-props (car children) props)) + ((pred stringp) + (if props (org-add-props type props) type)) + (_ + (if (and (= 1 (length children)) + (org-element-type-p (car children) 'anonymous)) + (apply #'org-element-adopt (list type props) (car children)) + (apply #'org-element-adopt (list type props) children))))) + +(defun org-element-copy (datum &optional keep-contents) + "Return a copy of DATUM. +DATUM is an element, object, string or nil. `:parent' property +is cleared and contents are removed in the process. +Secondary objects are also copied and their `:parent' is re-assigned. + +When optional argument KEEP-CONTENTS is non-nil, do not remove the +contents. Instead, copy the children recursively, updating their +`:parent' property. + +As a special case, `anonymous' nodes do not have their contents +removed. The contained children are copied recursively, updating +their `:parent' property to the copied `anonymous' node. + +When DATUM is `plain-text', all the properties are removed." + (pcase (org-element-type datum t) + ((guard (null datum)) nil) + (`plain-text (substring-no-properties datum)) + (`nil (error "Not an Org syntax node: %S" datum)) + (`anonymous + (let* ((node-copy (copy-sequence datum)) + (tail node-copy)) + (while tail + (setcar tail (org-element-copy (car tail) t)) + (org-element-put-property (car tail) :parent node-copy) + (setq tail (cdr tail))) + node-copy)) + (type + (let ((node-copy (append (list type (copy-sequence (cadr datum))) (copy-sequence (cddr datum))))) + ;; Copy `:standard-properties' + (when-let* ((parray (org-element-property-raw :standard-properties node-copy))) + (org-element-put-property node-copy :standard-properties (copy-sequence parray))) + ;; Clear `:parent'. + (org-element-put-property node-copy :parent nil) + ;; We cannot simply return the copied property list. When + ;; DATUM is i.e. a headline, it's property list `:title' can + ;; contain parsed objects. The objects will contain + ;; `:parent' property set to the DATUM itself. When copied, + ;; these inner `:parent' property values will contain + ;; incorrect object decoupled from DATUM. Changes to the + ;; DATUM copy will no longer be reflected in the `:parent' + ;; properties. So, we need to reassign inner `:parent' + ;; properties to the DATUM copy explicitly. + (dolist (secondary-prop (org-element-property :secondary node-copy)) + (when-let* ((secondary-value (org-element-property secondary-prop node-copy))) + (setq secondary-value (org-element-copy secondary-value t)) + (if (org-element-type secondary-value) + (org-element-put-property secondary-value :parent node-copy) + (dolist (el secondary-value) + (org-element-put-property el :parent node-copy))) + (org-element-put-property node-copy secondary-prop secondary-value))) + (when keep-contents + (let ((contents (org-element-contents node-copy))) + (while contents + (setcar contents (org-element-copy (car contents) t)) + (setq contents (cdr contents))))) + node-copy)))) + +;;;; AST queries + +(defun org-element-ast-map + ( data types fun + &optional + ignore first-match no-recursion + with-properties no-secondary no-undefer) + "Map a function on selected syntax nodes. + +DATA is a syntax tree. TYPES is a symbol or list of symbols of +node types. FUN is the function called on the matching nodes. +It has to accept one argument: the node itself. + +When TYPES is t, call FUN for all the node types. + +FUN can also be a Lisp form. The form will be evaluated as function +with symbol `node' bound to the current node. + +When optional argument IGNORE is non-nil, it should be a list holding +nodes to be skipped. In that case, the listed nodes and their +contents will be skipped. + +When optional argument FIRST-MATCH is non-nil, stop at the first +match for which FUN doesn't return nil, and return that value. + +Optional argument NO-RECURSION is a symbol or a list of symbols +representing node types. `org-element-map' won't enter any recursive +element or object whose type belongs to that list. Though, FUN can +still be applied on them. + +When optional argument WITH-PROPERTIES is non-nil, it should hold a list +of property names. These properties will be treated as additional +secondary properties. + +When optional argument NO-SECONDARY is non-nil, do not recurse into +secondary strings. + +When optional argument NO-UNDEFER is non-nil, do not resolve deferred +values. + +FUN may also throw `:org-element-skip' signal. Then, +`org-element-ast-map' will not recurse into the current node. + +Nil values returned from FUN do not appear in the results." + (declare (indent 2)) + ;; Ensure TYPES and NO-RECURSION are a list, even of one node. + (when types + (let* ((types (pcase types + ((pred listp) types) + (`t t) + (_ (list types)))) + (no-recursion (if (listp no-recursion) no-recursion + (list no-recursion))) + (fun (if (functionp fun) fun `(lambda (node) ,fun))) + --acc) + (letrec ((--walk-tree + (lambda (--data) + ;; Recursively walk DATA. INFO, if non-nil, is a plist + ;; holding contextual information. + (let ((--type (org-element-type --data t)) + recurse) + (cond + ((not --data)) + ((not --type)) + ;; Ignored node in an export context. + ((and ignore (memq --data ignore))) + ;; List of elements or objects. + ((eq --type 'anonymous) + (mapc --walk-tree (org-element-contents --data))) + (t + ;; Check if TYPE is matching among TYPES. If so, + ;; apply FUN to --DATA and accumulate return value + ;; into --ACC (or exit if FIRST-MATCH is non-nil). + (setq recurse t) + (when (or (eq types t) (memq --type types)) + (let ((result + (catch :org-element-skip + (setq recurse nil) + (prog1 (funcall fun --data) + (setq recurse t))))) + (cond ((not result)) + (first-match (throw :--map-first-match result)) + (t (push result --acc))))) + ;; Determine if a recursion into --DATA is possible. + (cond + ;; No recursion requested. + ((not recurse)) + ;; --TYPE is explicitly removed from recursion. + ((memq --type no-recursion)) + ;; In any other case, map secondary, affiliated, and contents. + (t + (when with-properties + (dolist (p with-properties) + (funcall + --walk-tree + (if no-undefer + (org-element-property-raw p --data) + (org-element-property p --data))))) + (unless no-secondary + (dolist (p (org-element-property :secondary --data)) + (funcall + --walk-tree + (if no-undefer + (org-element-property-raw p --data) + (org-element-property p --data))))) + (mapc --walk-tree (org-element-contents --data)))))))))) + (catch :--map-first-match + (funcall --walk-tree data) + ;; Return value in a proper order. + (nreverse --acc)))))) + +(defun org-element-lineage (datum &optional types with-self) + "List all ancestors of a given element or object. + +DATUM is an object or element. + +Return ancestors from the closest to the farthest. When optional +argument TYPES is a symbol or a list of symbols, return the first +element or object in the lineage whose type equals or belongs to that +list instead. + +When optional argument WITH-SELF is non-nil, lineage includes +DATUM itself as the first element, and TYPES, if provided, also +apply to it. + +When DATUM is obtained through `org-element-context' or +`org-element-at-point', and org-element-cache is disabled, only +ancestors from its section can be found. There is no such limitation +when DATUM belongs to a full parse tree." + (when (and types (not (listp types))) (setq types (list types))) + (let ((up (if with-self datum (org-element-parent datum))) + ancestors) + (while (and up (not (org-element-type-p up types))) + (unless types (push up ancestors)) + (setq up (org-element-parent up))) + (if types up (nreverse ancestors)))) + +(defun org-element-lineage-map (datum fun &optional types with-self first-match) + "Map FUN across ancestors of DATUM, from closest to furthest. +Return a list of results. Nil values returned from FUN do not appear +in the results. + +DATUM is an object or element. + +FUN is a function accepting a single argument: syntax node. +FUN can also be a Lisp form. The form will be evaluated as function +with symbol `node' bound to the current node. + +When optional argument TYPES is a list of symbols, only map across +nodes with the listed types. + +When optional argument WITH-SELF is non-nil, lineage includes +DATUM itself as the first element, and TYPES, if provided, also +apply to it. + +When optional argument FIRST-MATCH is non-nil, stop at the first +match for which FUN doesn't return nil, and return that value." + (declare (indent 2)) + (setq fun (if (functionp fun) fun `(lambda (node) ,fun))) + (let ((up (if with-self datum (org-element-parent datum))) + acc rtn) + (catch :--first-match + (while up + (when (or (not types) (org-element-type-p up types)) + (setq rtn (funcall fun up)) + (if (and first-match rtn) + (throw :--first-match rtn) + (when rtn (push rtn acc)))) + (setq up (org-element-parent up))) + (nreverse acc)))) + +(defun org-element-property-inherited (property node &optional with-self accumulate literal-nil include-nil) + "Extract non-nil value from the PROPERTY of a NODE and/or its parents. + +PROPERTY is a single property or a list of properties to be considered. + +When WITH-SELF is non-nil, consider PROPERTY in the NODE itself. +Otherwise, only start from the immediate parent. + +When optional argument ACCUMULATE is nil, return the first non-nil value +\(properties when PROPERTY is a list are considered one by one). +When ACCUMULATE is non-nil, extract all the values, starting from the +outermost ancestor and accumulate them into a single list. The values +that are lists are appended. + +When LITERAL-NIL is non-nil, treat property values \"nil\" and nil. + +When INCLUDE-NIL is non-nil, do not skip properties with value nil. The +properties that are missing from the property list will still be +skipped." + (unless (listp property) (setq property (list property))) + (let (acc local val) + (catch :found + (unless with-self (setq node (org-element-parent node))) + (while node + (setq local nil) + (dolist (prop property) + (setq val (org-element-property prop node 'org-element-ast--nil)) + (unless (eq val 'org-element-ast--nil) ; not present + (when literal-nil (setq val (org-not-nil val))) + (when (and (not accumulate) (or val include-nil)) + (throw :found val)) + ;; Append to the end. + (if (and include-nil (not val)) + (setq local (append local '(nil))) + (setq local (append local (if (listp val) val (list val))))))) + ;; Append parent to front. + (setq acc (append local acc)) + (setq node (org-element-parent node))) + acc))) + +;;;; AST modification + +(defalias 'org-element-adopt-elements #'org-element-adopt) +(defun org-element-adopt (parent &rest children) + "Append CHILDREN to the contents of PARENT. + +PARENT is a syntax node. CHILDREN can be elements, objects, or +strings. + +If PARENT is nil, create a new anonymous node containing CHILDREN. + +The function takes care of setting `:parent' property for each child. +Return the modified PARENT." + (declare (indent 1)) + (if (not children) parent + ;; Link every child to PARENT. If PARENT is nil, it is a secondary + ;; string: parent is the list itself. + (dolist (child children) + (when child + (org-element-put-property child :parent (or parent children)))) + ;; Add CHILDREN at the end of PARENT contents. + (when parent + (apply #'org-element-set-contents + parent + (nconc (org-element-contents parent) children))) + ;; Return modified PARENT element. + (or parent children))) + +(defalias 'org-element-extract-element #'org-element-extract) +(defun org-element-extract (node) + "Extract NODE from parse tree. +Remove NODE from the parse tree by side-effect, and return it +with its `:parent' property stripped out." + (let ((parent (org-element-parent node)) + (secondary (org-element-secondary-p node))) + (if secondary + (org-element-put-property + parent secondary + (delq node (org-element-property secondary parent))) + (apply #'org-element-set-contents + parent + (delq node (org-element-contents parent)))) + ;; Return NODE with its :parent removed. + (org-element-put-property node :parent nil))) + +(defun org-element-insert-before (node location) + "Insert NODE before LOCATION in parse tree. +LOCATION is an element, object or string within the parse tree. +Parse tree is modified by side effect." + (let* ((parent (org-element-parent location)) + (property (org-element-secondary-p location)) + (siblings (if property (org-element-property property parent) + (org-element-contents parent))) + ;; Special case: LOCATION is the first element of an + ;; independent secondary string (e.g. :title property). Add + ;; NODE in-place. + (specialp (and (not property) + (eq siblings parent) + (eq (car parent) location)))) + ;; Install NODE at the appropriate LOCATION within SIBLINGS. + (cond (specialp) + ((or (null siblings) (eq (car siblings) location)) + (push node siblings)) + ((null location) (nconc siblings (list node))) + (t + (let ((index (cl-position location siblings))) + (unless index (error "No location found to insert node")) + (push node (cdr (nthcdr (1- index) siblings)))))) + ;; Store SIBLINGS at appropriate place in parse tree. + (cond + (specialp (setcdr parent (copy-sequence parent)) (setcar parent node)) + (property (org-element-put-property parent property siblings)) + (t (apply #'org-element-set-contents parent siblings))) + ;; Set appropriate :parent property. + (org-element-put-property node :parent parent))) + +(defalias 'org-element-set-element #'org-element-set) +(defun org-element-set (old new &optional keep-props) + "Replace element or object OLD with element or object NEW. +When KEEP-PROPS is non-nil, keep OLD values of the listed property +names. + +Return the modified element. + +The function takes care of setting `:parent' property for NEW." + ;; Ensure OLD and NEW have the same parent. + (org-element-put-property new :parent (org-element-property :parent old)) + ;; Handle KEEP-PROPS. + (dolist (p keep-props) + (org-element-put-property new p (org-element-property p old))) + (let ((old-type (org-element-type old)) + (new-type (org-element-type new))) + (if (or (eq old-type 'plain-text) + (eq new-type 'plain-text)) + ;; We cannot replace OLD with NEW since strings are not mutable. + ;; We take the long path. + (progn + (org-element-insert-before new old) + (org-element-extract old) + ;; We will return OLD. + (setq old new)) + ;; Since OLD is going to be changed into NEW by side-effect, first + ;; make sure that every element or object within NEW has OLD as + ;; parent. + (dolist (blob (org-element-contents new)) + (org-element-put-property blob :parent old)) + ;; Both OLD and NEW are lists. + (setcar old (car new)) + (setcdr old (cdr new)))) + old) + +(provide 'org-element-ast) +;;; org-element-ast.el ends here diff --git a/elpa/org-9.6.7/org-element.el b/elpa/org-9.7.17/org-element.el similarity index 57% rename from elpa/org-9.6.7/org-element.el rename to elpa/org-9.7.17/org-element.el index df43ebcf..f119ed73 100644 --- a/elpa/org-9.6.7/org-element.el +++ b/elpa/org-9.7.17/org-element.el @@ -1,9 +1,10 @@ ;;; org-element.el --- Parser for Org Syntax -*- lexical-binding: t; -*- -;; Copyright (C) 2012-2023 Free Software Foundation, Inc. +;; Copyright (C) 2012-2024 Free Software Foundation, Inc. ;; Author: Nicolas Goaziou -;; Keywords: outlines, hypermedia, calendar, wp +;; Maintainer: Ihor Radchenko +;; Keywords: outlines, hypermedia, calendar, text ;; This file is part of GNU Emacs. @@ -77,6 +78,7 @@ (declare-function org-at-heading-p "org" (&optional _)) (declare-function org-escape-code-in-string "org-src" (s)) +(declare-function org-src-preserve-indentation-p "org-src" (&optional node)) (declare-function org-macro-escape-arguments "org-macro" (&rest args)) (declare-function org-macro-extract-arguments "org-macro" (s)) (declare-function org-reduced-level "org" (l)) @@ -93,7 +95,6 @@ (defvar org-property-drawer-re) (defvar org-property-format) (defvar org-property-re) -(defvar org-src-preserve-indentation) (defvar org-tags-column) (defvar org-todo-regexp) (defvar org-ts-regexp-both) @@ -109,7 +110,7 @@ ;; to current setup. (defconst org-element-archive-tag "ARCHIVE" - "Tag marking a substree as archived.") + "Tag marking a subtree as archived.") (defconst org-element-citation-key-re (rx "@" (group (one-or-more (any word "-.:?!`'/*@+|(){}<>&_^$#%~")))) @@ -125,17 +126,24 @@ Key is located in match group 1.") Style, if any, is located in match group 1.") (defconst org-element-clock-line-re - (rx-to-string - `(seq - line-start (0+ (or ?\t ?\s)) - "CLOCK: " - (regexp ,org-ts-regexp-inactive) - (opt "--" - (regexp ,org-ts-regexp-inactive) - (1+ (or ?\t ?\s)) "=>" (1+ (or ?\t ?\s)) - (1+ digit) ":" digit digit) - (0+ (or ?\t ?\s)) - line-end)) + (let ((duration ; "=> 212:12" + '(seq + (1+ (or ?\t ?\s)) "=>" (1+ (or ?\t ?\s)) + (1+ digit) ":" digit digit))) + (rx-to-string + `(seq + line-start (0+ (or ?\t ?\s)) + "CLOCK:" + (or + (seq + (1+ (or ?\t ?\s)) + (regexp ,org-ts-regexp-inactive) + (opt "--" + (regexp ,org-ts-regexp-inactive) + ,duration)) + ,duration) + (0+ (or ?\t ?\s)) + line-end))) "Regexp matching a clock line.") (defconst org-element-comment-string "COMMENT" @@ -169,6 +177,12 @@ Style, if any, is located in match group 1.") "Regexp matching opening or closing line of a drawer. Drawer's name is located in match group 1.") +(defconst org-element-drawer-re-nogroup + (rx line-start (0+ (any ?\s ?\t)) + ":" (1+ (any ?- ?_ word)) ":" + (0+ (any ?\s ?\t)) line-end) + "Regexp matching opening or closing line of a drawer.") + (defconst org-element-dynamic-block-open-re (rx line-start (0+ (any ?\s ?\t)) "#+BEGIN:" (0+ (any ?\s ?\t)) @@ -180,6 +194,11 @@ Drawer's name is located in match group 1.") Dynamic block's name is located in match group 1. Parameters are in match group 2.") +(defconst org-element-dynamic-block-open-re-nogroup + (rx line-start (0+ (any ?\s ?\t)) + "#+BEGIN:" (0+ (any ?\s ?\t)) word) + "Regexp matching the opening line of a dynamic block.") + (defconst org-element-headline-re (rx line-start (1+ "*") " ") "Regexp matching a headline.") @@ -400,10 +419,14 @@ Don't modify it, set `org-element-affiliated-keywords' instead.") subscript superscript underline verbatim)) (standard-set (remq 'citation-reference (remq 'table-cell org-element-all-objects))) - (standard-set-no-line-break (remq 'line-break standard-set))) + (standard-set-no-line-break (remq 'line-break standard-set)) + (standard-set-for-citations (seq-difference + standard-set-no-line-break + '( citation citation-reference + footnote-reference link)))) `((bold ,@standard-set) (citation citation-reference) - (citation-reference ,@minimal-set) + (citation-reference ,@standard-set-for-citations) (footnote-reference ,@standard-set) (headline ,@standard-set-no-line-break) (inlinetask ,@standard-set-no-line-break) @@ -487,6 +510,208 @@ past the brackets." (goto-char end) (buffer-substring-no-properties (1+ pos) (1- end))))))))) +(defconst org-element--cache-variables + '( org-element--cache org-element--cache-size + org-element--headline-cache org-element--headline-cache-size + org-element--cache-hash-left org-element--cache-hash-right + org-element--cache-sync-requests org-element--cache-sync-timer + org-element--cache-sync-keys-value org-element--cache-change-tic + org-element--cache-last-buffer-size + org-element--cache-diagnostics-ring + org-element--cache-diagnostics-ring-size + org-element--cache-gapless + org-element--cache-change-warning) + "List of variable symbols holding cache state.") + +(defconst org-element-ignored-local-variables + `( org-font-lock-keywords + ,@org-element--cache-variables) + "List of variables not copied through upon Org buffer duplication. +Export process and parsing in `org-element-parse-secondary-string' +takes place on a copy of the original buffer. When this copy is +created, all Org related local variables not in this list are copied +to the new buffer. Variables with an unreadable value are also +ignored.") + +(cl-defun org-element--generate-copy-script (buffer + &key + copy-unreadable + drop-visibility + drop-narrowing + drop-contents + drop-locals) + "Generate a function duplicating BUFFER. + +The copy will preserve local variables, visibility, contents and +narrowing of the original buffer. If a region was active in +BUFFER, contents will be narrowed to that region instead. + +When optional key COPY-UNREADABLE is non-nil, do not ensure that all +the copied local variables will be readable in another Emacs session. + +When optional keys DROP-VISIBILITY, DROP-NARROWING, DROP-CONTENTS, or +DROP-LOCALS are non-nil, do not preserve visibility, narrowing, +contents, or local variables correspondingly. + +The resulting function can be evaluated at a later time, from +another buffer, effectively cloning the original buffer there. + +The function assumes BUFFER's major mode is `org-mode'." + (declare-function org-fold-core--update-buffer-folds "org-fold-core" ()) + (require 'org-fold-core) + (with-current-buffer buffer + (let ((str (unless drop-contents (org-with-wide-buffer (buffer-string)))) + (narrowing + (unless drop-narrowing + (if (org-region-active-p) + (list (region-beginning) (region-end)) + (list (point-min) (point-max))))) + (pos (point)) + (varvals + (unless drop-locals + (let ((varvals nil)) + (dolist (entry (buffer-local-variables (buffer-base-buffer))) + (when (consp entry) + (let ((var (car entry)) + (val (cdr entry))) + (and (not (memq var org-element-ignored-local-variables)) + (or (memq var + '(default-directory + ;; Required to convert file + ;; links in the #+INCLUDEd + ;; files. See + ;; `org-export--prepare-file-contents'. + buffer-file-name + buffer-file-coding-system + ;; Needed to preserve folding state + char-property-alias-alist)) + (string-match-p "^\\(org-\\|orgtbl-\\)" + (symbol-name var))) + ;; Skip unreadable values, as they cannot be + ;; sent to external process. + (or copy-unreadable (not val) + (ignore-errors (read (format "%S" val)))) + (push (cons var val) varvals))))) + varvals))) + (ols + (unless drop-visibility + (let (ov-set) + (dolist (ov (overlays-in (point-min) (point-max))) + (let ((invis-prop (overlay-get ov 'invisible))) + (when invis-prop + (push (list (overlay-start ov) (overlay-end ov) + (overlay-properties ov)) + ov-set)))) + ov-set)))) + (lambda () + (let ((inhibit-modification-hooks t)) + ;; Set major mode. Ignore `org-mode-hook' and other hooks as + ;; they have been run already in BUFFER. + (unless (eq major-mode 'org-mode) + (delay-mode-hooks + (let ((org-inhibit-startup t)) (org-mode)))) + ;; Copy specific buffer local variables. + (pcase-dolist (`(,var . ,val) varvals) + (set (make-local-variable var) val)) + ;; Whole buffer contents when requested. + (when str + (let ((inhibit-read-only t)) + (erase-buffer) (insert str))) + ;; Make org-element-cache not complain about changed buffer + ;; state. + (org-element-cache-reset nil 'no-persistence) + ;; Narrowing. + (when narrowing + (apply #'narrow-to-region narrowing)) + ;; Current position of point. + (goto-char pos) + ;; Overlays with invisible property. + (pcase-dolist (`(,start ,end ,props) ols) + (let ((ov (make-overlay start end))) + (while props + (overlay-put ov (pop props) (pop props))))) + ;; Text property folds. + (unless drop-visibility (org-fold-core--update-buffer-folds)) + ;; Never write the buffer copy to disk, despite + ;; `buffer-file-name' not being nil. + (setq write-contents-functions (list (lambda (&rest _) t)))))))) + +(cl-defun org-element-copy-buffer (&key to-buffer drop-visibility + drop-narrowing drop-contents + drop-locals) + "Return a copy of the current buffer. +The copy preserves Org buffer-local variables, visibility and +narrowing. + +IMPORTANT: The buffer copy may also have variable `buffer-file-name' +copied. + +To prevent Emacs overwriting the original buffer file, +`write-contents-functions' is set to \\='(always). Do not alter this +variable and do not do anything that might alter it (like calling a +major mode) to prevent data corruption. Also, do note that Emacs may +jump into the created buffer if the original file buffer is closed and +then re-opened. Making edits in the buffer copy may also trigger +Emacs save dialog. Prefer using `org-element-with-buffer-copy' macro +when possible. + +When optional key TO-BUFFER is non-nil, copy into BUFFER. + +Optional keys DROP-VISIBILITY, DROP-NARROWING, DROP-CONTENTS, and +DROP-LOCALS are passed to `org-element--generate-copy-script'." + (let ((copy-buffer-fun (org-element--generate-copy-script + (current-buffer) + :copy-unreadable 'do-not-check + :drop-visibility drop-visibility + :drop-narrowing drop-narrowing + :drop-contents drop-contents + :drop-locals drop-locals)) + (new-buf (or to-buffer (generate-new-buffer (buffer-name))))) + (with-current-buffer new-buf + (funcall copy-buffer-fun) + (set-buffer-modified-p nil)) + new-buf)) + +(cl-defmacro org-element-with-buffer-copy ( &rest body + &key to-buffer drop-visibility + drop-narrowing drop-contents + drop-locals + &allow-other-keys) + "Apply BODY in a copy of the current buffer. +The copy preserves local variables, visibility and contents of +the original buffer. Point is at the beginning of the buffer +when BODY is applied. + +Optional keys can modify what is being copied and the generated buffer +copy. TO-BUFFER, DROP-VISIBILITY, DROP-NARROWING, DROP-CONTENTS, and +DROP-LOCALS are passed as arguments to `org-element-copy-buffer'." + (declare (debug t)) + ;; Drop keyword arguments from BODY. + (while (keywordp (car body)) (pop body) (pop body)) + (org-with-gensyms (buf-copy) + `(let ((,buf-copy (org-element-copy-buffer + :to-buffer ,to-buffer + :drop-visibility ,drop-visibility + :drop-narrowing ,drop-narrowing + :drop-contents ,drop-contents + :drop-locals ,drop-locals))) + (unwind-protect + (with-current-buffer ,buf-copy + (goto-char (point-min)) + (prog1 + (progn ,@body) + ;; `org-element-copy-buffer' carried the value of + ;; `buffer-file-name' from the original buffer. When not + ;; killed, the new buffer copy may become a target of + ;; `find-file'. Prevent this. + (setq buffer-file-name nil))) + (and (buffer-live-p ,buf-copy) + ;; Kill copy without confirmation. + (progn (with-current-buffer ,buf-copy + (restore-buffer-modified-p nil)) + (unless ,to-buffer + (kill-buffer ,buf-copy)))))))) + ;;; Accessors and Setters ;; @@ -497,38 +722,18 @@ past the brackets." ;; There is `org-element-put-property', `org-element-set-contents'. ;; These low-level functions are useful to build a parse tree. ;; -;; `org-element-adopt-elements', `org-element-set-element', -;; `org-element-extract-element' and `org-element-insert-before' are -;; high-level functions useful to modify a parse tree. +;; `org-element-adopt', `org-element-set', `org-element-extract' and +;; `org-element-insert-before' are high-level functions useful to +;; modify a parse tree. ;; ;; `org-element-secondary-p' is a predicate used to know if a given ;; object belongs to a secondary string. `org-element-class' tells if ;; some parsed data is an element or an object, handling pseudo ;; elements and objects. `org-element-copy' returns an element or -;; object, stripping its parent property in the process. - -(defsubst org-element-type (element) - "Return type of ELEMENT. - -The function returns the type of the element or object provided. -It can also return the following special value: - `plain-text' for a string - `org-data' for a complete document - nil in any other case." - (cond - ((not (consp element)) (and (stringp element) 'plain-text)) - ((symbolp (car element)) (car element)))) - -(defsubst org-element-property (property element) - "Extract the value from the PROPERTY of an ELEMENT." - (if (stringp element) (get-text-property 0 property element) - (plist-get (nth 1 element) property))) +;; object, stripping its parent property and resolving deferred values +;; in the process. -(defsubst org-element-contents (element) - "Extract contents from an ELEMENT." - (cond ((not (consp element)) nil) - ((symbolp (car element)) (nthcdr 2 element)) - (t element))) +(require 'org-element-ast) (defsubst org-element-restriction (element) "Return restriction associated to ELEMENT. @@ -537,39 +742,13 @@ element or object type." (cdr (assq (if (symbolp element) element (org-element-type element)) org-element-object-restrictions))) -(defsubst org-element-put-property (element property value) - "In ELEMENT set PROPERTY to VALUE. -Return modified element." - (if (stringp element) (org-add-props element nil property value) - (setcar (cdr element) (plist-put (nth 1 element) property value)) - element)) - -(defsubst org-element-set-contents (element &rest contents) - "Set ELEMENT's contents to CONTENTS. -Return ELEMENT." - (cond ((null element) contents) - ((not (symbolp (car element))) contents) - ((cdr element) (setcdr (cdr element) contents) element) - (t (nconc element contents)))) - -(defun org-element-secondary-p (object) - "Non-nil when OBJECT directly belongs to a secondary string. -Return value is the property name, as a keyword, or nil." - (let* ((parent (org-element-property :parent object)) - (properties (cdr (assq (org-element-type parent) - org-element-secondary-value-alist)))) - (catch 'exit - (dolist (p properties) - (and (memq object (org-element-property p parent)) - (throw 'exit p)))))) - (defsubst org-element-class (datum &optional parent) "Return class for ELEMENT, as a symbol. Class is either `element' or `object'. Optional argument PARENT is the element or object containing DATUM. It defaults to the value of DATUM `:parent' property." - (let ((type (org-element-type datum)) - (parent (or parent (org-element-property :parent datum)))) + (let ((type (org-element-type datum t)) + (parent (or parent (org-element-parent datum)))) (cond ;; Trivial cases. ((memq type org-element-all-objects) 'object) @@ -577,153 +756,98 @@ value of DATUM `:parent' property." ;; Special cases. ((eq type 'org-data) 'element) ((eq type 'plain-text) 'object) - ((not type) 'object) + ((eq type 'anonymous) 'object) + ((not type) nil) ;; Pseudo object or elements. Make a guess about its class. ;; Basically a pseudo object is contained within another object, ;; a secondary string or a container element. ((not parent) 'element) (t - (let ((parent-type (org-element-type parent))) - (cond ((not parent-type) 'object) + (let ((parent-type (org-element-type parent t))) + (cond ((eq 'anonymous parent-type) 'object) ((memq parent-type org-element-object-containers) 'object) ((org-element-secondary-p datum) 'object) (t 'element))))))) -(defsubst org-element-adopt-elements (parent &rest children) - "Append elements to the contents of another element. - -PARENT is an element or object. CHILDREN can be elements, -objects, or a strings. - -The function takes care of setting `:parent' property for CHILD. -Return parent element." - (declare (indent 1)) - (if (not children) parent - ;; Link every child to PARENT. If PARENT is nil, it is a secondary - ;; string: parent is the list itself. - (dolist (child children) - (when child - (org-element-put-property child :parent (or parent children)))) - ;; Add CHILDREN at the end of PARENT contents. - (when parent - (apply #'org-element-set-contents - parent - (nconc (org-element-contents parent) children))) - ;; Return modified PARENT element. - (or parent children))) - -(defun org-element-extract-element (element) - "Extract ELEMENT from parse tree. -Remove element from the parse tree by side-effect, and return it -with its `:parent' property stripped out." - (let ((parent (org-element-property :parent element)) - (secondary (org-element-secondary-p element))) - (if secondary - (org-element-put-property - parent secondary - (delq element (org-element-property secondary parent))) - (apply #'org-element-set-contents - parent - (delq element (org-element-contents parent)))) - ;; Return ELEMENT with its :parent removed. - (org-element-put-property element :parent nil))) - -(defun org-element-insert-before (element location) - "Insert ELEMENT before LOCATION in parse tree. -LOCATION is an element, object or string within the parse tree. -Parse tree is modified by side effect." - (let* ((parent (org-element-property :parent location)) - (property (org-element-secondary-p location)) - (siblings (if property (org-element-property property parent) - (org-element-contents parent))) - ;; Special case: LOCATION is the first element of an - ;; independent secondary string (e.g. :title property). Add - ;; ELEMENT in-place. - (specialp (and (not property) - (eq siblings parent) - (eq (car parent) location)))) - ;; Install ELEMENT at the appropriate LOCATION within SIBLINGS. - (cond (specialp) - ((or (null siblings) (eq (car siblings) location)) - (push element siblings)) - ((null location) (nconc siblings (list element))) - (t - (let ((index (cl-position location siblings))) - (unless index (error "No location found to insert element")) - (push element (cdr (nthcdr (1- index) siblings)))))) - ;; Store SIBLINGS at appropriate place in parse tree. - (cond - (specialp (setcdr parent (copy-sequence parent)) (setcar parent element)) - (property (org-element-put-property parent property siblings)) - (t (apply #'org-element-set-contents parent siblings))) - ;; Set appropriate :parent property. - (org-element-put-property element :parent parent))) +(defsubst org-element-parent-element (object) + "Return first element containing OBJECT or nil. +OBJECT is the object to consider." + (org-element-lineage object org-element-all-elements)) + +(defsubst org-element-begin (node) + "Get `:begin' property of NODE." + (org-element-property :begin node)) + +(gv-define-setter org-element-begin (value node) + `(org-element-put-property ,node :begin ,value)) + +(defsubst org-element-end (node) + "Get `:end' property of NODE." + (org-element-property :end node)) + +(gv-define-setter org-element-end (value node) + `(org-element-put-property ,node :end ,value)) + +(defsubst org-element-contents-begin (node) + "Get `:contents-begin' property of NODE." + (org-element-property :contents-begin node)) + +(gv-define-setter org-element-contents-begin (value node) + `(org-element-put-property ,node :contents-begin ,value)) + +(defsubst org-element-contents-end (node) + "Get `:contents-end' property of NODE." + (org-element-property :contents-end node)) + +(gv-define-setter org-element-contents-end (value node) + `(org-element-put-property ,node :contents-end ,value)) + +(defsubst org-element-post-affiliated (node) + "Get `:post-affiliated' property of NODE." + (org-element-property :post-affiliated node)) + +(gv-define-setter org-element-post-affiliated (value node) + `(org-element-put-property ,node :post-affiliated ,value)) + +(defsubst org-element-post-blank (node) + "Get `:post-blank' property of NODE." + (org-element-property :post-blank node)) + +(gv-define-setter org-element-post-blank (value node) + `(org-element-put-property ,node :post-blank ,value)) (defconst org-element--cache-element-properties '(:cached - :org-element--cache-sync-key) + :org-element--cache-sync-key + :buffer) "List of element properties used internally by cache.") -(defun org-element-set-element (old new) - "Replace element or object OLD with element or object NEW. -The function takes care of setting `:parent' property for NEW." - ;; Ensure OLD and NEW have the same parent. - (org-element-put-property new :parent (org-element-property :parent old)) - (dolist (p org-element--cache-element-properties) - (when (org-element-property p old) - (org-element-put-property new p (org-element-property p old)))) - (if (or (memq (org-element-type old) '(plain-text nil)) - (memq (org-element-type new) '(plain-text nil))) - ;; We cannot replace OLD with NEW since one of them is not an - ;; object or element. We take the long path. - (progn (org-element-insert-before new old) - (org-element-extract-element old)) - ;; Since OLD is going to be changed into NEW by side-effect, first - ;; make sure that every element or object within NEW has OLD as - ;; parent. - (dolist (blob (org-element-contents new)) - (org-element-put-property blob :parent old)) - ;; Transfer contents. - (apply #'org-element-set-contents old (org-element-contents new)) - ;; Overwrite OLD's properties with NEW's. - (setcar (cdr old) (nth 1 new)) - ;; Transfer type. - (setcar old (car new)))) - -(defun org-element-create (type &optional props &rest children) - "Create a new element of type TYPE. -Optional argument PROPS, when non-nil, is a plist defining the -properties of the element. CHILDREN can be elements, objects or -strings." - (apply #'org-element-adopt-elements (list type props) children)) - -(defun org-element-copy (datum) - "Return a copy of DATUM. -DATUM is an element, object, string or nil. `:parent' property -is cleared and contents are removed in the process." - (when datum - (let ((type (org-element-type datum))) - (pcase type - (`org-data (list 'org-data nil)) - (`plain-text (substring-no-properties datum)) - (`nil (copy-sequence datum)) - (_ - (let ((element-copy (list type (plist-put (copy-sequence (nth 1 datum)) :parent nil)))) - ;; We cannot simply return the copies property list. When - ;; DATUM is i.e. a headline, it's property list (`:title' - ;; in case of headline) can contain parsed objects. The - ;; objects will contain `:parent' property set to the DATUM - ;; itself. When copied, these inner `:parent' property - ;; values will contain incorrect object decoupled from - ;; DATUM. Changes to the DATUM copy will not longer be - ;; reflected in the `:parent' properties. So, we need to - ;; reassign inner `:parent' properties to the DATUM copy - ;; explicitly. - (org-element-map element-copy (cons 'plain-text org-element-all-objects) - (lambda (obj) (when (equal datum (org-element-property :parent obj)) - (org-element-put-property obj :parent element-copy)))) - element-copy)))))) - +(defvar org-element--string-cache (make-hash-table :test #'equal) + "Hash table holding tag strings and todo keyword objects. +We use shared string storage to reduce memory footprint of the syntax +tree.") + +(defsubst org-element--get-cached-string (string) + "Return cached object equal to STRING. +Return nil if STRING is nil." + (when string + (or (gethash string org-element--string-cache) + (puthash string string org-element--string-cache)))) + +(defun org-element--substring (element beg-offset end-offset) + "Get substring inside ELEMENT according to BEG-OFFSET and END-OFFSET." + (with-current-buffer (org-element-property :buffer element) + (org-with-wide-buffer + (let ((beg (org-element-begin element))) + (buffer-substring-no-properties + (+ beg beg-offset) (+ beg end-offset)))))) + +(defun org-element--unescape-substring (element beg-offset end-offset) + "Call `org-element--substring' and unescape the result. +See `org-element--substring' for the meaning of ELEMENT, BEG-OFFSET, +and END-OFFSET." + (org-unescape-code-in-string + (org-element--substring element beg-offset end-offset))) ;;; Greater elements @@ -758,7 +882,26 @@ is cleared and contents are removed in the process." ;; greater element requires tweaking `org-element--current-element'. ;; Moreover, the newly defined type must be added to both ;; `org-element-all-elements' and `org-element-greater-elements'. - +;; +;; When adding or modifying the parser, please keep in mind the +;; following rules. They are important to keep parser performance +;; optimal. +;; +;; 1. When you can use `looking-at-p' or `string-match-p' instead of +;; `looking-at' or `string-match' and keep match data unmodified, +;; do it. +;; 2. When regexps can be grouped together, avoiding multiple regexp +;; match calls, they should be grouped. +;; 3. When `save-match-data' can be avoided, avoid it. +;; 4. When simpler regexps can be used for analysis, use the simpler +;; regexps. +;; 5. When regexps can be calculated in advance, not dynamically, they +;; should be calculated in advance. +;; 6 Note that it is not an obligation of a given function to preserve +;; match data - `save-match-data' is costly and must be arranged by +;; the caller if necessary. +;; +;; See https://debbugs.gnu.org/cgi/bugreport.cgi?bug=63225 ;;;; Center Block @@ -770,9 +913,9 @@ the buffer position at the beginning of the first affiliated keyword and CDR is a plist of affiliated keywords along with their value. -Return a list whose CAR is `center-block' and CDR is a plist -containing `:begin', `:end', `:contents-begin', `:contents-end', -`:post-blank' and `:post-affiliated' keywords. +Return a new syntax node of `center-block' type containing `:begin', +`:end', `:contents-begin', `:contents-end', `:post-blank' and +`:post-affiliated' properties. Assume point is at the beginning of the block." (let ((case-fold-search t)) @@ -794,15 +937,16 @@ Assume point is at the beginning of the block." (end (save-excursion (skip-chars-forward " \r\t\n" limit) (if (eobp) (point) (line-beginning-position))))) - (list 'center-block - (nconc - (list :begin begin - :end end - :contents-begin contents-begin - :contents-end contents-end - :post-blank (count-lines pos-before-blank end) - :post-affiliated post-affiliated) - (cdr affiliated)))))))) + (org-element-create + 'center-block + (nconc + (list :begin begin + :end end + :contents-begin contents-begin + :contents-end contents-end + :post-blank (count-lines pos-before-blank end) + :post-affiliated post-affiliated) + (cdr affiliated)))))))) (defun org-element-center-block-interpreter (_ contents) "Interpret a center-block element as Org syntax. @@ -820,9 +964,9 @@ the buffer position at the beginning of the first affiliated keyword and CDR is a plist of affiliated keywords along with their value. -Return a list whose CAR is `drawer' and CDR is a plist containing -`:drawer-name', `:begin', `:end', `:contents-begin', -`:contents-end', `:post-blank' and `:post-affiliated' keywords. +Return a new syntax node of `drawer' type containing `:drawer-name', +`:begin', `:end', `:contents-begin', `:contents-end', `:post-blank' +and `:post-affiliated' properties. Assume point is at beginning of drawer." (let ((case-fold-search t)) @@ -836,7 +980,7 @@ Assume point is at beginning of drawer." (name (progn (looking-at org-element-drawer-re) - (match-string-no-properties 1))) + (org-element--get-cached-string (match-string-no-properties 1)))) (begin (car affiliated)) (post-affiliated (point)) ;; Empty drawers have no contents. @@ -849,16 +993,17 @@ Assume point is at beginning of drawer." (point))) (end (progn (skip-chars-forward " \r\t\n" limit) (if (eobp) (point) (line-beginning-position))))) - (list 'drawer - (nconc - (list :begin begin - :end end - :drawer-name name - :contents-begin contents-begin - :contents-end contents-end - :post-blank (count-lines pos-before-blank end) - :post-affiliated post-affiliated) - (cdr affiliated)))))))) + (org-element-create + 'drawer + (nconc + (list :begin begin + :end end + :drawer-name name + :contents-begin contents-begin + :contents-end contents-end + :post-blank (count-lines pos-before-blank end) + :post-affiliated post-affiliated) + (cdr affiliated)))))))) (defun org-element-drawer-interpreter (drawer contents) "Interpret DRAWER element as Org syntax. @@ -878,10 +1023,9 @@ the buffer position at the beginning of the first affiliated keyword and CDR is a plist of affiliated keywords along with their value. -Return a list whose CAR is `dynamic-block' and CDR is a plist -containing `:block-name', `:begin', `:end', `:contents-begin', -`:contents-end', `:arguments', `:post-blank' and -`:post-affiliated' keywords. +Return a new syntax node of `dynamic-block' type containing +`:block-name', `:begin', `:end', `:contents-begin', `:contents-end', +`:arguments', `:post-blank' and `:post-affiliated' properties. Assume point is at beginning of dynamic block." (let ((case-fold-search t)) @@ -893,7 +1037,7 @@ Assume point is at beginning of dynamic block." (save-excursion (let* ((name (progn (looking-at org-element-dynamic-block-open-re) - (match-string-no-properties 1))) + (org-element--get-cached-string (match-string-no-properties 1)))) (arguments (match-string-no-properties 2)) (begin (car affiliated)) (post-affiliated (point)) @@ -907,17 +1051,18 @@ Assume point is at beginning of dynamic block." (point))) (end (progn (skip-chars-forward " \r\t\n" limit) (if (eobp) (point) (line-beginning-position))))) - (list 'dynamic-block - (nconc - (list :begin begin - :end end - :block-name name - :arguments arguments - :contents-begin contents-begin - :contents-end contents-end - :post-blank (count-lines pos-before-blank end) - :post-affiliated post-affiliated) - (cdr affiliated))))))))) + (org-element-create + 'dynamic-block + (nconc + (list :begin begin + :end end + :block-name name + :arguments arguments + :contents-begin contents-begin + :contents-end contents-end + :post-blank (count-lines pos-before-blank end) + :post-affiliated post-affiliated) + (cdr affiliated))))))))) (defun org-element-dynamic-block-interpreter (dynamic-block contents) "Interpret DYNAMIC-BLOCK element as Org syntax. @@ -945,15 +1090,15 @@ the buffer position at the beginning of the first affiliated keyword and CDR is a plist of affiliated keywords along with their value. -Return a list whose CAR is `footnote-definition' and CDR is -a plist containing `:label', `:begin' `:end', `:contents-begin', -`:contents-end', `:pre-blank',`:post-blank' and -`:post-affiliated' keywords. +Return a new syntax node of `footnote-definition' type containing +`:label', `:begin' `:end', `:contents-begin', `:contents-end', +`:pre-blank',`:post-blank' and `:post-affiliated' properties. Assume point is at the beginning of the footnote definition." (save-excursion (let* ((label (progn (looking-at org-footnote-definition-re) - (match-string-no-properties 1))) + (org-element--get-cached-string + (match-string-no-properties 1)))) (begin (car affiliated)) (post-affiliated (point)) (end @@ -988,17 +1133,18 @@ Assume point is at the beginning of the footnote definition." (progn (goto-char end) (skip-chars-backward " \r\t\n") (line-beginning-position 2)))) - (list 'footnote-definition - (nconc - (list :label label - :begin begin - :end end - :contents-begin contents-begin - :contents-end (and contents-begin contents-end) - :pre-blank pre-blank - :post-blank (count-lines contents-end end) - :post-affiliated post-affiliated) - (cdr affiliated)))))) + (org-element-create + 'footnote-definition + (nconc + (list :label label + :begin begin + :end end + :contents-begin contents-begin + :contents-end (and contents-begin contents-end) + :pre-blank pre-blank + :post-blank (count-lines contents-end end) + :post-affiliated post-affiliated) + (cdr affiliated)))))) (defun org-element-footnote-definition-interpreter (footnote-definition contents) "Interpret FOOTNOTE-DEFINITION element as Org syntax. @@ -1018,8 +1164,9 @@ CONTENTS is the contents of the footnote-definition." ;;;; Headline -(defun org-element--get-node-properties (&optional at-point-p?) +(defun org-element--get-node-properties (&optional at-point-p? parent) "Return node properties for headline or property drawer at point. +The property values a deferred relative to PARENT element. Upcase property names. It avoids confusion between properties obtained through property drawer and default properties from the parser (e.g. `:end' and :END:). Return value is a plist. @@ -1027,37 +1174,53 @@ parser (e.g. `:end' and :END:). Return value is a plist. When AT-POINT-P? is nil, assume that point as at a headline. Otherwise parse properties for property drawer at point." (save-excursion - (unless at-point-p? - (forward-line) - (when (looking-at-p org-element-planning-line-re) (forward-line))) - (when (looking-at org-property-drawer-re) - (forward-line) - (let ((end (match-end 0)) properties) - (while (< (line-end-position) end) - (looking-at org-property-re) - (let* ((property-name (concat ":" (upcase (match-string 2)))) - (property-name-symbol (intern property-name)) - (property-value (match-string-no-properties 3))) - (cond - ((and (plist-member properties property-name-symbol) - (string-match-p "\\+$" property-name)) - (let ((val (plist-get properties property-name-symbol))) - (if (listp val) - (setq properties - (plist-put properties - property-name-symbol - (append (plist-get properties property-name-symbol) - (list property-value)))) - (plist-put properties property-name-symbol (list val property-value))))) - (t (setq properties (plist-put properties property-name-symbol property-value))))) - (forward-line)) - properties)))) + (let ((begin (or (org-element-begin parent) (point)))) + (unless at-point-p? + (forward-line) + (when (looking-at-p org-element-planning-line-re) (forward-line))) + (when (looking-at org-property-drawer-re) + (forward-line) + (let ((end (match-end 0)) properties) + (while (< (line-end-position) end) + (looking-at org-property-re) + (let* ((property-name (concat ":" (upcase (match-string 2)))) + (property-name-symbol (intern property-name)) + (property-value + (org-element-deferred-create + t #'org-element--substring + (- (match-beginning 3) begin) + (- (match-end 3) begin)))) + (cond + ((and (plist-member properties property-name-symbol) + (string-match-p "\\+$" property-name)) + (let ((val (plist-get properties property-name-symbol))) + (if (listp val) + (setq properties + (plist-put properties + property-name-symbol + (append (plist-get properties property-name-symbol) + (list property-value)))) + (plist-put properties property-name-symbol (list val property-value))))) + (t (setq properties (plist-put properties property-name-symbol property-value))))) + (forward-line)) + ;; Convert list of deferred properties into a single + ;; deferred property. + (let ((plist properties) val) + (while plist + (setq val (cadr plist)) + (when (and (car-safe val) + (org-element-deferred-p (car val))) + (setcar + (cdr plist) + (org-element-deferred-create-list (cadr plist)))) + (setq plist (cddr plist)))) + properties))))) (defun org-element--get-time-properties () "Return time properties associated to headline at point. Return value is a plist." (save-excursion - (when (progn (forward-line) (looking-at org-element-planning-line-re)) + (when (progn (forward-line) (looking-at-p org-element-planning-line-re)) (let ((end (line-end-position)) plist) (while (re-search-forward org-element-planning-keywords-re end t) @@ -1071,16 +1234,179 @@ Return value is a plist." (t (setq plist (plist-put plist :closed time)))))) plist)))) +(defun org-element--headline-deferred (element) + "Parse and set extra properties for ELEMENT headline in BUFFER." + (with-current-buffer (org-element-property :buffer element) + (org-with-wide-buffer + ;; Update robust boundaries to not + ;; include property drawer and planning. + ;; Changes there can now invalidate the + ;; properties. + (org-element-put-property + element :robust-begin + (let ((contents-begin (org-element-contents-begin element)) + (contents-end (org-element-contents-end element))) + (when contents-begin + (progn (goto-char contents-begin) + (when (looking-at-p org-element-planning-line-re) + (forward-line)) + (when (looking-at org-property-drawer-re) + (goto-char (match-end 0))) + ;; If there is :pre-blank, we + ;; need to be careful about + ;; robust beginning. + (max (if (< (+ 2 contents-begin) contents-end) + (+ 2 contents-begin) + 0) + (point)))))) + (org-element-put-property + element :robust-end + (let ((contents-end (org-element-contents-end element)) + (robust-begin (org-element-property :robust-begin element))) + (when contents-end + (when (> (- contents-end 2) robust-begin) + (- contents-end 2))))) + (unless (org-element-property :robust-end element) + (org-element-put-property element :robust-begin nil)) + (goto-char (org-element-begin element)) + (setcar (cdr element) + (nconc + (nth 1 element) + (org-element--get-time-properties))) + (goto-char (org-element-begin element)) + (setcar (cdr element) + (nconc + (nth 1 element) + (org-element--get-node-properties nil element))))) + ;; Return nil. + nil) + +(defun org-element--headline-raw-value (headline beg-offset end-offset) + "Retrieve :raw-value in HEADLINE according to BEG-OFFSET and END-OFFSET." + (org-trim (org-element--substring headline beg-offset end-offset))) + +(defun org-element--headline-archivedp (headline) + "Return t when HEADLINE is archived and nil otherwise." + (if (member org-element-archive-tag + (org-element-property :tags headline)) + t nil)) + +(defun org-element--headline-footnote-section-p (headline) + "Return t when HEADLINE is a footnote section and nil otherwise." + (and org-footnote-section + (string= org-footnote-section + (org-element-property :raw-value headline)))) + +(defconst org-element--headline-comment-re + (concat org-element-comment-string "\\(?: \\|$\\)") + "Regexp matching comment string in a headline.") + +(defconst org-element--headline-archivedp + (org-element-deferred-create + nil #'org-element--headline-archivedp) + "Constant holding deferred value for headline `:archivedp' property.") + +(defconst org-element--headline-footnote-section-p + (org-element-deferred-create + nil #'org-element--headline-footnote-section-p) + "Constant holding deferred value for headline `:footnote-section-p' property.") + +(defconst org-element--headline-raw-value + (org-element-deferred-create-alias :raw-value) + "Constant holding deferred value for headline `:raw-value' property.") + +(defun org-element--headline-parse-title (headline raw-secondary-p) + "Resolve title properties of HEADLINE for side effect. +When RAW-SECONDARY-P is non-nil, headline's title will not be +parsed as a secondary string, but as a plain string instead. + +Throw `:org-element-deferred-retry' signal at the end." + (with-current-buffer (org-element-property :buffer headline) + (org-with-point-at (org-element-begin headline) + (let* ((begin (point)) + (true-level (prog1 (skip-chars-forward "*") + (skip-chars-forward " \t"))) + (level (org-reduced-level true-level)) + (todo (and org-todo-regexp + (let (case-fold-search) (looking-at (concat org-todo-regexp "\\(?: \\|$\\)"))) + (progn (goto-char (match-end 0)) + (skip-chars-forward " \t") + (org-element--get-cached-string (match-string-no-properties 1))))) + (todo-type + (and todo (if (member todo org-done-keywords) 'done 'todo))) + (priority (and (looking-at "\\[#.\\][ \t]*") + (progn (goto-char (match-end 0)) + (aref (match-string 0) 2)))) + (commentedp + (and (let ((case-fold-search nil)) + (looking-at org-element--headline-comment-re)) + (prog1 t + (goto-char (match-end 0)) + (skip-chars-forward " \t")))) + (title-start (point)) + (tags (when (re-search-forward + "\\(:[[:alnum:]_@#%:]+:\\)[ \t]*$" + (line-end-position) + 'move) + (goto-char (match-beginning 0)) + (mapcar #'org-element--get-cached-string + (org-split-string (match-string-no-properties 1) ":")))) + (title-end (point)) + (raw-value + (org-element-deferred-create + t #'org-element--headline-raw-value + (- title-start begin) (- title-end begin)))) + (org-element-put-property headline :raw-value raw-value) + (org-element-put-property headline :level level) + (org-element-put-property headline :priority priority) + (org-element-put-property headline :tags tags) + (org-element-put-property headline :todo-keyword todo) + (org-element-put-property headline :todo-type todo-type) + (org-element-put-property + headline :footnote-section-p org-element--headline-footnote-section-p) + (org-element-put-property headline :archivedp org-element--headline-archivedp) + (org-element-put-property headline :commentedp commentedp) + (org-element-put-property + headline :title + (if raw-secondary-p + org-element--headline-raw-value + (org-element--parse-objects + (progn (goto-char title-start) + (skip-chars-forward " \t") + (point)) + (progn (goto-char title-end) + (skip-chars-backward " \t") + (point)) + nil + (org-element-restriction + (org-element-type headline)) + headline)))))) + (throw :org-element-deferred-retry nil)) + +(defconst org-element--headline-parse-title-raw + (org-element-deferred-create + t #'org-element--headline-parse-title t) + "Constant holding deferred value for raw headline `:title' property.") + +(defconst org-element--headline-parse-title-parse + (org-element-deferred-create + t #'org-element--headline-parse-title nil) + "Constant holding deferred value for parsed headline `:title' property.") + +(defconst org-element--headline-deferred + (org-element-deferred-create + t #'org-element--headline-deferred) + "Constant holding deferred value for headline `:deferred' property.") + (defun org-element-headline-parser (&optional _ raw-secondary-p) "Parse a headline. -Return a list whose CAR is `headline' and CDR is a plist -containing `:raw-value', `:title', `:begin', `:end', -`:pre-blank', `:contents-begin' and `:contents-end', `:level', -`:priority', `:tags', `:todo-keyword', `:todo-type', `:scheduled', -`:deadline', `:closed', `:archivedp', `:commentedp' -`:footnote-section-p', `:post-blank' and `:post-affiliated' -keywords. +Return a new syntax node of `headline' type containing `:raw-value', +`:title', `:begin', `:end', `:pre-blank', `:contents-begin' and +`:contents-end', `:level', `:priority', `:tags', `:todo-keyword', +`:todo-type', `:scheduled', `:deadline', `:closed', `:archivedp', +`:commentedp' `:footnote-section-p', `:post-blank' and +`:post-affiliated' properties. The plist also contains any property set in the property drawer, with its name in upper cases and colons added at the @@ -1091,117 +1417,65 @@ parsed as a secondary string, but as a plain string instead. Assume point is at beginning of the headline." (save-excursion - (let* ((begin (point)) - (true-level (prog1 (skip-chars-forward "*") - (skip-chars-forward " \t"))) - (level (org-reduced-level true-level)) - (todo (and org-todo-regexp - (let (case-fold-search) (looking-at (concat org-todo-regexp " "))) - (progn (goto-char (match-end 0)) - (skip-chars-forward " \t") - (match-string 1)))) - (todo-type - (and todo (if (member todo org-done-keywords) 'done 'todo))) - (priority (and (looking-at "\\[#.\\][ \t]*") - (progn (goto-char (match-end 0)) - (aref (match-string 0) 2)))) - (commentedp - (and (let ((case-fold-search nil)) - (looking-at org-element-comment-string)) - (goto-char (match-end 0)) - (when (looking-at-p "\\(?:[ \t]\\|$\\)") - (point)))) - (title-start (prog1 (point) - (unless (or todo priority commentedp) - ;; Headline like "* :tag:" - (skip-chars-backward " \t")))) - (tags (when (re-search-forward - "[ \t]+\\(:[[:alnum:]_@#%:]+:\\)[ \t]*$" - (line-end-position) - 'move) - (goto-char (match-beginning 0)) - (org-split-string (match-string 1) ":"))) - (title-end (point)) - (raw-value (org-trim - (buffer-substring-no-properties title-start title-end))) - (archivedp (member org-element-archive-tag tags)) - (footnote-section-p (and org-footnote-section - (string= org-footnote-section raw-value))) - (standard-props (org-element--get-node-properties)) - (time-props (org-element--get-time-properties)) - (end + (let* ((deferred-title-prop + (if raw-secondary-p + org-element--headline-parse-title-raw + org-element--headline-parse-title-parse)) + (begin (point)) + (true-level (skip-chars-forward "*")) + (end (save-excursion - (let ((re (rx-to-string - `(seq line-start (** 1 ,true-level "*") " ")))) - (if (re-search-forward re nil t) - (line-beginning-position) - (point-max))))) + (if (re-search-forward (org-headline-re true-level) nil t) + (line-beginning-position) + (point-max)))) (contents-begin (save-excursion (forward-line) (skip-chars-forward " \r\t\n" end) (and (/= (point) end) (line-beginning-position)))) - (contents-end (and contents-begin - (progn (goto-char end) - (skip-chars-backward " \r\t\n") - (line-beginning-position 2)))) - (robust-begin (and contents-begin - (progn (goto-char contents-begin) - (when (looking-at-p org-element-planning-line-re) - (forward-line)) - (when (looking-at org-property-drawer-re) - (goto-char (match-end 0))) - ;; If there is :pre-blank, we - ;; need to be careful about - ;; robust beginning. - (max (if (< (+ 2 contents-begin) contents-end) - (+ 2 contents-begin) - 0) - (point))))) - (robust-end (and robust-begin - (when (> (- contents-end 2) robust-begin) - (- contents-end 2))))) - (unless robust-end (setq robust-begin nil)) - (let ((headline - (list 'headline - (nconc - (list :raw-value raw-value - :begin begin - :end end - :pre-blank - (if (not contents-begin) 0 - (1- (count-lines begin contents-begin))) - :contents-begin contents-begin - :contents-end contents-end - :robust-begin robust-begin - :robust-end robust-end - :level level - :priority priority - :tags tags - :todo-keyword todo - :todo-type todo-type - :post-blank - (if contents-end - (count-lines contents-end end) - (1- (count-lines begin end))) - :footnote-section-p footnote-section-p - :archivedp archivedp - :commentedp commentedp - :post-affiliated begin) - time-props - standard-props)))) - (org-element-put-property - headline :title - (if raw-secondary-p raw-value - (org-element--parse-objects - (progn (goto-char title-start) - (skip-chars-forward " \t") - (point)) - (progn (goto-char title-end) - (skip-chars-backward " \t") - (point)) - nil - (org-element-restriction 'headline) - headline))))))) + (contents-end (and contents-begin end)) + (robust-begin + ;; If there is :pre-blank, we + ;; need to be careful about + ;; robust beginning. + (when contents-begin + (when (< (+ 2 contents-begin) contents-end) + (+ 2 contents-begin)))) + (robust-end (and robust-begin end))) + (org-element-create + 'headline + (list + :begin begin + :end end + :pre-blank + (if (not contents-begin) 0 + (1- (count-lines begin contents-begin))) + :contents-begin contents-begin + :contents-end contents-end + :robust-begin robust-begin + :robust-end robust-end + :true-level true-level + :buffer (current-buffer) + :raw-value deferred-title-prop + :title deferred-title-prop + :level deferred-title-prop + :priority deferred-title-prop + :tags deferred-title-prop + :todo-keyword deferred-title-prop + :todo-type deferred-title-prop + :post-blank + (if contents-end + ;; Trailing blank lines in org-data, headlines, and + ;; sections belong to the containing elements. + 0 + (1- (count-lines begin end))) + :footnote-section-p deferred-title-prop + :archivedp deferred-title-prop + :commentedp deferred-title-prop + :post-affiliated begin + :secondary (alist-get + 'headline + org-element-secondary-value-alist) + :deferred org-element--headline-deferred))))) (defun org-element-headline-interpreter (headline contents) "Interpret HEADLINE element as Org syntax. @@ -1248,82 +1522,104 @@ CONTENTS is the contents of the element." ;;;; org-data -(defun org-element--get-global-node-properties () - "Return node properties associated with the whole Org buffer. +(defun org-element--get-category () + "Return category in current buffer." + (let ((default-category + (cond ((null org-category) + (when (org-with-base-buffer nil + buffer-file-name) + (file-name-sans-extension + (file-name-nondirectory + (org-with-base-buffer nil + buffer-file-name))))) + ((symbolp org-category) (symbol-name org-category)) + (t org-category))) + category) + ;; Search for #+CATEGORY keywords. + (org-with-point-at (point-max) + (while (and (not category) + (re-search-backward "^[ \t]*#\\+CATEGORY:" (point-min) t)) + (let ((element (org-element-at-point-no-context))) + (when (org-element-type-p element 'keyword) + (setq category (org-element-property :value element)))))) + ;; Return. + (or category default-category))) + +(defun org-element--get-global-node-properties (data) + "Set node properties associated with the whole Org buffer. Upcase property names. It avoids confusion between properties obtained through property drawer and default properties from the -parser (e.g. `:end' and :END:). Return value is a plist." - (org-with-wide-buffer - (goto-char (point-min)) - (while (and (org-at-comment-p) (bolp)) (forward-line)) - (org-element--get-node-properties t))) - +parser (e.g. `:end' and :END:). + +Alter DATA by side effect." + (with-current-buffer (org-element-property :buffer data) + (org-with-wide-buffer + (goto-char (point-min)) + (org-skip-whitespace) + (forward-line 0) + (while (and (org-at-comment-p) (bolp)) (forward-line)) + (let ((props (org-element--get-node-properties t data)) + (has-category? nil)) + (while props + (org-element-put-property data (car props) (cadr props)) + (when (eq (car props) :CATEGORY) (setq has-category? t)) + (setq props (cddr props))) + ;; CATEGORY not set in top-level property drawer. Go the long way. + (unless has-category? + (org-element-put-property data :CATEGORY (org-element--get-category))))) + ;; Return nil. + nil)) + +(defconst org-element--get-global-node-properties + (org-element-deferred-create + t #'org-element--get-global-node-properties) + "Constant holding `:deferred' property for org-data.") (defvar org-element-org-data-parser--recurse nil) (defun org-element-org-data-parser (&optional _) - "Parse org-data." + "Parse org-data. + +Return a new syntax node of `org-data' type containing `:begin', +`:contents-begin', `:contents-end', `:end', `:post-blank', +`:post-affiliated', and `:path' properties." (org-with-wide-buffer (let* ((begin 1) (contents-begin (progn (goto-char 1) (org-skip-whitespace) - (beginning-of-line) + (forward-line 0) (point))) (end (point-max)) - (pos-before-blank (progn (goto-char (point-max)) - (skip-chars-backward " \r\t\n") - (line-beginning-position 2))) - (robust-end (when (> (- pos-before-blank 2) contents-begin) - (- pos-before-blank 2))) + (contents-end end) + (robust-end contents-end) (robust-begin (when (and robust-end - (< (+ 2 contents-begin) pos-before-blank)) + (< (+ 2 contents-begin) end)) (or (org-with-wide-buffer (goto-char (point-min)) + (org-skip-whitespace) + (forward-line 0) (while (and (org-at-comment-p) (bolp)) (forward-line)) (when (looking-at org-property-drawer-re) (goto-char (match-end 0)) - (skip-chars-backward " \t") (min robust-end (point)))) - (+ 2 contents-begin)))) - (category (cond ((null org-category) - (when (org-with-base-buffer nil - buffer-file-name) - (file-name-sans-extension - (file-name-nondirectory - (org-with-base-buffer nil - buffer-file-name))))) - ((symbolp org-category) (symbol-name org-category)) - (t org-category))) - (category (catch 'buffer-category - (unless org-element-org-data-parser--recurse - (org-with-point-at end - ;; Avoid recursive calls from - ;; `org-element-at-point-no-context'. - (let ((org-element-org-data-parser--recurse t)) - (while (re-search-backward "^[ \t]*#\\+CATEGORY:" (point-min) t) - (org-element-with-disabled-cache - (let ((element (org-element-at-point-no-context))) - (when (eq (org-element-type element) 'keyword) - (throw 'buffer-category - (org-element-property :value element))))))))) - category)) - (properties (org-element--get-global-node-properties))) - (unless (plist-get properties :CATEGORY) - (setq properties (plist-put properties :CATEGORY category))) - (list 'org-data - (nconc - (list :begin begin - :contents-begin contents-begin - :contents-end pos-before-blank - :end end - :robust-begin robust-begin - :robust-end robust-end - :post-blank (count-lines pos-before-blank end) - :post-affiliated begin - :path (buffer-file-name) - :mode 'org-data) - properties))))) + (+ 2 contents-begin))))) + (org-element-create + 'org-data + (list :begin begin + :contents-begin contents-begin + :contents-end contents-end + :end end + :robust-begin robust-begin + :robust-end robust-end + ;; Trailing blank lines in org-data, headlines, and + ;; sections belong to the containing elements. + :post-blank 0 + :post-affiliated begin + :path (buffer-file-name) + :mode 'org-data + :buffer (current-buffer) + :deferred org-element--get-global-node-properties))))) (defun org-element-org-data-interpreter (_ contents) "Interpret ORG-DATA element as Org syntax. @@ -1335,12 +1631,13 @@ CONTENTS is the contents of the element." (defun org-element-inlinetask-parser (limit &optional raw-secondary-p) "Parse an inline task. -Return a list whose CAR is `inlinetask' and CDR is a plist -containing `:title', `:begin', `:end', `:pre-blank', -`:contents-begin' and `:contents-end', `:level', `:priority', -`:raw-value', `:tags', `:todo-keyword', `:todo-type', -`:scheduled', `:deadline', `:closed', `:post-blank' and -`:post-affiliated' keywords. +Do not search past LIMIT. + +Return a new syntax node of `inlinetask' type containing `:title', +`:begin', `:end', `:pre-blank', `:contents-begin' and `:contents-end', +`:level', `:priority', `:raw-value', `:tags', `:todo-keyword', +`:todo-type', `:scheduled', `:deadline', `:closed', `:post-blank' and +`:post-affiliated' properties. The plist also contains any property set in the property drawer, with its name in upper cases and colons added at the @@ -1352,46 +1649,16 @@ string instead. Assume point is at beginning of the inline task." (save-excursion - (let* ((begin (point)) - (level (prog1 (org-reduced-level (skip-chars-forward "*")) - (skip-chars-forward " \t"))) - (todo (and org-todo-regexp - (let (case-fold-search) (looking-at org-todo-regexp)) - (progn (goto-char (match-end 0)) - (skip-chars-forward " \t") - (match-string 0)))) - (todo-type (and todo - (if (member todo org-done-keywords) 'done 'todo))) - (priority (and (looking-at "\\[#.\\][ \t]*") - (progn (goto-char (match-end 0)) - (aref (match-string 0) 2)))) - (commentedp - (and (let ((case-fold-search nil)) - (looking-at org-element-comment-string)) - (goto-char (match-end 0)) - (when (looking-at-p "\\(?:[ \t]\\|$\\)") - (point)))) - (title-start (prog1 (point) - (unless (or todo priority commentedp) - ;; Headline like "* :tag:" - (skip-chars-backward " \t")))) - (tags (when (re-search-forward - "[ \t]+\\(:[[:alnum:]_@#%:]+:\\)[ \t]*$" - (line-end-position) - 'move) - (goto-char (match-beginning 0)) - (org-split-string (match-string 1) ":"))) - (title-end (point)) - (raw-value (org-trim - (buffer-substring-no-properties title-start title-end))) - (archivedp (member org-element-archive-tag tags)) + (let* ((deferred-title-prop + (if raw-secondary-p + org-element--headline-parse-title-raw + org-element--headline-parse-title-parse)) + (begin (point)) (task-end (save-excursion - (end-of-line) + (forward-line 1) (and (re-search-forward org-element-headline-re limit t) (looking-at-p "[ \t]*END[ \t]*$") (line-beginning-position)))) - (standard-props (and task-end (org-element--get-node-properties))) - (time-props (and task-end (org-element--get-time-properties))) (contents-begin (and task-end (< (point) task-end) (progn @@ -1402,42 +1669,34 @@ Assume point is at beginning of the inline task." (end (progn (when task-end (goto-char task-end)) (forward-line) (skip-chars-forward " \r\t\n" limit) - (if (eobp) (point) (line-beginning-position)))) - (inlinetask - (list 'inlinetask - (nconc - (list :raw-value raw-value - :begin begin - :end end - :pre-blank - (if (not contents-begin) 0 - (1- (count-lines begin contents-begin))) - :contents-begin contents-begin - :contents-end contents-end - :level level - :priority priority - :tags tags - :todo-keyword todo - :todo-type todo-type - :post-blank (1- (count-lines (or task-end begin) end)) - :post-affiliated begin - :archivedp archivedp - :commentedp commentedp) - time-props - standard-props)))) - (org-element-put-property - inlinetask :title - (if raw-secondary-p raw-value - (org-element--parse-objects - (progn (goto-char title-start) - (skip-chars-forward " \t") - (point)) - (progn (goto-char title-end) - (skip-chars-backward " \t") - (point)) - nil - (org-element-restriction 'inlinetask) - inlinetask)))))) + (if (eobp) (point) (line-beginning-position))))) + (org-element-create + 'inlinetask + (list + :begin begin + :end end + :pre-blank + (if (not contents-begin) 0 + (1- (count-lines begin contents-begin))) + :contents-begin contents-begin + :contents-end contents-end + :buffer (current-buffer) + :raw-value deferred-title-prop + :title deferred-title-prop + :level deferred-title-prop + :priority deferred-title-prop + :tags deferred-title-prop + :todo-keyword deferred-title-prop + :todo-type deferred-title-prop + :archivedp deferred-title-prop + :commentedp deferred-title-prop + :post-blank (1- (count-lines (or task-end begin) end)) + :post-affiliated begin + :secondary (alist-get + 'inlinetask + org-element-secondary-value-alist) + :deferred + (and task-end org-element--headline-deferred)))))) (defun org-element-inlinetask-interpreter (inlinetask contents) "Interpret INLINETASK element as Org syntax. @@ -1479,15 +1738,15 @@ CONTENTS is the contents of inlinetask." ;;;; Item -(defun org-element-item-parser (_ struct &optional raw-secondary-p) - "Parse an item. +(defun org-element-item-parser (limit struct &optional raw-secondary-p) + "Parse an item up to LIMIT. STRUCT is the structure of the plain list. -Return a list whose CAR is `item' and CDR is a plist containing -`:bullet', `:begin', `:end', `:contents-begin', `:contents-end', -`:checkbox', `:counter', `:tag', `:structure', `:pre-blank', -`:post-blank' and `:post-affiliated' keywords. +Return a new syntax node of `item' type containing `:bullet', +`:begin', `:end', `:contents-begin', `:contents-end', `:checkbox', +`:counter', `:tag', `:structure', `:pre-blank', `:post-blank' and +`:post-affiliated' properties. When optional argument RAW-SECONDARY-P is non-nil, item's tag, if any, will not be parsed as a secondary string, but as a plain @@ -1495,25 +1754,19 @@ string instead. Assume point is at the beginning of the item." (save-excursion - (beginning-of-line) + (forward-line 0) (looking-at org-list-full-item-re) (let* ((begin (point)) - (bullet (match-string-no-properties 1)) + (bullet (org-element--get-cached-string (match-string-no-properties 1))) + (tag-begin (match-beginning 4)) + (tag-end (match-end 4)) (checkbox (let ((box (match-string 3))) (cond ((equal "[ ]" box) 'off) ((equal "[X]" box) 'on) ((equal "[-]" box) 'trans)))) - (counter (let ((c (match-string 2))) - (save-match-data - (cond - ((not c) nil) - ((string-match "[A-Za-z]" c) - (- (string-to-char (upcase (match-string 0 c))) - 64)) - ((string-match "[0-9]+" c) - (string-to-number (match-string 0 c))))))) (end (progn (goto-char (nth 6 (assq (point) struct))) - (if (bolp) (point) (line-beginning-position 2)))) + (min limit + (if (bolp) (point) (line-beginning-position 2))))) (pre-blank 0) (contents-begin (progn @@ -1521,7 +1774,7 @@ Assume point is at the beginning of the item." ;; Ignore tags in un-ordered lists: they are just ;; a part of item's body. (if (and (match-beginning 4) - (save-match-data (string-match "[.)]" bullet))) + (string-match-p "[.)]" bullet)) (match-beginning 4) (match-end 0))) (skip-chars-forward " \r\t\n" end) @@ -1537,26 +1790,38 @@ Assume point is at the beginning of the item." (progn (goto-char end) (skip-chars-backward " \r\t\n") (line-beginning-position 2)))) + (counter (let ((c (match-string 2))) + (cond + ((not c) nil) + ((string-match "[A-Za-z]" c) + (- (string-to-char (upcase (match-string-no-properties 0 c))) + 64)) + ((string-match "[0-9]+" c) + (string-to-number (match-string-no-properties 0 c)))))) (item - (list 'item - (list :bullet bullet - :begin begin - :end end - :contents-begin contents-begin - :contents-end contents-end - :checkbox checkbox - :counter counter - :structure struct - :pre-blank pre-blank - :post-blank (count-lines (or contents-end begin) end) - :post-affiliated begin)))) + (org-element-create + 'item + (list :bullet bullet + :begin begin + :end end + :contents-begin contents-begin + :contents-end contents-end + :checkbox checkbox + :counter counter + :structure struct + :pre-blank pre-blank + :post-blank (count-lines (or contents-end begin) end) + :post-affiliated begin + :secondary (alist-get + 'item + org-element-secondary-value-alist))))) (org-element-put-property item :tag (let ((raw (org-list-get-tag begin struct))) (when raw (if raw-secondary-p raw (org-element--parse-objects - (match-beginning 4) (match-end 4) nil + tag-begin tag-end nil (org-element-restriction 'item) item)))))))) @@ -1605,8 +1870,10 @@ CONTENTS is the contents of the element." ;;;; Plain List (defun org-element--list-struct (limit) - ;; Return structure of list at point. Internal function. See - ;; `org-list-struct' for details. +"Return structure of list at point. +Do not parse past LIMIT. + +Internal function. See `org-list-struct' for details." (let ((case-fold-search t) (top-ind limit) (item-re (org-item-re)) @@ -1628,11 +1895,11 @@ CONTENTS is the contents of the element." (dolist (item items) (setcar (nthcdr 6 item) end))) (throw :exit (sort (nconc items struct) #'car-less-than-car))) ;; At list end: end all items. - ((looking-at org-list-end-re) + ((looking-at-p org-list-end-re) (dolist (item items) (setcar (nthcdr 6 item) (point))) (throw :exit (sort (nconc items struct) #'car-less-than-car))) ;; At a new item: end previous sibling. - ((looking-at item-re) + ((looking-at-p item-re) (let ((ind (save-excursion (skip-chars-forward " \t") (org-current-text-column)))) (setq top-ind (min top-ind ind)) @@ -1648,17 +1915,17 @@ CONTENTS is the contents of the element." (match-string-no-properties 2) ; counter (match-string-no-properties 3) ; checkbox ;; Description tag. - (and (save-match-data - (string-match "[-+*]" bullet)) - (match-string-no-properties 4)) + (and + (string-match-p "[-+*]" bullet) + (match-string-no-properties 4)) ;; Ending position, unknown so far. nil))) items)) (forward-line)) ;; Skip empty lines. - ((looking-at "^[ \t]*$") (forward-line)) + ((looking-at-p "^[ \t]*$") (forward-line)) ;; Skip inline tasks and blank lines along the way. - ((and inlinetask-re (looking-at inlinetask-re)) + ((and inlinetask-re (looking-at-p inlinetask-re)) (forward-line) (let ((origin (point))) (when (re-search-forward inlinetask-re limit t) @@ -1684,7 +1951,7 @@ CONTENTS is the contents of the element." (re-search-forward (format "^[ \t]*#\\+END%s[ \t]*$" (match-string 1)) limit t))) - ((and (looking-at org-element-drawer-re) + ((and (looking-at-p org-element-drawer-re) (re-search-forward "^[ \t]*:END:[ \t]*$" limit t)))) (forward-line)))))))) @@ -1697,10 +1964,9 @@ keyword and CDR is a plist of affiliated keywords along with their value. STRUCTURE is the structure of the plain list being parsed. -Return a list whose CAR is `plain-list' and CDR is a plist -containing `:type', `:begin', `:end', `:contents-begin' and -`:contents-end', `:structure', `:post-blank' and -`:post-affiliated' keywords. +Return a new syntax node of `plain-list' type containing `:type', +`:begin', `:end', `:contents-begin' and `:contents-end', `:structure', +`:post-blank' and `:post-affiliated' properties. Assume point is at the beginning of the list." (save-excursion @@ -1717,30 +1983,43 @@ Assume point is at the beginning of the list." (= (nth 1 item) ind)) (setq pos (nth 6 item))) pos)) + (contents-end (progn (goto-char contents-end) + (skip-chars-backward " \r\t\n") + (if (bolp) (point) (line-beginning-position 2)))) (end (progn (goto-char contents-end) (skip-chars-forward " \r\t\n" limit) (if (= (point) limit) limit (line-beginning-position))))) ;; Return value. - (list 'plain-list - (nconc - (list :type type - :begin begin - :end end - :contents-begin contents-begin - :contents-end contents-end - :structure struct - :post-blank (count-lines contents-end end) - :post-affiliated contents-begin) - (cdr affiliated)))))) + (org-element-create + 'plain-list + (nconc + (list :type type + :begin begin + :end end + :contents-begin contents-begin + :contents-end contents-end + :structure struct + :post-blank (count-lines contents-end end) + :post-affiliated contents-begin) + (cdr affiliated)))))) (defun org-element-plain-list-interpreter (_ contents) "Interpret plain-list element as Org syntax. CONTENTS is the contents of the element." - (with-temp-buffer - (insert contents) - (goto-char (point-min)) - (org-list-repair) - (buffer-string))) + (org-element-with-buffer-copy + :to-buffer (org-get-buffer-create " *Org parse*" t) + :drop-contents t + :drop-visibility t + :drop-narrowing t + :drop-locals nil + ;; Transferring local variables may put the temporary buffer + ;; into a read-only state. Make sure we can insert CONTENTS. + (let ((inhibit-read-only t)) (erase-buffer) (insert contents)) + (goto-char (point-min)) + (org-list-repair) + ;; Prevent "Buffer *temp* modified; kill anyway?". + (restore-buffer-modified-p nil) + (buffer-string))) ;;;; Property Drawer @@ -1750,9 +2029,9 @@ CONTENTS is the contents of the element." LIMIT bounds the search. -Return a list whose car is `property-drawer' and cdr is a plist -containing `:begin', `:end', `:contents-begin', `:contents-end', -`:post-blank' and `:post-affiliated' keywords. +Return a new syntax node of `property-drawer' type containing +`:begin', `:end', `:contents-begin', `:contents-end', `:post-blank' +and `:post-affiliated' properties. Assume point is at the beginning of the property drawer." (save-excursion @@ -1765,13 +2044,14 @@ Assume point is at the beginning of the property drawer." (before-blank (progn (forward-line) (point))) (end (progn (skip-chars-forward " \r\t\n" limit) (if (eobp) (point) (line-beginning-position))))) - (list 'property-drawer - (list :begin begin - :end end - :contents-begin (and contents-end contents-begin) - :contents-end contents-end - :post-blank (count-lines before-blank end) - :post-affiliated begin)))))) + (org-element-create + 'property-drawer + (list :begin begin + :end end + :contents-begin (and contents-end contents-begin) + :contents-end contents-end + :post-blank (count-lines before-blank end) + :post-affiliated begin)))))) (defun org-element-property-drawer-interpreter (_ contents) "Interpret property-drawer element as Org syntax. @@ -1789,9 +2069,9 @@ the buffer position at the beginning of the first affiliated keyword and CDR is a plist of affiliated keywords along with their value. -Return a list whose CAR is `quote-block' and CDR is a plist -containing `:begin', `:end', `:contents-begin', `:contents-end', -`:post-blank' and `:post-affiliated' keywords. +Return a new syntax node of `quote-block' type containing `:begin', +`:end', `:contents-begin', `:contents-end', `:post-blank' and +`:post-affiliated' properties. Assume point is at the beginning of the block." (let ((case-fold-search t)) @@ -1813,15 +2093,16 @@ Assume point is at the beginning of the block." (point))) (end (progn (skip-chars-forward " \r\t\n" limit) (if (eobp) (point) (line-beginning-position))))) - (list 'quote-block - (nconc - (list :begin begin - :end end - :contents-begin contents-begin - :contents-end contents-end - :post-blank (count-lines pos-before-blank end) - :post-affiliated post-affiliated) - (cdr affiliated))))))))) + (org-element-create + 'quote-block + (nconc + (list :begin begin + :end end + :contents-begin contents-begin + :contents-end contents-end + :post-blank (count-lines pos-before-blank end) + :post-affiliated post-affiliated) + (cdr affiliated))))))))) (defun org-element-quote-block-interpreter (_ contents) "Interpret quote-block element as Org syntax. @@ -1834,30 +2115,32 @@ CONTENTS is the contents of the element." (defun org-element-section-parser (_) "Parse a section. -Return a list whose CAR is `section' and CDR is a plist -containing `:begin', `:end', `:contents-begin', `contents-end', -`:post-blank' and `:post-affiliated' keywords." +Return a new syntax node of `section' type containing `:begin', +`:end', `:contents-begin', `contents-end', `:post-blank' and +`:post-affiliated' properties." (save-excursion ;; Beginning of section is the beginning of the first non-blank ;; line after previous headline. (let* ((begin (point)) - (end (progn (org-with-limited-levels (outline-next-heading)) - (point))) - (pos-before-blank (progn (skip-chars-backward " \r\t\n") - (line-beginning-position 2))) - (robust-end (when (> (- pos-before-blank 2) begin) - (- pos-before-blank 2))) - (robust-begin (when robust-end begin)) - ) - (list 'section - (list :begin begin - :end end - :contents-begin begin - :contents-end pos-before-blank - :robust-begin robust-begin - :robust-end robust-end - :post-blank (count-lines pos-before-blank end) - :post-affiliated begin))))) + (end + (if (re-search-forward (org-get-limited-outline-regexp t) nil 'move) + (goto-char (match-beginning 0)) + (point))) + (contents-end end) + (robust-end end) + (robust-begin begin)) + (org-element-create + 'section + (list :begin begin + :end end + :contents-begin begin + :contents-end contents-end + :robust-begin robust-begin + :robust-end robust-end + ;; Trailing blank lines in org-data, headlines, and + ;; sections belong to the containing elements. + :post-blank 0 + :post-affiliated begin))))) (defun org-element-section-interpreter (_ contents) "Interpret section element as Org syntax. @@ -1875,20 +2158,20 @@ the buffer position at the beginning of the first affiliated keyword and CDR is a plist of affiliated keywords along with their value. -Return a list whose CAR is `special-block' and CDR is a plist -containing `:type', `:parameters', `:begin', `:end', -`:contents-begin', `:contents-end', `:post-blank' and -`:post-affiliated' keywords. +Return a new syntax node of `special-block' type containing `:type', +`:parameters', `:begin', `:end', `:contents-begin', `:contents-end', +`:post-blank' and `:post-affiliated' properties. Assume point is at the beginning of the block." (let* ((case-fold-search t) (type (progn (looking-at "[ \t]*#\\+BEGIN_\\(\\S-+\\)[ \t]*\\(.*\\)[ \t]*$") - (match-string-no-properties 1))) + (org-element--get-cached-string + (match-string-no-properties 1)))) (parameters (match-string-no-properties 2))) (if (not (save-excursion - (re-search-forward - (format "^[ \t]*#\\+END_%s[ \t]*$" (regexp-quote type)) - limit t))) + (re-search-forward + (format "^[ \t]*#\\+END_%s[ \t]*$" (regexp-quote type)) + limit t))) ;; Incomplete block: parse it as a paragraph. (org-element-paragraph-parser limit affiliated) (let ((block-end-line (match-beginning 0))) @@ -1905,18 +2188,19 @@ Assume point is at the beginning of the block." (point))) (end (progn (skip-chars-forward " \r\t\n" limit) (if (eobp) (point) (line-beginning-position))))) - (list 'special-block - (nconc - (list :type type - :parameters (and (org-string-nw-p parameters) - (org-trim parameters)) - :begin begin - :end end - :contents-begin contents-begin - :contents-end contents-end - :post-blank (count-lines pos-before-blank end) - :post-affiliated post-affiliated) - (cdr affiliated))))))))) + (org-element-create + 'special-block + (nconc + (list :type type + :parameters (and (org-string-nw-p parameters) + (org-trim parameters)) + :begin begin + :end end + :contents-begin contents-begin + :contents-end contents-end + :post-blank (count-lines pos-before-blank end) + :post-affiliated post-affiliated) + (cdr affiliated))))))))) (defun org-element-special-block-interpreter (special-block contents) "Interpret SPECIAL-BLOCK element as Org syntax. @@ -1950,10 +2234,9 @@ the buffer position at the beginning of the first affiliated keyword and cdr is a plist of affiliated keywords along with their value. -Return a list whose car is `babel-call' and cdr is a plist -containing `:call', `:inside-header', `:arguments', -`:end-header', `:begin', `:end', `:value', `:post-blank' and -`:post-affiliated' as keywords." +Return a new syntax node of `babel-call' type containing `:call', +`:inside-header', `:arguments', `:end-header', `:begin', `:end', +`:value', `:post-blank' and `:post-affiliated' as properties." (save-excursion (let* ((begin (car affiliated)) (post-affiliated (point)) @@ -1978,18 +2261,19 @@ containing `:call', `:inside-header', `:arguments', (end (progn (forward-line) (skip-chars-forward " \r\t\n" limit) (if (eobp) (point) (line-beginning-position))))) - (list 'babel-call - (nconc - (list :call call - :inside-header inside-header - :arguments arguments - :end-header end-header - :begin begin - :end end - :value value - :post-blank (count-lines before-blank end) - :post-affiliated post-affiliated) - (cdr affiliated)))))) + (org-element-create + 'babel-call + (nconc + (list :call call + :inside-header inside-header + :arguments arguments + :end-header end-header + :begin begin + :end end + :value value + :post-blank (count-lines before-blank end) + :post-affiliated post-affiliated) + (cdr affiliated)))))) (defun org-element-babel-call-interpreter (babel-call _) "Interpret BABEL-CALL element as Org syntax." @@ -2009,16 +2293,15 @@ containing `:call', `:inside-header', `:arguments', LIMIT bounds the search. -Return a list whose CAR is `clock' and CDR is a plist containing -`:status', `:value', `:time', `:begin', `:end', `:post-blank' and -`:post-affiliated' as keywords." +Return a new syntax node of `clock' type containing `:status', +`:value', `:time', `:begin', `:end', `:post-blank' and +`:post-affiliated' as properties." (save-excursion - (let* ((case-fold-search nil) - (begin (point)) - (value (progn (search-forward "CLOCK:" (line-end-position) t) + (let* ((begin (point)) + (value (progn (search-forward "CLOCK:" (line-end-position)) (skip-chars-forward " \t") (org-element-timestamp-parser))) - (duration (and (search-forward " => " (line-end-position) t) + (duration (and (search-forward "=> " (line-end-position) t) (progn (skip-chars-forward " \t") (looking-at "\\(\\S-+\\)[ \t]*$")) (match-string-no-properties 1))) @@ -2026,17 +2309,18 @@ Return a list whose CAR is `clock' and CDR is a plist containing (post-blank (let ((before-blank (progn (forward-line) (point)))) (skip-chars-forward " \r\t\n" limit) (skip-chars-backward " \t") - (unless (bolp) (end-of-line)) + (unless (bolp) (skip-chars-forward " \t")) (count-lines before-blank (point)))) (end (point))) - (list 'clock - (list :status status - :value value - :duration duration - :begin begin - :end end - :post-blank post-blank - :post-affiliated begin))))) + (org-element-create + 'clock + (list :status status + :value value + :duration duration + :begin begin + :end end + :post-blank post-blank + :post-affiliated begin))))) (defun org-element-clock-interpreter (clock _) "Interpret CLOCK element as Org syntax." @@ -2058,21 +2342,20 @@ Return a list whose CAR is `clock' and CDR is a plist containing LIMIT bounds the search. -Return a list whose CAR is `comment' and CDR is a plist -containing `:begin', `:end', `:value', `:post-blank', -`:post-affiliated' keywords. +Return a new syntax node of `comment' type containing `:begin', +`:end', `:value', `:post-blank', `:post-affiliated' properties. Assume point is at comment beginning." (save-excursion (let* ((begin (point)) - (value (prog2 (looking-at "[ \t]*# ?") + (value (prog2 (looking-at org-comment-regexp) (buffer-substring-no-properties (match-end 0) (line-end-position)) (forward-line))) (com-end ;; Get comments ending. (progn - (while (and (< (point) limit) (looking-at "[ \t]*#\\( \\|$\\)")) + (while (and (< (point) limit) (looking-at org-comment-regexp)) ;; Accumulate lines without leading hash and first ;; whitespace. (setq value @@ -2085,12 +2368,13 @@ Assume point is at comment beginning." (end (progn (goto-char com-end) (skip-chars-forward " \r\t\n" limit) (if (eobp) (point) (line-beginning-position))))) - (list 'comment - (list :begin begin - :end end - :value value - :post-blank (count-lines com-end end) - :post-affiliated begin))))) + (org-element-create + 'comment + (list :begin begin + :end end + :value value + :post-blank (count-lines com-end end) + :post-affiliated begin))))) (defun org-element-comment-interpreter (comment _) "Interpret COMMENT element as Org syntax. @@ -2108,9 +2392,8 @@ the buffer position at the beginning of the first affiliated keyword and CDR is a plist of affiliated keywords along with their value. -Return a list whose CAR is `comment-block' and CDR is a plist -containing `:begin', `:end', `:value', `:post-blank' and -`:post-affiliated' keywords. +Return a new syntax node of `comment-block' type containing `:begin', +`:end', `:value', `:post-blank' and `:post-affiliated' properties. Assume point is at comment block beginning." (let ((case-fold-search t)) @@ -2128,16 +2411,20 @@ Assume point is at comment block beginning." (point))) (end (progn (skip-chars-forward " \r\t\n" limit) (if (eobp) (point) (line-beginning-position)))) - (value (buffer-substring-no-properties - contents-begin contents-end))) - (list 'comment-block - (nconc - (list :begin begin - :end end - :value value - :post-blank (count-lines pos-before-blank end) - :post-affiliated post-affiliated) - (cdr affiliated))))))))) + (value + (org-element-deferred-create + t #'org-element--substring + (- contents-begin begin) + (- contents-end begin)))) + (org-element-create + 'comment-block + (nconc + (list :begin begin + :end end + :value value + :post-blank (count-lines pos-before-blank end) + :post-affiliated post-affiliated) + (cdr affiliated))))))))) (defun org-element-comment-block-interpreter (comment-block _) "Interpret COMMENT-BLOCK element as Org syntax." @@ -2157,9 +2444,8 @@ the buffer position at the beginning of the first affiliated keyword and CDR is a plist of affiliated keywords along with their value. -Return a list whose CAR is `diary-sexp' and CDR is a plist -containing `:begin', `:end', `:value', `:post-blank' and -`:post-affiliated' keywords." +Return a new syntax node of `diary-sexp' type containing `:begin', +`:end', `:value', `:post-blank' and `:post-affiliated' properties." (save-excursion (let ((begin (car affiliated)) (post-affiliated (point)) @@ -2168,14 +2454,15 @@ containing `:begin', `:end', `:value', `:post-blank' and (pos-before-blank (progn (forward-line) (point))) (end (progn (skip-chars-forward " \r\t\n" limit) (if (eobp) (point) (line-beginning-position))))) - (list 'diary-sexp - (nconc - (list :value value - :begin begin - :end end - :post-blank (count-lines pos-before-blank end) - :post-affiliated post-affiliated) - (cdr affiliated)))))) + (org-element-create + 'diary-sexp + (nconc + (list :value value + :begin begin + :end end + :post-blank (count-lines pos-before-blank end) + :post-affiliated post-affiliated) + (cdr affiliated)))))) (defun org-element-diary-sexp-interpreter (diary-sexp _) "Interpret DIARY-SEXP as Org syntax." @@ -2192,10 +2479,10 @@ the buffer position at the beginning of the first affiliated keyword and CDR is a plist of affiliated keywords along with their value. -Return a list whose CAR is `example-block' and CDR is a plist -containing `:begin', `:end', `:number-lines', `:preserve-indent', -`:retain-labels', `:use-labels', `:label-fmt', `:switches', -`:value', `:post-blank' and `:post-affiliated' keywords." +Return a new syntax node of `example-block' type containing `:begin', +`:end', `:number-lines', `:preserve-indent', `:retain-labels', +`:use-labels', `:label-fmt', `:switches', `:value', `:post-blank' and +`:post-affiliated' properties." (let ((case-fold-search t)) (if (not (save-excursion (re-search-forward "^[ \t]*#\\+END_EXAMPLE[ \t]*$" limit t))) @@ -2221,49 +2508,52 @@ containing `:begin', `:end', `:number-lines', `:preserve-indent', ;; first line. (1- (string-to-number (match-string 2 switches))))))) (preserve-indent - (and switches (string-match "-i\\>" switches))) + (and switches (string-match-p "-i\\>" switches))) ;; Should labels be retained in (or stripped from) example ;; blocks? (retain-labels (or (not switches) - (not (string-match "-r\\>" switches)) - (and number-lines (string-match "-k\\>" switches)))) + (not (string-match-p "-r\\>" switches)) + (and number-lines (string-match-p "-k\\>" switches)))) ;; What should code-references use - labels or ;; line-numbers? (use-labels (or (not switches) (and retain-labels - (not (string-match "-k\\>" switches))))) + (not (string-match-p "-k\\>" switches))))) (label-fmt (and switches (string-match "-l +\"\\([^\"\n]+\\)\"" switches) - (match-string 1 switches))) + (match-string-no-properties 1 switches))) ;; Standard block parsing. (begin (car affiliated)) (post-affiliated (point)) (contents-begin (line-beginning-position 2)) - (value (org-unescape-code-in-string - (buffer-substring-no-properties - contents-begin contents-end))) + (value + (org-element-deferred-create + t #'org-element--unescape-substring + (- contents-begin begin) + (- contents-end begin))) (pos-before-blank (progn (goto-char contents-end) (forward-line) (point))) (end (progn (skip-chars-forward " \r\t\n" limit) (if (eobp) (point) (line-beginning-position))))) - (list 'example-block - (nconc - (list :begin begin - :end end - :value value - :switches switches - :number-lines number-lines - :preserve-indent preserve-indent - :retain-labels retain-labels - :use-labels use-labels - :label-fmt label-fmt - :post-blank (count-lines pos-before-blank end) - :post-affiliated post-affiliated) - (cdr affiliated))))))))) + (org-element-create + 'example-block + (nconc + (list :begin begin + :end end + :value value + :switches switches + :number-lines number-lines + :preserve-indent preserve-indent + :retain-labels retain-labels + :use-labels use-labels + :label-fmt label-fmt + :post-blank (count-lines pos-before-blank end) + :post-affiliated post-affiliated) + (cdr affiliated))))))))) (defun org-element-example-block-interpreter (example-block _) "Interpret EXAMPLE-BLOCK element as Org syntax." @@ -2271,9 +2561,7 @@ containing `:begin', `:end', `:number-lines', `:preserve-indent', (value (let ((val (org-element-property :value example-block))) (cond - ((or org-src-preserve-indentation - (org-element-property :preserve-indent example-block)) - val) + ((org-src-preserve-indentation-p example-block) val) ((= 0 org-edit-src-content-indentation) (org-remove-indentation val)) (t @@ -2296,9 +2584,9 @@ the buffer position at the beginning of the first affiliated keyword and CDR is a plist of affiliated keywords along with their value. -Return a list whose CAR is `export-block' and CDR is a plist -containing `:begin', `:end', `:type', `:value', `:post-blank' and -`:post-affiliated' keywords. +Return a new syntax node of `export-block' type containing `:begin', +`:end', `:type', `:value', `:post-blank' and `:post-affiliated' +properties. Assume point is at export-block beginning." (let* ((case-fold-search t)) @@ -2321,18 +2609,21 @@ Assume point is at export-block beginning." (point))) (end (progn (skip-chars-forward " \r\t\n" limit) (if (eobp) (point) (line-beginning-position)))) - (value (org-unescape-code-in-string - (buffer-substring-no-properties contents-begin - contents-end)))) - (list 'export-block - (nconc - (list :type (and backend (upcase backend)) - :begin begin - :end end - :value value - :post-blank (count-lines pos-before-blank end) - :post-affiliated post-affiliated) - (cdr affiliated)))))))) + (value + (org-element-deferred-create + t #'org-element--unescape-substring + (- contents-begin begin) + (- contents-end begin)))) + (org-element-create + 'export-block + (nconc + (list :type (and backend (upcase backend)) + :begin begin + :end end + :value value + :post-blank (count-lines pos-before-blank end) + :post-affiliated post-affiliated) + (cdr affiliated)))))))) (defun org-element-export-block-interpreter (export-block _) "Interpret EXPORT-BLOCK element as Org syntax." @@ -2351,9 +2642,8 @@ the buffer position at the beginning of the first affiliated keyword and CDR is a plist of affiliated keywords along with their value. -Return a list whose CAR is `fixed-width' and CDR is a plist -containing `:begin', `:end', `:value', `:post-blank' and -`:post-affiliated' keywords. +Return a new syntax node of `fixed-width' type containing `:begin', +`:end', `:value', `:post-blank' and `:post-affiliated' properties. Assume point is at the beginning of the fixed-width area." (save-excursion @@ -2362,22 +2652,23 @@ Assume point is at the beginning of the fixed-width area." (end-area (progn (while (and (< (point) limit) - (looking-at "[ \t]*:\\( \\|$\\)")) + (looking-at-p "[ \t]*:\\( \\|$\\)")) (forward-line)) (if (bolp) (line-end-position 0) (point)))) (end (progn (skip-chars-forward " \r\t\n" limit) (if (eobp) (point) (line-beginning-position))))) - (list 'fixed-width - (nconc - (list :begin begin - :end end - :value (replace-regexp-in-string - "^[ \t]*: ?" "" - (buffer-substring-no-properties post-affiliated - end-area)) - :post-blank (count-lines end-area end) - :post-affiliated post-affiliated) - (cdr affiliated)))))) + (org-element-create + 'fixed-width + (nconc + (list :begin begin + :end end + :value (replace-regexp-in-string + "^[ \t]*: ?" "" + (buffer-substring-no-properties post-affiliated + end-area)) + :post-blank (count-lines end-area end) + :post-affiliated post-affiliated) + (cdr affiliated)))))) (defun org-element-fixed-width-interpreter (fixed-width _) "Interpret FIXED-WIDTH element as Org syntax." @@ -2397,22 +2688,22 @@ the buffer position at the beginning of the first affiliated keyword and CDR is a plist of affiliated keywords along with their value. -Return a list whose CAR is `horizontal-rule' and CDR is a plist -containing `:begin', `:end', `:post-blank' and `:post-affiliated' -keywords." +Return a new syntax node of `horizontal-rule' type containing +`:begin', `:end', `:post-blank' and `:post-affiliated' properties." (save-excursion (let ((begin (car affiliated)) (post-affiliated (point)) (post-hr (progn (forward-line) (point))) (end (progn (skip-chars-forward " \r\t\n" limit) (if (eobp) (point) (line-beginning-position))))) - (list 'horizontal-rule - (nconc - (list :begin begin - :end end - :post-blank (count-lines post-hr end) - :post-affiliated post-affiliated) - (cdr affiliated)))))) + (org-element-create + 'horizontal-rule + (nconc + (list :begin begin + :end end + :post-blank (count-lines post-hr end) + :post-affiliated post-affiliated) + (cdr affiliated)))))) (defun org-element-horizontal-rule-interpreter (&rest _) "Interpret HORIZONTAL-RULE element as Org syntax." @@ -2429,9 +2720,9 @@ the buffer position at the beginning of the first affiliated keyword and CDR is a plist of affiliated keywords along with their value. -Return a list whose CAR is a normalized `keyword' (uppercase) and -CDR is a plist containing `:key', `:value', `:begin', `:end', -`:post-blank' and `:post-affiliated' keywords." +Return a new syntax node of `keyword' type containing `:key', +`:value', `:begin', `:end', `:post-blank' and `:post-affiliated' +properties." (save-excursion ;; An orphaned affiliated keyword is considered as a regular ;; keyword. In this case AFFILIATED is nil, so we take care of @@ -2439,21 +2730,23 @@ CDR is a plist containing `:key', `:value', `:begin', `:end', (let ((begin (or (car affiliated) (point))) (post-affiliated (point)) (key (progn (looking-at "[ \t]*#\\+\\(\\S-*\\):") - (upcase (match-string-no-properties 1)))) + (org-element--get-cached-string + (upcase (match-string-no-properties 1))))) (value (org-trim (buffer-substring-no-properties (match-end 0) (line-end-position)))) (pos-before-blank (progn (forward-line) (point))) (end (progn (skip-chars-forward " \r\t\n" limit) (if (eobp) (point) (line-beginning-position))))) - (list 'keyword - (nconc - (list :key key - :value value - :begin begin - :end end - :post-blank (count-lines pos-before-blank end) - :post-affiliated post-affiliated) - (cdr affiliated)))))) + (org-element-create + 'keyword + (nconc + (list :key key + :value value + :begin begin + :end end + :post-blank (count-lines pos-before-blank end) + :post-affiliated post-affiliated) + (cdr affiliated)))))) (defun org-element-keyword-interpreter (keyword _) "Interpret KEYWORD element as Org syntax." @@ -2471,6 +2764,10 @@ The environment is captured by the first group. See also `org-element--latex-end-environment'.") +(defconst org-element--latex-begin-environment-nogroup + "^[ \t]*\\\\begin{[A-Za-z0-9*]+}" + "Regexp matching the beginning of a LaTeX environment.") + (defconst org-element--latex-end-environment "\\\\end{%s}[ \t]*$" "Format string matching the ending of a LaTeX environment. @@ -2484,9 +2781,9 @@ the buffer position at the beginning of the first affiliated keyword and CDR is a plist of affiliated keywords along with their value. -Return a list whose CAR is `latex-environment' and CDR is a plist -containing `:begin', `:end', `:value', `:post-blank' and -`:post-affiliated' keywords. +Return a new syntax node of `latex-environment' type containing +`:begin', `:end', `:value', `:post-blank' and `:post-affiliated' +properties. Assume point is at the beginning of the latex environment." (save-excursion @@ -2494,23 +2791,28 @@ Assume point is at the beginning of the latex environment." (code-begin (point))) (looking-at org-element--latex-begin-environment) (if (not (re-search-forward (format org-element--latex-end-environment - (regexp-quote (match-string 1))) - limit t)) + (regexp-quote (match-string 1))) + limit t)) ;; Incomplete latex environment: parse it as a paragraph. (org-element-paragraph-parser limit affiliated) (let* ((code-end (progn (forward-line) (point))) (begin (car affiliated)) - (value (buffer-substring-no-properties code-begin code-end)) + (value + (org-element-deferred-create + t #'org-element--substring + (- code-begin begin) + (- code-end begin))) (end (progn (skip-chars-forward " \r\t\n" limit) (if (eobp) (point) (line-beginning-position))))) - (list 'latex-environment - (nconc - (list :begin begin - :end end - :value value - :post-blank (count-lines code-end end) - :post-affiliated code-begin) - (cdr affiliated)))))))) + (org-element-create + 'latex-environment + (nconc + (list :begin begin + :end end + :value value + :post-blank (count-lines code-end end) + :post-affiliated code-begin) + (cdr affiliated)))))))) (defun org-element-latex-environment-interpreter (latex-environment _) "Interpret LATEX-ENVIRONMENT element as Org syntax." @@ -2519,31 +2821,26 @@ Assume point is at the beginning of the latex environment." ;;;; Node Property -(defun org-element-node-property-parser (limit) +(defun org-element-node-property-parser (_) "Parse a node-property at point. -LIMIT bounds the search. - -Return a list whose CAR is `node-property' and CDR is a plist -containing `:key', `:value', `:begin', `:end', `:post-blank' and -`:post-affiliated' keywords." +Return a new syntax node of `node-property' type containing `:key', +`:value', `:begin', `:end', `:post-blank' and `:post-affiliated' +properties." (looking-at org-property-re) - (let ((case-fold-search t) - (begin (point)) - (key (match-string-no-properties 2)) + (let ((begin (point)) + (key (org-element--get-cached-string + (match-string-no-properties 2))) (value (match-string-no-properties 3)) - (end (save-excursion - (end-of-line) - (if (re-search-forward org-property-re limit t) - (line-beginning-position) - limit)))) - (list 'node-property - (list :key key - :value value - :begin begin - :end end - :post-blank 0 - :post-affiliated begin)))) + (end (min (point-max) (1+ (match-end 0))))) + (org-element-create + 'node-property + (list :key key + :value value + :begin begin + :end end + :post-blank 0 + :post-affiliated begin)))) (defun org-element-node-property-interpreter (node-property _) "Interpret NODE-PROPERTY element as Org syntax." @@ -2562,9 +2859,9 @@ the buffer position at the beginning of the first affiliated keyword and CDR is a plist of affiliated keywords along with their value. -Return a list whose CAR is `paragraph' and CDR is a plist -containing `:begin', `:end', `:contents-begin' and -`:contents-end', `:post-blank' and `:post-affiliated' keywords. +Return a new syntax node of `paragraph' type containing `:begin', +`:end', `:contents-begin' and `:contents-end', `:post-blank' and +`:post-affiliated' properties. Assume point is at the beginning of the paragraph." (save-excursion @@ -2581,10 +2878,11 @@ Assume point is at the beginning of the paragraph." (while (not (cond ((not (and (re-search-forward - org-element-paragraph-separate limit 'move) - (progn (beginning-of-line) t)))) - ((looking-at org-element-drawer-re) + org-element-paragraph-separate limit 'move) + (progn (forward-line 0) t)))) + ((looking-at-p org-element-drawer-re) (save-excursion + (forward-line 1) (re-search-forward "^[ \t]*:END:[ \t]*$" limit t))) ((looking-at "[ \t]*#\\+BEGIN_\\(\\S-+\\)") (save-excursion @@ -2611,15 +2909,16 @@ Assume point is at the beginning of the paragraph." (line-beginning-position 2))) (end (progn (skip-chars-forward " \r\t\n" limit) (if (eobp) (point) (line-beginning-position))))) - (list 'paragraph - (nconc - (list :begin begin - :end end - :contents-begin contents-begin - :contents-end contents-end - :post-blank (count-lines before-blank end) - :post-affiliated contents-begin) - (cdr affiliated)))))) + (org-element-create + 'paragraph + (nconc + (list :begin begin + :end end + :contents-begin contents-begin + :contents-end contents-end + :post-blank (count-lines before-blank end) + :post-affiliated contents-begin) + (cdr affiliated)))))) (defun org-element-paragraph-interpreter (_ contents) "Interpret paragraph element as Org syntax. @@ -2634,16 +2933,16 @@ CONTENTS is the contents of the element." LIMIT bounds the search. -Return a list whose CAR is `planning' and CDR is a plist -containing `:closed', `:deadline', `:scheduled', `:begin', -`:end', `:post-blank' and `:post-affiliated' keywords." +Return a new syntax node of `planning' type containing `:closed', +`:deadline', `:scheduled', `:begin', `:end', `:post-blank' and +`:post-affiliated' properties." (save-excursion (let* ((case-fold-search nil) (begin (point)) (post-blank (let ((before-blank (progn (forward-line) (point)))) (skip-chars-forward " \r\t\n" limit) (skip-chars-backward " \t") - (unless (bolp) (end-of-line)) + (unless (bolp) (skip-chars-forward " \t")) (count-lines before-blank (point)))) (end (point)) closed deadline scheduled) @@ -2656,14 +2955,15 @@ containing `:closed', `:deadline', `:scheduled', `:begin', ((equal keyword org-element-closed-keyword) (setq closed time)) ((equal keyword org-element-deadline-keyword) (setq deadline time)) (t (setq scheduled time))))) - (list 'planning - (list :closed closed - :deadline deadline - :scheduled scheduled - :begin begin - :end end - :post-blank post-blank - :post-affiliated begin))))) + (org-element-create + 'planning + (list :closed closed + :deadline deadline + :scheduled scheduled + :begin begin + :end end + :post-blank post-blank + :post-affiliated begin))))) (defun org-element-planning-interpreter (planning _) "Interpret PLANNING element as Org syntax." @@ -2695,11 +2995,10 @@ the buffer position at the beginning of the first affiliated keyword and CDR is a plist of affiliated keywords along with their value. -Return a list whose CAR is `src-block' and CDR is a plist -containing `:language', `:switches', `:parameters', `:begin', -`:end', `:number-lines', `:retain-labels', `:use-labels', -`:label-fmt', `:preserve-indent', `:value', `:post-blank' and -`:post-affiliated' keywords. +Return a new syntax node of `src-block' type containing `:language', +`:switches', `:parameters', `:begin', `:end', `:number-lines', +`:retain-labels', `:use-labels', `:label-fmt', `:preserve-indent', +`:value', `:post-blank' and `:post-affiliated' properties. Assume point is at the beginning of the block." (let ((case-fold-search t)) @@ -2719,7 +3018,8 @@ Assume point is at the beginning of the block." \\(?: +\\(\\S-+\\)\\)?\ \\(\\(?: +\\(?:-\\(?:l \".+\"\\|[ikr]\\)\\|[-+]n\\(?: *[0-9]+\\)?\\)\\)+\\)?\ \\(.*\\)[ \t]*$") - (match-string-no-properties 1))) + (org-element--get-cached-string + (match-string-no-properties 1)))) ;; Get switches. (switches (match-string-no-properties 2)) ;; Get parameters. @@ -2738,51 +3038,54 @@ Assume point is at the beginning of the block." ;; first line. (1- (string-to-number (match-string 2 switches))))))) (preserve-indent (and switches - (string-match "-i\\>" switches))) + (string-match-p "-i\\>" switches))) (label-fmt (and switches (string-match "-l +\"\\([^\"\n]+\\)\"" switches) - (match-string 1 switches))) + (match-string-no-properties 1 switches))) ;; Should labels be retained in (or stripped from) ;; source blocks? (retain-labels (or (not switches) - (not (string-match "-r\\>" switches)) - (and number-lines (string-match "-k\\>" switches)))) + (not (string-match-p "-r\\>" switches)) + (and number-lines (string-match-p "-k\\>" switches)))) ;; What should code-references use - labels or ;; line-numbers? (use-labels (or (not switches) (and retain-labels - (not (string-match "-k\\>" switches))))) + (not (string-match-p "-k\\>" switches))))) ;; Retrieve code. - (value (org-unescape-code-in-string - (buffer-substring-no-properties - (line-beginning-position 2) contents-end))) + (value + (org-element-deferred-create + t #'org-element--unescape-substring + (- (line-beginning-position 2) begin) + (- contents-end begin))) (pos-before-blank (progn (goto-char contents-end) (forward-line) (point))) ;; Get position after ending blank lines. (end (progn (skip-chars-forward " \r\t\n" limit) (if (eobp) (point) (line-beginning-position))))) - (list 'src-block - (nconc - (list :language language - :switches (and (org-string-nw-p switches) - (org-trim switches)) - :parameters (and (org-string-nw-p parameters) - (org-trim parameters)) - :begin begin - :end end - :number-lines number-lines - :preserve-indent preserve-indent - :retain-labels retain-labels - :use-labels use-labels - :label-fmt label-fmt - :value value - :post-blank (count-lines pos-before-blank end) - :post-affiliated post-affiliated) - (cdr affiliated))))))))) + (org-element-create + 'src-block + (nconc + (list :language language + :switches (and (org-string-nw-p switches) + (org-trim switches)) + :parameters (and (org-string-nw-p parameters) + (org-trim parameters)) + :begin begin + :end end + :number-lines number-lines + :preserve-indent preserve-indent + :retain-labels retain-labels + :use-labels use-labels + :label-fmt label-fmt + :value value + :post-blank (count-lines pos-before-blank end) + :post-affiliated post-affiliated) + (cdr affiliated))))))))) (defun org-element-src-block-interpreter (src-block _) "Interpret SRC-BLOCK element as Org syntax." @@ -2792,9 +3095,7 @@ Assume point is at the beginning of the block." (value (let ((val (org-element-property :value src-block))) (cond - ((or org-src-preserve-indentation - (org-element-property :preserve-indent src-block)) - val) + ((org-src-preserve-indentation-p src-block) val) ((zerop org-edit-src-content-indentation) (org-remove-indentation val)) (t @@ -2819,16 +3120,15 @@ the buffer position at the beginning of the first affiliated keyword and CDR is a plist of affiliated keywords along with their value. -Return a list whose CAR is `table' and CDR is a plist containing -`:begin', `:end', `:tblfm', `:type', `:contents-begin', -`:contents-end', `:value', `:post-blank' and `:post-affiliated' -keywords. +Return a new syntax node of `table' type containing `:begin', `:end', +`:tblfm', `:type', `:contents-begin', `:contents-end', `:value', +`:post-blank' and `:post-affiliated' properties. Assume point is at the beginning of the table." (save-excursion (let* ((case-fold-search t) (table-begin (point)) - (type (if (looking-at "[ \t]*|") 'org 'table.el)) + (type (if (looking-at-p "[ \t]*|") 'org 'table.el)) (end-re (format "^[ \t]*\\($\\|[^| \t%s]\\)" (if (eq type 'org) "" "+"))) (begin (car affiliated)) @@ -2844,23 +3144,26 @@ Assume point is at the beginning of the table." (pos-before-blank (point)) (end (progn (skip-chars-forward " \r\t\n" limit) (if (eobp) (point) (line-beginning-position))))) - (list 'table - (nconc - (list :begin begin - :end end - :type type - :tblfm tblfm - ;; Only `org' tables have contents. `table.el' tables - ;; use a `:value' property to store raw table as - ;; a string. - :contents-begin (and (eq type 'org) table-begin) - :contents-end (and (eq type 'org) table-end) - :value (and (eq type 'table.el) - (buffer-substring-no-properties - table-begin table-end)) - :post-blank (count-lines pos-before-blank end) - :post-affiliated table-begin) - (cdr affiliated)))))) + (org-element-create + 'table + (nconc + (list :begin begin + :end end + :type type + :tblfm tblfm + ;; Only `org' tables have contents. `table.el' tables + ;; use a `:value' property to store raw table as + ;; a string. + :contents-begin (and (eq type 'org) table-begin) + :contents-end (and (eq type 'org) table-end) + :value (and (eq type 'table.el) + (org-element-deferred-create + t #'org-element--substring + (- table-begin begin) + (- table-end begin))) + :post-blank (count-lines pos-before-blank end) + :post-affiliated table-begin) + (cdr affiliated)))))) (defun org-element-table-interpreter (table contents) "Interpret TABLE element as Org syntax. @@ -2880,11 +3183,11 @@ CONTENTS is a string, if table's type is `org', or nil." (defun org-element-table-row-parser (_) "Parse table row at point. -Return a list whose CAR is `table-row' and CDR is a plist -containing `:begin', `:end', `:contents-begin', `:contents-end', -`:type', `:post-blank' and `:post-affiliated' keywords." +Return a new syntax node of `table-row' type containing `:begin', +`:end', `:contents-begin', `:contents-end', `:type', `:post-blank' and +`:post-affiliated' properties." (save-excursion - (let* ((type (if (looking-at "^[ \t]*|-") 'rule 'standard)) + (let* ((type (if (looking-at-p "^[ \t]*|-") 'rule 'standard)) (begin (point)) ;; A table rule has no contents. In that case, ensure ;; CONTENTS-BEGIN matches CONTENTS-END. @@ -2895,14 +3198,15 @@ containing `:begin', `:end', `:contents-begin', `:contents-end', (skip-chars-backward " \t") (point)))) (end (line-beginning-position 2))) - (list 'table-row - (list :type type - :begin begin - :end end - :contents-begin contents-begin - :contents-end contents-end - :post-blank 0 - :post-affiliated begin))))) + (org-element-create + 'table-row + (list :type type + :begin begin + :end end + :contents-begin contents-begin + :contents-end contents-end + :post-blank 0 + :post-affiliated begin))))) (defun org-element-table-row-interpreter (table-row contents) "Interpret TABLE-ROW element as Org syntax. @@ -2921,9 +3225,9 @@ the buffer position at the beginning of the first affiliated keyword and CDR is a plist of affiliated keywords along with their value. -Return a list whose CAR is `verse-block' and CDR is a plist -containing `:begin', `:end', `:contents-begin', `:contents-end', -`:post-blank' and `:post-affiliated' keywords. +Return a new syntax node of `verse-block' type containing `:begin', +`:end', `:contents-begin', `:contents-end', `:post-blank' and +`:post-affiliated' properties. Assume point is at beginning of the block." (let ((case-fold-search t)) @@ -2941,15 +3245,16 @@ Assume point is at beginning of the block." (point))) (end (progn (skip-chars-forward " \r\t\n" limit) (if (eobp) (point) (line-beginning-position))))) - (list 'verse-block - (nconc - (list :begin begin - :end end - :contents-begin contents-begin - :contents-end contents-end - :post-blank (count-lines pos-before-blank end) - :post-affiliated post-affiliated) - (cdr affiliated))))))))) + (org-element-create + 'verse-block + (nconc + (list :begin begin + :end end + :contents-begin contents-begin + :contents-end contents-end + :post-blank (count-lines pos-before-blank end) + :post-affiliated post-affiliated) + (cdr affiliated))))))))) (defun org-element-verse-block-interpreter (_ contents) "Interpret verse-block element as Org syntax. @@ -2968,7 +3273,7 @@ CONTENTS is verse block contents." ;; object types they can contain will be specified in ;; `org-element-object-restrictions'. ;; -;; Creating a new type of object requires to alter +;; Creating a new type of object requires altering ;; `org-element--object-regexp' and `org-element--object-lex', add the ;; new type in `org-element-all-objects', and possibly add ;; restrictions in `org-element-object-restrictions'. @@ -2991,7 +3296,7 @@ Assume point is at first MARK." `(seq (or line-start (any space ?- ?\( ?' ?\" ?\{)) ,mark (not space))))) - (when (looking-at opening-re) + (when (looking-at-p opening-re) (goto-char (1+ origin)) (let ((closing-re (rx-to-string @@ -3006,26 +3311,28 @@ Assume point is at first MARK." (let* ((post-blank (skip-chars-forward " \t")) (contents-begin (1+ origin)) (contents-end (1- closing))) - (list type - (append - (list :begin origin - :end (point) - :post-blank post-blank) - (if (memq type '(code verbatim)) - (list :value - (and (memq type '(code verbatim)) - (buffer-substring - contents-begin contents-end))) - (list :contents-begin contents-begin - :contents-end contents-end))))))))))))) + (org-element-create + type + (append + (list :begin origin + :end (point) + :post-blank post-blank) + (if (memq type '(code verbatim)) + (list :value + (and (memq type '(code verbatim)) + (org-element-deferred-create + t #'org-element--substring + (- contents-begin origin) + (- contents-end origin)))) + (list :contents-begin contents-begin + :contents-end contents-end))))))))))))) (defun org-element-bold-parser () "Parse bold object at point, if any. -When at a bold object, return a list whose car is `bold' and cdr -is a plist with `:begin', `:end', `:contents-begin' and -`:contents-end' and `:post-blank' keywords. Otherwise, return -nil. +When at a bold object, return a new syntax node `bold' type containing +`:begin', `:end', `:contents-begin', `:contents-end', and +`:post-blank' properties. Otherwise, return nil. Assume point is at the first star marker." (org-element--parse-generic-emphasis "*" 'bold)) @@ -3041,16 +3348,17 @@ CONTENTS is the contents of the object." (defun org-element-citation-parser () "Parse citation object at point, if any. -When at a citation object, return a list whose car is `citation' -and cdr is a plist with `:style', `:prefix', `:suffix', `:begin', -`:end', `:contents-begin', `:contents-end', and `:post-blank' -keywords. Otherwise, return nil. +When at a citation object, return a new syntax node of `citation' type +containing `:style', `:prefix', `:suffix', `:begin', `:end', +`:contents-begin', `:contents-end', and `:post-blank' properties. +Otherwise, return nil. Assume point is at the beginning of the citation." (when (looking-at org-element-citation-prefix-re) (let* ((begin (point)) (style (and (match-end 1) - (match-string-no-properties 1))) + (org-element--get-cached-string + (match-string-no-properties 1)))) ;; Ignore blanks between cite type and prefix or key. (start (match-end 0)) (closing (with-syntax-table org-element--pair-square-table @@ -3062,13 +3370,17 @@ Assume point is at the beginning of the citation." (let ((first-key-end (match-end 0)) (types (org-element-restriction 'citation-reference)) (cite - (list 'citation - (list :style style - :begin begin - :post-blank (progn - (goto-char closing) - (skip-chars-forward " \t")) - :end (point))))) + (org-element-create + 'citation + (list :style style + :begin begin + :post-blank (progn + (goto-char closing) + (skip-chars-forward " \t")) + :end (point) + :secondary (alist-get + 'citation + org-element-secondary-value-alist))))) ;; `:contents-begin' depends on the presence of ;; a non-empty common prefix. (goto-char first-key-end) @@ -3118,15 +3430,16 @@ CONTENTS is the contents of the object, as a string." (defun org-element-citation-reference-parser () "Parse citation reference object at point, if any. -When at a reference, return a list whose car is -`citation-reference', and cdr is a plist with `:key', -`:prefix', `:suffix', `:begin', `:end', and `:post-blank' keywords. +When at a reference, return a new syntax node of `citation-reference' +type containing `:key', `:prefix', `:suffix', `:begin', `:end', and +`:post-blank' properties. Assume point is at the beginning of the reference." (save-excursion (let ((begin (point))) (when (re-search-forward org-element-citation-key-re nil t) - (let* ((key (match-string-no-properties 1)) + (let* ((key (org-element--get-cached-string + (match-string-no-properties 1))) (key-start (match-beginning 0)) (key-end (match-end 0)) (separator (search-forward ";" nil t)) @@ -3134,11 +3447,15 @@ Assume point is at the beginning of the reference." (suffix-end (if separator (1- end) end)) (types (org-element-restriction 'citation-reference)) (reference - (list 'citation-reference - (list :key key - :begin begin - :end end - :post-blank 0)))) + (org-element-create + 'citation-reference + (list :key key + :begin begin + :end end + :post-blank 0 + :secondary (alist-get + 'citation-reference + org-element-secondary-value-alist))))) (when (< begin key-start) (org-element-put-property reference :prefix @@ -3164,9 +3481,9 @@ Assume point is at the beginning of the reference." (defun org-element-code-parser () "Parse code object at point, if any. -When at a code object, return a list whose car is `code' and cdr -is a plist with `:value', `:begin', `:end' and `:post-blank' -keywords. Otherwise, return nil. +When at a code object, return a new syntax node of `code' type +containing `:value', `:begin', `:end' and `:post-blank' properties. +Otherwise, return nil. Assume point is at the first tilde marker." (org-element--parse-generic-emphasis "~" 'code)) @@ -3181,14 +3498,26 @@ Assume point is at the first tilde marker." (defun org-element-entity-parser () "Parse entity at point, if any. -When at an entity, return a list whose car is `entity' and cdr -a plist with `:begin', `:end', `:latex', `:latex-math-p', -`:html', `:latin1', `:utf-8', `:ascii', `:use-brackets-p' and -`:post-blank' as keywords. Otherwise, return nil. +When at an entity, return a new syntax node of `entity' type +containing `:begin', `:end', `:latex', `:latex-math-p', `:html', +`:latin1', `:utf-8', `:ascii', `:use-brackets-p' and `:post-blank' as +properties. Otherwise, return nil. Assume point is at the beginning of the entity." (catch 'no-object - (when (looking-at "\\\\\\(?:\\(?1:_ +\\)\\|\\(?1:there4\\|sup[123]\\|frac[13][24]\\|[a-zA-Z]+\\)\\(?2:$\\|{}\\|[^[:alpha:]]\\)\\)") + (when (looking-at + (rx "\\" + (or + ;; Special case: whitespace entities are matched by + ;; name only. + (group-n 1 (seq "_" (1+ " "))) + (seq + (group-n 1 + (or "there4" + (seq "sup" (in "123")) + (seq "frac" (in "13") (in "24")) + (1+ (in "a-zA-Z")))) + (group-n 2 (or eol "{}" (not letter))))))) (save-excursion (let* ((value (or (org-entity-get (match-string 1)) (throw 'no-object nil))) @@ -3198,18 +3527,19 @@ Assume point is at the beginning of the entity." (when bracketsp (forward-char 2)) (skip-chars-forward " \t"))) (end (point))) - (list 'entity - (list :name (car value) - :latex (nth 1 value) - :latex-math-p (nth 2 value) - :html (nth 3 value) - :ascii (nth 4 value) - :latin1 (nth 5 value) - :utf-8 (nth 6 value) - :begin begin - :end end - :use-brackets-p bracketsp - :post-blank post-blank))))))) + (org-element-create + 'entity + (list :name (car value) + :latex (nth 1 value) + :latex-math-p (nth 2 value) + :html (nth 3 value) + :ascii (nth 4 value) + :latin1 (nth 5 value) + :utf-8 (nth 6 value) + :begin begin + :end end + :use-brackets-p bracketsp + :post-blank post-blank))))))) (defun org-element-entity-interpreter (entity _) "Interpret ENTITY object as Org syntax." @@ -3223,32 +3553,37 @@ Assume point is at the beginning of the entity." (defun org-element-export-snippet-parser () "Parse export snippet at point. -When at an export snippet, return a list whose car is -`export-snippet' and cdr a plist with `:begin', `:end', -`:back-end', `:value' and `:post-blank' as keywords. Otherwise, -return nil. +When at an export snippet, return a new syntax node of +`export-snippet' type containing `:begin', `:end', `:back-end', +`:value' and `:post-blank' as properties. Otherwise, return nil. Assume point is at the beginning of the snippet." (save-excursion - (let (contents-end) - (when (and (looking-at "@@\\([-A-Za-z0-9]+\\):") - (setq contents-end - (save-match-data (goto-char (match-end 0)) - (when - (re-search-forward "@@" nil t) - (match-beginning 0))))) - (let* ((begin (match-beginning 0)) - (back-end (match-string-no-properties 1)) - (value (buffer-substring-no-properties - (match-end 0) contents-end)) - (post-blank (skip-chars-forward " \t")) - (end (point))) - (list 'export-snippet - (list :back-end back-end - :value value - :begin begin - :end end - :post-blank post-blank))))))) + (when (looking-at "@@\\([-A-Za-z0-9]+\\):") + (goto-char (match-end 0)) + (let* ((begin (match-beginning 0)) + (contents-begin (match-end 0)) + (backend (org-element--get-cached-string + (match-string-no-properties 1))) + (contents-end + (when (re-search-forward "@@" nil t) + (match-beginning 0))) + (value + (when contents-end + (org-element-deferred-create + t #'org-element--substring + (- contents-begin begin) + (- contents-end begin)))) + (post-blank (skip-chars-forward " \t")) + (end (point))) + (when contents-end ; No match when no trailing "@@". + (org-element-create + 'export-snippet + (list :back-end backend + :value value + :begin begin + :end end + :post-blank post-blank))))))) (defun org-element-export-snippet-interpreter (export-snippet _) "Interpret EXPORT-SNIPPET object as Org syntax." @@ -3262,31 +3597,33 @@ Assume point is at the beginning of the snippet." (defun org-element-footnote-reference-parser () "Parse footnote reference at point, if any. -When at a footnote reference, return a list whose car is -`footnote-reference' and cdr a plist with `:label', `:type', -`:begin', `:end', `:contents-begin', `:contents-end' and -`:post-blank' as keywords. Otherwise, return nil." +When at a footnote reference, return a new syntax node of +`footnote-reference' type containing `:label', `:type', `:begin', +`:end', `:contents-begin', `:contents-end' and `:post-blank' as +properties. Otherwise, return nil." (when (looking-at org-footnote-re) (let ((closing (with-syntax-table org-element--pair-square-table (ignore-errors (scan-lists (point) 1 0))))) (when closing (save-excursion (let* ((begin (point)) - (label (match-string-no-properties 1)) + (label (org-element--get-cached-string + (match-string-no-properties 1))) (inner-begin (match-end 0)) (inner-end (1- closing)) (type (if (match-end 2) 'inline 'standard)) (post-blank (progn (goto-char closing) (skip-chars-forward " \t"))) (end (point))) - (list 'footnote-reference - (list :label label - :type type - :begin begin - :end end - :contents-begin (and (eq type 'inline) inner-begin) - :contents-end (and (eq type 'inline) inner-end) - :post-blank post-blank)))))))) + (org-element-create + 'footnote-reference + (list :label label + :type type + :begin begin + :end end + :contents-begin (and (eq type 'inline) inner-begin) + :contents-end (and (eq type 'inline) inner-end) + :post-blank post-blank)))))))) (defun org-element-footnote-reference-interpreter (footnote-reference contents) "Interpret FOOTNOTE-REFERENCE object as Org syntax. @@ -3301,10 +3638,10 @@ CONTENTS is its definition, when inline, or nil." (defun org-element-inline-babel-call-parser () "Parse inline babel call at point, if any. -When at an inline babel call, return a list whose car is -`inline-babel-call' and cdr a plist with `:call', -`:inside-header', `:arguments', `:end-header', `:begin', `:end', -`:value' and `:post-blank' as keywords. Otherwise, return nil. +When at an inline babel call, return a new syntax node of +`inline-babel-call' type containing `:call', `:inside-header', +`:arguments', `:end-header', `:begin', `:end', `:value' and +`:post-blank' as properties. Otherwise, return nil. Assume point is at the beginning of the babel call." (save-excursion @@ -3313,7 +3650,8 @@ Assume point is at the beginning of the babel call." (looking-at "\\. Unlike to @@ -3575,6 +3927,7 @@ Assume point is at the beginning of the link." ((looking-at org-link-angle-re) (setq format 'angle) (setq type (match-string-no-properties 1)) + (setq explicit-type-p t) (setq link-end (match-end 0)) (setq raw-link (buffer-substring-no-properties @@ -3591,10 +3944,10 @@ Assume point is at the beginning of the link." ;; Special "file"-type link processing. Extract opening ;; application and search option, if any. Also normalize URI. (when (string-match "\\`file\\(?:\\+\\(.+\\)\\)?\\'" type) - (setq application (match-string 1 type)) + (setq application (match-string-no-properties 1 type)) (setq type "file") (when (string-match "::\\(.*\\)\\'" path) - (setq search-option (match-string 1 path)) + (setq search-option (match-string-no-properties 1 path)) (setq path (replace-match "" nil nil path))) (setq path (replace-regexp-in-string "\\`///*\\(.:\\)?/" "\\1/" path))) ;; Translate link, if `org-link-translation-function' is set. @@ -3602,19 +3955,22 @@ Assume point is at the beginning of the link." (funcall org-link-translation-function type path)))) (when trans (setq type (car trans)) + (setq explicit-type-p t) (setq path (cdr trans)))) - (list 'link - (list :type type - :path path - :format format - :raw-link (or raw-link path) - :application application - :search-option search-option - :begin begin - :end end - :contents-begin contents-begin - :contents-end contents-end - :post-blank post-blank))))) + (org-element-create + 'link + (list :type (org-element--get-cached-string type) + :type-explicit-p explicit-type-p + :path path + :format format + :raw-link (or raw-link path) + :application application + :search-option search-option + :begin begin + :end end + :contents-begin contents-begin + :contents-end contents-end + :post-blank post-blank))))) (defun org-element-link-interpreter (link contents) "Interpret LINK object as Org syntax. @@ -3648,8 +4004,11 @@ CONTENTS is the contents of the object, or nil." ("custom-id" (concat "#" path)) ("file" (let ((app (org-element-property :application link)) - (opt (org-element-property :search-option link))) - (concat type (and app (concat "+" app)) ":" + (opt (org-element-property :search-option link)) + (type-explicit-p (org-element-property :type-explicit-p link))) + (concat (and type-explicit-p type) + (and type-explicit-p app (concat "+" app)) + (and type-explicit-p ":") path (and opt (concat "::" opt))))) ("fuzzy" path) @@ -3661,15 +4020,16 @@ CONTENTS is the contents of the object, or nil." (defun org-element-macro-parser () "Parse macro at point, if any. -When at a macro, return a list whose car is `macro' and cdr -a plist with `:key', `:args', `:begin', `:end', `:value' and -`:post-blank' as keywords. Otherwise, return nil. +When at a macro, return a new syntax node of `macro' type containing +`:key', `:args', `:begin', `:end', `:value' and `:post-blank' as +properties. Otherwise, return nil. Assume point is at the macro." (save-excursion - (when (looking-at "{{{\\([a-zA-Z][-a-zA-Z0-9_]*\\)\\((\\([^\000]*?\\))\\)?}}}") + (when (looking-at "{{{\\([a-zA-Z][-a-zA-Z0-9_]*\\)\\((\\(\\(?:.\\|\n\\)*?\\))\\)?}}}") (let ((begin (point)) - (key (downcase (match-string-no-properties 1))) + (key (org-element--get-cached-string + (downcase (match-string-no-properties 1)))) (value (match-string-no-properties 0)) (post-blank (progn (goto-char (match-end 0)) (skip-chars-forward " \t"))) @@ -3679,13 +4039,14 @@ Assume point is at the macro." (a (org-macro-extract-arguments (replace-regexp-in-string "[ \t\r\n]+" " " (org-trim a))))))) - (list 'macro - (list :key key - :value value - :args args - :begin begin - :end end - :post-blank post-blank)))))) + (org-element-create + 'macro + (list :key key + :value value + :args args + :begin begin + :end end + :post-blank post-blank)))))) (defun org-element-macro-interpreter (macro _) "Interpret MACRO object as Org syntax." @@ -3701,10 +4062,9 @@ Assume point is at the macro." (defun org-element-radio-target-parser () "Parse radio target at point, if any. -When at a radio target, return a list whose car is `radio-target' -and cdr a plist with `:begin', `:end', `:contents-begin', -`:contents-end', `:value' and `:post-blank' as keywords. -Otherwise, return nil. +When at a radio target, return a new syntax node of `radio-target' +type containing `:begin', `:end', `:contents-begin', `:contents-end', +`:value' and `:post-blank' as properties. Otherwise, return nil. Assume point is at the radio target." (save-excursion @@ -3716,13 +4076,14 @@ Assume point is at the radio target." (post-blank (progn (goto-char (match-end 0)) (skip-chars-forward " \t"))) (end (point))) - (list 'radio-target - (list :begin begin - :end end - :contents-begin contents-begin - :contents-end contents-end - :post-blank post-blank - :value value)))))) + (org-element-create + 'radio-target + (list :begin begin + :end end + :contents-begin contents-begin + :contents-end contents-end + :post-blank post-blank + :value value)))))) (defun org-element-radio-target-interpreter (_ contents) "Interpret target object as Org syntax. @@ -3735,9 +4096,9 @@ CONTENTS is the contents of the object." (defun org-element-statistics-cookie-parser () "Parse statistics cookie at point, if any. -When at a statistics cookie, return a list whose car is -`statistics-cookie', and cdr a plist with `:begin', `:end', -`:value' and `:post-blank' keywords. Otherwise, return nil. +When at a statistics cookie, return a new syntax node of +`statistics-cookie' type containing `:begin', `:end', `:value' and +`:post-blank' properties. Otherwise, return nil. Assume point is at the beginning of the statistics-cookie." (save-excursion @@ -3748,11 +4109,12 @@ Assume point is at the beginning of the statistics-cookie." (post-blank (progn (goto-char (match-end 0)) (skip-chars-forward " \t"))) (end (point))) - (list 'statistics-cookie - (list :begin begin - :end end - :value value - :post-blank post-blank)))))) + (org-element-create + 'statistics-cookie + (list :begin begin + :end end + :value value + :post-blank post-blank)))))) (defun org-element-statistics-cookie-interpreter (statistics-cookie _) "Interpret STATISTICS-COOKIE object as Org syntax." @@ -3764,10 +4126,10 @@ Assume point is at the beginning of the statistics-cookie." (defun org-element-strike-through-parser () "Parse strike-through object at point, if any. -When at a strike-through object, return a list whose car is -`strike-through' and cdr is a plist with `:begin', `:end', -`:contents-begin' and `:contents-end' and `:post-blank' keywords. -Otherwise, return nil. +When at a strike-through object, return a new syntax node of +`strike-through' type containing `:begin', `:end', `:contents-begin' +and `:contents-end' and `:post-blank' properties. Otherwise, return +nil. Assume point is at the first plus sign marker." (org-element--parse-generic-emphasis "+" 'strike-through)) @@ -3783,30 +4145,32 @@ CONTENTS is the contents of the object." (defun org-element-subscript-parser () "Parse subscript at point, if any. -When at a subscript object, return a list whose car is -`subscript' and cdr a plist with `:begin', `:end', -`:contents-begin', `:contents-end', `:use-brackets-p' and -`:post-blank' as keywords. Otherwise, return nil. +When at a subscript object, return a new syntax node of `subscript' +type containing `:begin', `:end', `:contents-begin', `:contents-end', +`:use-brackets-p' and `:post-blank' as properties. Otherwise, return +nil. Assume point is at the underscore." (save-excursion - (unless (bolp) (backward-char)) - (when (looking-at org-match-substring-regexp) - (let ((bracketsp (match-beginning 4)) - (begin (match-beginning 2)) - (contents-begin (or (match-beginning 4) - (match-beginning 3))) - (contents-end (or (match-end 4) (match-end 3))) - (post-blank (progn (goto-char (match-end 0)) - (skip-chars-forward " \t"))) - (end (point))) - (list 'subscript - (list :begin begin - :end end - :use-brackets-p bracketsp - :contents-begin contents-begin - :contents-end contents-end - :post-blank post-blank)))))) + (unless (bolp) + (backward-char) + (when (looking-at org-match-substring-regexp) + (let ((bracketsp (if (match-beginning 4) t nil)) + (begin (match-beginning 2)) + (contents-begin (or (match-beginning 4) + (match-beginning 3))) + (contents-end (or (match-end 4) (match-end 3))) + (post-blank (progn (goto-char (match-end 0)) + (skip-chars-forward " \t"))) + (end (point))) + (org-element-create + 'subscript + (list :begin begin + :end end + :use-brackets-p bracketsp + :contents-begin contents-begin + :contents-end contents-end + :post-blank post-blank))))))) (defun org-element-subscript-interpreter (subscript contents) "Interpret SUBSCRIPT object as Org syntax. @@ -3821,16 +4185,16 @@ CONTENTS is the contents of the object." (defun org-element-superscript-parser () "Parse superscript at point, if any. -When at a superscript object, return a list whose car is -`superscript' and cdr a plist with `:begin', `:end', -`:contents-begin', `:contents-end', `:use-brackets-p' and -`:post-blank' as keywords. Otherwise, return nil. +When at a superscript object, return a new syntax node of +`superscript' type containing `:begin', `:end', `:contents-begin', +`:contents-end', `:use-brackets-p' and `:post-blank' as properties. +Otherwise, return nil. Assume point is at the caret." (save-excursion (unless (bolp) (backward-char)) (when (looking-at org-match-substring-regexp) - (let ((bracketsp (match-beginning 4)) + (let ((bracketsp (if (match-beginning 4) t nil)) (begin (match-beginning 2)) (contents-begin (or (match-beginning 4) (match-beginning 3))) @@ -3838,13 +4202,14 @@ Assume point is at the caret." (post-blank (progn (goto-char (match-end 0)) (skip-chars-forward " \t"))) (end (point))) - (list 'superscript - (list :begin begin - :end end - :use-brackets-p bracketsp - :contents-begin contents-begin - :contents-end contents-end - :post-blank post-blank)))))) + (org-element-create + 'superscript + (list :begin begin + :end end + :use-brackets-p bracketsp + :contents-begin contents-begin + :contents-end contents-end + :post-blank post-blank)))))) (defun org-element-superscript-interpreter (superscript contents) "Interpret SUPERSCRIPT object as Org syntax. @@ -3858,20 +4223,21 @@ CONTENTS is the contents of the object." (defun org-element-table-cell-parser () "Parse table cell at point. -Return a list whose car is `table-cell' and cdr is a plist -containing `:begin', `:end', `:contents-begin', `:contents-end' -and `:post-blank' keywords." +Return a new syntax node of `table-cell' type containing `:begin', +`:end', `:contents-begin', `:contents-end' and `:post-blank' +properties." (looking-at "[ \t]*\\(.*?\\)[ \t]*\\(?:|\\|$\\)") (let* ((begin (match-beginning 0)) (end (match-end 0)) (contents-begin (match-beginning 1)) (contents-end (match-end 1))) - (list 'table-cell - (list :begin begin - :end end - :contents-begin contents-begin - :contents-end contents-end - :post-blank 0)))) + (org-element-create + 'table-cell + (list :begin begin + :end end + :contents-begin contents-begin + :contents-end contents-end + :post-blank 0)))) (defun org-element-table-cell-interpreter (_ contents) "Interpret table-cell element as Org syntax. @@ -3884,9 +4250,9 @@ CONTENTS is the contents of the cell, or nil." (defun org-element-target-parser () "Parse target at point, if any. -When at a target, return a list whose car is `target' and cdr -a plist with `:begin', `:end', `:value' and `:post-blank' as -keywords. Otherwise, return nil. +When at a target, return a new syntax node of `target' type containing +`:begin', `:end', `:value' and `:post-blank' as properties. +Otherwise, return nil. Assume point is at the target." (save-excursion @@ -3896,11 +4262,12 @@ Assume point is at the target." (post-blank (progn (goto-char (match-end 0)) (skip-chars-forward " \t"))) (end (point))) - (list 'target - (list :begin begin - :end end - :value value - :post-blank post-blank)))))) + (org-element-create + 'target + (list :begin begin + :end end + :value value + :post-blank post-blank)))))) (defun org-element-target-interpreter (target _) "Interpret TARGET object as Org syntax." @@ -3914,20 +4281,26 @@ Assume point is at the target." "\\|" "\\(?:<[0-9]+-[0-9]+-[0-9]+[^>\n]+?\\+[0-9]+[dwmy]>\\)" "\\|" - "\\(?:<%%\\(?:([^>\n]+)\\)>\\)") + "\\(?:<%%\\(?:([^>\n]+)\\)\\([^\n>]*\\)>\\)") "Regexp matching any timestamp type object.") +(defconst org-element--timestamp-raw-value-regexp + (concat "\\([<[]\\(%%\\)?.*?\\)[]>]\\(?:--\\(" + org-ts-regexp-both + "\\)\\)?") + "Regexp for matching raw value of a timestamp.") + (defun org-element-timestamp-parser () "Parse time stamp at point, if any. -When at a time stamp, return a list whose car is `timestamp', and -cdr a plist with `:type', `:raw-value', `:year-start', +When at a time stamp, return a new syntax node of `timestamp' type +containing `:type', `:range-type', `:raw-value', `:year-start', `:month-start', `:day-start', `:hour-start', `:minute-start', -`:year-end', `:month-end', `:day-end', `:hour-end', -`:minute-end', `:repeater-type', `:repeater-value', -`:repeater-unit', `:warning-type', `:warning-value', -`:warning-unit', `:begin', `:end' and `:post-blank' keywords. -Otherwise, return nil. +`:year-end', `:month-end', `:day-end', `:hour-end', `:minute-end', +`:repeater-type', `:repeater-value', `:repeater-unit', +`:repeater-deadline-value', `:repeater-deadline-unit', `:warning-type', +`:warning-value', `:warning-unit', `:diary-sexp', `:begin', `:end' and +`:post-blank' properties. Otherwise, return nil. Assume point is at the beginning of the timestamp." (when (looking-at-p org-element--timestamp-regexp) @@ -3936,42 +4309,72 @@ Assume point is at the beginning of the timestamp." (activep (eq (char-after) ?<)) (raw-value (progn - (looking-at (concat "\\([<[]\\(%%\\)?.*?\\)[]>]\\(?:--\\(" - org-ts-regexp-both - "\\)\\)?")) + (looking-at org-element--timestamp-raw-value-regexp) (match-string-no-properties 0))) - (date-start (match-string-no-properties 1)) - (date-end (match-string 3)) (diaryp (match-beginning 2)) + diary-sexp + (date-start (if diaryp + ;; Only consider part after sexp for + ;; diary timestamps. + (save-match-data + (looking-at org-element--timestamp-regexp) + (setq diary-sexp + (buffer-substring-no-properties + (+ 3 (match-beginning 0)) + (match-beginning 2))) + (match-string 2)) + (match-string-no-properties 1))) + (date-end (match-string-no-properties 3)) (post-blank (progn (goto-char (match-end 0)) (skip-chars-forward " \t"))) (end (point)) (time-range - (and (not diaryp) - (string-match - "[012]?[0-9]:[0-5][0-9]\\(-\\([012]?[0-9]\\):\\([0-5][0-9]\\)\\)" - date-start) - (cons (string-to-number (match-string 2 date-start)) - (string-to-number (match-string 3 date-start))))) + (when (string-match + "[012]?[0-9]:[0-5][0-9]\\(-\\([012]?[0-9]\\):\\([0-5][0-9]\\)\\)" + date-start) + (cons (string-to-number (match-string 2 date-start)) + (string-to-number (match-string 3 date-start))))) (type (cond (diaryp 'diary) ((and activep (or date-end time-range)) 'active-range) (activep 'active) ((or date-end time-range) 'inactive-range) (t 'inactive))) - (repeater-props - (and (not diaryp) - (string-match "\\([.+]?\\+\\)\\([0-9]+\\)\\([hdwmy]\\)" - raw-value) - (list - :repeater-type - (let ((type (match-string 1 raw-value))) - (cond ((equal "++" type) 'catch-up) - ((equal ".+" type) 'restart) - (t 'cumulate))) - :repeater-value (string-to-number (match-string 2 raw-value)) - :repeater-unit - (pcase (string-to-char (match-string 3 raw-value)) - (?h 'hour) (?d 'day) (?w 'week) (?m 'month) (_ 'year))))) + (range-type (cond + (date-end 'daterange) + (time-range 'timerange) + (t nil))) + (repeater-props + (and (not diaryp) + (string-match + (rx + (group-n 1 (or "+" "++" ".+")) + (group-n 2 (+ digit)) + (group-n 3 (any "hdwmy")) + (optional + "/" + (group-n 4 (+ digit)) + (group-n 5 (any "hdwmy")))) + raw-value) + (nconc + (list + :repeater-type + (let ((type (match-string 1 raw-value))) + (cond ((equal "++" type) 'catch-up) + ((equal ".+" type) 'restart) + (t 'cumulate))) + :repeater-value (string-to-number (match-string 2 raw-value)) + :repeater-unit + (pcase (string-to-char (match-string 3 raw-value)) + (?h 'hour) (?d 'day) (?w 'week) (?m 'month) (_ 'year))) + + (let ((repeater-deadline-value (match-string 4 raw-value)) + (repeater-deadline-unit (match-string 5 raw-value))) + (when (and repeater-deadline-value repeater-deadline-unit) + (list + :repeater-deadline-value (string-to-number repeater-deadline-value) + :repeater-deadline-unit + (pcase (string-to-char repeater-deadline-unit) + (?h 'hour) (?d 'day) (?w 'week) (?m 'month) (_ 'year)))))))) (warning-props (and (not diaryp) (string-match "\\(-\\)?-\\([0-9]+\\)\\([hdwmy]\\)" raw-value) @@ -3991,7 +4394,7 @@ Assume point is at the beginning of the timestamp." day-start (nth 3 date) hour-start (nth 2 date) minute-start (nth 1 date)))) - ;; Compute date-end. It can be provided directly in time-stamp, + ;; Compute date-end. It can be provided directly in timestamp, ;; or extracted from time range. Otherwise, it defaults to the ;; same values as date-start. (unless diaryp @@ -4001,129 +4404,181 @@ Assume point is at the beginning of the timestamp." day-end (or (nth 3 date) day-start) hour-end (or (nth 2 date) (car time-range) hour-start) minute-end (or (nth 1 date) (cdr time-range) minute-start)))) - (list 'timestamp - (nconc (list :type type - :raw-value raw-value - :year-start year-start - :month-start month-start - :day-start day-start - :hour-start hour-start - :minute-start minute-start - :year-end year-end - :month-end month-end - :day-end day-end - :hour-end hour-end - :minute-end minute-end - :begin begin - :end end - :post-blank post-blank) - repeater-props - warning-props)))))) + ;; Diary timestamp with time. + (when (and diaryp + (string-match "\\([012]?[0-9]\\):\\([0-5][0-9]\\)\\(-\\([012]?[0-9]\\):\\([0-5][0-9]\\)\\)?" date-start)) + (setq hour-start (match-string 1 date-start) + minute-start (match-string 2 date-start) + hour-end (match-string 4 date-start) + minute-end (match-string 5 date-start)) + (when hour-start (setq hour-start (string-to-number hour-start))) + (when minute-start (setq minute-start (string-to-number minute-start))) + (when hour-end (setq hour-end (string-to-number hour-end))) + (when minute-end (setq minute-end (string-to-number minute-end)))) + (org-element-create + 'timestamp + (nconc (list :type type + :range-type range-type + :raw-value raw-value + :year-start year-start + :month-start month-start + :day-start day-start + :hour-start hour-start + :minute-start minute-start + :year-end year-end + :month-end month-end + :day-end day-end + :hour-end hour-end + :minute-end minute-end + :begin begin + :end end + :post-blank post-blank) + (and diary-sexp (list :diary-sexp diary-sexp)) + repeater-props + warning-props)))))) (defun org-element-timestamp-interpreter (timestamp _) "Interpret TIMESTAMP object as Org syntax." - (let* ((repeat-string - (concat - (pcase (org-element-property :repeater-type timestamp) - (`cumulate "+") (`catch-up "++") (`restart ".+")) - (let ((val (org-element-property :repeater-value timestamp))) - (and val (number-to-string val))) - (pcase (org-element-property :repeater-unit timestamp) - (`hour "h") (`day "d") (`week "w") (`month "m") (`year "y")))) - (warning-string - (concat - (pcase (org-element-property :warning-type timestamp) - (`first "--") (`all "-")) - (let ((val (org-element-property :warning-value timestamp))) - (and val (number-to-string val))) - (pcase (org-element-property :warning-unit timestamp) - (`hour "h") (`day "d") (`week "w") (`month "m") (`year "y")))) - (build-ts-string - ;; Build an Org timestamp string from TIME. ACTIVEP is - ;; non-nil when time stamp is active. If WITH-TIME-P is - ;; non-nil, add a time part. HOUR-END and MINUTE-END - ;; specify a time range in the timestamp. REPEAT-STRING is - ;; the repeater string, if any. - (lambda (time activep &optional with-time-p hour-end minute-end) - (let ((ts (format-time-string - (org-time-stamp-format with-time-p) - time))) - (when (and hour-end minute-end) - (string-match "[012]?[0-9]:[0-5][0-9]" ts) - (setq ts - (replace-match - (format "\\&-%02d:%02d" hour-end minute-end) - nil nil ts))) - (unless activep (setq ts (format "[%s]" (substring ts 1 -1)))) - (dolist (s (list repeat-string warning-string)) - (when (org-string-nw-p s) - (setq ts (concat (substring ts 0 -1) - " " - s - (substring ts -1))))) - ;; Return value. - ts))) - (type (org-element-property :type timestamp))) - (pcase type - ((or `active `inactive) - (let* ((minute-start (org-element-property :minute-start timestamp)) - (minute-end (org-element-property :minute-end timestamp)) - (hour-start (org-element-property :hour-start timestamp)) - (hour-end (org-element-property :hour-end timestamp)) - (time-range-p (and hour-start hour-end minute-start minute-end - (or (/= hour-start hour-end) - (/= minute-start minute-end))))) - (funcall - build-ts-string - (org-encode-time 0 - (or minute-start 0) - (or hour-start 0) - (org-element-property :day-start timestamp) - (org-element-property :month-start timestamp) - (org-element-property :year-start timestamp)) - (eq type 'active) - (and hour-start minute-start) - (and time-range-p hour-end) - (and time-range-p minute-end)))) - ((or `active-range `inactive-range) - (let ((minute-start (org-element-property :minute-start timestamp)) - (minute-end (org-element-property :minute-end timestamp)) - (hour-start (org-element-property :hour-start timestamp)) - (hour-end (org-element-property :hour-end timestamp))) - (concat - (funcall - build-ts-string (org-encode-time - 0 - (or minute-start 0) - (or hour-start 0) - (org-element-property :day-start timestamp) - (org-element-property :month-start timestamp) - (org-element-property :year-start timestamp)) - (eq type 'active-range) - (and hour-start minute-start)) - "--" - (funcall build-ts-string - (org-encode-time - 0 - (or minute-end 0) - (or hour-end 0) - (org-element-property :day-end timestamp) - (org-element-property :month-end timestamp) - (org-element-property :year-end timestamp)) - (eq type 'active-range) - (and hour-end minute-end))))) - (_ (org-element-property :raw-value timestamp))))) - - + (let((type (org-element-property :type timestamp))) + (let ((day-start (org-element-property :day-start timestamp)) + (month-start (org-element-property :month-start timestamp)) + (year-start (org-element-property :year-start timestamp))) + ;; Return nil when start date is not available. Could also + ;; throw an error, but the current behavior is historical. + (when (or (and day-start month-start year-start) + (eq type 'diary)) + (let* ((repeat-string + (concat + (pcase (org-element-property :repeater-type timestamp) + (`cumulate "+") (`catch-up "++") (`restart ".+")) + (let ((val (org-element-property :repeater-value timestamp))) + (and val (number-to-string val))) + (pcase (org-element-property :repeater-unit timestamp) + (`hour "h") (`day "d") (`week "w") (`month "m") (`year "y")) + (when-let* ((repeater-deadline-value + (org-element-property :repeater-deadline-value timestamp)) + (repeater-deadline-unit + (org-element-property :repeater-deadline-unit timestamp))) + (concat + "/" + (number-to-string repeater-deadline-value) + (pcase repeater-deadline-unit + (`hour "h") (`day "d") (`week "w") (`month "m") (`year "y")))))) + (range-type (org-element-property :range-type timestamp)) + (warning-string + (concat + (pcase (org-element-property :warning-type timestamp) + (`first "--") (`all "-")) + (let ((val (org-element-property :warning-value timestamp))) + (and val (number-to-string val))) + (pcase (org-element-property :warning-unit timestamp) + (`hour "h") (`day "d") (`week "w") (`month "m") (`year "y")))) + (hour-start (org-element-property :hour-start timestamp)) + (minute-start (org-element-property :minute-start timestamp)) + (brackets + (if (member + type + '(inactive inactive-range)) + (cons "[" "]") + ;; diary as well + (cons "<" ">"))) + (timestamp-end + (concat + (and (org-string-nw-p repeat-string) (concat " " repeat-string)) + (and (org-string-nw-p warning-string) (concat " " warning-string)) + (cdr brackets)))) + (concat + ;; Opening bracket: [ or < + (car brackets) + ;; Starting date/time: YYYY-MM-DD DAY[ HH:MM] + (if (eq type 'diary) + (concat + "%%" + (org-element-property :diary-sexp timestamp) + (when (and minute-start hour-start) + (format " %02d:%02d" hour-start minute-start))) + (format-time-string + ;; `org-time-stamp-formats'. + (org-time-stamp-format + ;; Ignore time unless both HH:MM are available. + ;; Ignore means (car org-timestamp-formats). + (and minute-start hour-start) + 'no-brackets) + (org-encode-time + 0 (or minute-start 0) (or hour-start 0) + day-start month-start year-start))) + ;; Range: -HH:MM or TIMESTAMP-END--[YYYY-MM-DD DAY HH:MM] + (let ((hour-end (org-element-property :hour-end timestamp)) + (minute-end (org-element-property :minute-end timestamp))) + (pcase type + ((or `active `inactive) + ;; `org-element-timestamp-parser' uses this type + ;; when no time/date range is provided. So, + ;; should normally return nil in this clause. + (pcase range-type + (`nil + ;; `org-element-timestamp-parser' assigns end + ;; times for `active'/`inactive' TYPE if start + ;; time is not nil. But manually built + ;; timestamps may not contain end times, so + ;; check for end times anyway. + (when (and hour-start hour-end minute-start minute-end + (or (/= hour-start hour-end) + (/= minute-start minute-end))) + ;; Could also throw an error. Return range + ;; timestamp nevertheless to preserve + ;; historical behavior. + (format "-%02d:%02d" hour-end minute-end))) + ((or `timerange `daterange) + (error "`:range-type' must be `nil' for `active'/`inactive' type")))) + ;; Range must be present. + ((or `active-range `inactive-range + (and `diary (guard (eq 'timerange range-type)))) + (pcase range-type + ;; End time: -HH:MM. + ;; Fall back to start time if end time is not defined (arbitrary historical choice). + ;; Error will be thrown if both end and begin time is not defined. + (`timerange (format "-%02d:%02d" (or hour-end hour-start) (or minute-end minute-start))) + ;; End date: TIMESTAMP-END--[YYYY-MM-DD DAY HH:MM + ((or `daterange + ;; Should never happen in the output of `org-element-timestamp-parser'. + ;; Treat as an equivalent of `daterange' arbitrarily. + `nil) + (concat + ;; repeater + warning + closing > or ] + ;; This info is duplicated in date ranges. + timestamp-end + "--" (car brackets) + (format-time-string + ;; `org-time-stamp-formats'. + (org-time-stamp-format + ;; Ignore time unless both HH:MM are available. + ;; Ignore means (car org-timestamp-formats). + (and minute-end hour-end) + 'no-brackets) + (org-encode-time + ;; Closing HH:MM missing is a valid scenario. + 0 (or minute-end 0) (or hour-end 0) + ;; YEAR/MONTH/DAY-END will always be present + ;; for `daterange' range-type, as parsed by + ;; `org-element-timestamp-parser'. + ;; For manually constructed timestamp + ;; object, arbitrarily fall back to starting + ;; date. + (or (org-element-property :day-end timestamp) day-start) + (or (org-element-property :month-end timestamp) month-start) + (or (org-element-property :year-end timestamp) year-start))))))))) + ;; repeater + warning + closing > or ] + ;; This info is duplicated in date ranges. + timestamp-end)))))) ;;;; Underline (defun org-element-underline-parser () "Parse underline object at point, if any. -When at an underline object, return a list whose car is -`underline' and cdr is a plist with `:begin', `:end', -`:contents-begin' and `:contents-end' and `:post-blank' keywords. -Otherwise, return nil. +When at an underline object, return a new syntax node of `underline' +type containing `:begin', `:end', `:contents-begin' and +`:contents-end' and `:post-blank' properties. Otherwise, return nil. Assume point is at the first underscore marker." (org-element--parse-generic-emphasis "_" 'underline)) @@ -4139,9 +4594,9 @@ CONTENTS is the contents of the object." (defun org-element-verbatim-parser () "Parse verbatim object at point, if any. -When at a verbatim object, return a list whose car is `verbatim' -and cdr is a plist with `:value', `:begin', `:end' and -`:post-blank' keywords. Otherwise, return nil. +When at a verbatim object, return a new syntax node of `verbatim' type +containing `:value', `:begin', `:end' and `:post-blank' properties. +Otherwise, return nil. Assume point is at the first equal sign marker." (org-element--parse-generic-emphasis "=" 'verbatim)) @@ -4158,8 +4613,28 @@ Assume point is at the first equal sign marker." ;; It returns the Lisp representation of the element starting at ;; point. +(defconst org-element--current-element-re + (rx-to-string + `(or + (group-n 1 (regexp ,org-element--latex-begin-environment-nogroup)) + (group-n 2 (regexp ,org-element-drawer-re-nogroup)) + (group-n 3 (regexp "[ \t]*:\\( \\|$\\)")) + (group-n 7 (regexp ,org-element-dynamic-block-open-re-nogroup)) + (seq (group-n 4 (regexp "[ \t]*#\\+")) + (or + (seq "BEGIN_" (group-n 5 (1+ (not space)))) + (group-n 6 "CALL:") + (group-n 8 (1+ (not space)) ":"))) + (group-n 9 (regexp ,org-footnote-definition-re)) + (group-n 10 (regexp "[ \t]*-----+[ \t]*$")) + (group-n 11 "%%("))) + "Bulk regexp matching multiple elements in a single regexp. +This is a bit more efficient compared to invoking regexp search +multiple times.") + +(defvar org-inlinetask-min-level); Declared in org-inlinetask.el (defvar org-element--cache-sync-requests); Declared later -(defun org-element--current-element (limit &optional granularity mode structure add-to-cache) +(defsubst org-element--current-element (limit &optional granularity mode structure) "Parse the element starting at point. Return value is a list like (TYPE PROPS) where TYPE is the type @@ -4184,200 +4659,180 @@ Optional argument MODE, when non-nil, can be either If STRUCTURE isn't provided but MODE is set to `item', it will be computed. -Optional argument ADD-TO-CACHE, when non-nil, and when cache is active, -will also add current element to cache if it is not yet there. Use -this argument with care, as validity of the element in parse tree is -not checked. - This function assumes point is always at the beginning of the element it has to parse." - (let* ((element (and (not (buffer-narrowed-p)) - (org-element--cache-active-p) - (not org-element--cache-sync-requests) - (org-element--cache-find (point) t))) - (element (progn (while (and element - (not (and (eq (point) (org-element-property :begin element)) - (eq mode (org-element-property :mode element))))) - (setq element (org-element-property :parent element))) - element)) - (old-element element) - (element (when - (pcase (org-element-property :granularity element) - (`nil t) - (`object t) - (`element (not (memq granularity '(nil object)))) - (`greater-element (not (memq granularity '(nil object element)))) - (`headline (eq granularity 'headline))) - element))) - (if element - element - (save-excursion - (let ((case-fold-search t) - ;; Determine if parsing depth allows for secondary strings - ;; parsing. It only applies to elements referenced in - ;; `org-element-secondary-value-alist'. - (raw-secondary-p (and granularity (not (eq granularity 'object)))) - result) - (setq - result - (cond - ;; Item. - ((eq mode 'item) - (org-element-item-parser limit structure raw-secondary-p)) - ;; Table Row. - ((eq mode 'table-row) (org-element-table-row-parser limit)) - ;; Node Property. - ((eq mode 'node-property) (org-element-node-property-parser limit)) - ;; Headline. - ((org-with-limited-levels (looking-at-p org-outline-regexp-bol)) - (org-element-headline-parser limit raw-secondary-p)) - ;; Sections (must be checked after headline). - ((eq mode 'section) (org-element-section-parser limit)) - ((eq mode 'first-section) - (org-element-section-parser - (or (save-excursion (org-with-limited-levels (outline-next-heading))) - limit))) - ;; Comments. - ((looking-at "^[ \t]*#\\(?: \\|$\\)") - (org-element-comment-parser limit)) - ;; Planning. - ((and (eq mode 'planning) - (eq ?* (char-after (line-beginning-position 0))) - (looking-at org-element-planning-line-re)) - (org-element-planning-parser limit)) - ;; Property drawer. - ((and (pcase mode - (`planning (eq ?* (char-after (line-beginning-position 0)))) - ((or `property-drawer `top-comment) - (save-excursion - (beginning-of-line 0) - (not (looking-at "[[:blank:]]*$")))) - (_ nil)) - (looking-at org-property-drawer-re)) - (org-element-property-drawer-parser limit)) - ;; When not at bol, point is at the beginning of an item or - ;; a footnote definition: next item is always a paragraph. - ((not (bolp)) (org-element-paragraph-parser limit (list (point)))) - ;; Clock. - ((looking-at org-element-clock-line-re) - (org-element-clock-parser limit)) - ;; Inlinetask. - ((looking-at "^\\*+ ") - (org-element-inlinetask-parser limit raw-secondary-p)) - ;; From there, elements can have affiliated keywords. - (t (let ((affiliated (org-element--collect-affiliated-keywords - limit (memq granularity '(nil object))))) - (cond - ;; Jumping over affiliated keywords put point off-limits. - ;; Parse them as regular keywords. - ((and (cdr affiliated) (>= (point) limit)) - (goto-char (car affiliated)) - (org-element-keyword-parser limit nil)) - ;; LaTeX Environment. - ((looking-at org-element--latex-begin-environment) - (org-element-latex-environment-parser limit affiliated)) - ;; Drawer. - ((looking-at org-element-drawer-re) - (org-element-drawer-parser limit affiliated)) - ;; Fixed Width - ((looking-at "[ \t]*:\\( \\|$\\)") - (org-element-fixed-width-parser limit affiliated)) - ;; Inline Comments, Blocks, Babel Calls, Dynamic Blocks and - ;; Keywords. - ((looking-at "[ \t]*#\\+") - (goto-char (match-end 0)) - (cond - ((looking-at "BEGIN_\\(\\S-+\\)") - (beginning-of-line) - (funcall (pcase (upcase (match-string 1)) - ("CENTER" #'org-element-center-block-parser) - ("COMMENT" #'org-element-comment-block-parser) - ("EXAMPLE" #'org-element-example-block-parser) - ("EXPORT" #'org-element-export-block-parser) - ("QUOTE" #'org-element-quote-block-parser) - ("SRC" #'org-element-src-block-parser) - ("VERSE" #'org-element-verse-block-parser) - (_ #'org-element-special-block-parser)) - limit - affiliated)) - ((looking-at "CALL:") - (beginning-of-line) - (org-element-babel-call-parser limit affiliated)) - ((save-excursion - (beginning-of-line) - (looking-at org-element-dynamic-block-open-re)) - (beginning-of-line) - (org-element-dynamic-block-parser limit affiliated)) - ((looking-at "\\S-+:") - (beginning-of-line) - (org-element-keyword-parser limit affiliated)) - (t - (beginning-of-line) - (org-element-paragraph-parser limit affiliated)))) - ;; Footnote Definition. - ((looking-at org-footnote-definition-re) - (org-element-footnote-definition-parser limit affiliated)) - ;; Horizontal Rule. - ((looking-at "[ \t]*-\\{5,\\}[ \t]*$") - (org-element-horizontal-rule-parser limit affiliated)) - ;; Diary Sexp. - ((looking-at "%%(") - (org-element-diary-sexp-parser limit affiliated)) - ;; Table. - ((or (looking-at "[ \t]*|") - ;; There is no strict definition of a table.el - ;; table. Try to prevent false positive while being - ;; quick. - (let ((rule-regexp - (rx (zero-or-more (any " \t")) - "+" - (one-or-more (one-or-more "-") "+") - (zero-or-more (any " \t")) - eol)) - (non-table.el-line - (rx bol - (zero-or-more (any " \t")) - (or eol (not (any "+| \t"))))) - (next (line-beginning-position 2))) - ;; Start with a full rule. - (and - (looking-at rule-regexp) - (< next limit) ;no room for a table.el table - (save-excursion - (end-of-line) - (cond - ;; Must end with a full rule. - ((not (re-search-forward non-table.el-line limit 'move)) - (if (bolp) (forward-line -1) (beginning-of-line)) - (looking-at rule-regexp)) - ;; Ignore pseudo-tables with a single - ;; rule. - ((= next (line-beginning-position)) - nil) - ;; Must end with a full rule. - (t - (forward-line -1) - (looking-at rule-regexp))))))) - (org-element-table-parser limit affiliated)) - ;; List. - ((looking-at (org-item-re)) - (org-element-plain-list-parser - limit affiliated - (or structure (org-element--list-struct limit)))) - ;; Default element: Paragraph. - (t (org-element-paragraph-parser limit affiliated))))))) - (when result - (org-element-put-property result :mode mode) - (org-element-put-property result :granularity granularity)) - (when (and (not (buffer-narrowed-p)) - (org-element--cache-active-p) - (not org-element--cache-sync-requests) - add-to-cache) - (if (not old-element) - (setq result (org-element--cache-put result)) - (org-element-set-element old-element result) - (setq result old-element))) - result))))) + (save-excursion + (let ((case-fold-search t) + ;; Determine if parsing depth allows for secondary strings + ;; parsing. It only applies to elements referenced in + ;; `org-element-secondary-value-alist'. + (raw-secondary-p (and granularity (not (eq granularity 'object)))) + result at-task?) + (setq + result + ;; Regexp matches below should avoid modifying match data, + ;; if possible. Doing it unnecessarily degrades regexp + ;; matching performance an order of magnitude, which + ;; becomes important when parsing large buffers with huge + ;; amount of elements to be parsed. + ;; + ;; In general, the checks below should be as efficient as + ;; possible, especially early in the `cond' form. (The + ;; early checks will contribute to all subsequent parsers as + ;; well). + (cond + ;; Item. + ((eq mode 'item) (org-element-item-parser limit structure raw-secondary-p)) + ;; Table Row. + ((eq mode 'table-row) (org-element-table-row-parser limit)) + ;; Node Property. + ((eq mode 'node-property) (org-element-node-property-parser limit)) + ;; Headline. + ((and (looking-at-p "^\\*+ ") + (setq at-task? t) + (or (not (featurep 'org-inlinetask)) + (save-excursion + (< (skip-chars-forward "*") + (if org-odd-levels-only + (1- (* org-inlinetask-min-level 2)) + org-inlinetask-min-level))))) + (org-element-headline-parser limit raw-secondary-p)) + ;; Sections (must be checked after headline). + ((memq mode '(section first-section)) (org-element-section-parser nil)) + ;; Comments. + ((looking-at-p org-comment-regexp) (org-element-comment-parser limit)) + ;; Planning. + ((and (eq mode 'planning) + (eq ?* (char-after (line-beginning-position 0))) + (looking-at-p org-element-planning-line-re)) + (org-element-planning-parser limit)) + ;; Property drawer. + ((and (pcase mode + (`planning (eq ?* (char-after (line-beginning-position 0)))) + ((or `property-drawer `top-comment) + ;; See https://debbugs.gnu.org/cgi/bugreport.cgi?bug=63225#80 + (save-excursion + (forward-line -1) ; faster than beginning-of-line + (skip-chars-forward "[:blank:]") ; faster than looking-at-p + (or (not (eolp)) ; very cheap + ;; Document-wide property drawer may be preceded by blank lines. + (progn (skip-chars-backward " \t\n\r") (bobp))))) + (_ nil)) + (looking-at-p org-property-drawer-re)) + (org-element-property-drawer-parser limit)) + ;; When not at bol, point is at the beginning of an item or + ;; a footnote definition: next item is always a paragraph. + ((not (bolp)) (org-element-paragraph-parser limit (list (point)))) + ;; Clock. + ((looking-at-p org-element-clock-line-re) (org-element-clock-parser limit)) + ;; Inlinetask. + (at-task? (org-element-inlinetask-parser limit raw-secondary-p)) + ;; From there, elements can have affiliated keywords. + ;; Note an edge case with a keyword followed by element that + ;; cannot have affiliated keywords attached (the above). + ;; `org-element--collect-affiliated-keywords' must have a + ;; special check to fall back to parsing proper keyword. + (t (let ((affiliated (org-element--collect-affiliated-keywords + limit (memq granularity '(nil object))))) + (cond + ;; Jumping over affiliated keywords put point off-limits. + ;; Parse them as regular keywords. + ((and (cdr affiliated) (>= (point) limit)) + (goto-char (car affiliated)) + (org-element-keyword-parser limit nil)) + ;; Do a single regexp match do reduce overheads for + ;; multiple regexp search invocations. + ((looking-at org-element--current-element-re) + (cond + ;; LaTeX Environment. + ((match-beginning 1) + (org-element-latex-environment-parser limit affiliated)) + ;; Drawer. + ((match-beginning 2) + (org-element-drawer-parser limit affiliated)) + ;; Fixed Width + ((match-beginning 3) + (org-element-fixed-width-parser limit affiliated)) + ;; Inline Comments, Blocks, Babel Calls, Dynamic Blocks and + ;; Keywords. + ((match-beginning 5) + (funcall (pcase (upcase (match-string 5)) + ("CENTER" #'org-element-center-block-parser) + ("COMMENT" #'org-element-comment-block-parser) + ("EXAMPLE" #'org-element-example-block-parser) + ("EXPORT" #'org-element-export-block-parser) + ("QUOTE" #'org-element-quote-block-parser) + ("SRC" #'org-element-src-block-parser) + ("VERSE" #'org-element-verse-block-parser) + (_ #'org-element-special-block-parser)) + limit + affiliated)) + ((match-beginning 6) + (org-element-babel-call-parser limit affiliated)) + ((match-beginning 7) + (forward-line 0) + (org-element-dynamic-block-parser limit affiliated)) + ((match-beginning 8) + (org-element-keyword-parser limit affiliated)) + ((match-beginning 4) ;; #+, not matching a specific element. + (org-element-paragraph-parser limit affiliated)) + ;; Footnote Definition. + ((match-beginning 9) + (org-element-footnote-definition-parser limit affiliated)) + ;; Horizontal Rule. + ((match-beginning 10) + (org-element-horizontal-rule-parser limit affiliated)) + ;; Diary Sexp. + ((match-beginning 11) + (org-element-diary-sexp-parser limit affiliated)))) + ;; Table. + ((or (looking-at-p "[ \t]*|") + ;; There is no strict definition of a table.el + ;; table. Try to prevent false positive while being + ;; quick. + (let ((rule-regexp + (rx (zero-or-more (any " \t")) + "+" + (one-or-more (one-or-more "-") "+") + (zero-or-more (any " \t")) + eol)) + (non-table.el-line + (rx bol + (zero-or-more (any " \t")) + (or eol (not (any "+| \t"))))) + (next (line-beginning-position 2))) + ;; Start with a full rule. + (and + (looking-at-p rule-regexp) + (< next limit) ;no room for a table.el table + (save-excursion + (end-of-line) + (cond + ;; Must end with a full rule. + ((not (re-search-forward non-table.el-line limit 'move)) + (if (bolp) (forward-line -1) (forward-line 0)) + (looking-at-p rule-regexp)) + ;; Ignore pseudo-tables with a single + ;; rule. + ((= next (line-beginning-position)) + nil) + ;; Must end with a full rule. + (t + (forward-line -1) + (looking-at-p rule-regexp))))))) + (org-element-table-parser limit affiliated)) + ;; List. + ((looking-at-p (org-item-re)) + (org-element-plain-list-parser + limit affiliated + (or structure (org-element--list-struct limit)))) + ;; Default element: Paragraph. + (t (org-element-paragraph-parser limit affiliated))))))) + (when result + (org-element-put-property result :buffer (current-buffer)) + (org-element-put-property result :mode mode) + (org-element-put-property result :granularity granularity)) + result))) ;; Most elements can have affiliated keywords. When looking for an @@ -4416,16 +4871,13 @@ When PARSE is non-nil, values from keywords belonging to ;; value parsed. (parsed? (member kwd org-element-parsed-keywords)) ;; Find main value for any keyword. - (value - (let ((beg (match-end 0)) - (end (save-excursion - (end-of-line) - (skip-chars-backward " \t") - (point)))) - (if parsed? - (save-match-data - (org-element--parse-objects beg end nil restrict)) - (org-trim (buffer-substring-no-properties beg end))))) + (value-begin (match-end 0)) + (value-end + (save-excursion + (end-of-line) + (skip-chars-backward " \t") + (point))) + value ;; If KWD is a dual keyword, find its secondary value. ;; Maybe parse it. (dual? (member kwd org-element-dual-keywords)) @@ -4434,26 +4886,38 @@ When PARSE is non-nil, values from keywords belonging to (let ((sec (match-string-no-properties 2))) (cond ((and sec parsed?) - (save-match-data - (org-element--parse-objects - (match-beginning 2) (match-end 2) nil restrict))) + (org-element--parse-objects + (match-beginning 2) (match-end 2) nil restrict)) (sec sec))))) ;; Attribute a property name to KWD. (kwd-sym (and kwd (intern (concat ":" (downcase kwd)))))) + (setq value + (if parsed? + (org-element--parse-objects + value-begin value-end nil restrict) + (org-trim (buffer-substring-no-properties + value-begin value-end)))) ;; Now set final shape for VALUE. (when dual? (setq value (and (or value dual-value) (cons value dual-value)))) (when (or (member kwd org-element-multiple-keywords) ;; Attributes can always appear on multiple lines. - (string-match "^ATTR_" kwd)) - (setq value (cons value (plist-get output kwd-sym)))) + (string-match-p "^ATTR_" kwd)) + (setq value (nconc (plist-get output kwd-sym) (list value)))) ;; Eventually store the new value in OUTPUT. (setq output (plist-put output kwd-sym value)) ;; Move to next keyword. (forward-line))) ;; If affiliated keywords are orphaned: move back to first one. ;; They will be parsed as a paragraph. - (when (looking-at "[ \t]*$") (goto-char origin) (setq output nil)) + (when (or (looking-at-p "[ \t]*$") + ;; Affiliated keywords are not allowed before comments. + (looking-at-p org-comment-regexp) + ;; Clock lines are also not allowed. + (looking-at-p org-clock-line-re) + ;; Inlinetasks not allowed. + (looking-at-p "^\\*+ ")) + (goto-char origin) (setq output nil)) ;; Return value. (cons origin output)))) @@ -4472,11 +4936,14 @@ When PARSE is non-nil, values from keywords belonging to ;; resulting values. In an export situation, it also skips unneeded ;; parts of the parse tree. -(defun org-element-parse-buffer (&optional granularity visible-only) - "Recursively parse the buffer and return structure. +(defun org-element-parse-buffer (&optional granularity visible-only keep-deferred) + "Recursively parse the current Org mode buffer and return structure. If narrowing is in effect, only parse the visible part of the buffer. +This function assumes that current major mode is `org-mode'. When the +major mode is different, the behaviour is undefined. + Optional argument GRANULARITY determines the depth of the recursion. It can be set to the following symbols: @@ -4490,6 +4957,8 @@ recursion. It can be set to the following symbols: When VISIBLE-ONLY is non-nil, don't parse contents of hidden elements. +When KEEP-DEFERRED is non-nil, do not resolve deferred properties. + An element or object is represented as a list with the pattern (TYPE PROPERTIES CONTENTS), where : @@ -4498,7 +4967,7 @@ pattern (TYPE PROPERTIES CONTENTS), where : exhaustive list of such symbols. One can retrieve it with `org-element-type' function. - PROPERTIES is the list of attributes attached to the element or + PROPERTIES is the list of properties attached to the element or object, as a plist. Although most of them are specific to the element or object type, all types share `:begin', `:end', `:post-blank' and `:parent' properties, which respectively @@ -4513,19 +4982,24 @@ pattern (TYPE PROPERTIES CONTENTS), where : The Org buffer has `org-data' as type and nil as properties. `org-element-map' function can be used to find specific elements -or objects within the parse tree. - -This function assumes that current major mode is `org-mode'." +or objects within the parse tree." (save-excursion (goto-char (point-min)) (let ((org-data (org-element-org-data-parser)) (gc-cons-threshold #x40000000)) (org-skip-whitespace) - (org-element--parse-elements - (line-beginning-position) (point-max) - ;; Start in `first-section' mode so text before the first - ;; headline belongs to a section. - 'first-section nil granularity visible-only org-data)))) + (setq org-data + (org-element--parse-elements + (line-beginning-position) (point-max) + ;; Start in `first-section' mode so text before the first + ;; headline belongs to a section. + 'first-section nil granularity visible-only org-data)) + (unless keep-deferred + (org-element-map ; undefer + org-data t + (lambda (el) (org-element-properties-resolve el t)) + nil nil nil t)) + org-data))) (defun org-element-parse-secondary-string (string restriction &optional parent) "Recursively parse objects in STRING and return structure. @@ -4541,24 +5015,31 @@ If STRING is the empty string or nil, return nil." (cond ((not string) nil) ((equal string "") nil) - (t (let ((local-variables (buffer-local-variables))) - (with-temp-buffer - (dolist (v local-variables) - (ignore-errors - (if (symbolp v) (makunbound v) - ;; Don't set file name to avoid mishandling hooks (bug#44524) - (unless (memq (car v) '(buffer-file-name buffer-file-truename)) - (set (make-local-variable (car v)) (cdr v)))))) - ;; Transferring local variables may put the temporary buffer - ;; into a read-only state. Make sure we can insert STRING. - (let ((inhibit-read-only t)) (insert string)) - ;; Prevent "Buffer *temp* modified; kill anyway?". - (restore-buffer-modified-p nil) - (org-element--parse-objects - (point-min) (point-max) nil restriction parent)))))) + (t (let (rtn) + (org-element-with-buffer-copy + :to-buffer (org-get-buffer-create " *Org parse*" t) + :drop-contents t + :drop-visibility t + :drop-narrowing t + :drop-locals nil + ;; Transferring local variables may put the temporary buffer + ;; into a read-only state. Make sure we can insert STRING. + (let ((inhibit-read-only t)) (erase-buffer) (insert string)) + ;; Prevent "Buffer *temp* modified; kill anyway?". + (restore-buffer-modified-p nil) + (setq rtn + (org-element--parse-objects + (point-min) (point-max) nil restriction parent)) + ;; Resolve deferred. + (org-element-map rtn t + (lambda (el) (org-element-properties-resolve el t))) + rtn))))) (defun org-element-map - (data types fun &optional info first-match no-recursion with-affiliated) + ( data types fun + &optional + info first-match no-recursion + with-affiliated no-undefer) "Map a function on selected elements or objects. DATA is a parse tree (for example, returned by @@ -4569,9 +5050,15 @@ elements or object types (see `org-element-all-elements' and function called on the matching element or object. It has to accept one argument: the element or object itself. +When TYPES is t, call FUN for all the elements and objects. + +FUN can also be a Lisp form. The form will be evaluated as function +with symbol `node' bound to the current node. + When optional argument INFO is non-nil, it should be a plist -holding export options. In that case, parts of the parse tree -not exportable according to that property list will be skipped. +holding export options. In that case, elements of the parse tree +\\(compared with `eq') not exportable according to `:ignore-list' +property in that property list will be skipped. When optional argument FIRST-MATCH is non-nil, stop at the first match for which FUN doesn't return nil, and return that value. @@ -4585,8 +5072,18 @@ When optional argument WITH-AFFILIATED is non-nil, FUN will also apply to matching objects within parsed affiliated keywords (see `org-element-parsed-keywords'). +When optional argument NO-UNDEFER is non-nil, do not resolve deferred +values. + +FUN may throw `:org-element-skip' signal. Then, `org-element-map' +will not recurse into the current element. + Nil values returned from FUN do not appear in the results. +When buffer parse tree is used, elements and objects are generally +traversed in the same order they appear in text with a single +exception of dual keywords where secondary value is traversed after +the mail value. Examples: --------- @@ -4605,7 +5102,7 @@ of 1 and a \"phone\" tag, and will return its beginning position: (lambda (hl) (and (= (org-element-property :level hl) 1) (member \"phone\" (org-element-property :tags hl)) - (org-element-property :begin hl))) + (org-element-begin hl))) nil t) The next example will return a flat list of all `plain-list' type @@ -4623,99 +5120,35 @@ looking into captions: nil nil nil t)" (declare (indent 2)) ;; Ensure TYPES and NO-RECURSION are a list, even of one element. - (let* ((types (if (listp types) types (list types))) - (no-recursion (if (listp no-recursion) no-recursion - (list no-recursion))) - ;; Recursion depth is determined by --CATEGORY. - (--category - (catch :--found - (let ((category 'greater-elements) - (all-objects (cons 'plain-text org-element-all-objects))) - (dolist (type types category) - (cond ((memq type all-objects) - ;; If one object is found, the function has - ;; to recurse into every object. - (throw :--found 'objects)) - ((not (memq type org-element-greater-elements)) - ;; If one regular element is found, the - ;; function has to recurse, at least, into - ;; every element it encounters. - (and (not (eq category 'elements)) - (setq category 'elements)))))))) - (--ignore-list (plist-get info :ignore-list)) - --acc) - (letrec ((--walk-tree - (lambda (--data) - ;; Recursively walk DATA. INFO, if non-nil, is a plist - ;; holding contextual information. - (let ((--type (org-element-type --data))) - (cond - ((not --data)) - ;; Ignored element in an export context. - ((and info (memq --data --ignore-list))) - ;; List of elements or objects. - ((not --type) (mapc --walk-tree --data)) - ;; Unconditionally enter parse trees. - ((eq --type 'org-data) - (mapc --walk-tree (org-element-contents --data))) - (t - ;; Check if TYPE is matching among TYPES. If so, - ;; apply FUN to --DATA and accumulate return value - ;; into --ACC (or exit if FIRST-MATCH is non-nil). - (when (memq --type types) - (let ((result (funcall fun --data))) - (cond ((not result)) - (first-match (throw :--map-first-match result)) - (t (push result --acc))))) - ;; If --DATA has a secondary string that can contain - ;; objects with their type among TYPES, look inside. - (when (and (eq --category 'objects) (not (stringp --data))) - (dolist (p (cdr (assq --type - org-element-secondary-value-alist))) - (funcall --walk-tree (org-element-property p --data)))) - ;; If --DATA has any parsed affiliated keywords and - ;; WITH-AFFILIATED is non-nil, look for objects in - ;; them. - (when (and with-affiliated - (eq --category 'objects) - (eq (org-element-class --data) 'element)) - (dolist (kwd-pair org-element--parsed-properties-alist) - (let ((kwd (car kwd-pair)) - (value (org-element-property (cdr kwd-pair) --data))) - ;; Pay attention to the type of parsed - ;; keyword. In particular, preserve order for - ;; multiple keywords. - (cond - ((not value)) - ((member kwd org-element-dual-keywords) - (if (member kwd org-element-multiple-keywords) - (dolist (line (reverse value)) - (funcall --walk-tree (cdr line)) - (funcall --walk-tree (car line))) - (funcall --walk-tree (cdr value)) - (funcall --walk-tree (car value)))) - ((member kwd org-element-multiple-keywords) - (mapc --walk-tree (reverse value))) - (t (funcall --walk-tree value)))))) - ;; Determine if a recursion into --DATA is possible. - (cond - ;; --TYPE is explicitly removed from recursion. - ((memq --type no-recursion)) - ;; --DATA has no contents. - ((not (org-element-contents --data))) - ;; Looking for greater elements but --DATA is - ;; simply an element or an object. - ((and (eq --category 'greater-elements) - (not (memq --type org-element-greater-elements)))) - ;; Looking for elements but --DATA is an object. - ((and (eq --category 'elements) - (eq (org-element-class --data) 'object))) - ;; In any other case, map contents. - (t (mapc --walk-tree (org-element-contents --data)))))))))) - (catch :--map-first-match - (funcall --walk-tree data) - ;; Return value in a proper order. - (nreverse --acc))))) + (when (and types data) + (let* ((ignore-list (plist-get info :ignore-list)) + (objects? + (or (eq types t) + (cl-intersection + (cons 'plain-text org-element-all-objects) + (if (listp types) types (list types))))) + (no-recursion + (append + (if (listp no-recursion) no-recursion + (list no-recursion)) + (unless objects? + org-element-all-objects) + (unless objects? + ;; Do not recurse into elements that can only contain + ;; objects. + (cl-set-difference + org-element-all-elements + org-element-greater-elements))))) + (org-element-ast-map + data types fun + ignore-list first-match + no-recursion + ;; Affiliated keywords may only contain objects. + (when (and with-affiliated objects?) + (mapcar #'cdr org-element--parsed-properties-alist)) + ;; Secondary strings may only contain objects. + (not objects?) + no-undefer)))) ;; The following functions are internal parts of the parser. ;; @@ -4789,23 +5222,10 @@ Elements are accumulated into ACC." (when (and (eolp) (not (eobp))) (forward-char))) ;; Find current element's type and parse it accordingly to ;; its category. - (let* ((element (org-element-copy - ;; `org-element--current-element' may return cached - ;; elements. Below code reassigns - ;; `:parent' property of the element and - ;; may interfere with cache - ;; synchronization if parent element is not - ;; yet in cache. Moreover, the returned - ;; structure may be altered by caller code - ;; arbitrarily. Hence, we return a copy of - ;; the potentially cached element to make - ;; potential modifications safe for element - ;; cache. - (org-element--current-element - end granularity mode structure))) + (let* ((element (org-element--current-element end granularity mode structure)) (type (org-element-type element)) - (cbeg (org-element-property :contents-begin element))) - (goto-char (org-element-property :end element)) + (cbeg (org-element-contents-begin element))) + (goto-char (org-element-end element)) ;; Fill ELEMENT contents by side-effect. (cond ;; If element has no contents, don't modify it. @@ -4820,7 +5240,7 @@ Elements are accumulated into ACC." (eq type 'section)) (eq type 'headline))) (org-element--parse-elements - cbeg (org-element-property :contents-end element) + cbeg (org-element-contents-end element) ;; Possibly switch to a special mode. (org-element--next-mode mode type t) (and (memq type '(item plain-list)) @@ -4830,7 +5250,7 @@ Elements are accumulated into ACC." ;; GRANULARITY allows it. ((memq granularity '(object nil)) (org-element--parse-objects - cbeg (org-element-property :contents-end element) element + cbeg (org-element-contents-end element) element (org-element-restriction type)))) (push (org-element-put-property element :parent acc) elements) ;; Update mode. @@ -4844,117 +5264,127 @@ Elements are accumulated into ACC." RESTRICTION is a list of object types, as symbols, that should be looked after. This function assumes that the buffer is narrowed to an appropriate container (e.g., a paragraph)." - (cond - ((memq 'table-cell restriction) (org-element-table-cell-parser)) - ((memq 'citation-reference restriction) - (org-element-citation-reference-parser)) - (t - (let* ((start (point)) - (limit - ;; Object regexp sometimes needs to have a peek at - ;; a character ahead. Therefore, when there is a hard - ;; limit, make it one more than the true beginning of the - ;; radio target. - (save-excursion - (cond ((not org-target-link-regexp) nil) - ((not (memq 'link restriction)) nil) - ((progn - (unless (bolp) (forward-char -1)) - (not (re-search-forward org-target-link-regexp nil t))) - nil) - ;; Since we moved backward, we do not want to - ;; match again an hypothetical 1-character long - ;; radio link before us. Realizing that this can - ;; only happen if such a radio link starts at - ;; beginning of line, we prevent this here. - ((and (= start (1+ (line-beginning-position))) - (= start (match-end 1))) - (and (re-search-forward org-target-link-regexp nil t) - (1+ (match-beginning 1)))) - (t (1+ (match-beginning 1)))))) - found) - (save-excursion - (while (and (not found) - (re-search-forward org-element--object-regexp limit 'move)) - (goto-char (match-beginning 0)) - (let ((result (match-string 0))) - (setq found - (cond - ((string-prefix-p "call_" result t) - (and (memq 'inline-babel-call restriction) - (org-element-inline-babel-call-parser))) - ((string-prefix-p "src_" result t) - (and (memq 'inline-src-block restriction) - (org-element-inline-src-block-parser))) - (t - (pcase (char-after) - (?^ (and (memq 'superscript restriction) - (org-element-superscript-parser))) - (?_ (or (and (memq 'subscript restriction) - (org-element-subscript-parser)) - (and (memq 'underline restriction) - (org-element-underline-parser)))) - (?* (and (memq 'bold restriction) - (org-element-bold-parser))) - (?/ (and (memq 'italic restriction) - (org-element-italic-parser))) - (?~ (and (memq 'code restriction) - (org-element-code-parser))) - (?= (and (memq 'verbatim restriction) - (org-element-verbatim-parser))) - (?+ (and (memq 'strike-through restriction) - (org-element-strike-through-parser))) - (?@ (and (memq 'export-snippet restriction) - (org-element-export-snippet-parser))) - (?{ (and (memq 'macro restriction) - (org-element-macro-parser))) - (?$ (and (memq 'latex-fragment restriction) - (org-element-latex-fragment-parser))) - (?< - (if (eq (aref result 1) ?<) - (or (and (memq 'radio-target restriction) - (org-element-radio-target-parser)) - (and (memq 'target restriction) - (org-element-target-parser))) - (or (and (memq 'timestamp restriction) - (org-element-timestamp-parser)) - (and (memq 'link restriction) - (org-element-link-parser))))) - (?\\ - (if (eq (aref result 1) ?\\) - (and (memq 'line-break restriction) - (org-element-line-break-parser)) - (or (and (memq 'entity restriction) - (org-element-entity-parser)) - (and (memq 'latex-fragment restriction) - (org-element-latex-fragment-parser))))) - (?\[ - (pcase (aref result 1) - ((and ?\[ - (guard (memq 'link restriction))) - (org-element-link-parser)) - ((and ?f - (guard (memq 'footnote-reference restriction))) - (org-element-footnote-reference-parser)) - ((and ?c - (guard (memq 'citation restriction))) - (org-element-citation-parser)) - ((and (or ?% ?/) - (guard (memq 'statistics-cookie restriction))) - (org-element-statistics-cookie-parser)) - (_ - (or (and (memq 'timestamp restriction) - (org-element-timestamp-parser)) - (and (memq 'statistics-cookie restriction) - (org-element-statistics-cookie-parser)))))) - ;; This is probably a plain link. - (_ (and (memq 'link restriction) - (org-element-link-parser))))))) - (or (eobp) (forward-char)))) - (cond (found) - (limit (forward-char -1) - (org-element-link-parser)) ;radio link - (t nil))))))) + (let (result) + (setq + result + (cond + ((memq 'table-cell restriction) (org-element-table-cell-parser)) + ((memq 'citation-reference restriction) + (org-element-citation-reference-parser)) + (t + (let* ((start (point)) + (limit + ;; Object regexp sometimes needs to have a peek at + ;; a character ahead. Therefore, when there is a hard + ;; limit, make it one more than the true beginning of the + ;; radio target. + (save-excursion + (cond ((not org-target-link-regexp) nil) + ((not (memq 'link restriction)) nil) + ((progn + (unless (bolp) (forward-char -1)) + (not + (if org-target-link-regexps + (org--re-list-search-forward org-target-link-regexps nil t) + (re-search-forward org-target-link-regexp nil t)))) + nil) + ;; Since we moved backward, we do not want to + ;; match again an hypothetical 1-character long + ;; radio link before us. Realizing that this can + ;; only happen if such a radio link starts at + ;; beginning of line, we prevent this here. + ((and (= start (1+ (line-beginning-position))) + (= start (match-end 1))) + (and + (if org-target-link-regexps + (org--re-list-search-forward org-target-link-regexps nil t) + (re-search-forward org-target-link-regexp nil t)) + (1+ (match-beginning 1)))) + (t (1+ (match-beginning 1)))))) + found) + (save-excursion + (while (and (not found) + (re-search-forward org-element--object-regexp limit 'move)) + (goto-char (match-beginning 0)) + (let ((result (match-string 0))) + (setq found + (cond + ((string-prefix-p "call_" result t) + (and (memq 'inline-babel-call restriction) + (org-element-inline-babel-call-parser))) + ((string-prefix-p "src_" result t) + (and (memq 'inline-src-block restriction) + (org-element-inline-src-block-parser))) + (t + (pcase (char-after) + (?^ (and (memq 'superscript restriction) + (org-element-superscript-parser))) + (?_ (or (and (memq 'underline restriction) + (org-element-underline-parser)) + (and (memq 'subscript restriction) + (org-element-subscript-parser)))) + (?* (and (memq 'bold restriction) + (org-element-bold-parser))) + (?/ (and (memq 'italic restriction) + (org-element-italic-parser))) + (?~ (and (memq 'code restriction) + (org-element-code-parser))) + (?= (and (memq 'verbatim restriction) + (org-element-verbatim-parser))) + (?+ (and (memq 'strike-through restriction) + (org-element-strike-through-parser))) + (?@ (and (memq 'export-snippet restriction) + (org-element-export-snippet-parser))) + (?{ (and (memq 'macro restriction) + (org-element-macro-parser))) + (?$ (and (memq 'latex-fragment restriction) + (org-element-latex-fragment-parser))) + (?< + (if (eq (aref result 1) ?<) + (or (and (memq 'radio-target restriction) + (org-element-radio-target-parser)) + (and (memq 'target restriction) + (org-element-target-parser))) + (or (and (memq 'timestamp restriction) + (org-element-timestamp-parser)) + (and (memq 'link restriction) + (org-element-link-parser))))) + (?\\ + (if (eq (aref result 1) ?\\) + (and (memq 'line-break restriction) + (org-element-line-break-parser)) + (or (and (memq 'entity restriction) + (org-element-entity-parser)) + (and (memq 'latex-fragment restriction) + (org-element-latex-fragment-parser))))) + (?\[ + (pcase (aref result 1) + ((and ?\[ + (guard (memq 'link restriction))) + (org-element-link-parser)) + ((and ?f + (guard (memq 'footnote-reference restriction))) + (org-element-footnote-reference-parser)) + ((and ?c + (guard (memq 'citation restriction))) + (org-element-citation-parser)) + ((and (or ?% ?/) + (guard (memq 'statistics-cookie restriction))) + (org-element-statistics-cookie-parser)) + (_ + (or (and (memq 'timestamp restriction) + (org-element-timestamp-parser)) + (and (memq 'statistics-cookie restriction) + (org-element-statistics-cookie-parser)))))) + ;; This is probably a plain link. + (_ (and (memq 'link restriction) + (org-element-link-parser))))))) + (or (eobp) (forward-char)))) + (cond (found) + (limit (forward-char -1) + (org-element-link-parser)) ;radio link + (t nil))))))) + (org-element-put-property result :buffer (current-buffer)))) (defun org-element--parse-objects (beg end acc restriction &optional parent) "Parse objects between BEG and END and return recursive structure. @@ -4975,20 +5405,20 @@ the list of objects itself." (while (and (not (eobp)) (setq next-object (org-element--object-lex restriction))) ;; Text before any object. - (let ((obj-beg (org-element-property :begin next-object))) + (let ((obj-beg (org-element-begin next-object))) (unless (= (point) obj-beg) (let ((text (buffer-substring-no-properties (point) obj-beg))) (push (if acc (org-element-put-property text :parent acc) text) contents)))) ;; Object... - (let ((obj-end (org-element-property :end next-object)) - (cont-beg (org-element-property :contents-begin next-object))) + (let ((obj-end (org-element-end next-object)) + (cont-beg (org-element-contents-begin next-object))) (when acc (org-element-put-property next-object :parent acc)) (push (if cont-beg ;; Fill contents of NEXT-OBJECT if possible. (org-element--parse-objects cont-beg - (org-element-property :contents-end next-object) + (org-element-contents-end next-object) next-object (org-element-restriction next-object)) next-object) @@ -5037,7 +5467,7 @@ to interpret. Return Org syntax as a string." (results (cond ;; Secondary string. - ((not type) + ((eq type 'anonymous) (mapconcat (lambda (obj) (funcall fun obj parent)) data "")) @@ -5072,16 +5502,16 @@ to interpret. Return Org syntax as a string." ;; an item or a footnote-definition, ;; ignore first line's indentation. (and (eq type 'paragraph) - (memq (org-element-type parent) - '(footnote-definition item)) + (org-element-type-p + parent '(footnote-definition item)) (eq data (car (org-element-contents parent))) (eq (org-element-property :pre-blank parent) 0))))) "")))))) - (if (memq type '(org-data nil)) results + (if (memq type '(org-data anonymous)) results ;; Build white spaces. If no `:post-blank' property ;; is specified, assume its value is 0. - (let ((blank (or (org-element-property :post-blank data) 0))) + (let ((blank (or (org-element-post-blank data) 0))) (if (eq (org-element-class data parent) 'object) (concat results (make-string blank ?\s)) (concat (org-element--interpret-affiliated-keywords data) @@ -5112,22 +5542,25 @@ If there is no affiliated keyword, return the empty string." (when value (if (or (member keyword org-element-multiple-keywords) ;; All attribute keywords can have multiple lines. - (string-match "^ATTR_" keyword)) + (string-match-p "^ATTR_" keyword)) (mapconcat (lambda (line) (funcall keyword-to-org keyword line)) - (reverse value) - "") + value "") (funcall keyword-to-org keyword value))))) ;; List all ELEMENT's properties matching an attribute line or an ;; affiliated keyword, but ignore translated keywords since they ;; cannot belong to the property list. - (cl-loop for prop in (nth 1 element) by 'cddr - when (let ((keyword (upcase (substring (symbol-name prop) 1)))) - (or (string-match "^ATTR_" keyword) - (and - (member keyword org-element-affiliated-keywords) - (not (assoc keyword - org-element-keyword-translation-alist))))) - collect prop) + (let (acc) + (org-element-properties-mapc + (lambda (prop _ __) + (let ((keyword (upcase (substring (symbol-name prop) 1)))) + (when (or (string-match-p "^ATTR_" keyword) + (and + (member keyword org-element-affiliated-keywords) + (not (assoc keyword + org-element-keyword-translation-alist)))) + (push prop acc)))) + element t) + (nreverse acc)) ""))) ;; Because interpretation of the parse tree must return the same @@ -5209,9 +5642,9 @@ indentation removed from its contents." (put-text-property (match-beginning 1) (match-end 1) 'org-ind i datum) (setq min-ind (min i min-ind)))))))) - ((eq (org-element-type datum) 'line-break) + ((org-element-type-p datum 'line-break) (setq first-flag t)) - ((memq (org-element-type datum) org-element-recursive-objects) + ((org-element-type-p datum org-element-recursive-objects) (setq min-ind (funcall find-min-ind datum first-flag min-ind))))))) (min-ind @@ -5225,8 +5658,9 @@ indentation removed from its contents." (lambda (datum) ;; Return DATUM with all its strings indentation ;; shortened from MIN-IND white spaces. - (setcdr - (cdr datum) + (apply + #'org-element-set-contents + datum (mapcar (lambda (object) (cond @@ -5243,8 +5677,7 @@ indentation removed from its contents." (point))) (when (integerp i) (indent-to (- i min-ind)))))) (buffer-string))) - ((memq (org-element-type object) - org-element-recursive-objects) + ((org-element-type-p object org-element-recursive-objects) (funcall build object)) (t object))) (org-element-contents datum))) @@ -5316,6 +5749,11 @@ indentation removed from its contents." (defvar org-element-cache-persistent t "Non-nil when cache should persist between Emacs sessions.") +(defconst org-element-cache-version "2.3" + "Version number for Org AST structure. +Used to avoid loading obsolete AST representation when using +`org-element-cache-persistent'.") + (defvar org-element-cache-sync-idle-time 0.6 "Length, in seconds, of idle time before syncing cache.") @@ -5338,6 +5776,13 @@ of `org-element--cache-self-verify-frequency'. When set to symbol `backtrace', record and display backtrace log if any inconsistency is detected.") +(defvar org-element--cache-self-verify-before-persisting nil + "Perform consistency checks for the cache before writing to disk. + +When non-nil, signal an error an show backtrace if cache contains +incorrect elements. `org-element--cache-self-verify' must be set to +symbol `backtrace' to have non-empty backtrace displayed.") + (defvar org-element--cache-self-verify-frequency 0.03 "Frequency of cache element verification. @@ -5357,8 +5802,8 @@ to be correct. Setting this to a value less than 0.0001 is useless.") "Detail level of the diagnostics.") (defvar-local org-element--cache-diagnostics-ring nil - "Ring containing last `org-element--cache-diagnostics-ring-size' -cache process log entries.") + "Ring containing cache process log entries. +The ring size is `org-element--cache-diagnostics-ring-size'.") (defvar org-element--cache-diagnostics-ring-size 5000 "Size of `org-element--cache-diagnostics-ring'.") @@ -5397,14 +5842,6 @@ When non-nil, it should be a vector representing POS arguments of `org-element--cache-find' called with non-nil, non-`both' SIDE argument. Also, see `org-element--cache-hash-size'.") -(defvar org-element--cache-hash-statistics '(0 . 0) - "Cons cell storing how Org makes use of `org-element--cache-find' caching. -The car is the number of successful uses and cdr is the total calls to -`org-element--cache-find'.") -(defvar org-element--cache-hash-nocache 0 - "Number of calls to `org-element--cache-has' with `both' SIDE argument. -These calls are not cached by hash. See `org-element--cache-hash-size'.") - (defvar-local org-element--cache-size 0 "Size of the `org-element--cache'. @@ -5484,7 +5921,7 @@ This variable is used to determine when re-parsing buffer is not going to slow down the command. If the commands end up modifying the cache, the worst case scenario is -performance drop. So, advicing these commands is safe. Yet, it is +performance drop. So, advising these commands is safe. Yet, it is better to remove the commands advised in such a way from this list.") (defmacro org-element--request-key (request) @@ -5518,7 +5955,8 @@ better to remove the commands advised in such a way from this list.") (prin1-to-string ,element))) (defmacro org-element--cache-log-message (format-string &rest args) - "Add a new log message for org-element-cache." + "Add a new log message for org-element-cache. +FORMAT-STRING and ARGS are the same arguments as in `format'." `(when (or org-element--cache-diagnostics (eq org-element--cache-self-verify 'backtrace)) (let* ((format-string (concat (format "org-element-cache diagnostics(%s): " @@ -5526,14 +5964,15 @@ better to remove the commands advised in such a way from this list.") ,format-string)) (format-string (funcall #'format format-string ,@args))) (if org-element--cache-diagnostics - (display-warning 'org-element-cache format-string) + (display-warning '(org-element org-element-cache) format-string) (unless org-element--cache-diagnostics-ring (setq org-element--cache-diagnostics-ring (make-ring org-element--cache-diagnostics-ring-size))) (ring-insert org-element--cache-diagnostics-ring format-string))))) (defmacro org-element--cache-warn (format-string &rest args) - "Raise warning for org-element-cache." + "Raise warning for org-element-cache. +FORMAT-STRING and ARGS are the same arguments as in `format'." `(let* ((format-string (funcall #'format ,format-string ,@args)) (format-string (if (or (not org-element--cache-diagnostics-ring) @@ -5550,7 +5989,8 @@ better to remove the commands advised in such a way from this list.") (setq org-element--cache-diagnostics-ring nil))))) (if (and (boundp 'org-batch-test) org-batch-test) (error "%s" (concat "org-element--cache: " format-string)) - (display-warning 'org-element-cache + (push (concat "org-element--cache: " format-string) org--warnings) + (display-warning '(org-element org-element-cache) (concat "org-element--cache: " format-string))))) (defsubst org-element--cache-key (element) @@ -5573,23 +6013,24 @@ cache during the synchronization get a new key generated with Such keys are stored inside the element property `:org-element--cache-sync-key'. The property is a cons containing current `org-element--cache-sync-keys-value' and the element key." - (or (when (eq org-element--cache-sync-keys-value (car (org-element-property :org-element--cache-sync-key element))) - (cdr (org-element-property :org-element--cache-sync-key element))) - (let* ((begin (org-element-property :begin element)) + (or (when-let* ((key-cons (org-element-property :org-element--cache-sync-key element))) + (when (eq org-element--cache-sync-keys-value (car key-cons)) + (cdr key-cons))) + (let* ((begin (org-element-begin element)) + (type (org-element-type element)) ;; Increase beginning position of items (respectively ;; table rows) by one, so the first item can get ;; a different key from its parent list (respectively ;; table). - (key (if (memq (org-element-type element) '(item table-row)) - (1+ begin) - ;; Decrease beginning position of sections by one, - ;; so that the first element of the section get - ;; different key from the parent section. - (if (eq (org-element-type element) 'section) - (1- begin) - (if (eq (org-element-type element) 'org-data) - (- begin 2) - begin))))) + (key + (cond + ((memq type '(item table-row)) (1+ begin)) + ;; Decrease beginning position of sections by one, + ;; so that the first element of the section get + ;; different key from the parent section. + ((eq type 'section) (1- begin)) + ((eq type 'org-data) (- begin 2)) + (t begin)))) (when org-element--cache-sync-requests (org-element-put-property element @@ -5690,7 +6131,7 @@ position." ;; than B (A is longer). Therefore, return nil. (and (null a) b))))) -(defun org-element--cache-compare (a b) +(defsubst org-element--cache-compare (a b) "Non-nil when element A is located before element B." (org-element--cache-key-less-p (org-element--cache-key a) (org-element--cache-key b))) @@ -5706,16 +6147,18 @@ This function assumes `org-element--headline-cache' is a valid AVL tree." ;;;; Tools -;; FIXME: Ideally, this should be inlined to avoid overheads, but -;; inlined functions should be declared before the code that uses them -;; and some code above does use `org-element--cache-active-p'. Moving this -;; declaration on top would require restructuring the whole cache -;; section. +;; FIXME: `org-fold-core-cycle-over-indirect-buffers' should better be +;; taken out of org-fold-core to track indirect buffers in general. (defun org-element--cache-active-p (&optional called-from-cache-change-func-p) - "Non-nil when cache is active in current buffer." + "Non-nil when cache is active in current buffer. +When CALLED-FROM-CACHE-CHANGE-FUNC-P is non-nil, do not assert cache +consistency with buffer modifications." (org-with-base-buffer nil (and org-element-use-cache - org-element--cache + (or org-element--cache + (when (derived-mode-p 'org-mode) + (org-element-cache-reset) + t)) (or called-from-cache-change-func-p (eq org-element--cache-change-tic (buffer-chars-modified-tick)) (and @@ -5738,25 +6181,6 @@ This function assumes `org-element--headline-cache' is a valid AVL tree." (throw :inhibited nil))) t)))))) -;; FIXME: Remove after we establish that hashing is effective. -(defun org-element-cache-hash-show-statistics () - "Display efficiency of O(1) query cache for `org-element--cache-find'. - -This extra caching is based on the following paper: -Pugh [Information Processing Letters] (1990) Slow optimally balanced - search strategies vs. cached fast uniformly balanced search - strategies. http://dx.doi.org/10.1016/0020-0190(90)90130-P - -Also, see `org-element--cache-size'." - (interactive) - (message "%.2f%% of cache searches hashed, %.2f%% non-hashable." - (* 100 - (/ (float (car org-element--cache-hash-statistics)) - (cdr org-element--cache-hash-statistics))) - (* 100 - (/ (float org-element--cache-hash-nocache) - (cdr org-element--cache-hash-statistics))))) - (defun org-element--cache-find (pos &optional side) "Find element in cache starting at POS or before. @@ -5784,26 +6208,28 @@ the cache." lower upper) ;; `org-element--cache-key-less-p' does not accept markers. (when (markerp pos) (setq pos (marker-position pos))) - (cl-incf (cdr org-element--cache-hash-statistics)) - (when (eq side 'both) (cl-incf org-element--cache-hash-nocache)) (if (and hashed (not (eq side 'both)) + ;; Ensure that HASHED is not within synchronized part + ;; of the cache. + (org-element-property :cached hashed) (or (not limit) ;; Limit can be a list key. (org-element--cache-key-less-p (org-element--cache-key hashed) limit)) - (= pos (org-element-property :begin hashed)) + ;; It is only safe to assume that element at POS is + ;; exact. Extra elements starting before/after could + ;; have been added to cache and HASHED may no longer be + ;; valid. + (= pos (org-element-begin hashed)) ;; We cannot rely on element :begin for elements with ;; children starting at the same pos. - (not (memq (org-element-type hashed) - '(section org-data table))) - (org-element-property :cached hashed)) - (progn - (cl-incf (car org-element--cache-hash-statistics)) - hashed) + (not (org-element-type-p hashed '(section org-data table)))) + hashed + ;; No appropriate HASHED. Search the cache. (while node (let* ((element (avl-tree--node-data node)) - (begin (org-element-property :begin element))) + (begin (org-element-begin element))) (cond ((and limit (not (org-element--cache-key-less-p @@ -5815,7 +6241,7 @@ the cache." ((or (< begin pos) ;; If the element is section or org-data, we also need ;; to check the following element. - (memq (org-element-type element) '(section org-data))) + (org-element-type-p element '(section org-data))) (setq lower element node (avl-tree--node-right node))) ;; We found an element in cache starting at POS. If `side' @@ -5830,10 +6256,11 @@ the cache." ((eq side 'both) (setq lower element) (setq node (avl-tree--node-right node))) - ((and (memq (org-element-type element) '(item table-row)) - (let ((parent (org-element-property :parent element))) - (and (= (org-element-property :begin element) - (org-element-property :contents-begin parent)) + ((and (org-element-type-p element '(item table-row)) + ;; Cached elements cannot have deferred `:parent'. + (let ((parent (org-element-property-raw :parent element))) + (and (= (org-element-begin element) + (org-element-contents-begin parent)) (setq node nil lower parent upper parent))))) @@ -5841,14 +6268,12 @@ the cache." (setq node nil lower element upper element))))) - (if (not side) - (aset org-element--cache-hash-left hash-pos lower) - (unless (eq side 'both) - (aset org-element--cache-hash-right hash-pos lower))) (pcase side (`both (cons lower upper)) - (`nil lower) - (_ upper)))))) + (`nil + (aset org-element--cache-hash-left hash-pos lower)) + (_ + (aset org-element--cache-hash-right hash-pos upper))))))) (defun org-element--cache-put (element) "Store ELEMENT in current buffer's cache, if allowed." @@ -5859,7 +6284,7 @@ the cache." ;; the new element so `avl-tree-enter' can insert it at the ;; right spot in the cache. (let* ((keys (org-element--cache-find - (org-element-property :begin element) 'both)) + (org-element-begin element) 'both)) (new-key (org-element--cache-generate-key (and (car keys) (org-element--cache-key (car keys))) (cond ((cdr keys) (org-element--cache-key (cdr keys))) @@ -5875,7 +6300,7 @@ the cache." (org-element-property :org-element--cache-sync-key element) (org-element--format-element element))) (org-element-put-property element :cached t) - (when (memq (org-element-type element) '(headline inlinetask)) + (when (org-element-type-p element '(headline inlinetask)) (cl-incf org-element--headline-cache-size) (avl-tree-enter org-element--headline-cache element)) (cl-incf org-element--cache-size) @@ -5888,10 +6313,12 @@ Assume ELEMENT belongs to cache and that a cache is active." (org-element-put-property element :cached nil) (cl-decf org-element--cache-size) ;; Invalidate contents of parent. - (when (and (org-element-property :parent element) - (org-element-contents (org-element-property :parent element))) - (org-element-set-contents (org-element-property :parent element) nil)) - (when (memq (org-element-type element) '(headline inlinetask)) + (when (org-element-contents + ;; Cached elements cannot have deferred `:parent'. + (org-element-property-raw :parent element)) + (org-element-set-contents + (org-element-property-raw :parent element) nil)) + (when (org-element-type-p element '(headline inlinetask)) (cl-decf org-element--headline-cache-size) (avl-tree-delete org-element--headline-cache element)) (org-element--cache-log-message @@ -5903,10 +6330,10 @@ Assume ELEMENT belongs to cache and that a cache is active." If this warning appears regularly, please report the warning text to Org mode mailing list (M-x org-submit-bug-report)." (org-element-type element) (current-buffer) - (org-element-property :begin element) + (org-element-begin element) (org-element-property :org-element--cache-sync-key element)) (org-element-cache-reset) - (throw 'quit nil)) + (throw 'org-element--cache-quit nil)) (or (avl-tree-delete org-element--cache element) (progn ;; This should not happen, but if it is, would be better to know @@ -5916,10 +6343,10 @@ If this warning appears regularly, please report the warning text to Org mode ma If this warning appears regularly, please report the warning text to Org mode mailing list (M-x org-submit-bug-report)." (org-element-type element) (current-buffer) - (org-element-property :begin element) + (org-element-begin element) (org-element-property :org-element--cache-sync-key element)) (org-element-cache-reset) - (throw 'quit nil))))) + (throw 'org-element--cache-quit nil))))) ;;;; Synchronization @@ -5952,21 +6379,42 @@ optional argument PROPS is a list of keywords, only shift properties provided in that list. Properties are modified by side-effect." - (let ((properties (nth 1 element))) - ;; Shift `:structure' property for the first plain list only: it - ;; is the only one that really matters and it prevents from - ;; shifting it more than once. - (when (and (or (not props) (memq :structure props)) - (eq (org-element-type element) 'plain-list) - (not (eq (org-element-type (plist-get properties :parent)) 'item))) - (dolist (item (plist-get properties :structure)) - (cl-incf (car item) offset) - (cl-incf (nth 6 item) offset))) - (dolist (key '( :begin :contents-begin :contents-end :end - :post-affiliated :robust-begin :robust-end)) - (let ((value (and (or (not props) (memq key props)) - (plist-get properties key)))) - (and value (plist-put properties key (+ offset value))))))) + ;; Shift `:structure' property for the first plain list only: it + ;; is the only one that really matters and it prevents from + ;; shifting it more than once. + (when (and (not (zerop offset)) + (or (not props) (memq :structure props)) + (org-element-type-p element 'plain-list) + (not (org-element-type-p + ;; Cached elements cannot have deferred `:parent'. + (org-element-property-raw :parent element) + 'item))) + (let ((structure (org-element-property :structure element))) + (dolist (item structure) + (cl-incf (car item) offset) + (cl-incf (nth 6 item) offset)))) + ;; Clear :fragile cache when contents is changed. + (when props (org-element-put-property element :fragile-cache nil)) + ;; Do not use loop for inline expansion to work during compile time. + (unless (zerop offset) + (when (or (not props) (memq :begin props)) + (cl-incf (org-element-begin element) offset)) + (when (or (not props) (memq :end props)) + (cl-incf (org-element-end element) offset)) + (when (or (not props) (memq :post-affiliated props)) + (cl-incf (org-element-post-affiliated element) offset)) + (when (and (or (not props) (memq :contents-begin props)) + (org-element-contents-begin element)) + (cl-incf (org-element-contents-begin element) offset)) + (when (and (or (not props) (memq :contents-end props)) + (org-element-contents-end element)) + (cl-incf (org-element-contents-end element) offset)) + (when (and (or (not props) (memq :robust-begin props)) + (org-element-property :robust-begin element)) + (cl-incf (org-element-property :robust-begin element) offset)) + (when (and (or (not props) (memq :robust-end props)) + (org-element-property :robust-end element)) + (cl-incf (org-element-property :robust-end element) offset)))) (defvar org-element--cache-interrupt-C-g t "When non-nil, allow the user to abort `org-element--cache-sync'. @@ -5985,7 +6433,7 @@ It is a symbol among nil, t, or a number representing smallest level of modified headline. The level considers headline levels both before and after the modification.") -(defun org-element--cache-sync (buffer &optional threshold future-change offset) +(defun org-element--cache-sync (buffer &optional threshold future-change offset force) "Synchronize cache with recent modification in BUFFER. When optional argument THRESHOLD is non-nil, do the @@ -5998,13 +6446,18 @@ FUTURE-CHANGE, when non-nil, is a buffer position where changes not registered yet in the cache are going to happen. OFFSET is the change offset. It is used in `org-element--cache-submit-request', where cache is partially updated before current modification are -actually submitted." +actually submitted. + +FORCE, when non-nil will force the synchronization even when +`org-element--cache-active-p' returns nil." (when (buffer-live-p buffer) (org-with-base-buffer buffer ;; Do not sync when, for example, in the middle of ;; `combine-change-calls'. See the commentary inside - ;; `org-element--cache-active-p'. - (when (and org-element--cache-sync-requests (org-element--cache-active-p)) + ;; `org-element--cache-active-p'. Such situation may occur when + ;; sync timer triggers in the middle of `combine-change-calls'. + (when (and org-element--cache-sync-requests + (or force (org-element--cache-active-p))) ;; Check if the buffer have been changed outside visibility of ;; `org-element--cache-before-change' and `org-element--cache-after-change'. (if (/= org-element--cache-last-buffer-size (buffer-size)) @@ -6066,7 +6519,11 @@ The buffer is: %s\n Current command: %S\n Backtrace:\n%S" ;; Otherwise, reset keys. (if org-element--cache-sync-requests (org-element--cache-set-timer buffer) - (setq org-element--cache-change-warning nil) + ;; NOTE: We cannot reset + ;; `org-element--cache-change-warning' here as it might + ;; still be needed when synchronization is called by + ;; `org-element--cache-submit-request' before + ;; `org-element--cache-for-removal'. (setq org-element--cache-sync-keys-value (1+ org-element--cache-sync-keys-value))))))))) (defun org-element--cache-process-request @@ -6136,22 +6593,22 @@ completing the request." (if data ;; We found first element in cache starting at or ;; after REQUEST-KEY. - (let ((pos (org-element-property :begin data))) + (let ((pos (org-element-begin data))) ;; FIXME: Maybe simply (< pos end)? (if (<= pos end) (progn (org-element--cache-log-message "removing %S::%S" - (org-element-property :org-element--cache-sync-key data) - (org-element--format-element data)) + (org-element-property :org-element--cache-sync-key data) + (org-element--format-element data)) (cl-incf deletion-count) (org-element--cache-remove data) (when (and (> (log org-element--cache-size 2) 10) (> deletion-count (/ org-element--cache-size (log org-element--cache-size 2)))) (org-element--cache-log-message "Removed %S>N/LogN(=%S/%S) elements. Resetting cache to prevent performance degradation" - deletion-count - org-element--cache-size - (log org-element--cache-size 2)) + deletion-count + org-element--cache-size + (log org-element--cache-size 2)) (org-element-cache-reset) (throw 'org-element--cache-quit t))) ;; Done deleting everything starting before END. @@ -6215,8 +6672,8 @@ completing the request." ;; requests. (let ((next-request (nth 1 org-element--cache-sync-requests))) (org-element--cache-log-message "Phase 1: Unorderered requests. Merging: %S\n%S\n" - (let ((print-length 10) (print-level 3)) (prin1-to-string request)) - (let ((print-length 10) (print-level 3)) (prin1-to-string next-request))) + (let ((print-length 10) (print-level 3)) (prin1-to-string request)) + (let ((print-length 10) (print-level 3)) (prin1-to-string next-request))) (setf (org-element--request-key next-request) key) (setf (org-element--request-beg next-request) (org-element--request-beg request)) (setf (org-element--request-phase next-request) 1) @@ -6264,9 +6721,9 @@ completing the request." (let ((up parent)) (while (and up (or (not cached-before) - (> (org-element-property :begin up) - (org-element-property :begin cached-before)))) - (when (> (org-element-property :end up) future-change) + (> (org-element-begin up) + (org-element-begin cached-before)))) + (when (> (org-element-end up) future-change) ;; Offset future cache request. (org-element--cache-shift-positions up (- offset) @@ -6274,7 +6731,8 @@ completing the request." (org-element-property :robust-end up)) '(:contents-end :end :robust-end) '(:contents-end :end)))) - (setq up (org-element-property :parent up))))) + ;; Cached elements cannot have deferred `:parent'. + (setq up (org-element-property-raw :parent up))))) (org-element--cache-log-message "New parent at %S: %S::%S" limit @@ -6325,10 +6783,10 @@ completing the request." (org-element--cache-log-message "Reached next request.") (let ((next-request (nth 1 org-element--cache-sync-requests))) (unless (and (org-element-property :cached (org-element--request-parent next-request)) - (org-element-property :begin (org-element--request-parent next-request)) + (org-element-begin (org-element--request-parent next-request)) parent - (> (org-element-property :begin (org-element--request-parent next-request)) - (org-element-property :begin parent))) + (> (org-element-begin (org-element--request-parent next-request)) + (org-element-begin parent))) (setf (org-element--request-parent next-request) parent))) (throw 'org-element--cache-quit t)) ;; Handle interruption request. Update current request. @@ -6338,19 +6796,19 @@ completing the request." (setf (org-element--request-parent request) parent) (throw 'org-element--cache-interrupt nil)) ;; Shift element. - (unless (zerop offset) - (when (>= org-element--cache-diagnostics-level 3) - (org-element--cache-log-message "Shifting positions (𝝙%S) in %S::%S" - offset - (org-element-property :org-element--cache-sync-key data) - (org-element--format-element data))) - (org-element--cache-shift-positions data offset)) - (let ((begin (org-element-property :begin data))) + (when (>= org-element--cache-diagnostics-level 3) + (org-element--cache-log-message "Shifting positions (𝝙%S) in %S::%S" + offset + (org-element-property :org-element--cache-sync-key data) + (org-element--format-element data))) + (org-element--cache-shift-positions data offset) + (let ((begin (org-element-begin data))) ;; Update PARENT and re-parent DATA, only when ;; necessary. Propagate new structures for lists. - (while (and parent - (<= (org-element-property :end parent) begin)) - (setq parent (org-element-property :parent parent))) + (while (and parent (<= (org-element-end parent) begin)) + (setq parent + ;; Cached elements cannot have deferred `:parent'. + (org-element-property-raw :parent parent))) (cond ((and (not parent) (zerop offset)) (throw 'org-element--cache-quit nil)) ;; Consider scenario when DATA lays within ;; sensitive lines of PARENT that was found @@ -6367,21 +6825,25 @@ completing the request." ;; However, the paragraph element stored in ;; cache must be deleted instead. ((and parent - (or (not (memq (org-element-type parent) org-element-greater-elements)) - (and (org-element-property :contents-begin parent) - (< (org-element-property :begin data) (org-element-property :contents-begin parent))) - (and (org-element-property :contents-end parent) - (>= (org-element-property :begin data) (org-element-property :contents-end parent))) - (> (org-element-property :end data) (org-element-property :end parent)) - (and (org-element-property :contents-end data) - (> (org-element-property :contents-end data) (org-element-property :contents-end parent))))) + (or (not (org-element-type-p parent org-element-greater-elements)) + (and (org-element-contents-begin parent) + (< (org-element-begin data) (org-element-contents-begin parent))) + (and (org-element-contents-end parent) + (>= (org-element-begin data) (org-element-contents-end parent))) + (> (org-element-end data) (org-element-end parent)) + (and (org-element-contents-end data) + (> (org-element-contents-end data) (org-element-contents-end parent))))) (org-element--cache-log-message "org-element-cache: Removing obsolete element with key %S::%S" - (org-element-property :org-element--cache-sync-key data) - (org-element--format-element data)) + (org-element-property :org-element--cache-sync-key data) + (org-element--format-element data)) (org-element--cache-remove data) ;; We altered the tree structure. The tree ;; traversal needs to be restarted. (setf (org-element--request-key request) key) + ;; Make sure that we restart tree traversal + ;; past already shifted elements (before the + ;; removed DATA). + (setq start key) (setf (org-element--request-parent request) parent) ;; Restart tree traversal. (setq node (org-element--cache-root) @@ -6391,10 +6853,11 @@ completing the request." continue-flag t)) ((and parent (not (eq parent data)) - (let ((p (org-element-property :parent data))) + ;; Cached elements cannot have deferred `:parent'. + (let ((p (org-element-property-raw :parent data))) (or (not p) - (< (org-element-property :begin p) - (org-element-property :begin parent)) + (< (org-element-begin p) + (org-element-begin parent)) (unless (eq p parent) (not (org-element-property :cached p)) ;; (not (avl-tree-member-p org-element--cache p)) @@ -6402,10 +6865,11 @@ completing the request." (org-element--cache-log-message "Updating parent in %S\n Old parent: %S\n New parent: %S" (org-element--format-element data) - (org-element--format-element (org-element-property :parent data)) + (org-element--format-element + (org-element-property-raw :parent data)) (org-element--format-element parent)) - (when (and (eq 'org-data (org-element-type parent)) - (not (eq 'headline (org-element-type data)))) + (when (and (org-element-type-p parent 'org-data) + (not (org-element-type-p data 'headline))) ;; FIXME: This check is here to see whether ;; such error happens within ;; `org-element--cache-process-request' or somewhere @@ -6424,8 +6888,8 @@ If this warning appears regularly, please report the warning text to Org mode ma ;; interruption. (when (and threshold (> begin threshold)) (org-element--cache-log-message "Reached threshold %S: %S" - threshold - (org-element--format-element data)) + threshold + (org-element--format-element data)) (setq exit-flag t)))) (if continue-flag (setq continue-flag nil) @@ -6439,18 +6903,26 @@ If this warning appears regularly, please report the warning text to Org mode ma org-element--cache-size (let ((print-level 2)) (prin1-to-string org-element--cache-sync-requests))))) -(defsubst org-element--open-end-p (element) - "Check if ELEMENT in current buffer contains extra blank lines after -it and does not have closing term. - -Examples of such elements are: section, headline, org-data, -and footnote-definition." - (and (org-element-property :contents-end element) - (= (org-element-property :contents-end element) - (save-excursion - (goto-char (org-element-property :end element)) - (skip-chars-backward " \r\n\t") - (line-beginning-position 2))))) +(defun org-element--headline-parent-deferred (headline) + "Parse parent for HEADLINE." + (with-current-buffer (org-element-property :buffer headline) + (org-with-point-at (org-element-begin headline) + (if (or (bobp) (= 1 (org-element-property :true-level headline))) + ;; Top-level heading. Parent is `org-data'. + (org-element-org-data-parser) + (re-search-backward + (org-headline-re + (1- (org-element-property :true-level headline))) + nil 'move) + (let ((parent (org-element-at-point))) + (if (org-element-type-p parent 'headline) parent + ;; Before first headline. Assign `org-data'. + (org-element-lineage parent 'org-data t))))))) + +(defconst org-element--headline-parent-deferred + (org-element-deferred-create + t #'org-element--headline-parent-deferred) + "Constant holding deferred value for headline `:parent' property.") (defun org-element--parse-to (pos &optional syncp time-limit) "Parse elements in current section, down to POS. @@ -6466,212 +6938,194 @@ when the parsing should stop. The function throws `org-element--cache-interrupt' if the process stopped before finding the expected result." (catch 'exit - (save-match-data - (org-with-base-buffer nil - (org-with-wide-buffer - (goto-char pos) - (save-excursion - (end-of-line) - (skip-chars-backward " \r\t\n") - ;; Within blank lines at the beginning of buffer, return nil. - (when (bobp) (throw 'exit nil))) - (let* ((cached (and (org-element--cache-active-p) - (org-element--cache-find pos nil))) - (mode (org-element-property :mode cached)) - element next) - (cond - ;; Nothing in cache before point: start parsing from first - ;; element in buffer down to POS or from the beginning of the - ;; file. - ((and (not cached) (org-element--cache-active-p)) + (org-with-base-buffer nil + (org-with-wide-buffer + (goto-char pos) + (save-excursion + (forward-line 1) + (skip-chars-backward " \r\t\n") + ;; Within blank lines at the beginning of buffer, return nil. + (when (bobp) (throw 'exit nil))) + (let* ((cached (and (org-element--cache-active-p) + (org-element--cache-find pos nil))) + (mode (org-element-property :mode cached)) + element next) + (cond + ;; Nothing in cache before point: start parsing from first + ;; element in buffer down to POS or from the beginning of the + ;; file. + ((and (not cached) (org-element--cache-active-p)) + (setq element (org-element-org-data-parser)) + (unless (org-element-begin element) + (org-element--cache-warn "Error parsing org-data. Got %S\nPlease report to Org mode mailing list (M-x org-submit-bug-report)." element)) + (org-element--cache-log-message + "Nothing in cache. Adding org-data: %S" + (org-element--format-element element)) + (org-element--cache-put element) + (goto-char (org-element-contents-begin element)) + (setq mode 'org-data)) + ;; Nothing in cache before point because cache is not active. + ;; Parse from previous heading to avoid re-parsing the whole + ;; buffer above. Arrange `:parent' to be calculated on demand. + ((not cached) + (forward-line 1) ; ensure the end of current heading. + (if (re-search-backward + (org-get-limited-outline-regexp t) + nil 'move) + (progn + (setq element (org-element-headline-parser nil 'fast)) + (org-element-put-property + element :parent + org-element--headline-parent-deferred) + (setq mode 'planning) + (forward-line)) (setq element (org-element-org-data-parser)) - (unless (org-element-property :begin element) - (org-element--cache-warn "Error parsing org-data. Got %S\nPlease report to Org mode mailing list (M-x org-submit-bug-report)." element)) - (org-element--cache-log-message - "Nothing in cache. Adding org-data: %S" - (org-element--format-element element)) - (org-element--cache-put element) - (goto-char (org-element-property :contents-begin element)) (setq mode 'org-data)) - ;; Nothing in cache before point because cache is not active. - ;; Parse from previous heading to avoid re-parsing the whole - ;; buffer above. This comes at the cost of not calculating - ;; `:parent' property for headings. - ((not cached) - (if (org-with-limited-levels (outline-previous-heading)) - (progn - (setq element (org-element-headline-parser nil 'fast)) - (setq mode 'planning) - (forward-line)) - (setq element (org-element-org-data-parser)) - (setq mode 'org-data)) - (org-skip-whitespace) - (beginning-of-line)) - ;; Check if CACHED or any of its ancestors contain point. - ;; - ;; If there is such an element, we inspect it in order to know - ;; if we return it or if we need to parse its contents. - ;; Otherwise, we just start parsing from location, which is - ;; right after the top-most element containing CACHED but - ;; still before POS. - ;; - ;; As a special case, if POS is at the end of the buffer, we - ;; want to return the innermost element ending there. - ;; - ;; Also, if we find an ancestor and discover that we need to - ;; parse its contents, make sure we don't start from - ;; `:contents-begin', as we would otherwise go past CACHED - ;; again. Instead, in that situation, we will resume parsing - ;; from NEXT, which is located after CACHED or its higher - ;; ancestor not containing point. - (t - (let ((up cached) - (pos (if (= (point-max) pos) (1- pos) pos))) - (while (and up (<= (org-element-property :end up) pos)) - (goto-char (org-element-property :end up)) - (setq element up - mode (org-element--next-mode (org-element-property :mode element) (org-element-type element) nil) - up (org-element-property :parent up) - next (point))) - (when up (setq element up))))) - ;; Parse successively each element until we reach POS. - (let ((end (or (org-element-property :end element) (point-max))) - (parent (org-element-property :parent element))) - (while t - (when (org-element--cache-interrupt-p time-limit) - (throw 'org-element--cache-interrupt nil)) - (when (and inhibit-quit org-element--cache-interrupt-C-g quit-flag) - (when quit-flag - (cl-incf org-element--cache-interrupt-C-g-count) - (setq quit-flag nil)) - (when (>= org-element--cache-interrupt-C-g-count - org-element--cache-interrupt-C-g-max-count) - (setq quit-flag t) - (setq org-element--cache-interrupt-C-g-count 0) - (org-element-cache-reset) - (error "org-element: Parsing aborted by user. Cache has been cleared. -If you observe Emacs hangs frequently, please report this to Org mode mailing list (M-x org-submit-bug-report).")) - (message (substitute-command-keys - "`org-element--parse-buffer': Suppressed `\\[keyboard-quit]'. Press `\\[keyboard-quit]' %d more times to force interruption.") - (- org-element--cache-interrupt-C-g-max-count - org-element--cache-interrupt-C-g-count))) - (unless element - ;; Do not try to parse within blank at EOB. - (unless (save-excursion - (org-skip-whitespace) - (eobp)) - (org-element-with-disabled-cache - (setq element (org-element--current-element - end 'element mode - (org-element-property :structure parent))))) - ;; Make sure that we return referenced element in cache - ;; that can be altered directly. - (if element - (setq element (or (org-element--cache-put element) element)) - ;; Nothing to parse (i.e. empty file). - (throw 'exit parent)) - (unless (or (not (org-element--cache-active-p)) parent) - (org-element--cache-warn - "Got empty parent while parsing. Please report it to Org mode mailing list (M-x org-submit-bug-report).\n Backtrace:\n%S" - (when (and (fboundp 'backtrace-get-frames) - (fboundp 'backtrace-to-string)) - (backtrace-to-string (backtrace-get-frames 'backtrace)) - (org-element-cache-reset) - (error "org-element--cache: Emergency exit")))) - (org-element-put-property element :parent parent)) - (let ((elem-end (org-element-property :end element)) - (type (org-element-type element))) - (cond - ;; Skip any element ending before point. Also skip - ;; element ending at point (unless it is also the end of - ;; buffer) since we're sure that another element begins - ;; after it. - ((and (<= elem-end pos) (/= (point-max) elem-end)) - ;; Avoid parsing headline siblings above. - (goto-char elem-end) - (when (eq type 'headline) - (save-match-data - (unless (when (and (/= 1 (org-element-property :level element)) - (re-search-forward - (rx-to-string - `(and bol (repeat 1 ,(1- (let ((level (org-element-property :level element))) - (if org-odd-levels-only (1- (* level 2)) level))) - "*") - " ")) - pos t)) - (beginning-of-line) - t) - ;; There are headings with lower level than - ;; ELEMENT between ELEM-END and POS. Siblings - ;; may exist though. Parse starting from the - ;; last sibling or from ELEM-END if there are - ;; no other siblings. - (goto-char pos) - (unless - (re-search-backward - (rx-to-string - `(and bol (repeat ,(let ((level (org-element-property :level element))) - (if org-odd-levels-only (1- (* level 2)) level)) - "*") - " ")) - elem-end t) - ;; Roll-back to normal parsing. - (goto-char elem-end))))) - (setq mode (org-element--next-mode mode type nil))) - ;; A non-greater element contains point: return it. - ((not (memq type org-element-greater-elements)) - (throw 'exit (if syncp parent element))) - ;; Otherwise, we have to decide if ELEMENT really - ;; contains POS. In that case we start parsing from - ;; contents' beginning. - ;; - ;; If POS is at contents' beginning but it is also at - ;; the beginning of the first item in a list or a table. - ;; In that case, we need to create an anchor for that - ;; list or table, so return it. - ;; - ;; Also, if POS is at the end of the buffer, no element - ;; can start after it, but more than one may end there. - ;; Arbitrarily, we choose to return the innermost of - ;; such elements. - ((let ((cbeg (org-element-property :contents-begin element)) - (cend (org-element-property :contents-end element))) - (when (and cbeg cend - (or (< cbeg pos) - (and (= cbeg pos) - (not (memq type '(plain-list table))))) - (or (> cend pos) - ;; When we are at cend or within blank - ;; lines after, it is a special case: - ;; 1. At the end of buffer we return - ;; the innermost element. - ;; 2. At cend of element with return - ;; that element. - ;; 3. At the end of element, we would - ;; return in the earlier cond form. - ;; 4. Within blank lines after cend, - ;; when element does not have a - ;; closing keyword, we return that - ;; outermost element, unless the - ;; outermost element is a non-empty - ;; headline. In the latter case, we - ;; return the outermost element inside - ;; the headline section. - (and (org-element--open-end-p element) - (or (= (org-element-property :end element) (point-max)) - (and (>= pos (org-element-property :contents-end element)) - (memq (org-element-type element) '(org-data section headline))))))) - (goto-char (or next cbeg)) - (setq mode (if next mode (org-element--next-mode mode type t)) - next nil - parent element - end (if (org-element--open-end-p element) - (org-element-property :end element) - (org-element-property :contents-end element)))))) - ;; Otherwise, return ELEMENT as it is the smallest - ;; element containing POS. - (t (throw 'exit (if syncp parent element))))) - (setq element nil))))))))) + (org-skip-whitespace) + (forward-line 0)) + ;; Check if CACHED or any of its ancestors contain point. + ;; + ;; If there is such an element, we inspect it in order to know + ;; if we return it or if we need to parse its contents. + ;; Otherwise, we just start parsing from location, which is + ;; right after the top-most element containing CACHED but + ;; still before POS. + ;; + ;; As a special case, if POS is at the end of the buffer, we + ;; want to return the innermost element ending there. + ;; + ;; Also, if we find an ancestor and discover that we need to + ;; parse its contents, make sure we don't start from + ;; `:contents-begin', as we would otherwise go past CACHED + ;; again. Instead, in that situation, we will resume parsing + ;; from NEXT, which is located after CACHED or its higher + ;; ancestor not containing point. + (t + (let ((up cached) + (pos (if (= (point-max) pos) (1- pos) pos))) + (while (and up (<= (org-element-end up) pos)) + (setq next (org-element-end up) + element up + mode (org-element--next-mode (org-element-property :mode element) (org-element-type element) nil) + ;; Cached elements cannot have deferred `:parent'. + up (org-element-property-raw :parent up))) + (when next (goto-char next)) + (when up (setq element up))))) + ;; Parse successively each element until we reach POS. + (let ((end (or (org-element-end element) (point-max))) + (parent (org-element-property-raw :parent element))) + (while t + (when (org-element--cache-interrupt-p time-limit) + (throw 'org-element--cache-interrupt nil)) + (when (and inhibit-quit org-element--cache-interrupt-C-g quit-flag) + (when quit-flag + (cl-incf org-element--cache-interrupt-C-g-count) + (setq quit-flag nil)) + (when (>= org-element--cache-interrupt-C-g-count + org-element--cache-interrupt-C-g-max-count) + (setq quit-flag t) + (setq org-element--cache-interrupt-C-g-count 0) + (org-element-cache-reset) + (error "org-element: Parsing aborted by user. Cache has been cleared. +If you observe Emacs hangs frequently, please report this to Org mode mailing list (M-x org-submit-bug-report)")) + (message (substitute-command-keys + "`org-element--parse-to': Suppressed `\\[keyboard-quit]'. Press `\\[keyboard-quit]' %d more times to force interruption.") + (- org-element--cache-interrupt-C-g-max-count + org-element--cache-interrupt-C-g-count))) + (unless element + ;; Do not try to parse within blank at EOB. + (unless (save-excursion + (org-skip-whitespace) + (eobp)) + (setq element (org-element--current-element + end 'element mode + (org-element-property :structure parent)))) + ;; Make sure that we return referenced element in cache + ;; that can be altered directly. + (if element + (setq element (or (org-element--cache-put element) element)) + ;; Nothing to parse (i.e. empty file). + (throw 'exit parent)) + (unless (or parent (not (org-element--cache-active-p))) + (org-element--cache-warn + "Got empty parent while parsing. Please report it to Org mode mailing list (M-x org-submit-bug-report).\n Backtrace:\n%S" + (when (and (fboundp 'backtrace-get-frames) + (fboundp 'backtrace-to-string)) + (backtrace-to-string (backtrace-get-frames 'backtrace)) + (org-element-cache-reset) + (error "org-element--cache: Emergency exit")))) + (org-element-put-property element :parent parent)) + (let ((elem-end (org-element-end element)) + (type (org-element-type element))) + (cond + ;; Skip any element ending before point. Also skip + ;; element ending at point (unless it is also the end of + ;; buffer) since we're sure that another element begins + ;; after it. + ((and (<= elem-end pos) (/= (point-max) elem-end)) + ;; Avoid parsing headline siblings above. + (goto-char elem-end) + (when (eq type 'headline) + (unless (when (and (/= 1 (org-element-property :true-level element)) + (re-search-forward + (org-headline-re (1- (org-element-property :true-level element))) + pos t)) + (forward-line 0) + t) + ;; There are headings with lower level than + ;; ELEMENT between ELEM-END and POS. Siblings + ;; may exist though. Parse starting from the + ;; last sibling or from ELEM-END if there are + ;; no other siblings. + (goto-char pos) + (unless + (re-search-backward + (org-headline-re (org-element-property :true-level element)) + elem-end t) + ;; Roll-back to normal parsing. + (goto-char elem-end)))) + (setq mode (org-element--next-mode mode type nil))) + ;; A non-greater element contains point: return it. + ((not (memq type org-element-greater-elements)) + (throw 'exit (if syncp parent element))) + ;; Otherwise, we have to decide if ELEMENT really + ;; contains POS. In that case we start parsing from + ;; contents' beginning. + ;; + ;; If POS is at contents' beginning but it is also at + ;; the beginning of the first item in a list or a table. + ;; In that case, we need to create an anchor for that + ;; list or table, so return it. + ;; + ;; Also, if POS is at the end of the buffer, no element + ;; can start after it, but more than one may end there. + ;; Arbitrarily, we choose to return the innermost of + ;; such elements. + ((let ((cbeg (org-element-contents-begin element)) + (cend (org-element-contents-end element))) + (when (and cbeg cend + (or (< cbeg pos) + (and (= cbeg pos) + (not (memq type '(plain-list table))))) + (or (> cend pos) + ;; When we are at cend or within blank + ;; lines after, it is a special case: + ;; 1. At the end of buffer we return + ;; the innermost element. + (= pos cend (point-max)) + ;; 2. At cend of element with return + ;; that element (thus, no need to + ;; parse inside). + nil)) + (goto-char (or next cbeg)) + (setq mode (if next mode (org-element--next-mode mode type t)) + next nil + parent element + end (org-element-contents-end element))))) + ;; Otherwise, return ELEMENT as it is the smallest + ;; element containing POS. + (t (throw 'exit (if syncp parent element))))) + (setq element nil)))))))) ;;;; Staging Buffer Changes @@ -6703,20 +7157,8 @@ The function returns the new value of `org-element--cache-change-warning'." (setq org-element--cache-change-tic (buffer-chars-modified-tick)) (setq org-element--cache-last-buffer-size (buffer-size)) (goto-char beg) - (beginning-of-line) - (let ((bottom (save-excursion - (goto-char end) - (if (and (bolp) - ;; When beg == end, still extent to eol. - (> (point) beg)) - ;; FIXME: Potential pitfall. - ;; We are appending to an element end. - ;; Unless the last inserted char is not - ;; newline, the next element is not broken - ;; and does not need to be purged from the - ;; cache. - end - (line-end-position))))) + (forward-line 0) + (let ((bottom (save-excursion (goto-char end) (line-end-position)))) (prog1 ;; Use the worst change warning to not miss important edits. ;; This function is called before edit and after edit by @@ -6732,12 +7174,13 @@ The function returns the new value of `org-element--cache-change-warning'." (let ((org-element--cache-change-warning-before org-element--cache-change-warning) (org-element--cache-change-warning-after)) (setq org-element--cache-change-warning-after + ;; We must preserve match data when called as `before-change-functions'. (save-match-data (let ((case-fold-search t)) (when (re-search-forward org-element--cache-sensitive-re bottom t) (goto-char beg) - (beginning-of-line) + (forward-line 0) (let (min-level) (cl-loop while (re-search-forward (rx-to-string @@ -6749,7 +7192,7 @@ The function returns the new value of `org-element--cache-change-warning'." do (setq min-level (1- (length (match-string 0)))) until (= min-level 1)) (goto-char beg) - (beginning-of-line) + (forward-line 0) (or (and min-level (org-reduced-level min-level)) (when (looking-at-p "^[ \t]*#\\+CATEGORY:") 'org-data) @@ -6773,14 +7216,14 @@ The function returns the new value of `org-element--cache-change-warning'." (defun org-element--cache-after-change (beg end pre) "Update buffer modifications for current buffer. -BEG and END are the beginning and end of the range of changed +BEG, END, and PRE are the beginning and end of the range of changed text, and the length in bytes of the pre-change text replaced by that range. See `after-change-functions' for more information." (org-with-base-buffer nil (when (org-element--cache-active-p t) (when (not (eq org-element--cache-change-tic (buffer-chars-modified-tick))) (org-element--cache-log-message "After change") - (setq org-element--cache-change-warning (org-element--cache-before-change beg end)) + (org-element--cache-before-change beg end) ;; If beg is right after spaces in front of an element, we ;; risk affecting previous element, so move beg to bol, making ;; sure that we capture preceding element. @@ -6790,6 +7233,7 @@ that range. See `after-change-functions' for more information." (line-beginning-position))) ;; Store synchronization request. (let ((offset (- end beg pre))) + ;; We must preserve match data when called as `after-change-functions'. (save-match-data (org-element--cache-submit-request beg (- end offset) offset))) ;; Activate a timer to process the request during idle time. @@ -6798,6 +7242,16 @@ that range. See `after-change-functions' for more information." (defun org-element--cache-setup-change-functions () "Setup `before-change-functions' and `after-change-functions'." (when (and (derived-mode-p 'org-mode) org-element-use-cache) + ;; Clear copied local cache to avoid extra memory usage. + ;; We only use cache stored in the base buffer. + (when (buffer-base-buffer) + (setq-local org-element--cache nil) + (setq-local org-element--headline-cache nil)) + ;; Register current buffer in `org-fold-core--indirect-buffers' to + ;; be used within `org-fold-core-cycle-over-indirect-buffers'. + ;; FIXME: We should eventually factor out indirect buffer tracking + ;; from org-fold-core. + (org-fold-core-decouple-indirect-buffer-folds) (add-hook 'before-change-functions #'org-element--cache-before-change nil t) ;; Run `org-element--cache-after-change' early to handle cases @@ -6817,7 +7271,7 @@ when buffer modifications are mixed with cache requests. However, large automated edits inserting/deleting many headlines are somewhat slower by default (as in `org-archive-subtree'). Let-binding this variable to non-nil will reduce cache latency after every singular edit -(`after-change-functions') at the cost of slower cache queries.") +\(`after-change-functions') at the cost of slower cache queries.") (defun org-element--cache-for-removal (beg end offset) "Return first element to remove from cache. @@ -6841,12 +7295,12 @@ known element in cache (it may start after END)." (if (not before) after ;; If BEFORE is a keyword, it may need to be removed to become ;; an affiliated keyword. - (when (eq 'keyword (org-element-type before)) + (when (org-element-type-p before 'keyword) (let ((prev before)) - (while (eq 'keyword (org-element-type prev)) + (while (org-element-type-p prev 'keyword) (setq before prev - beg (org-element-property :begin prev)) - (setq prev (org-element--cache-find (1- (org-element-property :begin before))))))) + beg (org-element-begin prev)) + (setq prev (org-element--cache-find (1- (org-element-begin before))))))) (let ((up before) (robust-flag t)) (while up @@ -6859,8 +7313,8 @@ known element in cache (it may start after END)." ;; Sensitive change. This is ;; unconditionally non-robust change. (not org-element--cache-change-warning) - (let ((cbeg (org-element-property :contents-begin up)) - (cend (org-element-property :contents-end up))) + (let ((cbeg (org-element-contents-begin up)) + (cend (org-element-contents-end up))) (and cbeg (<= cbeg beg) (or (> cend end) @@ -6890,9 +7344,9 @@ known element in cache (it may start after END)." (or (not (numberp org-element--cache-change-warning)) (> org-element--cache-change-warning (org-element-property :level up))) - (org-with-point-at (org-element-property :contents-begin up) + (org-with-point-at (org-element-contents-begin up) (unless - (save-match-data + (progn (when (looking-at-p org-element-planning-line-re) (forward-line)) (when (looking-at org-property-drawer-re) @@ -6909,9 +7363,8 @@ known element in cache (it may start after END)." ;; Should not see property ;; drawer within changed ;; region. - (save-match-data - (or (not (looking-at org-property-drawer-re)) - (> beg (match-end 0))))))) + (or (not (looking-at org-property-drawer-re)) + (> beg (match-end 0)))))) (_ 'robust))))) ;; UP is a robust greater element containing changes. ;; We only need to extend its ending boundaries. @@ -6923,7 +7376,8 @@ known element in cache (it may start after END)." '(:contents-end :end :robust-end) '(:contents-end :end))) (org-element--cache-log-message - "Shifting end positions of robust parent: %S" + "Shifting end positions of robust parent (warning %S): %S" + org-element--cache-change-warning (org-element--format-element up))) (unless (or ;; UP is non-robust. Yet, if UP is headline, flagging @@ -6933,30 +7387,31 @@ known element in cache (it may start after END)." ;; starting from old :begin position, we do not care that ;; its boundaries could have extended to shrunk - we ;; will re-parent and shift them anyway. - (and (eq 'headline (org-element-type up)) + (and (org-element-type-p up 'headline) (not org-element--cache-avoid-synchronous-headline-re-parsing) ;; The change is not inside headline. Not ;; updating here. - (not (<= beg (org-element-property :begin up))) - (not (> end (org-element-property :end up))) - (let ((current (org-with-point-at (org-element-property :begin up) + (not (<= beg (org-element-begin up))) + (not (> end (org-element-end up))) + (let ((current (org-with-point-at (org-element-begin up) (org-element-with-disabled-cache (and (looking-at-p org-element-headline-re) - (org-element-headline-parser)))))) - (when (eq 'headline (org-element-type current)) + (org-element-headline-parser nil 'fast)))))) + (when (org-element-type-p current 'headline) (org-element--cache-log-message - "Found non-robust headline that can be updated individually: %S" + "Found non-robust headline that can be updated individually (warning %S): %S" + org-element--cache-change-warning (org-element--format-element current)) - (org-element-set-element up current) + (org-element-set up current org-element--cache-element-properties) t))) ;; If UP is org-data, the situation is similar to ;; headline case. We just need to re-parse the ;; org-data itself, unless the change is made ;; within blank lines at BOB (that could ;; potentially alter first-section). - (when (and (eq 'org-data (org-element-type up)) - (>= beg (org-element-property :contents-begin up))) - (org-element-set-element up (org-with-point-at 1 (org-element-org-data-parser))) + (when (and (org-element-type-p up 'org-data) + (>= beg (org-element-contents-begin up))) + (org-element-set up (org-with-point-at 1 (org-element-org-data-parser)) org-element--cache-element-properties) (org-element--cache-log-message "Found non-robust change invalidating org-data. Re-parsing: %S" (org-element--format-element up)) @@ -6966,12 +7421,12 @@ known element in cache (it may start after END)." (org-element--format-element up)) (setq before up) (when robust-flag (setq robust-flag nil)))) - (unless (or (org-element-property :parent up) - (eq 'org-data (org-element-type up))) + (unless (or (org-element-property-raw :parent up) + (org-element-type-p up 'org-data)) (org-element--cache-warn "Got element without parent. Please report it to Org mode mailing list (M-x org-submit-bug-report).\n%S" up) (org-element-cache-reset) (error "org-element--cache: Emergency exit")) - (setq up (org-element-property :parent up))) + (setq up (org-element-property-raw :parent up))) ;; We're at top level element containing ELEMENT: if it's ;; altered by buffer modifications, it is first element in ;; cache to be removed. Otherwise, that first element is the @@ -6979,7 +7434,7 @@ known element in cache (it may start after END)." ;; ;; As a special case, do not remove BEFORE if it is a robust ;; container for current changes. - (if (or (< (org-element-property :end before) beg) robust-flag) after + (if (or (< (org-element-end before) beg) robust-flag) after before))))) (defun org-element--cache-submit-request (beg end offset) @@ -7037,12 +7492,13 @@ change, as an integer." (setf (org-element--request-key next) (org-element--cache-key first)) (setf (org-element--request-beg next) - (org-element-property :begin first)) + (org-element-begin first)) (setf (org-element--request-end next) - (max (org-element-property :end first) + (max (org-element-end first) (org-element--request-end next))) (setf (org-element--request-parent next) - (org-element-property :parent first)))) + ;; Cached elements cannot have deferred `:parent'. + (org-element-property-raw :parent first)))) ;; The current and NEXT modifications are intersecting ;; with current modification starting before NEXT and NEXT ;; ending after current. We need to update the common @@ -7060,11 +7516,13 @@ change, as an integer." "Current request intersects with next. Updating. New parent: %S" (org-element--format-element first)) (setf (org-element--request-key next) (org-element--cache-key first)) - (setf (org-element--request-beg next) (org-element-property :begin first)) + (setf (org-element--request-beg next) (org-element-begin first)) (setf (org-element--request-end next) - (max (org-element-property :end first) + (max (org-element-end first) (org-element--request-end next))) - (setf (org-element--request-parent next) (org-element-property :parent first)))))) + (setf (org-element--request-parent next) + ;; Cached elements cannot have deferred `:parent'. + (org-element-property-raw :parent first)))))) ;; Ensure cache is correct up to END. Also make sure that NEXT, ;; if any, is no longer a 0-phase request, thus ensuring that ;; phases are properly ordered. We need to provide OFFSET as @@ -7072,10 +7530,10 @@ change, as an integer." ;; yet to the otherwise correct part of the cache (i.e, before ;; the first request). (org-element--cache-log-message "Adding new phase 0 request") - (when next (org-element--cache-sync (current-buffer) end beg offset)) + (when next (org-element--cache-sync (current-buffer) end beg offset 'force)) (let ((first (org-element--cache-for-removal beg end offset))) (if first - (push (let ((first-beg (org-element-property :begin first)) + (push (let ((first-beg (org-element-begin first)) (key (org-element--cache-key first))) (cond ;; When changes happen before the first known @@ -7091,10 +7549,11 @@ change, as an integer." ;; The current modification is completely inside ;; FIRST. Clear and update cached elements in ;; region containing FIRST. - ((let ((first-end (org-element-property :end first))) + ((let ((first-end (org-element-end first))) (when (> first-end end) (org-element--cache-log-message "Extending to non-robust element %S" (org-element--format-element first)) - (vector key first-beg first-end offset (org-element-property :parent first) 0)))) + (vector key first-beg first-end offset + (org-element-property-raw :parent first) 0)))) (t ;; Now, FIRST is the first element after BEG or ;; non-robust element containing BEG. However, @@ -7105,16 +7564,17 @@ change, as an integer." ;; parent of FIRST and everything inside ;; BEG..END. (let* ((element (org-element--cache-find end)) - (element-end (org-element-property :end element)) + (element-end (org-element-end element)) (up element)) (while (and (not (eq up first)) - (setq up (org-element-property :parent up)) - (>= (org-element-property :begin up) first-beg)) + ;; Cached elements cannot have deferred `:parent'. + (setq up (org-element-property-raw :parent up)) + (>= (org-element-begin up) first-beg)) ;; Note that UP might have been already ;; shifted if it is a robust element. After ;; deletion, it can put it's end before yet ;; unprocessed ELEMENT. - (setq element-end (max (org-element-property :end up) element-end) + (setq element-end (max (org-element-end up) element-end) element up)) ;; Extend region to remove elements between ;; beginning of first and the end of outermost @@ -7157,17 +7617,19 @@ Return non-nil when verification failed." ;; Verify correct parent for the element. (unless (or (not org-element--cache-self-verify) (org-element-property :parent element) - (eq 'org-data (org-element-type element))) + (org-element-type-p element 'org-data)) (org-element--cache-warn "Got element without parent (cache active?: %S). Please report it to Org mode mailing list (M-x org-submit-bug-report).\n%S" (org-element--cache-active-p) element) (org-element-cache-reset)) (when (and org-element--cache-self-verify (org-element--cache-active-p) - (eq 'headline (org-element-type element)) + (org-element-type-p element 'headline) ;; Avoid too much slowdown (< (random 1000) (* 1000 org-element--cache-self-verify-frequency))) - (org-with-point-at (org-element-property :begin element) + (org-with-point-at (org-element-begin element) (org-element-with-disabled-cache (org-up-heading-or-point-min)) - (unless (or (= (point) (org-element-property :begin (org-element-property :parent element))) + (unless (or (= (point) + (org-element-begin + (org-element-property :parent element))) (eq (point) (point-min))) (org-element--cache-warn "Cached element has wrong parent in %s. Resetting. @@ -7176,26 +7638,29 @@ The element is: %S\n The parent is: %S\n The real parent is: %S" (buffer-name (current-buffer)) (org-element--format-element element) (org-element--format-element (org-element-property :parent element)) - (org-element--format-element (org-element--current-element (org-element-property :end (org-element-property :parent element))))) + (org-element--format-element + (org-element--current-element + (org-element-end (org-element-property :parent element))))) (org-element-cache-reset)) - (org-element--cache-verify-element (org-element-property :parent element)))) + (org-element--cache-verify-element + (org-element-property :parent element)))) ;; Verify the element itself. (when (and org-element--cache-self-verify (org-element--cache-active-p) element - (not (memq (org-element-type element) '(section org-data))) + (not (org-element-type-p element '(section org-data))) ;; Avoid too much slowdown (< (random 1000) (* 1000 org-element--cache-self-verify-frequency))) - (let ((real-element (let (org-element-use-cache) + (let ((real-element (org-element-with-disabled-cache (org-element--parse-to - (if (memq (org-element-type element) '(table-row item)) - (1+ (org-element-property :begin element)) - (org-element-property :begin element)))))) + (if (org-element-type-p element '(table-row item)) + (1+ (org-element-begin element)) + (org-element-begin element)))))) (unless (and (eq (org-element-type real-element) (org-element-type element)) - (eq (org-element-property :begin real-element) (org-element-property :begin element)) - (eq (org-element-property :end real-element) (org-element-property :end element)) - (eq (org-element-property :contents-begin real-element) (org-element-property :contents-begin element)) - (eq (org-element-property :contents-end real-element) (org-element-property :contents-end element)) + (eq (org-element-begin real-element) (org-element-begin element)) + (eq (org-element-end real-element) (org-element-end element)) + (eq (org-element-contents-begin real-element) (org-element-contents-begin element)) + (eq (org-element-contents-end real-element) (org-element-contents-end element)) (or (not (org-element-property :ID real-element)) (string= (org-element-property :ID real-element) (org-element-property :ID element)))) (org-element--cache-warn "(%S) Cached element is incorrect in %s. (Cache tic up to date: %S) Resetting. @@ -7208,15 +7673,20 @@ The element is: %S\n The real element is: %S\n Cache around :begin:\n%S\n%S\n%S" "no" "yes") (org-element--format-element element) (org-element--format-element real-element) - (org-element--cache-find (1- (org-element-property :begin real-element))) - (car (org-element--cache-find (org-element-property :begin real-element) 'both)) - (cdr (org-element--cache-find (org-element-property :begin real-element) 'both))) + (org-element--format-element (org-element--cache-find (1- (org-element-begin real-element)))) + (org-element--format-element (car (org-element--cache-find (org-element-begin real-element) 'both))) + (org-element--format-element (cdr (org-element--cache-find (org-element-begin real-element) 'both)))) (org-element-cache-reset)))))) ;;; Cache persistence (defun org-element--cache-persist-before-write (container &optional associated) - "Sync cache before saving." + "Sync element cache for CONTAINER and ASSOCIATED item before saving. +This function is intended to be used in `org-persist-before-write-hook'. + +Prevent writing to disk cache when cache is disabled in the CONTAINER +buffer. Otherwise, cleanup cache sync keys, unreadable :buffer +properties, and verify cache consistency." (when (equal container '(elisp org-element--cache)) (if (and org-element-use-cache (plist-get associated :file) @@ -7228,39 +7698,78 @@ The element is: %S\n The real element is: %S\n Cache around :begin:\n%S\n%S\n%S" (org-with-wide-buffer (org-element--cache-sync (current-buffer) (point-max)) ;; Cleanup cache request keys to avoid collisions during next - ;; Emacs session. + ;; Emacs session. Cleanup known non-printable objects. (avl-tree-mapc (lambda (el) - (org-element-put-property el :org-element--cache-sync-key nil)) + (org-element-put-property el :org-element--cache-sync-key nil) + (org-element-map el t + (lambda (el2) + (unless (org-element-type-p el2 'plain-text) + (org-element-put-property el2 :buffer nil))) + nil nil nil 'with-affiliated 'no-undefer) + (let ((org-element--cache-self-verify-frequency 1.0)) + (when (and org-element--cache-self-verify-before-persisting + (org-element--cache-verify-element el)) + (error "Cache verification failed: aborting")))) org-element--cache) nil) 'forbid)) 'forbid))) (defun org-element--cache-persist-before-read (container &optional associated) - "Avoid reading cache before Org mode is loaded." + "Avoid reading cache for CONTAINER and ASSOCIATED before Org mode is loaded. +This function is intended to be used in `org-persist-before-read-hook'. + +Also, prevent reading cache when the buffer CONTAINER hash is not +consistent with the cache." (when (equal container '(elisp org-element--cache)) + (org-element--cache-log-message "Loading persistent cache for %s" (plist-get associated :file)) (if (not (and (plist-get associated :file) (get-file-buffer (plist-get associated :file)))) - 'forbid + (progn + (org-element--cache-log-message "%s does not have a buffer: not loading cache" (plist-get associated :file)) + 'forbid) (with-current-buffer (get-file-buffer (plist-get associated :file)) (unless (and org-element-use-cache org-element-cache-persistent (derived-mode-p 'org-mode) (equal (secure-hash 'md5 (current-buffer)) (plist-get associated :hash))) + (org-element--cache-log-message "Cache is not current (or persistence is disabled) in %s" (plist-get associated :file)) 'forbid))))) (defun org-element--cache-persist-after-read (container &optional associated) - "Setup restored cache." + "Setup restored cache for CONTAINER and ASSOCIATED. +Re-fill :buffer properties for cache elements (buffer objects cannot +be written onto disk). Also, perform some consistency checks to +prevent loading corrupted cache." (when (and (plist-get associated :file) (get-file-buffer (plist-get associated :file))) (with-current-buffer (get-file-buffer (plist-get associated :file)) (when (and org-element-use-cache org-element-cache-persistent) - (when (and (equal container '(elisp org-element--cache)) org-element--cache) - (setq-local org-element--cache-size (avl-tree-size org-element--cache))) - (when (and (equal container '(elisp org-element--headline-cache)) org-element--headline-cache) - (setq-local org-element--headline-cache-size (avl-tree-size org-element--headline-cache))))))) + (catch 'abort + (when (and (equal container '(elisp org-element--cache)) org-element--cache) + ;; Restore `:buffer' property. + (avl-tree-mapc + (lambda (el) + (org-element-map el t + (lambda (el2) + (unless (org-element-type-p el2 'plain-text) + (org-element-put-property el2 :buffer (current-buffer)))) + nil nil nil 'with-affiliated 'no-undefer) + (org-element--cache-log-message + "Recovering persistent cached element: %S" + (org-element--format-element el)) + (when (and (not (org-element-parent el)) (not (org-element-type-p el 'org-data))) + (org-element--cache-warn + "Got element without parent when loading cache from disk. Not using this persistent cache. +Please report it to Org mode mailing list (M-x org-submit-bug-report).\n%S" el) + (org-element-cache-reset) + (throw 'abort t))) + org-element--cache) + (setq-local org-element--cache-size (avl-tree-size org-element--cache))) + (when (and (equal container '(elisp org-element--headline-cache)) org-element--headline-cache) + (setq-local org-element--headline-cache-size (avl-tree-size org-element--headline-cache)))))))) (add-hook 'org-persist-before-write-hook #'org-element--cache-persist-before-write) (add-hook 'org-persist-before-read-hook #'org-element--cache-persist-before-read) @@ -7287,14 +7796,23 @@ the cache persistence in the buffer." ;; Only persist cache in file buffers. (when (and (buffer-file-name) (not no-persistence)) (when (not org-element-cache-persistent) - (org-persist-unregister 'org-element--headline-cache (current-buffer)) - (org-persist-unregister 'org-element--cache (current-buffer))) + (org-persist-unregister + 'org-element--headline-cache + (current-buffer) + :remove-related t) + (org-persist-unregister + 'org-element--cache + (current-buffer) + :remove-related t)) (when (and org-element-cache-persistent (buffer-file-name (current-buffer))) - (org-persist-register 'org-element--cache (current-buffer)) - (org-persist-register 'org-element--headline-cache - (current-buffer) - :inherit 'org-element--cache))) + (org-persist-register + `((elisp org-element--cache) (version ,org-element-cache-version)) + (current-buffer)) + (org-persist-register + 'org-element--headline-cache + (current-buffer) + :inherit `((elisp org-element--cache) (version ,org-element-cache-version))))) (setq-local org-element--cache-change-tic (buffer-chars-modified-tick)) (setq-local org-element--cache-last-buffer-size (buffer-size)) (setq-local org-element--cache-gapless nil) @@ -7311,6 +7829,14 @@ the cache persistence in the buffer." (setq-local org-element--cache-sync-requests nil) (setq-local org-element--cache-sync-timer nil) (org-element--cache-setup-change-functions) + ;; Install in the existing indirect buffers. + (dolist (buf (seq-filter + (lambda (buf) + (eq (current-buffer) + (buffer-base-buffer buf))) + (buffer-list))) + (with-current-buffer buf + (org-element--cache-setup-change-functions))) ;; Make sure that `org-element--cache-after-change' and ;; `org-element--cache-before-change' are working inside properly created ;; indirect buffers. Note that `clone-indirect-buffer-hook' @@ -7321,6 +7847,45 @@ the cache persistence in the buffer." (add-hook 'clone-indirect-buffer-hook #'org-element--cache-setup-change-functions))))) +;;;###autoload +(defun org-element-cache-store-key (epom key value &optional robust) + "Store KEY with VALUE associated with EPOM - point, marker, or element. +The key can be retrieved as long as the element (provided or at point) +contents is not modified. +If optional argument ROBUST is non-nil, the key will be retained even +when the contents (children) of current element are modified. Only +non-robust element modifications (affecting the element properties +other then begin/end boundaries) will invalidate the key then." + (let ((element (org-element-at-point epom)) + (property (if robust :robust-cache :fragile-cache))) + (let ((key-store (org-element-property property element))) + (unless (hash-table-p key-store) + (setq key-store (make-hash-table :test #'equal)) + (org-element-put-property element property key-store)) + (puthash key value key-store)))) + +;;;###autoload +(defun org-element-cache-get-key (epom key &optional default) + "Get KEY associated with EPOM - point, marker, or element. +Return DEFAULT when KEY is not associated with EPOM. +The key can be retrieved as long as the element (provided or at point) +contents is not modified." + (let ((element (org-element-at-point epom))) + (let ((key-store1 (org-element-property :fragile-cache element)) + (key-store2 (org-element-property :robust-cache element))) + (let ((val1 (if (hash-table-p key-store1) + (gethash key key-store1 'not-found) + 'not-found)) + (val2 (if (hash-table-p key-store2) + (gethash key key-store2 'not-found) + 'not-found))) + (cond + ((and (eq 'not-found val1) + (eq 'not-found val2)) + default) + ((eq 'not-found val1) val2) + ((eq 'not-found val2) val1)))))) + ;;;###autoload (defun org-element-cache-refresh (pos) "Refresh cache at position POS." @@ -7329,8 +7894,35 @@ the cache persistence in the buffer." (org-element--cache-submit-request pos pos 0) (org-element--cache-set-timer (current-buffer)))) -(defvar warning-minimum-log-level) ; Defined in warning.el +(defmacro org-element-with-enabled-cache (&rest body) + "Run BODY with org-element cache enabled (maybe temporarily). +When cache is enabled, just run body. +When cache is disabled, initialize a new cache, run BODY, and cleanup +at the end." + (declare (debug (form body)) (indent 0)) + (org-with-gensyms (old-state buffer) + `(if (org-element--cache-active-p) + ;; Cache is active, just run BODY. + (progn ,@body) + ;; Cache is disabled. + ;; Save existing cache. + (let ((,buffer (current-buffer)) + (,old-state + (org-with-base-buffer nil + (mapcar #'symbol-value org-element--cache-variables))) + (org-element-use-cache t)) + (unwind-protect + (progn + (org-element-cache-reset) + ,@body) + (cl-mapc + (lambda (var values) + (org-with-base-buffer ,buffer + (set var values))) + org-element--cache-variables + ,old-state)))))) +(defvar warning-minimum-log-level) ; Defined in warning.el (defvar org-element-cache-map-continue-from nil "Position from where mapping should continue. This variable can be set by called function, especially when the @@ -7339,8 +7931,8 @@ function modified the buffer.") (cl-defun org-element-cache-map (func &key (granularity 'headline+inlinetask) restrict-elements next-re fail-re from-pos (to-pos (point-max-marker)) after-element limit-count narrow) - "Map all elements in current buffer with FUNC according to -GRANULARITY. Collect non-nil return values into result list. + "Map all elements in current buffer with FUNC according to GRANULARITY. +Collect non-nil return values into result list. FUNC should accept a single argument - the element. @@ -7384,346 +7976,356 @@ This function does a subset of what `org-element-map' does, but with much better performance. Cached elements are supplied as the single argument of FUNC. Changes to elements made in FUNC will also alter the cache." - (unless (org-element--cache-active-p) - (error "Cache must be active.")) - (unless (memq granularity '( headline headline+inlinetask - greater-element element)) - (error "Unsupported granularity: %S" granularity)) - ;; Make TO-POS marker. Otherwise, buffer edits may garble the the - ;; process. - (unless (markerp to-pos) - (let ((mk (make-marker))) - (set-marker mk to-pos) - (setq to-pos mk))) - (let (;; Bind variables used inside loop to avoid memory - ;; re-allocation on every iteration. - ;; See https://emacsconf.org/2021/talks/faster/ - tmpnext-start tmpparent tmpelement) - (save-excursion - (save-restriction - (unless narrow (widen)) - ;; Synchronize cache up to the end of mapped region. - (org-element-at-point to-pos) - (cl-macrolet ((cache-root - ;; Use the most optimal version of cache available. - () `(org-with-base-buffer nil - (if (memq granularity '(headline headline+inlinetask)) - (org-element--headline-cache-root) - (org-element--cache-root)))) - (cache-size - ;; Use the most optimal version of cache available. - () `(org-with-base-buffer nil - (if (memq granularity '(headline headline+inlinetask)) - org-element--headline-cache-size - org-element--cache-size))) - (cache-walk-restart - ;; Restart tree traversal after AVL tree re-balance. - () `(when node - (org-element-at-point (point-max)) - (setq node (cache-root) - stack (list nil) - leftp t - continue-flag t))) - (cache-walk-abort - ;; Abort tree traversal. - () `(setq continue-flag t - node nil)) - (element-match-at-point - ;; Returning the first element to match around point. - ;; For example, if point is inside headline and - ;; granularity is restricted to headlines only, skip - ;; over all the child elements inside the headline - ;; and return the first parent headline. - ;; When we are inside a cache gap, calling - ;; `org-element-at-point' also fills the cache gap down to - ;; point. - () `(progn - ;; Parsing is one of the performance - ;; bottlenecks. Make sure to optimize it as - ;; much as possible. - ;; - ;; Avoid extra staff like timer cancels et al - ;; and only call `org-element--cache-sync-requests' when - ;; there are pending requests. - (org-with-base-buffer nil - (when org-element--cache-sync-requests - (org-element--cache-sync (current-buffer)))) - ;; Call `org-element--parse-to' directly avoiding any - ;; kind of `org-element-at-point' overheads. - (if restrict-elements - ;; Search directly instead of calling - ;; `org-element-lineage' to avoid funcall overheads - ;; and making sure that we do not go all - ;; the way to `org-data' as `org-element-lineage' - ;; does. - (progn - (setq tmpelement (org-element--parse-to (point))) - (while (and tmpelement (not (memq (org-element-type tmpelement) restrict-elements))) - (setq tmpelement (org-element-property :parent tmpelement))) - tmpelement) - (org-element--parse-to (point))))) - ;; Starting from (point), search RE and move START to - ;; the next valid element to be matched according to - ;; restriction. Abort cache walk if no next element - ;; can be found. When RE is nil, just find element at - ;; point. - (move-start-to-next-match - (re) `(save-match-data - (if (or (not ,re) - (if org-element--cache-map-statistics - (progn - (setq before-time (float-time)) - (re-search-forward (or (car-safe ,re) ,re) nil 'move) - (cl-incf re-search-time - (- (float-time) - before-time))) - (re-search-forward (or (car-safe ,re) ,re) nil 'move))) - (unless (or (< (point) (or start -1)) - (and data - (< (point) (org-element-property :begin data)))) - (if (cdr-safe ,re) - ;; Avoid parsing when we are 100% - ;; sure that regexp is good enough - ;; to find new START. - (setq start (match-beginning 0)) - (setq start (max (or start -1) - (or (org-element-property :begin data) -1) - (or (org-element-property :begin (element-match-at-point)) -1)))) - (when (>= start to-pos) (cache-walk-abort)) - (when (eq start -1) (setq start nil))) - (cache-walk-abort)))) - ;; Find expected begin position of an element after - ;; DATA. - (next-element-start - () `(progn - (setq tmpnext-start nil) - (if (memq granularity '(headline headline+inlinetask)) - (setq tmpnext-start (or (when (memq (org-element-type data) '(headline org-data)) - (org-element-property :contents-begin data)) - (org-element-property :end data))) - (setq tmpnext-start (or (when (memq (org-element-type data) org-element-greater-elements) - (org-element-property :contents-begin data)) - (org-element-property :end data)))) - ;; DATA end may be the last element inside - ;; i.e. source block. Skip up to the end - ;; of parent in such case. - (setq tmpparent data) - (catch :exit - (when (eq tmpnext-start (org-element-property :contents-end tmpparent)) - (setq tmpnext-start (org-element-property :end tmpparent))) - (while (setq tmpparent (org-element-property :parent tmpparent)) - (if (eq tmpnext-start (org-element-property :contents-end tmpparent)) - (setq tmpnext-start (org-element-property :end tmpparent)) - (throw :exit t)))) - tmpnext-start)) - ;; Check if cache does not have gaps. - (cache-gapless-p - () `(org-with-base-buffer nil - (eq org-element--cache-change-tic - (alist-get granularity org-element--cache-gapless))))) - ;; The core algorithm is simple walk along binary tree. However, - ;; instead of checking all the tree elements from first to last - ;; (like in `avl-tree-mapcar'), we begin from FROM-POS skipping - ;; the elements before FROM-POS efficiently: O(logN) instead of - ;; O(Nbefore). - ;; - ;; Later, we may also not check every single element in the - ;; binary tree after FROM-POS. Instead, we can find position of - ;; next candidate elements by means of regexp search and skip the - ;; binary tree branches that are before the next candidate: - ;; again, O(logN) instead of O(Nbetween). - ;; - ;; Some elements might not yet be in the tree. So, we also parse - ;; the empty gaps in cache as needed making sure that we do not - ;; miss anything. - (let* (;; START is always beginning of an element. When there is - ;; no element in cache at START, we are inside cache gap - ;; and need to fill it. - (start (and from-pos - (progn - (goto-char from-pos) - (org-element-property :begin (element-match-at-point))))) - ;; Some elements may start at the same position, so we - ;; also keep track of the last processed element and make - ;; sure that we do not try to search it again. - (prev after-element) - (node (cache-root)) - data - (stack (list nil)) - (leftp t) - result - ;; Whether previous element matched FUNC (FUNC - ;; returned non-nil). - (last-match t) - continue-flag - ;; Generic regexp to search next potential match. If it - ;; is a cons of (regexp . 'match-beg), we are 100% sure - ;; that the match beginning is the existing element - ;; beginning. - (next-element-re (pcase granularity - ((or `headline - (guard (equal '(headline) - restrict-elements))) - (cons - (org-with-limited-levels - org-element-headline-re) - 'match-beg)) - (`headline+inlinetask - (cons - (if (equal '(inlinetask) restrict-elements) - (org-inlinetask-outline-regexp) - org-element-headline-re) - 'match-beg)) - ;; TODO: May add other commonly - ;; searched elements as needed. - (_))) - ;; Make sure that we are not checking the same regexp twice. - (next-re (unless (and next-re - (string= next-re - (or (car-safe next-element-re) - next-element-re))) - next-re)) - (fail-re (unless (and fail-re - (string= fail-re - (or (car-safe next-element-re) - next-element-re))) - fail-re)) - (restrict-elements (or restrict-elements - (pcase granularity - (`headline - '(headline)) - (`headline+inlinetask - '(headline inlinetask)) - (`greater-element - org-element-greater-elements) - (_ nil)))) - ;; Statistics - (time (float-time)) - (predicate-time 0) - (pre-process-time 0) - (re-search-time 0) - (count-predicate-calls-match 0) - (count-predicate-calls-fail 0) - ;; Bind variables used inside loop to avoid memory - ;; re-allocation on every iteration. - ;; See https://emacsconf.org/2021/talks/faster/ - cache-size before-time modified-tic) - ;; Skip to first element within region. - (goto-char (or start (point-min))) - (move-start-to-next-match next-element-re) - (unless (and start (>= start to-pos)) - (while node - (setq data (avl-tree--node-data node)) - (if (and leftp (avl-tree--node-left node) ; Left branch. - ;; Do not move to left branch when we are before - ;; PREV. - (or (not prev) - (not (org-element--cache-key-less-p - (org-element--cache-key data) - (org-element--cache-key prev)))) - ;; ... or when we are before START. - (or (not start) - (not (> start (org-element-property :begin data))))) - (progn (push node stack) - (setq node (avl-tree--node-left node))) - ;; The whole tree left to DATA is before START and - ;; PREV. DATA may still be before START (i.e. when - ;; DATA is the root or when START moved), at START, or - ;; after START. - ;; - ;; If DATA is before start, skip it over and move to - ;; subsequent elements. - ;; If DATA is at start, run FUNC if necessary and - ;; update START according and NEXT-RE, FAIL-RE, - ;; NEXT-ELEMENT-RE. - ;; If DATA is after start, we have found a cache gap - ;; and need to fill it. - (unless (or (and start (< (org-element-property :begin data) start)) - (and prev (not (org-element--cache-key-less-p - (org-element--cache-key prev) - (org-element--cache-key data))))) - ;; DATA is at of after START and PREV. - (if (or (not start) (= (org-element-property :begin data) start)) - ;; DATA is at START. Match it. - ;; In the process, we may alter the buffer, - ;; so also keep track of the cache state. - (progn - (setq modified-tic + (org-element-with-enabled-cache + (unless (org-element--cache-active-p) + (error "Cache must be active")) + (unless (memq granularity '( headline headline+inlinetask + greater-element element)) + (error "Unsupported granularity: %S" granularity)) + ;; Make TO-POS marker. Otherwise, buffer edits may garble the + ;; process. + (unless (markerp to-pos) + (let ((mk (make-marker))) + (set-marker mk to-pos) + (setq to-pos mk))) + (let ((gc-cons-threshold #x40000000) + ;; Bind variables used inside loop to avoid memory + ;; re-allocation on every iteration. + ;; See https://emacsconf.org/2021/talks/faster/ + tmpnext-start tmpparent tmpelement) + (save-excursion + (save-restriction + (unless narrow (widen)) + ;; Synchronize cache up to the end of mapped region. + (org-element-at-point to-pos) + (cl-macrolet ((cache-root + ;; Use the most optimal version of cache available. + () `(org-with-base-buffer nil + (if (memq granularity '(headline headline+inlinetask)) + (org-element--headline-cache-root) + (org-element--cache-root)))) + (cache-size + ;; Use the most optimal version of cache available. + () `(org-with-base-buffer nil + (if (memq granularity '(headline headline+inlinetask)) + org-element--headline-cache-size + org-element--cache-size))) + (cache-walk-restart + ;; Restart tree traversal after AVL tree re-balance. + () `(when node + (org-element-at-point (point-max)) + (setq node (cache-root) + stack (list nil) + leftp t + continue-flag t))) + (cache-walk-abort + ;; Abort tree traversal. + () `(setq continue-flag t + node nil)) + (element-match-at-point + ;; Returning the first element to match around point. + ;; For example, if point is inside headline and + ;; granularity is restricted to headlines only, skip + ;; over all the child elements inside the headline + ;; and return the first parent headline. + ;; When we are inside a cache gap, calling + ;; `org-element-at-point' also fills the cache gap down to + ;; point. + () `(progn + ;; Parsing is one of the performance + ;; bottlenecks. Make sure to optimize it as + ;; much as possible. + ;; + ;; Avoid extra staff like timer cancels et al + ;; and only call `org-element--cache-sync-requests' when + ;; there are pending requests. (org-with-base-buffer nil - org-element--cache-change-tic)) - (setq cache-size (cache-size)) - ;; When NEXT-RE/FAIL-RE is provided, skip to - ;; next regexp match after :begin of the current - ;; element. - (when (if last-match next-re fail-re) - (goto-char (org-element-property :begin data)) - (move-start-to-next-match - (if last-match next-re fail-re))) - (when (and (or (not start) (eq (org-element-property :begin data) start)) - (< (org-element-property :begin data) to-pos)) - ;; Calculate where next possible element - ;; starts and update START if needed. - (setq start (next-element-start)) - (goto-char start) - ;; Move START further if possible. - (when (and next-element-re - ;; Do not move if we know for - ;; sure that cache does not - ;; contain gaps. Regexp - ;; searches are not cheap. - (not (cache-gapless-p))) - (move-start-to-next-match next-element-re) - ;; Make sure that point is at START - ;; before running FUNC. - (goto-char start)) - ;; Try FUNC if DATA matches all the - ;; restrictions. Calculate new START. - (when (or (not restrict-elements) - (memq (org-element-type data) restrict-elements)) - ;; DATA matches restriction. FUNC may - ;; - ;; Call FUNC. FUNC may move point. - (setq org-element-cache-map-continue-from nil) - (if (org-with-base-buffer nil org-element--cache-map-statistics) - (progn - (setq before-time (float-time)) - (push (funcall func data) result) - (cl-incf predicate-time - (- (float-time) - before-time)) - (if (car result) - (cl-incf count-predicate-calls-match) - (cl-incf count-predicate-calls-fail))) - (push (funcall func data) result) - (when (car result) (cl-incf count-predicate-calls-match))) - ;; Set `last-match'. - (setq last-match (car result)) - ;; If FUNC moved point forward, update - ;; START. - (when org-element-cache-map-continue-from - (goto-char org-element-cache-map-continue-from)) - (when (> (point) start) - (move-start-to-next-match nil) - ;; (point) inside matching element. - ;; Go further. - (when (> (point) start) - (setq data (element-match-at-point)) - (if (not data) - (cache-walk-abort) - (goto-char (next-element-start)) - (move-start-to-next-match next-element-re)))) - ;; Drop nil. - (unless (car result) (pop result))) - ;; If FUNC did not move the point and we - ;; know for sure that cache does not contain - ;; gaps, do not try to calculate START in - ;; advance but simply loop to the next cache + (when org-element--cache-sync-requests + (org-element--cache-sync (current-buffer)))) + ;; Call `org-element--parse-to' directly avoiding any + ;; kind of `org-element-at-point' overheads. + (if restrict-elements + ;; Search directly instead of calling + ;; `org-element-lineage' to avoid funcall overheads + ;; and making sure that we do not go all + ;; the way to `org-data' as `org-element-lineage' + ;; does. + (progn + (setq tmpelement (org-element--parse-to (point))) + (while (and tmpelement (not (org-element-type-p tmpelement restrict-elements))) + (setq tmpelement (org-element-parent tmpelement))) + tmpelement) + (org-element--parse-to (point))))) + ;; Starting from (point), search RE and move START to + ;; the next valid element to be matched according to + ;; restriction. Abort cache walk if no next element + ;; can be found. When RE is nil, just find element at + ;; point. + (move-start-to-next-match + ;; Preserve match data that might be set by FUNC. + (re) `(save-match-data + (if (or (not ,re) + (if org-element--cache-map-statistics + (progn + (setq before-time (float-time)) + (prog1 (re-search-forward (or (car-safe ,re) ,re) nil 'move) + (cl-incf re-search-time + (- (float-time) + before-time)))) + (re-search-forward (or (car-safe ,re) ,re) nil 'move))) + (unless (or (< (point) (or start -1)) + (and data + (< (point) (org-element-begin data)))) + (if (cdr-safe ,re) + ;; Avoid parsing when we are 100% + ;; sure that regexp is good enough + ;; to find new START. + (setq start (match-beginning 0)) + (setq start (max (or start -1) + (or (org-element-begin data) -1) + (or (org-element-begin (element-match-at-point)) -1)))) + (when (>= start to-pos) (cache-walk-abort)) + (when (eq start -1) (setq start nil))) + (cache-walk-abort)))) + ;; Find expected begin position of an element after + ;; DATA. + (next-element-start + () `(progn + (setq tmpnext-start nil) + (if (memq granularity '(headline headline+inlinetask)) + (setq tmpnext-start (or (when (org-element-type-p data '(headline org-data)) + (org-element-contents-begin data)) + (org-element-end data))) + (setq tmpnext-start (or (when (org-element-type-p data org-element-greater-elements) + (org-element-contents-begin data)) + (org-element-end data)))) + ;; DATA end may be the last element inside + ;; i.e. source block. Skip up to the end + ;; of parent in such case. + (setq tmpparent data) + (catch :exit + (when (eq tmpnext-start (org-element-contents-end tmpparent)) + (setq tmpnext-start (org-element-end tmpparent))) + (while (setq tmpparent (org-element-parent tmpparent)) + (if (eq tmpnext-start (org-element-contents-end tmpparent)) + (setq tmpnext-start (org-element-end tmpparent)) + (throw :exit t)))) + tmpnext-start)) + ;; Check if cache does not have gaps. + (cache-gapless-p + () `(org-with-base-buffer nil + (eq org-element--cache-change-tic + (alist-get granularity org-element--cache-gapless))))) + ;; The core algorithm is simple walk along binary tree. However, + ;; instead of checking all the tree elements from first to last + ;; (like in `avl-tree-mapcar'), we begin from FROM-POS skipping + ;; the elements before FROM-POS efficiently: O(logN) instead of + ;; O(Nbefore). + ;; + ;; Later, we may also not check every single element in the + ;; binary tree after FROM-POS. Instead, we can find position of + ;; next candidate elements by means of regexp search and skip the + ;; binary tree branches that are before the next candidate: + ;; again, O(logN) instead of O(Nbetween). + ;; + ;; Some elements might not yet be in the tree. So, we also parse + ;; the empty gaps in cache as needed making sure that we do not + ;; miss anything. + (let* (;; START is always beginning of an element. When there is + ;; no element in cache at START, we are inside cache gap + ;; and need to fill it. + (start (and from-pos + (progn + (goto-char from-pos) + (org-element-begin (element-match-at-point))))) + ;; Some elements may start at the same position, so we + ;; also keep track of the last processed element and make + ;; sure that we do not try to search it again. + (prev after-element) + (node (cache-root)) + data + (stack (list nil)) + (leftp t) + result + ;; Whether previous element matched FUNC (FUNC + ;; returned non-nil). + (last-match t) + continue-flag + ;; Generic regexp to search next potential match. If it + ;; is a cons of (regexp . 'match-beg), we are 100% sure + ;; that the match beginning is the existing element + ;; beginning. + (next-element-re (pcase granularity + ((or `headline + (guard (equal '(headline) + restrict-elements))) + (cons + (org-with-limited-levels + org-element-headline-re) + 'match-beg)) + (`headline+inlinetask + (cons + (if (equal '(inlinetask) restrict-elements) + (org-inlinetask-outline-regexp) + org-element-headline-re) + 'match-beg)) + ;; TODO: May add other commonly + ;; searched elements as needed. + (_))) + ;; Make sure that we are not checking the same regexp twice. + (next-re (unless (and next-re + (string= next-re + (or (car-safe next-element-re) + next-element-re))) + next-re)) + (fail-re (unless (and fail-re + (string= fail-re + (or (car-safe next-element-re) + next-element-re))) + fail-re)) + (restrict-elements (or restrict-elements + (pcase granularity + (`headline + '(headline)) + (`headline+inlinetask + '(headline inlinetask)) + (`greater-element + org-element-greater-elements) + (_ nil)))) + ;; Statistics + (time (float-time)) + (predicate-time 0) + (pre-process-time 0) + (re-search-time 0) + (count-predicate-calls-match 0) + (count-predicate-calls-fail 0) + ;; Bind variables used inside loop to avoid memory + ;; re-allocation on every iteration. + ;; See https://emacsconf.org/2021/talks/faster/ + cache-size before-time modified-tic) + ;; Skip to first element within region. + (goto-char (or start (point-min))) + (move-start-to-next-match next-element-re) + (unless (and start (>= start to-pos)) + (while node + (setq data (avl-tree--node-data node)) + (if (and leftp (avl-tree--node-left node) ; Left branch. + ;; Do not move to left branch when we are before + ;; PREV. + (or (not prev) + (not (org-element--cache-key-less-p + (org-element--cache-key data) + (org-element--cache-key prev)))) + ;; ... or when we are before START. + (or (not start) + (not (> start (org-element-begin data))))) + (progn (push node stack) + (setq node (avl-tree--node-left node))) + ;; The whole tree left to DATA is before START and + ;; PREV. DATA may still be before START (i.e. when + ;; DATA is the root or when START moved), at START, or + ;; after START. + ;; + ;; If DATA is before start, skip it over and move to + ;; subsequent elements. + ;; If DATA is at start, run FUNC if necessary and + ;; update START according and NEXT-RE, FAIL-RE, + ;; NEXT-ELEMENT-RE. + ;; If DATA is after start, we have found a cache gap + ;; and need to fill it. + (unless (or (and start (< (org-element-begin data) start)) + (and prev (not (org-element--cache-key-less-p + (org-element--cache-key prev) + (org-element--cache-key data))))) + ;; DATA is at of after START and PREV. + (if (or (not start) (= (org-element-begin data) start)) + ;; DATA is at START. Match it. + ;; In the process, we may alter the buffer, + ;; so also keep track of the cache state. + (progn + (setq modified-tic + (org-with-base-buffer nil + org-element--cache-change-tic)) + (setq cache-size (cache-size)) + ;; When NEXT-RE/FAIL-RE is provided, skip to + ;; next regexp match after :begin of the current ;; element. - (when (and (cache-gapless-p) - (eq (next-element-start) - start)) - (setq start nil)) - ;; Check if the buffer has been modified. + (when (if last-match next-re fail-re) + (goto-char (org-element-begin data)) + (move-start-to-next-match + (if last-match next-re fail-re))) + (when (and (or (not start) (eq (org-element-begin data) start)) + (< (org-element-begin data) to-pos) + (not continue-flag)) + ;; Calculate where next possible element + ;; starts and update START if needed. + (setq start (next-element-start)) + (goto-char start) + ;; Move START further if possible. + (save-excursion + (when (and next-element-re + ;; Do not move if we know for + ;; sure that cache does not + ;; contain gaps. Regexp + ;; searches are not cheap. + (not (cache-gapless-p))) + (move-start-to-next-match next-element-re))) + ;; Try FUNC if DATA matches all the + ;; restrictions. Calculate new START. + (when (or (not restrict-elements) + (org-element-type-p data restrict-elements)) + ;; DATA matches restriction. FUNC may + ;; + ;; Call FUNC. FUNC may move point. + (setq org-element-cache-map-continue-from nil) + (if (org-with-base-buffer nil org-element--cache-map-statistics) + (progn + (setq before-time (float-time)) + (push (funcall func data) result) + (cl-incf predicate-time + (- (float-time) + before-time)) + (if (car result) + (cl-incf count-predicate-calls-match) + (cl-incf count-predicate-calls-fail))) + (push (funcall func data) result) + (when (car result) (cl-incf count-predicate-calls-match))) + ;; Set `last-match'. + (setq last-match (car result)) + ;; If FUNC moved point forward, update + ;; START. + (when org-element-cache-map-continue-from + (goto-char org-element-cache-map-continue-from)) + (when (> (point) start) + (move-start-to-next-match nil) + ;; (point) inside matching element. + ;; Go further. + (when (> (point) start) + (setq data (element-match-at-point)) + (if (not data) + (cache-walk-abort) + (goto-char (next-element-start)) + (move-start-to-next-match next-element-re)))) + ;; Drop nil. + (unless (car result) (pop result))) + ;; If FUNC did not move the point and we + ;; know for sure that cache does not contain + ;; gaps, do not try to calculate START in + ;; advance but simply loop to the next cache + ;; element. + (when (and (cache-gapless-p) + (eq (next-element-start) + start)) + (setq start nil)) + ;; Reached LIMIT-COUNT. Abort. + (when (and limit-count + (>= count-predicate-calls-match + limit-count)) + (cache-walk-abort)) + ;; Make sure that we have a cached + ;; element at the new START. + (when start (element-match-at-point))) + ;; Check if the buffer or cache has been modified. (unless (org-with-base-buffer nil (and (eq modified-tic org-element--cache-change-tic) (eq cache-size (cache-size)))) @@ -7742,7 +8344,7 @@ the cache." ;; element past already processed ;; place. (when (and start - (<= start (org-element-property :begin data)) + (<= start (org-element-begin data)) (not org-element-cache-map-continue-from)) (goto-char start) (setq data (element-match-at-point)) @@ -7753,58 +8355,55 @@ the cache." (move-start-to-next-match next-element-re))) (org-element-at-point to-pos) (cache-walk-restart)) - ;; Reached LIMIT-COUNT. Abort. - (when (and limit-count - (>= count-predicate-calls-match - limit-count)) - (cache-walk-abort)) (if (org-element-property :cached data) (setq prev data) - (setq prev nil)))) - ;; DATA is after START. Fill the gap. - (if (memq (org-element-type (org-element--parse-to start)) '(plain-list table)) - ;; Tables and lists are special, we need a - ;; trickery to make items/rows be populated - ;; into cache. - (org-element--parse-to (1+ start))) - ;; Restart tree traversal as AVL tree is - ;; re-balanced upon adding elements. We can no - ;; longer trust STACK. - (cache-walk-restart))) - ;; Second, move to the right branch of the tree or skip - ;; it altogether. - (if continue-flag - (setq continue-flag nil) - (setq node (if (and (car stack) - ;; If START advanced beyond stack parent, skip the right branch. - (or (and start (< (org-element-property :begin (avl-tree--node-data (car stack))) start)) - (and prev (org-element--cache-key-less-p - (org-element--cache-key (avl-tree--node-data (car stack))) - (org-element--cache-key prev))))) - (progn - (setq leftp nil) - (pop stack)) - ;; Otherwise, move ahead into the right - ;; branch when it exists. - (if (setq leftp (avl-tree--node-right node)) - (avl-tree--node-right node) - (pop stack)))))))) - (when (and org-element--cache-map-statistics - (or (not org-element--cache-map-statistics-threshold) - (> (- (float-time) time) org-element--cache-map-statistics-threshold))) - (message "Mapped over elements in %S. %d/%d predicate matches. Total time: %f sec. Pre-process time: %f sec. Predicate time: %f sec. Re-search time: %f sec. + (setq prev nil))) + ;; DATA is after START. Fill the gap. + (if (org-element-type-p + (org-element--parse-to start) + '(plain-list table)) + ;; Tables and lists are special, we need a + ;; trickery to make items/rows be populated + ;; into cache. + (org-element--parse-to (1+ start))) + ;; Restart tree traversal as AVL tree is + ;; re-balanced upon adding elements. We can no + ;; longer trust STACK. + (cache-walk-restart))) + ;; Second, move to the right branch of the tree or skip + ;; it altogether. + (if continue-flag + (setq continue-flag nil) + (setq node (if (and (car stack) + ;; If START advanced beyond stack parent, skip the right branch. + (or (and start (< (org-element-begin (avl-tree--node-data (car stack))) start)) + (and prev (org-element--cache-key-less-p + (org-element--cache-key (avl-tree--node-data (car stack))) + (org-element--cache-key prev))))) + (progn + (setq leftp nil) + (pop stack)) + ;; Otherwise, move ahead into the right + ;; branch when it exists. + (if (setq leftp (avl-tree--node-right node)) + (avl-tree--node-right node) + (pop stack)))))))) + (when (and org-element--cache-map-statistics + (or (not org-element--cache-map-statistics-threshold) + (> (- (float-time) time) org-element--cache-map-statistics-threshold))) + (message "Mapped over elements in %S. %d/%d predicate matches. Total time: %f sec. Pre-process time: %f sec. Predicate time: %f sec. Re-search time: %f sec. Calling parameters: :granularity %S :restrict-elements %S :next-re %S :fail-re %S :from-pos %S :to-pos %S :limit-count %S :after-element %S" - (current-buffer) - count-predicate-calls-match - (+ count-predicate-calls-match - count-predicate-calls-fail) - (- (float-time) time) - pre-process-time - predicate-time - re-search-time - granularity restrict-elements next-re fail-re from-pos to-pos limit-count after-element)) - ;; Return result. - (nreverse result))))))) + (current-buffer) + count-predicate-calls-match + (+ count-predicate-calls-match + count-predicate-calls-fail) + (- (float-time) time) + pre-process-time + predicate-time + re-search-time + granularity restrict-elements next-re fail-re from-pos to-pos limit-count after-element)) + ;; Return result. + (nreverse result)))))))) @@ -7827,11 +8426,14 @@ the cache." ;;;###autoload -(defun org-element-at-point (&optional pom cached-only) - "Determine closest element around point or POM. +(defun org-element-at-point (&optional epom cached-only) + "Determine closest element around point or EPOM. + +When EPOM is an element, return it immediately. +Otherwise, determine element at EPOM marker or position. Only check cached element when CACHED-ONLY is non-nil and return nil -unconditionally when element at POM is not in cache. +unconditionally when element at EPOM is not in cache. Return value is a list like (TYPE PROPS) where TYPE is the type of the element and PROPS a plist of properties associated to the @@ -7848,66 +8450,76 @@ the first row of a table, returned element will be the table instead of the first row. When point is at the end of the buffer, return the innermost -element ending there." - (setq pom (or pom (point))) - ;; Allow re-parsing when the command can benefit from it. - (when (and cached-only - (memq this-command org-element--cache-non-modifying-commands)) - (setq cached-only nil)) - (let (element) - (when (org-element--cache-active-p) - (if (not org-element--cache) (org-element-cache-reset) - (unless cached-only (org-element--cache-sync (current-buffer) pom)))) - (setq element (if cached-only - (when (and (org-element--cache-active-p) - (or (not org-element--cache-sync-requests) - (< pom - (org-element--request-beg - (car org-element--cache-sync-requests))))) - (org-element--cache-find pom)) - (condition-case err - (org-element--parse-to pom) - (error - (org-element--cache-warn - "Org parser error in %s::%S. Resetting.\n The error was: %S\n Backtrace:\n%S\n Please report this to Org mode mailing list (M-x org-submit-bug-report)." - (buffer-name (current-buffer)) - pom - err - (when (and (fboundp 'backtrace-get-frames) - (fboundp 'backtrace-to-string)) - (backtrace-to-string (backtrace-get-frames 'backtrace)))) - (org-element-cache-reset) - (org-element--parse-to pom))))) - (when (and (org-element--cache-active-p) - element - (org-element--cache-verify-element element)) - (setq element (org-element--parse-to pom))) - (unless (eq 'org-data (org-element-type element)) - (unless (and cached-only - (not (and element - (or (= pom (org-element-property :begin element)) - (and (not (memq (org-element-type element) org-element-greater-elements)) - (>= pom (org-element-property :begin element)) - (< pom (org-element-property :end element))) - (and (org-element-property :contents-begin element) - (>= pom (org-element-property :begin element)) - (< pom (org-element-property :contents-begin element))) - (and (not (org-element-property :contents-end element)) - (>= pom (org-element-property :begin element)) - (< pom (org-element-property :end element))))))) - (if (not (eq (org-element-type element) 'section)) - element - (org-element-at-point (1+ pom) cached-only)))))) +element ending there. + +This function may modify the match data." + (if (org-element-type epom t) epom + (setq epom (or epom (point))) + (org-with-point-at epom + (unless (derived-mode-p 'org-mode) + (display-warning + '(org-element org-element-parser) + (format-message + "`org-element-at-point' cannot be used in non-Org buffer %S (%s)" + (current-buffer) major-mode))) + ;; Allow re-parsing when the command can benefit from it. + (when (and cached-only + (memq this-command org-element--cache-non-modifying-commands)) + (setq cached-only nil)) + (let (element) + (when (org-element--cache-active-p) + (if (not (org-with-base-buffer nil org-element--cache)) (org-element-cache-reset) + (unless cached-only (org-element--cache-sync (current-buffer) epom)))) + (setq element (if cached-only + (when (and (org-element--cache-active-p) + (or (not org-element--cache-sync-requests) + (< epom + (org-element--request-beg + (car org-element--cache-sync-requests))))) + (org-element--cache-find epom)) + (condition-case-unless-debug err + (org-element--parse-to epom) + (error + (org-element--cache-warn + "Org parser error in %s::%S. Resetting.\n The error was: %S\n Backtrace:\n%S\n Please report this to Org mode mailing list (M-x org-submit-bug-report)." + (buffer-name (current-buffer)) + epom + err + (when (and (fboundp 'backtrace-get-frames) + (fboundp 'backtrace-to-string)) + (backtrace-to-string (backtrace-get-frames 'backtrace)))) + (org-element-cache-reset) + (org-element--parse-to epom))))) + (when (and (org-element--cache-active-p) + element + (org-element--cache-verify-element element)) + (setq element (org-element--parse-to epom))) + (unless (org-element-type-p element 'org-data) + (unless (and cached-only + (not (and element + (or (= epom (org-element-begin element)) + (and (not (org-element-type-p element org-element-greater-elements)) + (>= epom (org-element-begin element)) + (< epom (org-element-end element))) + (and (org-element-contents-begin element) + (>= epom (org-element-begin element)) + (< epom (org-element-contents-begin element))) + (and (not (org-element-contents-end element)) + (>= epom (org-element-begin element)) + (< epom (org-element-end element))))))) + (if (not (org-element-type-p element 'section)) + element + (org-element-at-point (1+ epom) cached-only)))))))) ;;;###autoload (defsubst org-element-at-point-no-context (&optional pom) "Quickly find element at point or POM. It is a faster version of `org-element-at-point' that is not -guaranteed to return correct `:parent' properties even when cache is -enabled." +guaranteed to return cached element. `:parent' element may be +deferred and slow to retrieve." (or (org-element-at-point pom 'cached-only) - (let (org-element-use-cache) (org-element-at-point pom)))) + (org-element-with-disabled-cache (org-element-at-point pom)))) ;;;###autoload (defun org-element-context (&optional element) @@ -7927,148 +8539,125 @@ the beginning of any other object, return that object. Optional argument ELEMENT, when non-nil, is the closest element containing point, as returned by `org-element-at-point'. -Providing it allows for quicker computation." - (save-match-data - (catch 'objects-forbidden - (org-with-wide-buffer - (let* ((pos (point)) - (element (or element (org-element-at-point))) - (type (org-element-type element)) - (post (org-element-property :post-affiliated element))) - ;; If point is inside an element containing objects or - ;; a secondary string, narrow buffer to the container and - ;; proceed with parsing. Otherwise, return ELEMENT. - (cond - ;; At a parsed affiliated keyword, check if we're inside main - ;; or dual value. - ((and post (< pos post)) - (beginning-of-line) - (let ((case-fold-search t)) (looking-at org-element--affiliated-re)) - (cond - ((not (member-ignore-case (match-string 1) - org-element-parsed-keywords)) - (throw 'objects-forbidden element)) - ((< (match-end 0) pos) - (narrow-to-region (match-end 0) (line-end-position))) - ((and (match-beginning 2) - (>= pos (match-beginning 2)) - (< pos (match-end 2))) - (narrow-to-region (match-beginning 2) (match-end 2))) - (t (throw 'objects-forbidden element))) - ;; Also change type to retrieve correct restrictions. - (setq type 'keyword)) - ;; At an item, objects can only be located within tag, if any. - ((eq type 'item) - (let ((tag (org-element-property :tag element))) - (if (or (not tag) (/= (line-beginning-position) post)) - (throw 'objects-forbidden element) - (beginning-of-line) - (search-forward tag (line-end-position)) - (goto-char (match-beginning 0)) - (if (and (>= pos (point)) (< pos (match-end 0))) - (narrow-to-region (point) (match-end 0)) - (throw 'objects-forbidden element))))) - ;; At an headline or inlinetask, objects are in title. - ((memq type '(headline inlinetask)) - (let ((case-fold-search nil)) - (goto-char (org-element-property :begin element)) - (looking-at org-complex-heading-regexp) - (let ((end (match-end 4))) - (if (not end) (throw 'objects-forbidden element) - (goto-char (match-beginning 4)) - (when (looking-at org-element-comment-string) - (goto-char (match-end 0))) - (if (>= (point) end) (throw 'objects-forbidden element) - (narrow-to-region (point) end)))))) - ;; At a paragraph, a table-row or a verse block, objects are - ;; located within their contents. - ((memq type '(paragraph table-row verse-block)) - (let ((cbeg (org-element-property :contents-begin element)) - (cend (org-element-property :contents-end element))) - ;; CBEG is nil for table rules. - (if (and cbeg cend (>= pos cbeg) - (or (< pos cend) (and (= pos cend) (eobp)))) - (narrow-to-region cbeg cend) - (throw 'objects-forbidden element)))) +Providing it allows for quicker computation. + +This function may modify match data." + (catch 'objects-forbidden + (org-with-wide-buffer + (let* ((pos (point)) + (element (or element (org-element-at-point))) + (type (org-element-type element)) + (post (org-element-post-affiliated element))) + ;; If point is inside an element containing objects or + ;; a secondary string, narrow buffer to the container and + ;; proceed with parsing. Otherwise, return ELEMENT. + (cond + ;; At a parsed affiliated keyword, check if we're inside main + ;; or dual value. + ((and post (< pos post)) + (forward-line 0) + (let ((case-fold-search t)) (looking-at org-element--affiliated-re)) + (cond + ((not (member-ignore-case (match-string 1) + org-element-parsed-keywords)) + (throw 'objects-forbidden element)) + ((<= (match-end 0) pos) + (narrow-to-region (match-end 0) (line-end-position))) + ((and (match-beginning 2) + (>= pos (match-beginning 2)) + (< pos (match-end 2))) + (narrow-to-region (match-beginning 2) (match-end 2))) (t (throw 'objects-forbidden element))) - (goto-char (point-min)) - (let ((restriction (org-element-restriction type)) - (parent element) - last) - (catch 'exit - (while t - (let ((next (org-element--object-lex restriction))) - (when next (org-element-put-property next :parent parent)) - ;; Process NEXT, if any, in order to know if we need to - ;; skip it, return it or move into it. - (if (or (not next) (> (org-element-property :begin next) pos)) - (throw 'exit (or last parent)) - (let ((end (org-element-property :end next)) - (cbeg (org-element-property :contents-begin next)) - (cend (org-element-property :contents-end next))) - (cond - ;; Skip objects ending before point. Also skip - ;; objects ending at point unless it is also the - ;; end of buffer, since we want to return the - ;; innermost object. - ((and (<= end pos) (/= (point-max) end)) - (goto-char end) - ;; For convenience, when object ends at POS, - ;; without any space, store it in LAST, as we - ;; will return it if no object starts here. - (when (and (= end pos) - (not (memq (char-before) '(?\s ?\t)))) - (setq last next))) - ;; If POS is within a container object, move into - ;; that object. - ((and cbeg cend - (>= pos cbeg) - (or (< pos cend) - ;; At contents' end, if there is no - ;; space before point, also move into - ;; object, for consistency with - ;; convenience feature above. - (and (= pos cend) - (or (= (point-max) pos) - (not (memq (char-before pos) - '(?\s ?\t))))))) - (goto-char cbeg) - (narrow-to-region (point) cend) - (setq parent next) - (setq restriction (org-element-restriction next))) - ;; Otherwise, return NEXT. - (t (throw 'exit next)))))))))))))) - -(defun org-element-lineage (datum &optional types with-self) - "List all ancestors of a given element or object. - -DATUM is an object or element. - -Return ancestors from the closest to the farthest. When optional -argument TYPES is a list of symbols, return the first element or -object in the lineage whose type belongs to that list instead. - -When optional argument WITH-SELF is non-nil, lineage includes -DATUM itself as the first element, and TYPES, if provided, also -apply to it. - -When DATUM is obtained through `org-element-context' or -`org-element-at-point', only ancestors from its section can be -found. There is no such limitation when DATUM belongs to a full -parse tree." - (let ((up (if with-self datum (org-element-property :parent datum))) - ancestors) - (while (and up (not (memq (org-element-type up) types))) - (unless types (push up ancestors)) - (setq up (org-element-property :parent up))) - (if types up (nreverse ancestors)))) + ;; Also change type to retrieve correct restrictions. + (setq type 'keyword)) + ;; At an item, objects can only be located within tag, if any. + ((eq type 'item) + (let ((tag (org-element-property :tag element))) + (if (or (not tag) (/= (line-beginning-position) post)) + (throw 'objects-forbidden element) + (forward-line 0) + (search-forward tag (line-end-position)) + (goto-char (match-beginning 0)) + (if (and (>= pos (point)) (< pos (match-end 0))) + (narrow-to-region (point) (match-end 0)) + (throw 'objects-forbidden element))))) + ;; At an headline or inlinetask, objects are in title. + ((memq type '(headline inlinetask)) + (let ((case-fold-search nil)) + (goto-char (org-element-begin element)) + (looking-at org-complex-heading-regexp) + (let ((end (match-end 4))) + (if (not end) (throw 'objects-forbidden element) + (goto-char (match-beginning 4)) + (when (looking-at org-element-comment-string) + (goto-char (match-end 0))) + (if (>= (point) end) (throw 'objects-forbidden element) + (narrow-to-region (point) end)))))) + ;; At a paragraph, a table-row or a verse block, objects are + ;; located within their contents. + ((memq type '(paragraph table-row verse-block)) + (let ((cbeg (org-element-contents-begin element)) + (cend (org-element-contents-end element))) + ;; CBEG is nil for table rules. + (if (and cbeg cend (>= pos cbeg) + (or (< pos cend) (and (= pos cend) (eobp)))) + (narrow-to-region cbeg cend) + (throw 'objects-forbidden element)))) + (t (throw 'objects-forbidden element))) + (goto-char (point-min)) + (let ((restriction (org-element-restriction type)) + (parent element) + last) + (catch 'exit + (while t + (let ((next (org-element--object-lex restriction))) + (when next (org-element-put-property next :parent parent)) + ;; Process NEXT, if any, in order to know if we need to + ;; skip it, return it or move into it. + (if (or (not next) (> (org-element-begin next) pos)) + (throw 'exit (or last parent)) + (let ((end (org-element-end next)) + (cbeg (org-element-contents-begin next)) + (cend (org-element-contents-end next))) + (cond + ;; Skip objects ending before point. Also skip + ;; objects ending at point unless it is also the + ;; end of buffer, since we want to return the + ;; innermost object. + ((and (<= end pos) (/= (point-max) end)) + (goto-char end) + ;; For convenience, when object ends at POS, + ;; without any space, store it in LAST, as we + ;; will return it if no object starts here. + (when (and (= end pos) + (not (memq (char-before) '(?\s ?\t)))) + (setq last next))) + ;; If POS is within a container object, move into + ;; that object. + ((and cbeg cend + (>= pos cbeg) + (or (< pos cend) + ;; At contents' end, if there is no + ;; space before point, also move into + ;; object, for consistency with + ;; convenience feature above. + (and (= pos cend) + (or (= (point-max) pos) + (not (memq (char-before pos) + '(?\s ?\t))))))) + (goto-char cbeg) + (narrow-to-region (point) cend) + (setq parent next) + (setq restriction (org-element-restriction next))) + ;; Otherwise, return NEXT. + (t (throw 'exit next))))))))))))) (defun org-element-nested-p (elem-A elem-B) "Non-nil when elements ELEM-A and ELEM-B are nested." - (let ((beg-A (org-element-property :begin elem-A)) - (beg-B (org-element-property :begin elem-B)) - (end-A (org-element-property :end elem-A)) - (end-B (org-element-property :end elem-B))) + (let ((beg-A (org-element-begin elem-A)) + (beg-B (org-element-begin elem-B)) + (end-A (org-element-end elem-A)) + (end-B (org-element-end elem-B))) (or (and (>= beg-A beg-B) (<= end-A end-B)) (and (>= beg-B beg-A) (<= end-B end-A))))) @@ -8076,7 +8665,7 @@ parse tree." "Swap elements ELEM-A and ELEM-B. Assume ELEM-B is after ELEM-A in the buffer. Leave point at the end of ELEM-A." - (goto-char (org-element-property :begin elem-A)) + (goto-char (org-element-begin elem-A)) ;; There are two special cases when an element doesn't start at bol: ;; the first paragraph in an item or in a footnote definition. (let ((specialp (not (bolp)))) @@ -8085,9 +8674,9 @@ end of ELEM-A." ;; a footnote definition is impossible: it cannot contain two ;; paragraphs in a row because it cannot contain a blank line. (when (and specialp - (or (not (eq (org-element-type elem-B) 'paragraph)) - (/= (org-element-property :begin elem-B) - (org-element-property :contents-begin elem-B)))) + (or (not (org-element-type-p elem-B 'paragraph)) + (/= (org-element-begin elem-B) + (org-element-contents-begin elem-B)))) (error "Cannot swap elements")) ;; Preserve folding state when `org-fold-core-style' is set to ;; `text-properties'. @@ -8095,16 +8684,16 @@ end of ELEM-A." ;; In a special situation, ELEM-A will have no indentation. We'll ;; give it ELEM-B's (which will in, in turn, have no indentation). (let* ((ind-B (when specialp - (goto-char (org-element-property :begin elem-B)) + (goto-char (org-element-begin elem-B)) (current-indentation))) - (beg-A (org-element-property :begin elem-A)) + (beg-A (org-element-begin elem-A)) (end-A (save-excursion - (goto-char (org-element-property :end elem-A)) + (goto-char (org-element-end elem-A)) (skip-chars-backward " \r\t\n") (line-end-position))) - (beg-B (org-element-property :begin elem-B)) + (beg-B (org-element-begin elem-B)) (end-B (save-excursion - (goto-char (org-element-property :end elem-B)) + (goto-char (org-element-end elem-B)) (skip-chars-backward " \r\t\n") (line-end-position))) ;; Store inner folds responsible for visibility status. @@ -8131,7 +8720,7 @@ end of ELEM-A." (insert body-B) ;; Restore ex ELEM-A folds. (org-fold-core-regions (cdr folds) :relative beg-A) - (goto-char (org-element-property :end elem-B)))))) + (goto-char (org-element-end elem-B)))))) (provide 'org-element) diff --git a/elpa/org-9.6.7/org-entities.el b/elpa/org-9.7.17/org-entities.el similarity index 97% rename from elpa/org-9.6.7/org-entities.el rename to elpa/org-9.7.17/org-entities.el index 61083022..c38c0fcb 100644 --- a/elpa/org-9.6.7/org-entities.el +++ b/elpa/org-9.7.17/org-entities.el @@ -1,10 +1,10 @@ ;;; org-entities.el --- Support for Special Entities -*- lexical-binding: t; -*- -;; Copyright (C) 2010-2023 Free Software Foundation, Inc. +;; Copyright (C) 2010-2024 Free Software Foundation, Inc. ;; Author: Carsten Dominik , ;; Ulf Stegemann -;; Keywords: outlines, calendar, wp +;; Keywords: outlines, calendar, text ;; URL: https://orgmode.org ;; ;; This file is part of GNU Emacs. @@ -29,6 +29,7 @@ (require 'org-macs) (org-assert-version) +(require 'seq) ; Emacs 27 does not preload seq.el; for `seq-every-p'. (declare-function org-mode "org" ()) (declare-function org-toggle-pretty-entities "org" ()) @@ -41,14 +42,19 @@ (defun org-entities--user-safe-p (v) "Non-nil if V is a safe value for `org-entities-user'." - (pcase v - (`nil t) - (`(,(and (pred stringp) - (pred (string-match-p "\\`[a-zA-Z][a-zA-Z0-9]*\\'"))) - ,(pred stringp) ,(pred booleanp) ,(pred stringp) - ,(pred stringp) ,(pred stringp) ,(pred stringp)) - t) - (_ nil))) + (cond + ((not v) t) + ((listp v) + (seq-every-p + (lambda (e) + (pcase e + (`(,(and (pred stringp) + (pred (string-match-p "\\`[a-zA-Z][a-zA-Z0-9]*\\'"))) + ,(pred stringp) ,(pred booleanp) ,(pred stringp) + ,(pred stringp) ,(pred stringp) ,(pred stringp)) + t) + (_ nil))) + v)))) (defcustom org-entities-user nil "User-defined entities used in Org to produce special characters. @@ -272,8 +278,10 @@ packages to be loaded, add these packages to `org-latex-packages-alist'." ("vert" "\\vert{}" t "|" "|" "|" "|") ("vbar" "|" nil "|" "|" "|" "|") ("brvbar" "\\textbrokenbar{}" nil "¦" "|" "¦" "¦") - ("S" "\\S" nil "§" "paragraph" "§" "§") - ("sect" "\\S" nil "§" "paragraph" "§" "§") + ("S" "\\S" nil "§" "section" "§" "§") + ("sect" "\\S" nil "§" "section" "§" "§") + ("P" "\\P{}" nil "¶" "paragraph" "¶" "¶") + ("para" "\\P{}" nil "¶" "paragraph" "¶" "¶") ("amp" "\\&" nil "&" "&" "&" "&") ("lt" "\\textless{}" nil "<" "<" "<" "<") ("gt" "\\textgreater{}" nil ">" ">" ">" ">") @@ -489,7 +497,6 @@ packages to be loaded, add these packages to `org-latex-packages-alist'." ("checkmark" "\\checkmark" t "✓" "[checkmark]" "[checkmark]" "✓") "** Miscellaneous (seldom used)" - ("para" "\\P{}" nil "¶" "[pilcrow]" "¶" "¶") ("ordf" "\\textordfeminine{}" nil "ª" "_a_" "ª" "ª") ("ordm" "\\textordmasculine{}" nil "º" "_o_" "º" "º") ("cedil" "\\c{}" nil "¸" "[cedilla]" "¸" "¸") diff --git a/elpa/org-9.6.7/org-faces.el b/elpa/org-9.7.17/org-faces.el similarity index 97% rename from elpa/org-9.6.7/org-faces.el rename to elpa/org-9.7.17/org-faces.el index 594c9a6e..21b23b64 100644 --- a/elpa/org-9.6.7/org-faces.el +++ b/elpa/org-9.7.17/org-faces.el @@ -1,9 +1,9 @@ ;;; org-faces.el --- Face definitions -*- lexical-binding: t; -*- -;; Copyright (C) 2004-2023 Free Software Foundation, Inc. +;; Copyright (C) 2004-2024 Free Software Foundation, Inc. ;; Author: Carsten Dominik -;; Keywords: outlines, hypermedia, calendar, wp +;; Keywords: outlines, hypermedia, calendar, text ;; URL: https://orgmode.org ;; ;; This file is part of GNU Emacs. @@ -108,7 +108,7 @@ color of the frame." "Face used for drawers." :group 'org-faces) -(defface org-property-value nil +(defface org-property-value '((t :inherit default)) "Face used for the value of a property." :group 'org-faces) @@ -389,6 +389,10 @@ changes." "Face used for tables." :group 'org-faces) +(defface org-table-row '((t :inherit org-table)) + "Face used to fontify whole table rows (including newlines and indentation)." + :group 'org-faces) + (defface org-table-header '((t :inherit org-table :background "LightGray" :foreground "Black")) @@ -660,6 +664,10 @@ month and 365.24 days for a year)." "Face used for agenda entries that come from the Emacs diary." :group 'org-faces) +(defface org-agenda-calendar-daterange '((t :inherit default)) + "Face used to show entries with a date range in the agenda." + :group 'org-faces) + (defface org-agenda-calendar-event '((t :inherit default)) "Face used to show events and appointments in the agenda." :group 'org-faces) @@ -675,15 +683,15 @@ month and 365.24 days for a year)." (defcustom org-n-level-faces (length org-level-faces) "The number of different faces to be used for headlines. Org mode defines 8 different headline faces, so this can be at most 8. -If it is less than 8, the level-1 face gets re-used for level N+1 etc." +If it is less than 8, the level-1 face gets reused for level N+1 etc." :type 'integer :group 'org-faces) (defcustom org-cycle-level-faces t "Non-nil means level styles cycle after level `org-n-level-faces'. Then so level org-n-level-faces+1 is styled like level 1. -If nil, then all levels >= org-n-level-faces are styled like -level org-n-level-faces." +If nil, then all levels >= `org-n-level-faces' are styled like +level `org-n-level-faces'." :group 'org-appearance :group 'org-faces :version "24.1" diff --git a/elpa/org-9.6.7/org-feed.el b/elpa/org-9.7.17/org-feed.el similarity index 98% rename from elpa/org-9.6.7/org-feed.el rename to elpa/org-9.7.17/org-feed.el index f0b294b4..4077afa0 100644 --- a/elpa/org-9.6.7/org-feed.el +++ b/elpa/org-9.7.17/org-feed.el @@ -1,9 +1,9 @@ ;;; org-feed.el --- Add RSS feed items to Org files -*- lexical-binding: t; -*- ;; -;; Copyright (C) 2009-2023 Free Software Foundation, Inc. +;; Copyright (C) 2009-2024 Free Software Foundation, Inc. ;; ;; Author: Carsten Dominik -;; Keywords: outlines, hypermedia, calendar, wp +;; Keywords: outlines, hypermedia, calendar, text ;; URL: https://orgmode.org ;; ;; This file is part of GNU Emacs. @@ -475,7 +475,7 @@ This will find DRAWER and extract the alist." (goto-char pos) (let ((end (save-excursion (org-end-of-subtree t t)))) (if (re-search-forward - (concat "^[ \t]*:" drawer ":[ \t]*\n\\([^\000]*?\\)\n[ \t]*:END:") + (concat "^[ \t]*:" drawer ":[ \t]*\n\\(\\(?:.\\|\n\\)*?\\)\n[ \t]*:END:") end t) (read (match-string 1)) nil)))) @@ -495,7 +495,7 @@ This will find DRAWER and extract the alist." (match-beginning 0))))) (outline-next-heading) (insert " :" drawer ":\n :END:\n") - (beginning-of-line 0)) + (forward-line -1)) (insert (pp-to-string status))))) (defun org-feed-add-items (pos entries) @@ -508,7 +508,7 @@ This will find DRAWER and extract the alist." (setq level (org-get-valid-level (length (match-string 1)) 1)) (org-end-of-subtree t t) (skip-chars-backward " \t\n") - (beginning-of-line 2) + (forward-line 1) (setq pos (point)) (while (setq entry (pop entries)) (org-paste-subtree level entry 'yank)) @@ -565,7 +565,7 @@ If that property is already present, nothing changes." (let ((v (plist-get entry (intern (concat ":" name))))) (save-excursion (save-match-data - (beginning-of-line) + (forward-line 0) (if (looking-at (concat "^\\([ \t]*\\)%" name "[ \t]*$")) (org-feed-make-indented-block @@ -633,7 +633,7 @@ containing the properties `:guid' and `:item-full-text'." end (and (re-search-forward "" nil t) (match-beginning 0))) (setq item (buffer-substring beg end) - guid (if (string-match ".*?>\\([^\000]*?\\)" item) + guid (if (string-match ".*?>\\(\\(?:.\\|\n\\)*?\\)" item) (xml-substitute-special (match-string-no-properties 1 item)))) (setq entry (list :guid guid :item-full-text item)) (push entry entries) @@ -647,7 +647,7 @@ containing the properties `:guid' and `:item-full-text'." (with-temp-buffer (insert (plist-get entry :item-full-text)) (goto-char (point-min)) - (while (re-search-forward "<\\([a-zA-Z]+\\>\\).*?>\\([^\000]*?\\)" + (while (re-search-forward "<\\([a-zA-Z]+\\>\\).*?>\\(\\(?:.\\|\n\\)*?\\)" nil t) (setq entry (plist-put entry (intern (concat ":" (match-string 1))) diff --git a/elpa/org-9.6.7/org-fold-core.el b/elpa/org-9.7.17/org-fold-core.el similarity index 84% rename from elpa/org-9.6.7/org-fold-core.el rename to elpa/org-9.7.17/org-fold-core.el index 6c17b00f..07396b61 100644 --- a/elpa/org-9.6.7/org-fold-core.el +++ b/elpa/org-9.7.17/org-fold-core.el @@ -1,8 +1,8 @@ ;;; org-fold-core.el --- Folding buffer text -*- lexical-binding: t; -*- ;; -;; Copyright (C) 2020-2023 Free Software Foundation, Inc. +;; Copyright (C) 2020-2024 Free Software Foundation, Inc. ;; -;; Author: Ihor Radchenko +;; Author: Ihor Radchenko ;; Keywords: folding, invisible text ;; URL: https://orgmode.org ;; @@ -160,7 +160,7 @@ ;; If one wants to search invisible text without using the provided ;; functions, it is important to keep in mind that 'invisible text ;; property may have multiple possible values (not just nil and -;; t). Hence, (next-single-char-property-change pos 'invisible) is not +;; t). Hence, (next-single-char-property-change pos 'invisible) is not ;; guaranteed to return the boundary of invisible/visible text. ;;; Interactive searching inside folded text (via isearch) @@ -172,7 +172,7 @@ ;; The isearch behavior is controlled on per-folding-spec basis by ;; setting `isearch-open' and `isearch-ignore' folding spec -;; properties. The the docstring of `org-fold-core--specs' for more details. +;; properties. See the docstring of `org-fold-core--specs' for more details. ;;; Handling edits inside folded text @@ -280,16 +280,17 @@ ;;; Customization -(defcustom org-fold-core-style 'text-properties +(defcustom org-fold-core-style (if (version< emacs-version "29") + 'text-properties + 'overlays) "Internal implementation detail used to hide folded text. Can be either `text-properties' or `overlays'. -The former is faster on large files, while the latter is generally -less error-prone with regard to third-party packages that haven't yet -adapted to the new folding implementation. +The former is faster on large files in Emacs <29, while the latter is +generally less error-prone with regard to third-party packages. Important: This variable must be set before loading Org." :group 'org - :package-version '(Org . "9.6") + :package-version '(Org . "9.7") :type '(choice (const :tag "Overlays" overlays) (const :tag "Text properties" text-properties))) @@ -380,6 +381,9 @@ The following properties are known: `buffer-invisibility-spec' will be used as is. Note that changing this property from nil to t may clear the setting in `buffer-invisibility-spec'. +- :font-lock :: non-nil means that newlines after the fold should + be re-fontified upon folding/unfolding. See + `org-activate-folds'. - :alias :: a list of aliases for the SPEC-SYMBOL. - :fragile :: Must be a function accepting two arguments. Non-nil means that changes in region may cause @@ -424,7 +428,7 @@ Return nil when there is no matching folding spec." (unless org-fold-core--spec-symbols (dolist (spec (org-fold-core-folding-spec-list)) (push (cons spec spec) org-fold-core--spec-symbols) - (dolist (alias (assq :alias (assq spec org-fold-core--specs))) + (dolist (alias (cdr (assq :alias (assq spec org-fold-core--specs)))) (push (cons alias spec) org-fold-core--spec-symbols)))) (alist-get spec-or-alias org-fold-core--spec-symbols))) @@ -433,7 +437,7 @@ Return nil when there is no matching folding spec." (org-fold-core-get-folding-spec-from-alias spec-or-alias)) (defsubst org-fold-core--check-spec (spec-or-alias) - "Throw an error if SPEC-OR-ALIAS is not in `org-fold-core--spec-priority-list'." + "Throw an error if SPEC-OR-ALIAS is not in `org-fold-core-folding-spec-list'." (unless (org-fold-core-folding-spec-p spec-or-alias) (error "%s is not a valid folding spec" spec-or-alias))) @@ -553,7 +557,10 @@ and the setup appears to be created for different buffer, copy the old invisibility state into new buffer-local text properties, unless RETURN-ONLY is non-nil." (if (eq org-fold-core-style 'overlays) - (org-fold-core-get-folding-property-symbol spec nil 'global) + (or (gethash (cons 'global spec) org-fold-core--property-symbol-cache) + (puthash (cons 'global spec) + (org-fold-core-get-folding-property-symbol spec nil 'global) + org-fold-core--property-symbol-cache)) (let* ((buf (or buffer (current-buffer)))) ;; Create unique property symbol for SPEC in BUFFER (let ((local-prop (or (gethash (cons buf spec) org-fold-core--property-symbol-cache) @@ -574,15 +581,6 @@ unless RETURN-ONLY is non-nil." ;; would contain folding properties, which are not ;; matching the generated `local-prop'. (unless (member local-prop (cdr (assq 'invisible char-property-alias-alist))) - ;; Add current buffer to the list of indirect buffers in the base buffer. - (when (buffer-base-buffer) - (with-current-buffer (buffer-base-buffer) - (setq-local org-fold-core--indirect-buffers - (let (bufs) - (org-fold-core-cycle-over-indirect-buffers - (push (current-buffer) bufs)) - (push buf bufs) - (delete-dups bufs))))) ;; Copy all the old folding properties to preserve the folding state (with-silent-modifications (dolist (old-prop (cdr (assq 'invisible char-property-alias-alist))) @@ -633,14 +631,28 @@ unless RETURN-ONLY is non-nil." text-property-default-nonsticky full-prop-list)))))))))))))) +(defun org-fold-core--update-buffer-folds () + "Copy folding state in a new buffer with text copied from old buffer." + (org-fold-core--property-symbol-get-create (car (org-fold-core-folding-spec-list)))) + (defun org-fold-core-decouple-indirect-buffer-folds () "Copy and decouple folding state in a newly created indirect buffer. This function is mostly intended to be used in `clone-indirect-buffer-hook'." + ;; Add current buffer to the list of indirect buffers in the base buffer. + (when (buffer-base-buffer) + (let ((new-buffer (current-buffer))) + (with-current-buffer (buffer-base-buffer) + (setq-local org-fold-core--indirect-buffers + (let (bufs) + (org-fold-core-cycle-over-indirect-buffers + (push (current-buffer) bufs)) + (push new-buffer bufs) + (delete-dups bufs)))))) (when (and (buffer-base-buffer) (eq org-fold-core-style 'text-properties) (not (memql 'ignore-indirect org-fold-core--optimise-for-huge-buffers))) - (org-fold-core--property-symbol-get-create (car (org-fold-core-folding-spec-list))))) + (org-fold-core--update-buffer-folds))) ;;; API @@ -694,7 +706,7 @@ The folding spec properties will be set to PROPERTIES (see (let* ((full-properties (mapcar (lambda (prop) (cons prop (cdr (assq prop properties)))) '( :visible :ellipsis :isearch-ignore :global :isearch-open :front-sticky - :rear-sticky :fragile :alias))) + :rear-sticky :fragile :alias :font-lock))) (full-spec (cons spec full-properties))) (add-to-list 'org-fold-core--specs full-spec append) (mapc (lambda (prop-cons) (org-fold-core-set-folding-spec-property spec (car prop-cons) (cdr prop-cons) 'force)) full-properties) @@ -783,16 +795,19 @@ corresponding folding spec (if the text is folded using that spec)." (when (and spec (not (eq spec 'all))) (org-fold-core--check-spec spec)) (org-with-point-at pom (cond - ((eq spec 'all) - (let ((result)) - (dolist (spec (org-fold-core-folding-spec-list)) - (let ((val (get-char-property (point) (org-fold-core--property-symbol-get-create spec nil t)))) - (when val (push val result)))) - (reverse result))) - ((null spec) - (let ((result (get-char-property (point) 'invisible))) - (when (org-fold-core-folding-spec-p result) result))) - (t (get-char-property (point) (org-fold-core--property-symbol-get-create spec nil t))))))) + ((or (null spec) (eq spec 'all)) + (catch :single-spec + (let ((result)) + (dolist (lspec (org-fold-core-folding-spec-list)) + (let ((val (if (eq org-fold-core-style 'text-properties) + (get-text-property (point) (org-fold-core--property-symbol-get-create lspec nil t)) + (get-char-property (point) (org-fold-core--property-symbol-get-create lspec nil t))))) + (when (and val (null spec)) (throw :single-spec val)) + (when val (push val result)))) + (reverse result)))) + (t (if (eq org-fold-core-style 'text-properties) + (get-text-property (point) (org-fold-core--property-symbol-get-create spec nil t)) + (get-char-property (point) (org-fold-core--property-symbol-get-create spec nil t)))))))) (defun org-fold-core-get-folding-specs-in-region (beg end) "Get all folding specs in region from BEG to END." @@ -843,13 +858,20 @@ If PREVIOUS-P is non-nil, search backwards." (next-change (if previous-p (if ignore-hidden-p (lambda (p) (org-fold-core-previous-folding-state-change (org-fold-core-get-folding-spec nil p) p limit)) - (lambda (p) (max limit (1- (previous-single-char-property-change p 'invisible nil limit))))) + (lambda (p) (max limit (previous-single-char-property-change p 'invisible nil limit)))) (if ignore-hidden-p (lambda (p) (org-fold-core-next-folding-state-change (org-fold-core-get-folding-spec nil p) p limit)) (lambda (p) (next-single-char-property-change p 'invisible nil limit))))) (next pos)) (while (and (funcall cmp next limit) - (not (org-xor invisible-initially? (funcall invisible-p next)))) + (not (org-xor + invisible-initially? + (funcall invisible-p + (if previous-p + ;; NEXT-1 -> NEXT is the change. + (max limit (1- next)) + ;; NEXT -> NEXT+1 is the change. + next))))) (setq next (funcall next-change next))) next)) @@ -897,14 +919,19 @@ Search backwards when PREVIOUS-P is non-nil." (unless spec-or-alias (setq spec-or-alias (org-fold-core-folding-spec-list))) (setq pos (or pos (point))) - (apply (if previous-p - #'max - #'min) - (mapcar (if previous-p - (lambda (prop) (max (or limit (point-min)) (previous-single-char-property-change pos prop nil (or limit (point-min))))) - (lambda (prop) (next-single-char-property-change pos prop nil (or limit (point-max))))) - (mapcar (lambda (el) (org-fold-core--property-symbol-get-create el nil t)) - spec-or-alias)))) + (let ((limit (or limit (if previous-p (point-min) (point-max))))) + (catch :limit + (dolist (prop (mapcar + (lambda (el) + (org-fold-core--property-symbol-get-create el nil t)) + spec-or-alias)) + (when (= limit pos) (throw :limit limit)) + (setq + limit + (if previous-p + (previous-single-char-property-change pos prop nil limit) + (next-single-char-property-change pos prop nil limit)))) + limit))) (defun org-fold-core-previous-folding-state-change (&optional spec-or-alias pos limit) "Call `org-fold-core-next-folding-state-change' searching backwards." @@ -985,6 +1012,24 @@ WITH-MARKERS must be nil when RELATIVE is non-nil." ;;;;; Region visibility +(defvar org-fold-core--keep-overlays nil + "When non-nil, `org-fold-core-region' will not remove existing overlays.") +(defvar org-fold-core--isearch-overlays) ; defined below +(defmacro org-fold-core--keep-overlays (&rest body) + "Run BODY with `org-fold-core--keep-overlays' set to t." + (declare (debug (body))) + `(let ((org-fold-core--keep-overlays t)) + ,@body)) + +(defvar org-fold-core--isearch-active nil + "When non-nil, `org-fold-core-region' records created overlays. +New overlays will be added to `org-fold-core--isearch-overlays'.") +(defmacro org-fold-core--with-isearch-active (&rest body) + "Run BODY with `org-fold-core--isearch-active' set to t." + (declare (debug (body))) + `(let ((org-fold-core--isearch-active t)) + ,@body)) + ;; This is the core function performing actual folding/unfolding. The ;; folding state is stored in text property (folding property) ;; returned by `org-fold-core--property-symbol-get-create'. The value of the @@ -997,7 +1042,44 @@ If SPEC-OR-ALIAS is omitted and FLAG is nil, unfold everything in the region." (when spec (org-fold-core--check-spec spec)) (with-silent-modifications (org-with-wide-buffer - (when (eq org-fold-core-style 'overlays) (remove-overlays from to 'invisible spec)) + ;; Arrange fontifying newlines after all the folds between FROM + ;; and TO to match the first character before the fold; not the + ;; last as per Emacs defaults. This makes :extend faces span + ;; past the ellipsis. See bug#65896. The face properties are + ;; assigned via `org-activate-folds'. + (when (or (not spec) (org-fold-core-get-folding-spec-property spec :font-lock)) + (when (equal ?\n (char-after from)) + (font-lock-flush from (1+ from))) + (when (equal ?\n (char-after to)) + (font-lock-flush to (1+ to))) + (dolist (region (org-fold-core-get-regions :from from :to to :specs spec)) + (when (equal ?\n (char-after (cadr region))) + (font-lock-flush (cadr region) (1+ (cadr region)))) + ;; Re-fontify beginning of the fold - we may + ;; unfold inside an existing fold, with FROM begin a newline + ;; after spliced fold. + (when (equal ?\n (char-after (car region))) + (font-lock-flush (car region) (1+ (car region)))))) + (when (eq org-fold-core-style 'overlays) + (if org-fold-core--keep-overlays + (mapc + (lambda (ov) + (when (or (not spec) + (eq spec (overlay-get ov 'invisible))) + (when (and org-fold-core--isearch-active + (overlay-get ov 'invisible) + (org-fold-core-get-folding-spec-property + (overlay-get ov 'invisible) :isearch-open)) + (when-let* ((spec (overlay-get ov 'invisible))) + (overlay-put ov 'org-invisible spec) + (overlay-put ov (org-fold-core--property-symbol-get-create spec) nil)) + (overlay-put ov 'invisible nil) + (when org-fold-core--isearch-active + (cl-pushnew ov org-fold-core--isearch-overlays))))) + (overlays-in from to)) + (when spec + (remove-overlays from to 'org-invisible spec) + (remove-overlays from to 'invisible spec)))) (if flag (if (not spec) (error "Calling `org-fold-core-region' with missing SPEC") @@ -1007,17 +1089,14 @@ If SPEC-OR-ALIAS is omitted and FLAG is nil, unfold everything in the region." (let ((o (make-overlay from to nil (org-fold-core-get-folding-spec-property spec :front-sticky) (org-fold-core-get-folding-spec-property spec :rear-sticky)))) + (when org-fold-core--isearch-active + (push o org-fold-core--isearch-overlays)) (overlay-put o 'evaporate t) (overlay-put o (org-fold-core--property-symbol-get-create spec) spec) (overlay-put o 'invisible spec) - (overlay-put o 'isearch-open-invisible #'org-fold-core--isearch-show) - ;; FIXME: Disabling to work around Emacs bug#60399 - ;; and https://orgmode.org/list/87zgb6tk6h.fsf@localhost. - ;; The proper fix will require making sure that - ;; `org-fold-core-isearch-open-function' does not - ;; delete the overlays used by isearch. - ;; (overlay-put o 'isearch-open-invisible-temporary #'org-fold-core--isearch-show-temporary) - ) + ;; Preserve priority. + (overlay-put o 'priority (length (member spec (org-fold-core-folding-spec-list)))) + (overlay-put o 'isearch-open-invisible #'org-fold-core--isearch-show)) (put-text-property from to (org-fold-core--property-symbol-get-create spec) spec) (put-text-property from to 'isearch-open-invisible #'org-fold-core--isearch-show) (put-text-property from to 'isearch-open-invisible-temporary #'org-fold-core--isearch-show-temporary) @@ -1041,7 +1120,13 @@ If SPEC-OR-ALIAS is omitted and FLAG is nil, unfold everything in the region." (setq pos next)) (setq pos (next-single-char-property-change pos 'invisible nil to))))))) (when (eq org-fold-core-style 'text-properties) - (remove-text-properties from to (list (org-fold-core--property-symbol-get-create spec) nil))))))))) + (remove-text-properties from to (list (org-fold-core--property-symbol-get-create spec) nil))))) + ;; Re-calculate trailing faces for all the folds revealed + ;; by unfolding or created by folding. + (when (or (not spec) (org-fold-core-get-folding-spec-property spec :font-lock)) + (dolist (region (org-fold-core-get-regions :from from :to to :specs spec)) + (when (equal ?\n (char-after (cadr region))) + (font-lock-flush (cadr region) (1+ (cadr region)))))))))) (cl-defmacro org-fold-core-regions (regions &key override clean-markers relative) "Fold every region in REGIONS list in current buffer. @@ -1088,7 +1173,7 @@ because otherwise all these markers will point to nowhere." This is used to allow searching in regions hidden via text properties. As for [2020-05-09 Sat], Isearch only has special handling of hidden overlays. Any text hidden via text properties is not revealed even if `search-invisible' -is set to `t'.") +is set to t.") (defvar-local org-fold-core--isearch-local-regions (make-hash-table :test 'equal) "Hash table storing temporarily shown folds from isearch matches.") @@ -1104,13 +1189,19 @@ TYPE can be either `text-properties' or `overlays'." (setq-local isearch-filter-predicate #'org-fold-core--isearch-filter-predicate-text-properties)) (`overlays (when (eq org-fold-core-style 'text-properties) - (setq-local isearch-filter-predicate #'org-fold-core--isearch-filter-predicate-overlays) - (add-hook 'isearch-mode-end-hook #'org-fold-core--clear-isearch-overlays nil 'local))) + (add-function :before (local 'isearch-filter-predicate) #'org-fold-core--create-isearch-overlays) + ;; When `isearch-filter-predicate' is called outside isearch, + ;; it is common that `isearch-mode-end-hook' does not get + ;; executed, but `isearch-clean-overlays' usually does. + (advice-add + 'isearch-clean-overlays :after + #'org-fold-core--clear-isearch-overlays + '((name . isearch-clean-overlays@org-fold-core))))) (_ (error "%s: Unknown type of setup for `org-fold-core--isearch-setup'" type)))) (defun org-fold-core--isearch-reveal (pos) "Default function used to reveal hidden text at POS for isearch." - (let ((region (org-fold-core-get-region-at-point pos))) + (let ((region (org-fold-core-get-region-at-point nil pos))) (org-fold-core-region (car region) (cdr region) nil))) (defun org-fold-core--isearch-filter-predicate-text-properties (beg end) @@ -1145,34 +1236,38 @@ This function is intended to be used as `isearch-filter-predicate'." "Clear `org-fold-core--isearch-local-regions'." (clrhash org-fold-core--isearch-local-regions)) -(defun org-fold-core--isearch-show (_) - "Reveal text at point found by isearch." - (funcall org-fold-core-isearch-open-function (point))) +(defun org-fold-core--isearch-show (overlay-or-region) + "Reveal text at OVERLAY-OR-REGION found by isearch." + (let (beg end) + (if (overlayp overlay-or-region) + (setq beg (overlay-start overlay-or-region) + end (overlay-end overlay-or-region)) + (setq beg (car overlay-or-region) + end (cdr overlay-or-region))) + ;; FIXME: Reveal the match (usually point, but may sometimes go beyond the region). + (when (< beg (point) end) + (funcall org-fold-core-isearch-open-function (point))) + (if (overlayp overlay-or-region) + (delete-overlay overlay-or-region) + (org-fold-core-region beg end nil)))) (defun org-fold-core--isearch-show-temporary (region hide-p) "Temporarily reveal text in REGION. Hide text instead if HIDE-P is non-nil. REGION can also be an overlay in current buffer." - (when (overlayp region) - (setq region (cons (overlay-start region) - (overlay-end region)))) - (if (not hide-p) - (let ((pos (car region))) - (while (< pos (cdr region)) - (let ((spec-no-open - (catch :found - (dolist (spec (org-fold-core-get-folding-spec 'all pos)) - (unless (org-fold-core-get-folding-spec-property spec :isearch-open) - (throw :found spec)))))) - (if spec-no-open - ;; Skip regions folded with folding specs that cannot be opened. - (setq pos (org-fold-core-next-folding-state-change spec-no-open pos (cdr region))) - (dolist (spec (org-fold-core-get-folding-spec 'all pos)) - (push (cons spec (org-fold-core-get-region-at-point spec pos)) (gethash region org-fold-core--isearch-local-regions))) - (org-fold-core--isearch-show region) - (setq pos (org-fold-core-next-folding-state-change nil pos (cdr region))))))) - (mapc (lambda (val) (org-fold-core-region (cadr val) (cddr val) t (car val))) (gethash region org-fold-core--isearch-local-regions)) - (remhash region org-fold-core--isearch-local-regions))) + (save-match-data ; match data must not be modified. + (let ((org-fold-core-style (if (overlayp region) 'overlays 'text-properties))) + (if hide-p + (if (not (overlayp region)) + nil ;; FIXME: after isearch supports text properties. + (when-let* ((spec (overlay-get region 'org-invisible))) + (overlay-put region 'invisible spec) + (overlay-put region (org-fold-core--property-symbol-get-create spec) spec))) + ;; isearch expects all the temporarily opened overlays to exist. + ;; See https://debbugs.gnu.org/cgi/bugreport.cgi?bug=60399 + (org-fold-core--keep-overlays + (org-fold-core--with-isearch-active + (org-fold-core--isearch-show region))))))) (defvar-local org-fold-core--isearch-special-specs nil "List of specs that can break visibility state when converted to overlays. @@ -1187,49 +1282,28 @@ instead of text properties. The created overlays will be stored in (while (< pos end) ;; We need loop below to make sure that we clean all invisible ;; properties, which may be nested. - (dolist (spec (org-fold-core-get-folding-spec 'all pos)) - (unless (org-fold-core-get-folding-spec-property spec :isearch-ignore) - (let* ((region (org-fold-core-get-region-at-point spec pos))) - (when (memq spec org-fold-core--isearch-special-specs) - (setq pos (min pos (car region))) - (setq end (max end (cdr region)))) - ;; Changing text properties is considered buffer modification. - ;; We do not want it here. - (with-silent-modifications - (org-fold-core-region (car region) (cdr region) nil spec) - ;; The overlay is modeled after `outline-flag-region' - ;; [2020-05-09 Sat] overlay for 'outline blocks. - (let ((o (make-overlay (car region) (cdr region) nil 'front-advance))) - (overlay-put o 'evaporate t) - (overlay-put o 'invisible spec) - (overlay-put o 'org-invisible spec) - ;; Make sure that overlays are applied in the same order - ;; with the folding specs. - ;; Note: `memq` returns cdr with car equal to the first - ;; found matching element. - (overlay-put o 'priority (length (memq spec (org-fold-core-folding-spec-list)))) - ;; `delete-overlay' here means that spec information will be lost - ;; for the region. The region will remain visible. - (if (org-fold-core-get-folding-spec-property spec :isearch-open) - (overlay-put o 'isearch-open-invisible #'delete-overlay) - (overlay-put o 'isearch-open-invisible #'ignore) - (overlay-put o 'isearch-open-invisible-temporary #'ignore)) - (push o org-fold-core--isearch-overlays)))))) - (setq pos (org-fold-core-next-folding-state-change nil pos end))))) - -(defun org-fold-core--isearch-filter-predicate-overlays (beg end) - "Return non-nil if text between BEG and END is deemed visible by isearch. -This function is intended to be used as `isearch-filter-predicate'." - (org-fold-core--create-isearch-overlays beg end) ;; trick isearch by creating overlays in place of invisible text - (isearch-filter-visible beg end)) + (catch :repeat + (dolist (spec (org-fold-core-get-folding-spec 'all pos)) + (unless (org-fold-core-get-folding-spec-property spec :isearch-ignore) + (let* ((region (org-fold-core-get-region-at-point spec pos))) + (when (memq spec org-fold-core--isearch-special-specs) + (setq end (max end (cdr region))) + (when (< (car region) beg) + (setq beg (car region)) + (setq pos beg) + (throw :repeat t))) + ;; Changing text properties is considered buffer modification. + ;; We do not want it here. + (with-silent-modifications + (org-fold-core-region (car region) (cdr region) nil spec) + (let ((org-fold-core-style 'overlays)) + (org-fold-core--with-isearch-active + (org-fold-core-region (car region) (cdr region) t spec))))))) + (setq pos (org-fold-core-next-folding-state-change nil pos end)))))) (defun org-fold-core--clear-isearch-overlay (ov) "Convert OV region back into using text properties." - (let ((spec (if isearch-mode-end-hook-quit - ;; Restore all folds. - (overlay-get ov 'org-invisible) - ;; Leave opened folds open. - (overlay-get ov 'invisible)))) + (let ((spec (overlay-get ov 'invisible))) ;; Ignore deleted overlays. (when (and spec (overlay-buffer ov)) @@ -1238,8 +1312,6 @@ This function is intended to be used as `isearch-filter-predicate'." (with-silent-modifications (when (<= (overlay-end ov) (point-max)) (org-fold-core-region (overlay-start ov) (overlay-end ov) t spec))))) - (when (member ov isearch-opened-overlays) - (setq isearch-opened-overlays (delete ov isearch-opened-overlays))) (delete-overlay ov)) (defun org-fold-core--clear-isearch-overlays () @@ -1254,6 +1326,8 @@ This function is intended to be used as `isearch-filter-predicate'." "Non-nil: skip processing modifications in `org-fold-core--fix-folded-region'.") (defvar org-fold-core--ignore-fragility-checks nil "Non-nil: skip fragility checks in `org-fold-core--fix-folded-region'.") +(defvar org-fold-core--suppress-folding-fix nil + "Non-nil: skip folding fix in `org-fold-core--fix-folded-region'.") (defmacro org-fold-core-ignore-modifications (&rest body) "Run BODY ignoring buffer modifications in `org-fold-core--fix-folded-region'." @@ -1262,12 +1336,47 @@ This function is intended to be used as `isearch-filter-predicate'." (unwind-protect (progn ,@body) (setq org-fold-core--last-buffer-chars-modified-tick (buffer-chars-modified-tick))))) +(defmacro org-fold-core-suppress-folding-fix (&rest body) + "Run BODY skipping re-folding checks in `org-fold-core--fix-folded-region'." + (declare (debug (form body)) (indent 0)) + `(let ((org-fold-core--suppress-folding-fix t)) + (progn ,@body))) + (defmacro org-fold-core-ignore-fragility-checks (&rest body) "Run BODY skipping :fragility checks in `org-fold-core--fix-folded-region'." (declare (debug (form body)) (indent 0)) `(let ((org-fold-core--ignore-fragility-checks t)) (progn ,@body))) +(defvar org-fold-core--region-delayed-list nil + "List holding (MKFROM MKTO FLAG SPEC-OR-ALIAS) arguments to process. +The list is used by `org-fold-core--region-delayed'.") +(defun org-fold-core--region-delayed (from to flag &optional spec-or-alias) + "Call `org-fold-core-region' after current command. +Pass the same FROM, TO, FLAG, and SPEC-OR-ALIAS." + ;; Setup delayed folding. + (add-hook 'post-command-hook #'org-fold-core--process-delayed) + (let ((frommk (make-marker)) + (tomk (make-marker))) + (set-marker frommk from (current-buffer)) + (set-marker tomk to (current-buffer)) + (push (list frommk tomk flag spec-or-alias) org-fold-core--region-delayed-list))) + +(defun org-fold-core--process-delayed () + "Perform folding for `org-fold-core--region-delayed-list'." + (when org-fold-core--region-delayed-list + (mapc (lambda (args) + (when (and (buffer-live-p (marker-buffer (nth 0 args))) + (buffer-live-p (marker-buffer (nth 1 args))) + (< (nth 0 args) (nth 1 args))) + (org-with-point-at (car args) + (apply #'org-fold-core-region args)))) + ;; Restore the initial folding order. + (nreverse org-fold-core--region-delayed-list)) + ;; Cleanup `post-command-hook'. + (remove-hook 'post-command-hook #'org-fold-core--process-delayed) + (setq org-fold-core--region-delayed-list nil))) + (defvar-local org-fold-core--last-buffer-chars-modified-tick nil "Variable storing the last return value of `buffer-chars-modified-tick'.") @@ -1295,7 +1404,7 @@ property, unfold the region if the :fragile function returns non-nil." ;; buffer. Work around Emacs bug#46982. ;; Re-hide text inserted in the middle/front/back of a folded ;; region. - (unless (equal from to) ; Ignore deletions. + (unless (or org-fold-core--suppress-folding-fix (equal from to)) ; Ignore deletions. (when (eq org-fold-core-style 'text-properties) (org-fold-core-cycle-over-indirect-buffers (dolist (spec (org-fold-core-folding-spec-list)) @@ -1385,7 +1494,10 @@ property, unfold the region if the :fragile function returns non-nil." (cons fold-begin fold-end) spec)) ;; Reveal completely, not just from the SPEC. - (org-fold-core-region fold-begin fold-end nil))))) + ;; Do it only after command is finished - + ;; some Emacs commands assume that + ;; visibility is not altered by `after-change-functions'. + (org-fold-core--region-delayed fold-begin fold-end nil))))) ;; Move to next fold. (setq pos (org-fold-core-next-folding-state-change spec pos local-to))))))))))))) diff --git a/elpa/org-9.6.7/org-fold.el b/elpa/org-9.7.17/org-fold.el similarity index 87% rename from elpa/org-9.6.7/org-fold.el rename to elpa/org-9.7.17/org-fold.el index 1b7ca22b..33b43fd3 100644 --- a/elpa/org-9.6.7/org-fold.el +++ b/elpa/org-9.7.17/org-fold.el @@ -1,8 +1,8 @@ ;;; org-fold.el --- Folding of Org entries -*- lexical-binding: t; -*- ;; -;; Copyright (C) 2020-2023 Free Software Foundation, Inc. +;; Copyright (C) 2020-2024 Free Software Foundation, Inc. ;; -;; Author: Ihor Radchenko +;; Author: Ihor Radchenko ;; Keywords: folding, invisible text ;; URL: https://orgmode.org ;; @@ -49,8 +49,6 @@ (require 'org-fold-core) (defvar org-inlinetask-min-level) -(defvar org-link--link-folding-spec) -(defvar org-link--description-folding-spec) (defvar org-odd-levels-only) (defvar org-drawer-regexp) (defvar org-property-end-re) @@ -61,11 +59,12 @@ (defvar org-element-headline-re) (declare-function isearch-filter-visible "isearch" (beg end)) -(declare-function org-element-type "org-element" (element)) +(declare-function org-element-type "org-element-ast" (node &optional anonymous)) (declare-function org-element-at-point "org-element" (&optional pom cached-only)) -(declare-function org-element-property "org-element" (property element)) +(declare-function org-element-property "org-element-ast" (property node)) +(declare-function org-element-end "org-element" (node)) +(declare-function org-element-post-affiliated "org-element" (node)) (declare-function org-element--current-element "org-element" (limit &optional granularity mode structure)) -(declare-function org-element--cache-active-p "org-element" ()) (declare-function org-toggle-custom-properties-visibility "org" ()) (declare-function org-item-re "org-list" ()) (declare-function org-up-heading-safe "org" ()) @@ -189,7 +188,10 @@ smart Make point visible, and do insertion/deletion if it is Never delete a previously invisible character or add in the middle or right after an invisible region. Basically, this allows insertion and backward-delete right before ellipses. - FIXME: maybe in this case we should not even show?" + FIXME: maybe in this case we should not even show? + +This variable only affects commands listed in +`org-fold-catch-invisible-edits-commands'." :group 'org-edit-structure :version "24.1" :type '(choice @@ -199,6 +201,33 @@ smart Make point visible, and do insertion/deletion if it is (const :tag "Show invisible part and do the edit" show) (const :tag "Be smart and do the right thing" smart))) +(defcustom org-fold-catch-invisible-edits-commands + ;; We do not add non-Org commands here by default to avoid advising + ;; globally. See `org-fold--advice-edit-commands'. + '((org-self-insert-command . insert) + (org-delete-backward-char . delete-backward) + (org-delete-char . delete) + (org-meta-return . insert) + (org-return . insert)) + "Alist of commands where Org checks for invisible edits. +Each element is (COMMAND . KIND), where COMMAND is symbol representing +command as stored in `this-command' and KIND is symbol `insert', +symbol `delete', or symbol `delete-backward'. + +The checks are performed around `point'. + +This variable must be set before loading Org in order to take effect. + +Also, see `org-fold-catch-invisible-edits'." + :group 'org-edit-structure + :package-version '("Org" . "9.7") + :type '(alist + :key-type symbol + :value-type (choice + (const insert) + (const delete) + (const delete-backward)))) + ;;; Core functionality ;;; API @@ -224,6 +253,7 @@ smart Make point visible, and do insertion/deletion if it is (:ellipsis . ,ellipsis) (:fragile . ,#'org-fold--reveal-outline-maybe) (:isearch-open . t) + (:font-lock . t) ;; This is needed to make sure that inserting a ;; new planning line in folded heading is not ;; revealed. Also, the below combination of :front-sticky and @@ -236,6 +266,7 @@ smart Make point visible, and do insertion/deletion if it is (:ellipsis . ,ellipsis) (:fragile . ,#'org-fold--reveal-drawer-or-block-maybe) (:isearch-open . t) + (:font-lock . t) (:front-sticky . t) (:alias . ( block center-block comment-block dynamic-block example-block export-block @@ -245,10 +276,9 @@ smart Make point visible, and do insertion/deletion if it is (:ellipsis . ,ellipsis) (:fragile . ,#'org-fold--reveal-drawer-or-block-maybe) (:isearch-open . t) + (:font-lock . t) (:front-sticky . t) - (:alias . (drawer property-drawer))) - ,org-link--description-folding-spec - ,org-link--link-folding-spec))) + (:alias . (drawer property-drawer)))))) ;;;; Searching and examining folded text @@ -358,7 +388,7 @@ of the current heading, or to 1 if the current line is not a heading." (interactive (list (cond (current-prefix-arg (prefix-numeric-value current-prefix-arg)) - ((save-excursion (beginning-of-line) + ((save-excursion (forward-line 0) (looking-at outline-regexp)) (funcall outline-level)) (t 1)))) @@ -419,20 +449,21 @@ Show the heading too, if it is currently invisible." (defun org-fold-show-children (&optional level) "Show all direct subheadings of this heading. -Prefix arg LEVEL is how many levels below the current level -should be shown. Default is enough to cause the following -heading to appear." +Prefix arg LEVEL is how many levels below the current level should be +shown. If direct subheadings are deeper than LEVEL, they are still +displayed." (interactive "p") (unless (org-before-first-heading-p) (save-excursion (org-with-limited-levels (org-back-to-heading t)) (let* ((current-level (funcall outline-level)) + (parent-level current-level) (max-level (org-get-valid-level - current-level + parent-level (if level (prefix-numeric-value level) 1))) + (min-level-direct-child most-positive-fixnum) (end (save-excursion (org-end-of-subtree t t))) (regexp-fmt "^\\*\\{%d,%s\\}\\(?: \\|$\\)") - (past-first-child nil) ;; Make sure to skip inlinetasks. (re (format regexp-fmt current-level @@ -448,11 +479,12 @@ heading to appear." ;; MAX-LEVEL. Since we want to display it anyway, adjust ;; MAX-LEVEL accordingly. (while (re-search-forward re end t) - (unless past-first-child - (setq re (format regexp-fmt - current-level - (max (funcall outline-level) max-level))) - (setq past-first-child t)) + (setq current-level (funcall outline-level)) + (when (< current-level min-level-direct-child) + (setq min-level-direct-child current-level + re (format regexp-fmt + parent-level + (max min-level-direct-child max-level)))) (org-fold-heading nil)))))) (defun org-fold-show-subtree () @@ -496,12 +528,12 @@ Return a non-nil value when toggling is successful." comment-block dynamic-block example-block export-block quote-block special-block src-block verse-block)) (_ (error "Unknown category: %S" category)))) - (let* ((post (org-element-property :post-affiliated element)) + (let* ((post (org-element-post-affiliated element)) (start (save-excursion (goto-char post) (line-end-position))) (end (save-excursion - (goto-char (org-element-property :end element)) + (goto-char (org-element-end element)) (skip-chars-backward " \t\n") (line-end-position)))) ;; Do nothing when not before or at the block opening line or @@ -560,10 +592,12 @@ Return a non-nil value when toggling is successful." (interactive) (org-block-map (apply-partially #'org-fold-hide-block-toggle 'hide))) -(defun org-fold-hide-drawer-all () - "Fold all drawers in the current buffer." - (let ((begin (point-min)) - (end (point-max))) +(defun org-fold-hide-drawer-all (&optional begin end) + "Fold all drawers in the current buffer or active region BEGIN..END." + (interactive (list (and (use-region-p) (region-beginning)) + (and (use-region-p) (region-end)))) + (let ((begin (or begin (point-min))) + (end (or end (point-max)))) (org-fold--hide-drawers begin end))) (defun org-fold--hide-drawers (begin end) @@ -582,7 +616,7 @@ Return a non-nil value when toggling is successful." ;; Make sure to skip drawer entirely or we might flag it ;; another time when matching its ending line with ;; `org-drawer-regexp'. - (goto-char (org-element-property :end drawer)))))))) + (goto-char (org-element-end drawer)))))))) (defun org-fold-hide-archived-subtrees (beg end) "Re-hide all archived subtrees after a visibility state change." @@ -591,7 +625,7 @@ Return a non-nil value when toggling is successful." (re (concat org-outline-regexp-bol ".*:" org-archive-tag ":"))) (goto-char beg) ;; Include headline point is currently on. - (beginning-of-line) + (forward-line 0) (while (and (< (point) end) (re-search-forward re end t)) (when (member org-archive-tag (org-get-tags nil t)) (org-fold-subtree t) @@ -626,33 +660,27 @@ DETAIL is either nil, `minimal', `local', `ancestors', (when (org-invisible-p) ;; FIXME: No clue why, but otherwise the following might not work. (redisplay) - (let ((region (org-fold-get-region-at-point))) - ;; Reveal emphasis markers. - (when (eq detail 'local) - (let (org-hide-emphasis-markers - org-link-descriptive - org-pretty-entities - (org-hide-macro-markers nil) - (region (or (org-find-text-property-region (point) 'org-emphasis) - (org-find-text-property-region (point) 'org-macro) - (org-find-text-property-region (point) 'invisible) - region))) - ;; Silence byte-compiler. - (ignore org-hide-macro-markers) - (when region - (org-with-point-at (car region) - (beginning-of-line) - (let (font-lock-extend-region-functions) - (font-lock-fontify-region (max (point-min) (1- (car region))) (cdr region)))))) - ;; Unfold links. + ;; Reveal emphasis markers. + (when (eq detail 'local) + (let (org-hide-emphasis-markers + org-link-descriptive + org-pretty-entities + (org-hide-macro-markers nil) + (region (or (org-find-text-property-region (point) 'org-emphasis) + (org-find-text-property-region (point) 'org-macro) + (org-find-text-property-region (point) 'invisible)))) + ;; Silence byte-compiler. + (ignore org-hide-macro-markers) (when region - (dolist (spec '(org-link org-link-description)) - (org-fold-region (car region) (cdr region) nil spec)))) - (when region - (dolist (spec (org-fold-core-folding-spec-list)) - ;; Links are taken care by above. - (unless (memq spec '(org-link org-link-description)) - (org-fold-region (car region) (cdr region) nil spec)))))) + (org-with-point-at (car region) + (forward-line 0) + (let (font-lock-extend-region-functions) + (font-lock-fontify-region (max (point-min) (1- (car region))) (cdr region))))))) + (let (region) + (dolist (spec (org-fold-core-folding-spec-list)) + (setq region (org-fold-get-region-at-point spec)) + (when region + (org-fold-region (car region) (cdr region) nil spec))))) (unless (org-before-first-heading-p) (org-with-limited-levels (cl-case detail @@ -697,15 +725,15 @@ go to the parent and show the entire tree." ;;; Make isearch search in some text hidden via text properties. -(defun org-fold--isearch-reveal (&rest _) +(defun org-fold--isearch-reveal (pos) "Reveal text at POS found by isearch." - (org-fold-show-context 'isearch)) + (org-with-point-at pos + (org-fold-show-context 'isearch))) ;;; Handling changes in folded elements (defun org-fold--extend-changed-region (from to) - "Consider folded regions in the next/previous line when fixing -region visibility. + "Consider folded regions in the next/previous line when fixing region visibility. This function is intended to be used as a member of `org-fold-core-extend-changed-region-functions'." ;; If the edit is done in the first line of a folded drawer/block, @@ -724,7 +752,7 @@ the contents consists of blank lines. Assume that point is located at the header line." (org-with-wide-buffer - (beginning-of-line) + (forward-line 0) (org-fold-region (max (point-min) (1- (point))) (let ((endl (line-end-position))) @@ -735,7 +763,7 @@ Assume that point is located at the header line." (if (equal (point) (save-excursion (goto-char endl) - (org-end-of-subtree) + (org-end-of-subtree t) (skip-chars-forward "\n\t\r "))) (point) endl))) @@ -752,7 +780,7 @@ This function is intended to be used as :fragile property of ;; The line before beginning of the fold should be either a ;; headline or a list item. (backward-char) - (beginning-of-line) + (forward-line 0) ;; Make sure that headline is not partially hidden. (unless (org-fold-folded-p nil 'headline) (org-fold--reveal-headline-at-point)) @@ -764,14 +792,14 @@ This function is intended to be used as :fragile property of (org-fold--reveal-headline-at-point)))) ;; Make sure that headline after is not partially hidden. (goto-char (cdr region)) - (beginning-of-line) + (forward-line 0) (unless (org-fold-folded-p nil 'headline) (when (looking-at-p org-element-headline-re) (org-fold--reveal-headline-at-point))) ;; Check the validity of headline (goto-char (car region)) (backward-char) - (beginning-of-line) + (forward-line 0) (unless (let ((case-fold-search t)) (looking-at (rx-to-string `(or (regex ,(org-item-re)) @@ -807,7 +835,7 @@ This function is intended to be used as :fragile property of ;; The line before beginning of the fold should be the ;; first line of the drawer/block. (backward-char) - (beginning-of-line) + (forward-line 0) (unless (let ((case-fold-search t)) (looking-at begin-re)) ; the match-data will be used later (throw :exit (setq unfold? t)))) @@ -827,7 +855,7 @@ This function is intended to be used as :fragile property of ;; The last line of the folded text should match `end-re'. (save-excursion (goto-char fold-end) - (beginning-of-line) + (forward-line 0) (unless (let ((case-fold-search t)) (looking-at end-re)) (throw :exit (setq unfold? t)))) @@ -901,6 +929,19 @@ The detailed reaction depends on the user option ;; Don't do the edit, make the user repeat it in full visibility (user-error "Edit in invisible region aborted, repeat to confirm with text visible")))))))) +(defun org-fold-check-before-invisible-edit-maybe (&rest _) + "Check before invisible command by `this-command'." + (when (derived-mode-p 'org-mode) + (pcase (alist-get this-command org-fold-catch-invisible-edits-commands) + ((pred null) nil) + (kind (org-fold-check-before-invisible-edit kind))))) + +(defun org-fold--advice-edit-commands () + "Advice editing commands according to `org-fold-catch-invisible-edits-commands'. +The advices are installed in current buffer." + (dolist (command (mapcar #'car org-fold-catch-invisible-edits-commands)) + (advice-add command :before #'org-fold-check-before-invisible-edit-maybe))) + (provide 'org-fold) ;;; org-fold.el ends here diff --git a/elpa/org-9.6.7/org-footnote.el b/elpa/org-9.7.17/org-footnote.el similarity index 94% rename from elpa/org-9.6.7/org-footnote.el rename to elpa/org-9.7.17/org-footnote.el index 6bdd0b32..b886e4c0 100644 --- a/elpa/org-9.6.7/org-footnote.el +++ b/elpa/org-9.7.17/org-footnote.el @@ -1,9 +1,9 @@ ;;; org-footnote.el --- Footnote support in Org -*- lexical-binding: t; -*- ;; -;; Copyright (C) 2009-2023 Free Software Foundation, Inc. +;; Copyright (C) 2009-2024 Free Software Foundation, Inc. ;; ;; Author: Carsten Dominik -;; Keywords: outlines, hypermedia, calendar, wp +;; Keywords: outlines, hypermedia, calendar, text ;; URL: https://orgmode.org ;; ;; This file is part of GNU Emacs. @@ -45,9 +45,10 @@ (declare-function org-element-at-point "org-element" (&optional pom cached-only)) (declare-function org-element-class "org-element" (datum &optional parent)) (declare-function org-element-context "org-element" (&optional element)) -(declare-function org-element-lineage "org-element" (blob &optional types with-self)) -(declare-function org-element-property "org-element" (property element)) -(declare-function org-element-type "org-element" (element)) +(declare-function org-element-lineage "org-element-ast" (blob &optional types with-self)) +(declare-function org-element-property "org-element-ast" (property node)) +(declare-function org-element-type "org-element-ast" (node &optional anonymous)) +(declare-function org-element-type-p "org-element-ast" (node types)) (declare-function org-end-of-subtree "org" (&optional invisible-ok to-heading)) (declare-function org-fill-paragraph "org" (&optional justify region)) (declare-function org-in-block-p "org" (names)) @@ -136,15 +137,18 @@ Possible values are: nil Prompt the user for each label. t Create unique labels of the form [fn:1], [fn:2], etc. +anonymous Create anonymous footnotes confirm Like t, but let the user edit the created value. The label can be removed from the minibuffer to create an anonymous footnote. random Automatically generate a unique, random label." :group 'org-footnote + :package-version '(Org . "9.7") :type '(choice (const :tag "Prompt for label" nil) (const :tag "Create automatic [fn:N]" t) (const :tag "Offer automatic [fn:N] for editing" confirm) + (const :tag "Create anonymous [fn::]" anonymous) (const :tag "Create a random label" random)) :safe #'symbolp) @@ -183,21 +187,21 @@ extracted will be filled again." "Is point in a context where footnotes are allowed?" (save-match-data (not (or (org-at-comment-p) - (org-inside-LaTeX-fragment-p) - ;; Avoid literal example. - (org-in-verbatim-emphasis) - (save-excursion - (beginning-of-line) - (looking-at "[ \t]*:[ \t]+")) - ;; Avoid forbidden blocks. - (org-in-block-p org-footnote-forbidden-blocks))))) + (org-inside-LaTeX-fragment-p) + ;; Avoid literal example. + (org-in-verbatim-emphasis) + (save-excursion + (forward-line 0) + (looking-at "[ \t]*:[ \t]+")) + ;; Avoid forbidden blocks. + (org-in-block-p org-footnote-forbidden-blocks))))) (defun org-footnote-at-reference-p () "Non-nil if point is at a footnote reference. If so, return a list containing its label, beginning and ending positions, and the definition, when inline." (let ((reference (org-element-context))) - (when (eq 'footnote-reference (org-element-type reference)) + (when (org-element-type-p reference 'footnote-reference) (let ((end (save-excursion (goto-char (org-element-property :end reference)) (skip-chars-backward " \t") @@ -223,7 +227,7 @@ defined locally. The return value is nil if not at a footnote definition, and a list with label, start, end and definition of the footnote otherwise." - (pcase (org-element-lineage (org-element-at-point) '(footnote-definition) t) + (pcase (org-element-lineage (org-element-at-point) 'footnote-definition t) (`nil nil) (definition (let* ((label (org-element-property :label definition)) @@ -269,7 +273,7 @@ otherwise." ((memq type '(headline inlinetask)) (or (not (org-at-heading-p)) (and (save-excursion - (beginning-of-line) + (forward-line 0) (and (let ((case-fold-search t)) (not (looking-at-p "\\*+ END[ \t]*$"))) (let ((case-fold-search nil)) @@ -281,10 +285,10 @@ otherwise." ;; White spaces after an object or blank lines after an element ;; are OK. ((>= (point) - (save-excursion (goto-char (org-element-property :end context)) - (skip-chars-backward " \r\t\n") - (if (eq (org-element-class context) 'object) (point) - (line-beginning-position 2))))) + (save-excursion (goto-char (org-element-property :end context)) + (skip-chars-backward " \r\t\n") + (if (eq (org-element-class context) 'object) (point) + (line-beginning-position 2))))) ;; At the beginning of a footnote definition, right after the ;; label, is OK. ((eq type 'footnote-definition) (looking-at (rx space))) @@ -298,7 +302,7 @@ otherwise." ;; :contents-begin is not reliable on empty cells, so special ;; case it. (<= (save-excursion (skip-chars-backward " \t") (point)) - (org-element-property :contents-end context))) + (org-element-property :contents-end context))) ((let ((cbeg (org-element-property :contents-begin context)) (cend (org-element-property :contents-end context))) (and cbeg (>= (point) cbeg) (<= (point) cend)))))))) @@ -368,14 +372,14 @@ References are sorted according to a deep-reading order." ;; Ensure point is within the reference before parsing it. (backward-char) (let ((object (org-element-context))) - (when (eq (org-element-type object) 'footnote-reference) + (when (org-element-type-p object 'footnote-reference) (let* ((label (org-element-property :label object)) (begin (org-element-property :begin object)) (size (and (eq (org-element-property :type object) 'inline) (- (org-element-property :contents-end object) (org-element-property :contents-begin object))))) - (let ((d (org-element-lineage object '(footnote-definition)))) + (let ((d (org-element-lineage object 'footnote-definition))) (push (list label (copy-marker begin) (not d) size) references) (when d @@ -420,7 +424,7 @@ while collecting them." (backward-char) (let ((element (org-element-at-point))) (let ((label (org-element-property :label element))) - (when (and (eq (org-element-type element) 'footnote-definition) + (when (and (org-element-type-p element 'footnote-definition) (not (member label seen))) (push label seen) (let* ((beg (progn @@ -516,7 +520,7 @@ This function is meant to be used for fontification only." ;; Definition: also grab the last square bracket, matched in ;; `org-footnote-re' for non-inline footnotes. ((and (save-excursion - (beginning-of-line) + (forward-line 0) (save-match-data (org-footnote-in-valid-context-p))) (save-excursion (end-of-line) @@ -633,8 +637,8 @@ This function ignores narrowing, if any." (while (re-search-forward org-footnote-re nil t) (backward-char) (let ((context (org-element-context))) - (when (memq (org-element-type context) - '(footnote-definition footnote-reference)) + (when (org-element-type-p + context '(footnote-definition footnote-reference)) (let ((label (org-element-property :label context))) (when label (cl-pushnew label all :test #'equal)))))) all))) @@ -665,15 +669,16 @@ or new, let the user edit the definition of the footnote." (user-error "Cannot insert a footnote here")) (let* ((all (org-footnote-all-labels)) (label - (if (eq org-footnote-auto-label 'random) - (format "%x" (abs (random))) - (org-footnote-normalize-label - (let ((propose (org-footnote-unique-label all))) - (if (eq org-footnote-auto-label t) propose - (completing-read - "Label (leave empty for anonymous): " - (mapcar #'list all) nil nil - (and (eq org-footnote-auto-label 'confirm) propose)))))))) + (unless (eq org-footnote-auto-label 'anonymous) + (if (eq org-footnote-auto-label 'random) + (format "%x" (abs (random))) + (org-footnote-normalize-label + (let ((propose (org-footnote-unique-label all))) + (if (eq org-footnote-auto-label t) propose + (completing-read + "Label (leave empty for anonymous): " + (mapcar #'list all) nil nil + (and (eq org-footnote-auto-label 'confirm) propose))))))))) (cond ((not label) (insert "[fn::]") (backward-char 1)) diff --git a/elpa/org-9.6.7/org-goto.el b/elpa/org-9.7.17/org-goto.el similarity index 93% rename from elpa/org-9.6.7/org-goto.el rename to elpa/org-9.7.17/org-goto.el index 00bf5d46..f75cc9ed 100644 --- a/elpa/org-9.6.7/org-goto.el +++ b/elpa/org-9.7.17/org-goto.el @@ -1,9 +1,9 @@ ;;; org-goto.el --- Fast navigation in an Org buffer -*- lexical-binding: t; -*- -;; Copyright (C) 2012-2023 Free Software Foundation, Inc. +;; Copyright (C) 2012-2024 Free Software Foundation, Inc. ;; Author: Carsten Dominik -;; Keywords: outlines, hypermedia, calendar, wp +;; Keywords: outlines, hypermedia, calendar, text ;; This file is part of GNU Emacs. @@ -20,6 +20,8 @@ ;; You should have received a copy of the GNU General Public License ;; along with GNU Emacs. If not, see . +;;; Commentary: + ;;; Code: (require 'org-macs) @@ -102,7 +104,11 @@ When nil, you can use these keybindings to navigate the buffer: mouse-drag-region universal-argument org-occur))) (dolist (cmd cmds) (substitute-key-definition cmd cmd map global-map))) - (suppress-keymap map) + (if org-goto-auto-isearch + ;; Suppress 0-9 interpreted as digital arguments. + ;; Make them initiate isearch instead. + (suppress-keymap map t) + (suppress-keymap map)) (org-defkey map "\C-m" 'org-goto-ret) (org-defkey map [(return)] 'org-goto-ret) (org-defkey map [(left)] 'org-goto-left) @@ -145,7 +151,7 @@ When nil, you can use these keybindings to navigate the buffer: (search-backward string bound noerror)) (when (save-match-data (and (save-excursion - (beginning-of-line) + (forward-line 0) (looking-at org-complex-heading-regexp)) (or (not (match-beginning 5)) (< (point) (match-beginning 5))))) @@ -172,7 +178,7 @@ When nil, you can use these keybindings to navigate the buffer: (interactive) (if (org-at-heading-p) (progn - (beginning-of-line 1) + (forward-line 0) (setq org-goto-selected-point (point) org-goto-exit-command 'left) (throw 'exit nil)) @@ -211,12 +217,12 @@ position or nil." (help (or help org-goto-help))) (save-excursion (save-window-excursion - (delete-other-windows) (and (get-buffer "*org-goto*") (kill-buffer "*org-goto*")) - (pop-to-buffer-same-window - (condition-case nil + (pop-to-buffer + (condition-case nil (make-indirect-buffer (current-buffer) "*org-goto*" t) - (error (make-indirect-buffer (current-buffer) "*org-goto*" t)))) + (error (make-indirect-buffer (current-buffer) "*org-goto*" t))) + '(org-display-buffer-full-frame)) (let (temp-buffer-show-function temp-buffer-show-hook) (with-output-to-temp-buffer "*Org Help*" (princ (format help (if org-goto-auto-isearch @@ -234,8 +240,10 @@ position or nil." (let (org-special-ctrl-a/e) (org-beginning-of-line)) (message "Select location and press RET") (use-local-map org-goto-map) - (recursive-edit))) - (kill-buffer "*org-goto*") + (unwind-protect (recursive-edit) + (when-let* ((window (get-buffer-window "*Org Help*" t))) + (quit-window 'kill window))))) + (when (get-buffer "*org-goto*") (kill-buffer "*org-goto*")) (cons org-goto-selected-point org-goto-exit-command))) ;;;###autoload diff --git a/elpa/org-9.6.7/org-habit.el b/elpa/org-9.7.17/org-habit.el similarity index 97% rename from elpa/org-9.6.7/org-habit.el rename to elpa/org-9.7.17/org-habit.el index fb6a48b5..8b344f0c 100644 --- a/elpa/org-9.6.7/org-habit.el +++ b/elpa/org-9.7.17/org-habit.el @@ -1,9 +1,9 @@ ;;; org-habit.el --- The habit tracking code for Org -*- lexical-binding: t; -*- -;; Copyright (C) 2009-2023 Free Software Foundation, Inc. +;; Copyright (C) 2009-2024 Free Software Foundation, Inc. ;; Author: John Wiegley -;; Keywords: outlines, hypermedia, calendar, wp +;; Keywords: outlines, hypermedia, calendar, text ;; URL: https://orgmode.org ;; ;; This file is part of GNU Emacs. @@ -69,7 +69,7 @@ relative to the current effective date." :type 'boolean) (defcustom org-habit-show-all-today nil - "If non-nil, will show the consistency graph of all habits on + "If non-nil, show the consistency graph of all habits on today's agenda, even if they are not scheduled." :group 'org-habit :type 'boolean) @@ -168,9 +168,10 @@ means of creating calendar-based reminders." ("m" . 30.4) ("y" . 365.25)))))) (error "Invalid duration string: %s" ts))) -(defun org-is-habit-p (&optional pom) - "Is the task at POM or point a habit?" - (string= "habit" (org-entry-get (or pom (point)) "STYLE"))) +(defun org-is-habit-p (&optional epom) + "Is the task at EPOM or point a habit? +EPOM is an element, marker, or buffer position." + (string= "habit" (org-entry-get epom "STYLE" 'selective))) (defun org-habit-parse-todo (&optional pom) "Parse the TODO surrounding point for its habit-related data. @@ -263,8 +264,8 @@ This list represents a \"habit\" for the rest of this module." (defsubst org-habit-repeat-type (habit) (nth 5 habit)) -(defsubst org-habit-get-priority (habit &optional moment) - "Determine the relative priority of a habit. +(defsubst org-habit-get-urgency (habit &optional moment) + "Determine the relative urgency of a habit. This must take into account not just urgency, but consistency as well." (let ((pri 1000) (now (if moment (time-to-days moment) (org-today))) diff --git a/elpa/org-9.6.7/org-id.el b/elpa/org-9.7.17/org-id.el similarity index 72% rename from elpa/org-9.6.7/org-id.el rename to elpa/org-9.7.17/org-id.el index 490e4dde..e247fab1 100644 --- a/elpa/org-9.6.7/org-id.el +++ b/elpa/org-9.7.17/org-id.el @@ -1,9 +1,9 @@ ;;; org-id.el --- Global identifiers for Org entries -*- lexical-binding: t; -*- ;; -;; Copyright (C) 2008-2023 Free Software Foundation, Inc. +;; Copyright (C) 2008-2024 Free Software Foundation, Inc. ;; ;; Author: Carsten Dominik -;; Keywords: outlines, hypermedia, calendar, wp +;; Keywords: outlines, hypermedia, calendar, text ;; URL: https://orgmode.org ;; ;; This file is part of GNU Emacs. @@ -29,13 +29,13 @@ ;; are provided that create and retrieve such identifiers, and that find ;; entries based on the identifier. -;; Identifiers consist of a prefix (default "Org" given by the variable +;; Identifiers consist of a prefix (given by the variable ;; `org-id-prefix') and a unique part that can be created by a number -;; of different methods, see the variable `org-id-method'. -;; Org has a builtin method that uses a compact encoding of the creation -;; time of the ID, with microsecond accuracy. This virtually -;; guarantees globally unique identifiers, even if several people are -;; creating IDs at the same time in files that will eventually be used +;; of different methods, see the variable `org-id-method'. Org has a +;; builtin method that uses a compact encoding of the creation time of +;; the ID, with microsecond accuracy. This virtually guarantees +;; globally unique identifiers, even if several people are creating +;; IDs at the same time in files that will eventually be used ;; together. ;; ;; By default Org uses UUIDs as global unique identifiers. @@ -74,6 +74,7 @@ (org-assert-version) (require 'org) +(require 'org-element-ast) (require 'org-refile) (require 'ol) @@ -128,6 +129,46 @@ nil Never use an ID to make a link, instead link using a text search for (const :tag "Only use existing" use-existing) (const :tag "Do not use ID to create link" nil))) +(defcustom org-id-link-consider-parent-id nil + "Non-nil means storing a link to an Org entry considers inherited IDs. + +When this option is non-nil and `org-id-link-use-context' is +enabled, ID properties inherited from parent entries will be +considered when storing an ID link. If no ID is found in this +way, a new one may be created as normal (see +`org-id-link-to-org-use-id'). + +For example, given this org file: + +* Parent +:PROPERTIES: +:ID: abc +:END: +** Child 1 +** Child 2 + +With `org-id-link-consider-parent-id' and +`org-id-link-use-context' both enabled, storing a link with point +at \"Child 1\" will produce a link \"\". This +allows linking to uniquely-named sub-entries within a parent +entry with an ID, without requiring every sub-entry to have its +own ID." + :group 'org-link-store + :group 'org-id + :package-version '(Org . "9.7") + :type 'boolean) + +(defcustom org-id-link-use-context t + "Non-nil means enables search string context in org-id links. + +Search strings are added by `org-id-store-link' when both the +general option `org-link-context-for-files' and the org-id option +`org-id-link-use-context' are non-nil." + :group 'org-link-store + :group 'org-id + :package-version '(Org . "9.7") + :type 'boolean) + (defcustom org-id-uuid-program "uuidgen" "The uuidgen program." :group 'org-id @@ -225,6 +266,8 @@ systems." (defvar org-id-locations nil "List of files with IDs in those files.") +(defvar org-id--locations-checksum nil + "Last checksum corresponding to ID files and their modifications.") (defvar org-id-files nil "List of files that contain IDs.") @@ -277,25 +320,32 @@ This is useful when working with contents in a temporary buffer that will be copied back to the original.") ;;;###autoload -(defun org-id-get (&optional pom create prefix) - "Get the ID property of the entry at point-or-marker POM. -If POM is nil, refer to the entry at point. -If the entry does not have an ID, the function returns nil. -However, when CREATE is non-nil, create an ID if none is present already. -PREFIX will be passed through to `org-id-new'. -In any case, the ID of the entry is returned." - (org-with-point-at pom - (let ((id (org-entry-get nil "ID"))) - (cond - ((and id (stringp id) (string-match "\\S-" id)) - id) - (create - (setq id (org-id-new prefix)) - (org-entry-put pom "ID" id) - (org-id-add-location id +(defun org-id-get (&optional epom create prefix inherit) + "Get the ID of the entry at EPOM. + +EPOM is an element, marker, or buffer position. If EPOM is nil, +refer to the entry at point. + +If INHERIT is non-nil, ID properties inherited from parent +entries are considered. Otherwise, only ID properties on the +entry itself are considered. + +When CREATE is nil, return the ID of the entry if found, +otherwise nil. When CREATE is non-nil, create an ID if none has +been found, and return the new ID. PREFIX will be passed through +to `org-id-new'." + (let ((id (org-entry-get epom "ID" (and inherit t)))) + (cond + ((and id (stringp id) (string-match "\\S-" id)) + id) + (create + (setq id (org-id-new prefix)) + (org-entry-put epom "ID" id) + (org-with-point-at epom + (org-id-add-location id (or org-id-overriding-file-name - (buffer-file-name (buffer-base-buffer)))) - id))))) + (buffer-file-name (buffer-base-buffer))))) + id)))) ;;;###autoload (defun org-id-get-with-outline-path-completion (&optional targets) @@ -399,30 +449,6 @@ So a typical ID could look like \"Org:4nd91V40HI\"." (t (error "Invalid `org-id-method'"))) (concat prefix unique))) -(defun org-id-uuid () - "Return string with random (version 4) UUID." - (let ((rnd (md5 (format "%s%s%s%s%s%s%s" - (random) - (org-time-convert-to-list nil) - (user-uid) - (emacs-pid) - (user-full-name) - user-mail-address - (recent-keys))))) - (format "%s-%s-4%s-%s%s-%s" - (substring rnd 0 8) - (substring rnd 8 12) - (substring rnd 13 16) - (format "%x" - (logior - #b10000000 - (logand - #b10111111 - (string-to-number - (substring rnd 16 18) 16)))) - (substring rnd 18 20) - (substring rnd 20 32)))) - (defun org-id-int-to-b36-one-digit (integer) "Convert INTEGER between 0 and 61 into a single character 0..9, A..Z, a..z." (cond @@ -500,7 +526,6 @@ If SILENT is non-nil, messages are suppressed." (interactive) (unless org-id-track-globally (error "Please turn on `org-id-track-globally' if you want to track IDs")) - (setq org-id-locations nil) (let* ((files (delete-dups (mapcar #'file-truename @@ -524,11 +549,18 @@ If SILENT is non-nil, messages are suppressed." (nfiles (length files)) (id-regexp (rx (seq bol (0+ (any "\t ")) ":ID:" (1+ " ") (not (any " "))))) - (seen-ids nil) + (seen-ids (make-hash-table :test #'equal)) (ndup 0) - (i 0)) - (with-temp-buffer - (org-element-with-disabled-cache + (i 0) + (checksum + (mapcar + (lambda (f) + (when (file-exists-p f) + (list f (file-attribute-modification-time (file-attributes f))))) + (sort (copy-sequence files) #'string<)))) + (unless (equal checksum org-id--locations-checksum) ; Files have changed since the last update. + (setq org-id-locations nil) + (with-temp-buffer (delay-mode-hooks (org-mode) (dolist (file files) @@ -538,29 +570,32 @@ If SILENT is non-nil, messages are suppressed." (message "Finding ID locations (%d/%d files): %s" i nfiles file)) (insert-file-contents file nil nil nil 'replace) (let ((ids nil) + node (case-fold-search t)) (org-with-point-at 1 (while (re-search-forward id-regexp nil t) - (when (org-at-property-p) - (push (org-entry-get (point) "ID") ids))) + (setq node (org-element-at-point)) + (when (org-element-type-p node 'node-property) + (push (org-element-property :value node) ids))) (when ids (push (cons (abbreviate-file-name file) ids) org-id-locations) (dolist (id ids) (cond - ((not (member id seen-ids)) (push id seen-ids)) + ((not (gethash id seen-ids)) (puthash id t seen-ids)) (silent nil) (t (message "Duplicate ID %S" id) - (cl-incf ndup)))))))))))) - (setq org-id-files (mapcar #'car org-id-locations)) - (org-id-locations-save) - ;; Now convert to a hash table. - (setq org-id-locations (org-id-alist-to-hash org-id-locations)) - (when (and (not silent) (> ndup 0)) - (warn "WARNING: %d duplicate IDs found, check *Messages* buffer" ndup)) - (message "%d files scanned, %d files contains IDs, and %d IDs found." - nfiles (length org-id-files) (hash-table-count org-id-locations)) + (cl-incf ndup))))))))))) + (setq org-id-files (mapcar #'car org-id-locations)) + (org-id-locations-save) + ;; Now convert to a hash table. + (setq org-id-locations (org-id-alist-to-hash org-id-locations)) + (setq org-id--locations-checksum checksum) + (when (and (not silent) (> ndup 0)) + (warn "WARNING: %d duplicate IDs found, check *Messages* buffer" ndup)) + (message "%d files scanned, %d files contains IDs, and %d IDs found." + nfiles (length org-id-files) (hash-table-count org-id-locations))) org-id-locations)) (defun org-id-locations-save () @@ -686,34 +721,81 @@ optional argument MARKERP, return the position as a new marker." ((not (file-exists-p file)) nil) (t (let* ((visiting (find-buffer-visiting file)) - (buffer (or visiting (find-file-noselect file)))) + (buffer (or visiting + (if markerp (find-file-noselect file) + (org-get-buffer-create " *Org ID temp*" t))))) (unwind-protect (with-current-buffer buffer + (unless (derived-mode-p 'org-mode) (org-mode)) + (unless (or visiting markerp) + (buffer-disable-undo) + ;; FIXME: In Emacs 27, `insert-file-contents' seemingly + ;; does not trigger modification hooks in some + ;; scenarios. This is manifested in test failures due + ;; to element cache losing track of the modifications. + (org-element-cache-reset) + (insert-file-contents file nil nil nil 'replace)) (let ((pos (org-find-entry-with-id id))) (cond ((null pos) nil) (markerp (move-marker (make-marker) pos buffer)) (t (cons file pos))))) - ;; Remove opened buffer in the process. - (unless (or visiting markerp) (kill-buffer buffer))))))) + ;; Clean temporarily buffer if we don't need to keep it. + (unless (or visiting markerp) + (with-current-buffer buffer (erase-buffer)))))))) ;; id link type -;; Calling the following function is hard-coded into `org-store-link', -;; so we do have to add it to `org-store-link-functions'. +(defun org-id--get-id-to-store-link (&optional create) + "Get or create the relevant ID for storing a link. + +Optional argument CREATE is passed to `org-id-get'. + +Inherited IDs are only considered when +`org-id-link-consider-parent-id', `org-id-link-use-context' and +`org-link-context-for-files' are all enabled, since inherited IDs +are confusing without the additional search string context. + +Note that this function resets the +`org-entry-property-inherited-from' marker: it will either point +to nil (if the id was not inherited) or to the point it was +inherited from." + (let* ((inherit-id (and org-id-link-consider-parent-id + org-id-link-use-context + org-link-context-for-files))) + (move-marker org-entry-property-inherited-from nil) + (org-id-get nil create nil inherit-id))) ;;;###autoload (defun org-id-store-link () "Store a link to the current entry, using its ID. -If before first heading store first title-keyword as description -or filename if no title." +The link description is based on the heading, or if before the +first heading, the title keyword if available, or else the +filename. + +When `org-link-context-for-files' and `org-id-link-use-context' +are non-nil, add a search string to the link. The link +description is then based on the search string target. + +When in addition `org-id-link-consider-parent-id' is non-nil, the +ID can be inherited from a parent entry, with the search string +used to still link to the current location." (interactive) - (when (and (buffer-file-name (buffer-base-buffer)) (derived-mode-p 'org-mode)) - (let* ((link (concat "id:" (org-id-get-create))) + (when (and (buffer-file-name (buffer-base-buffer)) + (derived-mode-p 'org-mode)) + ;; Get the precise target first, in case looking for an id causes + ;; a properties drawer to be added at the current location. + (let* ((precise-target (and org-link-context-for-files + org-id-link-use-context + (org-link-precise-link-target))) + (link (concat "id:" (org-id--get-id-to-store-link 'create))) + (id-location (or (and org-entry-property-inherited-from + (marker-position org-entry-property-inherited-from)) + (save-excursion (org-back-to-heading-or-point-min t) (point)))) (case-fold-search nil) (desc (save-excursion - (org-back-to-heading-or-point-min t) + (goto-char id-location) (cond ((org-before-first-heading-p) (let ((keywords (org-collect-keywords '("TITLE")))) (if keywords @@ -725,14 +807,59 @@ or filename if no title." (match-string 4) (match-string 0))) (t link))))) + ;; Precise targets should be after id-location to avoid + ;; duplicating the current headline as a search string + (when (and precise-target + (> (nth 2 precise-target) id-location)) + (setq link (concat link "::" (nth 0 precise-target))) + (setq desc (nth 1 precise-target))) (org-link-store-props :link link :description desc :type "id") link))) -(defun org-id-open (id _) - "Go to the entry with id ID." - (org-mark-ring-push) - (let ((m (org-id-find id 'marker)) - cmd) +;;;###autoload +(defun org-id-store-link-maybe (&optional interactive?) + "Store a link to the current entry using its ID if enabled. + +The value of `org-id-link-to-org-use-id' determines whether an ID +link should be stored, using `org-id-store-link'. + +Assume the function is called interactively if INTERACTIVE? is +non-nil." + (when (and (buffer-file-name (buffer-base-buffer)) + (derived-mode-p 'org-mode) + (or (eq org-id-link-to-org-use-id t) + (and interactive? + (or (eq org-id-link-to-org-use-id 'create-if-interactive) + (and (eq org-id-link-to-org-use-id + 'create-if-interactive-and-no-custom-id) + (not (org-entry-get nil "CUSTOM_ID"))))) + ;; 'use-existing + (and org-id-link-to-org-use-id + (org-id--get-id-to-store-link)))) + (org-id-store-link))) + +(defun org-id-open (link _) + "Go to the entry indicated by id link LINK. + +The link can include a search string after \"::\", which is +passed to `org-link-search'. + +For backwards compatibility with IDs that contain \"::\", if no +match is found for the ID, the full link string including \"::\" +will be tried as an ID." + (let* ((option (and (string-match "::\\(.*\\)\\'" link) + (match-string 1 link))) + (id (if (not option) link + (substring link 0 (match-beginning 0)))) + m cmd) + (org-mark-ring-push) + (setq m (org-id-find id 'marker)) + (when (and (not m) option) + ;; Backwards compatibility: if id is not found, try treating + ;; whole link as an id. + (setq m (org-id-find link 'marker)) + (when m + (setq option nil))) (unless m (error "Cannot find entry with ID \"%s\"" id)) ;; Use a buffer-switching command in analogy to finding files @@ -749,9 +876,17 @@ or filename if no title." (funcall cmd (marker-buffer m))) (goto-char m) (move-marker m nil) + (when option + (save-restriction + (unless (org-before-first-heading-p) + (org-narrow-to-subtree)) + (org-link-search option nil nil + (org-element-lineage (org-element-at-point) 'headline t)))) (org-fold-show-context))) -(org-link-set-parameters "id" :follow #'org-id-open) +(org-link-set-parameters "id" + :follow #'org-id-open + :store #'org-id-store-link-maybe) (provide 'org-id) diff --git a/elpa/org-9.6.7/org-indent.el b/elpa/org-9.7.17/org-indent.el similarity index 96% rename from elpa/org-9.6.7/org-indent.el rename to elpa/org-9.7.17/org-indent.el index fe523387..cabed6ac 100644 --- a/elpa/org-9.6.7/org-indent.el +++ b/elpa/org-9.7.17/org-indent.el @@ -1,9 +1,9 @@ ;;; org-indent.el --- Dynamic indentation for Org -*- lexical-binding: t; -*- -;; Copyright (C) 2009-2023 Free Software Foundation, Inc. +;; Copyright (C) 2009-2024 Free Software Foundation, Inc. ;; ;; Author: Carsten Dominik -;; Keywords: outlines, hypermedia, calendar, wp +;; Keywords: outlines, hypermedia, calendar, text ;; URL: https://orgmode.org ;; ;; This file is part of GNU Emacs. @@ -103,6 +103,14 @@ For details see the variable `org-adapt-indentation'." :group 'org-indent :type 'integer) +(defcustom org-indent-post-buffer-init-functions nil + "Hook run after org-indent finishes initializing a buffer. +The function(s) in this hook must accept a single argument representing +the initialized buffer." + :group 'org-indent + :package-version '(Org . "9.7") + :type 'hook) + (defface org-indent '((t (:inherit org-hide))) "Face for outline indentation. The default is to make it look like whitespace. But you may find it @@ -290,7 +298,8 @@ a time value." ;; Job is complete: un-agentize buffer. (unless interruptp (setq org-indent-agentized-buffers - (delq buffer org-indent-agentized-buffers)))))))) + (delq buffer org-indent-agentized-buffers)) + (run-hook-with-args 'org-indent-post-buffer-init-functions buffer))))))) (defun org-indent-set-line-properties (level indentation &optional heading) "Set prefix properties on current line an move to next one. @@ -328,7 +337,7 @@ stopped." (save-match-data (org-with-wide-buffer (goto-char beg) - (beginning-of-line) + (forward-line 0) ;; Initialize prefix at BEG, according to current entry's level. (let* ((case-fold-search t) (limited-re (org-get-limited-outline-regexp)) @@ -410,7 +419,7 @@ This function is meant to be called by `after-change-functions'." (if (or org-indent-modified-headline-flag (save-excursion (goto-char beg) - (beginning-of-line) + (forward-line 0) (re-search-forward (org-with-limited-levels org-outline-regexp-bol) (save-excursion diff --git a/elpa/org-9.6.7/org-inlinetask.el b/elpa/org-9.7.17/org-inlinetask.el similarity index 96% rename from elpa/org-9.6.7/org-inlinetask.el rename to elpa/org-9.7.17/org-inlinetask.el index cb7fdf88..3292250c 100644 --- a/elpa/org-9.6.7/org-inlinetask.el +++ b/elpa/org-9.7.17/org-inlinetask.el @@ -1,9 +1,9 @@ ;;; org-inlinetask.el --- Tasks Independent of Outline Hierarchy -*- lexical-binding: t; -*- -;; Copyright (C) 2009-2023 Free Software Foundation, Inc. +;; Copyright (C) 2009-2024 Free Software Foundation, Inc. ;; ;; Author: Carsten Dominik -;; Keywords: outlines, hypermedia, calendar, wp +;; Keywords: outlines, hypermedia, calendar, text ;; URL: https://orgmode.org ;; This file is part of GNU Emacs. @@ -94,9 +94,8 @@ Don't set it to something higher than `29' or clocking will break since this is the hardcoded maximum number of stars `org-clock-sum' will work with. It is strongly recommended that you set `org-cycle-max-level' not at all, -or to a number smaller than this one. In fact, when `org-cycle-max-level' is -not set, it will be assumed to be one less than the value of smaller than -the value of this variable." +or to a number smaller than this one. See `org-cycle-max-level' +docstring for more details." :group 'org-inlinetask :type '(choice (const :tag "Off" nil) @@ -173,9 +172,9 @@ The number of levels is controlled by `org-inlinetask-min-level'." (not (org-inlinetask-end-p)))) (defun org-inlinetask-in-task-p () - "Return true if point is inside an inline task." + "Return non-nil if point is inside an inline task." (save-excursion - (beginning-of-line) + (forward-line 0) (let ((case-fold-search t)) (or (looking-at-p (concat (org-inlinetask-outline-regexp) "\\(?:.*\\)")) (and (re-search-forward "^\\*+[ \t]+" nil t) @@ -194,7 +193,7 @@ The number of levels is controlled by `org-inlinetask-min-level'." "Go to the end of the inline task at point. Return point." (save-match-data - (beginning-of-line) + (forward-line 0) (let ((case-fold-search t) (inlinetask-re (org-inlinetask-outline-regexp))) (cond @@ -242,7 +241,7 @@ going below `org-inlinetask-min-level'." (replace-match down-task nil t nil 1) (org-inlinetask-goto-end) (if (and (eobp) (looking-back "END\\s-*" (line-beginning-position))) - (beginning-of-line) + (forward-line 0) (forward-line -1)) (unless (= (point) beg) (looking-at (org-inlinetask-outline-regexp)) @@ -268,7 +267,7 @@ If the task has an end part, also demote it." (replace-match down-task nil t nil 1) (org-inlinetask-goto-end) (if (and (eobp) (looking-back "END\\s-*" (line-beginning-position))) - (beginning-of-line) + (forward-line 0) (forward-line -1)) (unless (= (point) beg) (looking-at (org-inlinetask-outline-regexp)) diff --git a/elpa/org-9.6.7/org-keys.el b/elpa/org-9.7.17/org-keys.el similarity index 89% rename from elpa/org-9.6.7/org-keys.el rename to elpa/org-9.7.17/org-keys.el index 37a150bb..5e9e666a 100644 --- a/elpa/org-9.6.7/org-keys.el +++ b/elpa/org-9.7.17/org-keys.el @@ -1,6 +1,6 @@ ;;; org-keys.el --- Key bindings for Org mode -*- lexical-binding: t; -*- -;; Copyright (C) 2018-2023 Free Software Foundation, Inc. +;; Copyright (C) 2018-2024 Free Software Foundation, Inc. ;; Author: Nicolas Goaziou @@ -85,11 +85,26 @@ (declare-function org-down-element "org" ()) (declare-function org-edit-special "org" (&optional arg)) (declare-function org-element-at-point "org-element" (&optional pom cached-only)) -(declare-function org-element-type "org-element" (element)) +(declare-function org-element-type-p "org-element-ast" (node types)) (declare-function org-emphasize "org" (&optional char)) (declare-function org-end-of-line "org" (&optional n)) (declare-function org-entry-put "org" (pom property value)) (declare-function org-eval-in-calendar "org" (form &optional keepdate)) +(declare-function org-calendar-goto-today-or-insert-dot "org" ()) +(declare-function org-calendar-goto-today "org" ()) +(declare-function org-calendar-backward-month "org" ()) +(declare-function org-calendar-forward-month "org" ()) +(declare-function org-calendar-backward-year "org" ()) +(declare-function org-calendar-forward-year "org" ()) +(declare-function org-calendar-backward-week "org" ()) +(declare-function org-calendar-forward-week "org" ()) +(declare-function org-calendar-backward-day "org" ()) +(declare-function org-calendar-forward-day "org" ()) +(declare-function org-calendar-view-entries "org" ()) +(declare-function org-calendar-scroll-month-left "org" ()) +(declare-function org-calendar-scroll-month-right "org" ()) +(declare-function org-calendar-scroll-three-months-left "org" ()) +(declare-function org-calendar-scroll-three-months-right "org" ()) (declare-function org-evaluate-time-range "org" (&optional to-buffer)) (declare-function org-export-dispatch "org" (&optional arg)) (declare-function org-feed-goto-inbox "org" (feed)) @@ -190,8 +205,8 @@ (declare-function org-table-sum "org" (&optional beg end nlast)) (declare-function org-table-toggle-coordinate-overlays "org" ()) (declare-function org-table-toggle-formula-debugger "org" ()) -(declare-function org-time-stamp "org" (arg &optional inactive)) -(declare-function org-time-stamp-inactive "org" (&optional arg)) +(declare-function org-timestamp "org" (arg &optional inactive)) +(declare-function org-timestamp-inactive "org" (&optional arg)) (declare-function org-timer "org" (&optional restart no-insert)) (declare-function org-timer-item "org" (&optional arg)) (declare-function org-timer-pause-or-continue "org" (&optional stop)) @@ -210,7 +225,7 @@ (declare-function org-toggle-ordered-property "org" ()) (declare-function org-toggle-pretty-entities "org" ()) (declare-function org-toggle-tags-groups "org" ()) -(declare-function org-toggle-time-stamp-overlays "org" ()) +(declare-function org-toggle-timestamp-overlays "org" ()) (declare-function org-transpose-element "org" ()) (declare-function org-transpose-words "org" ()) (declare-function org-tree-to-indirect-buffer "org" (&optional arg)) @@ -273,7 +288,7 @@ therefore you'll have to restart Emacs to apply it after changing." (defcustom org-mouse-1-follows-link (if (boundp 'mouse-1-click-follows-link) mouse-1-click-follows-link t) - "Non-nil means mouse-1 on a link will follow the link. + "Non-nil means Mouse-1 on a link will follow the link. A longer mouse click will still set point. Needs to be set before org.el is loaded." :group 'org-link-follow @@ -298,7 +313,7 @@ implementation is bad." :type 'hook) (defcustom org-return-follows-link nil - "Non-nil means on links RET will follow the link. + "Non-nil means on links RET will open links, timestamps, and citations. In tables, the special behavior of RET has precedence." :group 'org-link-follow :type 'boolean @@ -309,7 +324,7 @@ In tables, the special behavior of RET has precedence." ;;;; Base functions (defun org-key (key) - "Select key according to `org-replace-disputed-keys' and `org-disputed-keys'. + "Select KEY according to `org-replace-disputed-keys' and `org-disputed-keys'. Or return the original if not disputed." (when org-replace-disputed-keys (let* ((nkey (key-description key)) @@ -319,7 +334,7 @@ Or return the original if not disputed." key) (defun org-defkey (keymap key def) - "Define a key, possibly translated, as returned by `org-key'." + "Define KEY, possibly translated, as returned by `org-key' in KEYMAP to DEF." (define-key keymap (org-key key) def)) (defun org-remap (map &rest commands) @@ -349,71 +364,25 @@ COMMANDS is a list of alternating OLDDEF NEWDEF command names." (defvar org-read-date-minibuffer-local-map (let* ((map (make-sparse-keymap))) (set-keymap-parent map minibuffer-local-map) - (org-defkey map (kbd ".") - (lambda () (interactive) - ;; Are we at the beginning of the prompt? - (if (looking-back "^[^:]+: " - (let ((inhibit-field-text-motion t)) - (line-beginning-position))) - (org-eval-in-calendar '(calendar-goto-today)) - (insert ".")))) - (org-defkey map (kbd "C-.") - (lambda () (interactive) - (org-eval-in-calendar '(calendar-goto-today)))) - (org-defkey map (kbd "M-S-") - (lambda () (interactive) - (org-eval-in-calendar '(calendar-backward-month 1)))) - (org-defkey map (kbd "ESC S-") - (lambda () (interactive) - (org-eval-in-calendar '(calendar-backward-month 1)))) - (org-defkey map (kbd "M-S-") - (lambda () (interactive) - (org-eval-in-calendar '(calendar-forward-month 1)))) - (org-defkey map (kbd "ESC S-") - (lambda () (interactive) - (org-eval-in-calendar '(calendar-forward-month 1)))) - (org-defkey map (kbd "M-S-") - (lambda () (interactive) - (org-eval-in-calendar '(calendar-backward-year 1)))) - (org-defkey map (kbd "ESC S-") - (lambda () (interactive) - (org-eval-in-calendar '(calendar-backward-year 1)))) - (org-defkey map (kbd "M-S-") - (lambda () (interactive) - (org-eval-in-calendar '(calendar-forward-year 1)))) - (org-defkey map (kbd "ESC S-") - (lambda () (interactive) - (org-eval-in-calendar '(calendar-forward-year 1)))) - (org-defkey map (kbd "S-") - (lambda () (interactive) - (org-eval-in-calendar '(calendar-backward-week 1)))) - (org-defkey map (kbd "S-") - (lambda () (interactive) - (org-eval-in-calendar '(calendar-forward-week 1)))) - (org-defkey map (kbd "S-") - (lambda () (interactive) - (org-eval-in-calendar '(calendar-backward-day 1)))) - (org-defkey map (kbd "S-") - (lambda () (interactive) - (org-eval-in-calendar '(calendar-forward-day 1)))) - (org-defkey map (kbd "!") - (lambda () (interactive) - (org-eval-in-calendar '(diary-view-entries)) - (message ""))) - (org-defkey map (kbd ">") - (lambda () (interactive) - (org-eval-in-calendar '(calendar-scroll-left 1)))) - (org-defkey map (kbd "<") - (lambda () (interactive) - (org-eval-in-calendar '(calendar-scroll-right 1)))) - (org-defkey map (kbd "C-v") - (lambda () (interactive) - (org-eval-in-calendar - '(calendar-scroll-left-three-months 1)))) - (org-defkey map (kbd "M-v") - (lambda () (interactive) - (org-eval-in-calendar - '(calendar-scroll-right-three-months 1)))) + (org-defkey map (kbd ".") #'org-calendar-goto-today-or-insert-dot) + (org-defkey map (kbd "C-.") #'org-calendar-goto-today) + (org-defkey map (kbd "M-S-") #'org-calendar-backward-month) + (org-defkey map (kbd "ESC S-") #'org-calendar-backward-month) + (org-defkey map (kbd "M-S-") #'org-calendar-forward-month) + (org-defkey map (kbd "ESC S-") #'org-calendar-forward-month) + (org-defkey map (kbd "M-S-") #'org-calendar-backward-year) + (org-defkey map (kbd "ESC S-") #'org-calendar-backward-year) + (org-defkey map (kbd "M-S-") #'org-calendar-forward-year) + (org-defkey map (kbd "ESC S-") #'org-calendar-forward-year) + (org-defkey map (kbd "S-") #'org-calendar-backward-week) + (org-defkey map (kbd "S-") #'org-calendar-forward-week) + (org-defkey map (kbd "S-") #'org-calendar-backward-day) + (org-defkey map (kbd "S-") #'org-calendar-forward-day) + (org-defkey map (kbd "!") #'org-calendar-view-entries) + (org-defkey map (kbd ">") #'org-calendar-scroll-month-left) + (org-defkey map (kbd "<") #'org-calendar-scroll-month-right) + (org-defkey map (kbd "C-v") #'org-calendar-scroll-three-months-left) + (org-defkey map (kbd "M-v") #'org-calendar-scroll-three-months-right) map) "Keymap for minibuffer commands when using `org-read-date'.") @@ -503,6 +472,7 @@ COMMANDS is a list of alternating OLDDEF NEWDEF command names." (org-defkey org-mode-map (kbd "C-c C-x c") #'org-table-copy-down) (org-defkey org-mode-map (kbd "C-c C-x m") #'org-meta-return) (org-defkey org-mode-map (kbd "C-c C-x M") #'org-insert-todo-heading) + (org-defkey org-mode-map (kbd "C-c C-x s") #'org-insert-structure-template) (org-defkey org-mode-map (kbd "C-c C-x RET") #'org-meta-return) (org-defkey org-mode-map (kbd "ESC RET") #'org-meta-return) (org-defkey org-mode-map (kbd "ESC ") #'org-metaleft) @@ -593,8 +563,8 @@ COMMANDS is a list of alternating OLDDEF NEWDEF command names." (org-defkey org-mode-map (kbd "C-c %") #'org-mark-ring-push) (org-defkey org-mode-map (kbd "C-c &") #'org-mark-ring-goto) (org-defkey org-mode-map (kbd "C-c C-z") #'org-add-note) ;alternative binding -(org-defkey org-mode-map (kbd "C-c .") #'org-time-stamp) ;minor-mode reserved -(org-defkey org-mode-map (kbd "C-c !") #'org-time-stamp-inactive) ;minor-mode r. +(org-defkey org-mode-map (kbd "C-c .") #'org-timestamp) ;minor-mode reserved +(org-defkey org-mode-map (kbd "C-c !") #'org-timestamp-inactive) ;minor-mode r. (org-defkey org-mode-map (kbd "C-c ,") #'org-priority) ;minor-mode reserved (org-defkey org-mode-map (kbd "C-c C-y") #'org-evaluate-time-range) (org-defkey org-mode-map (kbd "C-c >") #'org-goto-calendar) @@ -638,7 +608,7 @@ COMMANDS is a list of alternating OLDDEF NEWDEF command names." (org-defkey org-mode-map (kbd "C-c C-x C-w") #'org-cut-special) (org-defkey org-mode-map (kbd "C-c C-x M-w") #'org-copy-special) (org-defkey org-mode-map (kbd "C-c C-x C-y") #'org-paste-special) -(org-defkey org-mode-map (kbd "C-c C-x C-t") #'org-toggle-time-stamp-overlays) +(org-defkey org-mode-map (kbd "C-c C-x C-t") #'org-toggle-timestamp-overlays) (org-defkey org-mode-map (kbd "C-c C-x C-i") #'org-clock-in) (org-defkey org-mode-map (kbd "C-c C-x C-x") #'org-clock-in-last) (org-defkey org-mode-map (kbd "C-c C-x C-z") #'org-resolve-clocks) @@ -788,19 +758,21 @@ command." (function) (sexp)))))) -(defun org-print-speed-command (e) - (if (> (length (car e)) 1) +(defun org--print-speed-command (speed-command) + "Print information about SPEED-COMMAND in help buffer. +SPEED-COMMAND is an element of `org-speed-commands'." + (if (> (length (car speed-command)) 1) (progn (princ "\n") - (princ (car e)) + (princ (car speed-command)) (princ "\n") - (princ (make-string (length (car e)) ?-)) + (princ (make-string (length (car speed-command)) ?-)) (princ "\n")) - (princ (car e)) + (princ (car speed-command)) (princ " ") - (if (symbolp (cdr e)) - (princ (symbol-name (cdr e))) - (prin1 (cdr e))) + (if (symbolp (cdr speed-command)) + (princ (symbol-name (cdr speed-command))) + (prin1 (cdr speed-command))) (princ "\n"))) (defun org-speed-command-help () @@ -810,12 +782,7 @@ command." (user-error "Speed commands are not activated, customize `org-use-speed-commands'")) (with-output-to-temp-buffer "*Help*" (princ "Speed commands\n==============\n") - (mapc #'org-print-speed-command - ;; FIXME: don't check `org-speed-commands-user' past 9.6 - (if (boundp 'org-speed-commands-user) - (append org-speed-commands - org-speed-commands-user) - org-speed-commands))) + (mapc #'org--print-speed-command org-speed-commands)) (with-current-buffer "*Help*" (setq truncate-lines t))) @@ -831,16 +798,12 @@ If not, return to the original position and throw an error." (defun org-speed-command-activate (keys) "Hook for activating single-letter speed commands. +KEYS is the keys vector as returned by `this-command-keys-vector'. See `org-speed-commands' for configuring them." (when (or (and (bolp) (looking-at org-outline-regexp)) (and (functionp org-use-speed-commands) (funcall org-use-speed-commands))) - (cdr (assoc keys - ;; FIXME: don't check `org-speed-commands-user' past 9.6 - (if (boundp 'org-speed-commands-user) - (append org-speed-commands - org-speed-commands-user) - org-speed-commands))))) + (cdr (assoc keys org-speed-commands)))) ;;; Babel speed keys @@ -910,10 +873,11 @@ a-list placed behind the generic `org-babel-key-prefix'.") (define-key org-babel-map key def)) (defun org-babel-speed-command-activate (keys) - "Hook for activating single-letter code block commands." + "Hook for activating single-letter code block commands. +KEYS is the keys vector as returned by `this-command-keys-vector'." (when (and (bolp) (let ((case-fold-search t)) (looking-at "[ \t]*#\\+begin_src")) - (eq 'src-block (org-element-type (org-element-at-point)))) + (org-element-type-p (org-element-at-point) 'src-block)) (cdr (assoc keys org-babel-key-bindings)))) ;;;###autoload diff --git a/elpa/org-9.6.7/org-lint.el b/elpa/org-9.7.17/org-lint.el similarity index 67% rename from elpa/org-9.6.7/org-lint.el rename to elpa/org-9.7.17/org-lint.el index 0e2967b6..0f961345 100644 --- a/elpa/org-9.6.7/org-lint.el +++ b/elpa/org-9.7.17/org-lint.el @@ -1,9 +1,9 @@ ;;; org-lint.el --- Linting for Org documents -*- lexical-binding: t; -*- -;; Copyright (C) 2015-2023 Free Software Foundation, Inc. +;; Copyright (C) 2015-2024 Free Software Foundation, Inc. ;; Author: Nicolas Goaziou -;; Keywords: outlines, hypermedia, calendar, wp +;; Keywords: outlines, hypermedia, calendar, text ;; This file is part of GNU Emacs. @@ -46,7 +46,7 @@ ;; - deprecated export block syntax, ;; - deprecated Babel header syntax, ;; - missing language in source blocks, -;; - missing back-end in export blocks, +;; - missing backend in export blocks, ;; - invalid Babel call blocks, ;; - NAME values with a colon, ;; - wrong babel headers, @@ -65,11 +65,13 @@ ;; - special properties in properties drawers, ;; - obsolete syntax for properties drawers, ;; - invalid duration in EFFORT property, +;; - invalid ID property with a double colon, ;; - missing definition for footnote references, ;; - missing reference for footnote definitions, ;; - non-footnote definitions in footnote section, ;; - probable invalid keywords, ;; - invalid blocks, +;; - mismatched repeaters in planning info line, ;; - misplaced planning info line, ;; - probable incomplete drawers, ;; - probable indented diary-sexps, @@ -194,7 +196,7 @@ for `tabulated-list-printer'." (with-current-buffer buffer (save-excursion (goto-char (point-min)) - (let ((ast (org-element-parse-buffer)) + (let ((ast (org-element-parse-buffer nil nil 'defer)) (id 0) (last-line 1) (last-pos 1)) @@ -208,10 +210,12 @@ for `tabulated-list-printer'." (cons (progn (goto-char (car report)) - (beginning-of-line) - (prog1 (number-to-string - (cl-incf last-line - (count-lines last-pos (point)))) + (forward-line 0) + (prog1 (propertize + (number-to-string + (cl-incf last-line + (count-lines last-pos (point)))) + 'org-lint-marker (car report)) (setf last-pos (point)))) (cdr report))))) ;; Insert trust level in generated reports. Also sort them @@ -221,7 +225,7 @@ for `tabulated-list-printer'." (let ((trust (symbol-name (org-lint-checker-trust c)))) (mapcar (lambda (report) - (list (car report) trust (nth 1 report) c)) + (list (copy-marker (car report)) trust (nth 1 report) c)) (save-excursion (funcall (org-lint-checker-function c) ast))))) @@ -244,6 +248,10 @@ for `tabulated-list-printer'." "Return current report line, as a number." (string-to-number (aref (tabulated-list-get-entry) 0))) +(defun org-lint--current-marker () + "Return current report marker." + (get-text-property 0 'org-lint-marker (aref (tabulated-list-get-entry) 0))) + (defun org-lint--current-checker (&optional entry) "Return current report checker. When optional argument ENTRY is non-nil, use this entry instead @@ -265,9 +273,10 @@ CHECKERS is the list of checkers used." (defun org-lint--jump-to-source () "Move to source line that generated the report at point." (interactive) - (let ((l (org-lint--current-line))) + (let ((mk (org-lint--current-marker))) (switch-to-buffer-other-window org-lint--source-buffer) - (org-goto-line l) + (unless (<= (point-min) mk (point-max)) (widen)) + (goto-char mk) (org-fold-show-set-visibility 'local) (recenter))) @@ -378,6 +387,28 @@ called with one argument, the key used for comparison." (t (push (cons key (funcall extract-position datum key)) keys)))))) (dolist (e originals reports) (funcall make-report (cdr e) (car e))))) +(defun org-lint-misplaced-heading (ast) + "Check for accidentally misplaced heading lines. +Example: +** Heading 1 +** Heading 2** Oops heading 3 +** Heading 4" + (org-with-point-at ast + (goto-char (point-min)) + (let (result) + ;; Heuristics for 2+ level heading not at bol. + (while (re-search-forward (rx (not (any "*\n\r ,")) ;; Not a bol; not escaped ,** heading; not " *** words" + "*" (1+ "*") " ") nil t) + ;; Limit false-positive rate by only complaining about + ;; ** Heading** Heading and + ;; ** Oops heading + ;; Paragraph** Oops heading + (when (org-element-type-p + (org-element-at-point) + '(paragraph headline)) + (push (list (match-beginning 0) "Possibly misplaced heading line") result))) + result))) + (defun org-lint-duplicate-custom-id (ast) (org-lint--collect-duplicates ast @@ -386,7 +417,7 @@ called with one argument, the key used for comparison." (and (org-string-equal-ignore-case "CUSTOM_ID" (org-element-property :key property)) (org-element-property :value property))) - (lambda (property _) (org-element-property :begin property)) + (lambda (property _) (org-element-begin property)) (lambda (key) (format "Duplicate CUSTOM_ID property \"%s\"" key)))) (defun org-lint-duplicate-name (ast) @@ -395,7 +426,7 @@ called with one argument, the key used for comparison." org-element-all-elements (lambda (datum) (org-element-property :name datum)) (lambda (datum name) - (goto-char (org-element-property :begin datum)) + (goto-char (org-element-begin datum)) (re-search-forward (format "^[ \t]*#\\+[A-Za-z]+:[ \t]*%s[ \t]*$" (regexp-quote name))) (match-beginning 0)) @@ -406,7 +437,7 @@ called with one argument, the key used for comparison." ast 'target (lambda (target) (split-string (org-element-property :value target))) - (lambda (target _) (org-element-property :begin target)) + (lambda (target _) (org-element-begin target)) (lambda (key) (format "Duplicate target <<%s>>" (mapconcat #'identity key " "))))) @@ -415,7 +446,7 @@ called with one argument, the key used for comparison." ast 'footnote-definition (lambda (definition) (org-element-property :label definition)) - (lambda (definition _) (org-element-property :post-affiliated definition)) + (lambda (definition _) (org-element-post-affiliated definition)) (lambda (key) (format "Duplicate footnote definition \"%s\"" key)))) (defun org-lint-orphaned-affiliated-keywords (ast) @@ -430,9 +461,22 @@ called with one argument, the key used for comparison." (and (or (let ((case-fold-search t)) (string-match-p "\\`ATTR_[-_A-Za-z0-9]+\\'" key)) (member key keywords)) - (list (org-element-property :post-affiliated k) + (list (org-element-post-affiliated k) (format "Orphaned affiliated keyword: \"%s\"" key)))))))) +(defun org-lint-regular-keyword-before-affiliated (ast) + (org-element-map ast 'keyword + (lambda (keyword) + (when (= (org-element-post-blank keyword) 0) + (let ((next-element (org-with-point-at (org-element-end keyword) + (org-element-at-point)))) + (when (< (org-element-begin next-element) (org-element-post-affiliated next-element)) + ;; A keyword followed without blank lines by an element with affiliated keywords. + ;; The keyword may be confused with affiliated keywords. + (list (org-element-begin keyword) + (format "Independent keyword %s may be confused with affiliated keywords below" + (org-element-property :key keyword))))))))) + (defun org-lint-obsolete-affiliated-keywords (_) (let ((regexp (format "^[ \t]*#\\+%s:" (regexp-opt '("DATA" "LABEL" "RESNAME" "SOURCE" @@ -442,7 +486,7 @@ called with one argument, the key used for comparison." (while (re-search-forward regexp nil t) (let ((key (upcase (match-string-no-properties 1)))) (when (< (point) - (org-element-property :post-affiliated (org-element-at-point))) + (org-element-post-affiliated (org-element-at-point))) (push (list (line-beginning-position) (format @@ -463,7 +507,7 @@ called with one argument, the key used for comparison." (let ((type (org-element-property :type b))) (when (member-ignore-case type deprecated) (list - (org-element-property :post-affiliated b) + (org-element-post-affiliated b) (format "Deprecated syntax for export block. Use \"BEGIN_EXPORT %s\" \ instead" @@ -485,14 +529,14 @@ instead" (let ((value (org-element-property :value datum))) (and (string= key "PROPERTY") (string-match deprecated-re value) - (list (org-element-property :begin datum) + (list (org-element-begin datum) (format "Deprecated syntax for \"%s\". \ Use header-args instead" (match-string-no-properties 1 value)))))) (`node-property (and (member-ignore-case key deprecated-babel-properties) (list - (org-element-property :begin datum) + (org-element-begin datum) (format "Deprecated syntax for \"%s\". \ Use :header-args: instead" key)))))))))) @@ -501,27 +545,38 @@ Use :header-args: instead" (org-element-map ast 'src-block (lambda (b) (unless (org-element-property :language b) - (list (org-element-property :post-affiliated b) + (list (org-element-post-affiliated b) "Missing language in source block"))))) +(defun org-lint-suspicious-language-in-src-block (ast) + (org-element-map ast 'src-block + (lambda (b) + (when-let* ((lang (org-element-property :language b))) + (unless (or (functionp (intern (format "org-babel-execute:%s" lang))) + ;; No babel backend, but there is corresponding + ;; major mode. + (fboundp (org-src-get-lang-mode lang))) + (list (org-element-property :post-affiliated b) + (format "Unknown source block language: '%s'" lang))))))) + (defun org-lint-missing-backend-in-export-block (ast) (org-element-map ast 'export-block (lambda (b) (unless (org-element-property :type b) - (list (org-element-property :post-affiliated b) - "Missing back-end in export block"))))) + (list (org-element-post-affiliated b) + "Missing backend in export block"))))) (defun org-lint-invalid-babel-call-block (ast) (org-element-map ast 'babel-call (lambda (b) (cond ((not (org-element-property :call b)) - (list (org-element-property :post-affiliated b) + (list (org-element-post-affiliated b) "Invalid syntax in babel call block")) ((let ((h (org-element-property :end-header b))) (and h (string-match-p "\\`\\[.*\\]\\'" h))) (list - (org-element-property :post-affiliated b) + (org-element-post-affiliated b) "Babel call's end header must not be wrapped within brackets")))))) (defun org-lint-deprecated-category-setup (ast) @@ -531,7 +586,7 @@ Use :header-args: instead" (cond ((not (string= (org-element-property :key k) "CATEGORY")) nil) (category-flag - (list (org-element-property :post-affiliated k) + (list (org-element-post-affiliated k) "Spurious CATEGORY keyword. Set :CATEGORY: property instead")) (t (setf category-flag t) nil)))))) @@ -542,7 +597,7 @@ Use :header-args: instead" (let ((ref (org-element-property :path link))) (and (equal (org-element-property :type link) "coderef") (not (ignore-errors (org-export-resolve-coderef ref info))) - (list (org-element-property :begin link) + (list (org-element-begin link) (format "Unknown coderef \"%s\"" ref)))))))) (defun org-lint-invalid-custom-id-link (ast) @@ -551,7 +606,7 @@ Use :header-args: instead" (lambda (link) (and (equal (org-element-property :type link) "custom-id") (not (ignore-errors (org-export-resolve-id-link link info))) - (list (org-element-property :begin link) + (list (org-element-begin link) (format "Unknown custom ID \"%s\"" (org-element-property :path link)))))))) @@ -561,7 +616,7 @@ Use :header-args: instead" (lambda (link) (and (equal (org-element-property :type link) "fuzzy") (not (ignore-errors (org-export-resolve-fuzzy-link link info))) - (list (org-element-property :begin link) + (list (org-element-begin link) (format "Unknown fuzzy location \"%s\"" (let ((path (org-element-property :path link))) (if (string-prefix-p "*" path) @@ -569,20 +624,54 @@ Use :header-args: instead" path))))))))) (defun org-lint-invalid-id-link (ast) + (let ((id-locations-updated nil)) + (org-element-map ast 'link + (lambda (link) + (let ((id (org-element-property :path link))) + (and (equal (org-element-property :type link) "id") + (progn + (unless id-locations-updated + (org-id-update-id-locations nil t) + (setq id-locations-updated t)) + t) + ;; The locations are up-to-date with file changes after + ;; the call to `org-id-update-id-locations'. We do not + ;; need to double-check if recorded ID is still present + ;; in the file. + (not (org-id-find-id-file id)) + (list (org-element-begin link) + (format "Unknown ID \"%s\"" id)))))))) + +(defun org-lint-confusing-brackets (ast) + (org-element-map ast 'link + (lambda (link) + (org-with-wide-buffer + (when (eq (char-after (org-element-end link)) ?\]) + (list (org-element-begin link) + (format "Trailing ']' after link end"))))))) + +(defun org-lint-brackets-inside-description (ast) (org-element-map ast 'link (lambda (link) - (let ((id (org-element-property :path link))) - (and (equal (org-element-property :type link) "id") - (not (org-id-find id)) - (list (org-element-property :begin link) - (format "Unknown ID \"%s\"" id))))))) + (when (org-element-contents-begin link) + (org-with-point-at link + (goto-char (org-element-contents-begin link)) + (let ((count 0)) + (while (re-search-forward (rx (or ?\] ?\[)) (org-element-contents-end link) t) + (if (equal (match-string 0) "[") (cl-incf count) (cl-decf count))) + (when (> count 0) + (list (org-element-begin link) + (format "No closing ']' matches '[' in link description: %s" + (buffer-substring-no-properties + (org-element-contents-begin link) + (org-element-contents-end link))))))))))) (defun org-lint-special-property-in-properties-drawer (ast) (org-element-map ast 'node-property (lambda (p) (let ((key (org-element-property :key p))) (and (member-ignore-case key org-special-properties) - (list (org-element-property :begin p) + (list (org-element-begin p) (format "Special property \"%s\" found in a properties drawer" key))))))) @@ -591,12 +680,12 @@ Use :header-args: instead" (org-element-map ast 'drawer (lambda (d) (when (equal (org-element-property :drawer-name d) "PROPERTIES") - (let ((headline? (org-element-lineage d '(headline))) + (let ((headline? (org-element-lineage d 'headline)) (before (mapcar #'org-element-type (assq d (reverse (org-element-contents - (org-element-property :parent d))))))) - (list (org-element-property :post-affiliated d) + (org-element-parent d))))))) + (list (org-element-post-affiliated d) (if (or (and headline? (member before '(nil (planning)))) (and (null headline?) (member before '(nil (comment))))) "Incorrect contents for PROPERTIES drawer" @@ -609,9 +698,19 @@ Use :header-args: instead" (let ((value (org-element-property :value p))) (and (org-string-nw-p value) (not (org-duration-p value)) - (list (org-element-property :begin p) + (list (org-element-begin p) (format "Invalid effort duration format: %S" value)))))))) +(defun org-lint-invalid-id-property (ast) + (org-element-map ast 'node-property + (lambda (p) + (when (equal "ID" (org-element-property :key p)) + (let ((value (org-element-property :value p))) + (and (org-string-nw-p value) + (string-match-p "::" value) + (list (org-element-begin p) + (format "IDs should not include \"::\": %S" value)))))))) + (defun org-lint-link-to-local-file (ast) (org-element-map ast 'link (lambda (l) @@ -621,12 +720,13 @@ Use :header-args: instead" (let* ((path (org-element-property :path l)) (file (if (string= type "file") path - (org-with-point-at (org-element-property :begin l) + (org-with-point-at (org-element-begin l) (org-attach-expand path))))) + (setq file (substitute-env-in-file-name file)) (and (not (file-remote-p file)) (not (file-exists-p file)) - (list (org-element-property :begin l) - (format (if (org-element-lineage l '(link)) + (list (org-element-begin l) + (format (if (org-element-lineage l 'link) "Link to non-existent image file %S \ in description" "Link to non-existent local file %S") @@ -643,7 +743,7 @@ in description" (and (not (org-url-p file)) (not (file-remote-p file)) (not (file-exists-p file)) - (list (org-element-property :begin k) + (list (org-element-begin k) (format "Non-existent setup file %S" file)))))))) (defun org-lint-wrong-include-link-parameter (ast) @@ -656,7 +756,7 @@ in description" (save-match-data (org-strip-quotes (match-string 1 value)))))) (if (not path) - (list (org-element-property :post-affiliated k) + (list (org-element-post-affiliated k) "Missing location argument in INCLUDE keyword") (let* ((file (org-string-nw-p (if (string-match "::\\(.*\\)\\'" path) @@ -668,7 +768,7 @@ in description" (if (and file (not (file-remote-p file)) (not (file-exists-p file))) - (list (org-element-property :post-affiliated k) + (list (org-element-post-affiliated k) "Non-existent file argument in INCLUDE keyword") (let* ((visiting (if file (find-buffer-visiting file) (current-buffer))) @@ -676,13 +776,14 @@ in description" (org-link-search-must-match-exact-headline t)) (unwind-protect (with-current-buffer buffer - (when (and search - (not (ignore-errors - (org-link-search search nil t)))) - (list (org-element-property :post-affiliated k) - (format - "Invalid search part \"%s\" in INCLUDE keyword" - search)))) + (org-with-wide-buffer + (when (and search + (not (ignore-errors + (org-link-search search nil t)))) + (list (org-element-post-affiliated k) + (format + "Invalid search part \"%s\" in INCLUDE keyword" + search))))) (unless visiting (kill-buffer buffer))))))))))))) (defun org-lint-obsolete-include-markup (ast) @@ -698,7 +799,7 @@ in description" (value (org-element-property :value k))) (when (string-match regexp value) (let ((markup (match-string-no-properties 1 value))) - (list (org-element-property :post-affiliated k) + (list (org-element-post-affiliated k) (format "Obsolete markup \"%s\" in INCLUDE keyword. \ Use \"export %s\" instead" markup @@ -725,15 +826,51 @@ Use \"export %s\" instead" (setf start (match-end 0)) (let ((item (match-string 1 value))) (unless (member item allowed) - (push (list (org-element-property :post-affiliated k) + (push (list (org-element-post-affiliated k) (format "Unknown OPTIONS item \"%s\"" item)) reports)) (unless (match-string 2 value) - (push (list (org-element-property :post-affiliated k) + (push (list (org-element-post-affiliated k) (format "Missing value for option item %S" item)) reports)))))))) reports)) +(defun org-lint-export-option-keywords (ast) + "Check for options keyword properties without EXPORT in AST." + (require 'ox) + (let (options reports common-options options-alist) + (dolist (opt org-export-options-alist) + (when (stringp (nth 1 opt)) + (cl-pushnew (nth 1 opt) common-options :test #'equal))) + (dolist (backend org-export-registered-backends) + (dolist (opt (org-export-backend-options backend)) + (when (stringp (nth 1 opt)) + (cl-pushnew (or (org-export-backend-name backend) 'anonymous) + (alist-get (nth 1 opt) options-alist nil nil #'equal)) + (cl-pushnew (nth 1 opt) options :test #'equal)))) + (setq options-alist (nreverse options-alist)) + (org-element-map ast 'node-property + (lambda (node) + (let ((prop (org-element-property :key node))) + (when (and (or (member prop options) (member prop common-options)) + (not (member prop org-default-properties))) + (push (list (org-element-post-affiliated node) + (format "Potentially misspelled %sexport option \"%s\"%s. Consider \"EXPORT_%s\"." + (when (member prop common-options) + "global ") + prop + (if-let* ((backends + (and (not (member prop common-options)) + (cdr (assoc-string prop options-alist))))) + (format + " in %S export %s" + (if (= 1 (length backends)) (car backends) backends) + (if (> (length backends) 1) "backends" "backend")) + "") + prop)) + reports))))) + reports)) + (defun org-lint-invalid-macro-argument-and-template (ast) (let* ((reports nil) (extract-placeholders @@ -747,7 +884,7 @@ Use \"export %s\" instead" (check-arity (lambda (arity macro) (let* ((name (org-element-property :key macro)) - (pos (org-element-property :begin macro)) + (pos (org-element-begin macro)) (args (org-element-property :args macro)) (l (length args))) (cond @@ -782,17 +919,17 @@ Use \"export %s\" instead" (org-trim (substring value (match-end 0)))))) (cond ((not name) - (push (list (org-element-property :post-affiliated k) + (push (list (org-element-post-affiliated k) "Missing name in MACRO keyword") reports)) ((not (org-string-nw-p template)) - (push (list (org-element-property :post-affiliated k) + (push (list (org-element-post-affiliated k) "Missing template in macro \"%s\"" name) reports)) (t (unless (let ((args (funcall extract-placeholders template))) (equal (number-sequence 1 (or (org-last args) 0)) args)) - (push (list (org-element-property :post-affiliated k) + (push (list (org-element-post-affiliated k) (format "Unused placeholders in macro \"%s\"" name)) reports)))))))) @@ -808,7 +945,7 @@ Use \"export %s\" instead" (template (cdr (assoc-string name templates t)))) (pcase template (`nil - (push (list (org-element-property :begin macro) + (push (list (org-element-begin macro) (format "Undefined macro %S" name)) reports)) ((guard (string= name "keyword")) @@ -833,17 +970,17 @@ Use \"export %s\" instead" (defun org-lint-undefined-footnote-reference (ast) (let ((definitions - (org-element-map ast '(footnote-definition footnote-reference) - (lambda (f) - (and (or (eq 'footnote-definition (org-element-type f)) - (eq 'inline (org-element-property :type f))) - (org-element-property :label f)))))) + (org-element-map ast '(footnote-definition footnote-reference) + (lambda (f) + (and (or (org-element-type-p f 'footnote-definition) + (eq 'inline (org-element-property :type f))) + (org-element-property :label f)))))) (org-element-map ast 'footnote-reference (lambda (f) (let ((label (org-element-property :label f))) (and (eq 'standard (org-element-property :type f)) (not (member label definitions)) - (list (org-element-property :begin f) + (list (org-element-begin f) (format "Missing definition for footnote [%s]" label)))))))) @@ -855,32 +992,46 @@ Use \"export %s\" instead" (let ((label (org-element-property :label f))) (and label (not (member label references)) - (list (org-element-property :post-affiliated f) + (list (org-element-post-affiliated f) (format "No reference for footnote definition [%s]" label)))))))) -(defun org-lint-colon-in-name (ast) - (org-element-map ast org-element-all-elements +(defun org-lint-mismatched-planning-repeaters (ast) + (org-element-map ast 'planning (lambda (e) - (let ((name (org-element-property :name e))) - (and name - (string-match-p ":" name) - (list (progn - (goto-char (org-element-property :begin e)) - (re-search-forward - (format "^[ \t]*#\\+\\w+: +%s *$" (regexp-quote name))) - (match-beginning 0)) - (format - "Name \"%s\" contains a colon; Babel cannot use it as input" - name))))))) + (let* ((scheduled (org-element-property :scheduled e)) + (deadline (org-element-property :deadline e)) + (scheduled-repeater-type (org-element-property + :repeater-type scheduled)) + (deadline-repeater-type (org-element-property + :repeater-type deadline)) + (scheduled-repeater-value (org-element-property + :repeater-value scheduled)) + (deadline-repeater-value (org-element-property + :repeater-value deadline))) + (when (and scheduled deadline + (memq scheduled-repeater-type '(cumulate catch-up)) + (memq deadline-repeater-type '(cumulate catch-up)) + (> scheduled-repeater-value 0) + (> deadline-repeater-value 0) + (not + (and + (eq scheduled-repeater-type deadline-repeater-type) + (eq (org-element-property :repeater-unit scheduled) + (org-element-property :repeater-unit deadline)) + (eql scheduled-repeater-value deadline-repeater-value)))) + (list + (org-element-property :begin e) + "Different repeaters in SCHEDULED and DEADLINE timestamps.")))))) (defun org-lint-misplaced-planning-info (_) (let ((case-fold-search t) reports) (while (re-search-forward org-planning-line-re nil t) - (unless (memq (org-element-type (org-element-at-point)) - '(comment-block example-block export-block planning - src-block verse-block)) + (unless (org-element-type-p + (org-element-at-point) + '(comment-block example-block export-block planning + src-block verse-block)) (push (list (line-beginning-position) "Misplaced planning info line") reports))) reports)) @@ -893,16 +1044,16 @@ Use \"export %s\" instead" (pcase (org-element-type element) (`drawer ;; Find drawer opening lines within non-empty drawers. - (let ((end (org-element-property :contents-end element))) + (let ((end (org-element-contents-end element))) (when end (while (re-search-forward org-drawer-regexp end t) (let ((n (org-trim (match-string-no-properties 0)))) (push (list (line-beginning-position) (format "Possible misleading drawer entry %S" n)) reports)))) - (goto-char (org-element-property :end element)))) + (goto-char (org-element-end element)))) (`property-drawer - (goto-char (org-element-property :end element))) + (goto-char (org-element-end element))) ((or `comment-block `example-block `export-block `src-block `verse-block) nil) @@ -916,9 +1067,10 @@ Use \"export %s\" instead" (defun org-lint-indented-diary-sexp (_) (let (reports) (while (re-search-forward "^[ \t]+%%(" nil t) - (unless (memq (org-element-type (org-element-at-point)) - '(comment-block diary-sexp example-block export-block - src-block verse-block)) + (unless (org-element-type-p + (org-element-at-point) + '(comment-block diary-sexp example-block export-block + src-block verse-block)) (push (list (line-beginning-position) "Possible indented diary-sexp") reports))) reports)) @@ -936,10 +1088,11 @@ Use \"export %s\" instead" (push (list (line-beginning-position) (format "Invalid block closing line \"%s\"" name)) reports)) - ((not (memq (org-element-type (org-element-at-point)) - '(center-block comment-block dynamic-block example-block - export-block quote-block special-block - src-block verse-block))) + ((not (org-element-type-p + (org-element-at-point) + '(center-block comment-block dynamic-block example-block + export-block quote-block special-block + src-block verse-block))) (push (list (line-beginning-position) (format "Possible incomplete block \"%s\"" name)) @@ -957,13 +1110,43 @@ Use \"export %s\" instead" (unless (or (string-prefix-p "BEGIN" name t) (string-prefix-p "END" name t) (save-excursion - (beginning-of-line) + (forward-line 0) (let ((case-fold-search t)) (looking-at exception-re)))) (push (list (match-beginning 0) (format "Possible missing colon in keyword \"%s\"" name)) reports)))) reports)) +(defun org-lint-invalid-image-alignment (ast) + (apply + #'nconc + (org-element-map ast 'paragraph + (lambda (p) + (let ((center-re ":center[[:space:]]+\\(\\S-+\\)") + (align-re ":align[[:space:]]+\\(\\S-+\\)") + (keyword-string + (car-safe (org-element-property :attr_org p))) + reports) + (when keyword-string + (when (and (string-match align-re keyword-string) + (not (member (match-string 1 keyword-string) + '("left" "center" "right")))) + (push + (list (org-element-begin p) + (format + "\"%s\" not a supported value for #+ATTR_ORG keyword attribute \":align\"." + (match-string 1 keyword-string))) + reports)) + (when (and (string-match center-re keyword-string) + (not (equal (match-string 1 keyword-string) "t"))) + (push + (list (org-element-begin p) + (format + "\"%s\" not a supported value for #+ATTR_ORG keyword attribute \":center\"." + (match-string 1 keyword-string))) + reports))) + reports))))) + (defun org-lint-extraneous-element-in-footnote-section (ast) (org-element-map ast 'headline (lambda (h) @@ -975,10 +1158,10 @@ Use \"export %s\" instead" property-drawer section))) org-element-all-elements) (lambda (e) - (not (and (eq (org-element-type e) 'headline) - (org-element-property :commentedp e)))) + (not (and (org-element-type-p e 'headline) + (org-element-property :commentedp e)))) nil t '(footnote-definition property-drawer)) - (list (org-element-property :begin h) + (list (org-element-begin h) "Extraneous elements in footnote section are not exported"))))) (defun org-lint-quote-section (ast) @@ -987,7 +1170,7 @@ Use \"export %s\" instead" (let ((title (org-element-property :raw-value h))) (and (or (string-prefix-p "QUOTE " title) (string-prefix-p (concat org-comment-string " QUOTE ") title)) - (list (org-element-property :begin h) + (list (org-element-begin h) "Deprecated QUOTE section")))))) (defun org-lint-file-application (ast) @@ -995,7 +1178,7 @@ Use \"export %s\" instead" (lambda (l) (let ((app (org-element-property :application l))) (and app - (list (org-element-property :begin l) + (list (org-element-begin l) (format "Deprecated \"file+%s\" link type" app))))))) (defun org-lint-percent-encoding-link-escape (ast) @@ -1012,7 +1195,7 @@ Use \"export %s\" instead" (throw :obsolete nil))) (string-match-p "%" uri)))) (when obsolete-flag - (list (org-element-property :begin l) + (list (org-element-begin l) "Link escaped with obsolete percent-encoding syntax"))))))) (defun org-lint-wrong-header-argument (ast) @@ -1034,8 +1217,8 @@ Use \"export %s\" instead" (mapcar #'car org-babel-load-languages)))))) (dolist (header headers) (let ((h (symbol-name (car header))) - (p (or (org-element-property :post-affiliated datum) - (org-element-property :begin datum)))) + (p (or (org-element-post-affiliated datum) + (org-element-begin datum)))) (cond ((not (string-prefix-p ":" h)) (push @@ -1096,6 +1279,37 @@ Use \"export %s\" instead" (org-element-property :header datum)))))))) reports)) +(defun org-lint-empty-header-argument (ast) + (let* (reports) + (org-element-map ast '(babel-call inline-babel-call inline-src-block src-block) + (lambda (datum) + (let ((headers + (pcase (org-element-type datum) + ((or `babel-call `inline-babel-call) + (cl-mapcan + (lambda (header) (org-babel-parse-header-arguments header 'no-eval)) + (list + (org-element-property :inside-header datum) + (org-element-property :end-header datum)))) + (`inline-src-block + (org-babel-parse-header-arguments + (org-element-property :parameters datum) + 'no-eval)) + (`src-block + (cl-mapcan + (lambda (header) (org-babel-parse-header-arguments header 'no-eval)) + (cons (org-element-property :parameters datum) + (org-element-property :header datum))))))) + (dolist (header headers) + (when (not (cdr header)) + (push + (list + (or (org-element-post-affiliated datum) + (org-element-begin datum)) + (format "Empty value in header argument \"%s\"" (symbol-name (car header)))) + reports)))))) + reports)) + (defun org-lint-wrong-header-value (ast) (let (reports) (org-element-map ast @@ -1148,8 +1362,8 @@ Use \"export %s\" instead" ((assq group groups-alist) (push (list - (or (org-element-property :post-affiliated datum) - (org-element-property :begin datum)) + (or (org-element-post-affiliated datum) + (org-element-begin datum)) (format "Forbidden combination in header \"%s\": %s, %s" (car header) @@ -1162,19 +1376,34 @@ Use \"export %s\" instead" (unless valid-value (push (list - (or (org-element-property :post-affiliated datum) - (org-element-property :begin datum)) + (or (org-element-post-affiliated datum) + (org-element-begin datum)) (format "Unknown value \"%s\" for header \"%s\"" v (car header))) reports)))))))))))) reports)) +(defun org-lint-named-result (ast) + (org-element-map ast org-element-all-elements + (lambda (el) + (when-let* ((result (org-element-property :results el)) + (result-name (org-element-property :name el)) + (origin-block + (if (org-string-nw-p (car result)) + (condition-case _ + (org-export-resolve-link (car result) `(:parse-tree ,ast)) + (org-link-broken nil)) + (org-export-get-previous-element el nil)))) + (when (org-element-type-p origin-block 'src-block) + (list (org-element-begin el) + (format "Links to \"%s\" will not be valid during export unless the parent source block has :exports results or both" result-name))))))) + (defun org-lint-spurious-colons (ast) (org-element-map ast '(headline inlinetask) (lambda (h) (when (member "" (org-element-property :tags h)) - (list (org-element-property :begin h) + (list (org-element-begin h) "Tags contain a spurious colon"))))) (defun org-lint-non-existent-bibliography (ast) @@ -1184,7 +1413,7 @@ Use \"export %s\" instead" (let ((file (org-strip-quotes (org-element-property :value k)))) (and (not (file-remote-p file)) (not (file-exists-p file)) - (list (org-element-property :begin k) + (list (org-element-begin k) (format "Non-existent bibliography %S" file)))))))) (defun org-lint-missing-print-bibliography (ast) @@ -1201,7 +1430,7 @@ Use \"export %s\" instead" (lambda (k) (when (equal "CITE_EXPORT" (org-element-property :key k)) (let ((value (org-element-property :value k)) - (source (org-element-property :begin k))) + (source (org-element-begin k))) (if (equal value "") (list source "Missing export processor name") (condition-case _ @@ -1209,8 +1438,11 @@ Use \"export %s\" instead" (`(,(and (pred symbolp) name) ,(pred string-or-null-p) ,(pred string-or-null-p)) - (unless (org-cite-get-processor name) - (list source "Unknown cite export processor %S" name))) + (unless (or (org-cite-get-processor name) + (progn + (org-cite-try-load-processor name) + (org-cite-get-processor name))) + (list source (format "Unknown cite export processor %S" name)))) (_ (list source "Invalid cite export processor declaration"))) (error @@ -1223,13 +1455,103 @@ Use \"export %s\" instead" ;; XXX: The code below signals the error at the beginning ;; of the paragraph containing the faulty object. It is ;; not very accurate but may be enough for now. - (list (org-element-property :contents-begin - (org-element-property :parent text)) + (list (org-element-contents-begin + (org-element-parent text)) "Possibly incomplete citation markup"))))) +(defun org-lint-item-number (ast) + (org-element-map ast 'item + (lambda (item) + (unless (org-element-property :counter item) + (when-let* ((bullet (org-element-property :bullet item)) + (bullet-number + (cond + ((string-match "[A-Za-z]" bullet) + (- (string-to-char (upcase (match-string 0 bullet))) + 64)) + ((string-match "[0-9]+" bullet) + (string-to-number (match-string 0 bullet))))) + (true-number + (org-list-get-item-number + (org-element-begin item) + (org-element-property :structure item) + (org-list-prevs-alist (org-element-property :structure item)) + (org-list-parents-alist (org-element-property :structure item))))) + (unless (equal bullet-number (car (last true-number))) + (list + (org-element-begin item) + (format "Bullet counter \"%s\" is not the same with item position %d. Consider adding manual [@%d] counter." + bullet (car (last true-number)) bullet-number)))))))) + +(defun org-lint-LaTeX-$ (ast) + "Report semi-obsolete $...$ LaTeX fragments. +AST is the buffer parse tree." + (org-element-map ast 'latex-fragment + (lambda (fragment) + (and (string-match-p "^[$][^$]" (org-element-property :value fragment)) + (list (org-element-begin fragment) + "Potentially confusing LaTeX fragment format. Prefer using more reliable \\(...\\)"))))) +(defun org-lint-LaTeX-$-ambiguous (_) + "Report LaTeX fragment-like text. +AST is the buffer parse tree." + (org-with-wide-buffer + (let ((ambiguous-latex-re (rx "$." digit)) + report context) + (while (re-search-forward ambiguous-latex-re nil t) + (setq context (org-element-context)) + (when (or (eq 'latex-fragment (org-element-type context)) + (memq 'latex-fragment (org-element-restriction context))) + (push + (list + (point) + "$ symbol potentially matching LaTeX fragment boundary. Consider using \\dollar entity.") + report))) + report))) +(defun org-lint-timestamp-syntax (ast) + "Report malformed timestamps. +AST is the buffer parse tree." + (org-element-map ast 'timestamp + (lambda (timestamp) + (let ((expected (org-element-interpret-data timestamp)) + (actual (buffer-substring-no-properties + (org-element-property :begin timestamp) + (org-element-property :end timestamp)))) + (unless (equal expected actual) + (list (org-element-property :begin timestamp) + (format "Potentially malformed timestamp %s. Parsed as: %s" actual expected))))))) +(defun org-lint-inactive-planning (ast) + "Report inactive timestamp in SCHEDULED/DEADLINE. +AST is the buffer parse tree." + (org-element-map ast 'planning + (lambda (planning) + (let ((scheduled (org-element-property :scheduled planning)) + (deadline (org-element-property :deadline planning))) + (cond + ((memq (org-element-property :type scheduled) '(inactive inactive-range)) + (list (org-element-begin planning) "Inactive timestamp in SCHEDULED will not appear in agenda.")) + ((memq (org-element-property :type deadline) '(inactive inactive-range)) + (list (org-element-begin planning) "Inactive timestamp in DEADLINE will not appear in agenda.")) + (t nil)))))) + +(defvar org-beamer-frame-environment) ; defined in ox-beamer.el +(defun org-lint-beamer-frame (ast) + "Check for occurrences of begin or end frame." + (require 'ox-beamer) + (org-with-point-at ast + (goto-char (point-min)) + (let (result) + (while (re-search-forward + (concat "\\\\\\(begin\\|end\\){" org-beamer-frame-environment "}") nil t) + (push (list (match-beginning 0) "Beamer frame name may cause error when exporting. Consider customizing `org-beamer-frame-environment'.") result)) + result))) + ;;; Checkers declaration +(org-lint-add-checker 'misplaced-heading + "Report accidentally misplaced heading lines." + #'org-lint-misplaced-heading :trust 'low) + (org-lint-add-checker 'duplicate-custom-id "Report duplicates CUSTOM_ID properties" #'org-lint-duplicate-custom-id @@ -1255,6 +1577,11 @@ Use \"export %s\" instead" #'org-lint-orphaned-affiliated-keywords :trust 'low) +(org-lint-add-checker 'combining-keywords-with-affiliated + "Report independent keywords preceding affiliated keywords." + #'org-lint-regular-keyword-before-affiliated + :trust 'low) + (org-lint-add-checker 'obsolete-affiliated-keywords "Report obsolete affiliated keywords" #'org-lint-obsolete-affiliated-keywords @@ -1275,8 +1602,13 @@ Use \"export %s\" instead" #'org-lint-missing-language-in-src-block :categories '(babel)) +(org-lint-add-checker 'suspicious-language-in-src-block + "Report suspicious language in source blocks" + #'org-lint-suspicious-language-in-src-block + :trust 'low :categories '(babel)) + (org-lint-add-checker 'missing-backend-in-export-block - "Report missing back-end in export blocks" + "Report missing backend in export blocks" #'org-lint-missing-backend-in-export-block :categories '(export)) @@ -1285,11 +1617,6 @@ Use \"export %s\" instead" #'org-lint-invalid-babel-call-block :categories '(babel)) -(org-lint-add-checker 'colon-in-name - "Report NAME values with a colon" - #'org-lint-colon-in-name - :categories '(babel)) - (org-lint-add-checker 'wrong-header-argument "Report wrong babel headers" #'org-lint-wrong-header-argument @@ -1300,6 +1627,16 @@ Use \"export %s\" instead" #'org-lint-wrong-header-value :categories '(babel) :trust 'low) +(org-lint-add-checker 'named-result + "Report results evaluation with #+name keyword." + #'org-lint-named-result + :categories '(babel) :trust 'high) + +(org-lint-add-checker 'empty-header-argument + "Report empty values in babel headers" + #'org-lint-empty-header-argument + :categories '(babel) :trust 'low) + (org-lint-add-checker 'deprecated-category-setup "Report misuse of CATEGORY keyword" #'org-lint-deprecated-category-setup @@ -1325,6 +1662,16 @@ Use \"export %s\" instead" #'org-lint-invalid-id-link :categories '(link)) +(org-lint-add-checker 'trailing-bracket-after-link + "Report potentially confused trailing ']' after link." + #'org-lint-confusing-brackets + :categories '(link) :trust 'low) + +(org-lint-add-checker 'unclosed-brackets-in-link-description + "Report potentially confused trailing ']' after link." + #'org-lint-brackets-inside-description + :categories '(link) :trust 'low) + (org-lint-add-checker 'link-to-local-file "Report links to non-existent local files" #'org-lint-link-to-local-file @@ -1350,6 +1697,11 @@ Use \"export %s\" instead" #'org-lint-unknown-options-item :categories '(export) :trust 'low) +(org-lint-add-checker 'misspelled-export-option + "Report potentially misspelled export options in properties." + #'org-lint-export-option-keywords + :categories '(export) :trust 'low) + (org-lint-add-checker 'invalid-macro-argument-and-template "Report spurious macro arguments or invalid macro templates" #'org-lint-invalid-macro-argument-and-template @@ -1370,6 +1722,11 @@ Use \"export %s\" instead" #'org-lint-invalid-effort-property :categories '(properties)) +(org-lint-add-checker 'invalid-id-property + "Report search string delimiter \"::\" in ID property" + #'org-lint-invalid-id-property + :categories '(properties)) + (org-lint-add-checker 'undefined-footnote-reference "Report missing definition for footnote references" #'org-lint-undefined-footnote-reference @@ -1390,11 +1747,21 @@ Use \"export %s\" instead" #'org-lint-invalid-keyword-syntax :trust 'low) +(org-lint-add-checker 'invalid-image-alignment + "Report unsupported align attribute for keyword" + #'org-lint-invalid-image-alignment + :trust 'high) + (org-lint-add-checker 'invalid-block "Report invalid blocks" #'org-lint-invalid-block :trust 'low) +(org-lint-add-checker 'mismatched-planning-repeaters + "Report mismatched repeaters in planning info line" + #'org-lint-mismatched-planning-repeaters + :trust 'low) + (org-lint-add-checker 'misplaced-planning-info "Report misplaced planning info line" #'org-lint-misplaced-planning-info @@ -1450,6 +1817,32 @@ Use \"export %s\" instead" #'org-lint-incomplete-citation :categories '(cite) :trust 'low) +(org-lint-add-checker 'item-number + "Report inconsistent item numbers in lists" + #'org-lint-item-number + :categories '(plain-list)) + +(org-lint-add-checker 'LaTeX-$ + "Report potentially confusing $...$ LaTeX markup." + #'org-lint-LaTeX-$ + :categories '(markup)) +(org-lint-add-checker 'LaTeX-$ + "Report $ that might be treated as LaTeX fragment boundary." + #'org-lint-LaTeX-$-ambiguous + :categories '(markup) :trust 'low) +(org-lint-add-checker 'beamer-frame + "Report that frame text contains beamer frame environment." + #'org-lint-beamer-frame + :categories '(export) :trust 'low) +(org-lint-add-checker 'timestamp-syntax + "Report malformed timestamps." + #'org-lint-timestamp-syntax + :categories '(timestamp) :trust 'low) +(org-lint-add-checker 'planning-inactive + "Report inactive timestamps in SCHEDULED/DEADLINE." + #'org-lint-inactive-planning + :categories '(timestamp) :trust 'high) + (provide 'org-lint) ;; Local variables: diff --git a/elpa/org-9.6.7/org-list.el b/elpa/org-9.7.17/org-list.el similarity index 93% rename from elpa/org-9.6.7/org-list.el rename to elpa/org-9.7.17/org-list.el index 1fc99d07..45a07a71 100644 --- a/elpa/org-9.6.7/org-list.el +++ b/elpa/org-9.7.17/org-list.el @@ -1,10 +1,10 @@ ;;; org-list.el --- Plain lists for Org -*- lexical-binding: t; -*- ;; -;; Copyright (C) 2004-2023 Free Software Foundation, Inc. +;; Copyright (C) 2004-2024 Free Software Foundation, Inc. ;; ;; Author: Carsten Dominik ;; Bastien Guerry -;; Keywords: outlines, hypermedia, calendar, wp +;; Keywords: outlines, hypermedia, calendar, text ;; URL: https://orgmode.org ;; ;; This file is part of GNU Emacs. @@ -111,15 +111,22 @@ (declare-function org-element-at-point "org-element" (&optional pom cached-only)) (declare-function org-element-context "org-element" (&optional element)) (declare-function org-element-interpret-data "org-element" (data)) -(declare-function org-element-lineage "org-element" (blob &optional types with-self)) +(declare-function org-element-lineage "org-element-ast" (blob &optional types with-self)) (declare-function org-element-macro-interpreter "org-element" (macro ##)) (declare-function org-element-map "org-element" (data types fun &optional info first-match no-recursion with-affiliated)) (declare-function org-element-normalize-string "org-element" (s)) -(declare-function org-element-parse-buffer "org-element" (&optional granularity visible-only)) -(declare-function org-element-property "org-element" (property element)) -(declare-function org-element-put-property "org-element" (element property value)) -(declare-function org-element-set-element "org-element" (old new)) -(declare-function org-element-type "org-element" (element)) +(declare-function org-element-parse-buffer "org-element" (&optional granularity visible-only keep-deferred)) +(declare-function org-element-property "org-element-ast" (property node)) +(declare-function org-element-begin "org-element" (node)) +(declare-function org-element-end "org-element" (node)) +(declare-function org-element-contents-begin "org-element" (node)) +(declare-function org-element-contents-end "org-element" (node)) +(declare-function org-element-post-affiliated "org-element" (node)) +(declare-function org-element-post-blank "org-element" (node)) +(declare-function org-element-parent "org-element-ast" (node)) +(declare-function org-element-put-property "org-element-ast" (node property value)) +(declare-function org-element-set "org-element-ast" (old new)) +(declare-function org-element-type-p "org-element-ast" (node types)) (declare-function org-element-update-syntax "org-element" ()) (declare-function org-end-of-meta-data "org" (&optional full)) (declare-function org-entry-get "org" (pom property &optional inherit literal-nil)) @@ -364,16 +371,32 @@ group 2: counter group 3: checkbox group 4: description tag") -(defun org-item-re () +(defvar org--item-re-cache nil + "Results cache for `org-item-re'.") +(defsubst org-item-re () "Return the correct regular expression for plain lists." - (let ((term (cond - ((eq org-plain-list-ordered-item-terminator t) "[.)]") - ((= org-plain-list-ordered-item-terminator ?\)) ")") - ((= org-plain-list-ordered-item-terminator ?.) "\\.") - (t "[.)]"))) - (alpha (if org-list-allow-alphabetical "\\|[A-Za-z]" ""))) - (concat "\\([ \t]*\\([-+]\\|\\(\\([0-9]+" alpha "\\)" term - "\\)\\)\\|[ \t]+\\*\\)\\([ \t]+\\|$\\)"))) + (or (plist-get + (plist-get org--item-re-cache + org-list-allow-alphabetical) + org-plain-list-ordered-item-terminator) + (let* ((term (cond + ((eq org-plain-list-ordered-item-terminator t) "[.)]") + ((= org-plain-list-ordered-item-terminator ?\)) ")") + ((= org-plain-list-ordered-item-terminator ?.) "\\.") + (t "[.)]"))) + (alpha (if org-list-allow-alphabetical "\\|[A-Za-z]" "")) + (re (concat "\\([ \t]*\\([-+]\\|\\(\\([0-9]+" alpha "\\)" term + "\\)\\)\\|[ \t]+\\*\\)\\([ \t]+\\|$\\)"))) + (setq org--item-re-cache + (plist-put + org--item-re-cache + org-list-allow-alphabetical + (plist-put + (plist-get org--item-re-cache + org-list-allow-alphabetical) + org-plain-list-ordered-item-terminator + re))) + re))) (defsubst org-item-beginning-re () "Regexp matching the beginning of a plain list item." @@ -400,7 +423,7 @@ group 4: description tag") (defun org-in-item-p () "Return item beginning position when in a plain list, nil otherwise." (save-excursion - (beginning-of-line) + (forward-line 0) (let* ((case-fold-search t) (context (org-list-context)) (lim-up (car context)) @@ -448,7 +471,7 @@ group 4: description tag") (re-search-backward "^[ \t]*#\\+begin_" lim-up t))) ((and (looking-at "^[ \t]*:END:") (re-search-backward org-drawer-regexp lim-up t)) - (beginning-of-line)) + (forward-line 0)) ((and inlinetask-re (looking-at inlinetask-re)) (org-inlinetask-goto-beginning) (forward-line -1)) @@ -462,11 +485,18 @@ group 4: description tag") (forward-line -1)) (t (forward-line -1))))))))))) +;; FIXME: We should make use of org-element API in more places here. (defun org-at-item-p () - "Is point in a line starting a hand-formatted item?" + "Is point in a line starting a hand-formatted item? +Modify match data, matching against `org-item-re'." (save-excursion - (beginning-of-line) - (and (looking-at (org-item-re)) (org-list-in-valid-context-p)))) + (forward-line 0) + (and + (org-element-type-p + (org-element-at-point) + '(plain-list item)) + ;; Set match data. + (looking-at (org-item-re))))) (defun org-at-item-bullet-p () "Is point at the bullet of a plain list item?" @@ -508,7 +538,7 @@ Contexts `block' and `invalid' refer to `org-list-forbidden-blocks'." (save-match-data (save-excursion (org-with-limited-levels - (beginning-of-line) + (forward-line 0) (let ((case-fold-search t) (pos (point)) beg end context-type ;; Get positions of surrounding headings. This is the ;; default context. @@ -595,7 +625,7 @@ will get the following structure: Assume point is at an item." (save-excursion - (beginning-of-line) + (forward-line 0) (let* ((case-fold-search t) (context (org-list-context)) (lim-up (car context)) @@ -663,7 +693,7 @@ Assume point is at an item." (re-search-backward "^[ \t]*#\\+begin_" lim-up t))) ((and (looking-at "^[ \t]*:END:") (re-search-backward org-drawer-regexp lim-up t)) - (beginning-of-line)) + (forward-line 0)) ((and inlinetask-re (looking-at inlinetask-re)) (org-inlinetask-goto-beginning) (forward-line -1)) @@ -1122,7 +1152,7 @@ This function modifies STRUCT." (org-fold-core-regions (cdr folds) :relative beg-A) (org-fold-core-regions (car folds) - :relative (+ beg-B (- size-B size-A (length between-A-no-blank-and-B)))) + :relative (+ beg-A size-B (length between-A-no-blank-and-B))) ;; 2. Now modify struct. No need to re-read the list, the ;; transformation is just a shift of positions. Some special ;; attention is required for items ending at END-A and END-B @@ -1831,7 +1861,7 @@ Initial position of cursor is restored after the changes." (lambda (end beg delta) (goto-char end) (skip-chars-backward " \r\t\n") - (beginning-of-line) + (forward-line 0) (while (or (> (point) beg) (and (= (point) beg) (not (looking-at item-re)))) @@ -2218,7 +2248,7 @@ item is invisible." (setq struct (org-list-insert-item pos struct prevs checkbox desc)) (org-list-write-struct struct (org-list-parents-alist struct)) (when checkbox (org-update-checkbox-count-maybe)) - (beginning-of-line) + (forward-line 0) (looking-at org-list-full-item-re) (goto-char (if (and (match-beginning 4) (save-match-data @@ -2248,7 +2278,7 @@ is an integer, 0 means `-', 1 means `+' etc. If WHICH is (interactive "P") (unless (org-at-item-p) (error "Not at an item")) (let ((origin (point-marker))) - (beginning-of-line) + (forward-line 0) (let* ((struct (org-list-struct)) (parents (org-list-parents-alist struct)) (prevs (org-list-prevs-alist struct)) @@ -2310,14 +2340,14 @@ is an integer, 0 means `-', 1 means `+' etc. If WHICH is (setq struct (org-list-struct)) (cond ((>= origin-offset2 0) - (beginning-of-line) + (forward-line 0) (move-marker origin (+ (point) (org-list-get-ind (point) struct) (length (org-list-get-bullet (point) struct)) origin-offset2)) (goto-char origin)) ((>= origin-offset 0) - (beginning-of-line) + (forward-line 0) (move-marker origin (+ (point) (org-list-get-ind (point) struct) origin-offset)) @@ -2362,15 +2392,15 @@ is an integer, 0 means `-', 1 means `+' etc. If WHICH is (defun org-at-radio-list-p () "Is point at a list item with radio buttons?" (when (org-match-line (org-item-re)) ;short-circuit - (let* ((e (save-excursion (beginning-of-line) (org-element-at-point)))) + (let* ((e (save-excursion (forward-line 0) (org-element-at-point)))) ;; Check we're really on a line with a bullet. - (when (memq (org-element-type e) '(item plain-list)) + (when (org-element-type-p e '(item plain-list)) ;; Look for ATTR_ORG attribute in the current plain list. - (let ((plain-list (org-element-lineage e '(plain-list) t))) - (org-with-point-at (org-element-property :post-affiliated plain-list) + (let ((plain-list (org-element-lineage e 'plain-list t))) + (org-with-point-at (org-element-post-affiliated plain-list) (let ((case-fold-search t) (regexp "^[ \t]*#\\+attr_org:.* :radio \\(\\S-+\\)") - (begin (org-element-property :begin plain-list))) + (begin (org-element-begin plain-list))) (and (re-search-backward regexp begin t) (not (string-equal "nil" (match-string 1))))))))))) @@ -2408,7 +2438,7 @@ subtree, ignoring planning line and any drawer following it." (setq lim-down (copy-marker limit)))) ((org-at-heading-p) ;; On a heading, start at first item after drawers and - ;; time-stamps (scheduled, etc.). + ;; timestamps (scheduled, etc.). (let ((limit (save-excursion (outline-next-heading) (point)))) (org-end-of-meta-data t) (if (org-list-search-forward (org-item-beginning-re) limit t) @@ -2492,8 +2522,8 @@ subtree, ignoring planning line and any drawer following it." (while (< (point) end) (when (org-at-item-checkbox-p) (replace-match "[ ]" t t nil 1)) - (beginning-of-line 2))) - (org-update-checkbox-count-maybe 'all))))) + (forward-line 1))) + (org-update-checkbox-count-maybe 'narrow))))) (defun org-update-checkbox-count (&optional all) "Update the checkbox statistics in the current section. @@ -2501,126 +2531,131 @@ subtree, ignoring planning line and any drawer following it." This will find all statistic cookies like [57%] and [6/12] and update them with the current numbers. -With optional prefix argument ALL, do this for the whole buffer." +With optional prefix argument ALL, do this for the whole buffer. +When ALL is symbol `narrow', update statistics only in the accessible +portion of the buffer." (interactive "P") - (org-with-wide-buffer - (let* ((cookie-re "\\(\\(\\[[0-9]*%\\]\\)\\|\\(\\[[0-9]*/[0-9]*\\]\\)\\)") - (box-re "^[ \t]*\\([-+*]\\|\\([0-9]+\\|[A-Za-z]\\)[.)]\\)[ \t]+\ + (save-excursion + (save-restriction + (unless (eq all 'narrow) (widen)) + (let* ((cookie-re "\\(\\(\\[[0-9]*%\\]\\)\\|\\(\\[[0-9]*/[0-9]*\\]\\)\\)") + (box-re "^[ \t]*\\([-+*]\\|\\([0-9]+\\|[A-Za-z]\\)[.)]\\)[ \t]+\ \\(?:\\[@\\(?:start:\\)?\\([0-9]+\\|[A-Za-z]\\)\\][ \t]*\\)?\\(\\[[- X]\\]\\)") - (cookie-data (or (org-entry-get nil "COOKIE_DATA") "")) - (recursivep - (or (not org-checkbox-hierarchical-statistics) - (string-match-p "\\" cookie-data))) - (within-inlinetask (and (not all) - (featurep 'org-inlinetask) - (org-inlinetask-in-task-p))) - (end (cond (all (point-max)) - (within-inlinetask - (save-excursion (outline-next-heading) (point))) - (t (save-excursion - (org-with-limited-levels (outline-next-heading)) - (point))))) - (count-boxes - (lambda (item structs recursivep) - ;; Return number of checked boxes and boxes of all types - ;; in all structures in STRUCTS. If RECURSIVEP is - ;; non-nil, also count boxes in sub-lists. If ITEM is - ;; nil, count across the whole structure, else count only - ;; across subtree whose ancestor is ITEM. - (let ((c-on 0) (c-all 0)) - (dolist (s structs (list c-on c-all)) - (let* ((pre (org-list-prevs-alist s)) - (par (org-list-parents-alist s)) - (items - (cond - ((and recursivep item) (org-list-get-subtree item s)) - (recursivep (mapcar #'car s)) - (item (org-list-get-children item s par)) - (t (org-list-get-all-items - (org-list-get-top-point s) s pre)))) - (cookies (delq nil (mapcar - (lambda (e) - (org-list-get-checkbox e s)) - items)))) - (cl-incf c-all (length cookies)) - (cl-incf c-on (cl-count "[X]" cookies :test #'equal))))))) - cookies-list cache) - ;; Move to start. - (cond (all (goto-char (point-min))) - (within-inlinetask (org-back-to-heading t)) - (t (org-with-limited-levels (outline-previous-heading)))) - ;; Build an alist for each cookie found. The key is the position - ;; at beginning of cookie and values ending position, format of - ;; cookie, number of checked boxes to report and total number of - ;; boxes. - (while (re-search-forward cookie-re end t) - (let ((context (save-excursion (backward-char) - (save-match-data (org-element-context))))) - (when (and (eq (org-element-type context) 'statistics-cookie) - (not (string-match-p "\\" cookie-data))) - (push - (append - (list (match-beginning 1) (match-end 1) (match-end 2)) - (let* ((container - (org-element-lineage - context - '(drawer center-block dynamic-block inlinetask item - quote-block special-block verse-block))) - (beg (if container - (org-element-property :contents-begin container) - (save-excursion - (org-with-limited-levels - (outline-previous-heading)) + (cookie-data (or (org-entry-get nil "COOKIE_DATA") "")) + (recursivep + (or (not org-checkbox-hierarchical-statistics) + (string-match-p "\\" cookie-data))) + (within-inlinetask (and (not all) + (featurep 'org-inlinetask) + (org-inlinetask-in-task-p))) + (end (cond (all (point-max)) + (within-inlinetask + (save-excursion (outline-next-heading) (point))) + (t (save-excursion + (org-with-limited-levels (outline-next-heading)) (point))))) - (or (cdr (assq beg cache)) - (save-excursion - (goto-char beg) - (let ((end - (if container - (org-element-property :contents-end container) + (count-boxes + (lambda (item structs recursivep) + ;; Return number of checked boxes and boxes of all types + ;; in all structures in STRUCTS. If RECURSIVEP is + ;; non-nil, also count boxes in sub-lists. If ITEM is + ;; nil, count across the whole structure, else count only + ;; across subtree whose ancestor is ITEM. + (let ((c-on 0) (c-all 0)) + (dolist (s structs (list c-on c-all)) + (let* ((pre (org-list-prevs-alist s)) + (par (org-list-parents-alist s)) + (items + (cond + ((and recursivep item) (org-list-get-subtree item s)) + (recursivep (mapcar #'car s)) + (item (org-list-get-children item s par)) + (t (org-list-get-all-items + (org-list-get-top-point s) s pre)))) + (cookies (delq nil (mapcar + (lambda (e) + (org-list-get-checkbox e s)) + items)))) + (cl-incf c-all (length cookies)) + (cl-incf c-on (cl-count "[X]" cookies :test #'equal))))))) + cookies-list cache) + ;; Move to start. + (cond (all (goto-char (point-min))) + (within-inlinetask (org-back-to-heading t)) + (t (org-with-limited-levels (outline-previous-heading)))) + ;; Build an alist for each cookie found. The key is the position + ;; at beginning of cookie and values ending position, format of + ;; cookie, number of checked boxes to report and total number of + ;; boxes. + (while (re-search-forward cookie-re end t) + (let ((context (save-excursion (backward-char) + (save-match-data (org-element-context))))) + (when (and (org-element-type-p context 'statistics-cookie) + (not (string-match-p "\\" cookie-data))) + (push + (append + (list (match-beginning 1) (match-end 1) (match-end 2)) + (let* ((container + (org-element-lineage + context + '(drawer center-block dynamic-block inlinetask item + quote-block special-block verse-block))) + (beg (if container + (org-element-contents-begin container) (save-excursion - (org-with-limited-levels (outline-next-heading)) - (point)))) - structs) - (while (re-search-forward box-re end t) - (let ((element (org-element-at-point))) - (when (eq (org-element-type element) 'item) - (push (org-element-property :structure element) - structs) - ;; Skip whole list since we have its - ;; structure anyway. - (while (setq element (org-element-lineage - element '(plain-list))) - (goto-char - (min (org-element-property :end element) - end)))))) - ;; Cache count for cookies applying to the same - ;; area. Then return it. - (let ((count - (funcall count-boxes - (and (eq (org-element-type container) - 'item) - (org-element-property - :begin container)) - structs - recursivep))) - (push (cons beg count) cache) - count)))))) - cookies-list)))) - ;; Apply alist to buffer. - (dolist (cookie cookies-list) - (let* ((beg (car cookie)) - (end (nth 1 cookie)) - (percent (nth 2 cookie)) - (checked (nth 3 cookie)) - (total (nth 4 cookie))) - (goto-char beg) - (insert - (if percent (format "[%d%%]" (floor (* 100.0 checked) - (max 1 total))) - (format "[%d/%d]" checked total))) - (delete-region (point) (+ (point) (- end beg))) - (when org-auto-align-tags (org-fix-tags-on-the-fly))))))) + (org-with-limited-levels + (outline-previous-heading)) + (point))))) + (or (cdr (assq beg cache)) + (save-excursion + (goto-char beg) + (let ((end + (if container + (org-element-contents-end container) + (save-excursion + (org-with-limited-levels (outline-next-heading)) + (point)))) + structs) + (while (re-search-forward box-re end t) + (let ((element (org-element-at-point))) + (when (org-element-type-p element 'item) + (push (org-element-property :structure element) + structs) + ;; Skip whole list since we have its + ;; structure anyway. + (while (setq element (org-element-lineage + element 'plain-list)) + (goto-char + (min (org-element-end element) + end)))))) + ;; Cache count for cookies applying to the same + ;; area. Then return it. + (let ((count + (funcall count-boxes + (and (org-element-type-p + container 'item) + (org-element-property + :begin container)) + structs + recursivep))) + (push (cons beg count) cache) + count)))))) + cookies-list)))) + ;; Apply alist to buffer. + (dolist (cookie cookies-list) + (let* ((beg (car cookie)) + (end (nth 1 cookie)) + (percent (nth 2 cookie)) + (checked (nth 3 cookie)) + (total (nth 4 cookie))) + (goto-char beg) + (org-fold-core-ignore-modifications + (insert-and-inherit + (if percent (format "[%d%%]" (floor (* 100.0 checked) + (max 1 total))) + (format "[%d/%d]" checked total))) + (delete-region (point) (+ (point) (- end beg)))) + (when org-auto-align-tags (org-fix-tags-on-the-fly)))))))) (defun org-get-checkbox-statistics-face () "Select the face for checkbox statistics. @@ -2637,7 +2672,9 @@ Otherwise it will be `org-todo'." (defun org-update-checkbox-count-maybe (&optional all) "Update checkbox statistics unless turned off by user. -With an optional argument ALL, update them in the whole buffer." +With an optional argument ALL, update them in the whole buffer. +When ALL is symbol `narrow', update statistics only in the accessible +portion of the buffer." (when (cdr (assq 'checkbox org-list-automatic-rules)) (org-update-checkbox-count all)) (run-hooks 'org-checkbox-statistics-hook)) @@ -2688,7 +2725,8 @@ Return t if successful." (no-subtree (1+ (line-beginning-position))) (t (org-list-get-item-end (line-beginning-position) struct)))))) (let* ((beg (marker-position org-last-indent-begin-marker)) - (end (marker-position org-last-indent-end-marker))) + (end (marker-position org-last-indent-end-marker)) + (deactivate-mark nil)) (cond ;; Special case: moving top-item with indent rule. (specialp @@ -2941,7 +2979,7 @@ function is being called interactively." (error "Missing key extractor")))) (sort-func (cond - ((= dcst ?a) #'string-collate-lessp) + ((= dcst ?a) #'org-string<) ((= dcst ?f) (or compare-func (and interactive? @@ -2959,7 +2997,7 @@ function is being called interactively." (now (current-time)) (next-record (lambda () (skip-chars-forward " \r\t\n") - (or (eobp) (beginning-of-line)))) + (or (eobp) (forward-line 0)))) (end-record (lambda () (goto-char (org-list-get-item-end-before-blank (point) struct)))) @@ -3030,28 +3068,25 @@ With a prefix argument ARG, change the region in a single item." (save-excursion (while (re-search-forward org-footnote-definition-re end t) (setq element (org-element-at-point)) - (when (eq 'footnote-definition - (org-element-type element)) + (when (org-element-type-p element 'footnote-definition) (push (buffer-substring-no-properties - (org-element-property :begin element) - (org-element-property :end element)) + (org-element-begin element) + (org-element-end element)) definitions) ;; Ensure at least 2 blank lines after the last ;; footnote definition, thus not slurping the ;; following element. - (unless (<= 2 (org-element-property - :post-blank - (org-element-at-point))) + (unless (<= 2 (org-element-post-blank + (org-element-at-point))) (setf (car definitions) (concat (car definitions) (make-string - (- 2 (org-element-property - :post-blank + (- 2 (org-element-post-blank (org-element-at-point))) ?\n)))) (delete-region - (org-element-property :begin element) - (org-element-property :end element)))) + (org-element-begin element) + (org-element-end element)))) definitions)))) (shift-text (lambda (ind end) @@ -3158,8 +3193,8 @@ With a prefix argument ARG, change the region in a single item." "[X]" "[ ]")) (org-list-write-struct struct - (org-list-parents-alist struct) - old))) + (org-list-parents-alist struct) + old))) ;; Ensure all text down to END (or SECTION-END) belongs ;; to the newly created item. (let ((section-end (save-excursion @@ -3171,7 +3206,7 @@ With a prefix argument ARG, change the region in a single item." (when footnote-definitions (goto-char end) ;; Insert footnote definitions after the list. - (unless (bolp) (beginning-of-line 2)) + (unless (bolp) (forward-line 1)) ;; At (point-max). (unless (bolp) (insert "\n")) (dolist (def footnote-definitions) @@ -3198,13 +3233,12 @@ With a prefix argument ARG, change the region in a single item." (when footnote-definitions ;; If the new list is followed by same-level items, ;; move past them as well. - (goto-char (org-element-property - :end + (goto-char (org-element-end (org-element-lineage (org-element-at-point (1- end)) - '(plain-list) t))) + 'plain-list t))) ;; Insert footnote definitions after the list. - (unless (bolp) (beginning-of-line 2)) + (unless (bolp) (forward-line 1)) ;; At (point-max). (unless (bolp) (insert "\n")) (dolist (def footnote-definitions) @@ -3333,7 +3367,7 @@ Valid parameters are: :backend, :raw - Export back-end used as a basis to transcode elements of the + Export backend used as a basis to transcode elements of the list, when no specific parameter applies to it. It is also used to translate its contents. You can prevent this by setting :raw property to a non-nil value. @@ -3421,7 +3455,7 @@ Valid parameters are: (if (consp e) (funcall insert-list e) (insert e) (insert "\n"))) - (beginning-of-line) + (forward-line 0) (save-excursion (let ((ind (if (eq type 'ordered) 3 2))) (while (> (point) start) @@ -3441,7 +3475,7 @@ Valid parameters are: (when (and backend (plist-get params :raw)) (org-element-map data org-element-all-objects (lambda (object) - (org-element-set-element + (org-element-set object (org-element-interpret-data object))))) ;; We use a low-level mechanism to export DATA so as to skip all ;; usual pre-processing and post-processing, i.e., hooks, filters, @@ -3454,7 +3488,7 @@ Valid parameters are: (defun org-list--depth (element) "Return the level of ELEMENT within current plain list. ELEMENT is either an item or a plain list." - (cl-count-if (lambda (ancestor) (eq (org-element-type ancestor) 'plain-list)) + (cl-count-if (lambda (ancestor) (org-element-type-p ancestor 'plain-list)) (org-element-lineage element nil t))) (defun org-list--trailing-newlines (string) @@ -3531,7 +3565,7 @@ PARAMS is a plist used to tweak the behavior of the transcoder." (ddend (plist-get params :ddend))) (lambda (item contents info) (let* ((type - (org-element-property :type (org-element-property :parent item))) + (org-element-property :type (org-element-parent item))) (tag (org-element-property :tag item)) (depth (org-list--depth item)) (separator (and (org-export-get-next-element item info) diff --git a/elpa/org-9.6.7/org-loaddefs.el b/elpa/org-9.7.17/org-loaddefs.el similarity index 53% rename from elpa/org-9.6.7/org-loaddefs.el rename to elpa/org-9.7.17/org-loaddefs.el index 43ea124d..649ab0f9 100644 --- a/elpa/org-9.6.7/org-loaddefs.el +++ b/elpa/org-9.7.17/org-loaddefs.el @@ -1,76 +1,38 @@ -;;; org-loaddefs.el --- autogenerated file, do not edit -;; -;;; Code: - -;;;### (autoloads nil "ob-C" "ob-C.el" (0 0 0 0)) -;;; Generated autoloads from ob-C.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ob-C" '("org-babel-"))) - -;;;*** - -;;;### (autoloads nil "ob-R" "ob-R.el" (0 0 0 0)) -;;; Generated autoloads from ob-R.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ob-R" '("ob-" "org-babel-"))) - -;;;*** - -;;;### (autoloads nil "ob-awk" "ob-awk.el" (0 0 0 0)) -;;; Generated autoloads from ob-awk.el +;;; org-loaddefs.el --- automatically extracted autoloads (do not edit) -*- lexical-binding: t -*- +;; Generated by the `loaddefs-generate' function. -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ob-awk" '("org-babel-"))) +;; This file is part of GNU Emacs. -;;;*** - -;;;### (autoloads nil "ob-calc" "ob-calc.el" (0 0 0 0)) -;;; Generated autoloads from ob-calc.el +;;; Code: -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ob-calc" '("org-babel-"))) +(add-to-list 'load-path (or (and load-file-name (directory-file-name (file-name-directory load-file-name))) (car load-path))) -;;;*** - -;;;### (autoloads nil "ob-clojure" "ob-clojure.el" (0 0 0 0)) -;;; Generated autoloads from ob-clojure.el -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ob-clojure" '("ob-clojure-" "org-babel-"))) - -;;;*** -;;;### (autoloads nil "ob-comint" "ob-comint.el" (0 0 0 0)) -;;; Generated autoloads from ob-comint.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ob-comint" '("org-babel-comint-"))) - -;;;*** - -;;;### (autoloads nil "ob-core" "ob-core.el" "1551d73fa40f7831de5eef5e95a85a1a") ;;; Generated autoloads from ob-core.el -(autoload 'org-babel-execute-safely-maybe "ob-core" nil nil nil) - -(autoload 'org-babel-execute-maybe "ob-core" nil t nil) - +(autoload 'org-babel-execute-safely-maybe "ob-core" "\ +Maybe `org-babel-execute-maybe'. +This function does nothing unless `org-babel-no-eval-on-ctrl-c-ctrl-c' +is non-nil.") +(autoload 'org-babel-execute-maybe "ob-core" "\ +Execute src block or babel call at point." t) (autoload 'org-babel-view-src-block-info "ob-core" "\ Display information on the current source block. This includes header arguments, language and name, and is largely -a window into the `org-babel-get-src-block-info' function." t nil) - +a window into the `org-babel-get-src-block-info' function." t) (autoload 'org-babel-expand-src-block-maybe "ob-core" "\ Conditionally expand a source block. Detect if this is context for an org-babel src-block and if so -then run `org-babel-expand-src-block'." t nil) - +then run `org-babel-expand-src-block'." t) (autoload 'org-babel-load-in-session-maybe "ob-core" "\ Conditionally load a source block in a session. Detect if this is context for an org-babel src-block and if so -then run `org-babel-load-in-session'." t nil) - +then run `org-babel-load-in-session'." t) (autoload 'org-babel-pop-to-session-maybe "ob-core" "\ Conditionally pop to a session. Detect if this is context for an org-babel src-block and if so -then run `org-babel-switch-to-session'." t nil) - +then run `org-babel-switch-to-session'." t) (autoload 'org-babel-execute-src-block "ob-core" "\ Execute the current source code block and return the result. Insert the results of execution into the buffer. Source code @@ -91,58 +53,59 @@ EXECUTOR-TYPE is the type of the org element responsible for the execution of the source block. If not provided then informed guess will be made. -\(fn &optional ARG INFO PARAMS EXECUTOR-TYPE)" t nil) - +(fn &optional ARG INFO PARAMS EXECUTOR-TYPE)" t) (autoload 'org-babel-expand-src-block "ob-core" "\ -Expand the current source code block. +Expand the current source code block or block specified by INFO. +INFO is the output of `org-babel-get-src-block-info'. +PARAMS defines inherited header arguments. + Expand according to the source code block's header arguments and pop open the results in a preview buffer. -\(fn &optional ARG INFO PARAMS)" t nil) - +(fn &optional ARG INFO PARAMS)" t) (autoload 'org-babel-check-src-block "ob-core" "\ -Check for misspelled header arguments in the current code block." t nil) - +Check for misspelled header arguments in the current code block." t) (autoload 'org-babel-insert-header-arg "ob-core" "\ -Insert a header argument selecting from lists of common args and values. - -\(fn &optional HEADER-ARG VALUE)" t nil) +Insert a header argument and its value. +HEADER-ARG and VALUE, when provided, are the header argument name and +its value. When HEADER-ARG or VALUE are nil, offer interactive +completion from lists of common args and values. +(fn &optional HEADER-ARG VALUE)" t) (autoload 'org-babel-load-in-session "ob-core" "\ Load the body of the current source-code block. +When optional argument INFO is non-nil, use source block defined in +INFO, as returned by `org-babel-get-src-block-info'. + Evaluate the header arguments for the source block before entering the session. After loading the body this pops open the session. -\(fn &optional ARG INFO)" t nil) - +(fn &optional ARG INFO)" t) (autoload 'org-babel-initiate-session "ob-core" "\ -Initiate session for current code block. -If called with a prefix argument then resolve any variable +Initiate session for current code block or the block defined by INFO. +If called with a prefix argument ARG, then resolve any variable references in the header arguments and assign these variables in the session. Copy the body of the code block to the kill ring. -\(fn &optional ARG INFO)" t nil) - +(fn &optional ARG INFO)" t) (autoload 'org-babel-switch-to-session "ob-core" "\ -Switch to the session of the current code block. +Switch to the session of the current code block or block defined by INFO. Uses `org-babel-initiate-session' to start the session. If called -with a prefix argument then this is passed on to +with a prefix argument ARG, then this is passed on to `org-babel-initiate-session'. -\(fn &optional ARG INFO)" t nil) - +(fn &optional ARG INFO)" t) (autoload 'org-babel-switch-to-session-with-code "ob-core" "\ Switch to code buffer and display session. +Prefix argument ARG is passed to `org-babel-switch-to-session'. -\(fn &optional ARG INFO)" t nil) - +(fn &optional ARG INFO)" t) (autoload 'org-babel-do-in-edit-buffer "ob-core" "\ Evaluate BODY in edit buffer if there is a code block at point. Return t if a code block was found at point, nil otherwise. -\(fn &rest BODY)" nil t) - +(fn &rest BODY)" nil t) (autoload 'org-babel-open-src-block-result "ob-core" "\ Open results of source block at point. @@ -151,8 +114,7 @@ code block, otherwise return nil. With optional prefix argument RE-RUN the source-code block is evaluated even if results already exist. -\(fn &optional RE-RUN)" t nil) - +(fn &optional RE-RUN)" t) (autoload 'org-babel-map-src-blocks "ob-core" "\ Evaluate BODY forms on each source-block in FILE. If FILE is nil evaluate BODY forms on source blocks in current @@ -175,233 +137,80 @@ body ------------- string holding the body of the code block beg-body --------- point at the beginning of the body end-body --------- point at the end of the body -\(fn FILE &rest BODY)" nil t) - -(function-put 'org-babel-map-src-blocks 'lisp-indent-function '1) - +(fn FILE &rest BODY)" nil t) +(function-put 'org-babel-map-src-blocks 'lisp-indent-function 1) (autoload 'org-babel-map-inline-src-blocks "ob-core" "\ Evaluate BODY forms on each inline source block in FILE. If FILE is nil evaluate BODY forms on source blocks in current buffer. -\(fn FILE &rest BODY)" nil t) - -(function-put 'org-babel-map-inline-src-blocks 'lisp-indent-function '1) - +(fn FILE &rest BODY)" nil t) +(function-put 'org-babel-map-inline-src-blocks 'lisp-indent-function 1) (autoload 'org-babel-map-call-lines "ob-core" "\ Evaluate BODY forms on each call line in FILE. If FILE is nil evaluate BODY forms on source blocks in current buffer. -\(fn FILE &rest BODY)" nil t) - -(function-put 'org-babel-map-call-lines 'lisp-indent-function '1) - +(fn FILE &rest BODY)" nil t) +(function-put 'org-babel-map-call-lines 'lisp-indent-function 1) (autoload 'org-babel-map-executables "ob-core" "\ Evaluate BODY forms on each active Babel code in FILE. If FILE is nil evaluate BODY forms on source blocks in current buffer. -\(fn FILE &rest BODY)" nil t) - -(function-put 'org-babel-map-executables 'lisp-indent-function '1) - +(fn FILE &rest BODY)" nil t) +(function-put 'org-babel-map-executables 'lisp-indent-function 1) (autoload 'org-babel-execute-buffer "ob-core" "\ Execute source code blocks in a buffer. +Prefix argument ARG is passed to `org-babel-execute-src-block'. Call `org-babel-execute-src-block' on every source block in the current buffer. -\(fn &optional ARG)" t nil) - +(fn &optional ARG)" t) (autoload 'org-babel-execute-subtree "ob-core" "\ Execute source code blocks in a subtree. Call `org-babel-execute-src-block' on every source block in -the current subtree. - -\(fn &optional ARG)" t nil) +the current subtree, passing over the prefix argument ARG. +(fn &optional ARG)" t) (autoload 'org-babel-sha1-hash "ob-core" "\ Generate a sha1 hash based on the value of INFO. CONTEXT specifies the context of evaluation. It can be `:eval', `:export', `:tangle'. A nil value means `:eval'. -\(fn &optional INFO CONTEXT)" t nil) - +(fn &optional INFO CONTEXT)" t) (autoload 'org-babel-hide-result-toggle-maybe "ob-core" "\ -Toggle visibility of result at point." t nil) - +Toggle visibility of result at point." t) (autoload 'org-babel-goto-src-block-head "ob-core" "\ -Go to the beginning of the current code block." t nil) - +Go to the beginning of the current code block." t) (autoload 'org-babel-goto-named-src-block "ob-core" "\ -Go to a named source-code block. - -\(fn NAME)" t nil) +Go to a source-code block with NAME. +(fn NAME)" t) (autoload 'org-babel-goto-named-result "ob-core" "\ -Go to a named result. - -\(fn NAME)" t nil) +Go to a result with NAME. +(fn NAME)" t) (autoload 'org-babel-next-src-block "ob-core" "\ Jump to the next source block. With optional prefix argument ARG, jump forward ARG many source blocks. -\(fn &optional ARG)" t nil) - +(fn &optional ARG)" t) (autoload 'org-babel-previous-src-block "ob-core" "\ Jump to the previous source block. With optional prefix argument ARG, jump backward ARG many source blocks. -\(fn &optional ARG)" t nil) - +(fn &optional ARG)" t) (autoload 'org-babel-mark-block "ob-core" "\ -Mark current source block." t nil) - -;;;### (autoloads "actual autoloads are elsewhere" "ob-core" "ob-core.el" -;;;;;; (0 0 0 0)) -;;; Generated autoloads from ob-core.el - -(register-definition-prefixes "ob-core" '("org-")) - -;;;*** - -;;;*** - -;;;### (autoloads nil "ob-css" "ob-css.el" (0 0 0 0)) -;;; Generated autoloads from ob-css.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ob-css" '("org-babel-"))) - -;;;*** - -;;;### (autoloads nil "ob-ditaa" "ob-ditaa.el" (0 0 0 0)) -;;; Generated autoloads from ob-ditaa.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ob-ditaa" '("org-"))) - -;;;*** - -;;;### (autoloads nil "ob-dot" "ob-dot.el" (0 0 0 0)) -;;; Generated autoloads from ob-dot.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ob-dot" '("org-babel-"))) - -;;;*** - -;;;### (autoloads nil "ob-emacs-lisp" "ob-emacs-lisp.el" (0 0 0 0)) -;;; Generated autoloads from ob-emacs-lisp.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ob-emacs-lisp" '("org-babel-"))) - -;;;*** - -;;;### (autoloads nil "ob-eshell" "ob-eshell.el" (0 0 0 0)) -;;; Generated autoloads from ob-eshell.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ob-eshell" '("ob-eshell-session-live-p" "org-babel-"))) - -;;;*** - -;;;### (autoloads nil "ob-eval" "ob-eval.el" (0 0 0 0)) -;;; Generated autoloads from ob-eval.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ob-eval" '("org-babel-"))) - -;;;*** - -;;;### (autoloads nil "ob-exp" "ob-exp.el" (0 0 0 0)) -;;; Generated autoloads from ob-exp.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ob-exp" '("org-"))) - -;;;*** - -;;;### (autoloads nil "ob-forth" "ob-forth.el" (0 0 0 0)) -;;; Generated autoloads from ob-forth.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ob-forth" '("org-babel-"))) - -;;;*** - -;;;### (autoloads nil "ob-fortran" "ob-fortran.el" (0 0 0 0)) -;;; Generated autoloads from ob-fortran.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ob-fortran" '("org-babel-"))) - -;;;*** - -;;;### (autoloads nil "ob-gnuplot" "ob-gnuplot.el" (0 0 0 0)) -;;; Generated autoloads from ob-gnuplot.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ob-gnuplot" '("*org-babel-gnuplot-" "org-babel-"))) - -;;;*** - -;;;### (autoloads nil "ob-groovy" "ob-groovy.el" (0 0 0 0)) -;;; Generated autoloads from ob-groovy.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ob-groovy" '("org-babel-"))) - -;;;*** - -;;;### (autoloads nil "ob-haskell" "ob-haskell.el" (0 0 0 0)) -;;; Generated autoloads from ob-haskell.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ob-haskell" '("org-babel-"))) - -;;;*** - -;;;### (autoloads nil "ob-java" "ob-java.el" (0 0 0 0)) -;;; Generated autoloads from ob-java.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ob-java" '("org-babel-"))) - -;;;*** - -;;;### (autoloads nil "ob-js" "ob-js.el" (0 0 0 0)) -;;; Generated autoloads from ob-js.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ob-js" '("org-babel-"))) - -;;;*** - -;;;### (autoloads nil "ob-julia" "ob-julia.el" (0 0 0 0)) -;;; Generated autoloads from ob-julia.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ob-julia" '("org-babel-"))) - -;;;*** - -;;;### (autoloads nil "ob-latex" "ob-latex.el" (0 0 0 0)) -;;; Generated autoloads from ob-latex.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ob-latex" '("org-babel-"))) - -;;;*** - -;;;### (autoloads nil "ob-lilypond" "ob-lilypond.el" (0 0 0 0)) -;;; Generated autoloads from ob-lilypond.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ob-lilypond" '("lilypond-mode" "ob-lilypond-header-args" "org-babel-"))) - -;;;*** - -;;;### (autoloads nil "ob-lisp" "ob-lisp.el" (0 0 0 0)) -;;; Generated autoloads from ob-lisp.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ob-lisp" '("org-babel-"))) +Mark current source block." t) -;;;*** -;;;### (autoloads nil "ob-lob" "ob-lob.el" "f2b24928cff81b0cc0d2e0820af38a82") ;;; Generated autoloads from ob-lob.el (autoload 'org-babel-lob-execute-maybe "ob-lob" "\ Execute a Library of Babel source block, if appropriate. Detect if this is context for a Library Of Babel source block and -if so then run the appropriate source block from the Library." t nil) - +if so then run the appropriate source block from the Library." t) (autoload 'org-babel-lob-get-info "ob-lob" "\ Return internal representation for Library of Babel function call. @@ -416,159 +225,9 @@ Return nil when not on an appropriate location. Otherwise return a list compatible with `org-babel-get-src-block-info', which see. -\(fn &optional DATUM NO-EVAL)" nil nil) - -;;;### (autoloads "actual autoloads are elsewhere" "ob-lob" "ob-lob.el" -;;;;;; (0 0 0 0)) -;;; Generated autoloads from ob-lob.el - -(register-definition-prefixes "ob-lob" '("org-babel-")) - -;;;*** - -;;;*** - -;;;### (autoloads nil "ob-lua" "ob-lua.el" (0 0 0 0)) -;;; Generated autoloads from ob-lua.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ob-lua" '("org-babel-"))) - -;;;*** - -;;;### (autoloads nil "ob-makefile" "ob-makefile.el" (0 0 0 0)) -;;; Generated autoloads from ob-makefile.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ob-makefile" '("org-babel-"))) - -;;;*** - -;;;### (autoloads nil "ob-maxima" "ob-maxima.el" (0 0 0 0)) -;;; Generated autoloads from ob-maxima.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ob-maxima" '("org-babel-"))) - -;;;*** - -;;;### (autoloads nil "ob-ocaml" "ob-ocaml.el" (0 0 0 0)) -;;; Generated autoloads from ob-ocaml.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ob-ocaml" '("org-babel-"))) - -;;;*** - -;;;### (autoloads nil "ob-octave" "ob-octave.el" (0 0 0 0)) -;;; Generated autoloads from ob-octave.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ob-octave" '("org-babel-"))) - -;;;*** - -;;;### (autoloads nil "ob-org" "ob-org.el" (0 0 0 0)) -;;; Generated autoloads from ob-org.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ob-org" '("org-babel-"))) - -;;;*** - -;;;### (autoloads nil "ob-perl" "ob-perl.el" (0 0 0 0)) -;;; Generated autoloads from ob-perl.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ob-perl" '("org-babel-"))) - -;;;*** - -;;;### (autoloads nil "ob-plantuml" "ob-plantuml.el" (0 0 0 0)) -;;; Generated autoloads from ob-plantuml.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ob-plantuml" '("org-"))) - -;;;*** - -;;;### (autoloads nil "ob-processing" "ob-processing.el" (0 0 0 0)) -;;; Generated autoloads from ob-processing.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ob-processing" '("org-babel-"))) - -;;;*** - -;;;### (autoloads nil "ob-python" "ob-python.el" (0 0 0 0)) -;;; Generated autoloads from ob-python.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ob-python" '("org-babel-"))) - -;;;*** - -;;;### (autoloads nil "ob-ref" "ob-ref.el" (0 0 0 0)) -;;; Generated autoloads from ob-ref.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ob-ref" '("org-babel-"))) - -;;;*** - -;;;### (autoloads nil "ob-ruby" "ob-ruby.el" (0 0 0 0)) -;;; Generated autoloads from ob-ruby.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ob-ruby" '("org-babel-"))) +(fn &optional DATUM NO-EVAL)") -;;;*** -;;;### (autoloads nil "ob-sass" "ob-sass.el" (0 0 0 0)) -;;; Generated autoloads from ob-sass.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ob-sass" '("org-babel-"))) - -;;;*** - -;;;### (autoloads nil "ob-scheme" "ob-scheme.el" (0 0 0 0)) -;;; Generated autoloads from ob-scheme.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ob-scheme" '("org-babel-"))) - -;;;*** - -;;;### (autoloads nil "ob-screen" "ob-screen.el" (0 0 0 0)) -;;; Generated autoloads from ob-screen.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ob-screen" '("org-babel-"))) - -;;;*** - -;;;### (autoloads nil "ob-sed" "ob-sed.el" (0 0 0 0)) -;;; Generated autoloads from ob-sed.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ob-sed" '("org-babel-"))) - -;;;*** - -;;;### (autoloads nil "ob-shell" "ob-shell.el" (0 0 0 0)) -;;; Generated autoloads from ob-shell.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ob-shell" '("org-babel-"))) - -;;;*** - -;;;### (autoloads nil "ob-sql" "ob-sql.el" (0 0 0 0)) -;;; Generated autoloads from ob-sql.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ob-sql" '("org-babel-"))) - -;;;*** - -;;;### (autoloads nil "ob-sqlite" "ob-sqlite.el" (0 0 0 0)) -;;; Generated autoloads from ob-sqlite.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ob-sqlite" '("org-babel-"))) - -;;;*** - -;;;### (autoloads nil "ob-table" "ob-table.el" (0 0 0 0)) -;;; Generated autoloads from ob-table.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ob-table" '("org-"))) - -;;;*** - -;;;### (autoloads nil "ob-tangle" "ob-tangle.el" "a9ed6681f7cb914b3e765c96ad7217e9") ;;; Generated autoloads from ob-tangle.el (autoload 'org-babel-tangle-file "ob-tangle" "\ @@ -583,8 +242,7 @@ source code blocks by languages matching a regular expression. Return list of the tangled file names. -\(fn FILE &optional TARGET-FILE LANG-RE)" t nil) - +(fn FILE &optional TARGET-FILE LANG-RE)" t) (autoload 'org-babel-tangle "ob-tangle" "\ Write code blocks to source-specific files. Extract the bodies of all source code blocks from the current @@ -597,68 +255,9 @@ export file for all source blocks. Optional argument LANG-RE can be used to limit the exported source code blocks by languages matching a regular expression. -\(fn &optional ARG TARGET-FILE LANG-RE)" t nil) - -;;;### (autoloads "actual autoloads are elsewhere" "ob-tangle" "ob-tangle.el" -;;;;;; (0 0 0 0)) -;;; Generated autoloads from ob-tangle.el +(fn &optional ARG TARGET-FILE LANG-RE)" t) -(register-definition-prefixes "ob-tangle" '("org-babel-")) - -;;;*** - -;;;*** -;;;### (autoloads nil "oc-basic" "oc-basic.el" (0 0 0 0)) -;;; Generated autoloads from oc-basic.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "oc-basic" '("org-cite-basic-"))) - -;;;*** - -;;;### (autoloads nil "oc-biblatex" "oc-biblatex.el" (0 0 0 0)) -;;; Generated autoloads from oc-biblatex.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "oc-biblatex" '("org-cite-biblatex-"))) - -;;;*** - -;;;### (autoloads nil "oc-bibtex" "oc-bibtex.el" (0 0 0 0)) -;;; Generated autoloads from oc-bibtex.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "oc-bibtex" '("org-cite-bibtex-export-"))) - -;;;*** - -;;;### (autoloads nil "oc-csl" "oc-csl.el" (0 0 0 0)) -;;; Generated autoloads from oc-csl.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "oc-csl" '("org-cite-csl-"))) - -;;;*** - -;;;### (autoloads nil "oc-natbib" "oc-natbib.el" (0 0 0 0)) -;;; Generated autoloads from oc-natbib.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "oc-natbib" '("org-cite-natbib-"))) - -;;;*** - -;;;### (autoloads nil "oc" "oc.el" (0 0 0 0)) -;;; Generated autoloads from oc.el - -(autoload 'org-cite-insert "oc" "\ -Insert a citation at point. -Insertion is done according to the processor set in `org-cite-insert-processor'. -ARG is the prefix argument received when calling interactively the function. - -\(fn ARG)" t nil) - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "oc" '("org-cite-"))) - -;;;*** - -;;;### (autoloads nil "ol" "ol.el" "e8b7fc9f9de8a75719e56efcf452161c") ;;; Generated autoloads from ol.el (autoload 'org-next-link "ol" "\ @@ -666,23 +265,22 @@ Move forward to the next link. If the link is in hidden text, expose it. When SEARCH-BACKWARD is non-nil, move backward. -\(fn &optional SEARCH-BACKWARD)" t nil) - +(fn &optional SEARCH-BACKWARD)" t) (autoload 'org-previous-link "ol" "\ Move backward to the previous link. -If the link is in hidden text, expose it." t nil) - +If the link is in hidden text, expose it." t) (autoload 'org-toggle-link-display "ol" "\ -Toggle the literal or descriptive display of links in current buffer." t nil) - +Toggle the literal or descriptive display of links in current buffer." t) (autoload 'org-store-link "ol" "\ Store a link to the current location. \\ This link is added to `org-stored-links' and can later be inserted into an Org buffer with `org-insert-link' (`\\[org-insert-link]'). +When optional argument INTERACTIVE? is nil, the link is not stored in +`org-stored-links', but returned as a string. For some link types, a `\\[universal-argument]' prefix ARG is interpreted. A single -`\\[universal-argument]' negates `org-context-in-file-links' for file links or +`\\[universal-argument]' negates `org-link-context-for-files' for file links or `org-gnus-prefer-web-links' for links to Usenet articles. A `\\[universal-argument] \\[universal-argument]' prefix ARG forces skipping storing functions that are not @@ -694,8 +292,12 @@ active region. Assume the function is called interactively if INTERACTIVE? is non-nil. -\(fn ARG &optional INTERACTIVE\\=\\?)" t nil) +In Org buffers, an additional \"human-readable\" simple file link +is stored as an alternative to persistent org-id or other links, +if at a heading with a CUSTOM_ID property or an element with a +NAME. +(fn ARG &optional INTERACTIVE?)" t) (autoload 'org-insert-link "ol" "\ Insert a link. At the prompt, enter the link. @@ -720,7 +322,7 @@ With a `\\[universal-argument]' prefix, prompts for a file to link to. The file selected using completion. The path to the file will be relative to the current directory if the file is in the current directory or a subdirectory. Otherwise, the link will be the absolute path as completed in the minibuffer -\(i.e. normally ~/path/to/file). You can configure this behavior using the +(i.e. normally ~/path/to/file). You can configure this behavior using the option `org-link-file-path-type'. With a `\\[universal-argument] \\[universal-argument]' prefix, enforce an absolute path even if the file is in @@ -738,10 +340,9 @@ generate a description as described in `org-link-parameters' docstring. Otherwise, if `org-link-make-description-function' is non-nil, this function will be called with the link target, and the result will be the default link description. When called -non-interactively, don't allow to edit the default description. - -\(fn &optional COMPLETE-FILE LINK-LOCATION DESCRIPTION)" t nil) +non-interactively, don't allow editing the default description. +(fn &optional COMPLETE-FILE LINK-LOCATION DESCRIPTION)" t) (autoload 'org-insert-all-links "ol" "\ Insert all links in `org-stored-links'. When a universal prefix, do not delete the links from `org-stored-links'. @@ -749,538 +350,53 @@ When `ARG' is a number, insert the last N link(s). `PRE' and `POST' are optional arguments to define a string to prepend or to append. -\(fn ARG &optional PRE POST)" t nil) - +(fn ARG &optional PRE POST)" t) (autoload 'org-insert-last-stored-link "ol" "\ Insert the last link stored in `org-stored-links'. -\(fn ARG)" t nil) - +(fn ARG)" t) (autoload 'org-insert-link-global "ol" "\ Insert a link like Org mode does. -This command can be called in any mode to insert a link in Org syntax." t nil) - +This command can be called in any mode to insert a link in Org syntax." t) (autoload 'org-update-radio-target-regexp "ol" "\ Find all radio targets in this file and update the regular expression. -Also refresh fontification if needed." t nil) - -;;;### (autoloads "actual autoloads are elsewhere" "ol" "ol.el" (0 -;;;;;; 0 0 0)) -;;; Generated autoloads from ol.el - -(register-definition-prefixes "ol" '("org-")) - -;;;*** +Also refresh fontification if needed." t) -;;;*** -;;;### (autoloads nil "ol-bbdb" "ol-bbdb.el" "20df5c4b0f6ebfeeaf86f524574e4508") ;;; Generated autoloads from ol-bbdb.el (autoload 'org-bbdb-anniversaries "ol-bbdb" "\ Extract anniversaries from BBDB for display in the agenda. When called programmatically, this function expects the `date' -variable to be globally bound." nil nil) - -;;;### (autoloads "actual autoloads are elsewhere" "ol-bbdb" "ol-bbdb.el" -;;;;;; (0 0 0 0)) -;;; Generated autoloads from ol-bbdb.el - -(register-definition-prefixes "ol-bbdb" '("org-bbdb-")) +variable to be globally bound.") -;;;*** - -;;;*** -;;;### (autoloads nil "ol-bibtex" "ol-bibtex.el" (0 0 0 0)) -;;; Generated autoloads from ol-bibtex.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ol-bibtex" '("org-"))) - -;;;*** - -;;;### (autoloads nil "ol-docview" "ol-docview.el" (0 0 0 0)) -;;; Generated autoloads from ol-docview.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ol-docview" '("org-docview-"))) - -;;;*** - -;;;### (autoloads nil "ol-doi" "ol-doi.el" (0 0 0 0)) -;;; Generated autoloads from ol-doi.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ol-doi" '("org-link-doi-"))) - -;;;*** - -;;;### (autoloads nil "ol-eshell" "ol-eshell.el" (0 0 0 0)) -;;; Generated autoloads from ol-eshell.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ol-eshell" '("org-eshell-"))) - -;;;*** - -;;;### (autoloads nil "ol-eww" "ol-eww.el" (0 0 0 0)) -;;; Generated autoloads from ol-eww.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ol-eww" '("org-eww-"))) - -;;;*** - -;;;### (autoloads nil "ol-gnus" "ol-gnus.el" (0 0 0 0)) -;;; Generated autoloads from ol-gnus.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ol-gnus" '("org-gnus-"))) - -;;;*** - -;;;### (autoloads nil "ol-info" "ol-info.el" (0 0 0 0)) -;;; Generated autoloads from ol-info.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ol-info" '("org-info-"))) - -;;;*** - -;;;### (autoloads nil "ol-irc" "ol-irc.el" "2878d0913894961227d05ccf4afaa02d") ;;; Generated autoloads from ol-irc.el (autoload 'org-irc-store-link "ol-irc" "\ -Dispatch to the appropriate function to store a link to an IRC session." nil nil) - -;;;### (autoloads "actual autoloads are elsewhere" "ol-irc" "ol-irc.el" -;;;;;; (0 0 0 0)) -;;; Generated autoloads from ol-irc.el - -(register-definition-prefixes "ol-irc" '("org-irc-")) - -;;;*** - -;;;*** - -;;;### (autoloads nil "ol-man" "ol-man.el" (0 0 0 0)) -;;; Generated autoloads from ol-man.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ol-man" '("org-man-"))) - -;;;*** - -;;;### (autoloads nil "ol-mhe" "ol-mhe.el" (0 0 0 0)) -;;; Generated autoloads from ol-mhe.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ol-mhe" '("org-mhe-"))) - -;;;*** - -;;;### (autoloads nil "ol-rmail" "ol-rmail.el" (0 0 0 0)) -;;; Generated autoloads from ol-rmail.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ol-rmail" '("org-rmail-"))) - -;;;*** - -;;;### (autoloads nil "ol-w3m" "ol-w3m.el" (0 0 0 0)) -;;; Generated autoloads from ol-w3m.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ol-w3m" '("org-w3m-"))) - -;;;*** - -;;;### (autoloads nil "ol" "ol.el" (0 0 0 0)) -;;; Generated autoloads from ol.el - -(autoload 'org-next-link "ol" "\ -Move forward to the next link. -If the link is in hidden text, expose it. When SEARCH-BACKWARD -is non-nil, move backward. - -\(fn &optional SEARCH-BACKWARD)" t nil) - -(autoload 'org-previous-link "ol" "\ -Move backward to the previous link. -If the link is in hidden text, expose it." t nil) - -(autoload 'org-toggle-link-display "ol" "\ -Toggle the literal or descriptive display of links in current buffer." t nil) - -(autoload 'org-store-link "ol" "\ -Store a link to the current location. -\\ -This link is added to `org-stored-links' and can later be inserted -into an Org buffer with `org-insert-link' (`\\[org-insert-link]'). - -For some link types, a `\\[universal-argument]' prefix ARG is interpreted. A single -`\\[universal-argument]' negates `org-context-in-file-links' for file links or -`org-gnus-prefer-web-links' for links to Usenet articles. - -A `\\[universal-argument] \\[universal-argument]' prefix ARG forces skipping storing functions that are not -part of Org core. - -A `\\[universal-argument] \\[universal-argument] \\[universal-argument]' prefix ARG forces storing a link for each line in the -active region. - -Assume the function is called interactively if INTERACTIVE? is -non-nil. - -\(fn ARG &optional INTERACTIVE\\=\\?)" t nil) - -(autoload 'org-insert-link "ol" "\ -Insert a link. At the prompt, enter the link. - -Completion can be used to insert any of the link protocol prefixes in use. - -The history can be used to select a link previously stored with -`org-store-link'. When the empty string is entered (i.e. if you just -press `RET' at the prompt), the link defaults to the most recently -stored link. As `SPC' triggers completion in the minibuffer, you need to -use `M-SPC' or `C-q SPC' to force the insertion of a space character. -Completion candidates include link descriptions. - -If there is a link under cursor then edit it. - -You will also be prompted for a description, and if one is given, it will -be displayed in the buffer instead of the link. - -If there is already a link at point, this command will allow you to edit -link and description parts. - -With a `\\[universal-argument]' prefix, prompts for a file to link to. The file name can be -selected using completion. The path to the file will be relative to the -current directory if the file is in the current directory or a subdirectory. -Otherwise, the link will be the absolute path as completed in the minibuffer -\(i.e. normally ~/path/to/file). You can configure this behavior using the -option `org-link-file-path-type'. - -With a `\\[universal-argument] \\[universal-argument]' prefix, enforce an absolute path even if the file is in -the current directory or below. - -A `\\[universal-argument] \\[universal-argument] \\[universal-argument]' prefix negates `org-link-keep-stored-after-insertion'. - -If the LINK-LOCATION parameter is non-nil, this value will be used as -the link location instead of reading one interactively. - -If the DESCRIPTION parameter is non-nil, this value will be used -as the default description. If not, and the chosen link type has -a non-nil `:insert-description' parameter, that is used to -generate a description as described in `org-link-parameters' -docstring. Otherwise, if `org-link-make-description-function' is -non-nil, this function will be called with the link target, and -the result will be the default link description. When called -non-interactively, don't allow to edit the default description. - -\(fn &optional COMPLETE-FILE LINK-LOCATION DESCRIPTION)" t nil) - -(autoload 'org-insert-all-links "ol" "\ -Insert all links in `org-stored-links'. -When a universal prefix, do not delete the links from `org-stored-links'. -When `ARG' is a number, insert the last N link(s). -`PRE' and `POST' are optional arguments to define a string to -prepend or to append. +Dispatch to the appropriate function to store a link to an IRC session. -\(fn ARG &optional PRE POST)" t nil) - -(autoload 'org-insert-last-stored-link "ol" "\ -Insert the last link stored in `org-stored-links'. +(fn &optional INTERACTIVE?)") -\(fn ARG)" t nil) - -(autoload 'org-insert-link-global "ol" "\ -Insert a link like Org mode does. -This command can be called in any mode to insert a link in Org syntax." t nil) - -(autoload 'org-update-radio-target-regexp "ol" "\ -Find all radio targets in this file and update the regular expression. -Also refresh fontification if needed." t nil) - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ol" '("org-"))) - -;;;*** -;;;### (autoloads nil "org-agenda" "org-agenda.el" (0 0 0 0)) -;;; Generated autoloads from org-agenda.el - -(autoload 'org-toggle-sticky-agenda "org-agenda" "\ -Toggle `org-agenda-sticky'. - -\(fn &optional ARG)" t nil) - -(autoload 'org-agenda "org-agenda" "\ -Dispatch agenda commands to collect entries to the agenda buffer. -Prompts for a command to execute. Any prefix arg will be passed -on to the selected command. The default selections are: - -a Call `org-agenda-list' to display the agenda for current day or week. -t Call `org-todo-list' to display the global todo list. -T Call `org-todo-list' to display the global todo list, select only - entries with a specific TODO keyword (the user gets a prompt). -m Call `org-tags-view' to display headlines with tags matching - a condition (the user is prompted for the condition). -M Like `m', but select only TODO entries, no ordinary headlines. -e Export views to associated files. -s Search entries for keywords. -S Search entries for keywords, only with TODO keywords. -/ Multi occur across all agenda files and also files listed - in `org-agenda-text-search-extra-files'. -< Restrict agenda commands to buffer, subtree, or region. - Press several times to get the desired effect. -> Remove a previous restriction. -# List \"stuck\" projects. -! Configure what \"stuck\" means. -C Configure custom agenda commands. - -More commands can be added by configuring the variable -`org-agenda-custom-commands'. In particular, specific tags and TODO keyword -searches can be pre-defined in this way. - -If the current buffer is in Org mode and visiting a file, you can also -first press `<' once to indicate that the agenda should be temporarily -\(until the next use of `\\[org-agenda]') restricted to the current file. -Pressing `<' twice means to restrict to the current subtree or region -\(if active). - -\(fn &optional ARG KEYS RESTRICTION)" t nil) - -(autoload 'org-batch-agenda "org-agenda" "\ -Run an agenda command in batch mode and send the result to STDOUT. -If CMD-KEY is a string of length 1, it is used as a key in -`org-agenda-custom-commands' and triggers this command. If it is a -longer string it is used as a tags/todo match string. -Parameters are alternating variable names and values that will be bound -before running the agenda command. - -\(fn CMD-KEY &rest PARAMETERS)" nil t) - -(autoload 'org-batch-agenda-csv "org-agenda" "\ -Run an agenda command in batch mode and send the result to STDOUT. -If CMD-KEY is a string of length 1, it is used as a key in -`org-agenda-custom-commands' and triggers this command. If it is a -longer string it is used as a tags/todo match string. -Parameters are alternating variable names and values that will be bound -before running the agenda command. - -The output gives a line for each selected agenda item. Each -item is a list of comma-separated values, like this: - -category,head,type,todo,tags,date,time,extra,priority-l,priority-n - -category The category of the item -head The headline, without TODO kwd, TAGS and PRIORITY -type The type of the agenda entry, can be - todo selected in TODO match - tagsmatch selected in tags match - diary imported from diary - deadline a deadline on given date - scheduled scheduled on given date - timestamp entry has timestamp on given date - closed entry was closed on given date - upcoming-deadline warning about deadline - past-scheduled forwarded scheduled item - block entry has date block including g. date -todo The todo keyword, if any -tags All tags including inherited ones, separated by colons -date The relevant date, like 2007-2-14 -time The time, like 15:00-16:50 -extra String with extra planning info -priority-l The priority letter if any was given -priority-n The computed numerical priority -agenda-day The day in the agenda where this is listed - -\(fn CMD-KEY &rest PARAMETERS)" nil t) - -(autoload 'org-store-agenda-views "org-agenda" "\ -Store agenda views. - -\(fn &rest PARAMETERS)" t nil) - -(autoload 'org-batch-store-agenda-views "org-agenda" "\ -Run all custom agenda commands that have a file argument. - -\(fn &rest PARAMETERS)" nil t) - -(autoload 'org-agenda-list "org-agenda" "\ -Produce a daily/weekly view from all files in variable `org-agenda-files'. -The view will be for the current day or week, but from the overview buffer -you will be able to go to other days/weeks. - -With a numeric prefix argument in an interactive call, the agenda will -span ARG days. Lisp programs should instead specify SPAN to change -the number of days. SPAN defaults to `org-agenda-span'. - -START-DAY defaults to TODAY, or to the most recent match for the weekday -given in `org-agenda-start-on-weekday'. - -When WITH-HOUR is non-nil, only include scheduled and deadline -items if they have an hour specification like [h]h:mm. - -\(fn &optional ARG START-DAY SPAN WITH-HOUR)" t nil) - -(autoload 'org-search-view "org-agenda" "\ -Show all entries that contain a phrase or words or regular expressions. - -With optional prefix argument TODO-ONLY, only consider entries that are -TODO entries. The argument STRING can be used to pass a default search -string into this function. If EDIT-AT is non-nil, it means that the -user should get a chance to edit this string, with cursor at position -EDIT-AT. - -The search string can be viewed either as a phrase that should be found as -is, or it can be broken into a number of snippets, each of which must match -in a Boolean way to select an entry. The default depends on the variable -`org-agenda-search-view-always-boolean'. -Even if this is turned off (the default) you can always switch to -Boolean search dynamically by preceding the first word with \"+\" or \"-\". - -The default is a direct search of the whole phrase, where each space in -the search string can expand to an arbitrary amount of whitespace, -including newlines. - -If using a Boolean search, the search string is split on whitespace and -each snippet is searched separately, with logical AND to select an entry. -Words prefixed with a minus must *not* occur in the entry. Words without -a prefix or prefixed with a plus must occur in the entry. Matching is -case-insensitive. Words are enclosed by word delimiters (i.e. they must -match whole words, not parts of a word) if -`org-agenda-search-view-force-full-words' is set (default is nil). - -Boolean search snippets enclosed by curly braces are interpreted as -regular expressions that must or (when preceded with \"-\") must not -match in the entry. Snippets enclosed into double quotes will be taken -as a whole, to include whitespace. - -- If the search string starts with an asterisk, search only in headlines. -- If (possibly after the leading star) the search string starts with an - exclamation mark, this also means to look at TODO entries only, an effect - that can also be achieved with a prefix argument. -- If (possibly after star and exclamation mark) the search string starts - with a colon, this will mean that the (non-regexp) snippets of the - Boolean search must match as full words. - -This command searches the agenda files, and in addition the files -listed in `org-agenda-text-search-extra-files' unless a restriction lock -is active. - -\(fn &optional TODO-ONLY STRING EDIT-AT)" t nil) - -(autoload 'org-todo-list "org-agenda" "\ -Show all (not done) TODO entries from all agenda files in a single list. -The prefix arg can be used to select a specific TODO keyword and limit -the list to these. When using `\\[universal-argument]', you will be prompted -for a keyword. A numeric prefix directly selects the Nth keyword in -`org-todo-keywords-1'. - -\(fn &optional ARG)" t nil) - -(autoload 'org-tags-view "org-agenda" "\ -Show all headlines for all `org-agenda-files' matching a TAGS criterion. -The prefix arg TODO-ONLY limits the search to TODO entries. - -\(fn &optional TODO-ONLY MATCH)" t nil) - -(autoload 'org-agenda-list-stuck-projects "org-agenda" "\ -Create agenda view for projects that are stuck. -Stuck projects are project that have no next actions. For the definitions -of what a project is and how to check if it stuck, customize the variable -`org-stuck-projects'. - -\(fn &rest IGNORE)" t nil) - -(autoload 'org-diary "org-agenda" "\ -Return diary information from org files. -This function can be used in a \"sexp\" diary entry in the Emacs calendar. -It accesses org files and extracts information from those files to be -listed in the diary. The function accepts arguments specifying what -items should be listed. For a list of arguments allowed here, see the -variable `org-agenda-entry-types'. - -The call in the diary file should look like this: - - &%%(org-diary) ~/path/to/some/orgfile.org - -Use a separate line for each org file to check. Or, if you omit the file name, -all files listed in `org-agenda-files' will be checked automatically: - - &%%(org-diary) - -If you don't give any arguments (as in the example above), the default value -of `org-agenda-entry-types' is used: (:deadline :scheduled :timestamp :sexp). -So the example above may also be written as - - &%%(org-diary :deadline :timestamp :sexp :scheduled) - -The function expects the lisp variables `entry' and `date' to be provided -by the caller, because this is how the calendar works. Don't use this -function from a program - use `org-agenda-get-day-entries' instead. - -\(fn &rest ARGS)" nil nil) - -(autoload 'org-agenda-check-for-timestamp-as-reason-to-ignore-todo-item "org-agenda" "\ -Do we have a reason to ignore this TODO entry because it has a time stamp? - -\(fn &optional END)" nil nil) - -(autoload 'org-agenda-set-restriction-lock "org-agenda" "\ -Set restriction lock for agenda to current subtree or file. -When in a restricted subtree, remove it. - -The restriction will span over the entire file if TYPE is `file', -or if TYPE is (4), or if the cursor is before the first headline -in the file. Otherwise, only apply the restriction to the current -subtree. - -\(fn &optional TYPE)" t nil) - -(autoload 'org-calendar-goto-agenda "org-agenda" "\ -Compute the Org agenda for the calendar date displayed at the cursor. -This is a command that has to be installed in `calendar-mode-map'." t nil) - -(autoload 'org-agenda-to-appt "org-agenda" "\ -Activate appointments found in `org-agenda-files'. - -With a `\\[universal-argument]' prefix, refresh the list of appointments. - -If FILTER is t, interactively prompt the user for a regular -expression, and filter out entries that don't match it. - -If FILTER is a string, use this string as a regular expression -for filtering entries out. - -If FILTER is a function, filter out entries against which -calling the function returns nil. This function takes one -argument: an entry from `org-agenda-get-day-entries'. - -FILTER can also be an alist with the car of each cell being -either `headline' or `category'. For example: - - ((headline \"IMPORTANT\") - (category \"Work\")) - -will only add headlines containing IMPORTANT or headlines -belonging to the \"Work\" category. - -ARGS are symbols indicating what kind of entries to consider. -By default `org-agenda-to-appt' will use :deadline*, :scheduled* -\(i.e., deadlines and scheduled items with a hh:mm specification) -and :timestamp entries. See the docstring of `org-diary' for -details and examples. - -If an entry has a APPT_WARNTIME property, its value will be used -to override `appt-message-warning-time'. +;;; Generated autoloads from org.el -\(fn &optional REFRESH FILTER &rest ARGS)" t nil) +(autoload 'org-dynamic-block-define "org" "\ +Define dynamic block TYPE with FUNC. +TYPE is a string. FUNC is the function creating the dynamic +block of such type. FUNC must be able to accept zero arguments. -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "org-agenda" '("org-"))) +(fn TYPE FUNC)") -;;;*** -;;;### (autoloads nil "org-archive" "org-archive.el" "4b4cc0b3beac33f17438945dd42f7625") ;;; Generated autoloads from org-archive.el (autoload 'org-add-archive-files "org-archive" "\ -Splice the archive files into the list of files. +Splice the archive FILES into the list of files. This implies visiting all these files and finding out what the archive file is. -\(fn FILES)" nil nil) - +(fn FILES)") (autoload 'org-archive-subtree "org-archive" "\ Move the current subtree to the archive. The archive can be a certain top-level heading in the current @@ -1297,8 +413,7 @@ cursor is not at a headline when these commands are called, try all level 1 trees. If the cursor is on a headline, only try the direct children of this heading. -\(fn &optional FIND-DONE)" t nil) - +(fn &optional FIND-DONE)" t) (autoload 'org-archive-to-archive-sibling "org-archive" "\ Archive the current heading by moving it under the archive sibling. @@ -1306,40 +421,27 @@ The archive sibling is a sibling of the heading with the heading name `org-archive-sibling-heading' and an `org-archive-tag' tag. If this sibling does not exist, it will be created at the end of the subtree. -Archiving time is retained in the ARCHIVE_TIME node property." t nil) - +Archiving time is retained in the ARCHIVE_TIME node property." t) (autoload 'org-toggle-archive-tag "org-archive" "\ Toggle the archive tag for the current headline. -With prefix ARG, check all children of current headline and offer tagging -the children that do not contain any open TODO items. - -\(fn &optional FIND-DONE)" t nil) +With prefix argument FIND-DONE, check all children of current headline +and offer tagging the children that do not contain any open TODO +items. +(fn &optional FIND-DONE)" t) (autoload 'org-archive-subtree-default "org-archive" "\ Archive the current subtree with the default command. -This command is set with the variable `org-archive-default-command'." t nil) - +This command is set with the variable `org-archive-default-command'." t) (autoload 'org-archive-subtree-default-with-confirmation "org-archive" "\ Archive the current subtree with the default command. -This command is set with the variable `org-archive-default-command'." t nil) - -;;;### (autoloads "actual autoloads are elsewhere" "org-archive" -;;;;;; "org-archive.el" (0 0 0 0)) -;;; Generated autoloads from org-archive.el - -(register-definition-prefixes "org-archive" '("org-a")) +This command is set with the variable `org-archive-default-command'." t) -;;;*** - -;;;*** -;;;### (autoloads nil "org-attach" "org-attach.el" "cc5d339d2aa5b1fe72d5666f464342d6") ;;; Generated autoloads from org-attach.el (autoload 'org-attach "org-attach" "\ The dispatcher for attachment commands. -Shows a list of commands and prompts for another key to execute a command." t nil) - +Shows a list of commands and prompts for another key to execute a command." t) (autoload 'org-attach-dir "org-attach" "\ Return the directory associated with the current outline node. First check for DIR property, then ID property. @@ -1358,129 +460,36 @@ filesystem. If no attachment directory can be derived, return nil. -\(fn &optional CREATE-IF-NOT-EXISTS-P NO-FS-CHECK)" nil nil) - -(autoload 'org-attach-dired-to-subtree "org-attach" "\ -Attach FILES marked or current file in `dired' to subtree in other window. -Takes the method given in `org-attach-method' for the attach action. -Precondition: Point must be in a `dired' buffer. -Idea taken from `gnus-dired-attach'. - -\(fn FILES)" t nil) - -;;;### (autoloads "actual autoloads are elsewhere" "org-attach" "org-attach.el" -;;;;;; (0 0 0 0)) -;;; Generated autoloads from org-attach.el - -(register-definition-prefixes "org-attach" '("org-attach-")) - -;;;*** - -;;;*** - -;;;### (autoloads nil "org-attach-git" "org-attach-git.el" (0 0 0 -;;;;;; 0)) -;;; Generated autoloads from org-attach-git.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "org-attach-git" '("org-attach-git-"))) - -;;;*** - -;;;### (autoloads nil "org-attach" "org-attach.el" (0 0 0 0)) -;;; Generated autoloads from org-attach.el - -(autoload 'org-attach "org-attach" "\ -The dispatcher for attachment commands. -Shows a list of commands and prompts for another key to execute a command." t nil) - -(autoload 'org-attach-dir "org-attach" "\ -Return the directory associated with the current outline node. -First check for DIR property, then ID property. -`org-attach-use-inheritance' determines whether inherited -properties also will be considered. - -If an ID property is found the default mechanism using that ID -will be invoked to access the directory for the current entry. -Note that this method returns the directory as declared by ID or -DIR even if the directory doesn't exist in the filesystem. - -If CREATE-IF-NOT-EXISTS-P is non-nil, `org-attach-dir-get-create' -is run. If NO-FS-CHECK is non-nil, the function returns the path -to the attachment even if it has not yet been initialized in the -filesystem. - -If no attachment directory can be derived, return nil. - -\(fn &optional CREATE-IF-NOT-EXISTS-P NO-FS-CHECK)" nil nil) - +(fn &optional CREATE-IF-NOT-EXISTS-P NO-FS-CHECK)") (autoload 'org-attach-dired-to-subtree "org-attach" "\ Attach FILES marked or current file in `dired' to subtree in other window. Takes the method given in `org-attach-method' for the attach action. Precondition: Point must be in a `dired' buffer. Idea taken from `gnus-dired-attach'. -\(fn FILES)" t nil) +(fn FILES)" t) -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "org-attach" '("org-attach-"))) - -;;;*** -;;;### (autoloads nil "org-capture" "org-capture.el" (0 0 0 0)) -;;; Generated autoloads from org-capture.el - -(autoload 'org-capture-string "org-capture" "\ -Capture STRING with the template selected by KEYS. - -\(fn STRING &optional KEYS)" t nil) - -(autoload 'org-capture "org-capture" "\ -Capture something. -\\ -This will let you select a template from `org-capture-templates', and -then file the newly captured information. The text is immediately -inserted at the target location, and an indirect buffer is shown where -you can edit it. Pressing `\\[org-capture-finalize]' brings you back to the previous -state of Emacs, so that you can continue your work. - -When called interactively with a `\\[universal-argument]' prefix argument GOTO, don't -capture anything, just go to the file/headline where the selected -template stores its notes. - -With a `\\[universal-argument] \\[universal-argument]' prefix argument, go to the last note stored. - -When called with a `C-0' (zero) prefix, insert a template at point. - -When called with a `C-1' (one) prefix, force prompting for a date when -a datetree entry is made. - -ELisp programs can set KEYS to a string associated with a template -in `org-capture-templates'. In this case, interactive selection -will be bypassed. - -If `org-capture-use-agenda-date' is non-nil, capturing from the -agenda will use the date at point as the default date. Then, a -`C-1' prefix will tell the capture process to use the HH:MM time -of the day at point (if any) or the current HH:MM time. - -\(fn &optional GOTO KEYS)" t nil) - -(autoload 'org-capture-import-remember-templates "org-capture" "\ -Set `org-capture-templates' to be similar to `org-remember-templates'." t nil) +;;; Generated autoloads from org-clock.el -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "org-capture" '("org-capture-"))) +(autoload 'org-clock-modify-effort-estimate "org-clock" "\ +Add to or set the effort estimate of the item currently being clocked. +VALUE can be a number of minutes, or a string with format hh:mm or mm. +When the string starts with a + or a - sign, the current value of the effort +property will be changed by that amount. If the effort value is expressed +as an unit defined in `org-duration-units' (e.g. \"3h\"), the modified +value will be converted to a hh:mm duration. -;;;*** - -;;;### (autoloads nil "org-clock" "org-clock.el" "e31e5d99e00a0457f233d33faf55ca15") -;;; Generated autoloads from org-clock.el +This command will update the \"Effort\" property of the currently +clocked item, and the value displayed in the mode line. +(fn &optional VALUE)" t) (autoload 'org-resolve-clocks "org-clock" "\ Resolve all currently open Org clocks. If `only-dangling-p' is non-nil, only ask to resolve dangling -\(i.e., not currently open and valid) clocks. - -\(fn &optional ONLY-DANGLING-P PROMPT-FN LAST-VALID)" t nil) +(i.e., not currently open and valid) clocks. +(fn &optional ONLY-DANGLING-P PROMPT-FN LAST-VALID)" t) (autoload 'org-clock-in "org-clock" "\ Start the clock on the current item. @@ -1497,10 +506,8 @@ When SELECT is `\\[universal-argument] \\[universal-argument] \\[universal-argum time as the start time. See `org-clock-continuously' to make this the default behavior. -\(fn &optional SELECT START-TIME)" t nil) - -(autoload 'org-clock-toggle-auto-clockout "org-clock" nil t nil) - +(fn &optional SELECT START-TIME)" t) +(autoload 'org-clock-toggle-auto-clockout "org-clock" nil t) (autoload 'org-clock-in-last "org-clock" "\ Clock in the last closed clocked item. When already clocking in, send a warning. @@ -1512,30 +519,25 @@ With three universal prefix arguments, interactively prompt for a todo state to switch to, overriding the existing value `org-clock-in-switch-to-state'. -\(fn &optional ARG)" t nil) - +(fn &optional ARG)" t) (autoload 'org-clock-out "org-clock" "\ Stop the currently running clock. Throw an error if there is no running clock and FAIL-QUIETLY is nil. With a universal prefix, prompt for a state to switch the clocked out task to, overriding the existing value of `org-clock-out-switch-to-state'. -\(fn &optional SWITCH-TO-STATE FAIL-QUIETLY AT-TIME)" t nil) - +(fn &optional SWITCH-TO-STATE FAIL-QUIETLY AT-TIME)" t) (autoload 'org-clock-cancel "org-clock" "\ -Cancel the running clock by removing the start timestamp." t nil) - +Cancel the running clock by removing the start timestamp." t) (autoload 'org-clock-goto "org-clock" "\ Go to the currently clocked-in entry, or to the most recently clocked one. With prefix arg SELECT, offer recently clocked tasks for selection. -\(fn &optional SELECT)" t nil) - +(fn &optional SELECT)" t) (autoload 'org-clock-sum-today "org-clock" "\ Sum the times for each subtree for today. -\(fn &optional HEADLINE-FILTER)" nil nil) - +(fn &optional HEADLINE-FILTER)") (autoload 'org-clock-sum "org-clock" "\ Sum the times for each subtree. Puts the resulting times in minutes as a text property on each headline. @@ -1545,8 +547,7 @@ each headline in the time range with point at the headline. Headlines for which HEADLINE-FILTER returns nil are excluded from the clock summation. PROPNAME lets you set a custom text property instead of :org-clock-minutes. -\(fn &optional TSTART TEND HEADLINE-FILTER PROPNAME)" nil nil) - +(fn &optional TSTART TEND HEADLINE-FILTER PROPNAME)") (autoload 'org-clock-display "org-clock" "\ Show subtree times in the entire buffer. @@ -1561,27 +562,23 @@ echo area. Use `\\[org-clock-remove-overlays]' to remove the subtree times. -\(fn &optional ARG)" t nil) - +(fn &optional ARG)" t) (autoload 'org-clock-remove-overlays "org-clock" "\ Remove the occur highlights from the buffer. If NOREMOVE is nil, remove this function from the `before-change-functions' in the current buffer. -\(fn &optional BEG END NOREMOVE)" t nil) - +(fn &optional BEG END NOREMOVE)" t) (autoload 'org-clock-out-if-current "org-clock" "\ Clock out if the current entry contains the running clock. This is used to stop the clock after a TODO entry is marked DONE, -and is only done if the variable `org-clock-out-when-done' is not nil." nil nil) - +and is only done if the variable `org-clock-out-when-done' is not nil.") (autoload 'org-clock-get-clocktable "org-clock" "\ Get a formatted clocktable with parameters according to PROPS. The table is created in a temporary buffer, fully formatted and fontified, and then returned. -\(fn &rest PROPS)" nil nil) - +(fn &rest PROPS)") (autoload 'org-clock-report "org-clock" "\ Update or create a table containing a report about clocked time. @@ -1599,10 +596,8 @@ heading). When called with a prefix argument, move to the first clock table in the buffer and update it. -\(fn &optional ARG)" t nil) - +(fn &optional ARG)" t) (eval-after-load 'org '(progn (org-dynamic-block-define "clocktable" #'org-clock-report))) - (autoload 'org-clocktable-shift "org-clock" "\ Try to shift the :block date of the clocktable at point. Point must be in the #+BEGIN: line of a clocktable, or this function @@ -1613,35 +608,21 @@ push it toward the future. N is the number of shift steps to take. The size of the step depends on the currently selected interval size. -\(fn DIR N)" nil nil) - +(fn DIR N)") (autoload 'org-dblock-write:clocktable "org-clock" "\ Write the standard clocktable. -\(fn PARAMS)" nil nil) - +(fn PARAMS)") (autoload 'org-clock-update-time-maybe "org-clock" "\ If this is a CLOCK line, update it and return t. -Otherwise, return nil." t nil) - -;;;### (autoloads "actual autoloads are elsewhere" "org-clock" "org-clock.el" -;;;;;; (0 0 0 0)) -;;; Generated autoloads from org-clock.el - -(register-definition-prefixes "org-clock" '("org-")) - -;;;*** +Otherwise, return nil." t) -;;;*** -;;;### (autoloads nil "org-colview" "org-colview.el" "689f085e9357f5d901d7f71be888f28b") ;;; Generated autoloads from org-colview.el (autoload 'org-columns-remove-overlays "org-colview" "\ -Remove all currently active column overlays." t nil) - -(autoload 'org-columns-get-format-and-top-level "org-colview" nil nil nil) - +Remove all currently active column overlays." t) +(autoload 'org-columns-get-format-and-top-level "org-colview") (autoload 'org-columns "org-colview" "\ Turn on column view on an Org mode file. @@ -1653,15 +634,13 @@ turn on column view for the whole buffer unconditionally. When COLUMNS-FMT-STRING is non-nil, use it as the column format. -\(fn &optional GLOBAL COLUMNS-FMT-STRING)" t nil) - +(fn &optional GLOBAL COLUMNS-FMT-STRING)" t) (autoload 'org-columns-compute "org-colview" "\ Summarize the values of PROPERTY hierarchically. Also update existing values for PROPERTY according to the first column specification. -\(fn PROPERTY)" t nil) - +(fn PROPERTY)" t) (autoload 'org-dblock-write:columnview "org-colview" "\ Write the column view table. @@ -1713,138 +692,36 @@ PARAMS is a property list of parameters: When non-nil, make each column a column group to enforce vertical lines. -\(fn PARAMS)" nil nil) +`:link' -(autoload 'org-columns-insert-dblock "org-colview" "\ -Create a dynamic block capturing a column view table." t nil) - -(eval-after-load 'org '(progn (org-dynamic-block-define "columnview" #'org-columns-insert-dblock))) + Link the item headlines in the table to their origins. -(autoload 'org-agenda-columns "org-colview" "\ -Turn on or update column view in the agenda." t nil) - -;;;### (autoloads "actual autoloads are elsewhere" "org-colview" -;;;;;; "org-colview.el" (0 0 0 0)) -;;; Generated autoloads from org-colview.el +`:formatter' -(register-definition-prefixes "org-colview" '("org-")) + A function to format the data and insert it into the + buffer. Overrides the default formatting function set in + `org-columns-dblock-formatter'. -;;;*** +(fn PARAMS)") +(autoload 'org-columns-insert-dblock "org-colview" "\ +Create a dynamic block capturing a column view table." t) +(eval-after-load 'org '(progn (org-dynamic-block-define "columnview" #'org-columns-insert-dblock))) +(autoload 'org-agenda-columns "org-colview" "\ +Turn on or update column view in the agenda." t) -;;;*** -;;;### (autoloads nil "org-compat" "org-compat.el" "af9401b3a08e590f4011c3f7974c6ed7") ;;; Generated autoloads from org-compat.el +(autoload 'org-list-of-strings-p "org-compat" "\ +Return t if OBJECT is nil or a list of strings. + +(fn OBJECT)") +(function-put 'org-list-of-strings-p 'pure 't) +(function-put 'org-list-of-strings-p 'side-effect-free 'error-free) (autoload 'org-check-version "org-compat" "\ Try very hard to provide sensible version strings." nil t) - -;;;### (autoloads "actual autoloads are elsewhere" "org-compat" "org-compat.el" -;;;;;; (0 0 0 0)) -;;; Generated autoloads from org-compat.el - -(register-definition-prefixes "org-compat" '("org-" "outline-")) - -;;;*** - -;;;*** - -;;;### (autoloads nil "org-crypt" "org-crypt.el" (0 0 0 0)) -;;; Generated autoloads from org-crypt.el - -(autoload 'org-encrypt-entry "org-crypt" "\ -Encrypt the content of the current headline." t nil) - -(autoload 'org-decrypt-entry "org-crypt" "\ -Decrypt the content of the current headline." t nil) - -(autoload 'org-encrypt-entries "org-crypt" "\ -Encrypt all top-level entries in the current buffer." t nil) - -(autoload 'org-decrypt-entries "org-crypt" "\ -Decrypt all entries in the current buffer." t nil) - -(autoload 'org-crypt-use-before-save-magic "org-crypt" "\ -Add a hook to automatically encrypt entries before a file is saved to disk." nil nil) - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "org-crypt" '("org-"))) - -;;;*** - -;;;### (autoloads nil "org-ctags" "org-ctags.el" (0 0 0 0)) -;;; Generated autoloads from org-ctags.el -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "org-ctags" '("org-"))) - -;;;*** - -;;;### (autoloads nil "org-cycle" "org-cycle.el" (0 0 0 0)) -;;; Generated autoloads from org-cycle.el - -(autoload 'org-cycle "org-cycle" "\ -TAB-action and visibility cycling for Org mode. - -This is the command invoked in Org mode by the `TAB' key. Its main -purpose is outline visibility cycling, but it also invokes other actions -in special contexts. - -When this function is called with a `\\[universal-argument]' prefix, rotate the entire -buffer through 3 states (global cycling) - 1. OVERVIEW: Show only top-level headlines. - 2. CONTENTS: Show all headlines of all levels, but no body text. - 3. SHOW ALL: Show everything. - -With a `\\[universal-argument] \\[universal-argument]' prefix argument, switch to the startup visibility, -determined by the variable `org-startup-folded', and by any VISIBILITY -properties in the buffer. - -With a `\\[universal-argument] \\[universal-argument] \\[universal-argument]' prefix argument, show the entire buffer, including -any drawers. - -When inside a table, re-align the table and move to the next field. - -When point is at the beginning of a headline, rotate the subtree started -by this line through 3 different states (local cycling) - 1. FOLDED: Only the main headline is shown. - 2. CHILDREN: The main headline and the direct children are shown. - From this state, you can move to one of the children - and zoom in further. - 3. SUBTREE: Show the entire subtree, including body text. -If there is no subtree, switch directly from CHILDREN to FOLDED. - -When point is at the beginning of an empty headline and the variable -`org-cycle-level-after-item/entry-creation' is set, cycle the level -of the headline by demoting and promoting it to likely levels. This -speeds up creation document structure by pressing `TAB' once or several -times right after creating a new headline. - -When there is a numeric prefix, go up to a heading with level ARG, do -a `show-subtree' and return to the previous cursor position. If ARG -is negative, go up that many levels. - -When point is not at the beginning of a headline, execute the global -binding for `TAB', which is re-indenting the line. See the option -`org-cycle-emulate-tab' for details. - -As a special case, if point is at the very beginning of the buffer, if -there is no headline there, and if the variable `org-cycle-global-at-bob' -is non-nil, this function acts as if called with prefix argument (`\\[universal-argument] TAB', -same as `S-TAB') also when called without prefix argument. - -\(fn &optional ARG)" t nil) - -(autoload 'org-cycle-global "org-cycle" "\ -Cycle the global visibility. For details see `org-cycle'. -With `\\[universal-argument]' prefix ARG, switch to startup visibility. -With a numeric prefix, show all headlines up to that level. - -\(fn &optional ARG)" t nil) - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "org-cycle" '("org-cycle-"))) - -;;;*** -;;;### (autoloads nil "org-datetree" "org-datetree.el" "7c3a6fa30ca4d0e7ead95661f1df4bdc") ;;; Generated autoloads from org-datetree.el (autoload 'org-datetree-find-date-create "org-datetree" "\ @@ -1854,8 +731,7 @@ When it is nil, the buffer will be widened to make sure an existing date tree can be found. If it is the symbol `subtree-at-point', then the tree will be built under the headline at point. -\(fn D &optional KEEP-RESTRICTION)" nil nil) - +(fn D &optional KEEP-RESTRICTION)") (autoload 'org-datetree-find-month-create "org-datetree" "\ Find or create a month entry for date D. Compared to `org-datetree-find-date-create' this function creates @@ -1865,8 +741,7 @@ When it is nil, the buffer will be widened to make sure an existing date tree can be found. If it is the symbol `subtree-at-point', then the tree will be built under the headline at point. -\(fn D &optional KEEP-RESTRICTION)" nil nil) - +(fn D &optional KEEP-RESTRICTION)") (autoload 'org-datetree-find-iso-week-create "org-datetree" "\ Find or create an ISO week entry for date D. Compared to `org-datetree-find-date-create' this function creates @@ -1875,29 +750,17 @@ When it is nil, the buffer will be widened to make sure an existing date tree can be found. If it is the symbol `subtree-at-point', then the tree will be built under the headline at point. -\(fn D &optional KEEP-RESTRICTION)" nil nil) - -;;;### (autoloads "actual autoloads are elsewhere" "org-datetree" -;;;;;; "org-datetree.el" (0 0 0 0)) -;;; Generated autoloads from org-datetree.el - -(register-definition-prefixes "org-datetree" '("org-datetree-")) - -;;;*** +(fn D &optional KEEP-RESTRICTION)") -;;;*** -;;;### (autoloads nil "org-duration" "org-duration.el" "d34da613b5267f7586e1f59d20c41523") ;;; Generated autoloads from org-duration.el (autoload 'org-duration-set-regexps "org-duration" "\ -Set duration related regexps." t nil) - +Set duration related regexps." t) (autoload 'org-duration-p "org-duration" "\ Non-nil when string S is a time duration. -\(fn S)" nil nil) - +(fn S)") (autoload 'org-duration-to-minutes "org-duration" "\ Return number of minutes of DURATION string. @@ -1910,8 +773,7 @@ translated into 0.0. Return value as a float. Raise an error if duration format is not recognized. -\(fn DURATION &optional CANONICAL)" nil nil) - +(fn DURATION &optional CANONICAL)") (autoload 'org-duration-from-minutes "org-duration" "\ Return duration string for a given number of MINUTES. @@ -1923,8 +785,7 @@ When optional argument CANONICAL is non-nil, ignore Raise an error if expected format is unknown. -\(fn MINUTES &optional FMT CANONICAL)" nil nil) - +(fn MINUTES &optional FMT CANONICAL)") (autoload 'org-duration-h:mm-only-p "org-duration" "\ Non-nil when every duration in TIMES has \"H:MM\" or \"H:MM:SS\" format. @@ -1935,34 +796,21 @@ Return nil if any duration is expressed with units, as defined in with \"H:MM:SS\" format, return `h:mm:ss'. Otherwise, return `h:mm'. -\(fn TIMES)" nil nil) - -;;;### (autoloads "actual autoloads are elsewhere" "org-duration" -;;;;;; "org-duration.el" (0 0 0 0)) -;;; Generated autoloads from org-duration.el - -(register-definition-prefixes "org-duration" '("org-duration-")) - -;;;*** +(fn TIMES)") -;;;*** -;;;### (autoloads nil "org-element" "org-element.el" "a783c22d33de48141d38eac1c2c073e9") ;;; Generated autoloads from org-element.el (autoload 'org-element-update-syntax "org-element" "\ -Update parser internals." t nil) - +Update parser internals." t) (autoload 'org-element-interpret-data "org-element" "\ Interpret DATA as Org syntax. DATA is a parse tree, an element, an object or a secondary string to interpret. Return Org syntax as a string. -\(fn DATA)" nil nil) - +(fn DATA)") (defvar org-element-use-cache t "\ Non-nil when Org parser should cache its results.") - (autoload 'org-element-cache-reset "org-element" "\ Reset cache in current buffer. When optional argument ALL is non-nil, reset cache in all Org @@ -1970,16 +818,31 @@ buffers. When optional argument NO-PERSISTENCE is non-nil, do not try to update the cache persistence in the buffer. -\(fn &optional ALL NO-PERSISTENCE)" t nil) - +(fn &optional ALL NO-PERSISTENCE)" t) +(autoload 'org-element-cache-store-key "org-element" "\ +Store KEY with VALUE associated with EPOM - point, marker, or element. +The key can be retrieved as long as the element (provided or at point) +contents is not modified. +If optional argument ROBUST is non-nil, the key will be retained even +when the contents (children) of current element are modified. Only +non-robust element modifications (affecting the element properties +other then begin/end boundaries) will invalidate the key then. + +(fn EPOM KEY VALUE &optional ROBUST)") +(autoload 'org-element-cache-get-key "org-element" "\ +Get KEY associated with EPOM - point, marker, or element. +Return DEFAULT when KEY is not associated with EPOM. +The key can be retrieved as long as the element (provided or at point) +contents is not modified. + +(fn EPOM KEY &optional DEFAULT)") (autoload 'org-element-cache-refresh "org-element" "\ Refresh cache at position POS. -\(fn POS)" nil nil) - +(fn POS)") (autoload 'org-element-cache-map "org-element" "\ -Map all elements in current buffer with FUNC according to -GRANULARITY. Collect non-nil return values into result list. +Map all elements in current buffer with FUNC according to GRANULARITY. +Collect non-nil return values into result list. FUNC should accept a single argument - the element. @@ -2024,13 +887,15 @@ much better performance. Cached elements are supplied as the single argument of FUNC. Changes to elements made in FUNC will also alter the cache. -\(fn FUNC &key (GRANULARITY \\='headline+inlinetask) RESTRICT-ELEMENTS NEXT-RE FAIL-RE FROM-POS (TO-POS (point-max-marker)) AFTER-ELEMENT LIMIT-COUNT NARROW)" nil nil) - +(fn FUNC &key (GRANULARITY \\='headline+inlinetask) RESTRICT-ELEMENTS NEXT-RE FAIL-RE FROM-POS (TO-POS (point-max-marker)) AFTER-ELEMENT LIMIT-COUNT NARROW)") (autoload 'org-element-at-point "org-element" "\ -Determine closest element around point or POM. +Determine closest element around point or EPOM. + +When EPOM is an element, return it immediately. +Otherwise, determine element at EPOM marker or position. Only check cached element when CACHED-ONLY is non-nil and return nil -unconditionally when element at POM is not in cache. +unconditionally when element at EPOM is not in cache. Return value is a list like (TYPE PROPS) where TYPE is the type of the element and PROPS a plist of properties associated to the @@ -2049,15 +914,15 @@ instead of the first row. When point is at the end of the buffer, return the innermost element ending there. -\(fn &optional POM CACHED-ONLY)" nil nil) +This function may modify the match data. +(fn &optional EPOM CACHED-ONLY)") (defsubst org-element-at-point-no-context (&optional pom) "\ Quickly find element at point or POM. It is a faster version of `org-element-at-point' that is not -guaranteed to return correct `:parent' properties even when cache is -enabled." (or (org-element-at-point pom 'cached-only) (let (org-element-use-cache) (org-element-at-point pom)))) - +guaranteed to return cached element. `:parent' element may be +deferred and slow to retrieve." (or (org-element-at-point pom 'cached-only) (org-element-with-disabled-cache (org-element-at-point pom)))) (autoload 'org-element-context "org-element" "\ Return smallest element or object around point. @@ -2077,80 +942,31 @@ Optional argument ELEMENT, when non-nil, is the closest element containing point, as returned by `org-element-at-point'. Providing it allows for quicker computation. -\(fn &optional ELEMENT)" nil nil) - -;;;### (autoloads "actual autoloads are elsewhere" "org-element" -;;;;;; "org-element.el" (0 0 0 0)) -;;; Generated autoloads from org-element.el - -(register-definition-prefixes "org-element" '("org-element-")) - -;;;*** - -;;;*** - -;;;### (autoloads nil "org-entities" "org-entities.el" (0 0 0 0)) -;;; Generated autoloads from org-entities.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "org-entities" '("org-entit"))) - -;;;*** - -;;;### (autoloads nil "org-faces" "org-faces.el" (0 0 0 0)) -;;; Generated autoloads from org-faces.el +This function may modify match data. -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "org-faces" '("org-"))) +(fn &optional ELEMENT)") -;;;*** -;;;### (autoloads nil "org-feed" "org-feed.el" "6c97244792665a6679669d31a77ebe1a") ;;; Generated autoloads from org-feed.el (autoload 'org-feed-update-all "org-feed" "\ -Get inbox items from all feeds in `org-feed-alist'." t nil) - +Get inbox items from all feeds in `org-feed-alist'." t) (autoload 'org-feed-update "org-feed" "\ Get inbox items from FEED. FEED can be a string with an association in `org-feed-alist', or it can be a list structured like an entry in `org-feed-alist'. -\(fn FEED &optional RETRIEVE-ONLY)" t nil) - +(fn FEED &optional RETRIEVE-ONLY)" t) (autoload 'org-feed-goto-inbox "org-feed" "\ Go to the inbox that captures the feed named FEED. -\(fn FEED)" t nil) - +(fn FEED)" t) (autoload 'org-feed-show-raw-feed "org-feed" "\ Show the raw feed buffer of a feed. -\(fn FEED)" t nil) - -;;;### (autoloads "actual autoloads are elsewhere" "org-feed" "org-feed.el" -;;;;;; (0 0 0 0)) -;;; Generated autoloads from org-feed.el - -(register-definition-prefixes "org-feed" '("org-feed-")) - -;;;*** +(fn FEED)" t) -;;;*** -;;;### (autoloads nil "org-fold-core" "org-fold-core.el" (0 0 0 0)) -;;; Generated autoloads from org-fold-core.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "org-fold-core" '("org-fold-core-"))) - -;;;*** - -;;;### (autoloads nil "org-fold" "org-fold.el" (0 0 0 0)) -;;; Generated autoloads from org-fold.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "org-fold" '("org-fold-"))) - -;;;*** - -;;;### (autoloads nil "org-footnote" "org-footnote.el" "9c6cc18ed284b01aa6fddba387a0815b") ;;; Generated autoloads from org-footnote.el (autoload 'org-footnote-action "org-footnote" "\ @@ -2167,19 +983,9 @@ interactively if possible. With prefix arg SPECIAL, or when no footnote can be created, offer additional commands in a menu. -\(fn &optional SPECIAL)" t nil) - -;;;### (autoloads "actual autoloads are elsewhere" "org-footnote" -;;;;;; "org-footnote.el" (0 0 0 0)) -;;; Generated autoloads from org-footnote.el - -(register-definition-prefixes "org-footnote" '("org-footnote-")) - -;;;*** +(fn &optional SPECIAL)" t) -;;;*** -;;;### (autoloads nil "org-goto" "org-goto.el" "8c32558fc27a378a062451e76b0df6fa") ;;; Generated autoloads from org-goto.el (autoload 'org-goto-location "org-goto" "\ @@ -2187,8 +993,7 @@ Let the user select a location in current buffer. This function uses a recursive edit. It returns the selected position or nil. -\(fn &optional BUF HELP)" nil nil) - +(fn &optional BUF HELP)") (autoload 'org-goto "org-goto" "\ Look up a different location in the current file, keeping current visibility. @@ -2209,26 +1014,9 @@ in the indirect buffer and expose the headline hierarchy above. With a prefix argument, use the alternative interface: e.g., if `org-goto-interface' is `outline' use `outline-path-completion'. -\(fn &optional ALTERNATIVE-INTERFACE)" t nil) - -;;;### (autoloads "actual autoloads are elsewhere" "org-goto" "org-goto.el" -;;;;;; (0 0 0 0)) -;;; Generated autoloads from org-goto.el - -(register-definition-prefixes "org-goto" '("org-goto-")) - -;;;*** - -;;;*** - -;;;### (autoloads nil "org-habit" "org-habit.el" (0 0 0 0)) -;;; Generated autoloads from org-habit.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "org-habit" '("org-"))) +(fn &optional ALTERNATIVE-INTERFACE)" t) -;;;*** -;;;### (autoloads nil "org-id" "org-id.el" "01eea74fbef35af6d97400787dfa0765") ;;; Generated autoloads from org-id.el (autoload 'org-id-get-create "org-id" "\ @@ -2236,22 +1024,26 @@ Create an ID for the current entry and return it. If the entry already has an ID, just return it. With optional argument FORCE, force the creation of a new ID. -\(fn &optional FORCE)" t nil) - +(fn &optional FORCE)" t) (autoload 'org-id-copy "org-id" "\ Copy the ID of the entry at point to the kill ring. -Create an ID if necessary." t nil) - +Create an ID if necessary." t) (autoload 'org-id-get "org-id" "\ -Get the ID property of the entry at point-or-marker POM. -If POM is nil, refer to the entry at point. -If the entry does not have an ID, the function returns nil. -However, when CREATE is non-nil, create an ID if none is present already. -PREFIX will be passed through to `org-id-new'. -In any case, the ID of the entry is returned. +Get the ID of the entry at EPOM. -\(fn &optional POM CREATE PREFIX)" nil nil) +EPOM is an element, marker, or buffer position. If EPOM is nil, +refer to the entry at point. +If INHERIT is non-nil, ID properties inherited from parent +entries are considered. Otherwise, only ID properties on the +entry itself are considered. + +When CREATE is nil, return the ID of the entry if found, +otherwise nil. When CREATE is non-nil, create an ID if none has +been found, and return the new ID. PREFIX will be passed through +to `org-id-new'. + +(fn &optional EPOM CREATE PREFIX INHERIT)") (autoload 'org-id-get-with-outline-path-completion "org-id" "\ Use `outline-path-completion' to retrieve the ID of an entry. TARGETS may be a setting for `org-refile-targets' to define @@ -2259,27 +1051,23 @@ eligible headlines. When omitted, all headlines in the current file are eligible. This function returns the ID of the entry. If necessary, the ID is created. -\(fn &optional TARGETS)" nil nil) - +(fn &optional TARGETS)") (autoload 'org-id-get-with-outline-drilling "org-id" "\ Use an outline-cycling interface to retrieve the ID of an entry. This only finds entries in the current buffer, using `org-goto-location'. -It returns the ID of the entry. If necessary, the ID is created." nil nil) - +It returns the ID of the entry. If necessary, the ID is created.") (autoload 'org-id-goto "org-id" "\ Switch to the buffer containing the entry with id ID. Move the cursor to that entry in that buffer. -\(fn ID)" t nil) - +(fn ID)" t) (autoload 'org-id-find "org-id" "\ Return the location of the entry with the id ID. The return value is a cons cell (file-name . position), or nil if there is no entry with that ID. With optional argument MARKERP, return the position as a new marker. -\(fn ID &optional MARKERP)" nil nil) - +(fn ID &optional MARKERP)") (autoload 'org-id-new "org-id" "\ Create a new globally unique ID. @@ -2293,8 +1081,7 @@ prefix even if `org-id-prefix' specifies one. So a typical ID could look like \"Org:4nd91V40HI\". -\(fn &optional PREFIX)" nil nil) - +(fn &optional PREFIX)") (autoload 'org-id-update-id-locations "org-id" "\ Scan relevant files for IDs. Store the relation between files and corresponding IDs. @@ -2303,49 +1090,42 @@ files, and all files currently mentioned in `org-id-locations'. When FILES is given, scan also these files. If SILENT is non-nil, messages are suppressed. -\(fn &optional FILES SILENT)" t nil) - +(fn &optional FILES SILENT)" t) (autoload 'org-id-find-id-file "org-id" "\ Query the id database for the file in which ID is located. -\(fn ID)" nil nil) - +(fn ID)") (autoload 'org-id-store-link "org-id" "\ Store a link to the current entry, using its ID. -If before first heading store first title-keyword as description -or filename if no title." t nil) - -;;;### (autoloads "actual autoloads are elsewhere" "org-id" "org-id.el" -;;;;;; (0 0 0 0)) -;;; Generated autoloads from org-id.el +The link description is based on the heading, or if before the +first heading, the title keyword if available, or else the +filename. + +When `org-link-context-for-files' and `org-id-link-use-context' +are non-nil, add a search string to the link. The link +description is then based on the search string target. -(register-definition-prefixes "org-id" '("org-id-")) +When in addition `org-id-link-consider-parent-id' is non-nil, the +ID can be inherited from a parent entry, with the search string +used to still link to the current location." t) +(autoload 'org-id-store-link-maybe "org-id" "\ +Store a link to the current entry using its ID if enabled. -;;;*** +The value of `org-id-link-to-org-use-id' determines whether an ID +link should be stored, using `org-id-store-link'. + +Assume the function is called interactively if INTERACTIVE? is +non-nil. + +(fn &optional INTERACTIVE?)") -;;;*** -;;;### (autoloads nil "org-indent" "org-indent.el" "0460feb476d61dea99dc6d17cae9fbd2") ;;; Generated autoloads from org-indent.el (autoload 'org-indent-mode "org-indent" "\ When active, indent text according to outline structure. -This is a minor mode. If called interactively, toggle the `Org-Indent -mode' mode. If the prefix argument is positive, enable the mode, and -if it is zero or negative, disable the mode. - -If called from Lisp, toggle the mode if ARG is `toggle'. Enable the -mode if ARG is nil, omitted, or is a positive number. Disable the -mode if ARG is a negative number. - -To check whether the minor mode is enabled in the current buffer, -evaluate `org-indent-mode'. - -The mode's hook is called both when the mode is enabled and when it is -disabled. - Internally this works by adding `line-prefix' and `wrap-prefix' properties, after each buffer modification, on the modified zone. @@ -2353,43 +1133,29 @@ The process is synchronous. Though, initial indentation of buffer, which can take a few seconds on large buffers, is done during idle time. -\(fn &optional ARG)" t nil) - -;;;### (autoloads "actual autoloads are elsewhere" "org-indent" "org-indent.el" -;;;;;; (0 0 0 0)) -;;; Generated autoloads from org-indent.el +This is a minor mode. If called interactively, toggle the `Org-Indent +mode' mode. If the prefix argument is positive, enable the mode, and if +it is zero or negative, disable the mode. -(register-definition-prefixes "org-indent" '("org-indent-")) +If called from Lisp, toggle the mode if ARG is `toggle'. Enable the +mode if ARG is nil, omitted, or is a positive number. Disable the mode +if ARG is a negative number. -;;;*** +To check whether the minor mode is enabled in the current buffer, +evaluate the variable `org-indent-mode'. -;;;*** - -;;;### (autoloads nil "org-inlinetask" "org-inlinetask.el" (0 0 0 -;;;;;; 0)) -;;; Generated autoloads from org-inlinetask.el +The mode's hook is called both when the mode is enabled and when it is +disabled. -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "org-inlinetask" '("org-inlinetask-"))) +(fn &optional ARG)" t) -;;;*** -;;;### (autoloads nil "org-keys" "org-keys.el" "174600a8d35b5b0f6fa6590aec9eab61") ;;; Generated autoloads from org-keys.el (autoload 'org-babel-describe-bindings "org-keys" "\ -Describe all keybindings behind `org-babel-key-prefix'." t nil) - -;;;### (autoloads "actual autoloads are elsewhere" "org-keys" "org-keys.el" -;;;;;; (0 0 0 0)) -;;; Generated autoloads from org-keys.el - -(register-definition-prefixes "org-keys" '("org-")) +Describe all keybindings behind `org-babel-key-prefix'." t) -;;;*** - -;;;*** -;;;### (autoloads nil "org-lint" "org-lint.el" "2459a25c9f02d05a93e52318764b2fce") ;;; Generated autoloads from org-lint.el (autoload 'org-lint-add-checker "org-lint" "\ @@ -2423,10 +1189,8 @@ checker. Currently, two properties are supported: the nature of the check. This has an indicative value only and is displayed along reports. -\(fn NAME SUMMARY FUN &rest PROPS)" nil nil) - -(function-put 'org-lint-add-checker 'lisp-indent-function '1) - +(fn NAME SUMMARY FUN &rest PROPS)") +(function-put 'org-lint-add-checker 'lisp-indent-function 1) (autoload 'org-lint "org-lint" "\ Check current Org buffer for syntax mistakes. @@ -2436,19 +1200,9 @@ checker by its name. ARG can also be a list of checker names, as symbols, to run. -\(fn &optional ARG)" t nil) - -;;;### (autoloads "actual autoloads are elsewhere" "org-lint" "org-lint.el" -;;;;;; (0 0 0 0)) -;;; Generated autoloads from org-lint.el - -(register-definition-prefixes "org-lint" '("org-lint-")) +(fn &optional ARG)" t) -;;;*** - -;;;*** -;;;### (autoloads nil "org-list" "org-list.el" "7b6fab2d5ae7af12a153efa9e28afd32") ;;; Generated autoloads from org-list.el (autoload 'org-list-checkbox-radio-mode "org-list" "\ @@ -2460,135 +1214,105 @@ positive, enable the mode, and if it is zero or negative, disable the mode. If called from Lisp, toggle the mode if ARG is `toggle'. Enable the -mode if ARG is nil, omitted, or is a positive number. Disable the -mode if ARG is a negative number. +mode if ARG is nil, omitted, or is a positive number. Disable the mode +if ARG is a negative number. To check whether the minor mode is enabled in the current buffer, -evaluate `org-list-checkbox-radio-mode'. +evaluate the variable `org-list-checkbox-radio-mode'. The mode's hook is called both when the mode is enabled and when it is disabled. -\(fn &optional ARG)" t nil) - -;;;### (autoloads "actual autoloads are elsewhere" "org-list" "org-list.el" -;;;;;; (0 0 0 0)) -;;; Generated autoloads from org-list.el - -(register-definition-prefixes "org-list" '("org-")) - -;;;*** - -;;;*** - -;;;### (autoloads nil "org-macro" "org-macro.el" (0 0 0 0)) -;;; Generated autoloads from org-macro.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "org-macro" '("org-macro-"))) +(fn &optional ARG)" t) -;;;*** -;;;### (autoloads nil "org-macs" "org-macs.el" "1f9d24c9dbe37c36e3bd811b85711202") ;;; Generated autoloads from org-macs.el (autoload 'org-load-noerror-mustsuffix "org-macs" "\ Load FILE with optional arguments NOERROR and MUSTSUFFIX. -\(fn FILE)" nil t) - -;;;### (autoloads "actual autoloads are elsewhere" "org-macs" "org-macs.el" -;;;;;; (0 0 0 0)) -;;; Generated autoloads from org-macs.el - -(register-definition-prefixes "org-macs" '("org-")) +(fn FILE)" nil t) +(autoload 'org-element-with-disabled-cache "org-macs" "\ +Run BODY without active org-element-cache. -;;;*** +(fn &rest BODY)" nil t) +(function-put 'org-element-with-disabled-cache 'lisp-indent-function 0) -;;;*** -;;;### (autoloads nil "org-mobile" "org-mobile.el" "bd31559c4c6a24b69d89db63772a4372") ;;; Generated autoloads from org-mobile.el (autoload 'org-mobile-push "org-mobile" "\ Push the current state of Org affairs to the target directory. This will create the index file, copy all agenda files there, and also -create all custom agenda views, for upload to the mobile phone." t nil) - +create all custom agenda views, for upload to the mobile phone." t) (autoload 'org-mobile-pull "org-mobile" "\ Pull the contents of `org-mobile-capture-file' and integrate them. Apply all flagged actions, flag entries to be flagged and then call an -agenda view showing the flagged items." t nil) - -;;;### (autoloads "actual autoloads are elsewhere" "org-mobile" "org-mobile.el" -;;;;;; (0 0 0 0)) -;;; Generated autoloads from org-mobile.el - -(register-definition-prefixes "org-mobile" '("org-mobile-")) - -;;;*** - -;;;*** - -;;;### (autoloads nil "org-mouse" "org-mouse.el" (0 0 0 0)) -;;; Generated autoloads from org-mouse.el +agenda view showing the flagged items." t) -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "org-mouse" '("org-"))) - -;;;*** -;;;### (autoloads nil "org-num" "org-num.el" "ff2773385e5c79b5fc0c83705399fb25") ;;; Generated autoloads from org-num.el +(defvar org-num-face nil "\ +Face to use for numbering. +When nil, use the same face as the headline. This value is +ignored if `org-num-format-function' specifies a face for its +output.") +(custom-autoload 'org-num-face "org-num" t) +(put 'org-num-face 'safe-local-variable (lambda (val) (or (null val) (facep val)))) +(defvar org-num-max-level nil "\ +Level below which headlines are not numbered. +When set to nil, all headlines are numbered.") +(custom-autoload 'org-num-max-level "org-num" t) +(put 'org-num-max-level 'safe-local-variable (lambda (val) (or (null val) (wholenump val)))) +(defvar org-num-skip-commented nil "\ +Non-nil means commented sub-trees are not numbered.") +(custom-autoload 'org-num-skip-commented "org-num" t) +(put 'org-num-skip-commented 'safe-local-variable #'booleanp) +(defvar org-num-skip-footnotes nil "\ +Non-nil means footnotes sections are not numbered.") +(custom-autoload 'org-num-skip-footnotes "org-num" t) +(put 'org-num-skip-footnotes 'safe-local-variable #'booleanp) +(defvar org-num-skip-tags nil "\ +List of tags preventing the numbering of sub-trees. + +For example, add \"ARCHIVE\" to this list to avoid numbering +archived sub-trees. + +Tag in this list prevent numbering the whole sub-tree, +irrespective to `org-use-tag-inheritance', or other means to +control tag inheritance.") +(custom-autoload 'org-num-skip-tags "org-num" t) +(put 'org-num-skip-tags 'safe-local-variable #'org-list-of-strings-p) +(defvar org-num-skip-unnumbered nil "\ +Non-nil means numbering obeys to UNNUMBERED property.") +(custom-autoload 'org-num-skip-unnumbered "org-num" t) +(put 'org-num-skip-unnumbered 'safe-local-variable #'booleanp) (autoload 'org-num-default-format "org-num" "\ Default numbering display function. NUMBERING is a list of numbers. -\(fn NUMBERING)" nil nil) - +(fn NUMBERING)") (autoload 'org-num-mode "org-num" "\ Dynamic numbering of headlines in an Org buffer. This is a minor mode. If called interactively, toggle the `Org-Num -mode' mode. If the prefix argument is positive, enable the mode, and -if it is zero or negative, disable the mode. +mode' mode. If the prefix argument is positive, enable the mode, and if +it is zero or negative, disable the mode. If called from Lisp, toggle the mode if ARG is `toggle'. Enable the -mode if ARG is nil, omitted, or is a positive number. Disable the -mode if ARG is a negative number. +mode if ARG is nil, omitted, or is a positive number. Disable the mode +if ARG is a negative number. To check whether the minor mode is enabled in the current buffer, -evaluate `org-num-mode'. +evaluate the variable `org-num-mode'. The mode's hook is called both when the mode is enabled and when it is disabled. -\(fn &optional ARG)" t nil) - -;;;### (autoloads "actual autoloads are elsewhere" "org-num" "org-num.el" -;;;;;; (0 0 0 0)) -;;; Generated autoloads from org-num.el - -(register-definition-prefixes "org-num" '("org-num-")) - -;;;*** - -;;;*** - -;;;### (autoloads nil "org-pcomplete" "org-pcomplete.el" (0 0 0 0)) -;;; Generated autoloads from org-pcomplete.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "org-pcomplete" '("org-" "pcomplete/org-mode/"))) - -;;;*** - -;;;### (autoloads nil "org-persist" "org-persist.el" (0 0 0 0)) -;;; Generated autoloads from org-persist.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "org-persist" '("org-persist-"))) +(fn &optional ARG)" t) -;;;*** -;;;### (autoloads nil "org-plot" "org-plot.el" "e2240038783c9658074c2189bc813f32") ;;; Generated autoloads from org-plot.el (autoload 'org-plot/gnuplot "org-plot" "\ @@ -2596,39 +1320,20 @@ Plot table using gnuplot. Gnuplot options can be specified with PARAMS. If not given options will be taken from the +PLOT line directly before or after the table. -\(fn &optional PARAMS)" t nil) - -;;;### (autoloads "actual autoloads are elsewhere" "org-plot" "org-plot.el" -;;;;;; (0 0 0 0)) -;;; Generated autoloads from org-plot.el - -(register-definition-prefixes "org-plot" '("org-")) - -;;;*** +(fn &optional PARAMS)" t) -;;;*** -;;;### (autoloads nil "org-protocol" "org-protocol.el" (0 0 0 0)) -;;; Generated autoloads from org-protocol.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "org-protocol" '("org-"))) - -;;;*** - -;;;### (autoloads nil "org-refile" "org-refile.el" "af18f3c602b496369a9b98d708a4dabc") ;;; Generated autoloads from org-refile.el (autoload 'org-refile-copy "org-refile" "\ -Like `org-refile', but preserve the refiled subtree." t nil) - +Like `org-refile', but preserve the refiled subtree." t) (autoload 'org-refile-reverse "org-refile" "\ Refile while temporarily toggling `org-reverse-note-order'. 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. -\(fn &optional ARG DEFAULT-BUFFER RFLOC MSG)" t nil) - +(fn &optional ARG DEFAULT-BUFFER RFLOC MSG)" t) (autoload 'org-refile "org-refile" "\ Move the entry or entries at point to another heading. @@ -2674,56 +1379,36 @@ See also `org-refile-use-outline-path'. If you are using target caching (see `org-refile-use-cache'), you have to clear the target cache in order to find new targets. -This can be done with a `0' prefix (`C-0 C-c C-w') or a triple -prefix argument (`C-u C-u C-u C-c C-w'). - -\(fn &optional ARG DEFAULT-BUFFER RFLOC MSG)" t nil) - -;;;### (autoloads "actual autoloads are elsewhere" "org-refile" "org-refile.el" -;;;;;; (0 0 0 0)) -;;; Generated autoloads from org-refile.el +This can be done with a `0' prefix (\\`C-0 C-c C-w') or a triple +prefix argument (\\`C-u C-u C-u C-c C-w'). -(register-definition-prefixes "org-refile" '("org-")) +(fn &optional ARG DEFAULT-BUFFER RFLOC MSG)" t) -;;;*** - -;;;*** - -;;;### (autoloads nil "org-src" "org-src.el" (0 0 0 0)) -;;; Generated autoloads from org-src.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "org-src" '("org-"))) - -;;;*** -;;;### (autoloads nil "org-table" "org-table.el" "1633ab790bd158214f26d2ee6c3cf02f") ;;; Generated autoloads from org-table.el (autoload 'org-table-header-line-mode "org-table" "\ Display the first row of the table at point in the header line. This is a minor mode. If called interactively, toggle the -`Org-Table-Header-Line mode' mode. If the prefix argument is -positive, enable the mode, and if it is zero or negative, disable the -mode. +`Org-Table-Header-Line mode' mode. If the prefix argument is positive, +enable the mode, and if it is zero or negative, disable the mode. If called from Lisp, toggle the mode if ARG is `toggle'. Enable the -mode if ARG is nil, omitted, or is a positive number. Disable the -mode if ARG is a negative number. +mode if ARG is nil, omitted, or is a positive number. Disable the mode +if ARG is a negative number. To check whether the minor mode is enabled in the current buffer, -evaluate `org-table-header-line-mode'. +evaluate the variable `org-table-header-line-mode'. The mode's hook is called both when the mode is enabled and when it is disabled. -\(fn &optional ARG)" t nil) - -(autoload 'org-table-create-with-table\.el "org-table" "\ +(fn &optional ARG)" t) +(autoload 'org-table-create-with-table.el "org-table" "\ Use the table.el package to insert a new table. If there is already a table at point, convert between Org tables -and table.el tables." t nil) - +and table.el tables." t) (autoload 'org-table-create-or-convert-from-region "org-table" "\ Convert region to table, or create an empty table. If there is an active region, convert it to a table, using the function @@ -2732,14 +1417,12 @@ to learn how the prefix argument is interpreted to determine the field separator. If there is no such region, create an empty table with `org-table-create'. -\(fn ARG)" t nil) - +(fn ARG)" t) (autoload 'org-table-create "org-table" "\ Query for a size and insert a table skeleton. SIZE is a string Columns x Rows like for example \"3x2\". -\(fn &optional SIZE)" t nil) - +(fn &optional SIZE)" t) (autoload 'org-table-convert-region "org-table" "\ Convert region to a table. @@ -2753,9 +1436,9 @@ Throw an error when the region has more than SEPARATOR specifies the field separator in the lines. It can have the following values: -\(4) Use the comma as a field separator -\(16) Use a TAB as field separator -\(64) Prompt for a regular expression as field separator +(4) Use the comma as a field separator +(16) Use a TAB as field separator +(64) Prompt for a regular expression as field separator integer When a number, use that many spaces, or a TAB, as field separator regexp When a regular expression, use it to match the separator nil When nil, the command tries to be smart and figure out the @@ -2763,9 +1446,11 @@ nil When nil, the command tries to be smart and figure out the - when each line contains a TAB, assume TAB-separated material - when each line contains a comma, assume CSV material - else, assume one or more SPACE characters as separator. +`babel-auto' + Use the same rules as nil, but do not try any separator when + the region contains a single line and has no commas or tabs. -\(fn BEG0 END0 &optional SEPARATOR)" t nil) - +(fn BEG0 END0 &optional SEPARATOR)" t) (autoload 'org-table-import "org-table" "\ Import FILE as a table. @@ -2785,44 +1470,37 @@ lines. It can have the following values: - integer When a number, use that many spaces, or a TAB, as field separator. - regexp When a regular expression, use it to match the separator. -\(fn FILE SEPARATOR)" t nil) - +(fn FILE SEPARATOR)" t) (autoload 'org-table-begin "org-table" "\ Find the beginning of the table and return its position. With a non-nil optional argument TABLE-TYPE, return the beginning of a table.el-type table. This function assumes point is on a table. -\(fn &optional TABLE-TYPE)" nil nil) - +(fn &optional TABLE-TYPE)") (autoload 'org-table-end "org-table" "\ Find the end of the table and return its position. With a non-nil optional argument TABLE-TYPE, return the end of a table.el-type table. This function assumes point is on a table. -\(fn &optional TABLE-TYPE)" nil nil) - +(fn &optional TABLE-TYPE)") (autoload 'org-table-next-field "org-table" "\ Go to the next field in the current table, creating new lines as needed. -Before doing so, re-align the table if necessary." t nil) - +Before doing so, re-align the table if necessary." t) (autoload 'org-table-previous-field "org-table" "\ Go to the previous field in the table. -Before doing so, re-align the table if necessary." t nil) - +Before doing so, re-align the table if necessary." t) (autoload 'org-table-next-row "org-table" "\ Go to the next row (same column) in the current table. -Before doing so, re-align the table if necessary." t nil) - +When next row is an hline or outside the table, create a new empty +row. Before doing so, re-align the table if necessary." t) (autoload 'org-table-blank-field "org-table" "\ -Blank the current table field or active region." t nil) - +Blank the current table field or active region." t) (autoload 'org-table-field-info "org-table" "\ Show info about the current field, and highlight any reference at point. -\(fn ARG)" t nil) - +(fn ARG)" t) (autoload 'org-table-goto-column "org-table" "\ Move the cursor to the Nth column in the current table line. With optional argument ON-DELIM, stop with point before the left delimiter @@ -2830,78 +1508,60 @@ of the field. If there are less than N fields, just go to after the last delimiter. However, when FORCE is non-nil, create new columns if necessary. -\(fn N &optional ON-DELIM FORCE)" t nil) - +(fn N &optional ON-DELIM FORCE)" t) (autoload 'org-table-insert-column "org-table" "\ -Insert a new column into the table." t nil) - +Insert a new column into the table." t) (autoload 'org-table-move-cell-up "org-table" "\ Move a single cell up in a table. -Swap with anything in target cell." t nil) - +Swap with anything in target cell." t) (autoload 'org-table-move-cell-down "org-table" "\ Move a single cell down in a table. -Swap with anything in target cell." t nil) - +Swap with anything in target cell." t) (autoload 'org-table-move-cell-left "org-table" "\ Move a single cell left in a table. -Swap with anything in target cell." t nil) - +Swap with anything in target cell." t) (autoload 'org-table-move-cell-right "org-table" "\ Move a single cell right in a table. -Swap with anything in target cell." t nil) - +Swap with anything in target cell." t) (autoload 'org-table-delete-column "org-table" "\ -Delete a column from the table." t nil) - +Delete a column from the table." t) (autoload 'org-table-move-column-right "org-table" "\ -Move column to the right." t nil) - +Move column to the right." t) (autoload 'org-table-move-column-left "org-table" "\ -Move column to the left." t nil) - +Move column to the left." t) (autoload 'org-table-move-column "org-table" "\ Move the current column to the right. With arg LEFT, move to the left. -\(fn &optional LEFT)" t nil) - +(fn &optional LEFT)" t) (autoload 'org-table-move-row-down "org-table" "\ -Move table row down." t nil) - +Move table row down." t) (autoload 'org-table-move-row-up "org-table" "\ -Move table row up." t nil) - +Move table row up." t) (autoload 'org-table-move-row "org-table" "\ Move the current table line down. With arg UP, move it up. -\(fn &optional UP)" t nil) - +(fn &optional UP)" t) (autoload 'org-table-insert-row "org-table" "\ Insert a new row above the current line into the table. With prefix ARG, insert below the current line. -\(fn &optional ARG)" t nil) - +(fn &optional ARG)" t) (autoload 'org-table-insert-hline "org-table" "\ Insert a horizontal-line below the current line into the table. With prefix ABOVE, insert above the current line. -\(fn &optional ABOVE)" t nil) - +(fn &optional ABOVE)" t) (autoload 'org-table-hline-and-move "org-table" "\ Insert a hline and move to the row below that line. -\(fn &optional SAME-COLUMN)" t nil) - +(fn &optional SAME-COLUMN)" t) (autoload 'org-table-kill-row "org-table" "\ -Delete the current row or horizontal line from the table." t nil) - +Delete the current row or horizontal line from the table." t) (autoload 'org-table-cut-region "org-table" "\ Copy region in table to the clipboard and blank all relevant fields. If there is no active region, use just the field at point. -\(fn BEG END)" t nil) - +(fn BEG END)" t) (autoload 'org-table-copy-down "org-table" "\ Copy the value of the current field one row below. @@ -2923,23 +1583,20 @@ the case of a timestamp, increment by days. However, when N is 0, do not increment the field at all. -\(fn N)" t nil) - +(fn N)" t) (autoload 'org-table-copy-region "org-table" "\ Copy rectangular region in table to clipboard. A special clipboard is used which can only be accessed with `org-table-paste-rectangle'. Return the region copied, as a list of lists of fields. -\(fn BEG END &optional CUT)" t nil) - +(fn BEG END &optional CUT)" t) (autoload 'org-table-paste-rectangle "org-table" "\ Paste a rectangular region into a table. The upper right corner ends up in the current field. All involved fields will be overwritten. If the rectangle does not fit into the present table, the table is enlarged as needed. The process ignores horizontal separator -lines." t nil) - +lines." t) (autoload 'org-table-edit-field "org-table" "\ Edit table field in a different window. This is mainly useful for fields that contain hidden parts. @@ -2949,20 +1606,17 @@ visible so that it can be edited in place. When called with a `\\[universal-argument] \\[universal-argument]' prefix, toggle `org-table-follow-field-mode'. -\(fn ARG)" t nil) - +(fn ARG)" t) (autoload 'org-table-get-stored-formulas "org-table" "\ Return an alist with the stored formulas directly after current table. By default, only return active formulas, i.e., formulas located on the first line after the table. However, if optional argument LOCATION is a buffer position, consider the formulas there. -\(fn &optional NOERROR LOCATION)" nil nil) - +(fn &optional NOERROR LOCATION)") (autoload 'org-table-maybe-eval-formula "org-table" "\ Check if the current field starts with \"=\" or \":=\". -If yes, store the formula and apply it." nil nil) - +If yes, store the formula and apply it.") (autoload 'org-table-rotate-recalc-marks "org-table" "\ Rotate the recalculation mark in the first column. If in any row, the first field is not consistent with a mark, @@ -2972,11 +1626,9 @@ after prompting for the marking character. After each change, a message will be displayed indicating the meaning of the new mark. -\(fn &optional NEWCHAR)" t nil) - +(fn &optional NEWCHAR)" t) (autoload 'org-table-maybe-recalculate-line "org-table" "\ -Recompute the current line if marked for it, and if we haven't just done it." t nil) - +Recompute the current line if marked for it, and if we haven't just done it." t) (autoload 'org-table-eval-formula "org-table" "\ Replace the table field value at the cursor by the result of a calculation. @@ -3016,8 +1668,7 @@ equation that should not overwrite the stored one. SUPPRESS-ANALYSIS prevents analyzing the table and checking location of point. -\(fn &optional ARG EQUATION SUPPRESS-ALIGN SUPPRESS-CONST SUPPRESS-STORE SUPPRESS-ANALYSIS)" t nil) - +(fn &optional ARG EQUATION SUPPRESS-ALIGN SUPPRESS-CONST SUPPRESS-STORE SUPPRESS-ANALYSIS)" t) (autoload 'org-table-recalculate "org-table" "\ Recalculate the current table line by applying all stored formulas. @@ -3030,30 +1681,23 @@ If NOALIGN is not nil, do not re-align the table after the computations are done. This is typically used internally to save time, if it is known that the table will be realigned a little later anyway. -\(fn &optional ALL NOALIGN)" t nil) - +(fn &optional ALL NOALIGN)" t) (autoload 'org-table-iterate "org-table" "\ Recalculate the table until it does not change anymore. The maximum number of iterations is 10, but you can choose a different value with the prefix ARG. -\(fn &optional ARG)" t nil) - +(fn &optional ARG)" t) (autoload 'org-table-recalculate-buffer-tables "org-table" "\ -Recalculate all tables in the current buffer." t nil) - +Recalculate all tables in the current buffer." t) (autoload 'org-table-iterate-buffer-tables "org-table" "\ -Iterate all tables in the buffer, to converge inter-table dependencies." t nil) - +Iterate all tables in the buffer, to converge inter-table dependencies." t) (autoload 'org-table-edit-formulas "org-table" "\ -Edit the formulas of the current table in a separate buffer." t nil) - +Edit the formulas of the current table in a separate buffer." t) (autoload 'org-table-toggle-coordinate-overlays "org-table" "\ -Toggle the display of Row/Column numbers in tables." t nil) - +Toggle the display of Row/Column numbers in tables." t) (autoload 'org-table-toggle-formula-debugger "org-table" "\ -Toggle the formula debugger in tables." t nil) - +Toggle the formula debugger in tables." t) (autoload 'org-table-toggle-column-width "org-table" "\ Shrink or expand current column in an Org table. @@ -3079,8 +1723,7 @@ shrink columns with a width cookie and expand the others. When called with `\\[universal-argument] \\[universal-argument]' prefix, expand all columns. -\(fn &optional ARG)" t nil) - +(fn &optional ARG)" t) (autoload 'org-table-shrink "org-table" "\ Shrink all columns with a width cookie in the table at point. @@ -3089,20 +1732,17 @@ Columns without a width cookie are expanded. Optional arguments BEGIN and END, when non-nil, specify the beginning and end position of the current table. -\(fn &optional BEGIN END)" t nil) - +(fn &optional BEGIN END)" t) (autoload 'org-table-expand "org-table" "\ Expand all columns in the table at point. Optional arguments BEGIN and END, when non-nil, specify the beginning and end position of the current table. -\(fn &optional BEGIN END)" t nil) - +(fn &optional BEGIN END)" t) (autoload 'org-table-map-tables "org-table" "\ Apply function F to the start of all tables in the buffer. -\(fn F &optional QUIETLY)" nil nil) - +(fn F &optional QUIETLY)") (autoload 'org-table-export "org-table" "\ Export table to a file, with configurable format. Such a file can be imported into usual spreadsheet programs. @@ -3118,21 +1758,18 @@ whether it is set locally or up in the hierarchy, then on the extension of the given file name, and finally on the variable `org-table-export-default-format'. -\(fn &optional FILE FORMAT)" t nil) - +(fn &optional FILE FORMAT)" t) (autoload 'org-table--align-field "org-table" "\ Format FIELD according to column WIDTH and alignment ALIGN. FIELD is a string. WIDTH is a number. ALIGN is either \"c\", \"l\" or\"r\". -\(fn FIELD WIDTH ALIGN)" nil nil) - +(fn FIELD WIDTH ALIGN)") (autoload 'org-table-justify-field-maybe "org-table" "\ Justify the current field, text to left, number to right. Optional argument NEW may specify text to replace the current field content. -\(fn &optional NEW)" nil nil) - +(fn &optional NEW)") (autoload 'org-table-sort-lines "org-table" "\ Sort table lines according to the column at point. @@ -3165,8 +1802,7 @@ entries. A non-nil value for INTERACTIVE? is used to signal that this function is being called interactively. -\(fn &optional WITH-CASE SORTING-TYPE GETKEY-FUNC COMPARE-FUNC INTERACTIVE\\=\\?)" t nil) - +(fn &optional WITH-CASE SORTING-TYPE GETKEY-FUNC COMPARE-FUNC INTERACTIVE?)" t) (autoload 'org-table-wrap-region "org-table" "\ Wrap several fields in a column like a paragraph. This is useful if you'd like to spread the contents of a field over several @@ -3190,8 +1826,7 @@ line down. If there is no region, but you specify a prefix ARG, the current field gets blank, and the content is appended to the field above. -\(fn ARG)" t nil) - +(fn ARG)" t) (autoload 'org-table-sum "org-table" "\ Sum numbers in region of current table column. The result will be displayed in the echo area, and will be available @@ -3208,8 +1843,7 @@ numbers are added as such. If NLAST is a number, only the NLAST fields will actually be summed. -\(fn &optional BEG END NLAST)" t nil) - +(fn &optional BEG END NLAST)" t) (autoload 'org-table-analyze "org-table" "\ Analyze table at point and store results. @@ -3223,33 +1857,31 @@ This function sets up the following dynamically scoped variables: `org-table-dlines', `org-table-hlines', `org-table-local-parameters', - `org-table-named-field-locations'." nil nil) - + `org-table-named-field-locations'.") (autoload 'turn-on-orgtbl "org-table" "\ -Unconditionally turn on `orgtbl-mode'." nil nil) - +Unconditionally turn on `orgtbl-mode'.") (autoload 'orgtbl-mode "org-table" "\ The Org mode table editor as a minor mode for use in other modes. -This is a minor mode. If called interactively, toggle the `OrgTbl -mode' mode. If the prefix argument is positive, enable the mode, and -if it is zero or negative, disable the mode. +This is a minor mode. If called interactively, toggle the `OrgTbl mode' +mode. If the prefix argument is positive, enable the mode, and if it is +zero or negative, disable the mode. If called from Lisp, toggle the mode if ARG is `toggle'. Enable the -mode if ARG is nil, omitted, or is a positive number. Disable the -mode if ARG is a negative number. +mode if ARG is nil, omitted, or is a positive number. Disable the mode +if ARG is a negative number. To check whether the minor mode is enabled in the current buffer, -evaluate `orgtbl-mode'. +evaluate the variable `orgtbl-mode'. The mode's hook is called both when the mode is enabled and when it is disabled. -\(fn &optional ARG)" t nil) +\\{orgtbl-mode-map} +(fn &optional ARG)" t) (defvar orgtbl-exp-regexp "^\\([-+]?[0-9][0-9.]*\\)[eE]\\([-+]?[0-9]+\\)$" "\ Regular expression matching exponentials as produced by calc.") - (autoload 'org-table-to-lisp "org-table" "\ Convert the table at point to a Lisp structure. @@ -3257,8 +1889,7 @@ The structure will be a list. Each item is either the symbol `hline' for a horizontal separator line, or a list of field values as strings. The table is taken from the parameter TXT, or from the buffer at point. -\(fn &optional TXT)" nil nil) - +(fn &optional TXT)") (autoload 'orgtbl-to-generic "org-table" "\ Convert the `orgtbl-mode' TABLE to some other format. @@ -3273,7 +1904,7 @@ Valid parameters are: :backend, :raw - Export back-end used as a basis to transcode elements of the + Export backend used as a basis to transcode elements of the table, when no specific parameter applies to it. It is also used to translate cells contents. You can prevent this by setting :raw property to a non-nil value. @@ -3362,19 +1993,16 @@ This may be either a string or a function of two arguments: list with column numbers and format strings or functions. :fmt will still be applied after :efmt. -\(fn TABLE PARAMS)" nil nil) - +(fn TABLE PARAMS)") (autoload 'orgtbl-to-tsv "org-table" "\ Convert the `orgtbl-mode' TABLE to TAB separated material. -\(fn TABLE PARAMS)" nil nil) - +(fn TABLE PARAMS)") (autoload 'orgtbl-to-csv "org-table" "\ Convert the `orgtbl-mode' TABLE to CSV material. This does take care of the proper quoting of fields with comma or quotes. -\(fn TABLE PARAMS)" nil nil) - +(fn TABLE PARAMS)") (autoload 'orgtbl-to-latex "org-table" "\ Convert the `orgtbl-mode' TABLE to LaTeX. @@ -3394,8 +2022,7 @@ supported. It is also possible to use the following ones: \"longtable\", you may also want to specify :language property, as a string, to get proper continuation strings. -\(fn TABLE PARAMS)" nil nil) - +(fn TABLE PARAMS)") (autoload 'orgtbl-to-html "org-table" "\ Convert the `orgtbl-mode' TABLE to HTML. @@ -3410,8 +2037,7 @@ supported. It is also possible to use the following one: Attributes and values, as a plist, which will be used in tag. -\(fn TABLE PARAMS)" nil nil) - +(fn TABLE PARAMS)") (autoload 'orgtbl-to-texinfo "org-table" "\ Convert the `orgtbl-mode' TABLE to Texinfo. @@ -3426,10 +2052,9 @@ supported. It is also possible to use the following one: Column widths, as a string. When providing column fractions, \"@columnfractions\" command can be omitted. -\(fn TABLE PARAMS)" nil nil) - +(fn TABLE PARAMS)") (autoload 'orgtbl-to-orgtbl "org-table" "\ -Convert the `orgtbl-mode' TABLE into another orgtbl-mode table. +Convert the `orgtbl-mode' TABLE into another `orgtbl-mode' table. TABLE is a list, each entry either the symbol `hline' for a horizontal separator line, or a list of fields for that line. @@ -3441,8 +2066,7 @@ Useful when slicing one table into many. The :hline, :sep, :lstart, and :lend provide orgtbl framing. :tstart and :tend can be set to provide ORGTBL directives for the generated table. -\(fn TABLE PARAMS)" nil nil) - +(fn TABLE PARAMS)") (autoload 'orgtbl-ascii-plot "org-table" "\ Draw an ASCII bar plot in a column. @@ -3453,26 +2077,9 @@ ASK, if given, is a numeric prefix to override the default 12 characters width of the plot. ASK may also be the `\\[universal-argument]' prefix, which will prompt for the width. -\(fn &optional ASK)" t nil) - -;;;### (autoloads "actual autoloads are elsewhere" "org-table" "org-table.el" -;;;;;; (0 0 0 0)) -;;; Generated autoloads from org-table.el - -(register-definition-prefixes "org-table" '("org")) - -;;;*** - -;;;*** - -;;;### (autoloads nil "org-tempo" "org-tempo.el" (0 0 0 0)) -;;; Generated autoloads from org-tempo.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "org-tempo" '("org-tempo-"))) +(fn &optional ASK)" t) -;;;*** -;;;### (autoloads nil "org-timer" "org-timer.el" "30c669a8d0bbe5a034d17b844be7d32f") ;;; Generated autoloads from org-timer.el (autoload 'org-timer-start "org-timer" "\ @@ -3486,42 +2093,39 @@ region will be shifted by a specific amount. You will be prompted for the amount, with the default to make the first timer string in the region 0:00:00. -\(fn &optional OFFSET)" t nil) - +(fn &optional OFFSET)" t) (autoload 'org-timer-pause-or-continue "org-timer" "\ Pause or continue the relative or countdown timer. With prefix arg STOP, stop it entirely. -\(fn &optional STOP)" t nil) - +(fn &optional STOP)" t) (autoload 'org-timer-stop "org-timer" "\ -Stop the relative or countdown timer." t nil) - +Stop the relative or countdown timer." t) (autoload 'org-timer "org-timer" "\ Insert a H:MM:SS string from the timer into the buffer. The first time this command is used, the timer is started. -When used with a `\\[universal-argument]' prefix, force restarting the timer. +When used with a `\\[universal-argument]' prefix RESTART, force +restarting the timer. -When used with a `\\[universal-argument] \\[universal-argument]' prefix, change all the timer strings -in the region by a fixed amount. This can be used to re-calibrate -a timer that was not started at the correct moment. +When used with a `\\[universal-argument] \\[universal-argument]' prefix +RESTART, change all the timer strings in the region by a fixed amount. +This can be used to re-calibrate a timer that was not started at the +correct moment. -If NO-INSERT is non-nil, return the string instead of inserting -it in the buffer. - -\(fn &optional RESTART NO-INSERT)" t nil) +If NO-INSERT is non-nil, return the string instead of inserting it in +the buffer. +(fn &optional RESTART NO-INSERT)" t) (autoload 'org-timer-change-times-in-region "org-timer" "\ -Change all h:mm:ss time in region by a DELTA. - -\(fn BEG END DELTA)" t nil) +Change all h:mm:ss time in region BEG..END by a DELTA. +(fn BEG END DELTA)" t) (autoload 'org-timer-item "org-timer" "\ Insert a description-type item with the current timer value. +Prefix argument ARG is passed to `org-timer'. -\(fn &optional ARG)" t nil) - +(fn &optional ARG)" t) (autoload 'org-timer-set-timer "org-timer" "\ Prompt for a duration in minutes or hh:mm:ss and set a timer. @@ -3529,206 +2133,41 @@ If `org-timer-default-timer' is not \"0\", suggest this value as the default duration for the timer. If a timer is already set, prompt the user if she wants to replace it. -Called with a numeric prefix argument, use this numeric value as +Called with a numeric prefix argument OPT, use this numeric value as the duration of the timer in minutes. -Called with a \\[universal-argument] prefix arguments, use `org-timer-default-timer' -without prompting the user for a duration. +Called with a \\[universal-argument] prefix argument OPT, use +`org-timer-default-timer' without prompting the user for a duration. -With two \\[universal-argument] prefix arguments, use `org-timer-default-timer' -without prompting the user for a duration and automatically -replace any running timer. +With two \\[universal-argument] prefix arguments OPT, use +`org-timer-default-timer' without prompting the user for a duration +and automatically replace any running timer. By default, the timer duration will be set to the number of minutes in the Effort property, if any. You can ignore this by using three \\[universal-argument] prefix arguments. -\(fn &optional OPT)" t nil) - -;;;### (autoloads "actual autoloads are elsewhere" "org-timer" "org-timer.el" -;;;;;; (0 0 0 0)) -;;; Generated autoloads from org-timer.el - -(register-definition-prefixes "org-timer" '("org-timer-")) - -;;;*** - -;;;*** - -;;;### (autoloads nil "org-version" "org-version.el" (0 0 0 0)) -;;; Generated autoloads from org-version.el - -(autoload 'org-release "org-version" "\ -The release version of Org. -Inserted by installing Org mode or when a release is made." nil nil) - -(autoload 'org-git-version "org-version" "\ -The Git version of Org mode. -Inserted by installing Org or when a release is made." nil nil) - -;;;*** - -;;;### (autoloads nil "org" "org.el" (0 0 0 0)) -;;; Generated autoloads from org.el - -(autoload 'org-babel-do-load-languages "org" "\ -Load the languages defined in `org-babel-load-languages'. - -\(fn SYM VALUE)" nil nil) - -(autoload 'org-babel-load-file "org" "\ -Load Emacs Lisp source code blocks in the Org FILE. -This function exports the source code using `org-babel-tangle' -and then loads the resulting file using `load-file'. With -optional prefix argument COMPILE, the tangled Emacs Lisp file is -byte-compiled before it is loaded. - -\(fn FILE &optional COMPILE)" t nil) - -(autoload 'org-version "org" "\ -Show the Org version. -Interactively, or when MESSAGE is non-nil, show it in echo area. -With prefix argument, or when HERE is non-nil, insert it at point. -In non-interactive uses, a reduced version string is output unless -FULL is given. - -\(fn &optional HERE FULL MESSAGE)" t nil) - -(autoload 'org-load-modules-maybe "org" "\ -Load all extensions listed in `org-modules'. - -\(fn &optional FORCE)" nil nil) - -(autoload 'org-clock-persistence-insinuate "org" "\ -Set up hooks for clock persistence." nil nil) - -(autoload 'org-mode "org" "\ -Outline-based notes management and organizer, alias -\"Carsten's outline-mode for keeping track of everything.\" - -Org mode develops organizational tasks around a NOTES file which -contains information about projects as plain text. Org mode is -implemented on top of Outline mode, which is ideal to keep the content -of large files well structured. It supports ToDo items, deadlines and -time stamps, which magically appear in the diary listing of the Emacs -calendar. Tables are easily created with a built-in table editor. -Plain text URL-like links connect to websites, emails (VM), Usenet -messages (Gnus), BBDB entries, and any files related to the project. -For printing and sharing of notes, an Org file (or a part of it) -can be exported as a structured ASCII or HTML file. - -The following commands are available: - -\\{org-mode-map} - -\(fn)" t nil) - -(autoload 'org-run-like-in-org-mode "org" "\ -Run a command, pretending that the current buffer is in Org mode. -This will temporarily bind local variables that are typically bound in -Org mode to the values they have in Org mode, and then interactively -call CMD. - -\(fn CMD)" nil nil) - -(autoload 'org-open-file "org" "\ -Open the file at PATH. -First, this expands any special file name abbreviations. Then the -configuration variable `org-file-apps' is checked if it contains an -entry for this file type, and if yes, the corresponding command is launched. - -If no application is found, Emacs simply visits the file. - -With optional prefix argument IN-EMACS, Emacs will visit the file. -With a double \\[universal-argument] \\[universal-argument] prefix arg, Org tries to avoid opening in Emacs -and to use an external application to visit the file. - -Optional LINE specifies a line to go to, optional SEARCH a string -to search for. If LINE or SEARCH is given, the file will be -opened in Emacs, unless an entry from `org-file-apps' that makes -use of groups in a regexp matches. - -If you want to change the way frames are used when following a -link, please customize `org-link-frame-setup'. - -If the file does not exist, throw an error. - -\(fn PATH &optional IN-EMACS LINE SEARCH)" nil nil) - -(autoload 'org-open-at-point-global "org" "\ -Follow a link or a time-stamp like Org mode does. -Also follow links and emails as seen by `thing-at-point'. -This command can be called in any mode to follow an external -link or a time-stamp that has Org mode syntax. Its behavior -is undefined when called on internal links like fuzzy links. -Raise a user error when there is nothing to follow." t nil) - -(autoload 'org-offer-links-in-entry "org" "\ -Offer links in the current entry and return the selected link. -If there is only one link, return it. -If NTH is an integer, return the NTH link found. -If ZERO is a string, check also this string for a link, and if -there is one, return it. - -\(fn BUFFER MARKER &optional NTH ZERO)" nil nil) - -(autoload 'org-switchb "org" "\ -Switch between Org buffers. - -With `\\[universal-argument]' prefix, restrict available buffers to files. - -With `\\[universal-argument] \\[universal-argument]' prefix, restrict available buffers to agenda files. - -\(fn &optional ARG)" t nil) +(fn &optional OPT)" t) -(autoload 'org-cycle-agenda-files "org" "\ -Cycle through the files in `org-agenda-files'. -If the current buffer visits an agenda file, find the next one in the list. -If the current buffer does not, find the first agenda file." t nil) - -(autoload 'org-submit-bug-report "org" "\ -Submit a bug report on Org via mail. - -Don't hesitate to report any problems or inaccurate documentation. - -If you don't have setup sending mail from (X)Emacs, please copy the -output buffer into your mail program, as it gives us important -information about your Org version and configuration." t nil) - -(autoload 'org-reload "org" "\ -Reload all Org Lisp files. -With prefix arg UNCOMPILED, load the uncompiled versions. - -\(fn &optional UNCOMPILED)" t nil) - -(autoload 'org-customize "org" "\ -Call the customize function with org as argument." t nil) - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "org" '("org-" "turn-on-org-cdlatex"))) - -;;;*** -;;;### (autoloads nil "ox" "ox.el" "de9bf9457b7cb9f7df22ea8f2f5ffdeb") ;;; Generated autoloads from ox.el (autoload 'org-export-get-backend "ox" "\ -Return export back-end named after NAME. -NAME is a symbol. Return nil if no such back-end is found. - -\(fn NAME)" nil nil) +Return export backend named after NAME. +NAME is a symbol. Return nil if no such backend is found. +(fn NAME)") (autoload 'org-export-derived-backend-p "ox" "\ Non-nil if BACKEND is derived from one of BACKENDS. -BACKEND is an export back-end, as returned by, e.g., +BACKEND is an export backend, as returned by, e.g., `org-export-create-backend', or a symbol referring to -a registered back-end. BACKENDS is constituted of symbols. - -\(fn BACKEND &rest BACKENDS)" nil nil) +a registered backend. BACKENDS is constituted of symbols. +(fn BACKEND &rest BACKENDS)") (autoload 'org-export-get-environment "ox" "\ Collect export options from the current buffer. -Optional argument BACKEND is an export back-end, as returned by +Optional argument BACKEND is an export backend, as returned by `org-export-create-backend'. When optional argument SUBTREEP is non-nil, assume the export is @@ -3738,24 +2177,27 @@ Third optional argument EXT-PLIST is a property list with external parameters overriding Org default settings, but still inferior to file-local settings. -\(fn &optional BACKEND SUBTREEP EXT-PLIST)" nil nil) - +(fn &optional BACKEND SUBTREEP EXT-PLIST)") (autoload 'org-export-data "ox" "\ -Convert DATA into current back-end format. +Convert DATA into current backend format. DATA is a parse tree, an element or an object or a secondary string. INFO is a plist holding export options. -Return a string. +The `:filter-parse-tree' filters are not applied. -\(fn DATA INFO)" nil nil) +Return a string. +(fn DATA INFO)") (autoload 'org-export-as "ox" "\ Transcode current Org buffer into BACKEND code. -BACKEND is either an export back-end, as returned by, e.g., +See info node `(org)Advanced Export Configuration' for the details of +the transcoding process. + +BACKEND is either an export backend, as returned by, e.g., `org-export-create-backend', or a symbol referring to -a registered back-end. +a registered backend. If narrowing is active in the current buffer, only transcode its narrowed part. @@ -3778,14 +2220,13 @@ still inferior to file-local settings. Return code as a string. -\(fn BACKEND &optional SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST)" nil nil) - +(fn BACKEND &optional SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST)") (autoload 'org-export-string-as "ox" "\ Transcode STRING into BACKEND code. -BACKEND is either an export back-end, as returned by, e.g., +BACKEND is either an export backend, as returned by, e.g., `org-export-create-backend', or a symbol referring to -a registered back-end. +a registered backend. When optional argument BODY-ONLY is non-nil, only return body code, without preamble nor postamble. @@ -3796,42 +2237,38 @@ still inferior to file-local settings. Return code as a string. -\(fn STRING BACKEND &optional BODY-ONLY EXT-PLIST)" nil nil) - +(fn STRING BACKEND &optional BODY-ONLY EXT-PLIST)") (autoload 'org-export-replace-region-by "ox" "\ Replace the active region by its export to BACKEND. -BACKEND is either an export back-end, as returned by, e.g., +BACKEND is either an export backend, as returned by, e.g., `org-export-create-backend', or a symbol referring to -a registered back-end. - -\(fn BACKEND)" nil nil) +a registered backend. +(fn BACKEND)") (autoload 'org-export-insert-default-template "ox" "\ Insert all export keywords with default values at beginning of line. BACKEND is a symbol referring to the name of a registered export -back-end, for which specific export options should be added to +backend, for which specific export options should be added to the template, or `default' for default template. When it is nil, the user will be prompted for a category. If SUBTREEP is non-nil, export configuration will be set up locally for the subtree through node properties. -\(fn &optional BACKEND SUBTREEP)" t nil) - +(fn &optional BACKEND SUBTREEP)" t) (autoload 'org-export-raw-string "ox" "\ Return a raw object containing string S. A raw string is exported as-is, with no additional processing -from the export back-end. - -\(fn S)" nil nil) +from the export backend. +(fn S)") (autoload 'org-export-to-buffer "ox" "\ Call `org-export-as' with output to a specified buffer. -BACKEND is either an export back-end, as returned by, e.g., +BACKEND is either an export backend, as returned by, e.g., `org-export-create-backend', or a symbol referring to -a registered back-end. +a registered backend. BUFFER is the name of the output buffer. If it already exists, it will be erased first, otherwise, it will be created. @@ -3848,7 +2285,7 @@ see. Optional argument POST-PROCESS is a function which should accept no argument. It is always called within the current process, -from BUFFER, with point at its beginning. Export back-ends can +from BUFFER, with point at its beginning. Export backends can use it to set a major mode there, e.g., (defun org-latex-export-as-latex @@ -3856,23 +2293,21 @@ use it to set a major mode there, e.g., (interactive) (org-export-to-buffer \\='latex \"*Org LATEX Export*\" async subtreep visible-only body-only ext-plist - #\\='LaTeX-mode)) + (major-mode-remap \\='latex-mode))) When expressed as an anonymous function, using `lambda', POST-PROCESS needs to be quoted. This function returns BUFFER. -\(fn BACKEND BUFFER &optional ASYNC SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST POST-PROCESS)" nil nil) - -(function-put 'org-export-to-buffer 'lisp-indent-function '2) - +(fn BACKEND BUFFER &optional ASYNC SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST POST-PROCESS)") +(function-put 'org-export-to-buffer 'lisp-indent-function 2) (autoload 'org-export-to-file "ox" "\ Call `org-export-as' with output to a specified file. -BACKEND is either an export back-end, as returned by, e.g., +BACKEND is either an export backend, as returned by, e.g., `org-export-create-backend', or a symbol referring to -a registered back-end. FILE is the name of the output file, as +a registered backend. FILE is the name of the output file, as a string. A non-nil optional argument ASYNC means the process should happen @@ -3885,7 +2320,7 @@ see. Optional argument POST-PROCESS is called with FILE as its argument and happens asynchronously when ASYNC is non-nil. It -has to return a file name, or nil. Export back-ends can use this +has to return a file name, or nil. Export backends can use this to send the output file through additional processing, e.g, (defun org-latex-export-to-latex @@ -3902,10 +2337,8 @@ POST-PROCESS needs to be quoted. The function returns either a file name returned by POST-PROCESS, or FILE. -\(fn BACKEND FILE &optional ASYNC SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST POST-PROCESS)" nil nil) - -(function-put 'org-export-to-file 'lisp-indent-function '2) - +(fn BACKEND FILE &optional ASYNC SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST POST-PROCESS)") +(function-put 'org-export-to-file 'lisp-indent-function 2) (autoload 'org-export-dispatch "ox" "\ Export dispatcher for Org mode. @@ -3925,27 +2358,15 @@ set of options used back then, on the current buffer. When ARG is `\\[universal-argument] \\[universal-argument]', display the asynchronous export stack. -\(fn &optional ARG)" t nil) - -;;;### (autoloads "actual autoloads are elsewhere" "ox" "ox.el" (0 -;;;;;; 0 0 0)) -;;; Generated autoloads from ox.el - -(register-definition-prefixes "ox" '("org-")) +(fn &optional ARG)" t) -;;;*** - -;;;*** -;;;### (autoloads nil "ox-ascii" "ox-ascii.el" "b1d121699775471a1ed1d342885d531e") ;;; Generated autoloads from ox-ascii.el (autoload 'org-ascii-convert-region-to-ascii "ox-ascii" "\ -Assume region has Org syntax, and convert it to plain ASCII." t nil) - +Assume region has Org syntax, and convert it to plain ASCII." t) (autoload 'org-ascii-convert-region-to-utf8 "ox-ascii" "\ -Assume region has Org syntax, and convert it to UTF-8." t nil) - +Assume region has Org syntax, and convert it to UTF-8." t) (autoload 'org-ascii-export-as-ascii "ox-ascii" "\ Export current buffer to a text buffer. @@ -3976,8 +2397,7 @@ Export is done in a buffer named \"*Org ASCII Export*\", which will be displayed when `org-export-show-temporary-export-buffer' is non-nil. -\(fn &optional ASYNC SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST)" t nil) - +(fn &optional ASYNC SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST)" t) (autoload 'org-ascii-export-to-ascii "ox-ascii" "\ Export current buffer to a text file. @@ -4006,8 +2426,7 @@ file-local settings. Return output file's name. -\(fn &optional ASYNC SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST)" t nil) - +(fn &optional ASYNC SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST)" t) (autoload 'org-ascii-publish-to-ascii "ox-ascii" "\ Publish an Org file to ASCII. @@ -4017,8 +2436,7 @@ publishing directory. Return output file name. -\(fn PLIST FILENAME PUB-DIR)" nil nil) - +(fn PLIST FILENAME PUB-DIR)") (autoload 'org-ascii-publish-to-latin1 "ox-ascii" "\ Publish an Org file to Latin-1. @@ -4028,8 +2446,7 @@ publishing directory. Return output file name. -\(fn PLIST FILENAME PUB-DIR)" nil nil) - +(fn PLIST FILENAME PUB-DIR)") (autoload 'org-ascii-publish-to-utf8 "ox-ascii" "\ Publish an org file to UTF-8. @@ -4039,40 +2456,29 @@ publishing directory. Return output file name. -\(fn PLIST FILENAME PUB-DIR)" nil nil) - -;;;### (autoloads "actual autoloads are elsewhere" "ox-ascii" "ox-ascii.el" -;;;;;; (0 0 0 0)) -;;; Generated autoloads from ox-ascii.el - -(register-definition-prefixes "ox-ascii" '("org-ascii-")) +(fn PLIST FILENAME PUB-DIR)") -;;;*** - -;;;*** -;;;### (autoloads nil "ox-beamer" "ox-beamer.el" "916beb92aa6eda7946d6260849031bb1") ;;; Generated autoloads from ox-beamer.el (autoload 'org-beamer-mode "ox-beamer" "\ Support for editing Beamer oriented Org mode files. This is a minor mode. If called interactively, toggle the `Org-Beamer -mode' mode. If the prefix argument is positive, enable the mode, and -if it is zero or negative, disable the mode. +mode' mode. If the prefix argument is positive, enable the mode, and if +it is zero or negative, disable the mode. If called from Lisp, toggle the mode if ARG is `toggle'. Enable the -mode if ARG is nil, omitted, or is a positive number. Disable the -mode if ARG is a negative number. +mode if ARG is nil, omitted, or is a positive number. Disable the mode +if ARG is a negative number. To check whether the minor mode is enabled in the current buffer, -evaluate `org-beamer-mode'. +evaluate the variable `org-beamer-mode'. The mode's hook is called both when the mode is enabled and when it is disabled. -\(fn &optional ARG)" t nil) - +(fn &optional ARG)" t) (autoload 'org-beamer-export-as-latex "ox-beamer" "\ Export current buffer as a Beamer buffer. @@ -4103,8 +2509,7 @@ Export is done in a buffer named \"*Org BEAMER Export*\", which will be displayed when `org-export-show-temporary-export-buffer' is non-nil. -\(fn &optional ASYNC SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST)" t nil) - +(fn &optional ASYNC SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST)" t) (autoload 'org-beamer-export-to-latex "ox-beamer" "\ Export current buffer as a Beamer presentation (tex). @@ -4133,8 +2538,7 @@ file-local settings. Return output file's name. -\(fn &optional ASYNC SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST)" t nil) - +(fn &optional ASYNC SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST)" t) (autoload 'org-beamer-export-to-pdf "ox-beamer" "\ Export current buffer as a Beamer presentation (PDF). @@ -4163,8 +2567,7 @@ file-local settings. Return PDF file's name. -\(fn &optional ASYNC SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST)" t nil) - +(fn &optional ASYNC SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST)" t) (autoload 'org-beamer-select-environment "ox-beamer" "\ Select the environment to be used by beamer for this entry. While this uses (for convenience) a tag selection interface, the @@ -4172,8 +2575,7 @@ result of this command will be that the BEAMER_env *property* of the entry is set. In addition to this, the command will also set a tag as a visual -aid, but the tag does not have any semantic meaning." t nil) - +aid, but the tag does not have any semantic meaning." t) (autoload 'org-beamer-publish-to-latex "ox-beamer" "\ Publish an Org file to a Beamer presentation (LaTeX). @@ -4183,8 +2585,7 @@ publishing directory. Return output file name. -\(fn PLIST FILENAME PUB-DIR)" nil nil) - +(fn PLIST FILENAME PUB-DIR)") (autoload 'org-beamer-publish-to-pdf "ox-beamer" "\ Publish an Org file to a Beamer presentation (PDF, via LaTeX). @@ -4194,27 +2595,14 @@ publishing directory. Return output file name. -\(fn PLIST FILENAME PUB-DIR)" nil nil) - -;;;### (autoloads "actual autoloads are elsewhere" "ox-beamer" "ox-beamer.el" -;;;;;; (0 0 0 0)) -;;; Generated autoloads from ox-beamer.el - -(register-definition-prefixes "ox-beamer" '("org-beamer-")) +(fn PLIST FILENAME PUB-DIR)") -;;;*** - -;;;*** -;;;### (autoloads nil "ox-html" "ox-html.el" "b38d114d65a837c2aa75e95506873f5f") ;;; Generated autoloads from ox-html.el (put 'org-html-head-include-default-style 'safe-local-variable 'booleanp) - (put 'org-html-head 'safe-local-variable 'stringp) - (put 'org-html-head-extra 'safe-local-variable 'stringp) - (autoload 'org-html-htmlize-generate-css "ox-html" "\ Create the CSS for all font definitions in the current Emacs session. Use this to create face definitions in your CSS style file that can then @@ -4223,10 +2611,12 @@ This command just produces a buffer that contains class definitions for all faces used in the current Emacs session. You can copy and paste the ones you need into your CSS file. +The face definitions are prepended with +`org-html-htmlize-font-prefix'. + If you then set `org-html-htmlize-output-type' to `css', calls to the function `org-html-htmlize-region-for-paste' will -produce code that uses these same face definitions." t nil) - +produce code that uses these same face definitions." t) (autoload 'org-html-export-as-html "ox-html" "\ Export current buffer to an HTML buffer. @@ -4257,14 +2647,12 @@ Export is done in a buffer named \"*Org HTML Export*\", which will be displayed when `org-export-show-temporary-export-buffer' is non-nil. -\(fn &optional ASYNC SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST)" t nil) - +(fn &optional ASYNC SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST)" t) (autoload 'org-html-convert-region-to-html "ox-html" "\ Assume the current region has Org syntax, and convert it to HTML. This can be used in any buffer. For example, you can write an itemized list in Org syntax in an HTML buffer and use this command -to convert it." t nil) - +to convert it." t) (autoload 'org-html-export-to-html "ox-html" "\ Export current buffer to a HTML file. @@ -4293,8 +2681,7 @@ file-local settings. Return output file's name. -\(fn &optional ASYNC SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST)" t nil) - +(fn &optional ASYNC SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST)" t) (autoload 'org-html-publish-to-html "ox-html" "\ Publish an org file to HTML. @@ -4304,147 +2691,13 @@ publishing directory. Return output file name. -\(fn PLIST FILENAME PUB-DIR)" nil nil) - -;;;### (autoloads "actual autoloads are elsewhere" "ox-html" "ox-html.el" -;;;;;; (0 0 0 0)) -;;; Generated autoloads from ox-html.el - -(register-definition-prefixes "ox-html" '("org-html-")) - -;;;*** - -;;;*** - -;;;### (autoloads nil "ox-icalendar" "ox-icalendar.el" "a8aa53e0e56193d591234d0471e1f15e") -;;; Generated autoloads from ox-icalendar.el - -(autoload 'org-icalendar-export-to-ics "ox-icalendar" "\ -Export current buffer to an iCalendar file. - -If narrowing is active in the current buffer, only export its -narrowed part. - -If a region is active, export that region. - -A non-nil optional argument ASYNC means the process should happen -asynchronously. The resulting file should be accessible through -the `org-export-stack' interface. - -When optional argument SUBTREEP is non-nil, export the sub-tree -at point, extracting information from the headline properties -first. - -When optional argument VISIBLE-ONLY is non-nil, don't export -contents of hidden elements. - -When optional argument BODY-ONLY is non-nil, only write code -between \"BEGIN:VCALENDAR\" and \"END:VCALENDAR\". - -Return ICS file name. - -\(fn &optional ASYNC SUBTREEP VISIBLE-ONLY BODY-ONLY)" t nil) - -(autoload 'org-icalendar-export-agenda-files "ox-icalendar" "\ -Export all agenda files to iCalendar files. -When optional argument ASYNC is non-nil, export happens in an -external process. - -\(fn &optional ASYNC)" t nil) - -(autoload 'org-icalendar-combine-agenda-files "ox-icalendar" "\ -Combine all agenda files into a single iCalendar file. - -A non-nil optional argument ASYNC means the process should happen -asynchronously. The resulting file should be accessible through -the `org-export-stack' interface. - -The file is stored under the name chosen in -`org-icalendar-combined-agenda-file'. +(fn PLIST FILENAME PUB-DIR)") -\(fn &optional ASYNC)" t nil) -;;;### (autoloads "actual autoloads are elsewhere" "ox-icalendar" -;;;;;; "ox-icalendar.el" (0 0 0 0)) ;;; Generated autoloads from ox-icalendar.el -(register-definition-prefixes "ox-icalendar" '("org-icalendar-")) - -;;;*** - -;;;*** - -;;;### (autoloads nil "ox-koma-letter" "ox-koma-letter.el" (0 0 0 -;;;;;; 0)) -;;; Generated autoloads from ox-koma-letter.el - -(autoload 'org-koma-letter-export-as-latex "ox-koma-letter" "\ -Export current buffer as a KOMA Scrlttr2 letter. - -If narrowing is active in the current buffer, only export its -narrowed part. - -If a region is active, export that region. - -A non-nil optional argument ASYNC means the process should happen -asynchronously. The resulting buffer should be accessible -through the `org-export-stack' interface. - -When optional argument SUBTREEP is non-nil, export the sub-tree -at point, extracting information from the headline properties -first. - -When optional argument VISIBLE-ONLY is non-nil, don't export -contents of hidden elements. - -When optional argument BODY-ONLY is non-nil, only write code -between \"\\begin{letter}\" and \"\\end{letter}\". - -EXT-PLIST, when provided, is a property list with external -parameters overriding Org default settings, but still inferior to -file-local settings. - -Export is done in a buffer named \"*Org KOMA-LETTER Export*\". It -will be displayed if `org-export-show-temporary-export-buffer' is -non-nil. - -\(fn &optional ASYNC SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST)" t nil) - -(autoload 'org-koma-letter-export-to-latex "ox-koma-letter" "\ -Export current buffer as a KOMA Scrlttr2 letter (tex). - -If narrowing is active in the current buffer, only export its -narrowed part. - -If a region is active, export that region. - -A non-nil optional argument ASYNC means the process should happen -asynchronously. The resulting file should be accessible through -the `org-export-stack' interface. - -When optional argument SUBTREEP is non-nil, export the sub-tree -at point, extracting information from the headline properties -first. - -When optional argument VISIBLE-ONLY is non-nil, don't export -contents of hidden elements. - -When optional argument BODY-ONLY is non-nil, only write code -between \"\\begin{letter}\" and \"\\end{letter}\". - -EXT-PLIST, when provided, is a property list with external -parameters overriding Org default settings, but still inferior to -file-local settings. - -When optional argument PUB-DIR is set, use it as the publishing -directory. - -Return output file's name. - -\(fn &optional ASYNC SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST)" t nil) - -(autoload 'org-koma-letter-export-to-pdf "ox-koma-letter" "\ -Export current buffer as a KOMA Scrlttr2 letter (pdf). +(autoload 'org-icalendar-export-to-ics "ox-icalendar" "\ +Export current buffer to an iCalendar file. If narrowing is active in the current buffer, only export its narrowed part. @@ -4463,21 +2716,30 @@ When optional argument VISIBLE-ONLY is non-nil, don't export contents of hidden elements. When optional argument BODY-ONLY is non-nil, only write code -between \"\\begin{letter}\" and \"\\end{letter}\". +between \"BEGIN:VCALENDAR\" and \"END:VCALENDAR\". -EXT-PLIST, when provided, is a property list with external -parameters overriding Org default settings, but still inferior to -file-local settings. +Return ICS file name. -Return PDF file's name. +(fn &optional ASYNC SUBTREEP VISIBLE-ONLY BODY-ONLY)" t) +(autoload 'org-icalendar-export-agenda-files "ox-icalendar" "\ +Export all agenda files to iCalendar files. +When optional argument ASYNC is non-nil, export happens in an +external process. + +(fn &optional ASYNC)" t) +(autoload 'org-icalendar-combine-agenda-files "ox-icalendar" "\ +Combine all agenda files into a single iCalendar file. + +A non-nil optional argument ASYNC means the process should happen +asynchronously. The resulting file should be accessible through +the `org-export-stack' interface. -\(fn &optional ASYNC SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST)" t nil) +The file is stored under the name chosen in +`org-icalendar-combined-agenda-file'. -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ox-koma-letter" '("org-koma-letter-"))) +(fn &optional ASYNC)" t) -;;;*** -;;;### (autoloads nil "ox-latex" "ox-latex.el" "8441479c3b5a31610ff225133ebeaefb") ;;; Generated autoloads from ox-latex.el (autoload 'org-latex-make-preamble "ox-latex" "\ @@ -4489,8 +2751,7 @@ non-nil, only includes packages relevant to image generation, as specified in `org-latex-default-packages-alist' or `org-latex-packages-alist'. -\(fn INFO &optional TEMPLATE SNIPPET\\=\\?)" nil nil) - +(fn INFO &optional TEMPLATE SNIPPET?)") (autoload 'org-latex-export-as-latex "ox-latex" "\ Export current buffer as a LaTeX buffer. @@ -4521,14 +2782,12 @@ Export is done in a buffer named \"*Org LATEX Export*\", which will be displayed when `org-export-show-temporary-export-buffer' is non-nil. -\(fn &optional ASYNC SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST)" t nil) - +(fn &optional ASYNC SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST)" t) (autoload 'org-latex-convert-region-to-latex "ox-latex" "\ Assume the current region has Org syntax, and convert it to LaTeX. This can be used in any buffer. For example, you can write an itemized list in Org syntax in an LaTeX buffer and use this -command to convert it." t nil) - +command to convert it." t) (autoload 'org-latex-export-to-latex "ox-latex" "\ Export current buffer to a LaTeX file. @@ -4555,8 +2814,7 @@ EXT-PLIST, when provided, is a property list with external parameters overriding Org default settings, but still inferior to file-local settings. -\(fn &optional ASYNC SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST)" t nil) - +(fn &optional ASYNC SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST)" t) (autoload 'org-latex-export-to-pdf "ox-latex" "\ Export current buffer to LaTeX then process through to PDF. @@ -4585,8 +2843,7 @@ file-local settings. Return PDF file's name. -\(fn &optional ASYNC SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST)" t nil) - +(fn &optional ASYNC SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST)" t) (autoload 'org-latex-publish-to-latex "ox-latex" "\ Publish an Org file to LaTeX. @@ -4596,8 +2853,7 @@ publishing directory. Return output file name. -\(fn PLIST FILENAME PUB-DIR)" nil nil) - +(fn PLIST FILENAME PUB-DIR)") (autoload 'org-latex-publish-to-pdf "ox-latex" "\ Publish an Org file to PDF (via LaTeX). @@ -4607,26 +2863,9 @@ publishing directory. Return output file name. -\(fn PLIST FILENAME PUB-DIR)" nil nil) - -;;;### (autoloads "actual autoloads are elsewhere" "ox-latex" "ox-latex.el" -;;;;;; (0 0 0 0)) -;;; Generated autoloads from ox-latex.el - -(register-definition-prefixes "ox-latex" '("org-")) - -;;;*** - -;;;*** - -;;;### (autoloads nil "ox-man" "ox-man.el" (0 0 0 0)) -;;; Generated autoloads from ox-man.el - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ox-man" '("org-man-"))) +(fn PLIST FILENAME PUB-DIR)") -;;;*** -;;;### (autoloads nil "ox-md" "ox-md.el" "c2cd34dc140f7b567dad67fc3a258401") ;;; Generated autoloads from ox-md.el (autoload 'org-md-export-as-markdown "ox-md" "\ @@ -4652,14 +2891,12 @@ Export is done in a buffer named \"*Org MD Export*\", which will be displayed when `org-export-show-temporary-export-buffer' is non-nil. -\(fn &optional ASYNC SUBTREEP VISIBLE-ONLY)" t nil) - +(fn &optional ASYNC SUBTREEP VISIBLE-ONLY)" t) (autoload 'org-md-convert-region-to-md "ox-md" "\ Assume the current region has Org syntax, and convert it to Markdown. This can be used in any buffer. For example, you can write an itemized list in Org syntax in a Markdown buffer and use -this command to convert it." t nil) - +this command to convert it." t) (autoload 'org-md-export-to-markdown "ox-md" "\ Export current buffer to a Markdown file. @@ -4681,8 +2918,7 @@ contents of hidden elements. Return output file's name. -\(fn &optional ASYNC SUBTREEP VISIBLE-ONLY)" t nil) - +(fn &optional ASYNC SUBTREEP VISIBLE-ONLY)" t) (autoload 'org-md-publish-to-md "ox-md" "\ Publish an org file to Markdown. @@ -4692,23 +2928,12 @@ publishing directory. Return output file name. -\(fn PLIST FILENAME PUB-DIR)" nil nil) - -;;;### (autoloads "actual autoloads are elsewhere" "ox-md" "ox-md.el" -;;;;;; (0 0 0 0)) -;;; Generated autoloads from ox-md.el - -(register-definition-prefixes "ox-md" '("org-md-")) +(fn PLIST FILENAME PUB-DIR)") -;;;*** - -;;;*** -;;;### (autoloads nil "ox-odt" "ox-odt.el" "134ec529b44773086acf2218c4bdb110") ;;; Generated autoloads from ox-odt.el (put 'org-odt-preferred-output-format 'safe-local-variable 'stringp) - (autoload 'org-odt-export-as-odf "ox-odt" "\ Export LATEX-FRAG as OpenDocument formula file ODF-FILE. Use `org-create-math-formula' to convert LATEX-FRAG first to @@ -4718,13 +2943,11 @@ region. If no LaTeX fragments are found, prompt for it. Push MathML source to kill ring depending on the value of `org-export-copy-to-kill-ring'. -\(fn LATEX-FRAG &optional ODF-FILE)" t nil) - +(fn LATEX-FRAG &optional ODF-FILE)" t) (autoload 'org-odt-export-as-odf-and-open "ox-odt" "\ Export LaTeX fragment as OpenDocument formula and immediately open it. Use `org-odt-export-as-odf' to read LaTeX fragment and OpenDocument -formula file." t nil) - +formula file." t) (autoload 'org-odt-export-to-odt "ox-odt" "\ Export current buffer to a ODT file. @@ -4750,8 +2973,7 @@ file-local settings. Return output file's name. -\(fn &optional ASYNC SUBTREEP VISIBLE-ONLY EXT-PLIST)" t nil) - +(fn &optional ASYNC SUBTREEP VISIBLE-ONLY EXT-PLIST)" t) (autoload 'org-odt-convert "ox-odt" "\ Convert IN-FILE to format OUT-FMT using a command line converter. IN-FILE is the file to be converted. If unspecified, it defaults @@ -4760,19 +2982,9 @@ format. Use `org-odt-convert-process' as the converter. If OPEN is non-nil then the newly converted file is opened using `org-open-file'. -\(fn &optional IN-FILE OUT-FMT OPEN)" t nil) - -;;;### (autoloads "actual autoloads are elsewhere" "ox-odt" "ox-odt.el" -;;;;;; (0 0 0 0)) -;;; Generated autoloads from ox-odt.el - -(register-definition-prefixes "ox-odt" '("org-odt-")) +(fn &optional IN-FILE OUT-FMT OPEN)" t) -;;;*** - -;;;*** -;;;### (autoloads nil "ox-org" "ox-org.el" "919f9ecd48fe93f1edbe7411cf2a35ff") ;;; Generated autoloads from ox-org.el (autoload 'org-org-export-as-org "ox-org" "\ @@ -4805,8 +3017,7 @@ Export is done in a buffer named \"*Org ORG Export*\", which will be displayed when `org-export-show-temporary-export-buffer' is non-nil. -\(fn &optional ASYNC SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST)" t nil) - +(fn &optional ASYNC SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST)" t) (autoload 'org-org-export-to-org "ox-org" "\ Export current buffer to an Org file. @@ -4835,8 +3046,7 @@ file-local settings. Return output file name. -\(fn &optional ASYNC SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST)" t nil) - +(fn &optional ASYNC SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST)" t) (autoload 'org-org-publish-to-org "ox-org" "\ Publish an Org file to Org. @@ -4846,23 +3056,12 @@ publishing directory. Return output file name. -\(fn PLIST FILENAME PUB-DIR)" nil nil) - -;;;### (autoloads "actual autoloads are elsewhere" "ox-org" "ox-org.el" -;;;;;; (0 0 0 0)) -;;; Generated autoloads from ox-org.el - -(register-definition-prefixes "ox-org" '("org-org-")) +(fn PLIST FILENAME PUB-DIR)") -;;;*** - -;;;*** -;;;### (autoloads nil "ox-publish" "ox-publish.el" "9694010c2d9013835a5b52b89979422b") ;;; Generated autoloads from ox-publish.el (defalias 'org-publish-project 'org-publish) - (autoload 'org-publish "ox-publish" "\ Publish PROJECT. @@ -4873,8 +3072,7 @@ When optional argument FORCE is non-nil, force publishing all files in PROJECT. With a non-nil optional argument ASYNC, publishing will be done asynchronously, in another process. -\(fn PROJECT &optional FORCE ASYNC)" t nil) - +(fn PROJECT &optional FORCE ASYNC)" t) (autoload 'org-publish-all "ox-publish" "\ Publish all projects. With prefix argument FORCE, remove all files in the timestamp @@ -4882,34 +3080,22 @@ directory and force publishing all projects. With a non-nil optional argument ASYNC, publishing will be done asynchronously, in another process. -\(fn &optional FORCE ASYNC)" t nil) - +(fn &optional FORCE ASYNC)" t) (autoload 'org-publish-current-file "ox-publish" "\ Publish the current file. With prefix argument FORCE, force publish the file. When optional argument ASYNC is non-nil, publishing will be done asynchronously, in another process. -\(fn &optional FORCE ASYNC)" t nil) - +(fn &optional FORCE ASYNC)" t) (autoload 'org-publish-current-project "ox-publish" "\ Publish the project associated with the current file. With a prefix argument, force publishing of all files in the project. -\(fn &optional FORCE ASYNC)" t nil) - -;;;### (autoloads "actual autoloads are elsewhere" "ox-publish" "ox-publish.el" -;;;;;; (0 0 0 0)) -;;; Generated autoloads from ox-publish.el - -(register-definition-prefixes "ox-publish" '("org-publish-")) +(fn &optional FORCE ASYNC)" t) -;;;*** - -;;;*** -;;;### (autoloads nil "ox-texinfo" "ox-texinfo.el" "843a236604ba657808a09cac3c77fa5a") ;;; Generated autoloads from ox-texinfo.el (autoload 'org-texinfo-export-to-texinfo "ox-texinfo" "\ @@ -4940,8 +3126,7 @@ file-local settings. Return output file's name. -\(fn &optional ASYNC SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST)" t nil) - +(fn &optional ASYNC SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST)" t) (autoload 'org-texinfo-export-to-info "ox-texinfo" "\ Export current buffer to Texinfo then process through to INFO. @@ -4970,8 +3155,7 @@ file-local settings. Return INFO file's name. -\(fn &optional ASYNC SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST)" t nil) - +(fn &optional ASYNC SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST)" t) (autoload 'org-texinfo-publish-to-texinfo "ox-texinfo" "\ Publish an org file to Texinfo. @@ -4981,253 +3165,23 @@ publishing directory. Return output file name. -\(fn PLIST FILENAME PUB-DIR)" nil nil) - +(fn PLIST FILENAME PUB-DIR)") (autoload 'org-texinfo-convert-region-to-texinfo "ox-texinfo" "\ Assume the current region has Org syntax, and convert it to Texinfo. This can be used in any buffer. For example, you can write an itemized list in Org syntax in an Texinfo buffer and use this -command to convert it." t nil) +command to convert it." t) -;;;### (autoloads nil "ox" "ox.el" (0 0 0 0)) -;;; Generated autoloads from ox.el - -(autoload 'org-export-get-backend "ox" "\ -Return export back-end named after NAME. -NAME is a symbol. Return nil if no such back-end is found. - -\(fn NAME)" nil nil) - -(autoload 'org-export-derived-backend-p "ox" "\ -Non-nil if BACKEND is derived from one of BACKENDS. -BACKEND is an export back-end, as returned by, e.g., -`org-export-create-backend', or a symbol referring to -a registered back-end. BACKENDS is constituted of symbols. - -\(fn BACKEND &rest BACKENDS)" nil nil) - -(autoload 'org-export-get-environment "ox" "\ -Collect export options from the current buffer. - -Optional argument BACKEND is an export back-end, as returned by -`org-export-create-backend'. - -When optional argument SUBTREEP is non-nil, assume the export is -done against the current sub-tree. - -Third optional argument EXT-PLIST is a property list with -external parameters overriding Org default settings, but still -inferior to file-local settings. - -\(fn &optional BACKEND SUBTREEP EXT-PLIST)" nil nil) - -(autoload 'org-export-data "ox" "\ -Convert DATA into current back-end format. - -DATA is a parse tree, an element or an object or a secondary -string. INFO is a plist holding export options. - -Return a string. - -\(fn DATA INFO)" nil nil) - -(autoload 'org-export-as "ox" "\ -Transcode current Org buffer into BACKEND code. - -BACKEND is either an export back-end, as returned by, e.g., -`org-export-create-backend', or a symbol referring to -a registered back-end. - -If narrowing is active in the current buffer, only transcode its -narrowed part. - -If a region is active, transcode that region. - -When optional argument SUBTREEP is non-nil, transcode the -sub-tree at point, extracting information from the headline -properties first. - -When optional argument VISIBLE-ONLY is non-nil, don't export -contents of hidden elements. - -When optional argument BODY-ONLY is non-nil, only return body -code, without surrounding template. - -Optional argument EXT-PLIST, when provided, is a property list -with external parameters overriding Org default settings, but -still inferior to file-local settings. - -Return code as a string. - -\(fn BACKEND &optional SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST)" nil nil) - -(autoload 'org-export-string-as "ox" "\ -Transcode STRING into BACKEND code. - -BACKEND is either an export back-end, as returned by, e.g., -`org-export-create-backend', or a symbol referring to -a registered back-end. +;;; End of scraped data -When optional argument BODY-ONLY is non-nil, only return body -code, without preamble nor postamble. - -Optional argument EXT-PLIST, when provided, is a property list -with external parameters overriding Org default settings, but -still inferior to file-local settings. - -Return code as a string. - -\(fn STRING BACKEND &optional BODY-ONLY EXT-PLIST)" nil nil) - -(autoload 'org-export-replace-region-by "ox" "\ -Replace the active region by its export to BACKEND. -BACKEND is either an export back-end, as returned by, e.g., -`org-export-create-backend', or a symbol referring to -a registered back-end. - -\(fn BACKEND)" nil nil) - -(autoload 'org-export-insert-default-template "ox" "\ -Insert all export keywords with default values at beginning of line. - -BACKEND is a symbol referring to the name of a registered export -back-end, for which specific export options should be added to -the template, or `default' for default template. When it is nil, -the user will be prompted for a category. - -If SUBTREEP is non-nil, export configuration will be set up -locally for the subtree through node properties. - -\(fn &optional BACKEND SUBTREEP)" t nil) - -(autoload 'org-export-raw-string "ox" "\ -Return a raw object containing string S. -A raw string is exported as-is, with no additional processing -from the export back-end. - -\(fn S)" nil nil) - -(autoload 'org-export-to-buffer "ox" "\ -Call `org-export-as' with output to a specified buffer. - -BACKEND is either an export back-end, as returned by, e.g., -`org-export-create-backend', or a symbol referring to -a registered back-end. - -BUFFER is the name of the output buffer. If it already exists, -it will be erased first, otherwise, it will be created. - -A non-nil optional argument ASYNC means the process should happen -asynchronously. The resulting buffer should then be accessible -through the `org-export-stack' interface. When ASYNC is nil, the -buffer is displayed if `org-export-show-temporary-export-buffer' -is non-nil. - -Optional arguments SUBTREEP, VISIBLE-ONLY, BODY-ONLY and -EXT-PLIST are similar to those used in `org-export-as', which -see. - -Optional argument POST-PROCESS is a function which should accept -no argument. It is always called within the current process, -from BUFFER, with point at its beginning. Export back-ends can -use it to set a major mode there, e.g., - - (defun org-latex-export-as-latex - (&optional async subtreep visible-only body-only ext-plist) - (interactive) - (org-export-to-buffer \\='latex \"*Org LATEX Export*\" - async subtreep visible-only body-only ext-plist - #\\='LaTeX-mode)) - -When expressed as an anonymous function, using `lambda', -POST-PROCESS needs to be quoted. - -This function returns BUFFER. - -\(fn BACKEND BUFFER &optional ASYNC SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST POST-PROCESS)" nil nil) - -(function-put 'org-export-to-buffer 'lisp-indent-function '2) - -(autoload 'org-export-to-file "ox" "\ -Call `org-export-as' with output to a specified file. - -BACKEND is either an export back-end, as returned by, e.g., -`org-export-create-backend', or a symbol referring to -a registered back-end. FILE is the name of the output file, as -a string. - -A non-nil optional argument ASYNC means the process should happen -asynchronously. The resulting buffer will then be accessible -through the `org-export-stack' interface. - -Optional arguments SUBTREEP, VISIBLE-ONLY, BODY-ONLY and -EXT-PLIST are similar to those used in `org-export-as', which -see. - -Optional argument POST-PROCESS is called with FILE as its -argument and happens asynchronously when ASYNC is non-nil. It -has to return a file name, or nil. Export back-ends can use this -to send the output file through additional processing, e.g, - - (defun org-latex-export-to-latex - (&optional async subtreep visible-only body-only ext-plist) - (interactive) - (let ((outfile (org-export-output-file-name \".tex\" subtreep))) - (org-export-to-file \\='latex outfile - async subtreep visible-only body-only ext-plist - #\\='org-latex-compile))) - -When expressed as an anonymous function, using `lambda', -POST-PROCESS needs to be quoted. - -The function returns either a file name returned by POST-PROCESS, -or FILE. - -\(fn BACKEND FILE &optional ASYNC SUBTREEP VISIBLE-ONLY BODY-ONLY EXT-PLIST POST-PROCESS)" nil nil) - -(function-put 'org-export-to-file 'lisp-indent-function '2) - -(autoload 'org-export-dispatch "ox" "\ -Export dispatcher for Org mode. - -It provides an access to common export related tasks in a buffer. -Its interface comes in two flavors: standard and expert. - -While both share the same set of bindings, only the former -displays the valid keys associations in a dedicated buffer. -Scrolling (resp. line-wise motion) in this buffer is done with -SPC and DEL (resp. C-n and C-p) keys. - -Set variable `org-export-dispatch-use-expert-ui' to switch to one -flavor or the other. - -When ARG is `\\[universal-argument]', repeat the last export action, with the same -set of options used back then, on the current buffer. - -When ARG is `\\[universal-argument] \\[universal-argument]', display the asynchronous export stack. - -\(fn &optional ARG)" t nil) - -(if (fboundp 'register-definition-prefixes) (register-definition-prefixes "ox" '("org-"))) - -;;;*** - (provide 'org-loaddefs) - -;;;### (autoloads "actual autoloads are elsewhere" "ox-texinfo" "ox-texinfo.el" -;;;;;; (0 0 0 0)) -;;; Generated autoloads from ox-texinfo.el -(register-definition-prefixes "ox-texinfo" '("org-texinfo-")) - -;;;*** - -;;;*** - ;; Local Variables: ;; version-control: never ;; no-byte-compile: t ;; no-update-autoloads: t -;; coding: utf-8 +;; no-native-compile: t +;; coding: utf-8-emacs-unix ;; End: + ;;; org-loaddefs.el ends here diff --git a/elpa/org-9.6.7/org-macro.el b/elpa/org-9.7.17/org-macro.el similarity index 90% rename from elpa/org-9.6.7/org-macro.el rename to elpa/org-9.7.17/org-macro.el index 481e431c..d2134353 100644 --- a/elpa/org-9.6.7/org-macro.el +++ b/elpa/org-9.7.17/org-macro.el @@ -1,9 +1,9 @@ ;;; org-macro.el --- Macro Replacement Code for Org -*- lexical-binding: t; -*- -;; Copyright (C) 2013-2023 Free Software Foundation, Inc. +;; Copyright (C) 2013-2024 Free Software Foundation, Inc. ;; Author: Nicolas Goaziou -;; Keywords: outlines, hypermedia, calendar, wp +;; Keywords: outlines, hypermedia, calendar, text ;; This file is part of GNU Emacs. @@ -57,14 +57,17 @@ (declare-function org-collect-keywords "org" (keywords &optional unique directory)) (declare-function org-element-at-point "org-element" (&optional pom cached-only)) (declare-function org-element-context "org-element" (&optional element)) -(declare-function org-element-copy "org-element" (datum)) +(declare-function org-element-copy "org-element-ast" (datum)) (declare-function org-element-macro-parser "org-element" ()) (declare-function org-element-keyword-parser "org-element" (limit affiliated)) -(declare-function org-element-put-property "org-element" (element property value)) +(declare-function org-element-put-property "org-element-ast" (node property value)) (declare-function org-element-parse-secondary-string "org-element" (string restriction &optional parent)) -(declare-function org-element-property "org-element" (property element)) +(declare-function org-element-property "org-element-ast" (property node)) +(declare-function org-element-begin "org-element" (node)) +(declare-function org-element-end "org-element" (node)) (declare-function org-element-restriction "org-element" (element)) -(declare-function org-element-type "org-element" (element)) +(declare-function org-element-type "org-element-ast" (node &optional anonymous)) +(declare-function org-element-type-p "org-element-ast" (node types)) (declare-function org-entry-get "org" (pom property &optional inherit literal-nil)) (declare-function org-file-contents "org" (file &optional noerror nocache)) (declare-function org-in-commented-heading-p "org" (&optional no-inheritance element)) @@ -109,6 +112,13 @@ previous one, unless VALUE is nil. Return the updated list." (let ((new-templates nil)) (pcase-dolist (`(,name . ,value) templates) (let ((old-definition (assoc name new-templates))) + ;; This code can be evaluated unconditionally, as a part of + ;; loading Org mode. We *must not* evaluate any code present + ;; inside the Org buffer while loading. Org buffers may come + ;; from various sources, like received email messages from + ;; potentially malicious senders. Org mode might be used to + ;; preview such messages and no code evaluation from inside the + ;; received Org text should ever happen without user consent. (when (and (stringp value) (string-match-p "\\`(eval\\>" value)) ;; Pre-process the evaluation form for faster macro expansion. (let* ((args (org-macro--makeargs value)) @@ -121,7 +131,7 @@ previous one, unless VALUE is nil. Return the updated list." (cadr (read value)) (error (user-error "Invalid definition for macro %S" name))))) - (setq value (eval (macroexpand-all `(lambda ,args ,body)) t)))) + (setq value `(lambda ,args ,body)))) (cond ((and value old-definition) (setcdr old-definition value)) (old-definition) (t (push (cons name (or value "")) new-templates))))) @@ -254,7 +264,7 @@ a definition in TEMPLATES." (org-element-put-property macro :parent nil) (let* ((key (org-element-property :key macro)) (value (org-macro-expand macro templates)) - (begin (org-element-property :begin macro)) + (begin (org-element-begin macro)) (signature (list begin macro (org-element-property :args macro)))) @@ -268,7 +278,7 @@ a definition in TEMPLATES." (delete-region begin ;; Preserve white spaces after the macro. - (progn (goto-char (org-element-property :end macro)) + (progn (goto-char (org-element-end macro)) (skip-chars-backward " \t") (point))) ;; Leave point before replacement in case of @@ -330,14 +340,14 @@ Return a list of arguments, as strings. This is the opposite of "Find PROPERTY's value at LOCATION. PROPERTY is a string. LOCATION is a search string, as expected by `org-link-search', or the empty string." - (save-excursion - (when (org-string-nw-p location) - (condition-case _ - (let ((org-link-search-must-match-exact-headline t)) - (org-link-search location nil t)) - (error - (error "Macro property failed: cannot find location %s" location)))) - (org-entry-get nil property 'selective))) + (org-with-wide-buffer + (when (org-string-nw-p location) + (condition-case _ + (let ((org-link-search-must-match-exact-headline t)) + (org-link-search location nil t)) + (error + (error "Macro property failed: cannot find location %s" location)))) + (org-entry-get nil property 'selective))) (defun org-macro--find-keyword-value (name &optional collect) "Find value for keyword NAME in current buffer. @@ -352,7 +362,7 @@ in the buffer." (catch :exit (while (re-search-forward regexp nil t) (let ((element (org-with-point-at (match-beginning 0) (org-element-keyword-parser (line-end-position) (list (match-beginning 0)))))) - (when (eq 'keyword (org-element-type element)) + (when (org-element-type-p element 'keyword) (let ((value (org-element-property :value element))) (if (not collect) (throw :exit value) (setq result (concat result " " value))))))) @@ -366,10 +376,13 @@ Return value as a string." value (org-element-restriction 'keyword)))) (if (and (consp date) (not (cdr date)) - (eq 'timestamp (org-element-type (car date)))) + (org-element-type-p (car date) 'timestamp)) (format "(eval (if (org-string-nw-p $1) %s %S))" (format "(org-format-timestamp '%S $1)" - (org-element-copy (car date))) + (org-element-put-property + (org-element-copy (car date)) + ;; Remove non-printable. + :buffer nil)) value) value))) diff --git a/elpa/org-9.6.7/org-macs.el b/elpa/org-9.7.17/org-macs.el similarity index 75% rename from elpa/org-9.6.7/org-macs.el rename to elpa/org-9.7.17/org-macs.el index 642a5840..f70fab95 100644 --- a/elpa/org-9.6.7/org-macs.el +++ b/elpa/org-9.7.17/org-macs.el @@ -1,9 +1,9 @@ ;;; org-macs.el --- Top-level Definitions for Org -*- lexical-binding: t; -*- -;; Copyright (C) 2004-2023 Free Software Foundation, Inc. +;; Copyright (C) 2004-2024 Free Software Foundation, Inc. ;; Author: Carsten Dominik -;; Keywords: outlines, hypermedia, calendar, wp +;; Keywords: outlines, hypermedia, calendar, text ;; URL: https://orgmode.org ;; ;; This file is part of GNU Emacs. @@ -33,6 +33,7 @@ (require 'cl-lib) (require 'format-spec) +(eval-when-compile (require 'subr-x)) ; For `when-let*', Emacs < 29 ;;; Org version verification. @@ -56,8 +57,8 @@ by `package-activate-all').") ;; `org-assert-version' calls would fail using strict ;; `org-git-version' check because the generated Org version strings ;; will not match. - `(unless (or org--inhibit-version-check (equal (org-release) ,(org-release))) - (warn "Org version mismatch. Org loading aborted. + `(unless (or ,org--inhibit-version-check (equal (org-release) ,(org-release))) + (warn "Org version mismatch. This warning usually appears when a built-in Org version is loaded prior to the more recent Org version. @@ -91,10 +92,15 @@ Version mismatch is commonly encountered in the following situations: early in the config. Ideally, right after the straight.el bootstrap. Moving `use-package' :straight declaration may not be sufficient if the corresponding `use-package' statement is - deferring the loading." + deferring the loading. + +4. A new Org version is synchronized with Emacs git repository and + stale .elc files are still left from the previous build. + + It is recommended to remove .elc files from lisp/org directory and + re-compile." ;; Avoid `warn' replacing "'" with "’" (see `format-message'). - "(straight-use-package 'org)") - (error "Org version mismatch. Make sure that correct `load-path' is set early in init.el"))) + "(straight-use-package 'org)"))) ;; We rely on org-macs when generating Org version. Checking Org ;; version here will interfere with Org build process. @@ -108,16 +114,24 @@ Version mismatch is commonly encountered in the following situations: (declare-function org-fold-next-visibility-change "org-fold" (&optional pos limit ignore-hidden-p previous-p)) (declare-function org-fold-core-with-forced-fontification "org-fold" (&rest body)) (declare-function org-fold-folded-p "org-fold" (&optional pos limit ignore-hidden-p previous-p)) -(declare-function string-collate-lessp "org-compat" (s1 s2 &optional locale ignore-case)) -(declare-function org-time-convert-to-integer "org-compat" (time)) +(declare-function org-time-convert-to-list "org-compat" (time)) +(declare-function org-buffer-text-pixel-width "org-compat" ()) (defvar org-ts-regexp0) (defvar ffap-url-regexp) -(defvar org-fold-core-style) ;;; Macros +(defmacro org-require-package (symbol &optional name noerror) + "Try to load library SYMBOL and display error otherwise. +With optional parameter NAME, use NAME as package name instead of +SYMBOL. Show warning instead of error when NOERROR is non-nil." + `(unless (require ,symbol nil t) + (,(if noerror 'warn 'user-error) + "`%s' failed to load required package \"%s\"" + this-command ,(or name symbol)))) + (defmacro org-with-gensyms (symbols &rest body) (declare (debug (sexp body)) (indent 1)) `(let ,(mapcar (lambda (s) @@ -146,19 +160,29 @@ If BUFFER is nil, use base buffer for `current-buffer'." (or ,buffer (current-buffer))) ,@body)) -(defmacro org-with-point-at (pom &rest body) - "Move to buffer and point of point-or-marker POM for the duration of BODY." +(defmacro org-with-point-at (epom &rest body) + "Move to buffer and point of EPOM for the duration of BODY. +EPOM is an element, point, or marker." (declare (debug (form body)) (indent 1)) - (org-with-gensyms (mpom) - `(let ((,mpom ,pom)) + (require 'org-element-ast) + (org-with-gensyms (mepom) + `(let ((,mepom ,epom)) (save-excursion - (when (markerp ,mpom) (set-buffer (marker-buffer ,mpom))) + (cond + ((markerp ,mepom) + (set-buffer (marker-buffer ,mepom))) + ((numberp ,mepom)) + (t + (when (org-element-property :buffer ,mepom) + (set-buffer (org-element-property :buffer ,mepom))) + (setq ,mepom (org-element-property :begin ,mepom)))) (org-with-wide-buffer - (goto-char (or ,mpom (point))) + (goto-char (or ,mepom (point))) ,@body))))) (defmacro org-with-remote-undo (buffer &rest body) - "Execute BODY while recording undo information in two buffers." + "Execute BODY while recording undo information in current buffer and BUFFER. +This function is only useful when called from Agenda buffer." (declare (debug (form body)) (indent 1)) (org-with-gensyms (cline cmd buf1 buf2 undo1 undo2 c1 c2) `(let ((,cline (org-current-line)) @@ -190,7 +214,7 @@ If BUFFER is nil, use base buffer for `current-buffer'." (defalias 'org-save-outline-visibility #'org-fold-save-outline-visibility) (defmacro org-with-wide-buffer (&rest body) - "Execute body while temporarily widening the buffer." + "Execute BODY while temporarily widening the buffer." (declare (debug (body))) `(save-excursion (save-restriction @@ -208,7 +232,7 @@ If BUFFER is nil, use base buffer for `current-buffer'." (let* ((org-called-with-limited-levels t) (org-outline-regexp (org-get-limited-outline-regexp)) (outline-regexp org-outline-regexp) - (org-outline-regexp-bol (concat "^" org-outline-regexp))) + (org-outline-regexp-bol (org-get-limited-outline-regexp t))) ,@body))) (defmacro org-eval-in-environment (environment form) @@ -244,11 +268,7 @@ If BUFFER is nil, use base buffer for `current-buffer'." (unless modified (restore-buffer-modified-p nil)))))))) -(defmacro org-no-popups (&rest body) - "Suppress popup windows and evaluate BODY." - `(let (pop-up-frames pop-up-windows) - ,@body)) - +;;;###autoload (defmacro org-element-with-disabled-cache (&rest body) "Run BODY without active org-element-cache." (declare (debug (form body)) (indent 0)) @@ -265,17 +285,36 @@ If BUFFER is nil, use base buffer for `current-buffer'." buffer))) (defun org-find-base-buffer-visiting (file) - "Like `find-buffer-visiting' but always return the base buffer and -not an indirect buffer." + "Like `find-buffer-visiting' but always return the base buffer. +FILE is the file name passed to `find-buffer-visiting'." (let ((buf (or (get-file-buffer file) (find-buffer-visiting file)))) (org-base-buffer buf))) -(defun org-switch-to-buffer-other-window (&rest args) - "Switch to buffer in a second window on the current frame. -In particular, do not allow pop-up frames. -Returns the newly created buffer." - (org-no-popups (apply #'switch-to-buffer-other-window args))) +(defvar-local org-file-buffer-created nil + "Non-nil when current buffer is created from `org-with-file-buffer'. +The value is FILE argument passed to `org-with-file-buffer'.") +(defmacro org-with-file-buffer (file &rest body) + "Evaluate BODY with current buffer visiting FILE. +When no live buffer is visiting FILE, create one and kill after +evaluating BODY. +During evaluation, when the buffer was created, `org-file-buffer-created' +variable is set to FILE." + (declare (debug (form body)) (indent 1)) + (org-with-gensyms (mark-function filename buffer) + `(let ((,mark-function (lambda () (setq-local org-file-buffer-created ,file))) + (,filename ,file) + ,buffer) + (add-hook 'find-file-hook ,mark-function) + (unwind-protect + (progn + (setq ,buffer (find-file-noselect ,filename t)) + (with-current-buffer ,buffer + (prog1 (progn ,@body) + (with-current-buffer ,buffer + (when (equal ,filename org-file-buffer-created) + (kill-buffer)))))) + (remove-hook 'find-file-hook ,mark-function))))) (defun org-fit-window-to-buffer (&optional window max-height min-height shrink-only) @@ -353,72 +392,6 @@ in target-prerequisite files relation." (let ((mtime (file-attribute-modification-time (file-attributes file)))) (and mtime (or (not time) (time-less-p time mtime))))) -(defun org-compile-file (source process ext &optional err-msg log-buf spec) - "Compile a SOURCE file using PROCESS. - -PROCESS is either a function or a list of shell commands, as -strings. EXT is a file extension, without the leading dot, as -a string. It is used to check if the process actually succeeded. - -PROCESS must create a file with the same base name and directory -as SOURCE, but ending with EXT. The function then returns its -filename. Otherwise, it raises an error. The error message can -then be refined by providing string ERR-MSG, which is appended to -the standard message. - -If PROCESS is a function, it is called with a single argument: -the SOURCE file. - -If it is a list of commands, each of them is called using -`shell-command'. By default, in each command, %b, %f, %F, %o and -%O are replaced with, respectively, SOURCE base name, name, full -name, directory and absolute output file name. It is possible, -however, to use more place-holders by specifying them in optional -argument SPEC, as an alist following the pattern - - (CHARACTER . REPLACEMENT-STRING). - -When PROCESS is a list of commands, optional argument LOG-BUF can -be set to a buffer or a buffer name. `shell-command' then uses -it for output." - (let* ((base-name (file-name-base source)) - (full-name (file-truename source)) - (relative-name (file-relative-name source)) - (out-dir (if (file-name-directory source) - ;; Expand "~". Shell expansion will be disabled - ;; in the shell command call. - (file-name-directory full-name) - "./")) - (output (expand-file-name (concat base-name "." ext) out-dir)) - (time (file-attribute-modification-time (file-attributes output))) - (err-msg (if (stringp err-msg) (concat ". " err-msg) ""))) - (save-window-excursion - (pcase process - ((pred functionp) (funcall process (shell-quote-argument relative-name))) - ((pred consp) - (let ((log-buf (and log-buf (get-buffer-create log-buf))) - (spec (append spec - `((?b . ,(shell-quote-argument base-name)) - (?f . ,(shell-quote-argument relative-name)) - (?F . ,(shell-quote-argument full-name)) - (?o . ,(shell-quote-argument out-dir)) - (?O . ,(shell-quote-argument output)))))) - ;; Combine output of all commands in PROCESS. - (with-current-buffer log-buf - (let (buffer-read-only) - (erase-buffer))) - (let ((shell-command-dont-erase-buffer t)) - (dolist (command process) - (shell-command (format-spec command spec) log-buf))) - (when log-buf (with-current-buffer log-buf (compilation-mode))))) - (_ (error "No valid command to process %S%s" source err-msg)))) - ;; Check for process failure. Output file is expected to be - ;; located in the same directory as SOURCE. - (unless (org-file-newer-than-p output time) - (error (format "File %S wasn't produced%s" output err-msg))) - output)) - - ;;; Indentation @@ -429,6 +402,8 @@ it for output." (defun org-do-remove-indentation (&optional n skip-fl) "Remove the maximum common indentation from the buffer. +Do not consider invisible text when calculating indentation. + When optional argument N is a positive integer, remove exactly that much characters from indentation, if possible. When optional argument SKIP-FL is non-nil, skip the first @@ -449,10 +424,14 @@ line. Return nil if it fails." ;; Remove exactly N indentation, but give up if not possible. (when skip-fl (forward-line)) (while (not (eobp)) - (let ((ind (progn (skip-chars-forward " \t") (current-column)))) - (cond ((eolp) (delete-region (line-beginning-position) (point))) - ((< ind n) (throw :exit nil)) - (t (indent-line-to (- ind n)))) + (let* ((buffer-invisibility-spec nil) ; do not treat invisible text specially + (ind (progn (skip-chars-forward " \t") (current-column)))) + (cond ((< ind n) + (if (eolp) (delete-region (line-beginning-position) (point)) + (throw :exit nil))) + (t (delete-region (line-beginning-position) + (progn (move-to-column n t) + (point))))) (forward-line))) ;; Signal success. t)))) @@ -471,7 +450,7 @@ error when the user input is empty." (allow-empty? nil) (t (user-error "Empty input is not valid"))))) -(declare-function org-time-stamp-inactive "org" (&optional arg)) +(declare-function org-timestamp-inactive "org" (&optional arg)) (defun org-completing-read (&rest args) "Completing-read with SPACE being a normal character." @@ -481,7 +460,7 @@ error when the user input is empty." (define-key minibuffer-local-completion-map " " #'self-insert-command) (define-key minibuffer-local-completion-map "?" #'self-insert-command) (define-key minibuffer-local-completion-map (kbd "C-c !") - #'org-time-stamp-inactive) + #'org-timestamp-inactive) (apply #'completing-read args))) (defun org--mks-read-key (allowed-keys prompt navigation-keys) @@ -530,7 +509,7 @@ alist with (\"key\" \"description\") entries. When one of these is selected, only the bare key is returned." (save-window-excursion (let ((inhibit-quit t) - (buffer (org-switch-to-buffer-other-window "*Org Select*")) + (buffer (switch-to-buffer-other-window "*Org Select*")) (prompt (or prompt "Select: ")) case-fold-search current) @@ -594,7 +573,10 @@ is selected, only the bare key is returned." ;; selection prefix. ((assoc current specials) (throw 'exit current)) (t (error "No entry available"))))))) - (when buffer (kill-buffer buffer)))))) + (when buffer + (when-let* ((window (get-buffer-window buffer t))) + (quit-window 'kill window)) + (kill-buffer buffer)))))) ;;; List manipulation @@ -776,46 +758,100 @@ get an unnecessary O(N²) space complexity, so you're usually better off using (defun org-eval (form) "Eval FORM and return result." - (condition-case error + (condition-case-unless-debug error (eval form t) (error (format "%%![Error: %s]" error)))) +(defvar org--headline-re-cache-no-bol nil + "Plist holding association between headline level regexp.") +(defvar org--headline-re-cache-bol nil + "Plist holding association between headline level regexp.") +(defsubst org-headline-re (true-level &optional no-bol) + "Generate headline regexp for TRUE-LEVEL. +When NO-BOL is non-nil, regexp will not demand the regexp to start at +beginning of line." + (or (plist-get + (if no-bol + org--headline-re-cache-no-bol + org--headline-re-cache-bol) + true-level) + (let ((re (rx-to-string + (if no-bol + `(seq (** 1 ,true-level "*") " ") + `(seq line-start (** 1 ,true-level "*") " "))))) + (if no-bol + (setq org--headline-re-cache-no-bol + (plist-put + org--headline-re-cache-no-bol + true-level re)) + (setq org--headline-re-cache-bol + (plist-put + org--headline-re-cache-bol + true-level re))) + re))) + (defvar org-outline-regexp) ; defined in org.el +(defvar org-outline-regexp-bol) ; defined in org.el (defvar org-odd-levels-only) ; defined in org.el (defvar org-inlinetask-min-level) ; defined in org-inlinetask.el -(defun org-get-limited-outline-regexp () +(defun org-get-limited-outline-regexp (&optional with-bol) "Return outline-regexp with limited number of levels. -The number of levels is controlled by `org-inlinetask-min-level'." +The number of levels is controlled by `org-inlinetask-min-level'. +Match at beginning of line when WITH-BOL is non-nil." (cond ((not (derived-mode-p 'org-mode)) - outline-regexp) + (if (string-prefix-p "^" outline-regexp) + (if with-bol outline-regexp (substring outline-regexp 1)) + (if with-bol (concat "^" outline-regexp) outline-regexp))) ((not (featurep 'org-inlinetask)) - org-outline-regexp) + (if with-bol org-outline-regexp-bol org-outline-regexp)) (t (let* ((limit-level (1- org-inlinetask-min-level)) (nstars (if org-odd-levels-only (1- (* limit-level 2)) limit-level))) - (format "\\*\\{1,%d\\} " nstars))))) + (org-headline-re nstars (not with-bol)))))) (defun org--line-empty-p (n) - "Is the Nth next line empty? -Counts the current line as N = 1 and the previous line as N = 0; -see `beginning-of-line'." + "Is the Nth next line empty?" (and (not (bobp)) (save-excursion - (beginning-of-line n) - (looking-at-p "[ \t]*$")))) + (forward-line n) + (skip-chars-forward " \t") + (eolp)))) (defun org-previous-line-empty-p () "Is the previous line a blank line? When NEXT is non-nil, check the next line instead." - (org--line-empty-p 0)) + (org--line-empty-p -1)) (defun org-next-line-empty-p () "Is the previous line a blank line? When NEXT is non-nil, check the next line instead." - (org--line-empty-p 2)) - + (org--line-empty-p 1)) + +(defun org-id-uuid () + "Return string with random (version 4) UUID." + (let ((rnd (md5 (format "%s%s%s%s%s%s%s" + (random) + (org-time-convert-to-list nil) + (user-uid) + (emacs-pid) + (user-full-name) + user-mail-address + (recent-keys))))) + (format "%s-%s-4%s-%s%s-%s" + (substring rnd 0 8) + (substring rnd 8 12) + (substring rnd 13 16) + (format "%x" + (logior + #b10000000 + (logand + #b10111111 + (string-to-number + (substring rnd 16 18) 16)))) + (substring rnd 18 20) + (substring rnd 20 32)))) ;;; Motion @@ -882,14 +918,14 @@ Return nil when PROP is not set at POS." (<= (match-beginning n) pos) (>= (match-end n) pos))) -(defun org-skip-whitespace () +(defsubst org-skip-whitespace () "Skip over space, tabs and newline characters." (skip-chars-forward " \t\n\r")) (defun org-match-line (regexp) "Match REGEXP at the beginning of the current line." (save-excursion - (beginning-of-line) + (forward-line 0) (looking-at regexp))) (defun org-match-any-p (re list) @@ -911,7 +947,7 @@ match." (let ((pos (point)) (eol (line-end-position (if nlines (1+ nlines) 1)))) (save-excursion - (beginning-of-line (- 1 (or nlines 0))) + (forward-line (- (or nlines 0))) (while (and (re-search-forward regexp eol t) (<= (match-beginning 0) pos)) (let ((end (match-end 0))) @@ -935,23 +971,79 @@ return nil." (require 'ffap) (and ffap-url-regexp (string-match-p ffap-url-regexp s))) - -;;; String manipulation +(defconst org-uuid-regexp + "\\`[0-9a-f]\\{8\\}-[0-9a-f]\\{4\\}-[0-9a-f]\\{4\\}-[0-9a-f]\\{4\\}-[0-9a-f]\\{12\\}\\'" + "Regular expression matching a universal unique identifier (UUID).") -(defun org-string< (a b) - (string-collate-lessp a b)) +(defun org-uuidgen-p (s) + "Is S an ID created by UUIDGEN?" + (string-match org-uuid-regexp (downcase s))) -(defun org-string<= (a b) - (or (string= a b) (string-collate-lessp a b))) -(defun org-string>= (a b) - (not (string-collate-lessp a b))) + +;;; String manipulation -(defun org-string> (a b) +(defcustom org-sort-function #'string-collate-lessp + "Function used to compare strings when sorting. +This function affects how Org mode sorts headlines, agenda items, +table lines, etc. + +The function must accept either 2 or 4 arguments: strings to compare +and, optionally, LOCALE and IGNORE-CASE - locale name and flag to make +comparison case-insensitive. + +The default value uses sorting rules according to OS language. Users +who want to make sorting language-independent, may customize the value +to `org-sort-function-fallback'. + +Note that some string sorting rules are known to be not accurate on +MacOS. See https://debbugs.gnu.org/cgi/bugreport.cgi?bug=59275. +MacOS users may customize the value to +`org-sort-function-fallback'." + :group 'org + :package-version '(Org . "9.7") + :type '(choice + (const :tag "According to OS language" string-collate-lessp) + (const :tag "Using string comparison" org-sort-function-fallback) + (function :tag "Custom function"))) + +(defun org-sort-function-fallback (a b &optional _ ignore-case) + "Return non-nil when downcased string A < string B. +Use `compare-strings' for comparison. Honor IGNORE-CASE." + (let ((ans (compare-strings a nil nil b nil nil ignore-case))) + (cond + ((and (numberp ans) (< ans 0)) t) + (t nil)))) + +(defun org-string< (a b &optional locale ignore-case) + "Return non-nil when string A < string B. +LOCALE is the locale name. IGNORE-CASE, when non-nil, makes comparison +ignore case." + (if (= 4 (cdr (func-arity org-sort-function))) + (funcall org-sort-function a b locale ignore-case) + (funcall org-sort-function a b))) + +(defun org-string<= (a b &optional locale ignore-case) + "Return non-nil when string A <= string B. +LOCALE is the locale name. IGNORE-CASE, when non-nil, makes comparison +ignore case." + (or (string= a b) (org-string< a b locale ignore-case))) + +(defun org-string>= (a b &optional locale ignore-case) + "Return non-nil when string A >= string B. +LOCALE is the locale name. IGNORE-CASE, when non-nil, makes comparison +ignore case." + (not (org-string< a b locale ignore-case))) + +(defun org-string> (a b &optional locale ignore-case) + "Return non-nil when string A > string B. +LOCALE is the locale name. IGNORE-CASE, when non-nil, makes comparison +ignore case." (and (not (string= a b)) - (not (string-collate-lessp a b)))) + (not (org-string< a b locale ignore-case)))) (defun org-string<> (a b) + "Return non-nil when string A and string B are not equal." (not (string= a b))) (defsubst org-trim (s &optional keep-lead) @@ -977,7 +1069,7 @@ Otherwise, return nil." "Splits STRING into substrings at SEPARATORS. SEPARATORS is a regular expression. When nil, it defaults to -\"[ \f\t\n\r\v]+\". +\"[ \\f\\t\\n\\r\\v]+\". Unlike `split-string', matching SEPARATORS at the beginning and end of string are ignored." @@ -1060,14 +1152,16 @@ Results may be off sometimes if it cannot handle a given `display' value." (org--string-from-props string 'display 0 (length string))) -(defun org-string-width (string &optional pixels) +(defun org-string-width (string &optional pixels default-face) "Return width of STRING when displayed in the current buffer. -Return width in pixels when PIXELS is non-nil." +Return width in pixels when PIXELS is non-nil. +When PIXELS is nil, DEFAULT-FACE is the face used to calculate relative +STRING width. When REFERENCE-FACE is nil, `default' face is used." (if (and (version< emacs-version "28") (not pixels)) ;; FIXME: Fallback to old limited version, because ;; `window-pixel-width' is buggy in older Emacs. (org--string-width-1 string) - ;; Wrap/line prefix will make `window-text-pizel-size' return too + ;; Wrap/line prefix will make `window-text-pixel-size' return too ;; large value including the prefix. (remove-text-properties 0 (length string) '(wrap-prefix t line-prefix t) @@ -1077,7 +1171,7 @@ Return width in pixels when PIXELS is non-nil." ;; is critical to get right string width from pixel width (not needed ;; when PIXELS are requested though). (unless pixels - (remove-text-properties 0 (length string) '(face t) string)) + (put-text-property 0 (length string) 'face (or default-face 'default) string)) (let (;; We need to remove the folds to make sure that folded table ;; alignment is not messed up. (current-invisibility-spec @@ -1097,8 +1191,10 @@ Return width in pixels when PIXELS is non-nil." (push el result))) result))) (current-char-property-alias-alist char-property-alias-alist)) - (with-temp-buffer + (with-current-buffer (get-buffer-create " *Org string width*") (setq-local display-line-numbers nil) + (setq-local line-prefix nil) + (setq-local wrap-prefix nil) (setq-local buffer-invisibility-spec (if (listp current-invisibility-spec) (mapcar (lambda (el) @@ -1116,47 +1212,26 @@ Return width in pixels when PIXELS is non-nil." (with-silent-modifications (erase-buffer) (insert string) - (setq pixel-width - (if (get-buffer-window (current-buffer)) - (car (window-text-pixel-size - nil (line-beginning-position) (point-max))) - (let ((dedicatedp (window-dedicated-p)) - (oldbuffer (window-buffer))) - (unwind-protect - (progn - ;; Do not throw error in dedicated windows. - (set-window-dedicated-p nil nil) - (set-window-buffer nil (current-buffer)) - (car (window-text-pixel-size - nil (line-beginning-position) (point-max)))) - (set-window-buffer nil oldbuffer) - (set-window-dedicated-p nil dedicatedp))))) + (setq pixel-width (org-buffer-text-pixel-width)) (unless pixels (erase-buffer) - (insert "a") - (setq symbol-width - (if (get-buffer-window (current-buffer)) - (car (window-text-pixel-size - nil (line-beginning-position) (point-max))) - (let ((dedicatedp (window-dedicated-p)) - (oldbuffer (window-buffer))) - (unwind-protect - (progn - ;; Do not throw error in dedicated windows. - (set-window-dedicated-p nil nil) - (set-window-buffer nil (current-buffer)) - (car (window-text-pixel-size - nil (line-beginning-position) (point-max)))) - (set-window-buffer nil oldbuffer) - (set-window-dedicated-p nil dedicatedp))))))) + (insert (propertize "a" 'face (or default-face 'default))) + (setq symbol-width (org-buffer-text-pixel-width)))) (if pixels pixel-width - (/ pixel-width symbol-width))))))) + (ceiling pixel-width symbol-width))))))) (defmacro org-current-text-column () - "Like `current-column' but ignore display properties." - `(string-width (buffer-substring-no-properties - (line-beginning-position) (point)))) + "Like `current-column' but ignore display properties. +Throw an error when `tab-width' is not 8. + +This function forces `tab-width' value because it is used as a part of +the parser, to ensure parser consistency when calculating list +indentation." + `(progn + (unless (= 8 tab-width) (error "Tab width in Org files must be 8, not %d. Please adjust your `tab-width' settings for Org mode" tab-width)) + (string-width (buffer-substring-no-properties + (line-beginning-position) (point))))) (defun org-not-nil (v) "If V not nil, and also not the string \"nil\", then return V. @@ -1217,6 +1292,10 @@ Assumes that s is a single line, starting in column 0." t t s))) s) +(defun org-remove-blank-lines (s) + "Remove blank lines in S." + (replace-regexp-in-string (rx "\n" (1+ (0+ space) "\n")) "\n" s)) + (defun org-wrap (string &optional width lines) "Wrap string to either a number of lines, or a width in characters. If WIDTH is non-nil, the string is wrapped to that width, however many lines @@ -1287,8 +1366,9 @@ so values can contain further %-escapes if they are define later in TABLE." (dolist (e tbl) (setq re (concat "%-?[0-9.]*" (substring (car e) 1))) (when (and (cdr e) (string-match re (cdr e))) - (let* ((sref (substring (cdr e) (match-beginning 0) (match-end 0))) - (safe (propertize "SREF" 'sref sref))) + (let ((sref (substring (cdr e) (match-beginning 0) (match-end 0))) + (safe (copy-sequence "SREF"))) + (add-text-properties 0 3 (list 'sref sref) safe) (setcdr e (replace-match safe t t (cdr e))))) (while (string-match re string) (setq rpl (format (concat (substring (match-string 0 string) 0 -1) "s") @@ -1542,6 +1622,9 @@ Return 0. if S is not recognized as a valid value." ((string-match org-ts-regexp0 s) (org-2ft s)) (t 0.))))) + +;;; Misc + (defun org-scroll (key &optional additional-keys) "Receive KEY and scroll the current window accordingly. When ADDITIONAL-KEYS is not nil, also include SPC and DEL in the @@ -1578,6 +1661,158 @@ Credit: https://stackoverflow.com/questions/11871245/knuth-multiplicative-hash#4 (cl-assert (and (<= 0 base 32))) (ash (* number 2654435769) (- base 32))) +(defvar org-sxhash-hashes (make-hash-table :weakness 'key :test 'equal)) +(defvar org-sxhash-objects (make-hash-table :weakness 'value)) +(defun org-sxhash-safe (obj &optional counter) + "Like `sxhash' for OBJ, but collision-free for in-memory objects. +When COUNTER is non-nil, return safe hash for (COUNTER . OBJ)." + ;; Note: third-party code may modify OBJ by side effect. + ;; Should not affect anything as long as `org-sxhash-safe' + ;; is used to calculate hash. + (or (and (not counter) (gethash obj org-sxhash-hashes)) + (let* ((hash (sxhash (if counter (cons counter obj) obj))) + (obj-old (gethash hash org-sxhash-objects))) + (if obj-old ; collision + (org-sxhash-safe obj (if counter (1+ counter) 1)) + ;; No collision. Remember and return normal hash. + (puthash hash obj org-sxhash-objects) + (puthash obj hash org-sxhash-hashes))))) + +(defun org-compile-file (source process ext &optional err-msg log-buf spec) + "Compile a SOURCE file using PROCESS. + +See `org-compile-file-commands' for information on PROCESS, EXT, and SPEC. +If PROCESS fails, an error will be raised. The error message can +then be refined by providing string ERR-MSG, which is appended to +the standard message. + +PROCESS must create a file with the same base name and directory +as SOURCE, but ending with EXT. The function then returns its +filename. Otherwise, it raises an error. + +When PROCESS is a list of commands, optional argument LOG-BUF can +be set to a buffer or a buffer name. `shell-command' then uses +it for output." + (let* ((commands (org-compile-file-commands source process ext spec err-msg)) + (output (concat (file-name-sans-extension source) "." ext)) + ;; Resolve symlinks in default-directory to correctly handle + ;; absolute source paths or relative paths with .. + (relname (if (file-name-absolute-p source) + (let ((pwd (file-truename default-directory))) + (file-relative-name source pwd)) + source)) + (log-buf (and log-buf (get-buffer-create log-buf))) + (time (file-attribute-modification-time (file-attributes output)))) + (save-window-excursion + (dolist (command commands) + (cond + ((functionp command) + (funcall command (shell-quote-argument relname))) + ((stringp command) + (let ((shell-command-dont-erase-buffer t)) + (shell-command command log-buf)))))) + ;; Check for process failure. Output file is expected to be + ;; located in the same directory as SOURCE. + (unless (org-file-newer-than-p output time) + (ignore (defvar org-batch-test)) + ;; Display logs when running tests. + (when (bound-and-true-p org-batch-test) + (message "org-compile-file log ::\n-----\n%s\n-----\n" + (with-current-buffer log-buf (buffer-string)))) + (error + (format + "File %S wasn't produced%s" + output + (if (org-string-nw-p err-msg) + (concat " " (org-trim err-msg)) + err-msg)))) + output)) + +(defun org-compile-file-commands (source process ext &optional spec err-msg) + "Return list of commands used to compile SOURCE file. + +The commands are formed from PROCESS, which is either a function or +a list of shell commands, as strings. EXT is a file extension, without +the leading dot, as a string. After PROCESS has been executed, +a file with the same basename and directory as SOURCE but with the +file extension EXT is expected to be produced. +Failure to produce this file will be interpreted as PROCESS failing. + +If PROCESS is a function, it is called with a single argument: +the SOURCE file. + +If PROCESS is a list of commands, each of them is called using +`shell-command'. By default, in each command, %b, %f, %F, %o and +%O are replaced with, respectively, SOURCE base name, relative +file name, absolute file name, relative directory and absolute +output file name. It is possible, however, to use more +place-holders by specifying them in optional argument SPEC, as an +alist following the pattern + + (CHARACTER . REPLACEMENT-STRING). + +Throw an error if PROCESS does not satisfy the described patterns. +The error string will be appended with ERR-MSG, when it is a string." + (let* ((basename (file-name-base source)) + ;; Resolve symlinks in default-directory to correctly handle + ;; absolute source paths or relative paths with .. + (pwd (file-truename default-directory)) + (absname (expand-file-name source pwd)) + (relname (if (file-name-absolute-p source) + (file-relative-name source pwd) + source)) + (relpath (or (file-name-directory relname) "./")) + (output (concat (file-name-sans-extension absname) "." ext)) + (err-msg (if (stringp err-msg) (concat ". " err-msg) ""))) + (pcase process + ((pred functionp) (list process)) + ((pred consp) + (let ((spec (append spec + `((?b . ,(shell-quote-argument basename)) + (?f . ,(shell-quote-argument relname)) + (?F . ,(shell-quote-argument absname)) + (?o . ,(shell-quote-argument relpath)) + (?O . ,(shell-quote-argument output)))))) + (mapcar (lambda (command) (format-spec command spec)) process))) + (_ (error "No valid command to process %S%s" source err-msg))))) + +(defun org-display-buffer-split (buffer alist) + "Display BUFFER in the current frame split in two parts. +The frame will display two buffers - current buffer and BUFFER. +ALIST is an association list of action symbols and values. See +Info node `(elisp) Buffer Display Action Alists' for details of +such alists. + +Use `display-buffer-in-direction' internally. + +This is an action function for buffer display, see Info +node `(elisp) Buffer Display Action Functions'. It should be +called only by `display-buffer' or a function directly or +indirectly called by the latter." + (let ((window-configuration (current-window-configuration))) + (ignore-errors (delete-other-windows)) + (or (display-buffer-in-direction buffer alist) + (display-buffer-pop-up-window buffer alist) + (prog1 nil + (set-window-configuration window-configuration))))) + +(defun org-display-buffer-in-window (buffer alist) + "Display BUFFER in specific window. +The window is defined according to the `window' slot in the ALIST. +Then `same-frame' slot in the ALIST is set, only display buffer when +window is present in the current frame. + +This is an action function for buffer display, see Info +node `(elisp) Buffer Display Action Functions'. It should be +called only by `display-buffer' or a function directly or +indirectly called by the latter." + (let ((window (alist-get 'window alist))) + (when (and window + (window-live-p window) + (or (not (alist-get 'same-frame alist)) + (eq (window-frame) (window-frame window)))) + (window--display-buffer buffer window 'reuse alist)))) + (provide 'org-macs) ;; Local variables: diff --git a/elpa/org-9.6.7/org-mobile.el b/elpa/org-9.7.17/org-mobile.el similarity index 99% rename from elpa/org-9.6.7/org-mobile.el rename to elpa/org-9.7.17/org-mobile.el index 01395a4b..2a6dd4e7 100644 --- a/elpa/org-9.6.7/org-mobile.el +++ b/elpa/org-9.7.17/org-mobile.el @@ -1,8 +1,8 @@ ;;; org-mobile.el --- Code for Asymmetric Sync With a Mobile Device -*- lexical-binding: t; -*- -;; Copyright (C) 2009-2023 Free Software Foundation, Inc. +;; Copyright (C) 2009-2024 Free Software Foundation, Inc. ;; ;; Author: Carsten Dominik -;; Keywords: outlines, hypermedia, calendar, wp +;; Keywords: outlines, hypermedia, calendar, text ;; URL: https://orgmode.org ;; ;; This file is part of GNU Emacs. @@ -392,7 +392,7 @@ agenda view showing the flagged items." (org-agenda nil "?")))))) (defun org-mobile-check-setup () - "Check if org-mobile-directory has been set up." + "Check if `org-mobile-directory' has been set up." (org-mobile-cleanup-encryption-tempfile) (unless (and org-directory (stringp org-directory) @@ -470,7 +470,7 @@ agenda view showing the flagged items." (insert "#+TAGS: " (mapconcat 'identity tags " ") "\n") (insert "#+ALLPRIORITIES: " org-mobile-allpriorities "\n") (when (file-exists-p (expand-file-name - org-mobile-directory "agendas.org")) + "agendas.org" org-mobile-directory)) (insert "* [[file:agendas.org][Agenda Views]]\n")) (pcase-dolist (`(,_ . ,link-name) files-alist) (insert (format "* [[file:%s][%s]]\n" link-name link-name))) @@ -627,11 +627,11 @@ The table of checksums is written to the file mobile-checksums." (setq short (get-text-property (point) 'short-heading)) (when (and short (looking-at ".+")) (replace-match short nil t) - (beginning-of-line 1)) + (forward-line 0)) (when app (end-of-line 1) (insert app) - (beginning-of-line 1)) + (forward-line 0)) (insert "* ")) ((get-text-property (point) 'org-agenda-date-header) (setq in-date t) @@ -649,7 +649,7 @@ The table of checksums is written to the file mobile-checksums." (line-end-position)))) (delete-region (line-beginning-position) (line-end-position)) (insert line "" prefix "") - (beginning-of-line 1)) + (forward-line 0)) (and (looking-at "[ \t]+") (replace-match ""))) (insert (if in-date "*** " "** ")) (end-of-line 1) @@ -666,7 +666,7 @@ The table of checksums is written to the file mobile-checksums." (org-mobile-get-outline-path-link m)))) (insert " :PROPERTIES:\n :ORIGINAL_ID: " id "\n :END:\n"))))) - (beginning-of-line 2)) + (forward-line 1)) (push (cons "agendas.org" (md5 (buffer-string))) org-mobile-checksum-files)) (message "Agenda written to Org file %s" file))) @@ -1057,7 +1057,7 @@ be returned that indicates what went wrong." (goto-char (match-beginning 4)) (insert new) (delete-region (point) (+ (point) (length current))) - (org-align-tags)) + (when org-auto-align-tags (org-align-tags))) (t (error "Heading changed in the mobile device and on the computer"))))))) @@ -1071,7 +1071,7 @@ be returned that indicates what went wrong." (end-of-line 1) (org-insert-heading-respect-content t) (org-demote)) - (beginning-of-line) + (forward-line 0) (insert "* ")) (insert new)) diff --git a/elpa/org-9.6.7/org-mouse.el b/elpa/org-9.7.17/org-mouse.el similarity index 96% rename from elpa/org-9.6.7/org-mouse.el rename to elpa/org-9.7.17/org-mouse.el index e0671f3d..322d9868 100644 --- a/elpa/org-9.6.7/org-mouse.el +++ b/elpa/org-9.7.17/org-mouse.el @@ -1,6 +1,6 @@ ;;; org-mouse.el --- Better mouse support for Org -*- lexical-binding: t; -*- -;; Copyright (C) 2006-2023 Free Software Foundation, Inc. +;; Copyright (C) 2006-2024 Free Software Foundation, Inc. ;; Author: Piotr Zielinski ;; Maintainer: Carsten Dominik @@ -185,8 +185,8 @@ Changing this variable requires a restart of Emacs to get activated." (const :tag "Activate checkboxes" activate-checkboxes))) (defun org-mouse-re-search-line (regexp) - "Search the current line for a given regular expression." - (beginning-of-line) + "Search the current line for a given regular expression REGEXP." + (forward-line 0) (re-search-forward regexp (line-end-position) t)) (defun org-mouse-end-headline () @@ -242,13 +242,13 @@ return `:middle'." (defun org-mouse-empty-line () "Return non-nil if the line contains only white space." - (save-excursion (beginning-of-line) (looking-at "[ \t]*$"))) + (save-excursion (forward-line 0) (looking-at "[ \t]*$"))) (defun org-mouse-next-heading () "Go to the next heading. If there is none, ensure that the point is at the beginning of an empty line." (unless (outline-next-heading) - (beginning-of-line) + (forward-line 0) (unless (org-mouse-empty-line) (end-of-line) (newline)))) @@ -261,7 +261,7 @@ insert the new heading before the current line. Otherwise, insert it after the current heading." (interactive) (cl-case (org-mouse-line-position) - (:beginning (beginning-of-line) + (:beginning (forward-line 0) (org-insert-heading)) (t (org-mouse-next-heading) (org-insert-heading)))) @@ -271,7 +271,7 @@ after the current heading." For the acceptable UNITS, see `org-timestamp-change'." (interactive) - (org-time-stamp nil) + (org-timestamp nil) (when shift (org-timestamp-change shift units))) (defun org-mouse-keyword-menu (keywords function &optional selected itemformat) @@ -426,13 +426,14 @@ SCHEDULED: or DEADLINE: or ANYTHINGLIKETHIS:" (append (let ((tags (org-get-tags nil t))) (org-mouse-keyword-menu - (sort (mapcar #'car (org-get-buffer-tags)) #'string-lessp) + (sort (mapcar #'car (org-get-buffer-tags)) + (or org-tags-sort-function #'org-string<)) (lambda (tag) (org-mouse-set-tags (sort (if (member tag tags) (delete tag tags) (cons tag tags)) - #'string-lessp))) + (or org-tags-sort-function #'org-string<)))) (lambda (tag) (member tag tags)) )) '("--" @@ -473,7 +474,7 @@ SCHEDULED: or DEADLINE: or ANYTHINGLIKETHIS:" (sort (if (member ',name ',options) (delete ',name ',options) (cons ',name ',options)) - 'string-lessp) + #'org-string<) " ") nil nil nil 1) (when (functionp ',function) (funcall ',function))) @@ -502,7 +503,8 @@ SCHEDULED: or DEADLINE: or ANYTHINGLIKETHIS:" ["Check TODOs" org-show-todo-tree t] ("Check Tags" ,@(org-mouse-keyword-menu - (sort (mapcar #'car (org-get-buffer-tags)) #'string-lessp) + (sort (mapcar #'car (org-get-buffer-tags)) + (or org-tags-sort-function #'org-string<)) (lambda (tag) (org-tags-sparse-tree nil tag))) "--" ["Custom Tag ..." org-tags-sparse-tree t]) @@ -512,7 +514,8 @@ SCHEDULED: or DEADLINE: or ANYTHINGLIKETHIS:" ["Display TODO List" org-todo-list t] ("Display Tags" ,@(org-mouse-keyword-menu - (sort (mapcar #'car (org-get-buffer-tags)) #'string-lessp) + (sort (mapcar #'car (org-get-buffer-tags)) + (or org-tags-sort-function #'org-string<)) (lambda (tag) (org-tags-view nil tag))) "--" ["Custom Tag ..." org-tags-view t]) @@ -558,7 +561,7 @@ SCHEDULED: or DEADLINE: or ANYTHINGLIKETHIS:" (save-excursion (org-apply-on-list wrap-fun nil))))) (defun org-mouse-bolp () - "Return true if there only spaces, tabs, and `*' before point. + "Return non-nil if there only spaces, tabs, and `*' before point. This means, between the beginning of line and the point." (save-excursion (skip-chars-backward " \t*") (bolp))) @@ -566,7 +569,7 @@ This means, between the beginning of line and the point." (defun org-mouse-insert-item (text) (cl-case (org-mouse-line-position) (:beginning ; insert before - (beginning-of-line) + (forward-line 0) (looking-at "[ \t]*") (open-line 1) (indent-to-column (- (match-end 0) (match-beginning 0))) @@ -582,7 +585,7 @@ This means, between the beginning of line and the point." (unless (looking-back org-mouse-punctuation (line-beginning-position)) (insert (concat org-mouse-punctuation " "))))) (insert text) - (beginning-of-line)) + (forward-line 0)) (advice-add 'dnd-insert-text :around #'org--mouse-dnd-insert-text) (defun org--mouse-dnd-insert-text (orig-fun window action text &rest args) @@ -632,7 +635,7 @@ This means, between the beginning of line and the point." (progn (save-excursion (goto-char (region-beginning)) (insert "[[")) (save-excursion (goto-char (region-end)) (insert "]]")))] ["Insert Link Here" (org-mouse-yank-link ',event)])))) - ((save-excursion (beginning-of-line) (looking-at "[ \t]*#\\+STARTUP: \\(.*\\)")) + ((save-excursion (forward-line 0) (looking-at "[ \t]*#\\+STARTUP: \\(.*\\)")) (popup-menu `(nil ,@(org-mouse-list-options-menu (mapcar #'car org-startup-options) @@ -713,7 +716,7 @@ This means, between the beginning of line and the point." (popup-menu '(nil ["Show Day" org-open-at-point t] - ["Change Timestamp" org-time-stamp t] + ["Change Timestamp" org-timestamp t] ["Delete Timestamp" (org-mouse-delete-timestamp) t] ["Compute Time Range" org-evaluate-time-range (org-at-date-range-p)] "--" @@ -823,8 +826,8 @@ This means, between the beginning of line and the point." :active (not (save-excursion (org-mouse-re-search-line org-scheduled-regexp)))] ["Insert Timestamp" - (progn (org-mouse-end-headline) (insert " ") (org-time-stamp nil)) t] - ; ["Timestamp (inactive)" org-time-stamp-inactive t] + (progn (org-mouse-end-headline) (insert " ") (org-timestamp nil)) t] + ; ["Timestamp (inactive)" org-timestamp-inactive t] "--" ["Archive Subtree" org-archive-subtree] ["Cut Subtree" org-cut-special] @@ -859,6 +862,10 @@ This means, between the beginning of line and the point." (org-mouse-in-region-p (posn-point (event-start event)))) (mouse-drag-region event))) +;; This function conflicts with touch screen gestures as it relays +;; events to `mouse-drag-region'. +(put 'org-mouse-down-mouse 'ignored-mouse-command t) + (add-hook 'org-mode-hook (lambda () (setq org-mouse-context-menu-function #'org-mouse-context-menu) @@ -976,7 +983,7 @@ This means, between the beginning of line and the point." (org-back-to-heading) (let ((minlevel 1000) (replace-text (concat (make-string (org-current-level) ?*) "* "))) - (beginning-of-line 2) + (forward-line 1) (save-excursion (while (not (or (eobp) (looking-at org-outline-regexp))) (when (looking-at org-mouse-plain-list-regexp) @@ -1024,7 +1031,7 @@ This means, between the beginning of line and the point." (unless (eq (marker-position marker) (marker-position endmarker)) (setq newhead (org-get-heading)))) - (beginning-of-line 1) + (forward-line 1) (save-excursion (org-agenda-change-all-lines newhead hdmarker 'fixface)))) t)))) diff --git a/elpa/org-9.6.7/org-num.el b/elpa/org-9.7.17/org-num.el similarity index 98% rename from elpa/org-9.6.7/org-num.el rename to elpa/org-9.7.17/org-num.el index cbe5e455..a8fcf333 100644 --- a/elpa/org-9.6.7/org-num.el +++ b/elpa/org-9.7.17/org-num.el @@ -1,9 +1,9 @@ ;;; org-num.el --- Dynamic Headlines Numbering -*- lexical-binding: t; -*- -;; Copyright (C) 2018-2023 Free Software Foundation, Inc. +;; Copyright (C) 2018-2024 Free Software Foundation, Inc. ;; Author: Nicolas Goaziou -;; Keywords: outlines, hypermedia, calendar, wp +;; Keywords: outlines, hypermedia, calendar, text ;; This file is part of GNU Emacs. @@ -83,6 +83,7 @@ ;;; Customization +;;;###autoload (defcustom org-num-face nil "Face to use for numbering. When nil, use the same face as the headline. This value is @@ -104,6 +105,7 @@ Any `face' text property on the returned string overrides :package-version '(Org . "9.3") :type 'function) +;;;###autoload (defcustom org-num-max-level nil "Level below which headlines are not numbered. When set to nil, all headlines are numbered." @@ -113,6 +115,7 @@ When set to nil, all headlines are numbered." (integer :tag "Stop numbering at level")) :safe (lambda (val) (or (null val) (wholenump val)))) +;;;###autoload (defcustom org-num-skip-commented nil "Non-nil means commented sub-trees are not numbered." :group 'org-appearance @@ -120,6 +123,7 @@ When set to nil, all headlines are numbered." :type 'boolean :safe #'booleanp) +;;;###autoload (defcustom org-num-skip-footnotes nil "Non-nil means footnotes sections are not numbered." :group 'org-appearance @@ -127,6 +131,7 @@ When set to nil, all headlines are numbered." :type 'boolean :safe #'booleanp) +;;;###autoload (defcustom org-num-skip-tags nil "List of tags preventing the numbering of sub-trees. @@ -139,8 +144,9 @@ control tag inheritance." :group 'org-appearance :package-version '(Org . "9.3") :type '(repeat (string :tag "Tag")) - :safe (lambda (val) (and (listp val) (cl-every #'stringp val)))) + :safe #'org-list-of-strings-p) +;;;###autoload (defcustom org-num-skip-unnumbered nil "Non-nil means numbering obeys to UNNUMBERED property." :group 'org-appearance @@ -156,6 +162,7 @@ control tag inheritance." (defvar-local org-num--overlays nil "Ordered list of overlays used for numbering outlines.") +(put 'org-num--overlays 'permanent-local t) (defvar-local org-num--skip-level nil "Level below which headlines from current tree are not numbered. @@ -213,7 +220,7 @@ Assume point is at a headline." (let ((after-edit-functions (list (lambda (o &rest _) (org-num--invalidate-overlay o)))) (o (save-excursion - (beginning-of-line) + (forward-line 0) (skip-chars-forward "*") (make-overlay (line-beginning-position) (1+ (point)))))) (overlay-put o 'org-num t) @@ -266,7 +273,7 @@ otherwise." tags) t) (and org-num-skip-unnumbered - (org-entry-get (point) "UNNUMBERED") + (org-entry-get (point) "UNNUMBERED" 'selective) t)))) (defun org-num--current-numbering (level skip) diff --git a/elpa/org-9.6.7/org-pcomplete.el b/elpa/org-9.7.17/org-pcomplete.el similarity index 91% rename from elpa/org-9.6.7/org-pcomplete.el rename to elpa/org-9.7.17/org-pcomplete.el index 0567052c..01ee2ac8 100644 --- a/elpa/org-9.6.7/org-pcomplete.el +++ b/elpa/org-9.7.17/org-pcomplete.el @@ -1,10 +1,10 @@ ;;; org-pcomplete.el --- In-buffer Completion Code -*- lexical-binding: t; -*- -;; Copyright (C) 2004-2023 Free Software Foundation, Inc. +;; Copyright (C) 2004-2024 Free Software Foundation, Inc. ;; ;; Author: Carsten Dominik ;; John Wiegley -;; Keywords: outlines, hypermedia, calendar, wp +;; Keywords: outlines, hypermedia, calendar, text ;; URL: https://orgmode.org ;; ;; This file is part of GNU Emacs. @@ -22,6 +22,10 @@ ;; You should have received a copy of the GNU General Public License ;; along with GNU Emacs. If not, see . +;;; Commentary: + +;; This library implements completion support in Org mode buffers. + ;;; Code: ;;;; Require other packages @@ -39,8 +43,9 @@ (declare-function org-before-first-heading-p "org" ()) (declare-function org-buffer-property-keys "org" (&optional specials defaults columns)) (declare-function org-element-at-point "org-element" (&optional pom cached-only)) -(declare-function org-element-property "org-element" property element) -(declare-function org-element-type "org-element" (element)) +(declare-function org-element-property "org-element-ast" (property node &optional dflt force-undefer)) +(declare-function org-element-end "org-element" (node)) +(declare-function org-element-type-p "org-element-ast" (node types)) (declare-function org-end-of-meta-data "org" (&optional full)) (declare-function org-entry-properties "org" (&optional pom which)) (declare-function org-export-backend-options "ox" (cl-x) t) @@ -171,21 +176,29 @@ When completing for #+STARTUP, for example, this function returns (defun org-parse-arguments () "Parse whitespace separated arguments in the current region." - (let ((begin (line-beginning-position)) - (end (line-end-position)) - begins args) - (save-restriction - (narrow-to-region begin end) + (if (equal (cons "searchhead" nil) (org-thing-at-point)) + ;; [[* foo bar link::search option. + ;; Arguments are not simply space-separated. (save-excursion - (goto-char (point-min)) - (while (not (eobp)) - (skip-chars-forward " \t\n[") - (setq begins (cons (point) begins)) - (skip-chars-forward "^ \t\n[") - (setq args (cons (buffer-substring-no-properties - (car begins) (point)) - args))) - (cons (reverse args) (reverse begins)))))) + (let ((origin (point))) + (skip-chars-backward "^*" (line-beginning-position)) + (cons (list (buffer-substring-no-properties (point) origin)) + (list (point))))) + (let ((begin (line-beginning-position)) + (end (line-end-position)) + begins args) + (save-restriction + (narrow-to-region begin end) + (save-excursion + (goto-char (point-min)) + (while (not (eobp)) + (skip-chars-forward " \t\n[") + (setq begins (cons (point) begins)) + (skip-chars-forward "^ \t\n[") + (setq args (cons (buffer-substring-no-properties + (car begins) (point)) + args))) + (cons (reverse args) (reverse begins))))))) (defun org-pcomplete-initial () "Call the right completion function for first argument completions." @@ -306,7 +319,7 @@ When completing for #+STARTUP, for example, this function returns "creator:" "date:" "d:" "email:" "*:" "e:" "::" "f:" "inline:" "tex:" "p:" "pri:" "':" "-:" "stat:" "^:" "toc:" "|:" "tags:" "tasks:" "<:" "todo:") - ;; OPTION items from registered back-ends. + ;; OPTION items from registered backends. (let (items) (dolist (backend (bound-and-true-p org-export-registered-backends)) @@ -361,14 +374,7 @@ This needs more work, to handle headings with lots of spaces in them." ;; Remove the leading asterisk from ;; `org-link-heading-search-string' result. (push (substring (org-link-heading-search-string) 1) tbl)) - (pcomplete-uniquify-list tbl))) - ;; When completing a bracketed link, i.e., "[[*", argument - ;; starts at the star, so remove this character. - ;; Also, if the completion is done inside [[*head]], - ;; drop the closing parentheses. - (replace-regexp-in-string - "\\]+$" "" - (substring pcomplete-stub 1))))) + (pcomplete-uniquify-list tbl)))))) (defun pcomplete/org-mode/tag () "Complete a tag name. Omit tags already set." @@ -397,10 +403,9 @@ This needs more work, to handle headings with lots of spaces in them." (goto-char (point-min)) (while (re-search-forward org-drawer-regexp nil t) (let ((drawer (org-element-at-point))) - (when (memq (org-element-type drawer) - '(drawer property-drawer)) + (when (org-element-type-p drawer '(drawer property-drawer)) (push (org-element-property :drawer-name drawer) names) - (goto-char (org-element-property :end drawer)))))) + (goto-char (org-element-end drawer)))))) (pcomplete-uniquify-list names)))) (substring pcomplete-stub 1))) ;remove initial colon diff --git a/elpa/org-9.6.7/org-persist.el b/elpa/org-9.7.17/org-persist.el similarity index 63% rename from elpa/org-9.6.7/org-persist.el rename to elpa/org-9.7.17/org-persist.el index 01078f45..886d227c 100644 --- a/elpa/org-9.6.7/org-persist.el +++ b/elpa/org-9.7.17/org-persist.el @@ -1,8 +1,8 @@ ;;; org-persist.el --- Persist cached data across Emacs sessions -*- lexical-binding: t; -*- -;; Copyright (C) 2021-2023 Free Software Foundation, Inc. +;; Copyright (C) 2021-2024 Free Software Foundation, Inc. -;; Author: Ihor Radchenko +;; Author: Ihor Radchenko ;; Keywords: cache, storage ;; This file is part of GNU Emacs. @@ -27,24 +27,44 @@ ;; implementation is not meant to be used to store important data - ;; all the caches should be safe to remove at any time. ;; +;; Entry points are `org-persist-register', `org-persist-write', +;; `org-persist-read', and `org-persist-load'. +;; +;; `org-persist-register' will mark the data to be stored. By +;; default, the data is written on disk before exiting Emacs session. +;; Optionally, the data can be written immediately. +;; +;; `org-persist-write' will immediately write the data onto disk. +;; +;; `org-persist-read' will read the data and return its value or list +;; of values for each requested container. +;; +;; `org-persist-load' will read the data with side effects. For +;; example, loading `elisp' container will assign the values to +;; variables. +;; ;; Example usage: ;; ;; 1. Temporarily cache Elisp symbol value to disk. Remove upon ;; closing Emacs: ;; (org-persist-write 'variable-symbol) ;; (org-persist-read 'variable-symbol) ;; read the data later +;; ;; 2. Temporarily cache a remote URL file to disk. Remove upon ;; closing Emacs: ;; (org-persist-write 'url "https://static.fsf.org/common/img/logo-new.png") ;; (org-persist-read 'url "https://static.fsf.org/common/img/logo-new.png") ;; `org-persist-read' will return the cached file location or nil if cached file ;; has been removed. +;; ;; 3. Temporarily cache a file, including TRAMP path to disk: ;; (org-persist-write 'file "/path/to/file") +;; ;; 4. Cache file or URL while some other file exists. ;; (org-persist-register '(url "https://static.fsf.org/common/img/logo-new.png") '(:file "/path to the other file") :expiry 'never :write-immediately t) ;; or, if the other file is current buffer file ;; (org-persist-register '(url "https://static.fsf.org/common/img/logo-new.png") (current-buffer) :expiry 'never :write-immediately t) +;; ;; 5. Cache value of a Elisp variable to disk. The value will be ;; saved and restored automatically (except buffer-local ;; variables). @@ -55,14 +75,29 @@ ;; ;; Save buffer-local variable (buffer-local will not be ;; ;; autoloaded!) ;; (org-persist-register 'org-element--cache (current-buffer)) -;; ;; Save buffer-local variable preserving circular links: +;; ;; Save several buffer-local variables preserving circular links +;; ;; between: ;; (org-persist-register 'org-element--headline-cache (current-buffer) ;; :inherit 'org-element--cache) +;; ;; 6. Load variable by side effects assigning variable symbol: ;; (org-persist-load 'variable-symbol (current-buffer)) +;; ;; 7. Version variable value: ;; (org-persist-register '((elisp variable-symbol) (version "2.0"))) -;; 8. Cancel variable persistence: +;; +;; 8. Define a named container group: +;; +;; (let ((info1 "test") +;; (info2 "test 2")) +;; (org-persist-register +;; `("Named data" (elisp info1 local) (elisp info2 local)) +;; nil :write-immediately t)) +;; (org-persist-read +;; "Named data" +;; nil nil nil :read-related t) ; => ("Named data" "test" "test2") +;; +;; 9. Cancel variable persistence: ;; (org-persist-unregister 'variable-symbol 'all) ; in all buffers ;; (org-persist-unregister 'variable-symbol) ;; global variable ;; (org-persist-unregister 'variable-symbol (current-buffer)) ;; buffer-local @@ -76,13 +111,14 @@ ;; data-cells and we want to preserve their circular structure. ;; ;; Each data collection can be associated with a local or remote file, -;; its inode number, or contents hash. The persistent data collection +;; its inode number, contents hash. The persistent data collection ;; can later be accessed using either file buffer, file, inode, or ;; contents hash. ;; ;; The data collections can be versioned and removed upon expiry. ;; -;; In the code below I will use the following naming conventions: +;; In the code below, I will use the following naming conventions: +;; ;; 1. Container :: a type of data to be stored ;; Containers can store elisp variables, files, and version ;; numbers. Each container can be customized with container @@ -90,19 +126,72 @@ ;; variable symbol. (elisp variable) is a container storing ;; Lisp variable value. Similarly, (version "2.0") container ;; will store version number. +;; +;; Container can also refer to a group of containers: +;; +;; ;; Three containers stored together. +;; '((elisp variable) (file "/path") (version "x.x")) +;; +;; Providing a single container from the list to `org-persist-read' +;; is sufficient to retrieve all the containers (with appropriate +;; optional parameter). +;; +;; Example: +;; +;; (org-persist-register '((version "My data") (file "/path/to/file")) '(:key "key") :write-immediately t) +;; (org-persist-read '(version "My data") '(:key "key") :read-related t) ;; => '("My data" "/path/to/file/copy") +;; +;; Individual containers can also take a short form (not a list): +;; +;; '("String" file '(quoted elisp "value") :keyword) +;; is the same with +;; '((elisp-data "String") (file nil) +;; (elisp-data '(quoted elisp "value")) (elisp-data :keyword)) +;; +;; Note that '(file "String" (elisp value)) would be interpreted as +;; `file' container with "String" path and extra options. See +;; `org-persist--normalize-container'. +;; ;; 2. Associated :: an object the container is associated with. The ;; object can be a buffer, file, inode number, file contents hash, ;; a generic key, or multiple of them. Associated can also be nil. -;; 3. Data collection :: a list of containers linked to an associated -;; object/objects. Each data collection can also have auxiliary -;; records. Their only purpose is readability of the collection -;; index. +;; +;; Example: +;; +;; '(:file "/path/to/file" :inode number :hash buffer-hash :key arbitrary-key) +;; +;; When several objects are associated with a single container, it +;; is not necessary to provide them all to access the container. +;; Just using a single :file/:inode/:hash/:key is sufficient. This +;; way, one can retrieve cached data even when the file has moved - +;; by contents hash. +;; +;; 3. Data collection :: a list of containers, the associated +;; object/objects, expiry, access time, and information about where +;; the cache is stored. Each data collection can also have +;; auxiliary records. Their only purpose is readability of the +;; collection index. +;; +;; Example: +;; +;; (:container +;; ((index "2.7")) +;; :persist-file "ba/cef3b7-e31c-4791-813e-8bd0bf6c5f9c" +;; :associated nil :expiry never +;; :last-access 1672207741.6422956 :last-access-hr "2022-12-28T09:09:01+0300") +;; ;; 4. Index file :: a file listing all the stored data collections. +;; ;; 5. Persist file :: a file holding data values or references to ;; actual data values for a single data collection. This file ;; contains an alist associating each data container in data ;; collection with its value or a reference to the actual value. ;; +;; Example (persist file storing two elisp container values): +;; +;; (((elisp org-element--headline-cache) . #s(avl-tree- ...)) +;; ((elisp org-element--cache) . #s(avl-tree- ...))) +;; ;; All the persistent data is stored in `org-persist-directory'. The data ;; collections are listed in `org-persist-index-file' and the actual data is ;; stored in UID-style subfolders. @@ -111,7 +200,8 @@ ;; ;; Each collection is represented as a plist containing the following ;; properties: -;; - `:container' : list of data continers to be stored in single +;; +;; - `:container' : list of data containers to be stored in single ;; file; ;; - `:persist-file': data file name; ;; - `:associated' : list of associated objects; @@ -120,15 +210,30 @@ ;; - all other keywords are ignored ;; ;; The available types of data containers are: -;; 1. (file variable-symbol) or just variable-symbol :: Storing -;; elisp variable data. +;; 1. (elisp variable-symbol scope) or just variable-symbol :: Storing +;; elisp variable data. SCOPE can be +;; +;; - `nil' :: Use buffer-local value in associated :file or global +;; value if no :file is associated. +;; - string :: Use buffer-local value in buffer named STRING or +;; with STRING `buffer-file-name'. +;; - `local' :: Use symbol value in current scope. +;; Note: If `local' scope is used without writing the +;; value immediately, the actual stored value is +;; undefined. +;; ;; 2. (file) :: Store a copy of the associated file preserving the ;; extension. + ;; (file "/path/to/a/file") :: Store a copy of the file in path. +;; ;; 3. (version "version number") :: Version the data collection. ;; If the stored collection has different version than "version ;; number", disregard it. -;; 4. (url) :: Store a downloaded copy of URL object. +;; +;; 4. (url) :: Store a downloaded copy of URL object given by +;; associated :file. +;; (url "path") :: Use "path" instead of associated :file. ;; ;; The data collections can expire, in which case they will be removed ;; from the persistent storage at the end of Emacs session. The @@ -145,7 +250,8 @@ ;; expiry is controlled by `org-persist-remote-files' instead. ;; ;; Data loading/writing can be more accurately controlled using -;; `org-persist-before-write-hook', `org-persist-before-read-hook', and `org-persist-after-read-hook'. +;; `org-persist-before-write-hook', `org-persist-before-read-hook', +;; and `org-persist-after-read-hook'. ;;; Code: @@ -163,7 +269,7 @@ ;; Silence byte-compiler (used in `org-persist--write-elisp-file'). (defvar pp-use-max-width) -(defconst org-persist--storage-version "3.1" +(defconst org-persist--storage-version "3.2" "Persistent storage layout version.") (defgroup org-persist nil @@ -171,18 +277,19 @@ :tag "Org persist" :group 'org) -(defcustom org-persist-directory (expand-file-name - (org-file-name-concat - (let ((cache-dir (when (fboundp 'xdg-cache-home) - (xdg-cache-home)))) - (if (or (seq-empty-p cache-dir) - (not (file-exists-p cache-dir)) - (file-exists-p (org-file-name-concat - user-emacs-directory - "org-persist"))) +(defcustom org-persist-directory + (expand-file-name + (org-file-name-concat + (let ((cache-dir (when (fboundp 'xdg-cache-home) + (xdg-cache-home)))) + (if (or (seq-empty-p cache-dir) + (not (file-exists-p cache-dir)) + (file-exists-p (org-file-name-concat user-emacs-directory - cache-dir)) - "org-persist/")) + "org-persist"))) + user-emacs-directory + cache-dir)) + "org-persist/")) "Directory where the data is stored." :group 'org-persist :package-version '(Org . "9.6") @@ -221,9 +328,24 @@ function will be called with a single argument - collection." (number :tag "Keep N days") (function :tag "Function"))) -(defconst org-persist-index-file "index" +(defconst org-persist-index-file "index.eld" "File name used to store the data index.") +(defconst org-persist-gc-lock-file "gc-lock.eld" + "File used to store information about active Emacs sessions. +The file contains an alist of (`before-init-time' . LAST-ACTIVE-TIME). +`before-init-time' uniquely identifies Emacs process and +LAST-ACTIVE-TIME is written every `org-persist-gc-lock-interval' +seconds. When LAST-ACTIVE-TIME is more than +`org-persist-gc-lock-expiry' seconds ago, that Emacs session is +considered not active.") + +(defvar org-persist-gc-lock-interval (* 60 60) ; 1 hour + "Interval in seconds for refreshing `org-persist-gc-lock-file'.") + +(defvar org-persist-gc-lock-expiry (* 60 60 24) ; 1 day + "Interval in seconds for expiring a record in `org-persist-gc-lock-file'.") + (defvar org-persist--disable-when-emacs-Q t "Disable persistence when Emacs is called with -Q command line arg. When non-nil, this sets `org-persist-directory' to temporary directory. @@ -253,7 +375,7 @@ The index is a list of plists. Each plist contains information about persistent data storage. Each plist contains the following properties: - - `:container' : list of data continers to be stored in single file + - `:container' : list of data containers to be stored in single file - `:persist-file': data file name - `:associated' : list of associated objects - `:last-access' : last date when the container has been read @@ -262,13 +384,16 @@ properties: (defvar org-persist--index-hash nil "Hash table storing `org-persist--index'. Used for quick access. -They keys are conses of (container . associated).") +The keys are conses of (container . associated).") -(defvar org-persist--report-time 0.5 +(defvar org-persist--index-age nil + "The modification time of the index file, when it was loaded.") + +(defvar org-persist--report-time nil "Whether to report read/write time. When the value is a number, it is a threshold number of seconds. If -the read/write time of a single variable exceeds the threshold, a +the read/write time of a single persist file exceeds the threshold, a message is displayed. When the value is a non-nil non-number, always display the message. @@ -290,41 +415,59 @@ FORMAT and ARGS are passed to `message'." (defun org-persist--read-elisp-file (&optional buffer-or-file) "Read elisp data from BUFFER-OR-FILE or current buffer." - (unless buffer-or-file (setq buffer-or-file (current-buffer))) - (with-temp-buffer - (if (bufferp buffer-or-file) - (set-buffer buffer-or-file) - (insert-file-contents buffer-or-file)) - (condition-case err - (let ((coding-system-for-read 'utf-8) - (read-circle t) - (start-time (float-time))) - ;; FIXME: Reading sometimes fails to read circular objects. - ;; I suspect that it happens when we have object reference - ;; #N# read before object definition #N=. If it is really - ;; so, it should be Emacs bug - either in `read' or in - ;; `prin1'. Meanwhile, just fail silently when `read' - ;; fails to parse the saved cache object. - (prog1 - (read (current-buffer)) - (org-persist--display-time - (- (float-time) start-time) - "Reading from %S" buffer-or-file))) - ;; Recover gracefully if index file is corrupted. - (error - ;; Remove problematic file. - (unless (bufferp buffer-or-file) (delete-file buffer-or-file)) - ;; Do not report the known error to user. - (if (string-match-p "Invalid read syntax" (error-message-string err)) - (message "Emacs reader failed to read data in %S. The error was: %S" - buffer-or-file (error-message-string err)) - (warn "Emacs reader failed to read data in %S. The error was: %S" - buffer-or-file (error-message-string err))) - nil)))) + (let (;; UTF-8 is explicitly used in `org-persist--write-elisp-file'. + (coding-system-for-read 'emacs-internal) + (buffer-or-file (or buffer-or-file (current-buffer)))) + (with-temp-buffer + (if (bufferp buffer-or-file) + (set-buffer buffer-or-file) + (insert-file-contents buffer-or-file)) + (condition-case err + (let ((read-circle t) + (start-time (float-time))) + ;; FIXME: Reading sometimes fails to read circular objects. + ;; I suspect that it happens when we have object reference + ;; #N# read before object definition #N=. If it is really + ;; so, it should be Emacs bug - either in `read' or in + ;; `prin1'. Meanwhile, just fail silently when `read' + ;; fails to parse the saved cache object. + (prog1 + (read (current-buffer)) + (org-persist--display-time + (- (float-time) start-time) + "Reading from %S" buffer-or-file))) + ;; Recover gracefully if index file is corrupted. + (error + ;; Remove problematic file. + (unless (bufferp buffer-or-file) (delete-file buffer-or-file)) + ;; Do not report the known error to user. + (if (string-match-p "Invalid read syntax" (error-message-string err)) + (message "Emacs reader failed to read data in %S. The error was: %S" + buffer-or-file (error-message-string err)) + (warn "Emacs reader failed to read data in %S. The error was: %S" + buffer-or-file (error-message-string err))) + nil))))) +;; FIXME: `pp' is very slow when writing even moderately large datasets +;; We should probably drop it or find some fast formatter. (defun org-persist--write-elisp-file (file data &optional no-circular pp) "Write elisp DATA to FILE." - (let ((print-circle (not no-circular)) + ;; Fsync slightly reduces the chance of an incomplete filesystem + ;; write, however on modern hardware its effectiveness is + ;; questionable and it is insufficient to guarantee complete writes. + ;; Coupled with the significant performance hit if writing many + ;; small files, it simply does not make sense to use fsync here, + ;; particularly as cache corruption is only a minor inconvenience. + ;; With all this in mind, we ensure `write-region-inhibit-fsync' is + ;; set. + ;; + ;; To read more about this, see the comments in Emacs's fileio.c, in + ;; particular the large comment block in init_fileio. + (let ((write-region-inhibit-fsync t) + ;; We set UTF-8 here and in `org-persist--read-elisp-file' + ;; to avoid the overhead from `find-auto-coding'. + (coding-system-for-write 'emacs-internal) + (print-circle (not no-circular)) print-level print-length print-quoted @@ -335,11 +478,17 @@ FORMAT and ARGS are passed to `message'." (start-time (float-time))) (unless (file-exists-p (file-name-directory file)) (make-directory (file-name-directory file) t)) - (with-temp-file file - (if pp - (let ((pp-use-max-width nil)) ; Emacs bug#58687 - (pp data (current-buffer))) - (prin1 data (current-buffer)))) + ;; Force writing even when the file happens to be opened by + ;; another Emacs process. + (cl-letf (((symbol-function #'ask-user-about-lock) + ;; FIXME: Emacs 27 does not yet have `always'. + (lambda (&rest _) t))) + (with-temp-file file + (insert ";; -*- mode: lisp-data; -*-\n") + (if pp + (let ((pp-use-max-width nil)) ; Emacs bug#58687 + (pp data (current-buffer))) + (prin1 data (current-buffer))))) (org-persist--display-time (- (float-time) start-time) "Writing to %S" file))) @@ -426,7 +575,9 @@ Return PLIST." (org-persist-collection-let collection (dolist (cont (cons container container)) (unless (listp (car container)) - (org-persist-gc:generic cont collection)) + (org-persist-gc:generic cont collection) + (dolist (afile (org-persist-associated-files:generic cont collection)) + (delete-file afile))) (remhash (cons cont associated) org-persist--index-hash) (when path (remhash (cons cont (list :file path)) org-persist--index-hash)) (when inode (remhash (cons cont (list :inode inode)) org-persist--index-hash)) @@ -458,18 +609,22 @@ MISC, if non-nil will be appended to the collection. It must be a plist." ;;;; Reading container data. -(defun org-persist--normalize-container (container) - "Normalize CONTAINER representation into (type . settings)." - (if (and (listp container) (listp (car container))) - (mapcar #'org-persist--normalize-container container) - (pcase container - ((or `elisp `version `file `index `url) - (list container nil)) - ((pred symbolp) - (list `elisp container)) - (`(,(or `elisp `version `file `index `url) . ,_) - container) - (_ (error "org-persist: Unknown container type: %S" container))))) +(defun org-persist--normalize-container (container &optional inner) + "Normalize CONTAINER representation into (type . settings). + +When INNER is non-nil, do not try to match as list of containers." + (pcase container + ((or `elisp `elisp-data `version `file `index `url) + `(,container nil)) + ((or (pred keywordp) (pred stringp) `(quote . ,_)) + `(elisp-data ,container)) + ((pred symbolp) + `(elisp ,container)) + (`(,(or `elisp `elisp-data `version `file `index `url) . ,_) + container) + ((and (pred listp) (guard (not inner))) + (mapcar (lambda (c) (org-persist--normalize-container c 'inner)) container)) + (_ (error "org-persist: Unknown container type: %S" container)))) (defvar org-persist--associated-buffer-cache (make-hash-table :weakness 'key) "Buffer hash cache.") @@ -481,9 +636,14 @@ MISC, if non-nil will be appended to the collection. It must be a plist." (unless (stringp associated) (setq associated (cadr associated))) (let* ((rtn `(:file ,associated)) - (inode (and (fboundp 'file-attribute-inode-number) - (file-attribute-inode-number - (file-attributes associated))))) + (inode (and + ;; Do not store :inode for remote files - it may + ;; be time-consuming on slow connections or even + ;; fail completely when ssh connection is closed. + (not (file-remote-p associated)) + (fboundp 'file-attribute-inode-number) + (file-attribute-inode-number + (file-attributes associated))))) (when inode (plist-put rtn :inode inode)) rtn)) ((or (pred bufferp) `(:buffer ,_)) @@ -501,10 +661,21 @@ MISC, if non-nil will be appended to the collection. It must be a plist." (or (buffer-base-buffer associated) associated))) (setq inode (when (and file + ;; Do not store :inode for remote files - it may + ;; be time-consuming on slow connections or even + ;; fail completely when ssh connection is closed. + (not (file-remote-p file)) (fboundp 'file-attribute-inode-number)) (file-attribute-inode-number (file-attributes file)))) - (setq hash (secure-hash 'md5 associated)) + (setq hash + ;; `secure-hash' may trigger interactive dialog when it + ;; cannot determine the coding system automatically. + ;; Force coding system that works reliably for any text + ;; to avoid it. The hash will be consistent, as long + ;; as we use the same coding system. + (let ((coding-system-for-write 'emacs-internal)) + (secure-hash 'md5 associated))) (puthash associated (list (buffer-modified-tick associated) file inode hash) @@ -534,10 +705,12 @@ COLLECTION is the plist holding data collection." "Read elisp container and return LISP-VALUE." lisp-value) -(defun org-persist-read:version (container _ __) - "Read version CONTAINER." +(defun org-persist-read:elisp-data (container _ __) + "Read elisp-data CONTAINER." (cadr container)) +(defalias 'org-persist-read:version #'org-persist-read:elisp-data) + (defun org-persist-read:file (_ path __) "Read file container from PATH." (when (and path (file-exists-p (org-file-name-concat org-persist-directory path))) @@ -589,14 +762,17 @@ COLLECTION is the plist holding data collection." (set lisp-symbol lisp-value)) (set lisp-symbol lisp-value)))) +(defalias 'org-persist-load:elisp-data #'org-persist-read:elisp-data) (defalias 'org-persist-load:version #'org-persist-read:version) (defalias 'org-persist-load:file #'org-persist-read:file) (defun org-persist-load:index (container index-file _) "Load `org-persist--index' from INDEX-FILE according to CONTAINER." (unless org-persist--index - (setq org-persist--index (org-persist-read:index container index-file nil)) - (setq org-persist--index-hash nil) + (setq org-persist--index (org-persist-read:index container index-file nil) + org-persist--index-hash nil + org-persist--index-age (file-attribute-modification-time + (file-attributes index-file))) (if org-persist--index (mapc (lambda (collection) (org-persist--add-to-index collection 'hash)) org-persist--index) (setq org-persist--index nil) @@ -609,7 +785,7 @@ COLLECTION is the plist holding data collection." (plist-put (org-persist--get-collection container) :expiry 'never)))) (defun org-persist--load-index () - "Load `org-persist--index." + "Load `org-persist--index'." (org-persist-load:index `(index ,org-persist--storage-version) (org-file-name-concat org-persist-directory org-persist-index-file) @@ -621,8 +797,9 @@ COLLECTION is the plist holding data collection." "Write CONTAINER in COLLECTION." `(let* ((c (org-persist--normalize-container ,container)) (write-func-symbol (intern (format "org-persist-write:%s" (car c))))) - (setf ,collection (plist-put ,collection :last-access (float-time))) - (setf ,collection (plist-put ,collection :last-access-hr (format-time-string "%FT%T%z" (float-time)))) + (unless (plist-get ,collection :last-access) + (setf ,collection (plist-put ,collection :last-access (float-time))) + (setf ,collection (plist-put ,collection :last-access-hr (format-time-string "%FT%T%z" (float-time))))) (unless (fboundp write-func-symbol) (error "org-persist: Write function %s not defined" write-func-symbol)) @@ -630,17 +807,31 @@ COLLECTION is the plist holding data collection." (defun org-persist-write:elisp (container collection) "Write elisp CONTAINER according to COLLECTION." - (if (and (plist-get (plist-get collection :associated) :file) - (get-file-buffer (plist-get (plist-get collection :associated) :file))) - (let ((buf (get-file-buffer (plist-get (plist-get collection :associated) :file)))) - ;; FIXME: There is `buffer-local-boundp' introduced in Emacs 28. - ;; Not using it yet to keep backward compatibility. - (condition-case nil - (buffer-local-value (cadr container) buf) - (void-variable nil))) - (when (boundp (cadr container)) - (symbol-value (cadr container))))) - + (let ((scope (nth 2 container))) + (pcase scope + ((pred stringp) + (when-let* ((buf (or (get-buffer scope) + (get-file-buffer scope)))) + ;; FIXME: There is `buffer-local-boundp' introduced in Emacs 28. + ;; Not using it yet to keep backward compatibility. + (condition-case nil + (buffer-local-value (cadr container) buf) + (void-variable nil)))) + (`local + (when (boundp (cadr container)) + (symbol-value (cadr container)))) + (`nil + (if-let* ((buf (and (plist-get (plist-get collection :associated) :file) + (get-file-buffer (plist-get (plist-get collection :associated) :file))))) + ;; FIXME: There is `buffer-local-boundp' introduced in Emacs 28. + ;; Not using it yet to keep backward compatibility. + (condition-case nil + (buffer-local-value (cadr container) buf) + (void-variable nil)) + (when (boundp (cadr container)) + (symbol-value (cadr container)))))))) + +(defalias 'org-persist-write:elisp-data #'ignore) (defalias 'org-persist-write:version #'ignore) (defun org-persist-write:file (c collection) @@ -676,38 +867,81 @@ COLLECTION is the plist holding data collection." (make-directory (file-name-directory file-copy) t)) (if (org--should-fetch-remote-resource-p path) (url-copy-file path file-copy 'overwrite) - (error "The remote resource %S is considered unsafe, and will not be downloaded." + (error "The remote resource %S is considered unsafe, and will not be downloaded" path))) (format "%s-%s.%s" persist-file (md5 path) ext))))) +(defun org-persist--check-write-access (path) + "Check write access to all missing directories in PATH. +Show message and return nil if there is no write access. +Otherwise, return t." + (let* ((dir (directory-file-name (file-name-as-directory path))) + (prev dir)) + (while (and (not (file-exists-p dir)) + (setq prev dir) + (not (equal dir (setq dir (directory-file-name + (file-name-directory dir))))))) + (if (file-writable-p prev) t ; return t + (message "org-persist: Missing write access rights to: %S" prev) + ;; return nil + nil))) + (defun org-persist-write:index (container _) "Write index CONTAINER." (org-persist--get-collection container) (unless (file-exists-p org-persist-directory) - (make-directory org-persist-directory)) - (unless (file-exists-p org-persist-directory) - (warn "Failed to create org-persist storage in %s." - org-persist-directory) - (let ((dir (directory-file-name - (file-name-as-directory org-persist-directory)))) - (while (and (not (file-exists-p dir)) - (not (equal dir (setq dir (directory-file-name - (file-name-directory dir))))))) - (unless (file-writable-p dir) - (message "Missing write access rights to org-persist-directory: %S" - org-persist-directory)))) + (condition-case nil + (make-directory org-persist-directory 'parent) + (t + (warn "Failed to create org-persist storage in %s." + org-persist-directory) + (org-persist--check-write-access org-persist-directory)))) (when (file-exists-p org-persist-directory) - (org-persist--write-elisp-file - (org-file-name-concat org-persist-directory org-persist-index-file) - org-persist--index - t t) - (org-file-name-concat org-persist-directory org-persist-index-file))) + (let ((index-file + (org-file-name-concat org-persist-directory org-persist-index-file))) + (org-persist--merge-index-with-disk) + (org-persist--write-elisp-file index-file org-persist--index t) + (setq org-persist--index-age + (file-attribute-modification-time (file-attributes index-file))) + index-file))) (defun org-persist--save-index () - "Save `org-persist--index." + "Save `org-persist--index'." (org-persist-write:index `(index ,org-persist--storage-version) nil)) +(defun org-persist--merge-index-with-disk () + "Merge `org-persist--index' with the current index file on disk." + (let* ((index-file + (org-file-name-concat org-persist-directory org-persist-index-file)) + (disk-index + (and (file-exists-p index-file) + (org-file-newer-than-p index-file org-persist--index-age) + (org-persist-read:index `(index ,org-persist--storage-version) index-file nil))) + (combined-index + (org-persist--merge-index org-persist--index disk-index))) + (when disk-index + (setq org-persist--index combined-index + org-persist--index-age + (file-attribute-modification-time (file-attributes index-file)))))) + +(defun org-persist--merge-index (base other) + "Attempt to merge new index items in OTHER into BASE. +Items with different details are considered too difficult, and skipped." + (if other + (let ((new (cl-set-difference other base :test #'equal)) + (base-files (mapcar (lambda (s) (plist-get s :persist-file)) base)) + (combined (reverse base))) + (dolist (item (nreverse new)) + (unless (or (memq 'index (mapcar #'car (plist-get item :container))) + (not (file-exists-p + (org-file-name-concat org-persist-directory + (plist-get item :persist-file)))) + (member (plist-get item :persist-file) base-files)) + (push item combined))) + (nreverse combined)) + base)) + ;;;; Public API (cl-defun org-persist-register (container &optional associated &rest misc @@ -751,37 +985,48 @@ with `org-persist-write'." (add-hook 'kill-buffer-hook #'org-persist-write-all-buffer nil 'local))) (when write-immediately (org-persist-write container associated))) -(defun org-persist-unregister (container &optional associated) +(cl-defun org-persist-unregister (container &optional associated &key remove-related) "Unregister CONTAINER in ASSOCIATED to be persistent. -When ASSOCIATED is `all', unregister CONTAINER everywhere." +When ASSOCIATED is `all', unregister CONTAINER everywhere. +When REMOVE-RELATED is non-nil, remove all the containers stored with +the CONTAINER as well." (unless org-persist--index (org-persist--load-index)) (setq container (org-persist--normalize-container container)) (if (eq associated 'all) (mapc (lambda (collection) (when (member container (plist-get collection :container)) - (org-persist-unregister container (plist-get collection :associated)))) + (org-persist-unregister container (plist-get collection :associated) :remove-related remove-related))) org-persist--index) (setq associated (org-persist--normalize-associated associated)) (let ((collection (org-persist--find-index `(:container ,container :associated ,associated)))) (when collection - (if (= (length (plist-get collection :container)) 1) + (if (or remove-related (= (length (plist-get collection :container)) 1)) (org-persist--remove-from-index collection) (plist-put collection :container (remove container (plist-get collection :container))) (org-persist--add-to-index collection)))))) -(defvar org-persist--write-cache (make-hash-table :test #'equal) - "Hash table storing as-written data objects. - -This data is used to avoid reading the data multiple times.") -(defun org-persist-read (container &optional associated hash-must-match load?) +(cl-defun org-persist-read (container &optional associated hash-must-match load &key read-related) "Restore CONTAINER data for ASSOCIATED. When HASH-MUST-MATCH is non-nil, do not restore data if hash for ASSOCIATED file or buffer does not match. + ASSOCIATED can be a plist, a buffer, or a string. A buffer is treated as (:buffer ASSOCIATED). A string is treated as (:file ASSOCIATED). -When LOAD? is non-nil, load the data instead of reading." + +When LOAD is non-nil, load the data instead of reading. + +When READ-RELATED is non-nil, return the data stored alongside with +CONTAINER as well. For example: + + (let ((info \"test\")) + (org-persist-register + \\=`(\"My data\" (elisp-data ,info)) + nil :write-immediately t)) + (org-persist-read \"My data\") ; => \"My data\" + (org-persist-read \"My data\" nil nil nil + :read-related t) ; => (\"My data\" \"test\")" (unless org-persist--index (org-persist--load-index)) (setq associated (org-persist--normalize-associated associated)) (setq container (org-persist--normalize-container container)) @@ -793,33 +1038,40 @@ When LOAD? is non-nil, load the data instead of reading." (plist-get collection :persist-file)))) (data nil)) (when (and collection - (file-exists-p persist-file) (or (not (plist-get collection :expiry)) ; current session (not (org-persist--gc-expired-p (plist-get collection :expiry) collection))) (or (not hash-must-match) (and (plist-get associated :hash) (equal (plist-get associated :hash) - (plist-get (plist-get collection :associated) :hash))))) + (plist-get (plist-get collection :associated) :hash)))) + (or (file-exists-p persist-file) + ;; Attempt to write data if it is not yet written. + (progn + (org-persist-write container associated 'no-read) + (file-exists-p persist-file)))) (unless (seq-find (lambda (v) (run-hook-with-args-until-success 'org-persist-before-read-hook v associated)) (plist-get collection :container)) - (setq data (or (gethash persist-file org-persist--write-cache) - (org-persist--read-elisp-file persist-file))) + (setq data (org-persist--read-elisp-file persist-file)) (when data - (cl-loop for container in (plist-get collection :container) + (cl-loop for c in (plist-get collection :container) with result = nil do - (if load? - (push (org-persist-load:generic container (alist-get container data nil nil #'equal) collection) result) - (push (org-persist-read:generic container (alist-get container data nil nil #'equal) collection) result)) - (run-hook-with-args 'org-persist-after-read-hook container associated) - finally return (if (= 1 (length result)) (car result) result))))))) - -(defun org-persist-load (container &optional associated hash-must-match) + (when (or read-related + (equal c container) + (member c container)) + (if load + (push (org-persist-load:generic c (alist-get c data nil nil #'equal) collection) result) + (push (org-persist-read:generic c (alist-get c data nil nil #'equal) collection) result))) + (run-hook-with-args 'org-persist-after-read-hook c associated) + finally return (if (= 1 (length result)) (car result) (nreverse result)))))))) + +(cl-defun org-persist-load (container &optional associated hash-must-match &key read-related) "Load CONTAINER data for ASSOCIATED. -The arguments have the same meaning as in `org-persist-read'." - (org-persist-read container associated hash-must-match t)) +The arguments CONTAINER, ASSOCIATED, HASH-MUST-MATCH, and READ-RELATED +have the same meaning as in `org-persist-read'." + (org-persist-read container associated hash-must-match t :read-related read-related)) (defun org-persist-load-all (&optional associated) "Restore all the persistent data associated with ASSOCIATED." @@ -872,7 +1124,6 @@ When IGNORE-RETURN is non-nil, just return t on success without calling (let ((file (org-file-name-concat org-persist-directory (plist-get collection :persist-file))) (data (mapcar (lambda (c) (cons c (org-persist-write:generic c collection))) (plist-get collection :container)))) - (puthash file data org-persist--write-cache) (org-persist--write-elisp-file file data) (or ignore-return (org-persist-read container associated))))))) @@ -925,32 +1176,84 @@ Do nothing in an indirect buffer." (defalias 'org-persist-gc:elisp #'ignore) (defalias 'org-persist-gc:index #'ignore) +(defalias 'org-persist-gc:elisp-data #'ignore) +(defalias 'org-persist-gc:version #'ignore) +(defalias 'org-persist-gc:file #'ignore) +(defalias 'org-persist-gc:url #'ignore) + +(defun org-persist--gc-persist-file (persist-file) + "Garbage collect PERSIST-FILE." + (when (file-exists-p persist-file) + (delete-file persist-file) + (when (org-directory-empty-p (file-name-directory persist-file)) + (delete-directory (file-name-directory persist-file))))) + +(defmacro org-persist-associated-files:generic (container collection) + "List associated files in `org-persist-directory' of CONTAINER in COLLECTION." + `(let* ((c (org-persist--normalize-container ,container)) + (assocf-func-symbol (intern (format "org-persist-associated-files:%s" (car c))))) + (if (fboundp assocf-func-symbol) + (funcall assocf-func-symbol c ,collection) + (error "org-persist: Read function %s not defined" + assocf-func-symbol)))) + +(defalias 'org-persist-associated-files:elisp #'ignore) +(defalias 'org-persist-associated-files:index #'ignore) +(defalias 'org-persist-associated-files:elisp-data #'ignore) +(defalias 'org-persist-associated-files:version #'ignore) -(defun org-persist-gc:file (container collection) - "Garbage collect file CONTAINER in COLLECTION." +(defun org-persist-associated-files:file (container collection) + "List file CONTAINER associated files of COLLECTION in `org-persist-directory'." (let ((file (org-persist-read container (plist-get collection :associated)))) - (when (file-exists-p file) - (delete-file file)))) + (when (and file (file-exists-p file)) + (list file)))) -(defun org-persist-gc:url (container collection) - "Garbage collect url CONTAINER in COLLECTION." +(defun org-persist-associated-files:url (container collection) + "List url CONTAINER associated files of COLLECTION in `org-persist-directory'." (let ((file (org-persist-read container (plist-get collection :associated)))) (when (file-exists-p file) - (delete-file file)))) - -(defmacro org-persist--gc-persist-file (persist-file) - "Garbage collect PERSIST-FILE." - `(when (file-exists-p ,persist-file) - (delete-file ,persist-file) - (when (org-directory-empty-p (file-name-directory ,persist-file)) - (delete-directory (file-name-directory ,persist-file))))) + (list file)))) + +(defun org-persist--refresh-gc-lock () + "Refresh session timestamp in `org-persist-gc-lock-file'. +Remove expired sessions timestamps." + (let* ((file (org-file-name-concat org-persist-directory org-persist-gc-lock-file)) + (alist (when (file-exists-p file) (org-persist--read-elisp-file file))) + new-alist) + (setf (alist-get before-init-time alist nil nil #'equal) + (current-time)) + (dolist (record alist) + (when (< (- (float-time (cdr record)) (float-time (current-time))) + org-persist-gc-lock-expiry) + (push record new-alist))) + (org-persist--write-elisp-file file new-alist))) + +(defun org-persist--gc-orphan-p () + "Return non-nil, when orphan files should be garbage-collected. +Remove current sessions from `org-persist-gc-lock-file'." + (let* ((file (org-file-name-concat org-persist-directory org-persist-gc-lock-file)) + (alist (when (file-exists-p file) (org-persist--read-elisp-file file)))) + (setq alist (org-assoc-delete-all before-init-time alist)) + (org-persist--write-elisp-file file alist) + ;; Only GC orphan files when there are no active sessions. + (not alist))) (defun org-persist-gc () - "Remove expired or unregistered containers. + "Remove expired or unregistered containers and orphaned files. Also, remove containers associated with non-existing files." - (let (new-index (remote-files-num 0)) + (if org-persist--index + (org-persist--merge-index-with-disk) + (org-persist--load-index)) + (let (new-index + (remote-files-num 0) + (orphan-files + (when (org-persist--gc-orphan-p) ; also removes current session from lock file. + (delete (org-file-name-concat org-persist-directory org-persist-index-file) + (when (file-exists-p org-persist-directory) + (directory-files-recursively org-persist-directory ".+")))))) (dolist (collection org-persist--index) (let* ((file (plist-get (plist-get collection :associated) :file)) + (web-file (and file (string-match-p "\\`https?://" file))) (file-remote (when file (file-remote-p file))) (persist-file (when (plist-get collection :persist-file) (org-file-name-concat @@ -959,7 +1262,8 @@ Also, remove containers associated with non-existing files." (expired? (org-persist--gc-expired-p (plist-get collection :expiry) collection))) (when persist-file - (when file + (setq orphan-files (delete persist-file orphan-files)) + (when (and file (not web-file)) (when file-remote (cl-incf remote-files-num)) (unless (if (not file-remote) (file-exists-p file) @@ -968,12 +1272,18 @@ Also, remove containers associated with non-existing files." ('check-existence (file-exists-p file)) ((pred numberp) - (<= org-persist-remote-files remote-files-num)) + (< org-persist-remote-files remote-files-num)) (_ nil))) (setq expired? t))) (if expired? (org-persist--gc-persist-file persist-file) - (push collection new-index))))) + (push collection new-index) + (dolist (container (plist-get collection :container)) + (dolist (associated-file + (org-persist-associated-files:generic + container collection)) + (setq orphan-files (delete associated-file orphan-files)))))))) + (mapc #'org-persist--gc-persist-file orphan-files) (setq org-persist--index (nreverse new-index)))) (defun org-persist-clear-storage-maybe () @@ -1001,22 +1311,27 @@ such scenario." (make-temp-file "org-persist-" 'dir))) ;; Automatically write the data, but only when we have write access. -(let ((dir (directory-file-name - (file-name-as-directory org-persist-directory)))) - (while (and (not (file-exists-p dir)) - (not (equal dir (setq dir (directory-file-name - (file-name-directory dir))))))) - (if (not (file-writable-p dir)) - (message "Missing write access rights to org-persist-directory: %S" - org-persist-directory) - (add-hook 'kill-emacs-hook #'org-persist-clear-storage-maybe) ; Run last. - (add-hook 'kill-emacs-hook #'org-persist-write-all) - ;; `org-persist-gc' should run before `org-persist-write-all'. - ;; So we are adding the hook after `org-persist-write-all'. - (add-hook 'kill-emacs-hook #'org-persist-gc))) +(when (org-persist--check-write-access org-persist-directory) + (add-hook 'kill-emacs-hook #'org-persist-clear-storage-maybe) ; Run last. + (add-hook 'kill-emacs-hook #'org-persist-write-all) + ;; `org-persist-gc' should run before `org-persist-write-all'. + ;; So we are adding the hook after `org-persist-write-all'. + (add-hook 'kill-emacs-hook #'org-persist-gc)) (add-hook 'after-init-hook #'org-persist-load-all) +(defvar org-persist--refresh-gc-lock-timer nil + "Timer used to refresh session timestamp in `org-persist-gc-lock-file'.") + +(unless (and org-persist--disable-when-emacs-Q + ;; FIXME: This is relying on undocumented fact that + ;; Emacs sets `user-init-file' to nil when loaded with + ;; "-Q" argument. + (not user-init-file)) + (unless org-persist--refresh-gc-lock-timer + (setq org-persist--refresh-gc-lock-timer + (run-at-time nil org-persist-gc-lock-interval #'org-persist--refresh-gc-lock)))) + (provide 'org-persist) ;;; org-persist.el ends here diff --git a/elpa/org-9.7.17/org-pkg.el b/elpa/org-9.7.17/org-pkg.el new file mode 100644 index 00000000..c3c9dcbf --- /dev/null +++ b/elpa/org-9.7.17/org-pkg.el @@ -0,0 +1,2 @@ +;; Generated package description from org.el -*- no-byte-compile: t -*- +(define-package "org" "9.7.17" "Outline-based notes management and organizer" '((emacs "26.1")) :commit "3ae179a5e2d4fedbc33ce7c7ac8ca280f0820655" :authors '(("Carsten Dominik" . "carsten.dominik@gmail.com")) :maintainer '("Bastien Guerry" . "bzg@gnu.org") :keywords '("outlines" "hypermedia" "calendar" "text") :url "https://orgmode.org") diff --git a/elpa/org-9.6.7/org-plot.el b/elpa/org-9.7.17/org-plot.el similarity index 98% rename from elpa/org-9.6.7/org-plot.el rename to elpa/org-9.7.17/org-plot.el index fe61e9ac..283d9938 100644 --- a/elpa/org-9.6.7/org-plot.el +++ b/elpa/org-9.7.17/org-plot.el @@ -1,6 +1,6 @@ ;;; org-plot.el --- Support for Plotting from Org -*- lexical-binding: t; -*- -;; Copyright (C) 2008-2023 Free Software Foundation, Inc. +;; Copyright (C) 2008-2024 Free Software Foundation, Inc. ;; ;; Author: Eric Schulte ;; Maintainer: TEC @@ -641,9 +641,13 @@ manner suitable for prepending to a user-specified script." If not given options will be taken from the +PLOT line directly before or after the table." (interactive) - (require 'gnuplot) + (org-require-package 'gnuplot) (save-window-excursion - (delete-other-windows) + ;; `gnuplot-send-buffer-to-gnuplot' will display *gnuplot* buffer + ;; if `gnuplot-display-process' is non-nil. Make it visible while + ;; gnuplot is processing the data, preferably as a split, and + ;; restore old window configuration after gnuplot finishes. + (ignore-errors (delete-other-windows)) (when (get-buffer "*gnuplot*") ; reset *gnuplot* if it already running (with-current-buffer "*gnuplot*" (goto-char (point-max)))) diff --git a/elpa/org-9.6.7/org-protocol.el b/elpa/org-9.7.17/org-protocol.el similarity index 95% rename from elpa/org-9.6.7/org-protocol.el rename to elpa/org-9.7.17/org-protocol.el index 2b07a377..85c9a0cc 100644 --- a/elpa/org-9.6.7/org-protocol.el +++ b/elpa/org-9.7.17/org-protocol.el @@ -1,13 +1,13 @@ ;;; org-protocol.el --- Intercept Calls from Emacsclient to Trigger Custom Actions -*- lexical-binding: t; -*- ;; -;; Copyright (C) 2008-2023 Free Software Foundation, Inc. +;; Copyright (C) 2008-2024 Free Software Foundation, Inc. ;; ;; Authors: Bastien Guerry ;; Daniel M German ;; Sebastian Rose ;; Ross Patterson ;; Maintainer: Sebastian Rose -;; Keywords: org, emacsclient, wp +;; Keywords: org, emacsclient, text ;; This file is part of GNU Emacs. ;; @@ -34,7 +34,10 @@ ;; `org-protocol-protocol-alist' and `org-protocol-protocol-alist-default'. ;; ;; Any application that supports calling external programs with an URL -;; as argument may be used with this functionality. +;; as argument could use this functionality. For example, you can +;; configure bookmarks in your web browser to send a link to the +;; current page to Org and create a note from it using `org-capture'. +;; See Info node `(org) Protocols' for more information. ;; ;; ;; Usage: @@ -44,13 +47,13 @@ ;; ;; (require 'org-protocol) ;; -;; 3.) Ensure emacs-server is up and running. -;; 4.) Try this from the command line (adjust the URL as needed): +;; 2.) Ensure emacs-server is up and running. +;; 3.) Try this from the command line (adjust the URL as needed): ;; ;; $ emacsclient \ ;; "org-protocol://store-link?url=http:%2F%2Flocalhost%2Findex.html&title=The%20title" ;; -;; 5.) Optionally add custom sub-protocols and handlers: +;; 4.) Optionally, add custom sub-protocols and handlers: ;; ;; (setq org-protocol-protocol-alist ;; '(("my-protocol" @@ -64,10 +67,11 @@ ;; If it works, you can now setup other applications for using this feature. ;; ;; -;; As of March 2009 Firefox users follow the steps documented on -;; https://kb.mozillazine.org/Register_protocol, Opera setup is described here: -;; http://www.opera.com/support/kb/view/535/ +;; Firefox users follow the steps documented on +;; https://kb.mozillazine.org/Register_protocol, Opera setup is +;; described here: http://www.opera.com/support/kb/view/535/ ;; +;; See also: https://orgmode.org/worg/org-contrib/org-protocol.html ;; ;; Documentation ;; ------------- @@ -123,9 +127,6 @@ ;; Note that using double slashes is optional from org-protocol.el's point of ;; view because emacsclient squashes the slashes to one. ;; -;; -;; provides: 'org-protocol -;; ;;; Code: (require 'org-macs) @@ -328,7 +329,7 @@ results of that splitting are returned as a list." Greedy handlers might receive a list like this from emacsclient: \((\"/dir/org-protocol:/greedy:/~/path1\" (23 . 12)) (\"/dir/param\")) where \"/dir/\" is the absolute path to emacsclient's working directory. This -function transforms it into a flat list using `org-protocol-flatten' and +function transforms it into a flat list using `flatten-tree' and transforms the elements of that list as follows: If STRIP-PATH is non-nil, remove the \"/dir/\" prefix from all members of @@ -343,9 +344,9 @@ Note, that this function will always behave as if `org-protocol-reverse-list-of-files' was set to t and the returned list will reflect that. emacsclient's first parameter will be the first one in the returned list." - (let* ((l (org-protocol-flatten (if org-protocol-reverse-list-of-files - param-list - (reverse param-list)))) + (let* ((l (org--flatten-tree (if org-protocol-reverse-list-of-files + param-list + (reverse param-list)))) (trigger (car l)) (len 0) dir @@ -368,21 +369,15 @@ returned list." ret) l))) -;; `flatten-tree' was added in Emacs 27.1. -(defalias 'org-protocol-flatten - (if (fboundp 'flatten-tree) 'flatten-tree - (lambda (list) - "Transform LIST into a flat list. +(define-obsolete-function-alias 'org-protocol-flatten + (if (fboundp 'flatten-tree) 'flatten-tree 'org--flatten-tree) + "9.7" + "Transform LIST into a flat list. Greedy handlers might receive a list like this from emacsclient: \((\"/dir/org-protocol:/greedy:/~/path1\" (23 . 12)) (\"/dir/param\")) where \"/dir/\" is the absolute path to emacsclients working directory. -This function transforms it into a flat list." - (if list - (if (consp list) - (append (org-protocol-flatten (car list)) - (org-protocol-flatten (cdr list))) - (list list)))))) +This function transforms it into a flat list.") (defun org-protocol-parse-parameters (info &optional new-style default-order) "Return a property list of parameters from INFO. @@ -688,7 +683,8 @@ to deal with new-style links.") (advice-add 'server-visit-files :around #'org--protocol-detect-protocol-server) (defun org--protocol-detect-protocol-server (orig-fun files client &rest args) - "Advice server-visit-flist to call `org-protocol-check-filename-for-protocol'." + "Advice `server-visit-files' to call `org-protocol-check-filename-for-protocol'. +This function is indented to be used as :around advice for `server-visit-files'." (let ((flist (if org-protocol-reverse-list-of-files (reverse files) files))) diff --git a/elpa/org-9.6.7/org-refile.el b/elpa/org-9.7.17/org-refile.el similarity index 82% rename from elpa/org-9.6.7/org-refile.el rename to elpa/org-9.7.17/org-refile.el index 5a41c022..9dea3444 100644 --- a/elpa/org-9.6.7/org-refile.el +++ b/elpa/org-9.7.17/org-refile.el @@ -1,9 +1,9 @@ ;;; org-refile.el --- Refile Org Subtrees -*- lexical-binding: t; -*- -;; Copyright (C) 2010-2023 Free Software Foundation, Inc. +;; Copyright (C) 2010-2024 Free Software Foundation, Inc. ;; Author: Carsten Dominik -;; Keywords: outlines, hypermedia, calendar, wp +;; Keywords: outlines, hypermedia, calendar, text ;; ;; This file is part of GNU Emacs. @@ -221,7 +221,8 @@ converted to a headline before refiling." ["Refile and copy Subtree" org-refile-copy (org-in-subtree-not-table-p)])) (defun org-refile-marker (pos) - "Get a new refile marker, but only if caching is in use." + "Return a new refile marker at POS, but only if caching is in use. +When `org-refile-use-cache' is nil, just return POS." (if (not org-refile-use-cache) pos (let ((m (make-marker))) @@ -273,8 +274,10 @@ converted to a headline before refiling." (entries (or org-refile-targets '((nil . (:level . 1))))) targets tgs files desc descre) (message "Getting targets...") + (cl-assert (listp entries) t "`org-refile-targets' must be a list of targets") (with-current-buffer (or default-buffer (current-buffer)) (dolist (entry entries) + (cl-assert (consp entry) t "Refile target must be a cons cell (FILES . SPECIFICATION)") (setq files (car entry) desc (cdr entry)) (cond ((null files) (setq files (list (current-buffer)))) @@ -285,28 +288,37 @@ converted to a headline before refiling." ((and (symbolp files) (boundp files)) (setq files (symbol-value files)))) (when (stringp files) (setq files (list files))) - (cond - ((eq (car desc) :tag) - (setq descre (concat "^\\*+[ \t]+.*?:" (regexp-quote (cdr desc)) ":"))) - ((eq (car desc) :todo) - (setq descre (concat "^\\*+[ \t]+" (regexp-quote (cdr desc)) "[ \t]"))) - ((eq (car desc) :regexp) - (setq descre (cdr desc))) - ((eq (car desc) :level) - (setq descre (concat "^\\*\\{" (number-to-string - (if org-odd-levels-only - (1- (* 2 (cdr desc))) - (cdr desc))) - "\\}[ \t]"))) - ((eq (car desc) :maxlevel) - (setq descre (concat "^\\*\\{1," (number-to-string + ;; Allow commonly used (FILE :maxlevel N) and similar values. + (when (and (listp (cdr desc)) (null (cddr desc))) + (setq desc (cons (car desc) (cadr desc)))) + (condition-case err + (cond + ((eq (car desc) :tag) + (setq descre (concat "^\\*+[ \t]+.*?:" (regexp-quote (cdr desc)) ":"))) + ((eq (car desc) :todo) + (setq descre (concat "^\\*+[ \t]+" (regexp-quote (cdr desc)) "[ \t]"))) + ((eq (car desc) :regexp) + (setq descre (cdr desc))) + ((eq (car desc) :level) + (setq descre (concat "^\\*\\{" (number-to-string (if org-odd-levels-only - (1- (* 2 (cdr desc))) + (1- (* 2 (cdr desc))) (cdr desc))) - "\\}[ \t]"))) - (t (error "Bad refiling target description %s" desc))) + "\\}[ \t]"))) + ((eq (car desc) :maxlevel) + (setq descre (concat "^\\*\\{1," (number-to-string + (if org-odd-levels-only + (1- (* 2 (cdr desc))) + (cdr desc))) + "\\}[ \t]"))) + (t (error "Bad refiling target description %s" desc))) + (error + (error "Error parsing refiling target description: %s" + (error-message-string err)))) (dolist (f files) (with-current-buffer (if (bufferp f) f (org-get-agenda-file-buffer f)) + (unless (derived-mode-p 'org-mode) + (error "Major mode in refile target buffer \"%s\" must be `org-mode'" f)) (or (setq tgs (org-refile-cache-get (buffer-file-name) descre)) (progn @@ -330,7 +342,7 @@ converted to a headline before refiling." (goto-char (point-min)) (setq org-outline-path-cache nil) (while (re-search-forward descre nil t) - (beginning-of-line) + (forward-line 0) (let ((case-fold-search nil)) (looking-at org-complex-heading-regexp)) (let ((begin (point)) @@ -365,7 +377,7 @@ converted to a headline before refiling." (buffer-base-buffer)))) (_ nil)) (mapcar (lambda (s) (replace-regexp-in-string - "/" "\\/" s nil t)) + "/" "\\/" s nil t)) (org-get-outline-path t t))) "/")))) (push (list target f re (org-refile-marker (point))) @@ -458,8 +470,8 @@ See also `org-refile-use-outline-path'. If you are using target caching (see `org-refile-use-cache'), you have to clear the target cache in order to find new targets. -This can be done with a `0' prefix (`C-0 C-c C-w') or a triple -prefix argument (`C-u C-u C-u C-c C-w')." +This can be done with a `0' prefix (\\`C-0 C-c C-w') or a triple +prefix argument (\\`C-u C-u C-u C-c C-w')." (interactive "P") (if (member arg '(0 (64))) (org-refile-cache-clear) @@ -474,7 +486,7 @@ prefix argument (`C-u C-u C-u C-c C-w')." (setq last-command nil) (when regionp (goto-char region-start) - (beginning-of-line) + (forward-line 0) (setq region-start (point)) (unless (or (org-kill-is-subtree-p (buffer-substring region-start region-end)) @@ -523,12 +535,13 @@ prefix argument (`C-u C-u C-u C-c C-w')." (if regionp (and (>= pos region-start) (<= pos region-end)) - (and (>= pos (point)) + (and (>= pos (save-excursion + (org-back-to-heading t) + (point))) (< pos (save-excursion (org-end-of-subtree t t)))))) (error "Cannot refile to position inside the tree or region")) - (setq nbuf (or (find-buffer-visiting file) - (find-file-noselect file))) + (setq nbuf (find-file-noselect file 'nowarn)) (if (and arg (not (equal arg 3))) (progn (pop-to-buffer-same-window nbuf) @@ -541,58 +554,70 @@ prefix argument (`C-u C-u C-u C-c C-w')." (org-kill-new (buffer-substring region-start region-end)) (org-save-markers-in-region region-start region-end)) (org-copy-subtree 1 nil t)) - (with-current-buffer (setq nbuf (or (find-buffer-visiting file) - (find-file-noselect file))) - (setq reversed (org-notes-order-reversed-p)) - (org-with-wide-buffer - (if pos - (progn - (goto-char pos) - (setq level (org-get-valid-level (funcall outline-level) 1)) - (goto-char - (if reversed - (or (outline-next-heading) (point-max)) - (or (save-excursion (org-get-next-sibling)) - (org-end-of-subtree t t) - (point-max))))) - (setq level 1) - (if (not reversed) - (goto-char (point-max)) - (goto-char (point-min)) - (or (outline-next-heading) (goto-char (point-max))))) - (unless (bolp) (newline)) - (org-paste-subtree level nil nil t) - ;; Record information, according to `org-log-refile'. - ;; Do not prompt for a note when refiling multiple - ;; headlines, however. Simply add a time stamp. - (cond - ((not org-log-refile)) - (regionp - (org-map-region - (lambda () (org-add-log-setup 'refile nil nil 'time)) - (point) - (+ (point) (- region-end region-start)))) - (t - (org-add-log-setup 'refile nil nil org-log-refile))) - (and org-auto-align-tags - (let ((org-loop-over-headlines-in-active-region nil)) - (org-align-tags))) - (let ((bookmark-name (plist-get org-bookmark-names-plist - :last-refile))) - (when bookmark-name - (with-demoted-errors "Bookmark set error: %S" - (bookmark-set bookmark-name)))) - ;; If we are refiling for capture, make sure that the - ;; last-capture pointers point here - (when (bound-and-true-p org-capture-is-refiling) - (let ((bookmark-name (plist-get org-bookmark-names-plist - :last-capture-marker))) + (let ((origin (point-marker))) + ;; Handle special case when we refile to exactly same + ;; location with tree promotion/demotion. Point marker + ;; saved by `org-with-wide-buffer' (`save-excursion') + ;; will then remain before the inserted subtree in + ;; unexpected location. + (set-marker-insertion-type origin t) + (with-current-buffer (setq nbuf (find-file-noselect file 'nowarn)) + (setq reversed (org-notes-order-reversed-p)) + (org-with-wide-buffer + (if pos + (progn + (goto-char pos) + (setq level (org-get-valid-level (funcall outline-level) 1)) + (goto-char + (if reversed + (or (outline-next-heading) (point-max)) + (or (save-excursion (org-get-next-sibling)) + (org-end-of-subtree t t) + (point-max))))) + (setq level 1) + (if (not reversed) + (goto-char (point-max)) + (goto-char (point-min)) + (or (outline-next-heading) (goto-char (point-max))))) + (unless (bolp) (newline)) + (org-paste-subtree level nil nil t) + ;; Record information, according to `org-log-refile'. + ;; Do not prompt for a note when refiling multiple + ;; headlines, however. Simply add a time stamp. + (cond + ((not org-log-refile)) + (regionp + (org-map-region + (lambda () (org-add-log-setup 'refile nil nil 'time)) + (point) + (+ (point) (- region-end region-start)))) + (t + (org-add-log-setup 'refile nil nil org-log-refile))) + (and org-auto-align-tags + (let ((org-loop-over-headlines-in-active-region nil)) + (org-align-tags))) + (let ((bookmark-name (plist-get org-bookmark-names-plist + :last-refile))) (when bookmark-name - (with-demoted-errors "Bookmark set error: %S" - (bookmark-set bookmark-name)))) - (move-marker org-capture-last-stored-marker (point))) - (deactivate-mark) - (run-hooks 'org-after-refile-insert-hook))) + (condition-case err + (bookmark-set bookmark-name) + (error + (message (format "Bookmark set error: %S" err)))))) + ;; If we are refiling for capture, make sure that the + ;; last-capture pointers point here + (when (bound-and-true-p org-capture-is-refiling) + (let ((bookmark-name (plist-get org-bookmark-names-plist + :last-capture-marker))) + (when bookmark-name + (condition-case err + (bookmark-set bookmark-name) + (error + (message (format "Bookmark set error: %S" err)))))) + (move-marker org-capture-last-stored-marker (point))) + (deactivate-mark) + (run-hooks 'org-after-refile-insert-hook))) + ;; Go back to ORIGIN. + (goto-char origin)) (unless org-refile-keep (if regionp (delete-region (point) (+ (point) (- region-end region-start))) @@ -641,12 +666,12 @@ this function appends the default value from #'completing-read)) (extra (if org-refile-use-outline-path "/" "")) (cbnex (concat (buffer-name) extra)) - (filename (and cfn (expand-file-name cfn))) + (filename (and cfn (file-truename cfn))) (tbl (mapcar (lambda (x) (if (and (not (member org-refile-use-outline-path '(file full-file-path title))) - (not (equal filename (nth 1 x)))) + (not (equal filename (file-truename (nth 1 x))))) (cons (concat (car x) extra " (" (file-name-nondirectory (nth 1 x)) ")") (cdr x)) @@ -700,12 +725,11 @@ this function appends the default value from (when (org-string-nw-p re) (setq buffer (if (markerp pos) (marker-buffer pos) - (or (find-buffer-visiting file) - (find-file-noselect file)))) + (find-file-noselect file 'nowarn))) (with-current-buffer buffer (org-with-wide-buffer (goto-char pos) - (beginning-of-line 1) + (forward-line 0) (unless (looking-at-p re) (user-error "Invalid refile position, please clear the cache with `C-0 C-c C-w' before refiling")))))))) @@ -716,8 +740,7 @@ this function appends the default value from (let ((file (nth 1 parent-target)) (pos (nth 3 parent-target)) level) - (with-current-buffer (or (find-buffer-visiting file) - (find-file-noselect file)) + (with-current-buffer (find-file-noselect file 'nowarn) (org-with-wide-buffer (if pos (goto-char pos) @@ -730,7 +753,7 @@ this function appends the default value from (insert "\n" (make-string (if pos (org-get-valid-level level 1) 1) ?*) " " child "\n") - (beginning-of-line 0) + (forward-line -1) (list (concat (car parent-target) "/" child) file "" (point)))))) (defun org-olpath-completing-read (prompt collection &rest args) @@ -752,6 +775,14 @@ this function appends the default value from (concat string (substring r 0 (match-end 0)) f) x))) (all-completions string thetable predicate)))) + ((eq (car-safe flag) 'boundaries) + ;; See `completion-file-name-table'. + (let ((start (or (and (string-match "/" string) + (match-beginning 0)) + (length string))) + (end (and (string-match "/" (cdr flag)) + (match-beginning 0)))) + `(boundaries ,start . ,end))) ;; Exact match? ((eq flag 'lambda) (assoc string thetable)))) args))) diff --git a/elpa/org-9.6.7/org-src.el b/elpa/org-9.7.17/org-src.el similarity index 84% rename from elpa/org-9.6.7/org-src.el rename to elpa/org-9.7.17/org-src.el index aadd8eba..229bf62e 100644 --- a/elpa/org-9.6.7/org-src.el +++ b/elpa/org-9.7.17/org-src.el @@ -1,11 +1,11 @@ ;;; org-src.el --- Source code examples in Org -*- lexical-binding: t; -*- ;; -;; Copyright (C) 2004-2023 Free Software Foundation, Inc. +;; Copyright (C) 2004-2024 Free Software Foundation, Inc. ;; ;; Author: Carsten Dominik ;; Bastien Guerry ;; Dan Davison -;; Keywords: outlines, hypermedia, calendar, wp +;; Keywords: outlines, hypermedia, calendar, text ;; URL: https://orgmode.org ;; ;; This file is part of GNU Emacs. @@ -39,6 +39,7 @@ (require 'org-macs) (require 'org-compat) (require 'org-keys) +(require 'sh-script) (declare-function org--get-expected-indentation "org" (element contentsp)) (declare-function org-mode "org" ()) @@ -47,11 +48,19 @@ (declare-function org-element-at-point "org-element" (&optional pom cached-only)) (declare-function org-element-class "org-element" (datum &optional parent)) (declare-function org-element-context "org-element" (&optional element)) -(declare-function org-element-lineage "org-element" +(declare-function org-element-lineage "org-element-ast" (blob &optional types with-self)) (declare-function org-element--parse-paired-brackets "org-element" (char)) -(declare-function org-element-property "org-element" (property element)) -(declare-function org-element-type "org-element" (element)) +(declare-function org-element-property "org-element-ast" (property node)) +(declare-function org-element-begin "org-element" (node)) +(declare-function org-element-end "org-element" (node)) +(declare-function org-element-contents-begin "org-element" (node)) +(declare-function org-element-contents-end "org-element" (node)) +(declare-function org-element-post-affiliated "org-element" (node)) +(declare-function org-element-post-blank "org-element" (node)) +(declare-function org-element-parent "org-element-ast" (node)) +(declare-function org-element-type "org-element-ast" (node &optional anonymous)) +(declare-function org-element-type-p "org-element-ast" (node types)) (declare-function org-footnote-goto-definition "org-footnote" (label &optional location)) @@ -110,15 +119,16 @@ These are the regions where each line starts with a colon." (defcustom org-src-preserve-indentation nil "If non-nil preserve leading whitespace characters on export. -\\ -If non-nil leading whitespace characters in source code blocks -are preserved on export, and when switching between the org -buffer and the language mode edit buffer. - -When this variable is nil, after editing with `\\[org-edit-src-code]', -the minimum (across-lines) number of leading whitespace characters -are removed from all lines, and the code block is uniformly indented -according to the value of `org-edit-src-content-indentation'." + +If non-nil leading whitespace characters in source code blocks are +preserved on export, or adjusted while indenting or when switching +between the org buffer and the language mode edit buffer. + +When this variable is nil, while indenting with `\\[org-indent-block]' +or after editing with `\\[org-edit-src-code]', the minimum (across-lines) +number of leading whitespace characters are removed from all lines, +and the code block is uniformly indented according to the value of +`org-edit-src-content-indentation'." :group 'org-edit-structure :type 'boolean) @@ -194,11 +204,17 @@ You may want to use this hook for example to turn off `outline-minor-mode' or similar things which you want to have when editing a source code file, but which mess up the display of a snippet in Org exported files.") +(defun org-src--get-known-shells () + "List all the shells in `sh-ancestor-alist' for `org-src-lang-modes'. +The shells are associated with `sh-mode'." + (mapcar + (lambda (shell) (cons (symbol-name shell) 'sh)) + (delete-dups (org--flatten-tree sh-ancestor-alist)))) + (defcustom org-src-lang-modes - '(("C" . c) + `(("C" . c) ("C++" . c++) ("asymptote" . asy) - ("bash" . sh) ("beamer" . latex) ("calc" . fundamental) ("cpp" . c++) @@ -208,9 +224,10 @@ but which mess up the display of a snippet in Org exported files.") ("elisp" . emacs-lisp) ("ocaml" . tuareg) ("screen" . shell-script) - ("shell" . sh) ("sqlite" . sql) - ("toml" . conf-toml)) + ("toml" . conf-toml) + ("shell" . sh) + ,@(org-src--get-known-shells)) "Alist mapping languages to their major mode. The key is the language name. The value is the mode name, as @@ -221,11 +238,11 @@ not the case, this variable provides a way to simplify things on the user side. For example, there is no `ocaml-mode' in Emacs, but the mode to use is `tuareg-mode'." :group 'org-edit-structure - :package-version '(Org . "9.6") + :package-version '(Org . "9.7") :type '(repeat (cons - (string "Language name") - (symbol "Major mode")))) + (string :tag "Language name") + (symbol :tag "Major mode")))) (defcustom org-src-block-faces nil "Alist of faces to be used for source-block. @@ -233,7 +250,8 @@ Each element is a cell of the format (\"language\" FACE) -Where FACE is either a defined face or an anonymous face. +Where FACE is either a defined face or an anonymous face. Empty +language string refers to source blocks without specified language. For instance, the following would color the background of emacs-lisp source blocks and python source blocks in purple and @@ -247,7 +265,6 @@ green, respectability. (choice (face :tag "Face") (sexp :tag "Anonymous face")))) - :version "26.1" :package-version '(Org . "9.0")) (defcustom org-src-tab-acts-natively t @@ -310,9 +327,6 @@ is 0.") "File name associated to Org source buffer, or nil.") (put 'org-src-source-file-name 'permanent-local t) -(defvar-local org-src--preserve-blank-line nil) -(put 'org-src--preserve-blank-line 'permanent-local t) - (defun org-src--construct-edit-buffer-name (org-buffer-name lang) "Construct the buffer name for a source editing buffer. Format is \"*Org Src ORG-BUFFER-NAME[ LANG ]*\"." @@ -369,36 +383,36 @@ where BEG and END are buffer positions and CONTENTS is a string." (cond ((eq type 'footnote-definition) (let* ((beg (progn - (goto-char (org-element-property :post-affiliated datum)) + (goto-char (org-element-post-affiliated datum)) (search-forward "]"))) - (end (or (org-element-property :contents-end datum) beg))) + (end (or (org-element-contents-end datum) beg))) (list beg end (buffer-substring-no-properties beg end)))) ((eq type 'inline-src-block) - (let ((beg (progn (goto-char (org-element-property :begin datum)) + (let ((beg (progn (goto-char (org-element-begin datum)) (search-forward "{" (line-end-position) t))) - (end (progn (goto-char (org-element-property :end datum)) + (end (progn (goto-char (org-element-end datum)) (search-backward "}" (line-beginning-position) t)))) (list beg end (buffer-substring-no-properties beg end)))) ((eq type 'latex-fragment) - (let ((beg (org-element-property :begin datum)) - (end (org-with-point-at (org-element-property :end datum) + (let ((beg (org-element-begin datum)) + (end (org-with-point-at (org-element-end datum) (skip-chars-backward " \t") (point)))) (list beg end (buffer-substring-no-properties beg end)))) - ((org-element-property :contents-begin datum) - (let ((beg (org-element-property :contents-begin datum)) - (end (org-element-property :contents-end datum))) + ((org-element-contents-begin datum) + (let ((beg (org-element-contents-begin datum)) + (end (org-element-contents-end datum))) (list beg end (buffer-substring-no-properties beg end)))) ((memq type '(example-block export-block src-block comment-block)) - (list (progn (goto-char (org-element-property :post-affiliated datum)) + (list (progn (goto-char (org-element-post-affiliated datum)) (line-beginning-position 2)) - (progn (goto-char (org-element-property :end datum)) + (progn (goto-char (org-element-end datum)) (skip-chars-backward " \r\t\n") (line-beginning-position 1)) (org-element-property :value datum))) ((memq type '(fixed-width latex-environment table)) - (let ((beg (org-element-property :post-affiliated datum)) - (end (progn (goto-char (org-element-property :end datum)) + (let ((beg (org-element-post-affiliated datum)) + (end (progn (goto-char (org-element-end datum)) (skip-chars-backward " \r\t\n") (line-beginning-position 2)))) (list beg @@ -439,58 +453,89 @@ END." "Non-nil when point is on DATUM. DATUM is an element or an object. Consider blank lines or white spaces after it as being outside." - (and (>= (point) (org-element-property :begin datum)) + (and (>= (point) (org-element-begin datum)) (<= (point) - (org-with-wide-buffer - (goto-char (org-element-property :end datum)) - (skip-chars-backward " \r\t\n") - (if (eq (org-element-class datum) 'element) - (line-end-position) - (point)))))) - -(defun org-src--contents-for-write-back (write-back-buf) - "Populate WRITE-BACK-BUF with contents in the appropriate format. -Assume point is in the corresponding edit buffer." - (let ((indentation-offset - (if org-src--preserve-indentation 0 - (+ (or org-src--block-indentation 0) - (if (memq org-src--source-type '(example-block src-block)) - org-src--content-indentation - 0)))) - (use-tabs? (and (> org-src--tab-width 0) t)) - (preserve-fl (eq org-src--source-type 'latex-fragment)) - (source-tab-width org-src--tab-width) - (contents (org-with-wide-buffer - (let ((eol (line-end-position))) - (list (buffer-substring (point-min) eol) - (buffer-substring eol (point-max)))))) - (write-back org-src--allow-write-back) - (preserve-blank-line org-src--preserve-blank-line) - marker) + (org-with-wide-buffer + (goto-char (org-element-end datum)) + (skip-chars-backward " \r\t\n") + (if (eq (org-element-class datum) 'element) + (line-end-position) + (point)))))) + +(defun org-src-preserve-indentation-p (&optional node) + "Non-nil when indentation should be preserved within NODE. +When NODE is not passed, assume element at point." + (let ((node (or node (org-element-at-point)))) + (and (org-element-type-p node '(example-block src-block)) + (or (org-element-property :preserve-indent node) + org-src-preserve-indentation)))) + +(defun org-src--contents-for-write-back-1 + ( write-back-buf contents + &optional indentation-offset preserve-fl source-tab-width write-back) + "Populate WRITE-BACK-BUF with CONTENTS in the appropriate format. + +INDENTATION-OFFSET, when non-nil is additional indentation to be applied +to all the lines. PRESERVE-FL means that first line should not be +indented (useful for inline blocks contents that belong to paragraph). +The original indentation, if any, is not altered. + +TAB-WIDTH is `tab-width' to be used when indenting. The value of 0 +means that tabs should not be used. + +WRITE-BACK, when non-nil, is a function to be called with point at +WRITE-BACK-BUF after inserting the original contents, but before +applying extra indentation." + (let ((use-tabs? (and (> source-tab-width 0) t)) + indent-str) (with-current-buffer write-back-buf - ;; Reproduce indentation parameters from source buffer. - (setq indent-tabs-mode use-tabs?) - (when (> source-tab-width 0) (setq tab-width source-tab-width)) ;; Apply WRITE-BACK function on edit buffer contents. - (insert (org-no-properties (car contents))) - (setq marker (point-marker)) - (insert (org-no-properties (car (cdr contents)))) + (insert (org-no-properties contents)) (goto-char (point-min)) (when (functionp write-back) (save-excursion (funcall write-back))) ;; Add INDENTATION-OFFSET to every line in buffer, ;; unless indentation is meant to be preserved. - (when (> indentation-offset 0) - (when preserve-fl (forward-line)) + (when (and indentation-offset (> indentation-offset 0)) + ;; The exact sequence of tabs and spaces used to indent + ;; up to `indentation-offset' in the Org buffer. + (setq indent-str + (with-temp-buffer + ;; Reproduce indentation parameters. + (setq indent-tabs-mode use-tabs?) + (when (> source-tab-width 0) + (setq tab-width source-tab-width)) + (indent-to indentation-offset) + (buffer-string))) + ;; LaTeX-fragments are inline. Do not add indentation to their + ;; first line. + (when preserve-fl (forward-line)) (while (not (eobp)) - (skip-chars-forward " \t") - (when (or (not (eolp)) ; not a blank line - (and (eq (point) (marker-position marker)) ; current line - preserve-blank-line)) - (let ((i (current-column))) - (delete-region (line-beginning-position) (point)) - (indent-to (+ i indentation-offset)))) - (forward-line))) - (set-marker marker nil)))) + ;; Keep empty src lines empty, even when src block is + ;; indented on Org side. + ;; See https://list.orgmode.org/725763.1632663635@apollo2.minshall.org/T/ + (when (not (eolp)) ; not an empty line + (insert indent-str)) + (forward-line)))))) + +(defun org-src--contents-for-write-back (write-back-buf) + "Populate WRITE-BACK-BUF with contents in the appropriate format. +Assume point is in the corresponding edit buffer." + (org-src--contents-for-write-back-1 + write-back-buf + ;; CONTENTS + (org-with-wide-buffer (buffer-string)) + ;; INDENTATION + (if org-src--preserve-indentation 0 + (+ (or org-src--block-indentation 0) + (if (memq org-src--source-type '(example-block src-block)) + org-src--content-indentation + 0))) + ;; PRESERVE-FL + (eq org-src--source-type 'latex-fragment) + ;; TAB-WIDTH + org-src--tab-width + ;; WRITE-BACK + org-src--allow-write-back)) (defun org-src--edit-element (datum name &optional initialize write-back contents remote) @@ -532,24 +577,16 @@ Leave point in edit buffer." (source-file-name (buffer-file-name (buffer-base-buffer))) (source-tab-width (if indent-tabs-mode tab-width 0)) (type (org-element-type datum)) - (block-ind (org-with-point-at (org-element-property :begin datum) + (block-ind (org-with-point-at (org-element-begin datum) (cond ((save-excursion (skip-chars-backward " \t") (bolp)) (org-current-text-indentation)) - ((org-element-property :parent datum) + ((org-element-parent datum) (org--get-expected-indentation - (org-element-property :parent datum) nil)) + (org-element-parent datum) nil)) (t (org-current-text-indentation))))) (content-ind org-edit-src-content-indentation) - (blank-line (save-excursion (beginning-of-line) - (looking-at-p "^[[:space:]]*$"))) - (empty-line (and blank-line (looking-at-p "^$"))) - (preserve-blank-line (or (and blank-line (not empty-line)) - (and empty-line (= (+ block-ind content-ind) 0)))) - (preserve-ind - (and (memq type '(example-block src-block)) - (or (org-element-property :preserve-indent datum) - org-src-preserve-indentation))) + (preserve-ind (org-src-preserve-indentation-p datum)) ;; Store relative positions of mark (if any) and point ;; within the edited area. (point-coordinates (and (not remote) @@ -576,7 +613,7 @@ Leave point in edit buffer." ;; Initialize buffer. (when (functionp initialize) (let ((org-inhibit-startup t)) - (condition-case e + (condition-case-unless-debug e (funcall initialize) (error (message "Initialization fails with: %S" (error-message-string e)))))) @@ -595,7 +632,6 @@ Leave point in edit buffer." (setq org-src--overlay overlay) (setq org-src--allow-write-back write-back) (setq org-src-source-file-name source-file-name) - (setq org-src--preserve-blank-line preserve-blank-line) ;; Start minor mode. (org-src-mode) ;; Clear undo information so we cannot undo back to the @@ -627,9 +663,9 @@ Leave point in edit buffer." (defvar org-src-fontify-natively) ; Defined in org.el (defun org-src-font-lock-fontify-block (lang start end) "Fontify code block between START and END using LANG's syntax. -This function is called by Emacs' automatic fontification, as long +This function is called by Emacs's automatic fontification, as long as `org-src-fontify-natively' is non-nil." - (let ((modified (buffer-modified-p))) + (let ((modified (buffer-modified-p)) native-tab-width) (remove-text-properties start end '(face nil)) (let ((lang-mode (org-src-get-lang-mode lang))) (when (fboundp lang-mode) @@ -643,8 +679,11 @@ as `org-src-fontify-natively' is non-nil." ;; Add string and a final space to ensure property change. (insert string " ")) (unless (eq major-mode lang-mode) (funcall lang-mode)) + (setq native-tab-width tab-width) (font-lock-ensure) - (let ((pos (point-min)) next) + (let ((pos (point-min)) next + ;; Difference between positions here and in org-buffer. + (offset (- start (point-min)))) (while (setq next (next-property-change pos)) ;; Handle additional properties from font-lock, so as to ;; preserve, e.g., composition. @@ -658,7 +697,7 @@ as `org-src-fontify-natively' is non-nil." (when new-prop (if (not (eq prop 'invisible)) (put-text-property - (+ start (1- pos)) (1- (+ start next)) prop new-prop + (+ offset pos) (+ offset next) prop new-prop org-buffer) ;; Special case. `invisible' text property may ;; clash with Org folding. Do not assign @@ -690,7 +729,7 @@ as `org-src-fontify-natively' is non-nil." (when invisibility-spec (add-to-invisibility-spec invisibility-spec)) (put-text-property - (+ start (1- pos)) (1- (+ start next)) + (+ offset pos) (+ offset next) 'org-src-invisible new-prop org-buffer))))))) (setq pos next))) @@ -700,8 +739,21 @@ as `org-src-fontify-natively' is non-nil." (when (or (facep src-face) (listp src-face)) (font-lock-append-text-property start end 'face src-face)) (font-lock-append-text-property start end 'face 'org-block)) - ;; Clear abbreviated link folding. - (org-fold-region start end nil 'org-link) + ;; Display native tab indentation characters as spaces + (save-excursion + (goto-char start) + (let ((indent-offset + (if (org-src-preserve-indentation-p) 0 + (+ (progn (backward-char) + (org-current-text-indentation)) + org-edit-src-content-indentation)))) + (while (re-search-forward "^[ ]*\t" end t) + (let* ((b (and (eq indent-offset (move-to-column indent-offset)) + (point))) + (e (progn (skip-chars-forward "\t") (point))) + (s (and b (make-string (* (- e b) native-tab-width) ? )))) + (when (and b (< b e)) (add-text-properties b e `(display ,s))) + (forward-char))))) (add-text-properties start end '(font-lock-fontified t fontified t font-lock-multiline t)) @@ -709,7 +761,7 @@ as `org-src-fontify-natively' is non-nil." (defun org-fontify-inline-src-blocks (limit) "Try to apply `org-fontify-inline-src-blocks-1'." - (condition-case nil + (condition-case-unless-debug nil (org-fontify-inline-src-blocks-1 limit) (error (message "Org mode fontification error in %S at %d" (current-buffer) @@ -724,12 +776,9 @@ as `org-src-fontify-natively' is non-nil." (lang-beg (match-beginning 1)) (lang-end (match-end 1)) pt) - (font-lock-append-text-property - lang-beg lang-end 'face 'org-meta-line) - (font-lock-append-text-property - beg lang-beg 'face 'shadow) - (font-lock-append-text-property - beg lang-end 'face 'org-inline-src-block) + (add-face-text-property beg lang-end 'org-inline-src-block) + (add-face-text-property beg lang-beg 'shadow) + (add-face-text-property lang-beg lang-end 'org-meta-line) (setq pt (goto-char lang-end)) ;; `org-element--parse-paired-brackets' doesn't take a limit, so to ;; prevent it searching the entire rest of the buffer we temporarily @@ -741,13 +790,11 @@ as `org-src-fontify-natively' is non-nil." (point))) (point-max)))) (when (ignore-errors (org-element--parse-paired-brackets ?\[)) - (font-lock-append-text-property - pt (point) 'face 'org-inline-src-block) + (add-face-text-property pt (point) 'org-inline-src-block) (setq pt (point))) (when (ignore-errors (org-element--parse-paired-brackets ?\{)) (remove-text-properties pt (point) '(face nil)) - (font-lock-append-text-property - pt (1+ pt) 'face '(org-inline-src-block shadow)) + (add-face-text-property pt (1+ pt) '(org-inline-src-block shadow)) (unless (= (1+ pt) (1- (point))) (if org-src-fontify-natively (org-src-font-lock-fontify-block @@ -755,8 +802,7 @@ as `org-src-fontify-natively' is non-nil." (1+ pt) (1- (point))) (font-lock-append-text-property (1+ pt) (1- (point)) 'face 'org-inline-src-block))) - (font-lock-append-text-property - (1- (point)) (point) 'face '(org-inline-src-block shadow)) + (add-face-text-property (1- (point)) (point) '(org-inline-src-block shadow)) (setq pt (point))))) t))) @@ -874,7 +920,6 @@ INFO should be a list similar in format to the return value of (interactive) (let ((session (cdr (assq :session (nth 2 info))))) (and session (not (string= session "none")) - (org-babel-comint-buffer-livep session) (let ((f (intern (format "org-babel-%s-associate-session" (nth 0 info))))) (and (fboundp f) (funcall f session)))))) @@ -905,16 +950,16 @@ remotely with point temporarily at the start of the code block in the Org buffer. This command is not bound to a key by default, to avoid conflicts -with language major mode bindings. To bind it to C-c @ in all +with language major mode bindings. To bind it to \\`C-c @' in all language major modes, you could use (add-hook \\='org-src-mode-hook (lambda () (define-key org-src-mode-map \"\\C-c@\" \\='org-src-do-key-sequence-at-code-block))) -In that case, for example, C-c @ t issued in code edit buffers -would tangle the current Org code block, C-c @ e would execute -the block and C-c @ h would display the other available +In that case, for example, \\`C-c @ t' issued in code edit buffers +would tangle the current Org code block, \\`C-c @ e' would execute +the block and \\`C-c @ h' would display the other available Org-babel commands." (interactive "kOrg-babel key: ") (if (equal key (kbd "C-g")) (keyboard-quit) @@ -961,7 +1006,7 @@ Raise an error when current buffer is not a source editing buffer." (`current-window (pop-to-buffer-same-window buffer)) (`other-window (let ((cur-win (selected-window))) - (org-switch-to-buffer-other-window buffer) + (switch-to-buffer-other-window buffer) (when (eq context 'exit) (quit-restore-window cur-win)))) (`split-window-below (if (eq context 'exit) @@ -984,9 +1029,10 @@ Raise an error when current buffer is not a source editing buffer." (pop-to-buffer-same-window buffer)) (_ (switch-to-buffer-other-frame buffer)))) (`reorganize-frame - (when (eq context 'edit) (delete-other-windows)) - (org-switch-to-buffer-other-window buffer) - (when (eq context 'exit) (delete-other-windows))) + (pcase context + (`edit (pop-to-buffer buffer '(org-display-buffer-split))) + (`exit (pop-to-buffer buffer '(org-display-buffer-full-frame))) + (_ (switch-to-buffer-other-window buffer)))) (`switch-invisibly (set-buffer buffer)) (_ (message "Invalid value %s for `org-src-window-setup'" @@ -1031,7 +1077,7 @@ A coderef format regexp can only match at the end of a line." (interactive) (let* ((context (org-element-context)) (label (org-element-property :label context))) - (unless (and (eq (org-element-type context) 'footnote-reference) + (unless (and (org-element-type-p context 'footnote-reference) (org-src--on-datum-p context)) (user-error "Not on a footnote reference")) (unless label (user-error "Cannot edit remotely anonymous footnotes")) @@ -1039,16 +1085,16 @@ A coderef format regexp can only match at the end of a line." (org-footnote-goto-definition label) (backward-char) (org-element-context))) - (inline? (eq 'footnote-reference (org-element-type definition))) + (inline? (org-element-type-p definition 'footnote-reference)) (contents (org-with-wide-buffer (buffer-substring-no-properties - (or (org-element-property :post-affiliated definition) - (org-element-property :begin definition)) + (or (org-element-post-affiliated definition) + (org-element-begin definition)) (cond - (inline? (1+ (org-element-property :contents-end definition))) - ((org-element-property :contents-end definition)) - (t (goto-char (org-element-property :post-affiliated definition)) + (inline? (1+ (org-element-contents-end definition))) + ((org-element-contents-end definition)) + (t (goto-char (org-element-post-affiliated definition)) (line-end-position))))))) (add-text-properties 0 @@ -1079,7 +1125,7 @@ A coderef format regexp can only match at the end of a line." ;; If footnote reference belongs to a table, make sure to ;; remove any newline characters in order to preserve ;; table's structure. - (when (org-element-lineage definition '(table-cell)) + (when (org-element-lineage definition 'table-cell) (while (search-forward "\n" nil t) (replace-match " "))))) contents 'remote)) @@ -1098,7 +1144,7 @@ the area in the Org mode buffer. Throw an error when not at such a table." (interactive) (let ((element (org-element-at-point))) - (unless (and (eq (org-element-type element) 'table) + (unless (and (org-element-type-p element 'table) (eq (org-element-property :type element) 'table.el) (org-src--on-datum-p element)) (user-error "Not in a table.el table")) @@ -1114,14 +1160,14 @@ Throw an error when not at such a table." "Edit LaTeX fragment at point." (interactive) (let ((context (org-element-context))) - (unless (and (eq 'latex-fragment (org-element-type context)) + (unless (and (org-element-type-p context 'latex-fragment) (org-src--on-datum-p context)) (user-error "Not on a LaTeX fragment")) (let* ((contents (buffer-substring-no-properties - (org-element-property :begin context) - (- (org-element-property :end context) - (org-element-property :post-blank context)))) + (org-element-begin context) + (- (org-element-end context) + (org-element-post-blank context)))) (delim-length (if (string-match "\\`\\$[^$]" contents) 1 2))) ;; Make the LaTeX deliminators read-only. (add-text-properties 0 delim-length @@ -1145,7 +1191,7 @@ Throw an error when not at such a table." ;; If within a table a newline would disrupt the structure, ;; so remove newlines. (goto-char (point-min)) - (when (org-element-lineage context '(table-cell)) + (when (org-element-lineage context 'table-cell) (while (search-forward "\n" nil t) (replace-match " ")))) contents)) t)) @@ -1162,7 +1208,7 @@ will then replace the LaTeX environment in the Org mode buffer." (interactive) (let ((element (org-element-at-point))) - (unless (and (eq (org-element-type element) 'latex-environment) + (unless (and (org-element-type-p element 'latex-environment) (org-src--on-datum-p element)) (user-error "Not in a LaTeX environment")) (org-src--edit-element @@ -1186,7 +1232,7 @@ the area in the Org mode buffer. Throw an error when not at an export block." (interactive) (let ((element (org-element-at-point))) - (unless (and (eq (org-element-type element) 'export-block) + (unless (and (org-element-type-p element 'export-block) (org-src--on-datum-p element)) (user-error "Not in an export block")) (let* ((type (downcase (or (org-element-property :type element) @@ -1214,7 +1260,7 @@ then replace the area in the Org mode buffer. Throw an error when not at a comment block." (interactive) (let ((element (org-element-at-point))) - (unless (and (eq (org-element-type element) 'comment-block) + (unless (and (org-element-type-p element 'comment-block) (org-src--on-datum-p element)) (user-error "Not in a comment block")) (org-src--edit-element @@ -1259,16 +1305,18 @@ name of the sub-editing buffer." element (or edit-buffer-name (org-src--construct-edit-buffer-name (buffer-name) lang)) - lang-f + (lambda () + (when lang-f (funcall lang-f)) + (setq-local org-coderef-label-format + (or (org-element-property :label-fmt element) + org-coderef-label-format)) + (when (eq type 'src-block) + (setq org-src--babel-info babel-info))) (and (null code) (lambda () (org-escape-code-in-region (point-min) (point-max)))) (and code (org-unescape-code-in-string code))) ;; Finalize buffer. - (setq-local org-coderef-label-format - (or (org-element-property :label-fmt element) - org-coderef-label-format)) (when (eq type 'src-block) - (setq org-src--babel-info babel-info) (let ((edit-prep-func (intern (concat "org-babel-edit-prep:" lang)))) (when (fboundp edit-prep-func) (funcall edit-prep-func babel-info)))) @@ -1278,7 +1326,7 @@ name of the sub-editing buffer." "Edit inline source code at point." (interactive) (let ((context (org-element-context))) - (unless (and (eq (org-element-type context) 'inline-src-block) + (unless (and (org-element-type-p context 'inline-src-block) (org-src--on-datum-p context)) (user-error "Not on inline source code")) (let* ((lang (org-element-property :language context)) @@ -1323,7 +1371,7 @@ will then replace the area in the Org mode buffer." (interactive) (let ((element (org-element-at-point))) - (unless (and (eq (org-element-type element) 'fixed-width) + (unless (and (org-element-type-p element 'fixed-width) (org-src--on-datum-p element)) (user-error "Not in a fixed-width area")) (org-src--edit-element @@ -1408,8 +1456,8 @@ EVENT is passed to `mouse-set-point'." (org-with-wide-buffer (when (and write-back (not (equal (buffer-substring beg end) - (with-current-buffer write-back-buf - (buffer-string))))) + (with-current-buffer write-back-buf + (buffer-string))))) (undo-boundary) (goto-char beg) (let ((expecting-bol (bolp))) @@ -1430,11 +1478,7 @@ EVENT is passed to `mouse-set-point'." (goto-char beg) (cond ;; Block is hidden; move at start of block. - ((if (eq org-fold-core-style 'text-properties) - (org-fold-folded-p nil 'block) - (cl-some (lambda (o) (eq (overlay-get o 'invisible) 'org-hide-block)) - (overlays-at (point)))) - (beginning-of-line 0)) + ((org-fold-folded-p nil 'block) (forward-line -1)) (write-back (org-src--goto-coordinates coordinates beg end)))) ;; Clean up left-over markers and restore window configuration. (set-marker beg nil) diff --git a/elpa/org-9.6.7/org-table.el b/elpa/org-9.7.17/org-table.el similarity index 94% rename from elpa/org-9.6.7/org-table.el rename to elpa/org-9.7.17/org-table.el index 83bad3f3..1d161149 100644 --- a/elpa/org-9.6.7/org-table.el +++ b/elpa/org-9.7.17/org-table.el @@ -1,9 +1,9 @@ ;;; org-table.el --- The Table Editor for Org -*- lexical-binding: t; -*- -;; Copyright (C) 2004-2023 Free Software Foundation, Inc. +;; Copyright (C) 2004-2024 Free Software Foundation, Inc. ;; Author: Carsten Dominik -;; Keywords: outlines, hypermedia, calendar, wp +;; Keywords: outlines, hypermedia, calendar, text ;; URL: https://orgmode.org ;; ;; This file is part of GNU Emacs. @@ -52,14 +52,16 @@ (declare-function org-duration-p "org-duration" (duration &optional canonical)) (declare-function org-duration-to-minutes "org-duration" (duration &optional canonical)) (declare-function org-element-at-point "org-element" (&optional pom cached-only)) -(declare-function org-element-contents "org-element" (element)) -(declare-function org-element-extract-element "org-element" (element)) +(declare-function org-element-contents "org-element-ast" (node)) +(declare-function org-element-extract "org-element-ast" (node)) (declare-function org-element-interpret-data "org-element" (data)) -(declare-function org-element-lineage "org-element" (blob &optional types with-self)) +(declare-function org-element-lineage "org-element-ast" (blob &optional types with-self)) (declare-function org-element-map "org-element" (data types fun &optional info first-match no-recursion with-affiliated)) -(declare-function org-element-parse-buffer "org-element" (&optional granularity visible-only)) -(declare-function org-element-property "org-element" (property element)) -(declare-function org-element-type "org-element" (element)) +(declare-function org-element-parse-buffer "org-element" (&optional granularity visible-only keep-deferred)) +(declare-function org-element-property "org-element-ast" (property node)) +(declare-function org-element-end "org-element" (node)) +(declare-function org-element-post-affiliated "org-element" (node)) +(declare-function org-element-type-p "org-element-ast" (node types)) (declare-function org-element-cache-reset "org-element" (&optional all no-persistence)) (declare-function org-entry-get "org" (pom property &optional inherit literal-nil)) (declare-function org-export-create-backend "ox" (&rest rest) t) @@ -417,7 +419,7 @@ It is probably good to never set this variable to nil, for the sake of portability of tables." :group 'org-table-calculation :type '(choice - (const :tag "Allow to cross" t) + (const :tag "Allow crossing hline" t) (const :tag "Stick to hline" nil) (const :tag "Error on attempt to cross" error))) @@ -465,18 +467,20 @@ prevents it from hanging Emacs." This may be useful when columns have been shrunk." (save-excursion (when pos (goto-char pos)) - (goto-char (line-beginning-position)) - (let ((end (line-end-position)) str) - (goto-char (1- pos)) - (while (progn (forward-char 1) (< (point) end)) - (let ((ov (car (overlays-at (point))))) - (if (not ov) - (push (char-to-string (char-after)) str) - (push (overlay-get ov 'display) str) - (goto-char (1- (overlay-end ov)))))) - (format "|%s" (mapconcat #'identity (reverse str) ""))))) + (let* ((beg (line-beginning-position)) + (end (line-end-position)) + (str (buffer-substring beg end))) + ;; FIXME: This does not handle intersecting overlays. + (dolist (ov (overlays-in beg end)) + (when (overlay-get ov 'display) + (put-text-property + (- (overlay-start ov) beg) (- (overlay-end ov) beg) + 'display (overlay-get ov 'display) + str))) + str))) (defvar-local org-table-header-overlay nil) +(put 'org-table-header-overlay 'permanent-local t) (defun org-table-header-set-header () "Display the header of the table at point." (let ((gcol temporary-goal-column)) @@ -484,19 +488,29 @@ This may be useful when columns have been shrunk." (progn (when (overlayp org-table-header-overlay) (delete-overlay org-table-header-overlay)) + ;; We might be called after scrolling but before display is + ;; updated. Make sure that any queued redisplay is executed + ;; before we look into `window-start'. + (redisplay) (let* ((ws (window-start)) (beg (save-excursion + ;; Check table at window start, not at point. + ;; Point might be after the table, or at + ;; another table located below the one visible + ;; on top. + (goto-char ws) (goto-char (org-table-begin)) (while (or (org-at-table-hline-p) (looking-at-p ".*|\\s-+<[rcl]?\\([0-9]+\\)?>")) (move-beginning-of-line 2)) - (line-beginning-position))) - (end (save-excursion (goto-char beg) (line-end-position)))) + (line-beginning-position)))) (if (pos-visible-in-window-p beg) (when (overlayp org-table-header-overlay) (delete-overlay org-table-header-overlay)) (setq org-table-header-overlay - (make-overlay ws (+ ws (- end beg)))) + (make-overlay + (save-excursion (goto-char ws) (line-beginning-position)) + (save-excursion (goto-char ws) (line-end-position)))) (org-overlay-display org-table-header-overlay (org-table-row-get-visible-string beg) @@ -572,7 +586,7 @@ This works for both table types.") "Match a reference that needs translation, for reference display.") (defconst org-table--separator-space-pre - (propertize " " 'display '(space :relative-width 1)) + (propertize " " 'display '(space :relative-width 1) 'rear-nonsticky t) "Space used in front of fields when aligning the table. This space serves as a segment separator for the purposes of the bidirectional reordering. @@ -608,7 +622,7 @@ This variable is set by `org-before-change-function'. `org-table-align' sets it back to nil.") (defvar orgtbl-after-send-table-hook nil - "Hook for functions attaching to `C-c C-c', if the table is sent. + "Hook for functions attaching to \\`C-c C-c', if the table is sent. This can be used to add additional functionality after the table is sent to the receiver position, otherwise, if table is not sent, the functions are not run.") @@ -752,16 +766,16 @@ Field is restored even in case of abnormal exit." "Non-nil when point (or POS) is in #+TBLFM line." (save-excursion (goto-char (or pos (point))) - (beginning-of-line) + (forward-line 0) (and (let ((case-fold-search t)) (looking-at org-TBLFM-regexp)) - (eq (org-element-type (org-element-at-point)) 'table)))) + (org-element-type-p (org-element-at-point) 'table)))) (defun org-at-table-p (&optional table-type) "Non-nil if the cursor is inside an Org table. If TABLE-TYPE is non-nil, also check for table.el-type tables." (and (org-match-line (if table-type "[ \t]*[|+]" "[ \t]*|")) (or (not (derived-mode-p 'org-mode)) - (let ((e (org-element-lineage (org-element-at-point) '(table) t))) + (let ((e (org-element-lineage (org-element-at-point) 'table t))) (and e (or table-type (eq 'org (org-element-property :type e)))))))) @@ -769,7 +783,7 @@ If TABLE-TYPE is non-nil, also check for table.el-type tables." "Non-nil when point is at a table.el table." (and (org-match-line "[ \t]*[|+]") (let ((element (org-element-at-point))) - (and (eq (org-element-type element) 'table) + (and (org-element-type-p element 'table) (eq (org-element-property :type element) 'table.el))))) (defun org-at-table-hline-p () @@ -843,7 +857,7 @@ SIZE is a string Columns x Rows like for example \"3x2\"." "\n"))) (if (string-match "^[ \t]*$" (buffer-substring-no-properties (line-beginning-position) (point))) - (beginning-of-line 1) + (forward-line 0) (newline)) ;; (mapcar (lambda (x) (insert line)) (make-list rows t)) (dotimes (_ rows) (insert line)) @@ -878,7 +892,10 @@ nil When nil, the command tries to be smart and figure out the separator in the following way: - when each line contains a TAB, assume TAB-separated material - when each line contains a comma, assume CSV material - - else, assume one or more SPACE characters as separator." + - else, assume one or more SPACE characters as separator. +`babel-auto' + Use the same rules as nil, but do not try any separator when + the region contains a single line and has no commas or tabs." (interactive "r\nP") (let* ((beg (min beg0 end0)) (end (max beg0 end0)) @@ -889,18 +906,21 @@ nil When nil, the command tries to be smart and figure out the (when (equal separator '(64)) (setq separator (read-regexp "Regexp for field separator"))) (goto-char beg) - (beginning-of-line 1) + (forward-line 0) (setq beg (point-marker)) (goto-char end) (if (bolp) (backward-char 1) (end-of-line 1)) (setq end (point-marker)) ;; Get the right field separator - (unless separator + (when (or (not separator) (eq separator 'babel-auto)) (goto-char beg) (setq separator (cond - ((not (re-search-forward "^[^\n\t]+$" end t)) '(16)) - ((not (re-search-forward "^[^\n,]+$" end t)) '(4)) + ((not (save-excursion (re-search-forward "^[^\n\t]+$" end t))) '(16)) + ((not (save-excursion (re-search-forward "^[^\n,]+$" end t))) '(4)) + ((and (eq separator 'babel-auto) + (= 1 (count-lines beg end))) + (rx unmatchable)) (t 1)))) (goto-char beg) (if (equal separator '(4)) @@ -908,13 +928,13 @@ nil When nil, the command tries to be smart and figure out the ;; parse the csv stuff (cond ((looking-at "^") (insert "| ")) - ((looking-at "[ \t]*$") (replace-match " |") (beginning-of-line 2)) + ((looking-at "[ \t]*$") (replace-match " |") (forward-line 1)) ((looking-at "[ \t]*\"\\([^\"\n]*\\)\"") (replace-match "\\1") (if (looking-at "\"") (insert "\""))) ((looking-at "[^,\n]+") (goto-char (match-end 0))) ((looking-at "[ \t]*,") (replace-match " | ")) - (t (beginning-of-line 2)))) + (t (forward-line 1)))) (setq re (cond ((equal separator '(4)) "^\\|\"?[ \t]*,[ \t]*\"?") ((equal separator '(16)) "^\\|\t") @@ -991,9 +1011,9 @@ applies a recipe that works for simple tables." ;; insert a hline before first (goto-char beg) (org-table-insert-hline 'above) - (beginning-of-line -1) + (forward-line -2) ;; insert a hline after each line - (while (progn (beginning-of-line 3) (< (point) end)) + (while (progn (forward-line 2) (< (point) end)) (org-table-insert-hline)) (goto-char beg) (setq end (move-marker end (org-table-end))) @@ -1015,7 +1035,7 @@ With a non-nil optional argument TABLE-TYPE, return the beginning of a table.el-type table. This function assumes point is on a table." (cond (table-type - (org-element-property :post-affiliated (org-element-at-point))) + (org-element-post-affiliated (org-element-at-point))) ((save-excursion (and (re-search-backward org-table-border-regexp nil t) (line-beginning-position 2)))) @@ -1029,7 +1049,7 @@ a table.el-type table. This function assumes point is on a table." (save-excursion (cond (table-type - (goto-char (org-element-property :end (org-element-at-point))) + (goto-char (org-element-end (org-element-at-point))) (skip-chars-backward " \t\n") (line-beginning-position 2)) ((re-search-forward org-table-border-regexp nil t) @@ -1067,7 +1087,7 @@ Before doing so, re-align the table if necessary." (goto-char (match-beginning 1))) (if (looking-at "-") (progn - (beginning-of-line 0) + (forward-line -1) (org-table-insert-row 'below)) (if (looking-at " ") (forward-char 1)))) (error @@ -1133,7 +1153,8 @@ With numeric argument N, move N-1 fields forward first." ;;;###autoload (defun org-table-next-row () "Go to the next row (same column) in the current table. -Before doing so, re-align the table if necessary." +When next row is an hline or outside the table, create a new empty +row. Before doing so, re-align the table if necessary." (interactive) (org-table-maybe-eval-formula) (org-table-maybe-recalculate-line) @@ -1141,11 +1162,11 @@ Before doing so, re-align the table if necessary." org-table-may-need-update) (org-table-align)) (let ((col (org-table-current-column))) - (beginning-of-line 2) + (forward-line 1) (unless (bolp) (insert "\n")) ;missing newline at eob (when (or (not (org-at-table-p)) (org-at-table-hline-p)) - (beginning-of-line 0) + (forward-line -1) (org-table-insert-row 'below)) (org-table-goto-column col) (skip-chars-backward "^|\n\r") @@ -1188,7 +1209,7 @@ When ALIGN is set, also realign the table." (interactive) (save-excursion (let ((pos (point))) - (beginning-of-line) + (forward-line 0) (if (not (search-forward "|" pos t)) 0 (let ((column 1) (separator (if (org-at-table-hline-p) "[+|]" "|"))) @@ -1229,7 +1250,7 @@ Return t when the line exists, nil if it does not exist." (if (looking-at "|[^|\n]+") (let* ((pos (match-beginning 0)) (match (match-string 0)) - (len (save-match-data (org-string-width match)))) + (len (save-match-data (org-string-width match nil 'org-table)))) (replace-match (concat "|" (make-string (1- len) ?\ ))) (goto-char (+ 2 pos)) (substring match 1))))) @@ -1340,7 +1361,7 @@ of the field. If there are less than N fields, just go to after the last delimiter. However, when FORCE is non-nil, create new columns if necessary." (interactive "p") - (beginning-of-line 1) + (forward-line 0) (when (> n 0) (while (and (> (setq n (1- n)) -1) (or (search-forward "|" (line-end-position) t) @@ -1619,15 +1640,15 @@ Swap with anything in target cell." (interactive "P") (let* ((col (current-column)) (pos (point)) - (hline1p (save-excursion (beginning-of-line 1) + (hline1p (save-excursion (forward-line 0) (looking-at org-table-hline-regexp))) (dline1 (org-table-current-dline)) (dline2 (+ dline1 (if up -1 1))) - (tonew (if up 0 2)) + (tonew (if up -1 1)) hline2p) (when (and up (= (point-min) (line-beginning-position))) (user-error "Cannot move row further")) - (beginning-of-line tonew) + (forward-line tonew) (when (or (and (not up) (eobp)) (not (org-at-table-p))) (goto-char pos) (user-error "Cannot move row further")) @@ -1636,16 +1657,16 @@ Swap with anything in target cell." (goto-char pos) (let ((row (delete-and-extract-region (line-beginning-position) (line-beginning-position 2)))) - (beginning-of-line tonew) + (forward-line tonew) (unless (bolp) (insert "\n")) ;at eob without a newline (insert row) (unless (bolp) (insert "\n")) ;missing final newline in ROW - (beginning-of-line 0) + (forward-line -1) (org-move-to-column col) (unless (or hline1p hline2p (not (or (not org-table-fix-formulas-confirm) - (funcall org-table-fix-formulas-confirm - "Fix formulas? ")))) + (funcall org-table-fix-formulas-confirm + "Fix formulas? ")))) (org-table-fix-formulas "@" (list (cons (number-to-string dline1) (number-to-string dline2)) @@ -1666,12 +1687,12 @@ With prefix ARG, insert below the current line." ;; Fix the first field if necessary (when (string-match "^[ \t]*| *[#*$] *|" line) (setq new (replace-match (match-string 0 line) t t new))) - (beginning-of-line (if arg 2 1)) + (forward-line (if arg 1 0)) ;; Buffer may not end of a newline character, so ensure - ;; (beginning-of-line 2) moves point to a new line. + ;; (forward-line 1) moves point to a new line. (unless (bolp) (insert "\n")) (let (org-table-may-need-update) (insert-before-markers new "\n")) - (beginning-of-line 0) + (forward-line -1) (re-search-forward "| ?" (line-end-position) t) (when (or org-table-may-need-update org-table-overlay-coordinates) (org-table-align)) @@ -1697,9 +1718,9 @@ With prefix ABOVE, insert above the current line." (concat "+" (make-string (- (match-end 1) (match-beginning 1)) ?-) "|") t t line))) (and (string-match "\\+" line) (setq line (replace-match "|" t t line))) - (beginning-of-line (if above 1 2)) + (forward-line (if above 0 1)) (insert line "\n") - (beginning-of-line (if above 1 -1)) + (forward-line (if above 0 -2)) (org-move-to-column col) (when org-table-overlay-coordinates (org-table-align))))) @@ -1728,7 +1749,7 @@ In particular, this does handle wide and invisible characters." (concat "|" (make-string (save-match-data - (org-string-width (match-string 1 s))) + (org-string-width (match-string 1 s) nil 'org-table)) ?\ ) "|") t t s))) @@ -1745,7 +1766,7 @@ In particular, this does handle wide and invisible characters." (org-table-with-shrunk-columns (kill-region (line-beginning-position) (min (1+ (line-end-position)) (point-max))) - (if (not (org-at-table-p)) (beginning-of-line 0)) + (if (not (org-at-table-p)) (forward-line -1)) (org-move-to-column col) (when (and dline (or (not org-table-fix-formulas-confirm) @@ -1891,7 +1912,7 @@ However, when N is 0, do not increment the field at all." (save-excursion ;; Get reference field. (if initial-field (setq field initial-field) - (beginning-of-line) + (forward-line 0) (setq field (catch :exit (while (re-search-backward org-table-dataline-regexp beg t) @@ -1899,7 +1920,7 @@ However, when N is 0, do not increment the field at all." (cond ((and (> n 1) f) (cl-decf n)) (f (throw :exit (org-trim f))) (t nil)) - (beginning-of-line))) + (forward-line 0))) (user-error "No non-empty field found")))) ;; Check if increment is appropriate, and how it should be done. (when (and org-table-copy-increment (/= n 0)) @@ -1921,8 +1942,8 @@ However, when N is 0, do not increment the field at all." (let ((org-table-may-need-update nil)) (org-table-next-row)) (org-table-blank-field)) ;; Insert the new field. NEW-FIELD may be nil if - ;; `org-table-increment' is nil, or N = 0. In that case, copy - ;; FIELD. + ;; `org-table-copy-increment' is nil, or N = 0. In that case, + ;; copy FIELD. (insert (or next-field field)) (org-table-maybe-recalculate-line) (org-table-align))) @@ -2048,7 +2069,7 @@ toggle `org-table-follow-field-mode'." (cw (current-window-configuration)) p) (goto-char pos) - (org-switch-to-buffer-other-window "*Org Table Edit Field*") + (switch-to-buffer-other-window "*Org Table Edit Field*") (when (and (local-variable-p 'org-field-marker) (markerp org-field-marker)) (move-marker org-field-marker nil)) @@ -2184,7 +2205,7 @@ If optional argument LOCATION is a buffer position, insert it at LOCATION instead." (save-excursion (if location - (progn (goto-char location) (beginning-of-line)) + (progn (goto-char location) (forward-line 0)) (goto-char (org-table-end))) (let ((case-fold-search t)) (if (looking-at "\\([ \t]*\n\\)*[ \t]*\\(#\\+TBLFM:\\)\\(.*\n?\\)") @@ -2234,7 +2255,7 @@ on the first line after the table. However, if optional argument LOCATION is a buffer position, consider the formulas there." (save-excursion (if location - (progn (goto-char location) (beginning-of-line)) + (progn (goto-char location) (forward-line 0)) (goto-char (org-table-end))) (let ((case-fold-search t)) (when (looking-at "\\([ \t]*\n\\)*[ \t]*#\\+TBLFM: *\\(.*\\)") @@ -2354,7 +2375,7 @@ of the new mark." newchar)) (when l1 (goto-char l1)) (save-excursion - (beginning-of-line) + (forward-line 0) (unless (looking-at org-table-dataline-regexp) (user-error "Not at a table data line"))) (when no-special-column @@ -2363,7 +2384,7 @@ of the new mark." (let ((previous-line-end (line-end-position)) (newchar (save-excursion - (beginning-of-line) + (forward-line 0) (cond ((not (looking-at "^[ \t]*| *\\([#!$*^_ ]\\) *|")) "#") (newchar) (t (cadr (member (match-string 1) @@ -2395,8 +2416,8 @@ of the new mark." (interactive) (and org-table-allow-automatic-line-recalculation (not (and (memq last-command org-recalc-commands) - (eq org-last-recalc-line (line-beginning-position)))) - (save-excursion (beginning-of-line 1) + (eq org-last-recalc-line (line-beginning-position)))) + (save-excursion (forward-line 0) (looking-at org-table-auto-recalculate-regexp)) (org-table-recalculate) t)) @@ -2627,10 +2648,10 @@ location of point." duration-output-format) ev)) - ;; Use <...> time-stamps so that Calc can handle them. + ;; Use <...> timestamps so that Calc can handle them. (setq form (replace-regexp-in-string org-ts-regexp-inactive "<\\1>" form)) - ;; Internationalize local time-stamps by setting locale to + ;; Internationalize local timestamps by setting locale to ;; "C". (setq form (replace-regexp-in-string @@ -2647,11 +2668,16 @@ location of point." form (calc-eval (cons form calc-modes) (when (and (not keep-empty) numbers) 'num))) - ev (if duration (org-table-time-seconds-to-string - (if (string-match "^[0-9]+:[0-9]+\\(?::[0-9]+\\)?$" ev) - (string-to-number (org-table-time-string-to-seconds ev)) - (string-to-number ev)) - duration-output-format) + ev (if (and duration + ;; When the result is an empty string, + ;; keep it empty. + ;; See https://list.orgmode.org/orgmode/CAF_DUeEFpNU5UXjE80yB1MB9xj5oVLqG=XadnkqCdzWtakWdPg@mail.gmail.com/ + (not (string-empty-p ev))) + (org-table-time-seconds-to-string + (if (string-match "^[0-9]+:[0-9]+\\(?::[0-9]+\\)?$" ev) + (string-to-number (org-table-time-string-to-seconds ev)) + (string-to-number ev)) + duration-output-format) ev))) (when org-table-formula-debug @@ -2861,10 +2887,15 @@ list, `literal' is for the format specifier L." (if lispp (if (eq lispp 'literal) elements - (if (and (eq elements "") (not keep-empty)) - "" - (prin1-to-string - (if numbers (string-to-number elements) elements)))) + ;; Ignore KEEP-EMPTY here. + ;; When ELEMENTS="" and NUMBERS=t, (string-to-number "") + ;; returns 0 - consistent with (0) for Calc branch. + ;; When ELEMENTS="" and NUMBERS=nil, `prin1-to-string' will + ;; return "\"\"" - historical behavior that also does not + ;; leave missing arguments in formulas like (string< $1 $2) + ;; when $2 cell is empty. + (prin1-to-string + (if numbers (string-to-number elements) elements))) (if (string-match "\\S-" elements) (progn (when numbers (setq elements (number-to-string @@ -3150,7 +3181,7 @@ with the prefix ARG." (insert formula "\n") (let ((e (point-marker))) ;; Recalculate the table. - (beginning-of-line 0) ; move to the inserted line + (forward-line -1) ; move to the inserted line (skip-chars-backward " \r\n\t") (unwind-protect (org-call-with-arg #'org-table-recalculate (or arg t)) @@ -3354,7 +3385,10 @@ Parameters get priority." (titles '((column . "# Column Formulas\n") (field . "# Field and Range Formulas\n") (named . "# Named Field Formulas\n")))) - (org-switch-to-buffer-other-window "*Edit Formulas*") + (let ((pop-up-frames nil)) + ;; We explicitly prohibit creating edit buffer in a new frame + ;; - such configuration is not supported. + (switch-to-buffer-other-window "*Edit Formulas*")) (erase-buffer) ;; Keep global-font-lock-mode from turning on font-lock-mode (let ((font-lock-global-modes '(not fundamental-mode))) @@ -3675,7 +3709,9 @@ With prefix ARG, apply the new formulas to the table." (org-table-store-formulas eql) (set-marker pos nil) (set-marker source nil) - (kill-buffer "*Edit Formulas*") + (when-let* ((window (get-buffer-window "*Edit Formulas*" t))) + (quit-window 'kill window)) + (when (get-buffer "*Edit Formulas*") (kill-buffer "*Edit Formulas*")) (if arg (org-table-recalculate 'all) (message "New formulas installed - press C-u C-c C-c to apply.")))) @@ -3695,7 +3731,7 @@ With prefix ARG, apply the new formulas to the table." "Pretty-print and re-indent Lisp expressions in the Formula Editor." (interactive) (let ((pos (point)) beg end ind) - (beginning-of-line 1) + (forward-line 0) (cond ((looking-at "[ \t]") (goto-char pos) @@ -3721,7 +3757,7 @@ With prefix ARG, apply the new formulas to the table." (untabify (point-min) (point-max)) (goto-char (1+ (point-min))) (while (re-search-forward "^." nil t) - (beginning-of-line 1) + (forward-line 0) (insert ind)) (goto-char (point-max)) (org-delete-backward-char 1))) @@ -3812,6 +3848,7 @@ FACE, when non-nil, for the highlight." (defvar-local org-table-coordinate-overlays nil "Collects the coordinate grid overlays, so that they can be removed.") +(put 'org-table-coordinate-overlays 'permanent-local t) (defun org-table-overlay-coordinates () "Add overlays to the table at point, to show row/column coordinates." @@ -3898,10 +3935,10 @@ When non-nil, return the overlay narrowing the field." ;; Aligning table from the first row will not shrink again the ;; second row, which was not visible initially. ;; - ;; However, fixing it requires to check every row, which may be + ;; However, fixing it requires checking every row, which may be ;; slow on large tables. Moreover, the hindrance of this ;; pathological case is very limited. - (beginning-of-line) + (forward-line 0) (search-forward "|") (let ((separator (if (org-at-table-hline-p) "+" "|")) (column 1) @@ -3987,7 +4024,7 @@ already hidden." start end (make-string (1+ width) ?-) ""))) ((equal contents "") ;no contents to hide (list - (let ((w (org-string-width (buffer-substring start end))) + (let ((w (org-string-width (buffer-substring start end) nil 'org-table)) ;; We really want WIDTH + 2 whitespace, to include blanks ;; around fields. (full (+ 2 width))) @@ -4006,7 +4043,8 @@ already hidden." (let* ((lead (org-with-point-at start (skip-chars-forward " "))) (trail (org-with-point-at end (abs (skip-chars-backward " ")))) (contents-width (org-string-width - (buffer-substring (+ start lead) (- end trail))))) + (buffer-substring (+ start lead) (- end trail)) + nil 'org-table))) (cond ;; Contents are too large to fit in WIDTH character. Limit, if ;; possible, blanks at the beginning of the field to a single @@ -4031,7 +4069,7 @@ already hidden." (let ((mean (+ (ash lower -1) (ash upper -1) (logand lower upper 1)))) - (pcase (org-string-width (buffer-substring begin mean)) + (pcase (org-string-width (buffer-substring begin mean) nil 'org-table) ((pred (= width)) (throw :exit mean)) ((pred (< width)) (setq upper mean)) (_ (setq lower mean))))) @@ -4082,8 +4120,8 @@ already hidden." "Read column selection select as a list of numbers. SELECT is a string containing column ranges, separated by white -space characters, see `org-table-hide-column' for details. MAX -is the maximum column number. +space characters, see `org-table-toggle-column-width' for details. +MAX is the maximum column number. Return value is a sorted list of numbers. Ignore any number outside of the [1;MAX] range." @@ -4259,13 +4297,13 @@ beginning and end position of the current table." "Apply function F to the start of all tables in the buffer." (org-with-point-at 1 (while (re-search-forward org-table-line-regexp nil t) - (let ((table (org-element-lineage (org-element-at-point) '(table) t))) + (let ((table (org-element-lineage (org-element-at-point) 'table t))) (when table (unless quietly (message "Mapping tables: %d%%" (floor (* 100.0 (point)) (buffer-size)))) - (goto-char (org-element-property :post-affiliated table)) - (let ((end (copy-marker (org-element-property :end table)))) + (goto-char (org-element-post-affiliated table)) + (let ((end (copy-marker (org-element-end table)))) (unwind-protect (progn (funcall f) (goto-char end)) (set-marker end nil))))))) @@ -4332,14 +4370,8 @@ extension of the given file name, and finally on the variable (table (org-table-to-lisp))) (unless (fboundp transform) (user-error "No such transformation function %s" transform)) - (let (buf) - (with-current-buffer (find-file-noselect file) - (setq buf (current-buffer)) - (erase-buffer) - (fundamental-mode) - (insert (funcall transform table params) "\n") - (save-buffer)) - (kill-buffer buf)) + (with-temp-file file + (insert (funcall transform table params) "\n")) (message "Export done.")) (user-error "TABLE_EXPORT_FORMAT invalid"))))) @@ -4348,7 +4380,7 @@ extension of the given file name, and finally on the variable "Format FIELD according to column WIDTH and alignment ALIGN. FIELD is a string. WIDTH is a number. ALIGN is either \"c\", \"l\" or\"r\"." - (let* ((spaces (- width (org-string-width field))) + (let* ((spaces (- width (org-string-width field nil 'org-table))) (prefix (pcase align ("l" "") ("r" (make-string spaces ?\s)) @@ -4397,7 +4429,7 @@ FIELD is a string. WIDTH is a number. ALIGN is either \"c\", (non-empty 0)) (dolist (row rows) (let ((cell (or (nth i row) ""))) - (setq max-width (max max-width (org-string-width cell))) + (setq max-width (max max-width (org-string-width cell nil 'org-table))) (cond (fixed-align? nil) ((equal cell "") nil) ((string-match "\\`<\\([lrc]\\)[0-9]*>\\'" cell) @@ -4464,46 +4496,48 @@ Optional argument NEW may specify text to replace the current field content." (cond ((and (not new) org-table-may-need-update)) ; Realignment will happen anyway ((org-at-table-hline-p)) - ((and (not new) - (or (not (eq (marker-buffer org-table-aligned-begin-marker) - (current-buffer))) - (< (point) org-table-aligned-begin-marker) - (>= (point) org-table-aligned-end-marker))) - ;; This is not the same table, force a full re-align. - (setq org-table-may-need-update t)) (t - ;; Realign the current field, based on previous full realign. - (let ((pos (point)) - (col (org-table-current-column))) - (when (> col 0) - (skip-chars-backward "^|") - (if (not (looking-at " *\\(?:\\([^|\n]*?\\) *\\(|\\)\\|\\([^|\n]+?\\) *\\($\\)\\)")) - (setq org-table-may-need-update t) - (let* ((align (nth (1- col) org-table-last-alignment)) - (width (nth (1- col) org-table-last-column-widths)) - (cell (match-string 0)) - (field (match-string 1)) - (properly-closed? (/= (match-beginning 2) (match-end 2))) - (new-cell - (save-match-data - (cond (org-table-may-need-update - (format " %s |" (or new field))) - ((not properly-closed?) - (setq org-table-may-need-update t) - (format " %s |" (or new field))) - ((not new) - (concat (org-table--align-field field width align) - "|")) - ((and width (<= (org-string-width new) width)) - (concat (org-table--align-field new width align) - "|")) - (t - (setq org-table-may-need-update t) - (format " %s |" new)))))) - (unless (equal new-cell cell) - (let (org-table-may-need-update) - (replace-match new-cell t t))) - (goto-char pos)))))))) + (when (or (not (eq (marker-buffer org-table-aligned-begin-marker) + (current-buffer))) + (< (point) org-table-aligned-begin-marker) + (>= (point) org-table-aligned-end-marker)) + ;; This is not the same table, force a full re-align. + (setq org-table-may-need-update t + org-table-last-alignment nil + org-table-last-column-widths nil)) + (when new + ;; Realign the current field, based on previous full realign. + (let ((pos (point)) + (col (org-table-current-column))) + (when (> col 0) + (skip-chars-backward "^|") + (if (not (looking-at " *\\(?:\\([^|\n]*?\\) *\\(|\\)\\|\\([^|\n]+?\\) *\\($\\)\\)")) + (setq org-table-may-need-update t) + (let* ((align (nth (1- col) org-table-last-alignment)) + (width (nth (1- col) org-table-last-column-widths)) + (cell (match-string 0)) + (field (match-string 1)) + (properly-closed? (/= (match-beginning 2) (match-end 2))) + (new-cell + (save-match-data + (cond (org-table-may-need-update + (format " %s |" (or new field))) + ((not properly-closed?) + (setq org-table-may-need-update t) + (format " %s |" (or new field))) + ((not new) + (concat (org-table--align-field field width align) + "|")) + ((and width (<= (org-string-width new nil 'org-table) width)) + (concat (org-table--align-field new width align) + "|")) + (t + (setq org-table-may-need-update t) + (format " %s |" new)))))) + (unless (equal new-cell cell) + (let (org-table-may-need-update) + (replace-match new-cell t t))) + (goto-char pos))))))))) ;;;###autoload (defun org-table-sort-lines @@ -4603,8 +4637,8 @@ function is being called interactively." (predicate (cl-case sorting-type ((?n ?N ?t ?T) #'<) - ((?a ?A) (if with-case #'string-collate-lessp - (lambda (s1 s2) (string-collate-lessp s1 s2 nil t)))) + ((?a ?A) (if with-case #'org-string< + (lambda (s1 s2) (org-string< s1 s2 nil t)))) ((?f ?F) (or compare-func (and interactive? @@ -4892,7 +4926,7 @@ This function sets up the following dynamically scoped variables: (push (cons field v) org-table-local-parameters) (push (list field line col) org-table-named-field-locations)))))))))) - ;; Re-use existing markers when possible. + ;; Reuse existing markers when possible. (if (markerp org-table-current-begin-pos) (move-marker org-table-current-begin-pos (point)) (setq org-table-current-begin-pos (point-marker))) @@ -4977,7 +5011,7 @@ When LOCAL is non-nil, show references for the table at point." (save-excursion (end-of-line) (re-search-backward "^\\S-" nil t) - (beginning-of-line) + (forward-line 0) (when (looking-at "\\(\\$[0-9a-zA-Z]+\\|@[0-9]+\\$[0-9]+\\|[a-zA-Z]+\ \\([0-9]+\\|&\\)\\) *=") (setq dest @@ -4988,8 +5022,8 @@ When LOCAL is non-nil, show references for the table at point." (if (and (markerp pos) (marker-buffer pos)) (if (get-buffer-window (marker-buffer pos)) (select-window (get-buffer-window (marker-buffer pos))) - (org-switch-to-buffer-other-window (get-buffer-window - (marker-buffer pos))))) + (switch-to-buffer-other-window (get-buffer-window + (marker-buffer pos))))) (goto-char pos) (org-table--force-dataline) (let ((table-start @@ -5191,7 +5225,7 @@ When LOCAL is non-nil, show references for the table at point." ;; accident in Org mode. (message "Orgtbl mode is not useful in Org mode, command ignored")) (orgtbl-mode - (and (orgtbl-setup) (defun orgtbl-setup () nil)) ;; FIXME: Yuck!?! + (orgtbl-setup) ;; Make sure we are first in minor-mode-map-alist (let ((c (assq 'orgtbl-mode minor-mode-map-alist))) ;; FIXME: maybe it should use emulation-mode-map-alists? @@ -5246,92 +5280,91 @@ to execute outside of tables." (interactive) (user-error "This key has no function outside tables")) +;; Fill in orgtbl keymap. +(let ((nfunc 0) + (bindings + '(([(meta shift left)] org-table-delete-column) + ([(meta left)] org-table-move-column-left) + ([(meta right)] org-table-move-column-right) + ([(meta shift right)] org-table-insert-column) + ([(meta shift up)] org-table-kill-row) + ([(meta shift down)] org-table-insert-row) + ([(meta up)] org-table-move-row-up) + ([(meta down)] org-table-move-row-down) + ("\C-c\C-w" org-table-cut-region) + ("\C-c\M-w" org-table-copy-region) + ("\C-c\C-y" org-table-paste-rectangle) + ("\C-c\C-w" org-table-wrap-region) + ("\C-c-" org-table-insert-hline) + ("\C-c}" org-table-toggle-coordinate-overlays) + ("\C-c{" org-table-toggle-formula-debugger) + ("\C-m" org-table-next-row) + ([(shift return)] org-table-copy-down) + ("\C-c?" org-table-field-info) + ("\C-c " org-table-blank-field) + ("\C-c+" org-table-sum) + ("\C-c=" org-table-eval-formula) + ("\C-c'" org-table-edit-formulas) + ("\C-c`" org-table-edit-field) + ("\C-c*" org-table-recalculate) + ("\C-c^" org-table-sort-lines) + ("\M-a" org-table-beginning-of-field) + ("\M-e" org-table-end-of-field) + ([(control ?#)] org-table-rotate-recalc-marks))) + elt key fun cmd) + (while (setq elt (pop bindings)) + (setq nfunc (1+ nfunc)) + (setq key (org-key (car elt)) + fun (nth 1 elt) + cmd (orgtbl-make-binding fun nfunc key)) + (org-defkey orgtbl-mode-map key cmd)) + + ;; Special treatment needed for TAB, RET and DEL + (org-defkey orgtbl-mode-map [(return)] + (orgtbl-make-binding 'orgtbl-ret 100 [(return)] "\C-m")) + (org-defkey orgtbl-mode-map "\C-m" + (orgtbl-make-binding 'orgtbl-ret 101 "\C-m" [(return)])) + (org-defkey orgtbl-mode-map [(tab)] + (orgtbl-make-binding 'orgtbl-tab 102 [(tab)] "\C-i")) + (org-defkey orgtbl-mode-map "\C-i" + (orgtbl-make-binding 'orgtbl-tab 103 "\C-i" [(tab)])) + (org-defkey orgtbl-mode-map [(shift tab)] + (orgtbl-make-binding 'org-table-previous-field 104 + [(shift tab)] [(tab)] "\C-i")) + (org-defkey orgtbl-mode-map [backspace] + (orgtbl-make-binding 'org-delete-backward-char 109 + [backspace] (kbd "DEL"))) + + (org-defkey orgtbl-mode-map [S-iso-lefttab] + (orgtbl-make-binding 'org-table-previous-field 107 + [S-iso-lefttab] [backtab] [(shift tab)] + [(tab)] "\C-i")) + + (org-defkey orgtbl-mode-map [backtab] + (orgtbl-make-binding 'org-table-previous-field 108 + [backtab] [S-iso-lefttab] [(shift tab)] + [(tab)] "\C-i")) + + (org-defkey orgtbl-mode-map "\M-\C-m" + (orgtbl-make-binding 'org-table-wrap-region 105 + "\M-\C-m" [(meta return)])) + (org-defkey orgtbl-mode-map [(meta return)] + (orgtbl-make-binding 'org-table-wrap-region 106 + [(meta return)] "\M-\C-m")) + + (org-defkey orgtbl-mode-map "\C-c\C-c" 'orgtbl-ctrl-c-ctrl-c) + (org-defkey orgtbl-mode-map "\C-c|" 'orgtbl-create-or-convert-from-region)) + (defun orgtbl-setup () "Setup orgtbl keymaps." - (let ((nfunc 0) - (bindings - '(([(meta shift left)] org-table-delete-column) - ([(meta left)] org-table-move-column-left) - ([(meta right)] org-table-move-column-right) - ([(meta shift right)] org-table-insert-column) - ([(meta shift up)] org-table-kill-row) - ([(meta shift down)] org-table-insert-row) - ([(meta up)] org-table-move-row-up) - ([(meta down)] org-table-move-row-down) - ("\C-c\C-w" org-table-cut-region) - ("\C-c\M-w" org-table-copy-region) - ("\C-c\C-y" org-table-paste-rectangle) - ("\C-c\C-w" org-table-wrap-region) - ("\C-c-" org-table-insert-hline) - ("\C-c}" org-table-toggle-coordinate-overlays) - ("\C-c{" org-table-toggle-formula-debugger) - ("\C-m" org-table-next-row) - ([(shift return)] org-table-copy-down) - ("\C-c?" org-table-field-info) - ("\C-c " org-table-blank-field) - ("\C-c+" org-table-sum) - ("\C-c=" org-table-eval-formula) - ("\C-c'" org-table-edit-formulas) - ("\C-c`" org-table-edit-field) - ("\C-c*" org-table-recalculate) - ("\C-c^" org-table-sort-lines) - ("\M-a" org-table-beginning-of-field) - ("\M-e" org-table-end-of-field) - ([(control ?#)] org-table-rotate-recalc-marks))) - elt key fun cmd) - (while (setq elt (pop bindings)) - (setq nfunc (1+ nfunc)) - (setq key (org-key (car elt)) - fun (nth 1 elt) - cmd (orgtbl-make-binding fun nfunc key)) - (org-defkey orgtbl-mode-map key cmd)) - - ;; Special treatment needed for TAB, RET and DEL - (org-defkey orgtbl-mode-map [(return)] - (orgtbl-make-binding 'orgtbl-ret 100 [(return)] "\C-m")) - (org-defkey orgtbl-mode-map "\C-m" - (orgtbl-make-binding 'orgtbl-ret 101 "\C-m" [(return)])) - (org-defkey orgtbl-mode-map [(tab)] - (orgtbl-make-binding 'orgtbl-tab 102 [(tab)] "\C-i")) - (org-defkey orgtbl-mode-map "\C-i" - (orgtbl-make-binding 'orgtbl-tab 103 "\C-i" [(tab)])) - (org-defkey orgtbl-mode-map [(shift tab)] - (orgtbl-make-binding 'org-table-previous-field 104 - [(shift tab)] [(tab)] "\C-i")) - (org-defkey orgtbl-mode-map [backspace] - (orgtbl-make-binding 'org-delete-backward-char 109 - [backspace] (kbd "DEL"))) - - (org-defkey orgtbl-mode-map [S-iso-lefttab] - (orgtbl-make-binding 'org-table-previous-field 107 - [S-iso-lefttab] [backtab] [(shift tab)] - [(tab)] "\C-i")) - - (org-defkey orgtbl-mode-map [backtab] - (orgtbl-make-binding 'org-table-previous-field 108 - [backtab] [S-iso-lefttab] [(shift tab)] - [(tab)] "\C-i")) - - (org-defkey orgtbl-mode-map "\M-\C-m" - (orgtbl-make-binding 'org-table-wrap-region 105 - "\M-\C-m" [(meta return)])) - (org-defkey orgtbl-mode-map [(meta return)] - (orgtbl-make-binding 'org-table-wrap-region 106 - [(meta return)] "\M-\C-m")) - - (org-defkey orgtbl-mode-map "\C-c\C-c" 'orgtbl-ctrl-c-ctrl-c) - (org-defkey orgtbl-mode-map "\C-c|" 'orgtbl-create-or-convert-from-region) - - (when orgtbl-optimized - ;; If the user wants maximum table support, we need to hijack - ;; some standard editing functions - (org-remap orgtbl-mode-map - 'self-insert-command 'orgtbl-self-insert-command - 'delete-char 'org-delete-char - 'delete-forward-char 'org-delete-char - 'delete-backward-char 'org-delete-backward-char) - (org-defkey orgtbl-mode-map "|" 'org-force-self-insert)) - t)) + ;; If the user wants maximum table support, we need to hijack + ;; some standard editing functions + (org-remap orgtbl-mode-map + 'self-insert-command (and orgtbl-optimized 'orgtbl-self-insert-command) + 'delete-char (and orgtbl-optimized 'org-delete-char) + 'delete-forward-char (and orgtbl-optimized 'org-delete-char) + 'delete-backward-char (and orgtbl-optimized 'org-delete-backward-char)) + (org-defkey orgtbl-mode-map "|" (and orgtbl-optimized 'org-force-self-insert))) (defun orgtbl-ctrl-c-ctrl-c (arg) "If the cursor is inside a table, realign the table. @@ -5340,7 +5373,7 @@ With prefix arg, also recompute table." (interactive "P") (let ((case-fold-search t) (pos (point)) action) (save-excursion - (beginning-of-line 1) + (forward-line 0) (setq action (cond ((looking-at "[ \t]*#\\+ORGTBL:.*\n[ \t]*|") (match-end 0)) ((looking-at "[ \t]*|") pos) @@ -5357,7 +5390,7 @@ With prefix arg, also recompute table." (run-hooks 'orgtbl-after-send-table-hook))) ((eq action 'recalc) (save-excursion - (beginning-of-line 1) + (forward-line 0) (skip-chars-backward " \r\n\t") (if (org-at-table-p) (org-call-with-arg 'org-table-recalculate t)))) @@ -5390,7 +5423,7 @@ conflicting binding to this key outside `orgtbl-mode'." (org-table-next-row))) (defun orgtbl-self-insert-command (N) - "Like `self-insert-command', use overwrite-mode for whitespace in tables. + "Like `self-insert-command', use `overwrite-mode' for whitespace in tables. If the cursor is in a table looking at whitespace, the whitespace is overwritten, and the table is not marked as requiring realignment." (interactive "p") @@ -5443,15 +5476,17 @@ a radio table." (save-excursion (goto-char (org-table-begin)) (let (rtn) - (beginning-of-line 0) - (while (looking-at "[ \t]*#\\+ORGTBL[: \t][ \t]*SEND[ \t]+\\([^ \t\r\n]+\\)[ \t]+\\([^ \t\r\n]+\\)\\([ \t]+.*\\)?") - (let ((name (org-no-properties (match-string 1))) - (transform (intern (match-string 2))) - (params (if (match-end 3) - (read (concat "(" (match-string 3) ")"))))) - (push (list :name name :transform transform :params params) - rtn) - (beginning-of-line 0))) + (forward-line -1) + (catch :bob + (while (looking-at "[ \t]*#\\+ORGTBL[: \t][ \t]*SEND[ \t]+\\([^ \t\r\n]+\\)[ \t]+\\([^ \t\r\n]+\\)\\([ \t]+.*\\)?") + (let ((name (org-no-properties (match-string 1))) + (transform (intern (match-string 2))) + (params (if (match-end 3) + (read (concat "(" (match-string 3) ")"))))) + (push (list :name name :transform transform :params params) + rtn) + (when (bobp) (throw :bob nil)) + (forward-line -1)))) rtn))) (defun orgtbl-send-replace-tbl (name text) @@ -5467,7 +5502,7 @@ a radio table." (let ((beg (line-beginning-position 2))) (unless (re-search-forward end-re nil t) (user-error "Cannot find end of receiver location at %d" beg)) - (beginning-of-line) + (forward-line 0) (delete-region beg (point)) (insert text "\n"))) (unless location-flag @@ -5482,25 +5517,38 @@ for a horizontal separator line, or a list of field values as strings. The table is taken from the parameter TXT, or from the buffer at point." (if txt (with-temp-buffer + (buffer-disable-undo) (insert txt) (goto-char (point-min)) (org-table-to-lisp)) (save-excursion (goto-char (org-table-begin)) - (let ((table nil)) - (while (re-search-forward "\\=[ \t]*|" nil t) - (let ((row nil)) - (if (looking-at "-") - (push 'hline table) - (while (not (progn (skip-chars-forward " \t") (eolp))) - (push (buffer-substring - (point) - (progn (re-search-forward "[ \t]*\\(|\\|$\\)") - (match-beginning 0))) - row)) - (push (nreverse row) table))) + (let (table) + (while (progn (skip-chars-forward " \t") + (eq (following-char) ?|)) + (forward-char) + (push + (if (eq (following-char) ?-) + 'hline + (let (row) + (while (progn + (skip-chars-forward " \t") + (not (eolp))) + (let ((q (point))) + (skip-chars-forward "^|\n") + (goto-char + (prog1 + (let ((p (point))) + (unless (eolp) (setq p (1+ p))) + p) + (skip-chars-backward " \t" q) + ;; Preserve text properties. They are used when + ;; calculating cell width. + (push (buffer-substring q (point)) row))))) + (nreverse row))) + table) (forward-line)) - (nreverse table))))) + (nreverse table))))) (defun org-table-collapse-header (table &optional separator max-header-lines) "Collapse the lines before `hline' into a single header. @@ -5572,22 +5620,22 @@ First element has index 0, or I0 if given." (let* ((case-fold-search t) (re1 (concat "^" (regexp-quote comment-start) orgtbl-line-start-regexp)) (re2 (concat "^" orgtbl-line-start-regexp)) - (commented (save-excursion (beginning-of-line 1) + (commented (save-excursion (forward-line 0) (cond ((looking-at re1) t) ((looking-at re2) nil) (t (user-error "Not at an org table"))))) (re (if commented re1 re2)) beg end) (save-excursion - (beginning-of-line 1) + (forward-line 0) (while (and (not (eq (point) (point-min))) (looking-at re)) - (beginning-of-line 0)) - (unless (eq (point) (point-min)) (beginning-of-line 2)) + (forward-line -1)) + (unless (eq (point) (point-min)) (forward-line 1)) (setq beg (point)) (while (and (not (eq (point) (point-max))) (looking-at re)) - (beginning-of-line 2)) + (forward-line 1)) (setq end (point))) (comment-region beg end (if commented '(4) nil)))) @@ -5621,7 +5669,7 @@ Valid parameters are: :backend, :raw - Export back-end used as a basis to transcode elements of the + Export backend used as a basis to transcode elements of the table, when no specific parameter applies to it. It is also used to translate cells contents. You can prevent this by setting :raw property to a non-nil value. @@ -5713,7 +5761,7 @@ This may be either a string or a function of two arguments: (require 'ox) (let* ((backend (plist-get params :backend)) (custom-backend - ;; Build a custom back-end according to PARAMS. Before + ;; Build a custom backend according to PARAMS. Before ;; defining a translator, check if there is anything to do. ;; When there isn't, let BACKEND handle the element. (org-export-create-backend @@ -5723,7 +5771,7 @@ This may be either a string or a function of two arguments: (table-row . ,(org-table--to-generic-row params)) (table-cell . ,(org-table--to-generic-cell params)) ;; Macros are not going to be expanded. However, no - ;; regular back-end has a transcoder for them. We + ;; regular backend has a transcoder for them. We ;; provide one so they are not ignored, but displayed ;; as-is instead. (macro . (lambda (m c i) (org-element-macro-interpreter m nil)))))) @@ -5741,7 +5789,7 @@ This may be either a string or a function of two arguments: (princ "| ") (dolist (c e) (princ c) (princ " |")) (princ "\n"))))) (org-element-cache-reset) - ;; Add back-end specific filters, but not user-defined ones. In + ;; Add backend specific filters, but not user-defined ones. In ;; particular, make sure to call parse-tree filters on the ;; table. (setq info @@ -5767,7 +5815,7 @@ This may be either a string or a function of two arguments: (org-element-map data 'table-row (lambda (row) (if (>= n skip) t - (org-element-extract-element row) + (org-element-extract row) (cl-incf n) nil)) nil t)))) @@ -5784,7 +5832,7 @@ This may be either a string or a function of two arguments: (dolist (cell (nthcdr (if specialp 1 0) (org-element-contents row))) (when (memq c skipcols) - (org-element-extract-element cell)) + (org-element-extract cell)) (cl-incf c)))))))))) ;; Since we are going to export using a low-level mechanism, ;; ignore special column and special rows manually. @@ -5792,7 +5840,7 @@ This may be either a string or a function of two arguments: ignore) (org-element-map data (if special? '(table-cell table-row) 'table-row) (lambda (datum) - (when (if (eq (org-element-type datum) 'table-row) + (when (if (org-element-type-p datum 'table-row) (org-export-table-row-is-special-p datum nil) (org-export-first-sibling-p datum nil)) (push datum ignore)))) @@ -5800,7 +5848,7 @@ This may be either a string or a function of two arguments: ;; We use a low-level mechanism to export DATA so as to skip all ;; usual pre-processing and post-processing, i.e., hooks, Babel ;; code evaluation, include keywords and macro expansion. Only - ;; back-end specific filters are retained. + ;; backend specific filters are retained. (let ((output (org-export-data-with-backend data custom-backend info))) ;; Remove final newline. (if (org-string-nw-p output) (substring-no-properties output 0 -1) "")))) @@ -5960,7 +6008,7 @@ information." (let ((headerp ,(and (or hfmt hsep) '(org-export-table-row-in-header-p - (org-export-get-parent-element cell) info))) + (org-element-parent-element cell) info))) (column ;; Call costly `org-export-table-cell-address' only if ;; absolutely necessary, i.e., if one @@ -6108,7 +6156,7 @@ supported. It is also possible to use the following one: ;;;###autoload (defun orgtbl-to-orgtbl (table params) - "Convert the `orgtbl-mode' TABLE into another orgtbl-mode table. + "Convert the `orgtbl-mode' TABLE into another `orgtbl-mode' table. TABLE is a list, each entry either the symbol `hline' for a horizontal separator line, or a list of fields for that line. @@ -6132,9 +6180,13 @@ supported." (with-temp-buffer (insert (orgtbl-to-orgtbl table params)) (org-table-align) - (replace-regexp-in-string - "-|" "-+" - (replace-regexp-in-string "|-" "+-" (buffer-substring 1 (buffer-size)))))) + (goto-char (point-min)) + (while (search-forward "-|" nil t) + (replace-match "-+")) + (goto-char (point-min)) + (while (search-forward "|-" nil t) + (replace-match "+-")) + (buffer-string))) (defun orgtbl-to-unicode (table params) "Convert the `orgtbl-mode' TABLE into a table with unicode characters. diff --git a/elpa/org-9.6.7/org-tempo.el b/elpa/org-9.7.17/org-tempo.el similarity index 95% rename from elpa/org-9.6.7/org-tempo.el rename to elpa/org-9.7.17/org-tempo.el index 81ec8fdc..c811f61c 100644 --- a/elpa/org-9.6.7/org-tempo.el +++ b/elpa/org-9.7.17/org-tempo.el @@ -1,9 +1,9 @@ ;;; org-tempo.el --- Template expansion for Org structures -*- lexical-binding: t; -*- -;; Copyright (C) 2017-2023 Free Software Foundation, Inc. +;; Copyright (C) 2017-2024 Free Software Foundation, Inc. ;; ;; Author: Rasmus Pank Roulund -;; Keywords: outlines, hypermedia, calendar, wp +;; Keywords: outlines, hypermedia, calendar, text ;; URL: https://orgmode.org ;; ;; This file is part of GNU Emacs. @@ -24,7 +24,7 @@ ;;; Commentary: ;; ;; Org Tempo reimplements completions of structure template before -;; point like `org-try-structure-completion' in Org v9.1 and earlier. +;; point in Org v9.1 and earlier. ;; For example, strings like " -;; Keywords: outlines, hypermedia, calendar, wp +;; Keywords: outlines, hypermedia, calendar, text ;; URL: https://orgmode.org ;; ;; This file is part of GNU Emacs. @@ -44,7 +44,7 @@ (declare-function org-agenda-error "org-agenda" ()) (defvar org-timer-start-time nil - "t=0 for the running timer.") + "Start time for the running timer.") (defvar org-timer-pause-time nil "Time when the timer was paused.") @@ -203,15 +203,16 @@ With prefix arg STOP, stop it entirely." "Insert a H:MM:SS string from the timer into the buffer. The first time this command is used, the timer is started. -When used with a `\\[universal-argument]' prefix, force restarting the timer. +When used with a `\\[universal-argument]' prefix RESTART, force +restarting the timer. -When used with a `\\[universal-argument] \\[universal-argument]' \ -prefix, change all the timer strings -in the region by a fixed amount. This can be used to re-calibrate -a timer that was not started at the correct moment. +When used with a `\\[universal-argument] \\[universal-argument]' prefix +RESTART, change all the timer strings in the region by a fixed amount. +This can be used to re-calibrate a timer that was not started at the +correct moment. -If NO-INSERT is non-nil, return the string instead of inserting -it in the buffer." +If NO-INSERT is non-nil, return the string instead of inserting it in +the buffer." (interactive "P") (if (equal restart '(16)) (org-timer-start restart) @@ -231,7 +232,7 @@ it in the buffer." ;;;###autoload (defun org-timer-change-times-in-region (beg end delta) - "Change all h:mm:ss time in region by a DELTA." + "Change all h:mm:ss time in region BEG..END by a DELTA." (interactive "r\nsEnter time difference like \"-1:08:26\". Default is first time to zero: ") (let ((re "[-+]?[0-9]+:[0-9]\\{2\\}:[0-9]\\{2\\}") p) @@ -257,7 +258,8 @@ it in the buffer." ;;;###autoload (defun org-timer-item (&optional arg) - "Insert a description-type item with the current timer value." + "Insert a description-type item with the current timer value. +Prefix argument ARG is passed to `org-timer'." (interactive "P") (let ((itemp (org-in-item-p)) (pos (point))) (cond @@ -275,14 +277,14 @@ it in the buffer." (itemp (goto-char pos) (error "This is not a timer list")) ;; Else, start a new list. (t - (beginning-of-line) + (forward-line 0) (org-indent-line) (insert "- ") (org-timer (when arg '(4))) (insert ":: "))))) (defun org-timer-fix-incomplete (hms) - "If hms is a H:MM:SS string with missing hour or hour and minute, fix it." + "If HMS is a H:MM:SS string with missing hour or hour and minute, fix it." (if (string-match "\\(?:\\([0-9]+:\\)?\\([0-9]+:\\)\\)?\\([0-9]+\\)" hms) (replace-match (format "%d:%02d:%02d" @@ -293,7 +295,7 @@ it in the buffer." (error "Cannot parse HMS string \"%s\"" hms))) (defun org-timer-hms-to-secs (hms) - "Convert h:mm:ss string to an integer time. + "Convert h:mm:ss (HMS) string to an integer time. If the string starts with a minus sign, the integer will be negative." (if (not (string-match "\\([-+]?[0-9]+\\):\\([0-9]\\{2\\}\\):\\([0-9]\\{2\\}\\)" @@ -400,15 +402,15 @@ If `org-timer-default-timer' is not \"0\", suggest this value as the default duration for the timer. If a timer is already set, prompt the user if she wants to replace it. -Called with a numeric prefix argument, use this numeric value as +Called with a numeric prefix argument OPT, use this numeric value as the duration of the timer in minutes. -Called with a \\[universal-argument] prefix arguments, use `org-timer-default-timer' -without prompting the user for a duration. +Called with a \\[universal-argument] prefix argument OPT, use +`org-timer-default-timer' without prompting the user for a duration. -With two \\[universal-argument] prefix arguments, use `org-timer-default-timer' -without prompting the user for a duration and automatically -replace any running timer. +With two \\[universal-argument] prefix arguments OPT, use +`org-timer-default-timer' without prompting the user for a duration +and automatically replace any running timer. By default, the timer duration will be set to the number of minutes in the Effort property, if any. You can ignore this by @@ -418,13 +420,18 @@ using three \\[universal-argument] prefix arguments." (not org-timer-countdown-timer)) (user-error "Relative timer is running. Stop first")) (let* ((default-timer - ;; `org-timer-default-timer' used to be a number, don't choke: - (if (numberp org-timer-default-timer) - (number-to-string org-timer-default-timer) - org-timer-default-timer)) - (effort-minutes (let ((effort (org-entry-get nil org-effort-property))) - (when (org-string-nw-p effort) - (floor (org-duration-to-minutes effort))))) + ;; `org-timer-default-timer' used to be a number, don't choke: + (if (numberp org-timer-default-timer) + (number-to-string org-timer-default-timer) + org-timer-default-timer)) + (effort-minutes + (cond ((derived-mode-p 'org-agenda-mode) + (org-get-at-bol 'effort-minutes)) + ((derived-mode-p 'org-mode) + (let ((effort (org-entry-get nil org-effort-property))) + (when (org-string-nw-p effort) + (floor (org-duration-to-minutes effort))))) + (t nil))) (minutes (or (and (numberp opt) (number-to-string opt)) (and (not (equal opt '(64))) effort-minutes @@ -441,7 +448,7 @@ using three \\[universal-argument] prefix arguments." (let ((secs (org-timer-hms-to-secs (org-timer-fix-incomplete minutes)))) (if (and org-timer-countdown-timer (not (or (equal opt '(16)) - (y-or-n-p "Replace current timer? ")))) + (y-or-n-p "Replace current timer? ")))) (message "No timer set") (when (timerp org-timer-countdown-timer) (cancel-timer org-timer-countdown-timer)) diff --git a/elpa/org-9.6.7/org-version.el b/elpa/org-9.7.17/org-version.el similarity index 87% rename from elpa/org-9.6.7/org-version.el rename to elpa/org-9.7.17/org-version.el index e089fbfa..378cb6f7 100644 --- a/elpa/org-9.6.7/org-version.el +++ b/elpa/org-9.7.17/org-version.el @@ -5,13 +5,13 @@ (defun org-release () "The release version of Org. Inserted by installing Org mode or when a release is made." - (let ((org-release "9.6.7")) + (let ((org-release "9.7.17")) org-release)) ;;;###autoload (defun org-git-version () "The Git version of Org mode. Inserted by installing Org or when a release is made." - (let ((org-git-version "")) + (let ((org-git-version "9.7.17-3ae179")) org-git-version)) (provide 'org-version) diff --git a/elpa/org-9.6.7/org.el b/elpa/org-9.7.17/org.el similarity index 83% rename from elpa/org-9.6.7/org.el rename to elpa/org-9.7.17/org.el index 2cf08e85..1085a8c7 100644 --- a/elpa/org-9.6.7/org.el +++ b/elpa/org-9.7.17/org.el @@ -1,15 +1,15 @@ ;;; org.el --- Outline-based notes management and organizer -*- lexical-binding: t; -*- ;; Carstens outline-mode for keeping track of everything. -;; Copyright (C) 2004-2023 Free Software Foundation, Inc. +;; Copyright (C) 2004-2024 Free Software Foundation, Inc. ;; ;; Author: Carsten Dominik ;; Maintainer: Bastien Guerry -;; Keywords: outlines, hypermedia, calendar, wp +;; Keywords: outlines, hypermedia, calendar, text ;; URL: https://orgmode.org ;; Package-Requires: ((emacs "26.1")) -;; Version: 9.6.7 +;; Version: 9.7.17 ;; This file is part of GNU Emacs. ;; @@ -81,6 +81,7 @@ (require 'calendar) (require 'find-func) (require 'format-spec) +(require 'thingatpt) (condition-case nil (load (concat (file-name-directory load-file-name) @@ -101,10 +102,6 @@ (require 'org-fold) (require 'org-cycle) -(defvaralias 'org-hide-block-startup 'org-cycle-hide-block-startup) -(defvaralias 'org-hide-drawer-startup 'org-cycle-hide-drawer-startup) -(defvaralias 'org-pre-cycle-hook 'org-cycle-pre-hook) -(defvaralias 'org-tab-first-hook 'org-cycle-tab-first-hook) (defalias 'org-global-cycle #'org-cycle-global) (defalias 'org-overview #'org-cycle-overview) (defalias 'org-content #'org-cycle-content) @@ -171,27 +168,38 @@ Stars are put in group 1 and the trimmed body in group 2.") (declare-function org-element-cache-refresh "org-element" (pos)) (declare-function org-element-cache-reset "org-element" (&optional all no-persistence)) (declare-function org-element-cache-map "org-element" (func &rest keys)) -(declare-function org-element-contents "org-element" (element)) +(declare-function org-element-contents "org-element-ast" (node)) (declare-function org-element-context "org-element" (&optional element)) -(declare-function org-element-copy "org-element" (datum)) -(declare-function org-element-create "org-element" (type &optional props &rest children)) -(declare-function org-element-extract-element "org-element" (element)) -(declare-function org-element-insert-before "org-element" (element location)) +(declare-function org-element-copy "org-element-ast" (datum)) +(declare-function org-element-create "org-element-ast" (type &optional props &rest children)) +(declare-function org-element-extract "org-element-ast" (node)) +(declare-function org-element-insert-before "org-element-ast" (node location)) (declare-function org-element-interpret-data "org-element" (data)) (declare-function org-element-keyword-parser "org-element" (limit affiliated)) -(declare-function org-element-lineage "org-element" (blob &optional types with-self)) +(declare-function org-element-lineage "org-element-ast" (blob &optional types with-self)) +(declare-function org-element-property-inherited "org-element-ast" + (property node &optional with-self accumulate literal-nil include-nil)) +(declare-function org-element-lineage-map "org-element-ast" + (datum fun &optional types with-self first-match)) (declare-function org-element-link-parser "org-element" ()) (declare-function org-element-map "org-element" (data types fun &optional info first-match no-recursion with-affiliated)) (declare-function org-element-nested-p "org-element" (elem-a elem-b)) -(declare-function org-element-parse-buffer "org-element" (&optional granularity visible-only)) +(declare-function org-element-parse-buffer "org-element" (&optional granularity visible-only keep-deferred)) (declare-function org-element-parse-secondary-string "org-element" (string restriction &optional parent)) -(declare-function org-element-property "org-element" (property element)) -(declare-function org-element-put-property "org-element" (element property value)) +(declare-function org-element-property "org-element-ast" (property node)) +(declare-function org-element-begin "org-element" (node)) +(declare-function org-element-end "org-element" (node)) +(declare-function org-element-contents-begin "org-element" (node)) +(declare-function org-element-contents-end "org-element" (node)) +(declare-function org-element-post-affiliated "org-element" (node)) +(declare-function org-element-post-blank "org-element" (node)) +(declare-function org-element-parent "org-element-ast" (node)) +(declare-function org-element-put-property "org-element-ast" (node property value)) (declare-function org-element-restriction "org-element" (element)) (declare-function org-element-swap-A-B "org-element" (elem-a elem-b)) (declare-function org-element-timestamp-parser "org-element" ()) -(declare-function org-element-type "org-element" (element)) -(declare-function org-element--cache-active-p "org-element" ()) +(declare-function org-element-type "org-element-ast" (node &optional anonymous)) +(declare-function org-element-type-p "org-element-ast" (node types)) (declare-function org-export-dispatch "ox" (&optional arg)) (declare-function org-export-get-backend "ox" (name)) (declare-function org-export-get-environment "ox" (&optional backend subtreep ext-plist)) @@ -206,7 +214,7 @@ Stars are put in group 1 and the trimmed body in group 2.") (declare-function org-latex-make-preamble "ox-latex" (info &optional template snippet?)) (declare-function org-num-mode "org-num" (&optional arg)) (declare-function org-plot/gnuplot "org-plot" (&optional params)) -(declare-function org-persist-load "org-persist" (container &optional associated hash-must-match)) +(declare-function org-persist-load "org-persist") (declare-function org-tags-view "org-agenda" (&optional todo-only match)) (declare-function org-timer "org-timer" (&optional restart no-insert)) (declare-function org-timer-item "org-timer" (&optional arg)) @@ -405,7 +413,7 @@ FULL is given." ;;;; Block (defconst org-block-regexp - "^[ \t]*#\\+begin_?\\([^ \n]+\\)\\(\\([^\n]+\\)\\)?\n\\([^\000]+?\\)#\\+end_?\\1[ \t]*$" + "^[ \t]*#\\+begin_?\\([^ \n]+\\)\\(\\([^\n]+\\)\\)?\n\\(\\(?:.\\|\n\\)+?\\)#\\+end_?\\1[ \t]*$" "Regular expression for hiding blocks.") (defconst org-dblock-start-re @@ -471,7 +479,8 @@ The time stamps may be either active or inactive.") "Regular expression for specifying repeated events. After a match, group 1 contains the repeat expression.") -(defconst org-time-stamp-formats '("%Y-%m-%d %a" . "%Y-%m-%d %a %H:%M") +(defvaralias 'org-time-stamp-formats 'org-timestamp-formats) +(defconst org-timestamp-formats '("%Y-%m-%d %a" . "%Y-%m-%d %a %H:%M") "Formats for `format-time-string' which are used for time stamps. The value is a cons cell containing two strings. The `car' and `cdr' @@ -582,7 +591,11 @@ Matched keyword is in group 1.") ;;;; Drawer -(defconst org-drawer-regexp "^[ \t]*:\\(\\(?:\\w\\|[-_]\\)+\\):[ \t]*$" +(defconst org-drawer-regexp + ;; FIXME: Duplicate of `org-element-drawer-re'. + (rx line-start (0+ (any ?\s ?\t)) + ":" (group (1+ (any ?- ?_ word))) ":" + (0+ (any ?\s ?\t)) line-end) "Matches first or last line of a hidden block. Group 1 contains drawer's name or \"END\".") @@ -611,7 +624,7 @@ Group 1 contains drawer's name or \"END\".") "Matches an entire property drawer.") (defconst org-clock-drawer-re - (concat "\\(" org-clock-drawer-start-re "\\)[^\000]*?\\(" + (concat "\\(" org-clock-drawer-start-re "\\)\\(?:.\\|\n\\)*?\\(" org-clock-drawer-end-re "\\)\n?") "Matches an entire clock drawer.") @@ -661,14 +674,13 @@ An entry can be toggled between COMMENT and normal with ;;;; LaTeX Environments and Fragments (defconst org-latex-regexps - '(("begin" "^[ \t]*\\(\\\\begin{\\([a-zA-Z0-9\\*]+\\)[^\000]+?\\\\end{\\2}\\)" 1 t) + '(("begin" "^[ \t]*\\(\\\\begin{\\([a-zA-Z0-9\\*]+\\)\\(?:.\\|\n\\)+?\\\\end{\\2}\\)" 1 t) ;; ("$" "\\([ \t(]\\|^\\)\\(\\(\\([$]\\)\\([^ \t\n,.$].*?\\(\n.*?\\)\\{0,5\\}[^ \t\n,.$]\\)\\4\\)\\)\\([ \t.,?;:'\")]\\|$\\)" 2 nil) - ;; \000 in the following regex is needed for org-inside-LaTeX-fragment-p - ("$1" "\\([^$]\\|^\\)\\(\\$[^ \t\r\n,;.$]\\$\\)\\(\\s.\\|\\s-\\|\\s(\\|\\s)\\|\\s\"\\|\000\\|'\\|$\\)" 2 nil) - ("$" "\\([^$]\\|^\\)\\(\\(\\$\\([^ \t\n,;.$][^$\n\r]*?\\(\n[^$\n\r]*?\\)\\{0,2\\}[^ \t\n,.$]\\)\\$\\)\\)\\(\\s.\\|\\s-\\|\\s(\\|\\s)\\|\\s\"\\|\000\\|'\\|$\\)" 2 nil) - ("\\(" "\\\\([^\000]*?\\\\)" 0 nil) - ("\\[" "\\\\\\[[^\000]*?\\\\\\]" 0 nil) - ("$$" "\\$\\$[^\000]*?\\$\\$" 0 nil)) + ("$1" "\\([^$]\\|^\\)\\(\\$[^ \t\r\n,;.$]\\$\\)\\(\\s.\\|\\s-\\|\\s(\\|\\s)\\|\\s\"\\|'\\|$\\)" 2 nil) + ("$" "\\([^$]\\|^\\)\\(\\(\\$\\([^ \t\n,;.$][^$\n\r]*?\\(\n[^$\n\r]*?\\)\\{0,2\\}[^ \t\n,.$]\\)\\$\\)\\)\\(\\s.\\|\\s-\\|\\s(\\|\\s)\\|\\s\"\\|'\\|$\\)" 2 nil) + ("\\(" "\\\\(\\(?:.\\|\n\\)*?\\\\)" 0 nil) + ("\\[" "\\\\\\[\\(?:.\\|\n\\)*?\\\\\\]" 0 nil) + ("$$" "\\$\\$\\(?:.\\|\n\\)*?\\$\\$" 0 nil)) "Regular expressions for matching embedded LaTeX.") ;;;; Node Property @@ -716,7 +728,7 @@ defined in org-duration.el.") "Load all extensions listed in `org-modules'." (when (or force (not org-modules-loaded)) (dolist (ext org-modules) - (condition-case nil (require ext) + (condition-case-unless-debug nil (require ext) (error (message "Problems while trying to load feature `%s'" ext)))) (setq org-modules-loaded t))) @@ -812,7 +824,7 @@ For export specific modules, see also `org-export-backends'." (declare-function org-export-derived-backend-p "ox" (backend &rest backends)) (declare-function org-export-backend-name "ox" (backend) t) (defcustom org-export-backends '(ascii html icalendar latex odt) - "List of export back-ends that should be always available. + "List of export backends that should be always available. If a description starts with , the file is not part of Emacs and Org mode, so loading it will require that you have properly installed org-contrib @@ -844,12 +856,12 @@ value of the variable, after updating it: (dolist (backend val) (cond ((not (load (format \"ox-%s\" backend) t t)) - (message \"Problems while trying to load export back-end \\=`%s\\='\" + (message \"Problems while trying to load export backend \\=`%s\\='\" backend)) ((not (memq backend new-list)) (push backend new-list)))) (set-default \\='org-export-backends new-list))) -Adding a back-end to this list will also pull the back-end it +Adding a backend to this list will also pull the backend it depends on, if any." :group 'org :group 'org-export @@ -858,9 +870,9 @@ depends on, if any." :initialize 'custom-initialize-set :set (lambda (var val) (if (not (featurep 'ox)) (set-default-toplevel-value var val) - ;; Any back-end not required anymore (not present in VAL and not - ;; a parent of any back-end in the new value) is removed from the - ;; list of registered back-ends. + ;; Any backend not required anymore (not present in VAL and not + ;; a parent of any backend in the new value) is removed from the + ;; list of registered backends. (setq org-export-registered-backends (cl-remove-if-not (lambda (backend) @@ -871,14 +883,14 @@ depends on, if any." (and (org-export-derived-backend-p b name) (throw 'parentp t))))))) org-export-registered-backends)) - ;; Now build NEW-LIST of both new back-ends and required + ;; Now build NEW-LIST of both new backends and required ;; parents. (let ((new-list (mapcar #'org-export-backend-name org-export-registered-backends))) (dolist (backend val) (cond ((not (load (format "ox-%s" backend) t t)) - (message "Problems while trying to load export back-end `%s'" + (message "Problems while trying to load export backend `%s'" backend)) ((not (memq backend new-list)) (push backend new-list)))) ;; Set VAR to that list with fixed dependencies. @@ -905,8 +917,8 @@ depends on, if any." (eval-after-load 'ox '(dolist (backend org-export-backends) - (condition-case nil (require (intern (format "ox-%s" backend))) - (error (message "Problems while trying to load export back-end `%s'" + (condition-case-unless-debug nil (require (intern (format "ox-%s" backend))) + (error (message "Problems while trying to load export backend `%s'" backend))))) (defcustom org-support-shift-select nil @@ -990,7 +1002,30 @@ equivalent option for agenda views." :group 'org) (defcustom org-startup-folded 'showeverything - "Non-nil means entering Org mode will switch to OVERVIEW. + "Initial folding state of headings when entering Org mode. + +Allowed values are: + +symbol `nofold' + Do not fold headings. + +symbol `fold' + Fold everything, leaving only top-level headings visible. + +symbol `content' + Leave all the headings and sub-headings visible, but hide their + text. This is an equivalent of table of contents. + +symbol `show2levels', `show3levels', `show4levels', `show5levels' + Show headings up to Nth level. + +symbol `showeverything' (default) + Start Org mode in fully unfolded state. Unlike all other allowed + values, this value prevents drawers, blocks, and archived subtrees + from being folded even when `org-cycle-hide-block-startup', + `org-cycle-open-archived-trees', or `org-cycle-hide-drawer-startup' + are non-nil. Per-subtree visibility settings (see manual node + `(org)Initial visibility)') are also ignored. This can also be configured on a per-file basis by adding one of the following lines anywhere in the buffer: @@ -1007,8 +1042,8 @@ time." :group 'org-startup :package-version '(Org . "9.4") :type '(choice - (const :tag "nofold: show all" nil) - (const :tag "fold: overview" t) + (const :tag "nofold: show all" nofold) + (const :tag "fold: overview" fold) (const :tag "fold: show two levels" show2levels) (const :tag "fold: show three levels" show3levels) (const :tag "fold: show four levels" show4evels) @@ -1021,7 +1056,7 @@ time." This is useful since some lines containing links can be very long and uninteresting. Also tables look terrible when wrapped. -The variable `org-startup-truncated' allows to configure +The variable `org-startup-truncated' enables you to configure truncation for Org mode different to the other modes that use the variable `truncate-lines' and as a shortcut instead of putting the variable `truncate-lines' into the `org-mode-hook'. If one @@ -1073,19 +1108,26 @@ will be parsed as single sub- or superscripts: 10^-12 or 10^-tau a leading sign with digits or a word x^2-y^3 will be read as x^2 - y^3, because items are terminated by almost any nonword/nondigit char. - x_{i^2} or x^(2-i) braces or parenthesis do grouping. + x^(2 - i) expression inside round braces, including the + braces is read as a sub/superscript. + x_{i^2} curly braces do grouping; braces are not + considered a part of the sub/superscript. Still, ambiguity is possible. So when in doubt, use {} to enclose the sub/superscript. If you set this variable to the symbol `{}', -the braces are *required* in order to trigger interpretations as +the curly braces are *required* in order to trigger interpretations as sub/superscript. This can be helpful in documents that need \"_\" -frequently in plain text." +frequently in plain text. + +Setting this variable does not change Org mode markup. Org mode will +still parse the matching text as sub/superscript internally. It is +only the visual appearance that will be changed." :group 'org-startup :version "24.4" :package-version '(Org . "8.0") :type '(choice (const :tag "Always interpret" t) - (const :tag "Only with braces" {}) + (const :tag "Only with curly braces" {}) (const :tag "Never interpret" nil))) (defcustom org-startup-with-beamer-mode nil @@ -1140,6 +1182,26 @@ the following lines anywhere in the buffer: :package-version '(Org . "8.0") :type 'boolean) +(unless (boundp 'untrusted-content) + (defvar untrusted-content nil)) +(defvar untrusted-content) ; defined in files.el since Emacs 29.3 +(defvar org--latex-preview-when-risky nil + "If non-nil, enable LaTeX preview in Org buffers from unsafe source. + +Some specially designed LaTeX code may generate huge pdf or log files +that may exhaust disk space. + +This variable controls how to handle LaTeX preview when rendering LaTeX +fragments that originate from incoming email messages. It has no effect +when Org mode is unable to determine the origin of the Org buffer. + +An Org buffer is considered to be from unsafe source when the +variable `untrusted-content' has a non-nil value in the buffer. + +If this variable is non-nil, LaTeX previews are rendered unconditionally. + +This variable may be renamed or changed in the future.") + (defcustom org-insert-mode-line-in-empty-file nil "Non-nil means insert the first line setting Org mode in empty files. When the function `org-mode' is called interactively in an empty file, this @@ -1209,7 +1271,7 @@ are matched against file names, and values." :group 'org) (defcustom org-closed-keep-when-no-todo nil - "Remove CLOSED: time-stamp when switching back to a non-todo state?" + "Remove CLOSED: timestamp when switching back to a non-todo state?" :group 'org-todo :group 'org-keywords :version "24.4" @@ -1230,7 +1292,7 @@ This applies to indirect buffers created with the commands Valid values are: current-window Display in the current window other-window Just display in another window. -dedicated-frame Create one new frame, and re-use it each time. +dedicated-frame Create one new frame, and reuse it each time. new-frame Make a new frame each time. Note that in this case previously-made indirect buffers are kept, and you need to kill these buffers yourself." @@ -1321,14 +1383,15 @@ Possible values for the file identifier are: to open [[file:document.pdf::5]] with evince at page 5. Likely, you will need more entries: without page - number; with search pattern; with cross-reference - anchor; some combination of options. Consider simple - pattern here and a Lisp function to determine command - line arguments instead. Passing argument list to - `call-process' or `make-process' directly allows to - avoid treating some character in peculiar file names - as shell specialls causing executing part of file - name as a subcommand. + number; with search pattern; with + cross-reference anchor; some combination of + options. Consider simple pattern here and a + Lisp function to determine command line + arguments instead. Passing an argument list to + `call-process' or `make-process' directly avoids + treating some character in peculiar file names + as shell specials that prompt parts of said file + names to be executed as subcommands. `directory' Matches a directory `remote' Matches a remote file, accessible through tramp. @@ -1395,7 +1458,7 @@ This affects keywords like #+setupfile and #+include on export, Emacs sessions. This recognizes four possible values: -- t, remote resources should always be downloaded. +- t (dangerous), remote resources should always be downloaded. - prompt, you will be prompted to download resources not considered safe. - safe, only resources considered safe will be downloaded. - nil, never download remote resources. @@ -1404,7 +1467,7 @@ A resource is considered safe if it matches one of the patterns in `org-safe-remote-resources'." :group 'org :package-version '(Org . "9.6") - :type '(choice (const :tag "Always download remote resources" t) + :type '(choice (const :tag "Always download remote resources (dangerous)" t) (const :tag "Prompt before downloading an unsafe resource" prompt) (const :tag "Only download resources considered safe" safe) (const :tag "Never download any resources" nil))) @@ -1929,6 +1992,13 @@ Lisp variable `org-state'." :group 'org-todo :type 'hook) +(defcustom org-after-note-stored-hook nil + "Hook triggered after a note is stored. +The point is at the stored note when the hook is executed." + :group 'org-progress + :type 'hook + :package-version '(Org . "9.7")) + (defvar org-blocker-hook nil "Hook for functions that are allowed to block a state change. @@ -2398,7 +2468,8 @@ string as an argument and return the numeric priority." :tag "Org Time" :group 'org) -(defcustom org-time-stamp-rounding-minutes '(0 5) +(defvaralias 'org-time-stamp-rounding-minutes 'org-timestamp-rounding-minutes) +(defcustom org-timestamp-rounding-minutes '(0 5) "Number of minutes to round time stamps to. \\\ These are two values, the first applies when first creating a time stamp. @@ -2411,7 +2482,7 @@ numbers should be factors of 60, so for example 5, 10, 15. When this is larger than 1, you can still force an exact time stamp by using a double prefix argument to a time stamp command like \ -`\\[org-time-stamp]' or `\\[org-time-stamp-inactive], +`\\[org-timestamp]' or `\\[org-timestamp-inactive], and by using a prefix arg to `S-up/down' to specify the exact number of minutes to shift." :group 'org-time @@ -2424,21 +2495,22 @@ of minutes to shift." (integer :tag "when modifying times"))) ;; Normalize old customizations of this variable. -(when (integerp org-time-stamp-rounding-minutes) - (setq org-time-stamp-rounding-minutes - (list org-time-stamp-rounding-minutes - org-time-stamp-rounding-minutes))) +(when (integerp org-timestamp-rounding-minutes) + (setq org-timestamp-rounding-minutes + (list org-timestamp-rounding-minutes + org-timestamp-rounding-minutes))) (defcustom org-display-custom-times nil "Non-nil means overlay custom formats over all time stamps. -The formats are defined through the variable `org-time-stamp-custom-formats'. +The formats are defined through the variable `org-timestamp-custom-formats'. To turn this on on a per-file basis, insert anywhere in the file: #+STARTUP: customtime" :group 'org-time :type 'sexp) (make-variable-buffer-local 'org-display-custom-times) -(defcustom org-time-stamp-custom-formats +(defvaralias 'org-time-stamp-custom-formats 'org-timestamp-custom-formats) +(defcustom org-timestamp-custom-formats '("%m/%d/%y %a" . "%m/%d/%y %a %H:%M") ; american "Custom formats for time stamps. @@ -2449,6 +2521,8 @@ These are overlaid over the default ISO format if the variable end of the second format. The custom formats are also honored by export commands, if custom time display is turned on at the time of export. +This variable also affects how timestamps are exported. + Leading \"<\" and trailing \">\" pair will be stripped from the format strings." :group 'org-time @@ -2458,8 +2532,8 @@ strings." (defun org-time-stamp-format (&optional with-time inactive custom) "Get timestamp format for a time string. -The format is based on `org-time-stamp-formats' (if CUSTOM is nil) or or -`org-time-stamp-custom-formats' (if CUSTOM if non-nil). +The format is based on `org-timestamp-formats' (if CUSTOM is nil) or or +`org-timestamp-custom-formats' (if CUSTOM if non-nil). When optional argument WITH-TIME is non-nil, the timestamp will contain time. @@ -2470,8 +2544,8 @@ Otherwise, format inactive timestamp." (let ((format (funcall (if with-time #'cdr #'car) (if custom - org-time-stamp-custom-formats - org-time-stamp-formats)))) + org-timestamp-custom-formats + org-timestamp-formats)))) ;; Strip brackets, if any. (when (or (and (string-prefix-p "<" format) (string-suffix-p ">" format)) @@ -2596,7 +2670,7 @@ is non-nil." (defcustom org-read-date-popup-calendar t "Non-nil means pop up a calendar when prompting for a date. -In the calendar, the date can be selected with mouse-1. However, the +In the calendar, the date can be selected with \\`mouse-1'. However, the minibuffer will also be active, and you can simply enter the date as well. When nil, only the minibuffer will be available." :group 'org-time @@ -2771,6 +2845,25 @@ displaying the tags menu is not even shown, until you press `C-c' again." (const :tag "Yes" t) (const :tag "Expert" expert))) +(defvar org--fast-tag-selection-keys + (string-to-list "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ{|}~") + "List of chars to be used as bindings by `org-fast-tag-selection'.") + +(defcustom org-fast-tag-selection-maximum-tags (length org--fast-tag-selection-keys) + "Set the maximum tags number for fast tag selection. +This variable only affects tags without explicit key bindings outside +tag groups. All the tags with user bindings and all the tags +corresponding to tag groups are always displayed. + +When the number of tags with bindings + tags inside tag groups is +smaller than `org-fast-tag-selection-maximum-tags', tags without +explicit bindings will be assigned a binding and displayed up to the +limit." + :package-version '(Org . "9.7") + :group 'org-tags + :type 'number + :safe #'numberp) + (defvar org-fast-tag-selection-include-todo nil "Non-nil means fast tags selection interface will also offer TODO states. This is an undocumented feature, you should not rely on it.") @@ -2860,8 +2953,8 @@ is better to limit inheritance to certain tags using the variables :group 'org-tags :type '(choice (const :tag "No sorting" nil) - (const :tag "Alphabetical" string-collate-lessp) - (const :tag "Reverse alphabetical" org-string-collate-greaterp) + (const :tag "Alphabetical" org-string<) + (const :tag "Reverse alphabetical" org-string>) (function :tag "Custom function" nil))) (defvar org-tags-history nil @@ -3189,7 +3282,9 @@ Replace format-specifiers in the command as noted below and use %j: Executable file in fully expanded form as specified by `org-latex-to-mathml-jar-file'. %I: Input LaTeX file in fully expanded form. -%i: The latex fragment to be converted. +%i: Shell-escaped LaTeX fragment to be converted. + It must not be used inside a quoted argument, the result of %i + expansion inside a quoted argument is undefined. %o: Output MathML file. This command is used by `org-create-math-formula'. @@ -3198,25 +3293,27 @@ When using MathToWeb as the converter, set this option to \"java -jar %j -unicode -force -df %o %I\". When using LaTeXML set this option to -\"latexmlmath \"%i\" --presentationmathml=%o\"." +\"latexmlmath %i --presentationmathml=%o\"." :group 'org-latex - :version "24.1" + :package-version '(Org . "9.7") :type '(choice (const :tag "None" nil) (string :tag "\nShell command"))) (defcustom org-latex-to-html-convert-command nil - "Command to convert LaTeX fragments to HTML. + "Shell command to convert LaTeX fragments to HTML. This command is very open-ended: the output of the command will directly replace the LaTeX fragment in the resulting HTML. Replace format-specifiers in the command as noted below and use `shell-command' to convert LaTeX to HTML. -%i: The LaTeX fragment to be converted. +%i: The LaTeX fragment to be converted (shell-escaped). + It must not be used inside a quoted argument, the result of %i + expansion inside a quoted argument is undefined. For example, this could be used with LaTeXML as -\"latexmlc \\='literal:%i\\=' --profile=math --preload=siunitx.sty 2>/dev/null\"." +\"latexmlc literal:%i --profile=math --preload=siunitx.sty 2>/dev/null\"." :group 'org-latex - :package-version '(Org . "9.4") + :package-version '(Org . "9.7") :type '(choice (const :tag "None" nil) (string :tag "Shell command"))) @@ -3383,15 +3480,21 @@ header, or they will be appended." (default-value var))) (defcustom org-latex-default-packages-alist - '(("AUTO" "inputenc" t ("pdflatex")) + '(;; amsmath before fontspec for lualatex and xetex + ("" "amsmath" t ("lualatex" "xetex")) + ;; fontspec ASAP for lualatex and xetex + ("" "fontspec" t ("lualatex" "xetex")) + ;; inputenc and fontenc are for pdflatex only + ("AUTO" "inputenc" t ("pdflatex")) ("T1" "fontenc" t ("pdflatex")) ("" "graphicx" t) ("" "longtable" nil) ("" "wrapfig" nil) ("" "rotating" nil) ("normalem" "ulem" t) - ("" "amsmath" t) - ("" "amssymb" t) + ;; amsmath and amssymb after inputenc/fontenc for pdflatex + ("" "amsmath" t ("pdflatex")) + ("" "amssymb" t ("pdflatex")) ("" "capt-of" nil) ("" "hyperref" nil)) "Alist of default packages to be inserted in the header. @@ -3402,7 +3505,9 @@ incompatibility with another package you are using. The packages in this list are needed by one part or another of Org mode to function properly: +- fontspec: for font and character selection in lualatex and xetex - inputenc, fontenc: for basic font and character selection + in pdflatex - graphicx: for including images - longtable: For multipage tables - wrapfig: for figure placement @@ -3439,8 +3544,7 @@ A string will be inserted as-is in the header of the document." :group 'org-export-latex :set 'org-set-packages-alist :get 'org-get-packages-alist - :version "26.1" - :package-version '(Org . "8.3") + :package-version '(Org . "9.7") :type '(repeat (choice (list :tag "options/package pair" @@ -3692,8 +3796,8 @@ You need to reload Org or to restart Emacs after setting this.") "Alist of characters and faces to emphasize text. Text starting and ending with a special character will be emphasized, for example *bold*, _underlined_ and /italic/. This variable sets the -marker characters and the face to be used by font-lock for highlighting -in Org buffers. +face to be used by font-lock for highlighting in Org buffers. +Marker characters must be one of */_=~+. You need to reload Org or to restart Emacs after customizing this." :group 'org-appearance @@ -3702,7 +3806,13 @@ You need to reload Org or to restart Emacs after customizing this." :package-version '(Org . "8.0") :type '(repeat (list - (string :tag "Marker character") + (choice + (const :tag "Bold" "*") + (const :tag "Italic" "/") + (const :tag "Underline" "_") + (const :tag "Verbatim" "=") + (const :tag "Code" "~") + (const :tag "Strike through" "+")) (choice (face :tag "Font-lock-face") (plist :tag "Face property list")) @@ -3760,7 +3870,6 @@ This is needed for font-lock setup.") (defvar calc-embedded-close-formula) (defvar calc-embedded-open-formula) (defvar calc-embedded-open-mode) -(defvar font-lock-unfontify-region-function) (defvar org-agenda-tags-todo-honor-ignore-options) (defvar remember-data-file) (defvar texmathp-why) @@ -4021,10 +4130,10 @@ After a match, the following groups carry important information: 4 the second time, if it is a range.") (defconst org-startup-options - '(("fold" org-startup-folded t) - ("overview" org-startup-folded t) - ("nofold" org-startup-folded nil) - ("showall" org-startup-folded nil) + '(("fold" org-startup-folded fold) + ("overview" org-startup-folded overview) + ("nofold" org-startup-folded nofold) + ("showall" org-startup-folded showall) ("show2levels" org-startup-folded show2levels) ("show3levels" org-startup-folded show3levels) ("show4levels" org-startup-folded show4levels) @@ -4042,6 +4151,8 @@ After a match, the following groups carry important information: ("align" org-startup-align-all-tables t) ("noalign" org-startup-align-all-tables nil) ("shrink" org-startup-shrink-all-tables t) + ("descriptivelinks" org-link-descriptive t) + ("literallinks" org-link-descriptive nil) ("inlineimages" org-startup-with-inline-images t) ("noinlineimages" org-startup-with-inline-images nil) ("latexpreview" org-startup-with-latex-preview t) @@ -4077,6 +4188,7 @@ After a match, the following groups carry important information: ("fnplain" org-footnote-auto-label plain) ("fnadjust" org-footnote-auto-adjust t) ("nofnadjust" org-footnote-auto-adjust nil) + ("fnanon" org-footnote-auto-label anonymous) ("constcgs" constants-unit-system cgs) ("constSI" constants-unit-system SI) ("noptag" org-tag-persistent-alist nil) @@ -4406,18 +4518,20 @@ directory." (regexp (org-make-options-regexp keywords))) (while (and keywords (re-search-forward regexp nil t)) (let ((element (org-element-at-point))) - (when (eq 'keyword (org-element-type element)) + (when (org-element-type-p element 'keyword) (let ((value (org-element-property :value element))) (pcase (org-element-property :key element) ("SETUPFILE" - (when (and (org-string-nw-p value) - (not buffer-read-only)) ;FIXME: bug in Gnus? + (when (org-string-nw-p value) (let* ((uri (org-strip-quotes value)) (uri-is-url (org-url-p uri)) (uri (if uri-is-url uri - (expand-file-name uri)))) - (unless (member uri files) + ;; In case of error, be safe. + ;; See bug#68976. + (ignore-errors ; return nil when expansion fails. + (expand-file-name uri))))) + (unless (or (not uri) (member uri files)) (with-temp-buffer (unless uri-is-url (setq default-directory (file-name-directory uri))) @@ -4427,6 +4541,7 @@ directory." ;; Fake Org mode: `org-element-at-point' ;; doesn't need full set-up. (let ((major-mode 'org-mode)) + (setq-local tab-width 8) (setq alist (org--collect-keywords-1 keywords unique directory @@ -4558,12 +4673,17 @@ from file or URL, and return nil. If NOCACHE is non-nil, do a fresh fetch of FILE even if cached version is available. This option applies only if FILE is a URL." (let* ((is-url (org-url-p file)) + (is-remote (condition-case nil + (file-remote-p file) + ;; In case of error, be safe. + ;; See bug#68976. + (t t))) (cache (and is-url (not nocache) (gethash file org--file-cache)))) (cond (cache) - (is-url + ((or is-url is-remote) (if (org--should-fetch-remote-resource-p file) (condition-case error (with-current-buffer (url-retrieve-synchronously file) @@ -4582,7 +4702,7 @@ is available. This option applies only if FILE is a URL." file) nil)) (error (if noerror - (message "Org could't download \"%s\": %s %S" file (car error) (cdr error)) + (message "Org couldn't download \"%s\": %s %S" file (car error) (cdr error)) (signal (car error) (cdr error))))) (funcall (if noerror #'message #'user-error) "The remote resource %S is considered unsafe, and will not be downloaded." @@ -4649,9 +4769,9 @@ returns non-nil if any of them match." (propertize domain 'face '(:inherit org-link :weight normal)) ") as safe.\n ") "") - (propertize "f" 'face 'success) (if current-file (concat + (propertize "f" 'face 'success) " to download this resource, and permanently mark all resources in " (propertize current-file 'face 'underline) " as safe.\n ") @@ -4685,7 +4805,7 @@ returns non-nil if any of them match." (if (and (= char ?f) current-file) (concat "file://" current-file) uri)) "\\'"))))) - (prog1 (memq char '(?y ?n ?! ?d ?\s ?f)) + (prog1 (memq char '(?y ?! ?d ?\s ?f)) (quit-window t))))))) (defun org-extract-log-state-settings (x) @@ -4735,7 +4855,7 @@ Respect keys that are already there." (defvar org-selected-window nil "Used in various places to store a window configuration.") (defvar org-finish-function nil - "Function to be called when `C-c C-c' is used. + "Function to be called when \\`C-c C-c' is used. This is for getting out of special buffers like capture.") (defvar org-last-state) @@ -4777,6 +4897,7 @@ This is for getting out of special buffers like capture.") ;; babel (require 'ob) +(defvar org-element-cache-version); Defined in org-element.el (defvar org-element-cache-persistent); Defined in org-element.el (defvar org-element-use-cache); Defined in org-element.el (defvar org-mode-loading nil @@ -4785,6 +4906,23 @@ This is for getting out of special buffers like capture.") (defvar org-agenda-file-menu-enabled t "When non-nil, refresh Agenda files in Org menu when loading Org.") +(defvar org-mode-syntax-table + (let ((st (make-syntax-table outline-mode-syntax-table))) + (modify-syntax-entry ?\" "\"" st) + (modify-syntax-entry ?\\ "_" st) + (modify-syntax-entry ?~ "_" st) + (modify-syntax-entry ?< "(>" st) + (modify-syntax-entry ?> ")<" st) + st) + "Standard syntax table for Org mode buffers.") + +(defvar org-mode-tags-syntax-table + (let ((st (make-syntax-table org-mode-syntax-table))) + (modify-syntax-entry ?@ "w" st) + (modify-syntax-entry ?_ "w" st) + st) + "Syntax table including \"@\" and \"_\" as word constituents.") + ;;;###autoload (define-derived-mode org-mode outline-mode "Org" "Outline-based notes management and organizer, alias @@ -4805,21 +4943,28 @@ The following commands are available: \\{org-mode-map}" (setq-local org-mode-loading t) + ;; Force tab width - indentation is significant in lists, so we need + ;; to make sure that it is consistent across configurations. + (setq-local tab-width 8) (org-load-modules-maybe) (when org-agenda-file-menu-enabled (org-install-agenda-files-menu)) - (when (and org-link-descriptive - (eq org-fold-core-style 'overlays)) - (add-to-invisibility-spec '(org-link))) + (setq-local outline-regexp org-outline-regexp) + (setq-local outline-level 'org-outline-level) + ;; Initialize cache. + (org-element-cache-reset) + (when (and org-element-cache-persistent + org-element-use-cache) + (org-persist-load + `((elisp org-element--cache) (version ,org-element-cache-version)) + (current-buffer) + 'match-hash :read-related t)) + (org-set-regexps-and-options) + (add-to-invisibility-spec '(org-link)) (org-fold-initialize (or (and (stringp org-ellipsis) (not (equal "" org-ellipsis)) org-ellipsis) - "...")) + "...")) (make-local-variable 'org-link-descriptive) (when (eq org-fold-core-style 'overlays) (add-to-invisibility-spec '(org-hide-block . t))) - (if org-link-descriptive - (org-fold-core-set-folding-spec-property (car org-link--link-folding-spec) :visible nil) - (org-fold-core-set-folding-spec-property (car org-link--link-folding-spec) :visible t)) - (setq-local outline-regexp org-outline-regexp) - (setq-local outline-level 'org-outline-level) (when (and (stringp org-ellipsis) (not (equal "" org-ellipsis))) (unless org-display-table (setq org-display-table (make-display-table))) @@ -4828,30 +4973,23 @@ The following commands are available: (vconcat (mapcar (lambda (c) (make-glyph-code c 'org-ellipsis)) org-ellipsis))) (setq buffer-display-table org-display-table)) - (org-set-regexps-and-options) (org-set-font-lock-defaults) (when (and org-tag-faces (not org-tags-special-faces-re)) ;; tag faces set outside customize.... force initialization. (org-set-tag-faces 'org-tag-faces org-tag-faces)) ;; Calc embedded (setq-local calc-embedded-open-mode "# ") - ;; Modify a few syntax entries - (modify-syntax-entry ?\" "\"") - (modify-syntax-entry ?\\ "_") - (modify-syntax-entry ?~ "_") - (modify-syntax-entry ?< "(>") - (modify-syntax-entry ?> ")<") + ;; Set syntax table. Ensure that buffer-local changes to the syntax + ;; table do not affect other Org buffers. + (set-syntax-table (make-syntax-table org-mode-syntax-table)) (setq-local font-lock-unfontify-region-function 'org-unfontify-region) ;; Activate before-change-function (setq-local org-table-may-need-update t) (add-hook 'before-change-functions 'org-before-change-function nil 'local) ;; Check for running clock before killing a buffer (add-hook 'kill-buffer-hook 'org-check-running-clock nil 'local) - ;; Initialize cache. - (org-element-cache-reset) - (when (and org-element-cache-persistent - org-element-use-cache) - (org-persist-load 'org-element--cache (current-buffer) t)) + ;; Check for invisible edits. + (org-fold--advice-edit-commands) ;; Initialize macros templates. (org-macro-initialize-templates) ;; Initialize radio targets. @@ -4905,6 +5043,20 @@ The following commands are available: #'pcomplete-completions-at-point nil t) (setq-local buffer-face-mode-face 'org-default) + ;; `thing-at-point' support + (when (boundp 'thing-at-point-provider-alist) + (setq-local thing-at-point-provider-alist + (cons '(url . org--link-at-point) + thing-at-point-provider-alist))) + (when (boundp 'forward-thing-provider-alist) + (setq-local forward-thing-provider-alist + (cons '(url . org-next-link) + forward-thing-provider-alist))) + (when (boundp 'bounds-of-thing-at-point-provider-alist) + (setq-local bounds-of-thing-at-point-provider-alist + (cons '(url . org--bounds-of-link-at-point) + bounds-of-thing-at-point-provider-alist))) + ;; If empty file that did not turn on Org mode automatically, make ;; it to. (when (and org-insert-mode-line-in-empty-file @@ -4956,7 +5108,10 @@ The following commands are available: (org--set-faces-extend '(org-block-begin-line org-block-end-line) org-fontify-whole-block-delimiter-line) (org--set-faces-extend org-level-faces org-fontify-whole-heading-line) - (setq-local org-mode-loading nil)) + (setq-local org-mode-loading nil) + + ;; `yank-media' handler and DND support. + (org-setup-yank-dnd-handlers)) ;; Update `customize-package-emacs-version-alist' (add-to-list 'customize-package-emacs-version-alist @@ -4971,7 +5126,8 @@ The following commands are available: ("9.3" . "27.1") ("9.4" . "27.2") ("9.5" . "28.1") - ("9.6" . "29.1"))) + ("9.6" . "29.1") + ("9.7" . "30.1"))) (defvar org-mode-transpose-word-syntax-table (let ((st (make-syntax-table text-mode-syntax-table))) @@ -4999,10 +5155,10 @@ The following commands are available: (defun org-current-time (&optional rounding-minutes past) "Current time, possibly rounded to ROUNDING-MINUTES. When ROUNDING-MINUTES is not an integer, fall back on the car of -`org-time-stamp-rounding-minutes'. When PAST is non-nil, ensure +`org-timestamp-rounding-minutes'. When PAST is non-nil, ensure the rounding returns a past time." (let ((r (or (and (integerp rounding-minutes) rounding-minutes) - (car org-time-stamp-rounding-minutes))) + (car org-timestamp-rounding-minutes))) (now (current-time))) (if (< r 1) now @@ -5061,6 +5217,12 @@ stacked delimiters is N. Escaping delimiters is not possible." (defvar org-emph-face nil) +(defconst org-nonsticky-props + '(mouse-face highlight keymap invisible intangible help-echo org-linked-text htmlize-link)) + +(defsubst org-rear-nonsticky-at (pos) + (add-text-properties (1- pos) pos (list 'rear-nonsticky org-nonsticky-props))) + (defun org-do-emphasis-faces (limit) "Run through the buffer and emphasize strings." (let ((quick-re (format "\\([%s]\\|^\\)\\([~=*/_+]\\)" @@ -5099,10 +5261,6 @@ stacked delimiters is N. Escaping delimiters is not possible." (when verbatim? (org-remove-flyspell-overlays-in (match-beginning 0) (match-end 0)) - (when (and (org-fold-core-folding-spec-p 'org-link) - (org-fold-core-folding-spec-p 'org-link-description)) - (org-fold-region (match-beginning 0) (match-end 0) nil 'org-link) - (org-fold-region (match-beginning 0) (match-end 0) nil 'org-link-description)) (remove-text-properties (match-beginning 2) (match-end 2) '(display t invisible t intangible t))) (add-text-properties (match-beginning 2) (match-end 2) @@ -5111,8 +5269,18 @@ stacked delimiters is N. Escaping delimiters is not possible." (not (org-at-comment-p))) (add-text-properties (match-end 4) (match-beginning 5) '(invisible t)) + ;; https://orgmode.org/list/8b691a7f-6b62-d573-e5a8-80fac3dc9bc6@vodafonemail.de + (org-rear-nonsticky-at (match-beginning 5)) (add-text-properties (match-beginning 3) (match-end 3) - '(invisible t))) + '(invisible t)) + ;; FIXME: This would break current behavior with point + ;; being adjusted before hidden emphasis marker when + ;; using M-b. A proper fix would require custom + ;; syntax function that will mark emphasis markers as + ;; word constituents where appropriate. + ;; https://orgmode.org/list/87edl41jf0.fsf@localhost + ;; (org-rear-nonsticky-at (match-end 3)) + ) (throw :exit t)))))))) (defun org-emphasize (&optional char) @@ -5160,13 +5328,7 @@ prompted for." (insert string) (and move (backward-char 1)))) -(defconst org-nonsticky-props - '(mouse-face highlight keymap invisible intangible help-echo org-linked-text htmlize-link)) - -(defsubst org-rear-nonsticky-at (pos) - (add-text-properties (1- pos) pos (list 'rear-nonsticky org-nonsticky-props))) - -(defun org-activate-links--overlays (limit) +(defun org-activate-links (limit) "Add link properties to links. This includes angle, plain, and bracket links." (catch :exit @@ -5222,10 +5384,12 @@ This includes angle, plain, and bracket links." ;; Handle invisible parts in bracket links. (remove-text-properties start end '(invisible nil)) (let ((hidden - (append `(invisible - ,(or (org-link-get-parameter type :display) - 'org-link)) - properties))) + (if org-link-descriptive + (append `(invisible + ,(or (org-link-get-parameter type :display) + 'org-link)) + properties) + properties))) (add-text-properties start visible-start hidden) (add-face-text-property start end face-property) (add-text-properties visible-start visible-end properties) @@ -5237,99 +5401,6 @@ This includes angle, plain, and bracket links." (funcall f start end path (eq style 'bracket)))) (throw :exit t))))) ;signal success nil)) -(defun org-activate-links--text-properties (limit) - "Add link properties to links. -This includes angle, plain, and bracket links." - (catch :exit - (while (re-search-forward org-link-any-re limit t) - (let* ((start (match-beginning 0)) - (end (match-end 0)) - (visible-start (or (match-beginning 3) (match-beginning 2))) - (visible-end (or (match-end 3) (match-end 2))) - (style (cond ((eq ?< (char-after start)) 'angle) - ((eq ?\[ (char-after (1+ start))) 'bracket) - (t 'plain)))) - (when (and (memq style org-highlight-links) - ;; Do not span over paragraph boundaries. - (not (string-match-p org-element-paragraph-separate - (match-string 0))) - ;; Do not confuse plain links with tags. - (not (and (eq style 'plain) - (let ((face (get-text-property - (max (1- start) (point-min)) 'face))) - (if (consp face) (memq 'org-tag face) - (eq 'org-tag face)))))) - (let* ((link-object (save-excursion - (goto-char start) - (save-match-data (org-element-link-parser)))) - (link (org-element-property :raw-link link-object)) - (type (org-element-property :type link-object)) - (path (org-element-property :path link-object)) - (face-property (pcase (org-link-get-parameter type :face) - ((and (pred functionp) face) (funcall face path)) - ((and (pred facep) face) face) - ((and (pred consp) face) face) ;anonymous - (_ 'org-link))) - (properties ;for link's visible part - (list 'mouse-face (or (org-link-get-parameter type :mouse-face) - 'highlight) - 'keymap (or (org-link-get-parameter type :keymap) - org-mouse-map) - 'help-echo (pcase (org-link-get-parameter type :help-echo) - ((and (pred stringp) echo) echo) - ((and (pred functionp) echo) echo) - (_ (concat "LINK: " link))) - 'htmlize-link (pcase (org-link-get-parameter type - :htmlize-link) - ((and (pred functionp) f) (funcall f)) - (_ `(:uri ,link))) - 'font-lock-multiline t))) - (org-remove-flyspell-overlays-in start end) - (org-rear-nonsticky-at end) - (if (not (eq 'bracket style)) - (progn - (add-face-text-property start end face-property) - (add-text-properties start end properties)) - ;; Initialize folding when used outside org-mode. - (unless (or (derived-mode-p 'org-mode) - (and (org-fold-folding-spec-p 'org-link-description) - (org-fold-folding-spec-p 'org-link))) - (org-fold-initialize (or (and (stringp org-ellipsis) (not (equal "" org-ellipsis)) org-ellipsis) - "..."))) - ;; Handle invisible parts in bracket links. - (let ((spec (or (org-link-get-parameter type :display) - 'org-link))) - (unless (org-fold-folding-spec-p spec) - (org-fold-add-folding-spec spec - (cdr org-link--link-folding-spec) - nil - 'append) - (org-fold-core-set-folding-spec-property spec :visible t)) - (org-fold-region start end nil 'org-link) - (org-fold-region start end nil 'org-link-description) - ;; We are folding the whole emphasized text with SPEC - ;; first. It makes everything invisible (or whatever - ;; the user wants). - (org-fold-region start end t spec) - ;; The visible part of the text is folded using - ;; 'org-link-description, which is forcing this part of - ;; the text to be visible. - (org-fold-region visible-start visible-end t 'org-link-description) - (add-text-properties start end properties) - (add-face-text-property start end face-property) - (org-rear-nonsticky-at visible-start) - (org-rear-nonsticky-at visible-end))) - (let ((f (org-link-get-parameter type :activate-func))) - (when (functionp f) - (funcall f start end path (eq style 'bracket)))) - (throw :exit t))))) ;signal success - nil)) -(defsubst org-activate-links (limit) - "Add link properties to links. -This includes angle, plain, and bracket links." - (if (eq org-fold-core-style 'text-properties) - (org-activate-links--text-properties limit) - (org-activate-links--overlays limit))) (defun org-activate-code (limit) (when (re-search-forward "^[ \t]*\\(:\\(?: .*\\|$\\)\n?\\)" limit t) @@ -5356,7 +5427,7 @@ by a #." :group 'org-appearance) (defun org-fontify-meta-lines-and-blocks (limit) - (condition-case nil + (condition-case-unless-debug nil (org-fontify-meta-lines-and-blocks-1 limit) (error (message "Org mode fontification error in %S at %d" (current-buffer) @@ -5374,7 +5445,7 @@ by a #." (zero-or-more (any " \t")) (group (group (zero-or-more (not (any " \t\n")))) (zero-or-more (any " \t")) - (group (zero-or-more any))))) + (group (zero-or-more nonl))))) limit t) (let ((beg (match-beginning 0)) (end-of-beginline (match-end 0)) @@ -5400,7 +5471,7 @@ by a #." "#+end" ,(match-string 4) word-end - (zero-or-more any))))) + (zero-or-more nonl))))) ;; We look further than LIMIT on purpose. nil t) ;; We do have a matching #+end line. @@ -5416,10 +5487,18 @@ by a #." beg end-of-endline '(font-lock-fontified t font-lock-multiline t)) (org-remove-flyspell-overlays-in beg bol-after-beginline) (org-remove-flyspell-overlays-in nl-before-endline end-of-endline) - (cond - ((and lang (not (string= lang "")) org-src-fontify-natively) + (cond + ((and org-src-fontify-natively + ;; Technically, according to the + ;; `org-src-fontify-natively' docstring, we should + ;; only fontify src blocks. However, it is common + ;; to use undocumented fontification of export and + ;; example blocks. (The latter which do not support a + ;; language specifier.) Keep this undocumented feature + ;; for user convenience. + (member block-type '("src" "export" "example"))) (save-match-data - (org-src-font-lock-fontify-block lang block-start block-end)) + (org-src-font-lock-fontify-block (or lang "") block-start block-end)) (add-text-properties bol-after-beginline block-end '(src-block t))) (quoting (add-text-properties @@ -5470,10 +5549,10 @@ by a #." '(display t invisible t intangible t)) ;; Handle short captions (save-excursion - (beginning-of-line) + (forward-line 0) (looking-at (rx (group (zero-or-more (any " \t")) "#+caption" - (optional "[" (zero-or-more any) "]") + (optional "[" (zero-or-more nonl) "]") ":") (zero-or-more (any " \t"))))) (add-text-properties (line-beginning-position) (match-end 1) @@ -5513,9 +5592,10 @@ by a #." (match-string 1)) (let ((end (match-end 1)) (closing-start (match-beginning 1))) + (add-face-text-property begin end 'org-macro) (add-text-properties begin end - '(font-lock-multiline t font-lock-fontified t face org-macro)) + '(font-lock-multiline t font-lock-fontified t)) (org-remove-flyspell-overlays-in begin end) (when org-hide-macro-markers (add-text-properties begin opening-end '(invisible t)) @@ -5524,7 +5604,9 @@ by a #." (defun org-fontify-extend-region (beg end _old-len) (let ((end (if (progn (goto-char end) (looking-at-p "^[*#]")) - (1+ end) end)) + (min (point-max) (1+ end)) + ;; See `font-lock-extend-jit-lock-region-after-change' and bug#68849. + (min (point-max) (1+ end)))) (begin-re "\\(\\\\\\[\\|\\(#\\+begin_\\|\\\\begin{\\)\\S-+\\)") (end-re "\\(\\\\\\]\\|\\(#\\+end_\\|\\\\end{\\)\\S-+\\)") (extend @@ -5557,6 +5639,7 @@ by a #." (goto-char beg) (search-forward (or label "fn:")) (org-remove-flyspell-overlays-in beg (match-end 0)))) + (add-face-text-property beg end 'org-footnote) (add-text-properties beg end (list 'mouse-face 'highlight 'keymap org-mouse-map @@ -5564,8 +5647,7 @@ by a #." (if referencep "Footnote reference" "Footnote definition") 'font-lock-fontified t - 'font-lock-multiline t - 'face 'org-footnote)))))) + 'font-lock-multiline t)))))) (defun org-activate-dates (limit) "Add text properties for dates." @@ -5590,7 +5672,9 @@ by a #." ;; `org-target-link-regexp' matches one character before the ;; actual target. (unless (bolp) (forward-char -1)) - (when (re-search-forward org-target-link-regexp limit t) + (when (if org-target-link-regexps + (org--re-list-search-forward org-target-link-regexps limit t) + (re-search-forward org-target-link-regexp limit t)) (org-remove-flyspell-overlays-in (match-beginning 1) (match-end 1)) (add-text-properties (match-beginning 1) (match-end 1) (list 'mouse-face 'highlight @@ -5686,12 +5770,31 @@ highlighting was done, nil otherwise." (org-rear-nonsticky-at (match-end 1)) t)) +(defun org-activate-folds (limit) + "Arrange trailing newlines after folds to inherit face before the fold." + (let ((next-unfolded-newline (search-forward "\n" limit 'move))) + (while (and next-unfolded-newline (org-fold-folded-p) (not (eobp))) + (goto-char (org-fold-core-next-visibility-change nil limit)) + (setq next-unfolded-newline (search-forward "\n" limit 'move))) + (when next-unfolded-newline + (org-with-wide-buffer + (when (and (> (match-beginning 0) (point-min)) + (org-fold-folded-p (1- (match-beginning 0)))) + (put-text-property + (match-beginning 0) (match-end 0) + 'face + (get-text-property + (org-fold-previous-visibility-change + (1- (match-beginning 0))) + 'face))) + t)))) + (defun org-outline-level () "Compute the outline level of the heading at point. If this is called at a normal headline, the level is the number of stars. Use `org-reduced-level' to remove the effect of -`org-odd-levels'. Unlike to `org-current-level', this function +`org-odd-levels-only'. Unlike `org-current-level', this function takes into consideration inlinetasks." (org-with-wide-buffer (end-of-line) @@ -5754,6 +5857,8 @@ needs to be inserted at a specific position in the font-lock sequence.") (defun org-set-font-lock-defaults () "Set font lock defaults for the current buffer." (let ((org-font-lock-extra-keywords + ;; As a general rule, we apply the element (container) faces + ;; first and then prepend the object faces on top. (list ;; Call the hook '(org-font-lock-hook) @@ -5765,7 +5870,8 @@ needs to be inserted at a specific position in the font-lock sequence.") (2 (org-get-level-face 2)) (3 (org-get-level-face 3))) ;; Table lines - '("^[ \t]*\\(\\(|\\|\\+-[-+]\\).*\\S-\\)" + '("^[ \t]*\\(\\(|\\|\\+-[-+]\\).*\\S-\\)\n?" + (0 'org-table-row t) (1 'org-table t)) ;; Table internals '("^[ \t]*|\\(?:.*?|\\)? *\\(:?=[^|\n]*\\)" (1 'org-formula t)) @@ -5776,21 +5882,22 @@ needs to be inserted at a specific position in the font-lock sequence.") (list org-property-re '(1 'org-special-keyword t) '(3 'org-property-value t)) - ;; Drawers + ;; Drawer boundaries. '(org-fontify-drawers) + ;; Diary sexps. + '("^&?%%(.*\\|<%%([^>\n]*?>" (0 'org-sexp-date t)) ;; Link related fontification. - '(org-activate-links) + '(org-activate-links) ; `org-activate-links' prepends faces (when (memq 'tag org-highlight-links) '(org-activate-tags (1 'org-tag prepend))) - (when (memq 'radio org-highlight-links) '(org-activate-target-links (1 'org-link t))) - (when (memq 'date org-highlight-links) '(org-activate-dates (0 'org-date t))) + (when (memq 'radio org-highlight-links) '(org-activate-target-links (1 'org-link prepend))) + (when (memq 'date org-highlight-links) '(org-activate-dates (0 'org-date prepend))) + ;; `org-activate-footnote-links' prepends faces (when (memq 'footnote org-highlight-links) '(org-activate-footnote-links)) ;; Targets. - (list org-radio-target-regexp '(0 'org-target t)) - (list org-target-regexp '(0 'org-target t)) - ;; Diary sexps. - '("^&?%%(.*\\|<%%([^>\n]*?>" (0 'org-sexp-date t)) + (list org-radio-target-regexp '(0 'org-target prepend)) + (list org-target-regexp '(0 'org-target prepend)) ;; Macro - '(org-fontify-macros) + '(org-fontify-macros) ; `org-fontify-macro' pepends faces ;; TODO keyword (list (format org-heading-keyword-regexp-format org-todo-regexp) @@ -5812,8 +5919,10 @@ needs to be inserted at a specific position in the font-lock sequence.") "\\)")) '(2 'org-headline-done prepend))) ;; Priorities + ;; `org-font-lock-add-priority-faces' prepends faces '(org-font-lock-add-priority-faces) ;; Tags + ;; `org-font-lock-add-tag-faces' prepends faces '(org-font-lock-add-tag-faces) ;; Tags groups (when (and org-group-tags org-tag-groups-alist) @@ -5821,16 +5930,16 @@ needs to be inserted at a specific position in the font-lock sequence.") (regexp-opt (mapcar 'car org-tag-groups-alist)) ":\\).*$") '(1 'org-tag-group prepend))) - ;; Special keywords + ;; Special keywords (as a part of planning) (list (concat "\\<" org-deadline-string) '(0 'org-special-keyword t)) (list (concat "\\<" org-scheduled-string) '(0 'org-special-keyword t)) (list (concat "\\<" org-closed-string) '(0 'org-special-keyword t)) (list (concat "\\<" org-clock-string) '(0 'org-special-keyword t)) ;; Emphasis + ;; `org-do-emphasis-faces' prepends faces (when org-fontify-emphasized-text '(org-do-emphasis-faces)) ;; Checkboxes - '("^[ \t]*\\(?:[-+*]\\|[0-9]+[.)]\\)[ \t]+\\(?:\\[@\\(?:start:\\)?[0-9]+\\][ \t]*\\)?\\(\\[[- X]\\]\\)" - 1 'org-checkbox prepend) + `(,org-list-full-item-re 3 'org-checkbox prepend lax) (when (cdr (assq 'checkbox org-list-automatic-rules)) '("\\[\\([0-9]*%\\)\\]\\|\\[\\([0-9]*\\)/\\([0-9]*\\)\\]" (0 (org-get-checkbox-statistics-face) prepend))) @@ -5839,35 +5948,44 @@ needs to be inserted at a specific position in the font-lock sequence.") 1 'org-list-dt prepend) ;; Inline export snippets '("\\(@@\\)\\([a-z-]+:\\).*?\\(@@\\)" - (1 'font-lock-comment-face t) - (2 'org-tag t) - (3 'font-lock-comment-face t)) + (1 'font-lock-comment-face prepend) + (2 'org-tag prepend) + (3 'font-lock-comment-face prepend)) ;; ARCHIVEd headings (list (concat org-outline-regexp-bol "\\(.*:" org-archive-tag ":.*\\)") '(1 'org-archived prepend)) ;; Specials - '(org-do-latex-and-related) - '(org-fontify-entities) - '(org-raise-scripts) + '(org-do-latex-and-related) ; prepends faces + '(org-fontify-entities) ; applies composition + '(org-raise-scripts) ; applies display ;; Code - '(org-activate-code (1 'org-code t)) - ;; COMMENT - (list (format - "^\\*+\\(?: +%s\\)?\\(?: +\\[#[A-Z0-9]\\]\\)? +\\(?9:%s\\)\\(?: \\|$\\)" - org-todo-regexp - org-comment-string) - '(9 'org-special-keyword t)) + '(org-activate-code (1 'org-code prepend)) ;; Blocks and meta lines + ;; Their face is an override - keywords, affiliated + ;; keywords, blocks, and block boundaries are all + ;; containers or part of container-only markup. '(org-fontify-meta-lines-and-blocks) + ;; `org-fontify-inline-src-blocks' prepends object boundary + ;; faces and overrides native faces. '(org-fontify-inline-src-blocks) ;; Citations. When an activate processor is specified, if ;; specified, try loading it beforehand. (progn (unless (null org-cite-activate-processor) (org-cite-try-load-processor org-cite-activate-processor)) - '(org-cite-activate))))) + ;; prepends faces + '(org-cite-activate)) + ;; COMMENT + ;; Apply this last, after all the markup is highlighted, so + ;; that even "bright" markup will become dim. + (list (format + "^\\*+\\(?: +%s\\)?\\(?: +\\[#[A-Z0-9]\\]\\)? +\\(?9:%s\\)\\(?: \\|$\\)" + org-todo-regexp + org-comment-string) + '(9 'org-special-keyword prepend)) + '(org-activate-folds)))) (setq org-font-lock-extra-keywords (delq nil org-font-lock-extra-keywords)) (run-hooks 'org-font-lock-set-keywords-hook) ;; Now set the full font-lock-keywords @@ -5893,6 +6011,8 @@ needs to be inserted at a specific position in the font-lock sequence.") (defvar-local org-custom-properties-overlays nil "List of overlays used for custom properties.") +;; Preserve when switching modes or when restarting Org. +(put 'org-custom-properties-overlays 'permanent-local t) (defun org-toggle-custom-properties-visibility () "Display or hide properties in `org-custom-properties'." @@ -6039,8 +6159,6 @@ If TAG is a number, get the corresponding match group." '(mouse-face t keymap t org-linked-text t invisible t intangible t org-emphasis t)) - (org-fold-region beg end nil 'org-link) - (org-fold-region beg end nil 'org-link-description) (org-fold-core-update-optimisation beg end) (org-remove-font-lock-display-properties beg end))) @@ -6181,7 +6299,10 @@ frame is not changed." (let ((cbuf (current-buffer)) (cwin (selected-window)) (pos (point)) - beg end level heading ibuf) + beg end level heading ibuf + (last-indirect-window + (and org-last-indirect-buffer + (get-buffer-window org-last-indirect-buffer)))) (save-excursion (org-back-to-heading t) (when (numberp arg) @@ -6204,8 +6325,7 @@ frame is not changed." ((or (eq org-indirect-buffer-display 'new-frame) (and arg (eq org-indirect-buffer-display 'dedicated-frame))) (select-frame (make-frame)) - (delete-other-windows) - (pop-to-buffer-same-window ibuf) + (pop-to-buffer ibuf '(org-display-buffer-full-frame)) (org-set-frame-title heading)) ((eq org-indirect-buffer-display 'dedicated-frame) (raise-frame @@ -6213,13 +6333,15 @@ frame is not changed." (frame-live-p org-indirect-dedicated-frame) org-indirect-dedicated-frame) (setq org-indirect-dedicated-frame (make-frame))))) - (delete-other-windows) - (pop-to-buffer-same-window ibuf) + (pop-to-buffer ibuf '(org-display-buffer-full-frame)) (org-set-frame-title (concat "Indirect: " heading))) ((eq org-indirect-buffer-display 'current-window) (pop-to-buffer-same-window ibuf)) ((eq org-indirect-buffer-display 'other-window) - (pop-to-buffer ibuf)) + (pop-to-buffer + ibuf + `(org-display-buffer-in-window (window . ,last-indirect-window) + (same-frame . t)))) (t (error "Invalid value"))) (narrow-to-region beg end) (org-fold-show-all '(headings drawers blocks)) @@ -6275,7 +6397,7 @@ headline instead of current one." (`(heading . ,value) value) (_ nil))) -(defun org-insert-heading (&optional arg invisible-ok top) +(defun org-insert-heading (&optional arg invisible-ok level) "Insert a new heading or an item with the same depth at point. If point is at the beginning of a heading, insert a new heading @@ -6304,12 +6426,29 @@ When INVISIBLE-OK is set, stop at invisible headlines when going back. This is important for non-interactive uses of the command. -When optional argument TOP is non-nil, insert a level 1 heading, -unconditionally." +When optional argument LEVEL is a number, insert a heading at +that level. For backwards compatibility, when LEVEL is non-nil +but not a number, insert a level-1 heading." (interactive "P") (let* ((blank? (org--blank-before-heading-p (equal arg '(16)))) - (level (org-current-level)) - (stars (make-string (if (and level (not top)) level 1) ?*))) + (current-level (org-current-level)) + (num-stars (or + ;; Backwards compat: if LEVEL non-nil, level is 1 + (and level (if (wholenump level) level 1)) + current-level + ;; This `1' is for when before first headline + 1)) + (stars (make-string num-stars ?*)) + (maybe-add-blank-after + (lambda (blank?) + "Add a blank line before next heading when BLANK? is non-nil. +Assume that point is on the inserted heading." + (save-excursion + (end-of-line) + (unless (eobp) + (forward-char) + (when (and blank? (org-at-heading-p)) + (insert "\n"))))))) (cond ((or org-insert-heading-respect-content (member arg '((4) (16))) @@ -6318,22 +6457,29 @@ unconditionally." ;; Position point at the location of insertion. Make sure we ;; end up on a visible headline if INVISIBLE-OK is nil. (org-with-limited-levels - (if (not level) (outline-next-heading) ;before first headline + (if (not current-level) (outline-next-heading) ;before first headline (org-back-to-heading invisible-ok) (when (equal arg '(16)) (org-up-heading-safe)) - (org-end-of-subtree))) + (org-end-of-subtree invisible-ok 'to-heading))) + ;; At `point-max', if the file does not have ending newline, + ;; create one, so that we are not appending stars at non-empty + ;; line. (unless (bolp) (insert "\n")) (when (and blank? (save-excursion (backward-char) (org-before-first-heading-p))) (insert "\n") (backward-char)) - (when (and (not level) (not (eobp)) (not (bobp))) + (when (and (not current-level) (not (eobp)) (not (bobp))) (when (org-at-heading-p) (insert "\n")) (backward-char)) (unless (and blank? (org-previous-line-empty-p)) (org-N-empty-lines-before-current (if blank? 1 0))) - (insert stars " ") + (insert stars " " "\n") + ;; Move point after stars. + (backward-char) + ;; Retain blank lines before next heading. + (funcall maybe-add-blank-after blank?) ;; When INVISIBLE-OK is non-nil, ensure newly created headline ;; is visible. (unless invisible-ok @@ -6364,34 +6510,42 @@ unconditionally." ;; Preserve tags. (let ((split (delete-and-extract-region (point) (match-end 4)))) (if (looking-at "[ \t]*$") (replace-match "") - (org-align-tags)) + (when org-auto-align-tags (org-align-tags))) (end-of-line) (when blank? (insert "\n")) (insert "\n" stars " ") + ;; Retain blank lines before next heading. + (funcall maybe-add-blank-after blank?) (when (org-string-nw-p split) (insert split)))) (t (end-of-line) (when blank? (insert "\n")) - (insert "\n" stars " ")))) + (insert "\n" stars " ") + ;; Retain blank lines before next heading. + (funcall maybe-add-blank-after blank?)))) ;; On regular text, turn line into a headline or split, if ;; appropriate. ((bolp) (insert stars " ") (unless (and blank? (org-previous-line-empty-p)) - (org-N-empty-lines-before-current (if blank? 1 0)))) + (org-N-empty-lines-before-current (if blank? 1 0))) + ;; Retain blank lines before next heading. + (funcall maybe-add-blank-after blank?)) (t (unless (org-get-alist-option org-M-RET-may-split-line 'headline) (end-of-line)) (insert "\n" stars " ") (unless (and blank? (org-previous-line-empty-p)) - (org-N-empty-lines-before-current (if blank? 1 0)))))) + (org-N-empty-lines-before-current (if blank? 1 0))) + ;; Retain blank lines before next heading. + (funcall maybe-add-blank-after blank?)))) (run-hooks 'org-insert-heading-hook)) (defun org-N-empty-lines-before-current (n) "Make the number of empty lines before current exactly N. So this will delete or add empty lines." (let ((column (current-column))) - (beginning-of-line) + (forward-line 0) (unless (bobp) (let ((start (save-excursion (skip-chars-backward " \r\t\n") @@ -6476,7 +6630,7 @@ Set it to HEADING when provided." (if old (replace-match new t t nil 4) (goto-char (or (match-end 3) (match-end 2) (match-end 1))) (insert " " new)) - (org-align-tags) + (when org-auto-align-tags (org-align-tags)) (when (looking-at "[ \t]*$") (replace-match "")))))))) (defun org-insert-heading-after-current () @@ -6492,19 +6646,22 @@ Set it to HEADING when provided." (interactive) (org-insert-heading '(4) invisible-ok)) -(defun org-insert-todo-heading-respect-content (&optional _) - "Insert TODO heading with `org-insert-heading-respect-content' set to t." - (interactive) +(defun org-insert-todo-heading-respect-content (&optional arg) + "Call `org-insert-todo-heading', inserting after current subtree. +ARG is passed to `org-insert-todo-heading'. +This command temporarily sets `org-insert-heading-respect-content' to t." + (interactive "P") (let ((org-insert-heading-respect-content t)) - (org-insert-todo-heading '(4) t))) + (org-insert-todo-heading arg t))) (defun org-insert-todo-heading (arg &optional force-heading) "Insert a new heading with the same level and TODO state as current heading. If the heading has no TODO state, or if the state is DONE, use -the first state (TODO by default). Also with one prefix arg, -force first state. With two prefix args, force inserting at the -end of the parent subtree. +the first state (TODO by default). Also with `\\[universal-argument]' +prefix, force first state. With a `\\[universal-argument] +\\[universal-argument]' prefix, force inserting at the end of the +parent subtree. When called at a plain list item, insert a new item with an unchecked check box." @@ -6526,7 +6683,7 @@ unchecked check box." (run-hook-with-args-until-success 'org-todo-get-default-hook new-mark-x nil) new-mark-x))) - (beginning-of-line 1) + (forward-line 0) (and (looking-at org-outline-regexp) (goto-char (match-end 0)) (if org-treat-insert-todo-heading-as-state-change (org-todo new-mark) @@ -6536,8 +6693,12 @@ unchecked check box." (defun org-insert-subheading (arg) "Insert a new subheading and demote it. -Works for outline headings and for plain lists alike." +Works for outline headings and for plain lists alike. +The prefix argument ARG is passed to `org-insert-heading'. +Unlike `org-insert-heading', when point is at the beginning of a +heading, still insert the new sub-heading below." (interactive "P") + (when (and (bolp) (not (eobp)) (not (eolp))) (forward-char)) (org-insert-heading arg) (cond ((org-at-heading-p) (org-do-demote)) @@ -6545,7 +6706,8 @@ Works for outline headings and for plain lists alike." (defun org-insert-todo-subheading (arg) "Insert a new subheading with TODO keyword or checkbox and demote it. -Works for outline headings and for plain lists alike." +Works for outline headings and for plain lists alike. +The prefix argument ARG is passed to `org-insert-todo-heading'." (interactive "P") (org-insert-todo-heading arg) (cond @@ -6591,7 +6753,8 @@ headings in the region." (interactive) (save-excursion (if (org-region-active-p) - (org-map-region 'org-promote (region-beginning) (region-end)) + (let ((deactivate-mark nil)) + (org-map-region 'org-promote (region-beginning) (region-end))) (org-promote))) (org-fix-position-after-promote)) @@ -6602,7 +6765,8 @@ headings in the region." (interactive) (save-excursion (if (org-region-active-p) - (org-map-region 'org-demote (region-beginning) (region-end)) + (let ((deactivate-mark nil)) + (org-map-region 'org-demote (region-beginning) (region-end))) (org-demote))) (org-fix-position-after-promote)) @@ -6610,7 +6774,7 @@ headings in the region." "Fix cursor position and indentation after demoting/promoting." (let ((pos (point))) (when (save-excursion - (beginning-of-line) + (forward-line 0) (let ((case-fold-search nil)) (looking-at org-todo-line-regexp)) (or (eq pos (match-end 1)) (eq pos (match-end 2)))) (cond ((eobp) (insert " ")) @@ -6621,7 +6785,7 @@ headings in the region." "Return the level of the current entry, or nil if before the first headline. The level is the number of stars at the beginning of the headline. Use `org-reduced-level' to remove the effect of -`org-odd-levels'. Unlike to `org-outline-level', this function +`org-odd-levels-only'. Unlike `org-outline-level', this function ignores inlinetasks." (let ((level (org-with-limited-levels (org-outline-level)))) (and (> level 0) level))) @@ -6632,7 +6796,7 @@ Returns 0 for the first headline in the buffer, and nil if before the first headline." (and (org-current-level) (or (and (/= (line-beginning-position) (point-min)) - (save-excursion (beginning-of-line 0) (org-current-level))) + (save-excursion (forward-line -1) (org-current-level))) 0))) (defun org-reduced-level (l) @@ -6702,7 +6866,9 @@ This goes first to child, then to parent, level, then up the hierarchy. After top level, it switches back to sibling level." (interactive) (let ((org-adapt-indentation nil)) - (when (org-point-at-end-of-empty-headline) + (when (and (org-point-at-end-of-empty-headline) + (not (and (featurep 'org-inlinetask) + (org-inlinetask-in-task-p)))) (setq this-command 'org-cycle-level) ; Only needed for caching (let ((cur-level (org-current-level)) (prev-level (org-get-previous-line-level))) @@ -6822,8 +6988,8 @@ Assume point is at a heading or an inlinetask beginning." ((looking-at-p "[ \t]*$") (forward-line)) ((and (looking-at-p org-footnote-definition-re) (let ((e (org-element-at-point))) - (and (eq (org-element-type e) 'footnote-definition) - (goto-char (org-element-property :end e)))))) + (and (org-element-type-p e 'footnote-definition) + (goto-char (org-element-end e)))))) ((looking-at-p org-outline-regexp) (forward-line)) ;; Give up if shifting would move before column 0 or ;; if it would introduce a headline or a footnote @@ -6837,17 +7003,14 @@ Assume point is at a heading or an inlinetask beginning." ;; Ignore contents of example blocks and source ;; blocks if their indentation is meant to be ;; preserved. Jump to block's closing line. - (beginning-of-line) + (forward-line 0) (or (and (looking-at-p "[ \t]*#\\+BEGIN_\\(EXAMPLE\\|SRC\\)") (let ((e (org-element-at-point))) - (and (memq (org-element-type e) - '(example-block src-block)) - (or org-src-preserve-indentation - (org-element-property :preserve-indent e)) - (goto-char (org-element-property :end e)) - (progn (skip-chars-backward " \r\t\n") - (beginning-of-line) - t)))) + (and (org-src-preserve-indentation-p e) + (goto-char (org-element-end e)) + (progn (skip-chars-backward " \r\t\n") + (forward-line 0) + t)))) (forward-line)))))))) ;; Shift lines but footnote definitions, inlinetasks boundaries ;; by DIFF. Also skip contents of source or example blocks @@ -6856,22 +7019,19 @@ Assume point is at a heading or an inlinetask beginning." (cond ((and (looking-at-p org-footnote-definition-re) (let ((e (org-element-at-point))) - (and (eq (org-element-type e) 'footnote-definition) - (goto-char (org-element-property :end e)))))) + (and (org-element-type-p e 'footnote-definition) + (goto-char (org-element-end e)))))) ((looking-at-p org-outline-regexp) (forward-line)) ((looking-at-p "[ \t]*$") (forward-line)) (t (indent-line-to (+ (current-indentation) diff)) - (beginning-of-line) + (forward-line 0) (or (and (looking-at-p "[ \t]*#\\+BEGIN_\\(EXAMPLE\\|SRC\\)") (let ((e (org-element-at-point))) - (and (memq (org-element-type e) - '(example-block src-block)) - (or org-src-preserve-indentation - (org-element-property :preserve-indent e)) - (goto-char (org-element-property :end e)) + (and (org-src-preserve-indentation-p e) + (goto-char (org-element-end e)) (progn (skip-chars-backward " \r\t\n") - (beginning-of-line) + (forward-line 0) t)))) (forward-line))))))))) @@ -7044,6 +7204,9 @@ useful if the caller implements cut-and-paste as copy-then-paste-then-cut." (if (called-interactively-p 'any) (org-back-to-heading nil) ; take what looks like a subtree (org-back-to-heading t)) ; take what is really there + ;; Do not consider inlinetasks as a subtree. + (when (org-element-type-p (org-element-at-point) 'inlinetask) + (org-up-element)) (setq beg (point)) (skip-chars-forward " \t\r\n") (save-match-data @@ -7077,7 +7240,13 @@ The entire subtree is promoted or demoted in order to match a new headline level. If the cursor is at the beginning of a headline, the same level as -that headline is used to paste the tree. +that headline is used to paste the tree before current headline. + +With `\\[universal-argument]' prefix, force inserting at the same level +as current headline, after subtree at point. + +With `\\[universal-argument]' `\\[universal-argument]' prefix, force +inserting as a child headline, as the first child. If not, the new level is derived from the *visible* headings before and after the insertion point, and taken to be the inferior headline @@ -7110,25 +7279,33 @@ When REMOVE is non-nil, remove the subtree from the clipboard." (old-level (if (string-match org-outline-regexp-bol txt) (- (match-end 0) (match-beginning 0) 1) -1)) + level-indicator? (force-level (cond - (level (prefix-numeric-value level)) ;; When point is after the stars in an otherwise empty ;; headline, use the number of stars as the forced level. - ((and (org-match-line "^\\*+[ \t]*$") + ((and (or (not level) (member level '((4) (16)))) + (org-match-line "^\\*+[ \t]*$") (not (eq ?* (char-after)))) - (org-outline-level)) + (setq level-indicator? (org-outline-level))) + ((equal level '(4)) (org-outline-level)) + ((equal level '(16)) nil) ; handle later + (level (prefix-numeric-value level)) ((looking-at-p org-outline-regexp-bol) (org-outline-level)))) (previous-level (save-excursion - (org-previous-visible-heading 1) + (unless (org-at-heading-p) (org-previous-visible-heading 1)) (if (org-at-heading-p) (org-outline-level) 1))) (next-level (save-excursion - (if (org-at-heading-p) (org-outline-level) - (org-next-visible-heading 1) - (if (org-at-heading-p) (org-outline-level) 1)))) - (new-level (or force-level (max previous-level next-level))) + (org-next-visible-heading 1) + (if (org-at-heading-p) (org-outline-level) 1))) + (new-level (or force-level + (max + ;; C-u C-u forces child. + (if (equal level '(16)) (1+ previous-level) 0) + previous-level + next-level))) (shift (if (or (= old-level -1) (= new-level -1) (= old-level new-level)) @@ -7139,11 +7316,12 @@ When REMOVE is non-nil, remove the subtree from the clipboard." (org-odd-levels-only nil) beg end newend) ;; Remove the forced level indicator. - (when (and force-level (not level)) - (delete-region (line-beginning-position) (point))) + (when level-indicator? + (delete-region (line-beginning-position) (line-beginning-position 2))) ;; Paste before the next visible heading or at end of buffer, ;; unless point is at the beginning of a headline. - (unless (and (bolp) (org-at-heading-p)) + (unless (and (bolp) (org-at-heading-p) (not (member level '((4) (16))))) + (when (equal level '(4)) (org-end-of-subtree t)) (org-next-visible-heading 1) (unless (bolp) (insert "\n"))) (setq beg (point)) @@ -7210,6 +7388,7 @@ If optional TXT is given, check this string instead of the current kill." Those markers are stored together with their positions relative to the start of the region.") +(defvar org-log-note-marker) ; defined later (defun org-save-markers-in-region (beg end) "Check markers in region. If these markers are between BEG and END, record their position relative @@ -7219,6 +7398,7 @@ This function gets called just before an entry or tree gets cut from the buffer. After re-insertion, `org-reinstall-markers-in-region' must be called immediately, to move the markers with the entries." (setq org-markers-to-move nil) + (org-check-and-save-marker org-log-note-marker beg end) (when (featurep 'org-clock) (org-clock-save-markers-for-cut-and-paste beg end)) (when (featurep 'org-agenda) @@ -7240,29 +7420,32 @@ If yes, remember the marker and the distance to BEG." (setq org-markers-to-move nil)) (defun org-narrow-to-subtree (&optional element) - "Narrow buffer to the current subtree." + "Narrow buffer to the current subtree. +Use the command `\\[widen]' to see the whole buffer again. +With optional argument ELEMENT narrow to subtree around ELEMENT." (interactive) - (if (org-element--cache-active-p) - (let* ((heading (org-element-lineage - (or element (org-element-at-point)) - '(headline) t)) - (end (org-element-property :end heading))) - (if (and heading end) - (narrow-to-region (org-element-property :begin heading) - (if (= end (point-max)) - end (1- end))) - (signal 'outline-before-first-heading nil))) - (save-excursion - (save-match-data - (org-with-limited-levels - (narrow-to-region - (progn (org-back-to-heading t) (point)) - (progn (org-end-of-subtree t t) - (when (and (org-at-heading-p) (not (eobp))) (backward-char 1)) - (point)))))))) + (let* ((heading + (org-element-lineage + (or element (org-element-at-point)) + 'headline 'with-self)) + (begin (org-element-begin heading)) + (end (org-element-end heading))) + (if (and heading end + ;; Preserve historical behavior throwing an error when + ;; current heading starts before active narrowing. + (<= (point-min) begin)) + (narrow-to-region + begin + ;; Preserve historical behavior not extending the active + ;; narrowing when the subtree extends beyond it. + (min (point-max) + (if (= end (point-max)) + end (1- end)))) + (signal 'outline-before-first-heading nil)))) (defun org-toggle-narrow-to-subtree () - "Narrow to the subtree at point or widen a narrowed buffer." + "Narrow to the subtree at point or widen a narrowed buffer. +Use the command `\\[widen]' to see the whole buffer again." (interactive) (if (buffer-narrowed-p) (progn (widen) (message "Buffer widen")) @@ -7270,13 +7453,13 @@ If yes, remember the marker and the distance to BEG." (message "Buffer narrowed to current subtree"))) (defun org-narrow-to-block () - "Narrow buffer to the current block." + "Narrow buffer to the current block. +Use the command `\\[widen]' to see the whole buffer again." (interactive) (let* ((case-fold-search t) - (blockp (org-between-regexps-p "^[ \t]*#\\+begin_.*" - "^[ \t]*#\\+end_.*"))) - (if blockp - (narrow-to-region (car blockp) (cdr blockp)) + (element (org-element-at-point))) + (if (string-match-p "block" (symbol-name (org-element-type element))) + (org-narrow-to-element) (user-error "Not in a block")))) (defun org-clone-subtree-with-time-shift (n &optional shift) @@ -7420,6 +7603,8 @@ Assume buffer is widened and point is on a headline." (replace-regexp-in-string "\\[[0-9]+%\\]\\|\\[[0-9]+/[0-9]+\\]" "" (match-string-no-properties 4)))))))) + (when (org-element-property :commentedp (org-element-at-point)) + (setq heading (replace-regexp-in-string (format "^%s[ \t]*" org-comment-string) "" heading))) (if (org-up-heading-safe) (let ((path (cons heading (org--get-outline-path-1 use-cache)))) (when use-cache @@ -7565,7 +7750,7 @@ Assume S may contain only objects." (let ((new (org-element-property :value o))) (org-element-insert-before new o) (org-element-put-property - new :post-blank (org-element-property :post-blank o)))) + new :post-blank (org-element-post-blank o)))) ;; Non-terminal objects. Splice contents. (type (let ((contents @@ -7577,8 +7762,8 @@ Assume S may contain only objects." (setq c (pop contents)) (org-element-insert-before c o)) (org-element-put-property - c :post-blank (org-element-property :post-blank o))))) - (org-element-extract-element o))) + c :post-blank (org-element-post-blank o))))) + (org-element-extract o))) ;; Return modified tree. tree))) @@ -7641,12 +7826,24 @@ function is being called interactively." ;; Find beginning and end of region to sort (cond ((org-region-active-p) + (setq start (region-beginning) + end (region-end)) ;; we will sort the region - (setq end (region-end) + ;; Limit the region to full headings. + (goto-char start) + ;; Move to beginning of heading. + ;; If we are inside heading, move to next. + ;; If we are on heading, move to its begin position. + (if (org-at-heading-p) + (forward-line 0) + (outline-next-heading)) + (setq start (point)) + ;; Extend region end beyond the last subtree. + (goto-char end) + (org-end-of-subtree nil t) + (setq end (point) what "region") - (goto-char (region-beginning)) - (unless (org-at-heading-p) (outline-next-heading)) - (setq start (point))) + (goto-char start)) ((or (org-at-heading-p) (ignore-errors (progn (org-back-to-heading) t))) ;; we will sort the children of the current headline @@ -7667,7 +7864,7 @@ function is being called interactively." (or (org-at-heading-p) (outline-next-heading)) (setq start (point)) (goto-char (point-max)) - (beginning-of-line 1) + (forward-line 0) (when (looking-at ".*?\\S-") ;; File ends in a non-white line (end-of-line 1) @@ -7717,6 +7914,12 @@ function is being called interactively." (save-restriction (narrow-to-region start end) + ;; No trailing newline - add one to avoid + ;; * heading + ;; text* another heading + (save-excursion + (goto-char end) + (unless (bolp) (insert "\n"))) (let ((restore-clock? ;; The clock marker is lost when using `sort-subr'; mark ;; the clock with temporary `:org-clock-marker-backup' @@ -7803,7 +8006,7 @@ function is being called interactively." (t (error "Invalid sorting type `%c'" sorting-type)))) nil (cond - ((= dcst ?a) 'string-collate-lessp) + ((= dcst ?a) #'org-string<) ((= dcst ?f) (or compare-func (and interactive? @@ -7922,20 +8125,15 @@ call CMD." (cl-progv vars vals (call-interactively cmd)))) -(defun org-get-category (&optional pos force-refresh) - "Get the category applying to position POS." - (save-match-data - (when force-refresh (org-refresh-category-properties)) - (let ((pos (or pos (point)))) - (if (org-element--cache-active-p) - ;; Sync cache. - (org-with-point-at (org-element-property :begin (org-element-at-point pos)) - (or (org-entry-get-with-inheritance "CATEGORY") - "???")) - (or (get-text-property pos 'org-category) - (progn - (org-refresh-category-properties) - (get-text-property pos 'org-category))))))) +(defun org-get-category (&optional pos _) + "Get the category applying to position POS. +Return \"???\" when no category is set. + +This function may modify the match data." + ;; Sync cache. + (or (org-entry-get-with-inheritance + "CATEGORY" nil (or pos (point))) + "???")) ;;; Refresh properties @@ -7992,49 +8190,48 @@ the whole buffer." (defun org-refresh-category-properties () "Refresh category text properties in the buffer." - (unless (org-element--cache-active-p) - (let ((case-fold-search t) - (inhibit-read-only t) - (default-category - (cond ((null org-category) - (if buffer-file-name - (file-name-sans-extension - (file-name-nondirectory buffer-file-name)) - "???")) - ((symbolp org-category) (symbol-name org-category)) - (t org-category)))) - (let ((category (catch 'buffer-category - (org-with-wide-buffer - (goto-char (point-max)) - (while (re-search-backward "^[ \t]*#\\+CATEGORY:" (point-min) t) - (let ((element (org-element-at-point-no-context))) - (when (eq (org-element-type element) 'keyword) - (throw 'buffer-category - (org-element-property :value element)))))) - default-category))) - (with-silent-modifications - (org-with-wide-buffer - ;; Set buffer-wide property from keyword. Search last #+CATEGORY - ;; keyword. If none is found, fall-back to `org-category' or - ;; buffer file name, or set it by the document property drawer. - (put-text-property (point-min) (point-max) - 'org-category category) - ;; Set categories from the document property drawer or - ;; property drawers in the outline. If category is found in - ;; the property drawer for the whole buffer that value - ;; overrides the keyword-based value set above. - (goto-char (point-min)) - (let ((regexp (org-re-property "CATEGORY"))) - (while (re-search-forward regexp nil t) - (let ((value (match-string-no-properties 3))) - (when (org-at-property-p) - (put-text-property - (save-excursion (org-back-to-heading-or-point-min t)) - (save-excursion (if (org-before-first-heading-p) - (point-max) - (org-end-of-subtree t t))) - 'org-category - value))))))))))) + (let ((case-fold-search t) + (inhibit-read-only t) + (default-category + (cond ((null org-category) + (if buffer-file-name + (file-name-sans-extension + (file-name-nondirectory buffer-file-name)) + "???")) + ((symbolp org-category) (symbol-name org-category)) + (t org-category)))) + (let ((category (catch 'buffer-category + (org-with-wide-buffer + (goto-char (point-max)) + (while (re-search-backward "^[ \t]*#\\+CATEGORY:" (point-min) t) + (let ((element (org-element-at-point-no-context))) + (when (org-element-type-p element 'keyword) + (throw 'buffer-category + (org-element-property :value element)))))) + default-category))) + (with-silent-modifications + (org-with-wide-buffer + ;; Set buffer-wide property from keyword. Search last #+CATEGORY + ;; keyword. If none is found, fall-back to `org-category' or + ;; buffer file name, or set it by the document property drawer. + (put-text-property (point-min) (point-max) + 'org-category category) + ;; Set categories from the document property drawer or + ;; property drawers in the outline. If category is found in + ;; the property drawer for the whole buffer that value + ;; overrides the keyword-based value set above. + (goto-char (point-min)) + (let ((regexp (org-re-property "CATEGORY"))) + (while (re-search-forward regexp nil t) + (let ((value (match-string-no-properties 3))) + (when (org-at-property-p) + (put-text-property + (save-excursion (org-back-to-heading-or-point-min t)) + (save-excursion (if (org-before-first-heading-p) + (point-max) + (org-end-of-subtree t t))) + 'org-category + value)))))))))) (defun org-refresh-stats-properties () "Refresh stats text properties in the buffer." @@ -8072,7 +8269,23 @@ See the docstring of `org-open-file' for details." (mouse-set-point ev) (when (eq major-mode 'org-agenda-mode) (org-agenda-copy-local-variable 'org-link-abbrev-alist-local)) - (org-open-at-point)) + ;; FIXME: This feature is actually unreliable - if we are in non-Org + ;; buffer and the link happens to be inside what Org parser + ;; recognizes as verbarim (for exampe, src block), + ;; `org-open-at-point' will do nothing. + ;; We might have used `org-open-at-point-global' instead, but it is + ;; not exactly the same. For example, it will have no way to open + ;; link abbreviations. So, suppressing parser complains about + ;; non-Org buffer to keep the feature working at least to the extent + ;; it did before. + (require 'warnings) ; Emacs <30 + (defvar warning-suppress-types) ; warnings.el + (let ((warning-suppress-types + (cons '(org-element org-element-parser) + warning-suppress-types))) + ;; FIXME: Suppress warning in Emacs <30 + ;; (ignore warning-suppress-types) + (org-open-at-point))) (defvar org-window-config-before-follow-link nil "The window configuration before following a link. @@ -8314,7 +8527,7 @@ If the file does not exist, throw an error." ;; Save position before error-ing out so user ;; can easily move back to the original buffer. (error (funcall save-position-maybe) - (error (nth 1 err))))))) + (error "%s" (error-message-string err))))))) ((functionp cmd) (save-match-data (set-match-data link-match-data) @@ -8338,16 +8551,25 @@ If the file does not exist, throw an error." ;;;###autoload (defun org-open-at-point-global () - "Follow a link or a time-stamp like Org mode does. + "Follow a link or a timestamp like Org mode does. Also follow links and emails as seen by `thing-at-point'. This command can be called in any mode to follow an external -link or a time-stamp that has Org mode syntax. Its behavior +link or a timestamp that has Org mode syntax. Its behavior is undefined when called on internal links like fuzzy links. Raise a user error when there is nothing to follow." (interactive) (let ((tap-url (thing-at-point 'url)) (tap-email (thing-at-point 'email))) - (cond ((org-in-regexp org-link-any-re) + (cond ((org-in-regexp + org-link-any-re + (let ((origin (point))) + (max + (save-excursion + (backward-paragraph) + (count-lines (point) origin)) + (save-excursion + (forward-paragraph) + (count-lines origin (point)))))) (org-link-open-from-string (match-string-no-properties 0))) ((or (org-in-regexp org-ts-regexp-both nil t) (org-in-regexp org-tsr-regexp-both nil t)) @@ -8369,11 +8591,11 @@ they must return nil.") The thing can be a link, citation, timestamp, footnote, src-block or tags. -When point is on a link, follow it. Normally, files will be -opened by an appropriate application. If the optional prefix -argument ARG is non-nil, Emacs will visit the file. With -a double prefix argument, try to open outside of Emacs, in the -application the system uses for this file type. +When point is on a link, follow it. Normally, files will be opened by +an appropriate application (see `org-file-apps'). If the optional prefix +argument ARG is non-nil, Emacs will visit the file. With a double +prefix argument, try to open outside of Emacs, in the application the +system uses for this file type. When point is on a timestamp, open the agenda at the day specified. @@ -8391,7 +8613,7 @@ entry, so it is possible to pick one, or all, of them. If point is on a tag, call `org-tags-view' instead. On top of syntactically correct links, this function also tries -to open links and time-stamps in comments, node properties, and +to open links and timestamps in comments, node properties, and keywords if point is on something looking like a timestamp or a link." (interactive "P") @@ -8441,13 +8663,20 @@ a link." (org-attach-reveal-in-emacs) (org-attach-reveal)))) (`(,links . ,links-end) - (dolist (link (if (stringp links) (list links) links)) - (search-forward link nil links-end) - (goto-char (match-beginning 0)) - ;; When opening file link, current buffer may be - ;; altered. - (save-current-buffer - (org-open-at-point arg)))))))) + (let ((link-marker (make-marker)) + (last-moved-marker (point-marker))) + (dolist (link (if (stringp links) (list links) links)) + (search-forward link nil links-end) + (goto-char (match-beginning 0)) + (move-marker link-marker (point)) + (save-excursion + (org-open-at-point arg) + (unless (equal (point-marker) link-marker) + (move-marker last-moved-marker (point-marker))))) + ;; If any of the links moved point in current buffer, + ;; move to the point corresponding to such latest link. + ;; Otherwise, restore the original point position. + (goto-char last-moved-marker))))))) ;; On a footnote reference or at definition's label. ((or (eq type 'footnote-reference) (and (eq type 'footnote-definition) @@ -8457,9 +8686,9 @@ a link." ;; to be on par with behavior on links. (skip-chars-forward " \t") (let ((begin - (org-element-property :contents-begin context))) + (org-element-contents-begin context))) (if begin (< (point) begin) - (= (org-element-property :post-affiliated context) + (= (org-element-post-affiliated context) (line-beginning-position))))))) (org-footnote-action)) ;; On a planning line. Check if we are really on a timestamp. @@ -8470,14 +8699,14 @@ a link." ;; before opening it. ((and (eq type 'clock) value - (>= (point) (org-element-property :begin value)) - (<= (point) (org-element-property :end value))) + (>= (point) (org-element-begin value)) + (<= (point) (org-element-end value))) (org-follow-timestamp-link)) ((eq type 'src-block) (org-babel-open-src-block-result)) ;; Do nothing on white spaces after an object. ((>= (point) (save-excursion - (goto-char (org-element-property :end context)) + (goto-char (org-element-end context)) (skip-chars-backward " \t") (point))) (user-error "No link found")) @@ -8509,7 +8738,9 @@ there is one, return it." (while (re-search-forward org-link-any-re end t) ;; Only consider valid links or links openable via ;; `org-open-at-point'. - (when (memq (org-element-type (org-element-context)) '(link comment comment-block node-property keyword)) + (when (org-element-type-p + (save-match-data (org-element-context)) + '(link comment comment-block node-property keyword)) (push (match-string 0) links))) (setq links (org-uniquify (reverse links)))) (cond @@ -8522,7 +8753,12 @@ there is one, return it." (t ; we have to select a link (save-excursion (save-window-excursion - (delete-other-windows) + ;; We have no direct control over how + ;; `with-output-to-temp-buffer' displays the buffer. Try + ;; to gain more space, making sure that only the Org + ;; buffer and the *Select link* buffer are displayed for + ;; the duration of selection. + (ignore-errors (delete-other-windows)) (with-output-to-temp-buffer "*Select Link*" (dolist (l links) (cond @@ -8536,8 +8772,10 @@ there is one, return it." (match-string 1 l))))))) (org-fit-window-to-buffer (get-buffer-window "*Select Link*")) (message "Select link to open, RET to open all:") - (setq c (read-char-exclusive)) - (and (get-buffer "*Select Link*") (kill-buffer "*Select Link*")))) + (unwind-protect (setq c (read-char-exclusive)) + (and (get-buffer-window "*Select Link*" t) + (quit-window 'kill (get-buffer-window "*Select Link*" t))) + (and (get-buffer "*Select Link*") (kill-buffer "*Select Link*"))))) (when (equal c ?q) (user-error "Abort")) (if (equal c ?\C-m) (setq link links) @@ -8548,6 +8786,17 @@ there is one, return it." (setq link (nth (1- nth) links))))) (cons link end))))) +(defun org--link-at-point () + "`thing-at-point' provider function." + (org-element-property :raw-link (org-element-context))) + +(defun org--bounds-of-link-at-point () + "`bounds-of-thing-at-point' provider function." + (let ((context (org-element-context))) + (when (eq (org-element-type context) 'link) + (cons (org-element-begin context) + (org-element-end context))))) + ;;; File search (defun org-do-occur (regexp &optional cleanup) @@ -8624,7 +8873,7 @@ or to another Org file, automatically push the old position onto the ring." (defvar org-agenda-start-on-weekday) (defvar org-agenda-buffer-name) (defun org-follow-timestamp-link () - "Open an agenda view for the time-stamp date/range at point." + "Open an agenda view for the timestamp date/range at point." (require 'org-agenda) ;; Avoid changing the global value. (let ((org-agenda-buffer-name org-agenda-buffer-name)) @@ -8668,12 +8917,12 @@ or to another Org file, automatically push the old position onto the ring." "Check if the current file should receive notes in reversed order." (cond ((not org-reverse-note-order) nil) - ((eq t org-reverse-note-order) t) - ((not (listp org-reverse-note-order)) nil) - (t (catch 'exit + ((listp org-reverse-note-order) + (catch 'exit (dolist (entry org-reverse-note-order) (when (string-match (car entry) buffer-file-name) - (throw 'exit (cdr entry)))))))) + (throw 'exit (cdr entry)))))) + (t org-reverse-note-order))) (defvar org-agenda-new-buffers nil "Buffers created to visit agenda files.") @@ -8697,7 +8946,7 @@ If not found, stay at current position and return nil." "Create a dynamic block section, with parameters taken from PLIST. PLIST must contain a :name entry which is used as the name of the block." (when (string-match "\\S-" (buffer-substring (line-beginning-position) - (line-end-position))) + (line-end-position))) (end-of-line 1) (newline)) (let ((col (current-column)) @@ -8708,7 +8957,7 @@ PLIST must contain a :name entry which is used as the name of the block." (setq plist (cddr plist)) (insert " " (prin1-to-string (pop plist))))) (insert "\n\n" (make-string col ?\ ) "#+END:\n") - (beginning-of-line -2))) + (forward-line -3))) (defun org-prepare-dblock () "Prepare dynamic block for refresh. @@ -8721,7 +8970,7 @@ the property list including an extra property :name with the block name." (params (append (list :name name) (read (concat "(" (match-string 3) ")"))))) (save-excursion - (beginning-of-line 1) + (forward-line 0) (skip-chars-forward " \t") (setq params (plist-put params :indentation-column (current-column)))) (unless (re-search-forward org-dblock-end-re nil t) @@ -8744,7 +8993,7 @@ If COMMAND is not given, use `org-update-dblock'." (while (re-search-forward org-dblock-start-re nil t) (goto-char (match-beginning 0)) (save-excursion - (condition-case nil + (condition-case-unless-debug nil (funcall cmd) (error (message "Error during update of dynamic block")))) (unless (re-search-forward org-dblock-end-re nil t) @@ -8771,7 +9020,7 @@ TYPE is the dynamic block type, as a string." (defun org-dynamic-block-define (type func) "Define dynamic block TYPE with FUNC. TYPE is a string. FUNC is the function creating the dynamic -block of such type." +block of such type. FUNC must be able to accept zero arguments." (pcase (assoc type org-dynamic-block-alist) (`nil (push (cons type func) org-dynamic-block-alist)) (def (setcdr def func)))) @@ -8787,7 +9036,7 @@ is non-nil, call the dynamic block function interactively." (pcase (org-dynamic-block-function type) (`nil (error "No such dynamic block: %S" type)) ((and f (pred functionp)) - (if interactive-p (call-interactively f) (funcall f))) + (if (and interactive-p (commandp f)) (call-interactively f) (funcall f))) (_ (error "Invalid function for dynamic block %S" type)))) (defun org-dblock-update (&optional arg) @@ -8810,7 +9059,9 @@ the correct writing function." (let* ((win (selected-window)) (pos (point)) (line (org-current-line)) - (params (org-prepare-dblock)) + (params + ;; Called for side effect. + (org-prepare-dblock)) (name (plist-get params :name)) (indent (plist-get params :indentation-column)) (cmd (intern (concat "org-dblock-write:" name)))) @@ -8826,7 +9077,7 @@ the correct writing function." (forward-line 1) (while (not (looking-at org-dblock-end-re)) (insert indent) - (beginning-of-line 2)) + (forward-line 1)) (when (looking-at org-dblock-end-re) (and (looking-at "[ \t]+") (replace-match "")) @@ -8860,22 +9111,24 @@ This function can be used in a hook." (defun org-get-export-keywords () "Return a list of all currently understood export keywords. Export keywords include options, block names, attributes and -keywords relative to each registered export back-end." +keywords relative to each registered export backend." (let (keywords) (dolist (backend (bound-and-true-p org-export-registered-backends) (delq nil keywords)) - ;; Back-end name (for keywords, like #+LATEX:) + ;; Backend name (for keywords, like #+LATEX:) (push (upcase (symbol-name (org-export-backend-name backend))) keywords) + ;; Backend attributes, like #+ATTR_LATEX: + (push (format "ATTR_%s" (upcase (symbol-name (org-export-backend-name backend)))) keywords) (dolist (option-entry (org-export-backend-options backend)) - ;; Back-end options. + ;; Backend options. (push (nth 1 option-entry) keywords))))) (defconst org-options-keywords '("ARCHIVE:" "AUTHOR:" "BIBLIOGRAPHY:" "BIND:" "CATEGORY:" "CITE_EXPORT:" "COLUMNS:" "CREATOR:" "DATE:" "DESCRIPTION:" "DRAWERS:" "EMAIL:" "EXCLUDE_TAGS:" "FILETAGS:" "INCLUDE:" "INDEX:" "KEYWORDS:" "LANGUAGE:" - "MACRO:" "OPTIONS:" "PROPERTY:" "PRINT_BIBLIOGRAPHY" "PRIORITIES:" + "MACRO:" "OPTIONS:" "PROPERTY:" "PRINT_BIBLIOGRAPHY:" "PRIORITIES:" "SELECT_TAGS:" "SEQ_TODO:" "SETUPFILE:" "STARTUP:" "TAGS:" "TITLE:" "TODO:" "TYP_TODO:" "SELECT_TAGS:" "EXCLUDE_TAGS:" "EXPORT_FILE_NAME:")) @@ -9032,8 +9285,13 @@ block. When foo is written as FOO, upcase the #+BEGIN/END as well." (interactive (list (pcase (org--insert-structure-template-mks) - (`("\t" . ,_) (read-string "Structure type: ")) + (`("\t" . ,_) + (let ((type (read-string "Structure type: "))) + (when (string-empty-p type) (user-error "Empty structure type")) + type)) (`(,_ ,choice . ,_) choice)))) + (when (or (not (stringp type)) (string-empty-p type)) + (error "Invalid structure type: %S" type)) (let* ((case-fold-search t) ; Make sure that matches are case-insensitive. (region? (use-region-p)) (region-start (and region? (region-beginning))) @@ -9048,7 +9306,7 @@ When foo is written as FOO, upcase the #+BEGIN/END as well." (when region? (goto-char region-start)) (let ((column (current-indentation))) (if (save-excursion (skip-chars-backward " \t") (bolp)) - (beginning-of-line) + (forward-line 0) (insert "\n")) (save-excursion (indent-to column) @@ -9328,7 +9586,7 @@ When called through ELisp, arg is also interpreted in the following way: (unless (org-invisible-p (line-beginning-position)) (org-fold-region (line-beginning-position) (line-end-position) - nil))) + nil 'outline))) (cond ((and org-state (equal this org-state)) (message "TODO state was already %s" (org-trim next))) ((not (pos-visible-in-window-p hl-pos)) @@ -9398,8 +9656,9 @@ When called through ELisp, arg is also interpreted in the following way: ;; Fixup cursor location if close to the keyword. (when (and (outline-on-heading-p) (not (bolp)) - (save-excursion (beginning-of-line 1) - (looking-at org-todo-line-regexp)) + (save-excursion + (forward-line 0) + (looking-at org-todo-line-regexp)) (< (point) (+ 2 (or (match-end 2) (match-end 1))))) (goto-char (or (match-end 2) (match-end 1))) (and (looking-at " ") @@ -9588,15 +9847,15 @@ all statistics cookies in the buffer." (re-search-forward "^[ \t]*\\([-+*]\\|[0-9]+[.)]\\) \\[[- X]\\]" end t)) (not (save-excursion - (re-search-forward - ":COOKIE_DATA:.*\\" end t)))) + (re-search-forward + ":COOKIE_DATA:.*\\" end t)))) (org-update-checkbox-count) (if (and l2 (> l2 l1)) (progn (goto-char end) (org-update-parent-todo-statistics)) (goto-char pos) - (beginning-of-line 1) + (forward-line 0) (while (re-search-forward "\\(\\(\\[[0-9]*%\\]\\)\\|\\(\\[[0-9]*/[0-9]*\\]\\)\\)" (line-end-position) t) @@ -9624,7 +9883,7 @@ statistics everywhere." checkbox-beg cookie-present) (catch 'exit (save-excursion - (beginning-of-line 1) + (forward-line 0) (setq ltoggle (funcall outline-level)) ;; Three situations are to consider: @@ -9649,49 +9908,58 @@ statistics everywhere." (while (re-search-forward box-re (line-end-position) t) (setq cnt-all 0 cnt-done 0 cookie-present t) (setq is-percent (match-end 2) checkbox-beg (match-beginning 0)) - (save-match-data - (unless (outline-next-heading) (throw 'exit nil)) - (while (and (looking-at org-complex-heading-regexp) - (> (setq l1 (length (match-string 1))) level)) - (setq kwd (and (or recursive (= l1 ltoggle)) - (match-string 2))) - (if (or (eq org-provide-todo-statistics 'all-headlines) - (and (eq org-provide-todo-statistics t) - (or (member kwd org-done-keywords))) - (and (listp org-provide-todo-statistics) - (stringp (car org-provide-todo-statistics)) - (or (member kwd org-provide-todo-statistics) - (member kwd org-done-keywords))) - (and (listp org-provide-todo-statistics) - (listp (car org-provide-todo-statistics)) - (or (member kwd (car org-provide-todo-statistics)) - (and (member kwd org-done-keywords) - (member kwd (cadr org-provide-todo-statistics)))))) - (setq cnt-all (1+ cnt-all)) - (and (eq org-provide-todo-statistics t) - kwd - (setq cnt-all (1+ cnt-all)))) - (when (or (and (member org-provide-todo-statistics '(t all-headlines)) - (member kwd org-done-keywords)) + (when (org-element-type-p + (save-excursion + (goto-char checkbox-beg) + (save-match-data (org-element-context))) + '(statistics-cookie + ;; Special case - statistics cookie inside properties. + keyword)) + (save-match-data + (unless (outline-next-heading) (throw 'exit nil)) + (while (and (looking-at org-complex-heading-regexp) + (> (setq l1 (length (match-string 1))) level)) + (setq kwd (and (or recursive (= l1 ltoggle)) + (match-string 2))) + (if (or (eq org-provide-todo-statistics 'all-headlines) + (and (eq org-provide-todo-statistics t) + (or (member kwd org-done-keywords))) + (and (listp org-provide-todo-statistics) + (stringp (car org-provide-todo-statistics)) + (or (member kwd org-provide-todo-statistics) + (member kwd org-done-keywords))) (and (listp org-provide-todo-statistics) (listp (car org-provide-todo-statistics)) - (member kwd org-done-keywords) - (member kwd (cadr org-provide-todo-statistics))) - (and (listp org-provide-todo-statistics) - (stringp (car org-provide-todo-statistics)) - (member kwd org-done-keywords))) - (setq cnt-done (1+ cnt-done))) - (outline-next-heading))) - (setq new - (if is-percent - (format "[%d%%]" (floor (* 100.0 cnt-done) - (max 1 cnt-all))) - (format "[%d/%d]" cnt-done cnt-all)) - ndel (- (match-end 0) checkbox-beg)) - (goto-char checkbox-beg) - (insert new) - (delete-region (point) (+ (point) ndel)) - (when org-auto-align-tags (org-fix-tags-on-the-fly))) + (or (member kwd (car org-provide-todo-statistics)) + (and (member kwd org-done-keywords) + (member kwd (cadr org-provide-todo-statistics)))))) + (setq cnt-all (1+ cnt-all)) + (and (eq org-provide-todo-statistics t) + kwd + (setq cnt-all (1+ cnt-all)))) + (when (or (and (member org-provide-todo-statistics '(t all-headlines)) + (member kwd org-done-keywords)) + (and (listp org-provide-todo-statistics) + (listp (car org-provide-todo-statistics)) + (member kwd org-done-keywords) + (member kwd (cadr org-provide-todo-statistics))) + (and (listp org-provide-todo-statistics) + (stringp (car org-provide-todo-statistics)) + (member kwd org-done-keywords))) + (setq cnt-done (1+ cnt-done))) + (outline-next-heading))) + (setq new + (if is-percent + (format "[%d%%]" (floor (* 100.0 cnt-done) + (max 1 cnt-all))) + (format "[%d/%d]" cnt-done cnt-all)) + ndel (- (match-end 0) checkbox-beg)) + (goto-char (match-end 0)) + (unless (string-equal new (buffer-substring checkbox-beg (match-end 0))) + (goto-char checkbox-beg) + (insert new) + (delete-region (point) (+ (point) ndel)) + (when org-auto-align-tags (org-fix-tags-on-the-fly))))) (when cookie-present (run-hook-with-args 'org-after-todo-statistics-hook cnt-done (- cnt-all cnt-done)))))) @@ -9709,7 +9977,7 @@ when there is a statistics cookie in the headline! (defun org-summary-todo (n-done n-not-done) \"Switch entry to DONE when all subentries are done, to TODO otherwise.\" - (let (org-log-done org-log-states) ; turn off logging + (let (org-log-done org-todo-log-states) ; turn off logging (org-todo (if (= n-not-done 0) \"DONE\" \"TODO\"))))") (defvar org-todo-statistics-hook nil @@ -9765,88 +10033,123 @@ right sequence." (car org-todo-keywords-1)) (t (nth 2 (assoc kwd org-todo-kwd-alist)))))) -(defun org-fast-todo-selection (&optional current-state) +(defun org-fast-todo-selection (&optional current-todo-keyword) "Fast TODO keyword selection with single keys. Returns the new TODO keyword, or nil if no state change should occur. -When CURRENT-STATE is given and selection letters are not unique globally, -prefer a state in the current sequence over on in another sequence." - (let* ((fulltable org-todo-key-alist) - (head (org-get-todo-sequence-head current-state)) - (done-keywords org-done-keywords) ;; needed for the faces. - (maxlen (apply 'max (mapcar - (lambda (x) - (if (stringp (car x)) (string-width (car x)) 0)) - fulltable))) - (expert (equal org-use-fast-todo-selection 'expert)) - (prompt "") - (fwidth (+ maxlen 3 1 3)) - (ncol (/ (- (window-width) 4) fwidth)) - tg cnt e c tbl subtable - groups ingroup in-current-sequence) + +When CURRENT-TODO-KEYWORD is given and selection letters are not +unique globally, prefer a state in the current todo keyword sequence +where CURRENT-TODO-KEYWORD belongs over on in another sequence." + (let* ((todo-alist org-todo-key-alist) ; copy from the original Org buffer. + (todo-alist-tail todo-alist) + ;; TODO keyword sequence that takes priority in case if there is binding collision. + (preferred-sequence-head (org-get-todo-sequence-head current-todo-keyword)) + in-preferred-sequence preferred-todo-alist + (done-keywords org-done-keywords) ;; needed for the faces when calling `org-get-todo-face'. + (expert-interface (equal org-use-fast-todo-selection 'expert)) + (prompt "") ; Additional expert prompt, listing todo keyword bindings. + ;; Max width occupied by a single todo record in the completion buffer. + (field-width + (+ 3 ; keep space for "[c]" binding. + 1 ; ensure that there is at least one space between adjacent todo fields. + 3 ; FIXME: likely coped from `org-fast-tag-selection' + ;; The longest todo keyword. + (apply 'max (mapcar + (lambda (x) + (if (stringp (car x)) (string-width (car x)) 0)) + org-todo-key-alist)))) + field-number ; current todo keyword column in the completion buffer. + todo-binding-spec todo-keyword todo-char input-char) + ;; Display todo selection dialog, read the user input, and return. (save-excursion (save-window-excursion - (if expert + ;; Select todo keyword list buffer, and display it unless EXPERT-INTERFACE. + (if expert-interface (set-buffer (get-buffer-create " *Org todo*")) - (delete-other-windows) - (set-window-buffer (split-window-vertically) (get-buffer-create " *Org todo*")) - (org-switch-to-buffer-other-window " *Org todo*")) + (pop-to-buffer + (get-buffer-create (get-buffer-create " *Org todo*")) + '(org-display-buffer-split (direction . down)))) + ;; Fill text in *Org todo* buffer. (erase-buffer) + ;; Copy `org-done-keywords' from the original Org buffer to be + ;; used by `org-get-todo-face'. (setq-local org-done-keywords done-keywords) - (setq tbl fulltable cnt 0) - (while (setq e (pop tbl)) - (cond - ((equal e '(:startgroup)) - (push '() groups) (setq ingroup t) - (unless (= cnt 0) - (setq cnt 0) - (insert "\n")) - (setq prompt (concat prompt "{")) - (insert "{ ")) - ((equal e '(:endgroup)) - (setq ingroup nil cnt 0 in-current-sequence nil) - (setq prompt (concat prompt "}")) - (insert "}\n")) - ((equal e '(:newline)) - (unless (= cnt 0) - (setq cnt 0) - (insert "\n") - (setq e (car tbl)) - (while (equal (car tbl) '(:newline)) - (insert "\n") - (setq tbl (cdr tbl))))) - (t - (setq tg (car e) c (cdr e)) - (if (equal tg head) (setq in-current-sequence t)) - (when ingroup (push tg (car groups))) - (when in-current-sequence (push e subtable)) - (setq tg (org-add-props tg nil 'face - (org-get-todo-face tg))) - (when (and (= cnt 0) (not ingroup)) (insert " ")) - (setq prompt (concat prompt "[" (char-to-string c) "] " tg " ")) - (insert "[" c "] " tg (make-string - (- fwidth 4 (length tg)) ?\ )) - (when (and (= (setq cnt (1+ cnt)) ncol) - ;; Avoid lines with just a closing delimiter. - (not (equal (car tbl) '(:endgroup)))) - (insert "\n") - (when ingroup (insert " ")) - (setq cnt 0))))) + ;; Show todo keyword sequences and bindings in a grid. + ;; Each todo keyword in the grid occupies FIELD-WIDTH characters. + ;; The keywords are filled up to `window-width'. + (setq field-number 0) + (while (setq todo-binding-spec (pop todo-alist-tail)) + (pcase todo-binding-spec + ;; Group keywords as { KWD1 KWD2 ... } + (`(:startgroup) + (unless (= field-number 0) + (setq field-number 0) + (insert "\n")) + (setq prompt (concat prompt "{")) + (insert "{ ")) + (`(:endgroup) + (setq field-number 0 + ;; End of a group. Reset flag indicating preferred keyword sequence. + in-preferred-sequence nil) + (setq prompt (concat prompt "}")) + (insert "}\n")) + (`(:newline) + (unless (= field-number 0) + (insert "\n") + (setq field-number 0) + (setq todo-binding-spec (car todo-alist-tail)) + (while (equal (car todo-alist-tail) '(:newline)) + (insert "\n") + (pop todo-alist-tail)))) + (_ + (setq todo-keyword (car todo-binding-spec) + todo-char (cdr todo-binding-spec)) + ;; For the first keyword in a preferred sequence, set flag. + (if (equal todo-keyword preferred-sequence-head) + (setq in-preferred-sequence t)) + ;; Store the preferred todo keyword sequence. + (when in-preferred-sequence (push todo-binding-spec preferred-todo-alist)) + ;; Assign face to the todo keyword. + (setq todo-keyword + (org-add-props + todo-keyword nil + 'face (org-get-todo-face todo-keyword))) + (when (= field-number 0) (insert " ")) + (setq prompt (concat prompt "[" (char-to-string todo-char) "] " todo-keyword " ")) + (insert "[" todo-char "] " todo-keyword + ;; Fill spaces up to FIELD-WIDTH. + (make-string + (- field-width 4 (length todo-keyword)) ?\ )) + ;; Last column in the row. + (when (and (= (setq field-number (1+ field-number)) + (/ (- (window-width) 4) field-width)) + ;; Avoid lines with just a closing delimiter. + (not (equal (car todo-alist-tail) '(:endgroup)))) + (insert "\n") + (setq field-number 0))))) (insert "\n") (goto-char (point-min)) - (unless expert (org-fit-window-to-buffer)) + (unless expert-interface (org-fit-window-to-buffer)) (message (concat "[a-z..]:Set [SPC]:clear" - (if expert (concat "\n" prompt) ""))) - (setq c (let ((inhibit-quit t)) (read-char-exclusive))) - (setq subtable (nreverse subtable)) + (if expert-interface (concat "\n" prompt) ""))) + ;; Read the todo keyword input and exit. + (setq input-char + (let ((inhibit-quit t)) ; intercept C-g. + (read-char-exclusive))) + ;; Restore the original keyword order. Previously, it was reversed using `push'. + (setq preferred-todo-alist (nreverse preferred-todo-alist)) (cond - ((or (= c ?\C-g) - (and (= c ?q) (not (rassoc c fulltable)))) - (setq quit-flag t)) - ((= c ?\ ) nil) - ((setq e (or (rassoc c subtable) (rassoc c fulltable)) - tg (car e)) - tg) - (t (setq quit-flag t))))))) + ((equal input-char ?\s) nil) + ((or (= input-char ?\C-g) + (and (= input-char ?q) (not (rassoc input-char todo-alist)))) + (signal 'quit nil)) + ((setq todo-binding-spec (or + ;; Prefer bindings from todo sequence containing CURRENT-TODO-KEYWORD. + (rassoc input-char preferred-todo-alist) + (rassoc input-char todo-alist)) + todo-keyword (car todo-binding-spec)) + todo-keyword) + (t (signal 'quit nil))))))) (defun org-entry-is-todo-p () (member (org-get-todo-state) org-not-done-keywords)) @@ -9872,7 +10175,6 @@ inactive time ranges. When this function returns a non-nil value, match data is set according to `org-tr-regexp-both' or `org-tr-regexp', depending on INACTIVE-OK." - (interactive) (save-excursion (catch 'exit (let ((pos (point))) @@ -9889,7 +10191,7 @@ on INACTIVE-OK." nil))) (defun org-get-repeat (&optional timestamp) - "Check if there is a time-stamp with repeater in this entry. + "Check if there is a timestamp with repeater in this entry. Return the repeater, as a string, or nil. Also return nil when this function is called before first heading. @@ -9919,7 +10221,7 @@ repeater from there instead." (defvar org-log-note-extra) (defvar org-log-setup nil) (defun org-auto-repeat-maybe (done-word) - "Check if the current headline contains a repeated time-stamp. + "Check if the current headline contains a repeated timestamp. If yes, set TODO state back to what it was and change the base date of repeating deadline/scheduled time stamps to new date. @@ -9969,14 +10271,14 @@ This function is run automatically after each state change to a DONE state." (or done-word (car org-done-keywords)) org-last-state org-log-repeat))) - ;; Time-stamps without a repeater are usually skipped. However, - ;; a SCHEDULED time-stamp without one is removed, as they are no + ;; Timestamps without a repeater are usually skipped. However, + ;; a SCHEDULED timestamp without one is removed, as they are no ;; longer relevant. (save-excursion (let ((scheduled (org-entry-get (point) "SCHEDULED"))) (when (and scheduled (not (string-match-p org-repeat-re scheduled))) (org-remove-timestamp-with-keyword org-scheduled-string)))) - ;; Update every time-stamp with a repeater in the entry. + ;; Update every timestamp with a repeater in the entry. (let ((planning-re (regexp-opt (list org-scheduled-string org-deadline-string)))) (while (re-search-forward org-repeat-re end t) @@ -10008,14 +10310,17 @@ This function is run automatically after each state change to a DONE state." ;; repeater is by hours. (if (equal what "h") (org-timestamp-change - (floor (- (org-time-stamp-to-now ts t)) 60) 'minute) + (floor (- (org-timestamp-to-now ts t)) 60) 'minute) (org-timestamp-change (- (org-today) (time-to-days time)) 'day))) ((equal "+" repeater-type) (let ((nshiftmax 10) (nshift 0)) (while (or (= nshift 0) - (not (time-less-p nil time))) + (if (equal what "h") + (not (time-less-p nil time)) + (>= (org-today) + (time-to-days time)))) (when (= nshiftmax (cl-incf nshift)) (or (y-or-n-p (format "%d repeater intervals were not \ @@ -10059,8 +10364,8 @@ of `org-todo-keywords-1'." (completing-read "Keyword (or KWD1|KWD2|...): " (mapcar #'list org-todo-keywords-1)))) (concat "\\(" - (mapconcat 'identity (org-split-string kwd "|") "\\|") - "\\)\\>"))) + (mapconcat #'regexp-quote (org-split-string kwd "|") "\\|") + "\\)\\(?:[ \t]\\|$\\)"))) ((<= (prefix-numeric-value arg) (length org-todo-keywords-1)) (regexp-quote (nth (1- (prefix-numeric-value arg)) org-todo-keywords-1))) @@ -10237,10 +10542,9 @@ nil." ;; This is as accurate and faster than `org-element-at-point' since ;; planning info location is fixed in the section. (or (let ((cached (org-element-at-point nil 'cached))) - (and cached - (eq 'planning (org-element-type cached)))) + (and cached (org-element-type-p cached 'planning))) (org-with-wide-buffer - (beginning-of-line) + (forward-line 0) (and (looking-at-p org-planning-line-re) (eq (point) (ignore-errors @@ -10344,7 +10648,7 @@ WHAT entry will also be removed." (otherwise (error "Invalid planning type: %s" what))) " ") ;; Insert associated timestamp. - (let ((ts (org-insert-time-stamp + (let ((ts (org-insert-timestamp time (or org-time-was-given (and (eq what 'closed) org-log-done-with-time)) @@ -10389,6 +10693,9 @@ narrowing." (let ((drawer (org-log-into-drawer))) (cond (drawer + ;; This either moves past planning and property drawer, to + ;; first line below heading, or to `eob' (if heading is the + ;; last heading in buffer without contents). (org-end-of-meta-data) (let ((regexp (concat "^[ \t]*:" (regexp-quote drawer) ":[ \t]*$")) (end (if (org-at-heading-p) (point) @@ -10398,39 +10705,70 @@ narrowing." ;; Try to find existing drawer. (while (re-search-forward regexp end t) (let ((element (org-element-at-point))) - (when (eq (org-element-type element) 'drawer) - (let ((cend (org-element-property :contents-end element))) + (when (org-element-type-p element 'drawer) + (let ((cend (org-element-contents-end element))) (when (and (not org-log-states-order-reversed) cend) (goto-char cend))) (throw 'exit nil)))) ;; No drawer found. Create one, if permitted. (when create + ;; `org-end-of-meta-data' ended up at next heading + ;; * Heading to insert darawer + ;; * Another heading + ;; ;; Unless current heading is the last heading in buffer ;; and does not have a newline, `org-end-of-meta-data' - ;; should move us somewhere below the heading. + ;; can move us to the next heading. ;; Avoid situation when we insert drawer right before - ;; first "*". Otherwise, if the previous heading is - ;; folded, we are inserting after visible newline at - ;; the end of the fold, thus breaking the fold - ;; continuity. + ;; first "*". Otherwise, if the heading is folded, we + ;; are inserting after visible newline at the end of the + ;; fold, thus breaking the fold continuity. (unless (eobp) (when (org-at-heading-p) (backward-char))) (org-fold-core-ignore-modifications - (unless (bolp) (insert-and-inherit "\n")) - (let ((beg (point))) - (insert-and-inherit ":" drawer ":\n:END:\n") - (org-indent-region beg (point)) - (org-fold-region (line-end-position -1) (1- (point)) t (if (eq org-fold-core-style 'text-properties) 'drawer 'outline))))) - (end-of-line -1)))) + (let (;; Heading + ;; + ;; Text + (at-blank-line? (looking-at-p "^[ \t]*$")) + ;; Heading + ;; Text + (at-beginning-of-non-blank-line? + (and (bolp) (not (eolp))))) + (unless (bolp) + ;; Heading (see `backward-char' branch above) + (insert-and-inherit "\n")) + (let ((beg (point)) cbeg) + (insert-and-inherit ":" drawer ":") + (setq cbeg (point)) + (insert-and-inherit "\n:END:") + (cond + (at-blank-line? + ;; Heading + ;; :LOGBOOK: + ;; :END: + ;; + ;; Text + (insert "\n") + (backward-char)) + (at-beginning-of-non-blank-line? + ;; Heading + ;; :LOGBOOK: + ;; :END: + ;; Text + (insert "\n") + (backward-char))) + (org-indent-region beg (point)) + (org-fold-region cbeg (point) t 'drawer))))) + (end-of-line 0)))) (t (org-end-of-meta-data org-log-state-notes-insert-after-drawers) (let ((endpos (point))) (skip-chars-forward " \t\n") - (beginning-of-line) + (forward-line 0) (unless org-log-states-order-reversed (org-skip-over-state-notes) (skip-chars-backward " \t\n") - (beginning-of-line 2)) + (forward-line 1)) ;; When current headline is at the end of buffer and does not ;; end with trailing newline the above can move to the ;; beginning of the headline. @@ -10455,7 +10793,11 @@ EXTRA is additional text that will be inserted into the notes buffer." (add-hook 'post-command-hook 'org-add-log-note 'append)) (defun org-skip-over-state-notes () - "Skip past the list of State notes in an entry." + "Skip past the list of State notes in an entry. +The point is assumed to be on a list of State notes, each matching +`org-log-note-headings'. The function moves point to the first list +item that is not a State note or to the end of the list if all the +items are State notes." (when (ignore-errors (goto-char (org-in-item-p))) (let* ((struct (org-list-struct)) (prevs (org-list-prevs-alist struct)) @@ -10484,11 +10826,10 @@ EXTRA is additional text that will be inserted into the notes buffer." (remove-hook 'post-command-hook 'org-add-log-note) (setq org-log-setup nil) (setq org-log-note-window-configuration (current-window-configuration)) - (delete-other-windows) (move-marker org-log-note-return-to (point)) - (pop-to-buffer-same-window (marker-buffer org-log-note-marker)) + (pop-to-buffer (marker-buffer org-log-note-marker) '(org-display-buffer-full-frame)) (goto-char org-log-note-marker) - (org-switch-to-buffer-other-window "*Org Note*") + (pop-to-buffer "*Org Note*" '(org-display-buffer-split)) (erase-buffer) (if (memq org-log-note-how '(time state)) (org-store-log-note) @@ -10592,6 +10933,7 @@ EXTRA is additional text that will be inserted into the notes buffer." (unless (string-empty-p line) (indent-line-to ind) (insert-and-inherit line)))) + (run-hooks 'org-after-note-stored-hook) (message "Note stored") (org-back-to-heading t)))))) ;; Don't add undo information when called from `org-agenda-todo'. @@ -10608,10 +10950,10 @@ POS may also be a marker." (org-with-wide-buffer (goto-char pos) (let ((drawer (org-element-at-point))) - (when (and (memq (org-element-type drawer) '(drawer property-drawer)) - (not (org-element-property :contents-begin drawer))) - (delete-region (org-element-property :begin drawer) - (progn (goto-char (org-element-property :end drawer)) + (when (and (org-element-type-p drawer '(drawer property-drawer)) + (not (org-element-contents-begin drawer))) + (delete-region (org-element-begin drawer) + (progn (goto-char (org-element-end drawer)) (skip-chars-backward " \r\t\n") (forward-line) (point)))))))) @@ -10644,7 +10986,7 @@ D Show deadlines and scheduled items between a date range." (deadline "only deadline") (active "only active timestamps") (inactive "only inactive timestamps") - (closed "with a closed time-stamp") + (closed "with a closed timestamp") (otherwise "scheduled/deadline"))) (let ((answer (read-char-exclusive))) (cl-case answer @@ -10663,6 +11005,9 @@ D Show deadlines and scheduled items between a date range." ((?p ?P) (let* ((kwd (completing-read "Property: " (mapcar #'list (org-buffer-property-keys)))) + (kwd + ;; Escape "-" in property names. + (replace-regexp-in-string "-" "\\\\-" kwd)) (value (completing-read "Value: " (mapcar #'list (org-property-values kwd))))) (unless (string-match "\\`{.*}\\'" value) @@ -10673,6 +11018,7 @@ D Show deadlines and scheduled items between a date range." (defvar-local org-occur-highlights nil "List of overlays used for occur matches.") +(put 'org-occur-highlights 'permanent-local t) (defvar-local org-occur-parameters nil "Parameters of the active org-occur calls. This is a list, each call to org-occur pushes as cons cell, @@ -10680,7 +11026,7 @@ containing the regular expression and the callback, onto the list. The list can contain several entries if `org-occur' has been called several time with the KEEP-PREVIOUS argument. Otherwise, this list will only contain one set of parameters. When the highlights are -removed (for example with `C-c C-c', or with the next edit (depending +removed (for example with \\`C-c C-c', or with the next edit (depending on `org-remove-highlights-with-change'), this variable is emptied as well.") @@ -10902,22 +11248,21 @@ or a character." (insert " [#" news "]")) (goto-char (match-beginning 3)) (insert "[#" news "] ")))) - (org-align-tags)) + (when org-auto-align-tags (org-align-tags))) (if remove (message "Priority removed") (message "Priority of current item set to %s" news))))) (defalias 'org-show-priority 'org-priority-show) (defun org-priority-show () - "Show the priority of the current item. -This priority is composed of the main priority given with the [#A] cookies, -and by additional input from the age of a schedules or deadline entry." + "Show the priority of the current item as number. +Return the priority value." (interactive) (let ((pri (if (eq major-mode 'org-agenda-mode) (org-get-at-bol 'priority) (save-excursion (save-match-data - (beginning-of-line) + (forward-line 0) (and (looking-at org-heading-regexp) (org-get-priority (match-string 0)))))))) (message "Priority is %d" (if pri pri -1000)))) @@ -10979,13 +11324,13 @@ included in the output. START-LEVEL can be a string with asterisks, reducing the scope to headlines matching this string." (require 'org-agenda) - (let* ((re (concat "^" - (if start-level - ;; Get the correct level to match - (concat "\\*\\{" (number-to-string start-level) "\\} ") - org-outline-regexp) - " *\\(?:\\(" (regexp-opt org-todo-keywords-1 t) "\\) \\)?" - " *\\(.*?\\)\\([ \t]:\\(?:" org-tag-re ":\\)+\\)?[ \t]*$")) + (let* ((heading-re + (concat ;;FIXME: use cache + "^" + (if start-level + ;; Get the correct level to match + (concat "\\*\\{" (number-to-string start-level) "\\} ") + org-outline-regexp))) (props (list 'face 'default 'done-face 'org-agenda-done 'undone-face 'default @@ -10999,10 +11344,8 @@ headlines matching this string." (or (buffer-file-name (buffer-base-buffer)) (buffer-name (buffer-base-buffer))))))) (org-map-continue-from nil) - lspos tags tags-list - (tags-alist (list (cons 0 org-file-tags))) - (llast 0) rtn rtn1 level category i txt - todo marker entry priority + tags-list rtn rtn1 level category txt + todo marker priority ts-date ts-date-type ts-date-pair) (unless (or (member action '(agenda sparse-tree)) (functionp action)) (setq action (list 'lambda nil action))) @@ -11011,215 +11354,100 @@ headlines matching this string." (when (eq action 'sparse-tree) (org-cycle-overview) (org-remove-occur-highlights)) - (if (org-element--cache-active-p) - (let ((fast-re (concat "^" - (if start-level - ;; Get the correct level to match - (concat "\\*\\{" (number-to-string start-level) "\\} ") - org-outline-regexp)))) - (org-element-cache-map - (lambda (el) - (goto-char (org-element-property :begin el)) - (setq todo (org-element-property :todo-keyword el) - level (org-element-property :level el) - category (org-entry-get-with-inheritance "CATEGORY" nil el) - tags-list (org-get-tags el) - org-scanner-tags tags-list) - (when (eq action 'agenda) - (setq ts-date-pair (org-agenda-entry-get-agenda-timestamp (point)) - ts-date (car ts-date-pair) - ts-date-type (cdr ts-date-pair))) - (catch :skip - (when (and - - ;; eval matcher only when the todo condition is OK - (and (or (not todo-only) (member todo org-todo-keywords-1)) - (if (functionp matcher) - (let ((case-fold-search t) (org-trust-scanner-tags t)) - (funcall matcher todo tags-list level)) - matcher)) - - ;; Call the skipper, but return t if it does not - ;; skip, so that the `and' form continues evaluating. - (progn - (unless (eq action 'sparse-tree) (org-agenda-skip el)) - t) - - ;; Check if timestamps are deselecting this entry - (or (not todo-only) - (and (member todo org-todo-keywords-1) - (or (not org-agenda-tags-todo-honor-ignore-options) - (not (org-agenda-check-for-timestamp-as-reason-to-ignore-todo-item)))))) - - ;; select this headline - (cond - ((eq action 'sparse-tree) - (and org-highlight-sparse-tree-matches - (org-get-heading) (match-end 0) - (org-highlight-new-match - (match-beginning 1) (match-end 1))) - (org-fold-show-context 'tags-tree)) - ((eq action 'agenda) - (let* ((effort (org-entry-get (point) org-effort-property)) - (effort-minutes (when effort (save-match-data (org-duration-to-minutes effort))))) - (setq txt (org-agenda-format-item - "" - ;; Add `effort' and `effort-minutes' - ;; properties for prefix format. - (org-add-props - (concat - (if (eq org-tags-match-list-sublevels 'indented) - (make-string (1- level) ?.) "") - (org-get-heading)) - nil - 'effort effort - 'effort-minutes effort-minutes) - (make-string level ?\s) - category - tags-list) - priority (org-get-priority txt)) - ;; Now add `effort' and `effort-minutes' to - ;; full agenda line. - (setq txt (org-add-props txt nil - 'effort effort - 'effort-minutes effort-minutes))) - (goto-char (org-element-property :begin el)) - (setq marker (org-agenda-new-marker)) - (org-add-props txt props - 'org-marker marker 'org-hd-marker marker 'org-category category - 'todo-state todo - 'ts-date ts-date - 'priority priority - 'type (concat "tagsmatch" ts-date-type)) - (push txt rtn)) - ((functionp action) - (setq org-map-continue-from nil) - (save-excursion - (setq rtn1 (funcall action)) - (push rtn1 rtn))) - (t (user-error "Invalid action"))) - - ;; if we are to skip sublevels, jump to end of subtree - (unless org-tags-match-list-sublevels - (goto-char (1- (org-element-property :end el)))))) - ;; Get the correct position from where to continue - (when org-map-continue-from - (setq org-element-cache-map-continue-from org-map-continue-from) - (goto-char org-map-continue-from)) - ;; Return nil. - nil) - :next-re fast-re - :fail-re fast-re - :narrow t)) - (while (let (case-fold-search) - (re-search-forward re nil t)) - (setq org-map-continue-from nil) - (catch :skip - ;; Ignore closing parts of inline tasks. - (when (and (fboundp 'org-inlinetask-end-p) (org-inlinetask-end-p)) - (throw :skip t)) - (setq todo (and (match-end 1) (match-string-no-properties 1))) - (setq tags (and (match-end 4) (org-trim (match-string-no-properties 4)))) - (goto-char (setq lspos (match-beginning 0))) - (setq level (org-reduced-level (org-outline-level)) - category (org-get-category)) - (when (eq action 'agenda) - (setq ts-date-pair (org-agenda-entry-get-agenda-timestamp (point)) - ts-date (car ts-date-pair) - ts-date-type (cdr ts-date-pair))) - (setq i llast llast level) - ;; remove tag lists from same and sublevels - (while (>= i level) - (when (setq entry (assoc i tags-alist)) - (setq tags-alist (delete entry tags-alist))) - (setq i (1- i))) - ;; add the next tags - (when tags - (setq tags (org-split-string tags ":") - tags-alist - (cons (cons level tags) tags-alist))) - ;; compile tags for current headline - (setq tags-list - (if org-use-tag-inheritance - (apply 'append (mapcar 'cdr (reverse tags-alist))) - tags) - org-scanner-tags tags-list) - (when org-use-tag-inheritance - (setcdr (car tags-alist) - (mapcar (lambda (x) - (setq x (copy-sequence x)) - (org-add-prop-inherited x)) - (cdar tags-alist)))) - (when (and tags org-use-tag-inheritance - (or (not (eq t org-use-tag-inheritance)) - org-tags-exclude-from-inheritance)) - ;; Selective inheritance, remove uninherited ones. - (setcdr (car tags-alist) - (org-remove-uninherited-tags (cdar tags-alist)))) - (when (and - - ;; eval matcher only when the todo condition is OK - (and (or (not todo-only) (member todo org-todo-keywords-1)) - (if (functionp matcher) - (let ((case-fold-search t) (org-trust-scanner-tags t)) - (funcall matcher todo tags-list level)) - matcher)) - - ;; Call the skipper, but return t if it does not - ;; skip, so that the `and' form continues evaluating. - (progn - (unless (eq action 'sparse-tree) (org-agenda-skip)) - t) - - ;; Check if timestamps are deselecting this entry - (or (not todo-only) - (and (member todo org-todo-keywords-1) - (or (not org-agenda-tags-todo-honor-ignore-options) - (not (org-agenda-check-for-timestamp-as-reason-to-ignore-todo-item)))))) - - ;; select this headline - (cond - ((eq action 'sparse-tree) - (and org-highlight-sparse-tree-matches - (org-get-heading) (match-end 0) - (org-highlight-new-match - (match-beginning 1) (match-end 1))) - (org-fold-show-context 'tags-tree)) - ((eq action 'agenda) - (setq txt (org-agenda-format-item - "" - (concat - (if (eq org-tags-match-list-sublevels 'indented) - (make-string (1- level) ?.) "") - (org-get-heading)) - (make-string level ?\s) - category - tags-list) - priority (org-get-priority txt)) - (goto-char lspos) - (setq marker (org-agenda-new-marker)) - (org-add-props txt props - 'org-marker marker 'org-hd-marker marker 'org-category category - 'todo-state todo - 'ts-date ts-date - 'priority priority - 'type (concat "tagsmatch" ts-date-type)) - (push txt rtn)) - ((functionp action) - (setq org-map-continue-from nil) - (save-excursion - (setq rtn1 (funcall action)) - (push rtn1 rtn))) - (t (user-error "Invalid action"))) - - ;; if we are to skip sublevels, jump to end of subtree - (unless org-tags-match-list-sublevels - (org-end-of-subtree t) - (backward-char 1)))) - ;; Get the correct position from where to continue - (if org-map-continue-from - (goto-char org-map-continue-from) - (and (= (point) lspos) (end-of-line 1)))))) + (org-element-cache-map + (lambda (el) + (goto-char (org-element-begin el)) + (setq todo (org-element-property :todo-keyword el) + level (org-element-property :level el) + category (org-entry-get-with-inheritance "CATEGORY" nil el) + tags-list (org-get-tags el) + org-scanner-tags tags-list) + (when (eq action 'agenda) + (setq ts-date-pair (org-agenda-entry-get-agenda-timestamp el) + ts-date (car ts-date-pair) + ts-date-type (cdr ts-date-pair))) + (catch :skip + (when (and + + ;; eval matcher only when the todo condition is OK + (and (or (not todo-only) (member todo org-todo-keywords-1)) + (if (functionp matcher) + (let ((case-fold-search t) (org-trust-scanner-tags t)) + (funcall matcher todo tags-list level)) + matcher)) + + ;; Call the skipper, but return t if it does not + ;; skip, so that the `and' form continues evaluating. + (progn + (unless (eq action 'sparse-tree) (org-agenda-skip el)) + t) + + ;; Check if timestamps are deselecting this entry + (or (not todo-only) + (and (member todo org-todo-keywords-1) + (or (not org-agenda-tags-todo-honor-ignore-options) + (not (org-agenda-check-for-timestamp-as-reason-to-ignore-todo-item)))))) + + ;; select this headline + (cond + ((eq action 'sparse-tree) + (and org-highlight-sparse-tree-matches + (org-get-heading) (match-end 0) + (org-highlight-new-match + (match-beginning 1) (match-end 1))) + (org-fold-show-context 'tags-tree)) + ((eq action 'agenda) + (let* ((effort (org-entry-get (point) org-effort-property)) + (effort-minutes (when effort (save-match-data (org-duration-to-minutes effort))))) + (setq txt (org-agenda-format-item + "" + ;; Add `effort' and `effort-minutes' + ;; properties for prefix format. + (org-add-props + (concat + (if (eq org-tags-match-list-sublevels 'indented) + (make-string (1- level) ?.) "") + (org-get-heading)) + nil + 'effort effort + 'effort-minutes effort-minutes) + (make-string level ?\s) + category + tags-list) + priority (org-get-priority txt)) + ;; Now add `effort' and `effort-minutes' to + ;; full agenda line. + (setq txt (org-add-props txt nil + 'effort effort + 'effort-minutes effort-minutes))) + (goto-char (org-element-begin el)) + (setq marker (org-agenda-new-marker)) + (org-add-props txt props + 'org-marker marker 'org-hd-marker marker 'org-category category + 'todo-state todo + 'ts-date ts-date + 'priority priority + 'type (concat "tagsmatch" ts-date-type)) + (push txt rtn)) + ((functionp action) + (setq org-map-continue-from nil) + (save-excursion + (setq rtn1 (funcall action)) + (push rtn1 rtn))) + (t (user-error "Invalid action"))) + + ;; if we are to skip sublevels, jump to end of subtree + (unless org-tags-match-list-sublevels + (goto-char (1- (org-element-end el)))))) + ;; Get the correct position from where to continue + (when org-map-continue-from + (setq org-element-cache-map-continue-from org-map-continue-from) + (goto-char org-map-continue-from)) + ;; Return nil. + nil) + :next-re heading-re + :fail-re heading-re + :narrow t)) (when (and (eq action 'sparse-tree) (not org-sparse-tree-open-archived-trees)) (org-fold-hide-archived-subtrees (point-min) (point-max))) @@ -11264,22 +11492,6 @@ are also TODO tasks." (defalias 'org-tags-sparse-tree 'org-match-sparse-tree) -(defvar org-cached-props nil) -(defun org-cached-entry-get (pom property) - (if (or (eq t org-use-property-inheritance) - (and (stringp org-use-property-inheritance) - (let ((case-fold-search t)) - (string-match-p org-use-property-inheritance property))) - (and (listp org-use-property-inheritance) - (member-ignore-case property org-use-property-inheritance))) - ;; Caching is not possible, check it directly. - (org-entry-get pom property 'inherit) - ;; Get all properties, so we can do complicated checks easily. - (cdr (assoc-string property - (or org-cached-props - (setq org-cached-props (org-entry-properties pom))) - t)))) - (defun org-global-tags-completion-table (&optional files) "Return the list of all tags in all agenda buffer/files. Optional FILES argument is a list of files which can be used @@ -11327,7 +11539,8 @@ See also `org-scan-tags'." ;; tags table and the local tags in current buffer. (let ((org-last-tags-completion-table (org--tag-add-to-alist - (org-get-buffer-tags) + (when (derived-mode-p 'org-mode) + (org-get-buffer-tags)) (unless only-local-tags (org-global-tags-completion-table))))) (setq match @@ -11335,15 +11548,55 @@ See also `org-scan-tags'." "Match: " 'org-tags-completion-function nil nil nil 'org-tags-history)))) - (let ((match0 match) - (re (concat - "^&?\\([-+:]\\)?\\({[^}]+}\\|LEVEL\\([<=>]\\{1,2\\}\\)" - "\\([0-9]+\\)\\|\\(\\(?:[[:alnum:]_]+\\(?:\\\\-\\)*\\)+\\)" - "\\([<>=]\\{1,2\\}\\)" - "\\({[^}]+}\\|\"[^\"]*\"\\|-?[.0-9]+\\(?:[eE][-+]?[0-9]+\\)?\\)" - "\\|" org-tag-re "\\)")) - (start 0) - tagsmatch todomatch tagsmatcher todomatcher) + (let* ((match0 match) + (opre "[<=>]=?\\|[!/]=\\|<>") + (re (concat + "^" + ;; implicit AND operator (OR is done by global splitting) + "&?" + ;; exclusion and inclusion (the latter being implicit) + "\\(?1:[-+:]\\)?" + ;; query term + "\\(?2:" + ;; tag regexp match + "{[^}]+}\\|" + ;; property match. Try to keep this subre generic + ;; and rather handle special properties like LEVEL + ;; and CATEGORY further below. This ensures that + ;; the same quoting mechanics can be used for all + ;; property names. + "\\(?:" + ;; property name [1] + "\\(?5:\\(?:[[:alnum:]_]+\\|\\\\[^[:space:]]\\)+\\)" + ;; operator, optionally starred + "\\(?6:" opre "\\)\\(?7:\\*\\)?" + ;; operand (regexp, double-quoted string, + ;; number) + "\\(?8:" + "{[^}]+}\\|" + "\"[^\"]*\"\\|" + "-?[.0-9]+\\(?:[eE][-+]?[0-9]+\\)?" + "\\)" + "\\)\\|" + ;; exact tag match + org-tag-re + "\\)")) + (start 0) + tagsmatch todomatch tagsmatcher todomatcher) + + ;; [1] The history of this particular subre: + ;; - \\([[:alnum:]_]+\\) [pre-19b0e03] + ;; Does not allow for minus characters in property names. + ;; - "\\(\\(?:[[:alnum:]_]+\\(?:\\\\-\\)*\\)+\\)" [19b0e03] + ;; Incomplete fix of above issue, still resulting in, e.g., + ;; https://orgmode.org/list/87jzv67k3p.fsf@localhost. + ;; - "\\(?5:[[:alnum:]_-]+\\)" [f689eb4] + ;; Allows for unquoted minus characters in property names, but + ;; conflicts with searches like -TAG-PROP="VALUE". See + ;; https://orgmode.org/list/87h6oq2nu1.fsf@gmail.com. + ;; - current subre + ;; Like second solution, but with proper unquoting and allowing + ;; for all possible characters in property names to be quoted. ;; Expand group tags. (setq match (org-tags-expand match)) @@ -11383,47 +11636,74 @@ See also `org-scan-tags'." (let* ((rest (substring term (match-end 0))) (minus (and (match-end 1) (equal (match-string 1 term) "-"))) - (tag (save-match-data - (replace-regexp-in-string - "\\\\-" "-" (match-string 2 term)))) + ;; Bind the whole query term to `tag' and use that + ;; variable for a tag regexp match in [2] or as an + ;; exact tag match in [3]. + (tag (match-string 2 term)) (regexp (eq (string-to-char tag) ?{)) - (levelp (match-end 4)) (propp (match-end 5)) (mm (cond - (regexp `(org-match-any-p ,(substring tag 1 -1) tags-list)) - (levelp - `(,(org-op-to-function (match-string 3 term)) - level - ,(string-to-number (match-string 4 term)))) + (regexp ; [2] + `(with-syntax-table org-mode-tags-syntax-table + (org-match-any-p ,(substring tag 1 -1) tags-list))) (propp - (let* ((gv (pcase (upcase (match-string 5 term)) + (let* (;; Determine property name. + (pn (upcase + (save-match-data + (replace-regexp-in-string + "\\\\\\(.\\)" "\\1" + (match-string 5 term) + t nil)))) + ;; Convert property name to an Elisp + ;; accessor for that property (aka. as + ;; getter value). Symbols LEVEL and TODO + ;; referenced below get bound by the + ;; matcher that this function returns. + (gv (pcase pn + ("LEVEL" + '(number-to-string level)) ("CATEGORY" '(org-get-category (point))) ("TODO" 'todo) - (p `(org-cached-entry-get nil ,p)))) - (pv (match-string 7 term)) + (p `(org-entry-get (point) ,p 'selective)))) + ;; Determine operand (aka. property + ;; value). + (pv (match-string 8 term)) + ;; Determine type of operand. Note that + ;; these are not exclusive: Any TIMEP is + ;; also STRP. (regexp (eq (string-to-char pv) ?{)) (strp (eq (string-to-char pv) ?\")) (timep (string-match-p "^\"[[<]\\(?:[0-9]+\\|now\\|today\\|tomorrow\\|[+-][0-9]+[dmwy]\\).*[]>]\"$" pv)) + ;; Massage operand. TIMEP must come + ;; before STRP. + (pv (cond (regexp (substring pv 1 -1)) + (timep (org-matcher-time + (substring pv 1 -1))) + (strp (substring pv 1 -1)) + (t pv))) + ;; Convert operator to Elisp. (po (org-op-to-function (match-string 6 term) - (if timep 'time strp)))) - (setq pv (if (or regexp strp) (substring pv 1 -1) pv)) - (when timep (setq pv (org-matcher-time pv))) - (cond ((and regexp (eq po '/=)) - `(not (string-match ,pv (or ,gv "")))) - (regexp `(string-match ,pv (or ,gv ""))) - (strp `(,po (or ,gv "") ,pv)) - (t - `(,po - (string-to-number (or ,gv "")) - ,(string-to-number pv)))))) - (t `(member ,tag tags-list))))) + (if timep 'time strp))) + ;; Convert whole property term to Elisp. + (pt (cond ((and regexp (eq po '/=)) + `(not (string-match ,pv (or ,gv "")))) + (regexp `(string-match ,pv (or ,gv ""))) + (strp `(,po (or ,gv "") ,pv)) + (t + `(,po + (string-to-number (or ,gv "")) + ,(string-to-number pv))))) + ;; Respect the star after the operand. + (pt (if (match-end 7) `(and ,gv ,pt) pt))) + pt)) + (t `(member ,tag tags-list))))) ; [3] (push (if minus `(not ,mm) mm) tagsmatcher) (setq term rest))) (push `(and ,@tagsmatcher) orlist) (setq tagsmatcher nil)) - (setq tagsmatcher `(progn (setq org-cached-props nil) (or ,@orlist))))) + (setq tagsmatcher `(or ,@orlist)))) ;; Make the TODO matcher. (when (org-string-nw-p todomatch) @@ -11453,7 +11733,12 @@ See also `org-scan-tags'." (or tagsmatcher todomatcher t)))) (when org--matcher-tags-todo-only (setq matcher `(and (member todo org-not-done-keywords) ,matcher))) - (cons match0 `(lambda (todo tags-list level) ,matcher))))) + (cons match0 + (byte-compile + `(lambda (todo tags-list level) + ;; Pacify byte-compiler. + (ignore todo) (ignore tags-list) (ignore level) + ,matcher)))))) (defun org--tags-expand-group (group tag-groups expanded) "Recursively expand all tags in GROUP, according to TAG-GROUPS. @@ -11503,7 +11788,6 @@ the list of tags in this group." (single-as-list (org--tags-expand-group (list match) tag-groups nil)) (org-group-tags (let* ((case-fold-search t) - (tag-syntax org-mode-syntax-table) (group-keys (mapcar #'car tag-groups)) (key-regexp (concat "\\([+-]?\\)" (regexp-opt group-keys 'words))) (return-match match)) @@ -11514,11 +11798,8 @@ the list of tags in this group." (setq s (match-end 0)) (add-text-properties (match-beginning 0) (match-end 0) '(regexp t) return-match))) - ;; @ and _ are allowed as word-components in tags. - (modify-syntax-entry ?@ "w" tag-syntax) - (modify-syntax-entry ?_ "w" tag-syntax) ;; For each tag token found in MATCH, compute a regexp and it - (with-syntax-table tag-syntax + (with-syntax-table org-mode-tags-syntax-table (replace-regexp-in-string key-regexp (lambda (m) @@ -11553,12 +11834,12 @@ the list of tags in this group." "Turn an operator into the appropriate function." (setq op (cond - ((equal op "<" ) '(< org-string< org-time<)) - ((equal op ">" ) '(> org-string> org-time>)) - ((member op '("<=" "=<")) '(<= org-string<= org-time<=)) - ((member op '(">=" "=>")) '(>= org-string>= org-time>=)) - ((member op '("=" "==")) '(= string= org-time=)) - ((member op '("<>" "!=")) '(/= org-string<> org-time<>)))) + ((equal op "<" ) '(< org-string< org-time<)) + ((equal op ">" ) '(> org-string> org-time>)) + ((member op '("<=" "=<" )) '(<= org-string<= org-time<=)) + ((member op '(">=" "=>" )) '(>= org-string>= org-time>=)) + ((member op '("=" "==" )) '(= string= org-time=)) + ((member op '("<>" "!=" "/=")) '(/= org-string<> org-time<>)))) (nth (if (eq stringp 'time) 2 (if stringp 1 0)) op)) (defvar org-add-colon-after-tag-completion nil) ;; dynamically scoped param @@ -11566,8 +11847,7 @@ the list of tags in this group." (delete-overlay org-tags-overlay) (defun org-add-prop-inherited (s) - (add-text-properties 0 (length s) '(inherited t) s) - s) + (propertize s 'inherited t)) (defun org-toggle-tag (tag &optional onoff) "Toggle the tag TAG for the current line. @@ -11650,6 +11930,9 @@ in Lisp code use `org-set-tags' instead." (lambda () (when (org-invisible-p) (org-end-of-subtree nil t)))))) (t (save-excursion + ;; FIXME: We need to add support setting #+FILETAGS. + (when (org-before-first-heading-p) + (user-error "Setting file tags is not supported yet")) (org-back-to-heading) (let* ((all-tags (org-get-tags)) (local-table (or org-current-tag-alist (org-get-buffer-tags))) @@ -11760,7 +12043,7 @@ This function assumes point is on a headline." (unless (org-invisible-p (line-beginning-position)) (org-fold-region (point) (line-end-position) nil 'outline)))) ;; Align tags, if any. - (when tags (org-align-tags)) + (when (and tags org-auto-align-tags) (org-align-tags)) (when tags-change? (run-hooks 'org-after-tags-change-hook)))))) (defun org-change-tag-in-region (beg end tag off) @@ -11811,13 +12094,20 @@ function is passed as a collection function to `completing-read', which see." (let ((completion-ignore-case nil) ;tags are case-sensitive (confirm (lambda (x) (stringp (car x)))) - (prefix "")) + (prefix "") + begin) (when (string-match "^\\(.*[-+:&,|]\\)\\([^-+:&,|]*\\)$" string) (setq prefix (match-string 1 string)) + (setq begin (match-beginning 2)) (setq string (match-string 2 string))) (pcase flag (`t (all-completions string org-last-tags-completion-table confirm)) (`lambda (assoc string org-last-tags-completion-table)) ;exact match? + (`(boundaries . ,suffix) + (let ((end (if (string-match "[-+:&,|]" suffix) + (match-string 0 suffix) + (length suffix)))) + `(boundaries ,(or begin 0) . ,end))) (`nil (pcase (try-completion string org-last-tags-completion-table confirm) ((and completion (pred stringp)) @@ -11853,36 +12143,90 @@ Also insert END." (put-text-property 0 (length s) 'face '(secondary-selection org-tag) s) (org-overlay-display org-tags-overlay (concat prefix s)))) +(defun org--add-or-remove-tag (tag current-tags &optional groups) + "Add or remove TAG entered by user to/from CURRENT-TAGS. +Return the modified CURRENT-TAGS. + +When TAG is present in CURRENT-TAGS, remove it. Otherwise, add it. +When TAG is a part of a tag group from GROUPS, make sure that no +exclusive tags from the same group remain in CURRENT-TAGS. + +CURRENT-TAGS may be modified by side effect." + (if (member tag current-tags) + ;; Remove the tag. + (delete tag current-tags) + ;; Add the tag. If the tag is from a tag + ;; group, exclude selected alternative tags + ;; from the group, if any. + (dolist (g groups) + (when (member tag g) + (dolist (x g) (setq current-tags (delete x current-tags))))) + (cons tag current-tags))) + (defvar org-last-tag-selection-key nil) -(defun org-fast-tag-selection (current inherited table &optional todo-table) +(defun org-fast-tag-selection (current-tags inherited-tags tag-table &optional todo-table) "Fast tag selection with single keys. -CURRENT is the current list of tags in the headline, INHERITED is the -list of inherited tags, and TABLE is an alist of tags and corresponding keys, -possibly with grouping information. TODO-TABLE is a similar table with -TODO keywords, should these have keys assigned to them. +CURRENT-TAGS is the current list of tags in the headline, +INHERITED-TAGS is the list of inherited tags, and TAG-TABLE is an +alist of tags and corresponding keys, possibly with grouping +information. TODO-TABLE is a similar table with TODO keywords, should +these have keys assigned to them. If the keys are nil, a-z are automatically assigned. Returns the new tags string, or nil to not change the current settings." - (let* ((fulltable (append table todo-table)) - (maxlen (if (null fulltable) 0 - (apply #'max - (mapcar (lambda (x) - (if (stringp (car x)) (string-width (car x)) - 0)) - fulltable)))) - (buf (current-buffer)) - (expert (eq org-fast-tag-selection-single-key 'expert)) + (let* (;; Combined alist of all the tags and todo keywords. + (tag-alist (append tag-table todo-table)) + ;; Max width occupied by a single tag record in the completion buffer. + (field-width + (+ 3 ; keep space for "[c]" binding. + 1 ; ensure that there is at least one space between adjacent tag fields. + 3 ; keep space for group tag " : " delimiter. + ;; The longest tag. + (if (null tag-alist) 0 + (apply #'max + (mapcar (lambda (x) + (if (stringp (car x)) (string-width (car x)) + 0)) + tag-alist))))) + (origin-buffer (current-buffer)) + (expert-interface (eq org-fast-tag-selection-single-key 'expert)) + ;; Tag completion table, for normal completion (). (tab-tags nil) - (fwidth (+ maxlen 3 1 3)) - (ncol (/ (- (window-width) 4) fwidth)) - (i-face 'org-done) - (c-face 'org-todo) - tg cnt e c char c1 c2 ntable tbl rtn + (inherited-face 'org-done) + (current-face 'org-todo) + ;; Characters available for auto-assignment. + (tag-binding-char-list org--fast-tag-selection-keys) + (tag-binding-chars-left org-fast-tag-selection-maximum-tags) + field-number ; current tag column in the completion buffer. + tag-binding-spec ; Alist element. + current-tag current-tag-char auto-tag-char + tag-table-local ; table holding all the displayed tags together with auto-assigned bindings. + input-char rtn ov-start ov-end ov-prefix (exit-after-next org-fast-tag-selection-single-key) (done-keywords org-done-keywords) groups ingroup intaggroup) + ;; Calculate the number of tags with explicit user bindings + tags in groups. + ;; These tags will be displayed unconditionally. Other tags will + ;; be displayed only when there are free bindings left according + ;; to `org-fast-tag-selection-maximum-tags'. + (dolist (tag-binding-spec tag-alist) + (pcase tag-binding-spec + (`((or :startgroup :startgrouptag) . _) + (setq ingroup t)) + (`((or :endgroup :endgrouptag) . _) + (setq ingroup nil)) + ((guard (cdr tag-binding-spec)) + (cl-decf tag-binding-chars-left)) + (`((or :newline :grouptags))) ; pass + ((guard ingroup) + (cl-decf tag-binding-chars-left)))) + (setq ingroup nil) ; It t, it means malformed tag alist. Reset just in case. + ;; Move global `org-tags-overlay' overlay to current heading. + ;; Calls to `org-set-current-tags-overlay' will take care about + ;; updating the overlay text. + ;; FIXME: What if we are setting file tags? (save-excursion - (beginning-of-line) + (forward-line 0) (if (looking-at org-tag-line-re) (setq ov-start (match-beginning 1) ov-end (match-end 1) @@ -11897,179 +12241,237 @@ Returns the new tags string, or nil to not change the current settings." " " (make-string (- org-tags-column (current-column)) ?\ )))))) (move-overlay org-tags-overlay ov-start ov-end) + ;; Highlight tags overlay in Org buffer. + (org-set-current-tags-overlay current-tags ov-prefix) + ;; Display tag selection dialog, read the user input, and return. (save-excursion (save-window-excursion - (if expert + ;; Select tag list buffer, and display it unless EXPERT-INTERFACE. + (if expert-interface (set-buffer (get-buffer-create " *Org tags*")) - (delete-other-windows) - (set-window-buffer (split-window-vertically) (get-buffer-create " *Org tags*")) - (org-switch-to-buffer-other-window " *Org tags*")) + (pop-to-buffer + (get-buffer-create " *Org tags*") + '(org-display-buffer-split (direction . down)))) + ;; Fill text in *Org tags* buffer. (erase-buffer) (setq-local org-done-keywords done-keywords) - (org-fast-tag-insert "Inherited" inherited i-face "\n") - (org-fast-tag-insert "Current" current c-face "\n\n") + ;; Insert current tags. + (org-fast-tag-insert "Inherited" inherited-tags inherited-face "\n") + (org-fast-tag-insert "Current" current-tags current-face "\n\n") + ;; Display whether next change exits selection dialog. (org-fast-tag-show-exit exit-after-next) - (org-set-current-tags-overlay current ov-prefix) - (setq tbl fulltable char ?a cnt 0) - (while (setq e (pop tbl)) - (cond - ((eq (car e) :startgroup) - (push '() groups) (setq ingroup t) - (unless (zerop cnt) - (setq cnt 0) - (insert "\n")) - (insert (if (cdr e) (format "%s: " (cdr e)) "") "{ ")) - ((eq (car e) :endgroup) - (setq ingroup nil cnt 0) - (insert "}" (if (cdr e) (format " (%s) " (cdr e)) "") "\n")) - ((eq (car e) :startgrouptag) - (setq intaggroup t) - (unless (zerop cnt) - (setq cnt 0) - (insert "\n")) - (insert "[ ")) - ((eq (car e) :endgrouptag) - (setq intaggroup nil cnt 0) - (insert "]\n")) - ((equal e '(:newline)) - (unless (zerop cnt) - (setq cnt 0) - (insert "\n") - (setq e (car tbl)) - (while (equal (car tbl) '(:newline)) - (insert "\n") - (setq tbl (cdr tbl))))) - ((equal e '(:grouptags)) - (delete-char -3) - (insert " : ")) - (t - (setq tg (copy-sequence (car e)) c2 nil) - (if (cdr e) - (setq c (cdr e)) - ;; automatically assign a character. - (setq c1 (string-to-char - (downcase (substring - tg (if (= (string-to-char tg) ?@) 1 0))))) - (if (or (rassoc c1 ntable) (rassoc c1 table)) - (while (or (rassoc char ntable) (rassoc char table)) - (setq char (1+ char))) - (setq c2 c1)) - (setq c (or c2 - (if (> char ?~) - ?\s - char))) - ;; Consider characters A-Z after a-z. - (if (equal char ?z) - (setq char ?A))) - (when ingroup (push tg (car groups))) - (setq tg (org-add-props tg nil 'face - (cond - ((not (assoc tg table)) - (org-get-todo-face tg)) - ((member tg current) c-face) - ((member tg inherited) i-face)))) - (when (equal (caar tbl) :grouptags) - (org-add-props tg nil 'face 'org-tag-group)) - (when (and (zerop cnt) (not ingroup) (not intaggroup)) (insert " ")) - (insert "[" c "] " tg (make-string - (- fwidth 4 (length tg)) ?\ )) - (push (cons tg c) ntable) - (when (= (cl-incf cnt) ncol) - (unless (memq (caar tbl) '(:endgroup :endgrouptag)) - (insert "\n") - (when (or ingroup intaggroup) (insert " "))) - (setq cnt 0))))) - (setq ntable (nreverse ntable)) - (insert "\n") - (goto-char (point-min)) - (unless expert (org-fit-window-to-buffer)) - (setq rtn + ;; Show tags, tag groups, and bindings in a grid. + ;; Each tag in the grid occupies FIELD-WIDTH characters. + ;; The tags are filled up to `window-width'. + (setq field-number 0) + (while (setq tag-binding-spec (pop tag-alist)) + (pcase tag-binding-spec + ;; Display tag groups on starting from a new line. + (`(:startgroup . ,group-name) + (push '() groups) (setq ingroup t) + (unless (zerop field-number) + (setq field-number 0) + (insert "\n")) + (insert (if group-name (format "%s: " group-name) "") "{ ")) + ;; Tag group end is followed by newline. + (`(:endgroup . ,group-name) + (setq ingroup nil field-number 0) + (insert "}" (if group-name (format " (%s) " group-name) "") "\n")) + ;; Group tags start at newline. + (`(:startgrouptag) + (setq intaggroup t) + (unless (zerop field-number) + (setq field-number 0) + (insert "\n")) + (insert "[ ")) + ;; Group tags end with a newline. + (`(:endgrouptag) + (setq intaggroup nil field-number 0) + (insert "]\n")) + (`(:newline) + (unless (zerop field-number) + (setq field-number 0) + (insert "\n") + (setq tag-binding-spec (car tag-alist)) + (while (equal (car tag-alist) '(:newline)) + (insert "\n") + (setq tag-alist (cdr tag-alist))))) + (`(:grouptags) + ;; Previous tag is the tag representing the following group. + ;; It was inserted as "[c] TAG " with spaces filling up + ;; to the field width. Replace the trailing spaces with + ;; " : ", keeping to total field width unchanged. + (delete-char -3) + (insert " : ")) + (_ + (setq current-tag (copy-sequence (car tag-binding-spec))) ; will be modified by side effect + ;; Compute tag binding. + (if (cdr tag-binding-spec) + ;; Custom binding. + (setq current-tag-char (cdr tag-binding-spec)) + ;; No auto-binding. Update `tag-binding-chars-left'. + (unless (or ingroup intaggroup) ; groups are always displayed. + (cl-decf tag-binding-chars-left)) + ;; Automatically assign a character according to the tag string. + (setq auto-tag-char + (string-to-char + (downcase (substring + current-tag (if (= (string-to-char current-tag) ?@) 1 0))))) + (if (or (rassoc auto-tag-char tag-table-local) + (rassoc auto-tag-char tag-table)) + ;; Already bound. Assign first unbound char instead. + (progn + (while (and tag-binding-char-list + (or (rassoc (car tag-binding-char-list) tag-table-local) + (rassoc (car tag-binding-char-list) tag-table))) + (pop tag-binding-char-list)) + (setq current-tag-char (or (car tag-binding-char-list) + ;; Fall back to display "[ ]". + ?\s))) + ;; Can safely use binding derived from the tag string. + (setq current-tag-char auto-tag-char))) + ;; Record all the tags in the group. `:startgroup' + ;; clause earlier added '() to `groups'. + ;; `(car groups)' now contains the tag list for the + ;; current group. + (when ingroup (push current-tag (car groups))) + ;; Compute tag face. + (setq current-tag (org-add-props current-tag nil 'face + (cond + ((not (assoc current-tag tag-table)) + ;; The tag is from TODO-TABLE. + (org-get-todo-face current-tag)) + ((member current-tag current-tags) current-face) + ((member current-tag inherited-tags) inherited-face)))) + (when (equal (caar tag-alist) :grouptags) + (org-add-props current-tag nil 'face 'org-tag-group)) + ;; Respect `org-fast-tag-selection-maximum-tags'. + (when (or ingroup intaggroup (cdr tag-binding-spec) (> tag-binding-chars-left 0)) + ;; Insert the tag. + (when (and (zerop field-number) (not ingroup) (not intaggroup)) (insert " ")) + (insert "[" current-tag-char "] " current-tag + ;; Fill spaces up to FIELD-WIDTH. + (make-string + (- field-width 4 (length current-tag)) ?\ )) + ;; Record tag and the binding/auto-binding. + (push (cons current-tag current-tag-char) tag-table-local) + ;; Last column in the row. + (when (= (cl-incf field-number) (/ (- (window-width) 4) field-width)) + (unless (memq (caar tag-alist) '(:endgroup :endgrouptag)) + (insert "\n") + (when (or ingroup intaggroup) (insert " "))) + (setq field-number 0)))))) + (insert "\n") + ;; Keep the tags in order displayed. Will be used later for sorting. + (setq tag-table-local (nreverse tag-table-local)) + (goto-char (point-min)) + (unless expert-interface (org-fit-window-to-buffer)) + ;; Read user input. + (setq rtn (catch 'exit - (while t + (while t (message "[a-z..]:toggle [SPC]:clear [RET]:accept [TAB]:edit [!] %sgroups%s" (if (not groups) "no " "") - (if expert " [C-c]:window" (if exit-after-next " [C-c]:single" " [C-c]:multi"))) - (setq c (let ((inhibit-quit t)) (read-char-exclusive))) - (setq org-last-tag-selection-key c) - (cond - ((= c ?\r) (throw 'exit t)) - ((= c ?!) - (setq groups (not groups)) - (goto-char (point-min)) - (while (re-search-forward "[{}]" nil t) (replace-match " "))) - ((= c ?\C-c) - (if (not expert) - (org-fast-tag-show-exit - (setq exit-after-next (not exit-after-next))) - (setq expert nil) - (delete-other-windows) - (set-window-buffer (split-window-vertically) " *Org tags*") - (org-switch-to-buffer-other-window " *Org tags*") - (org-fit-window-to-buffer))) - ((or (= c ?\C-g) - (and (= c ?q) (not (rassoc c ntable)))) - (delete-overlay org-tags-overlay) - (setq quit-flag t)) - ((= c ?\ ) - (setq current nil) - (when exit-after-next (setq exit-after-next 'now))) - ((= c ?\t) - (unless tab-tags - (setq tab-tags - (delq nil - (mapcar (lambda (x) - (let ((item (car-safe x))) - (and (stringp item) - (list item)))) - (org--tag-add-to-alist - (with-current-buffer buf - (org-get-buffer-tags)) - table))))) - (setq tg (completing-read "Tag: " tab-tags)) - (when (string-match "\\S-" tg) - (cl-pushnew (list tg) tab-tags :test #'equal) - (if (member tg current) - (setq current (delete tg current)) - (push tg current))) - (when exit-after-next (setq exit-after-next 'now))) - ((setq e (rassoc c todo-table) tg (car e)) - (with-current-buffer buf - (save-excursion (org-todo tg))) - (when exit-after-next (setq exit-after-next 'now))) - ((setq e (rassoc c ntable) tg (car e)) - (if (member tg current) - (setq current (delete tg current)) - (cl-loop for g in groups do - (when (member tg g) - (dolist (x g) (setq current (delete x current))))) - (push tg current)) - (when exit-after-next (setq exit-after-next 'now)))) - - ;; Create a sorted list - (setq current - (sort current + (if expert-interface " [C-c]:window" (if exit-after-next " [C-c]:single" " [C-c]:multi"))) + (setq input-char + (let ((inhibit-quit t)) ; intercept C-g. + (read-char-exclusive))) + ;; FIXME: Global variable used by `org-beamer-select-environment'. + ;; Should factor it out. + (setq org-last-tag-selection-key input-char) + (pcase input-char + ;; + (?\r (throw 'exit t)) + ;; Toggle tag groups. + (?! + (setq groups (not groups)) + (goto-char (point-min)) + (while (re-search-forward "[{}]" nil t) (replace-match " "))) + ;; Toggle expert interface. + (?\C-c + (if (not expert-interface) + (org-fast-tag-show-exit + (setq exit-after-next (not exit-after-next))) + (setq expert-interface nil) + (pop-to-buffer + " *Org tags*" + '((org-display-buffer-split (direction down)))) + (org-fit-window-to-buffer))) + ;; Quit. + ((or ?\C-g + (and ?q (guard (not (rassoc input-char tag-table-local))))) + (delete-overlay org-tags-overlay) + ;; Quit as C-g does. + (keyboard-quit)) + ;; Clear tags. + (?\s + (setq current-tags nil) + (when exit-after-next (setq exit-after-next 'now))) + ;; Use normal completion. + (?\t + ;; Compute completion table, unless already computed. + (unless tab-tags + (setq tab-tags + (delq nil + (mapcar (lambda (x) + (let ((item (car-safe x))) + (and (stringp item) + (list item)))) + ;; Complete using all tags; tags from current buffer first. + (org--tag-add-to-alist + (with-current-buffer origin-buffer + (org-get-buffer-tags)) + tag-table))))) + (setq current-tag (completing-read "Tag: " tab-tags)) + (when (string-match "\\S-" current-tag) + (cl-pushnew (list current-tag) tab-tags :test #'equal) + (setq current-tags (org--add-or-remove-tag current-tag current-tags groups))) + (when exit-after-next (setq exit-after-next 'now))) + ;; INPUT-CHAR is for a todo keyword. + ((let (and todo-keyword (guard todo-keyword)) + (car (rassoc input-char todo-table))) + (with-current-buffer origin-buffer + (save-excursion (org-todo todo-keyword))) + (when exit-after-next (setq exit-after-next 'now))) + ;; INPUT-CHAR is for a tag. + ((let (and tag (guard tag)) + (car (rassoc input-char tag-table-local))) + (setq current-tags (org--add-or-remove-tag tag current-tags groups)) + (when exit-after-next (setq exit-after-next 'now)))) + ;; Create a sorted tag list. + (setq current-tags + (sort current-tags (lambda (a b) - (assoc b (cdr (memq (assoc a ntable) ntable)))))) + ;; b is after a. + ;; `memq' returns tail of the list after the match + the match. + (assoc b (cdr (memq (assoc a tag-table-local) tag-table-local)))))) + ;; Exit when we are set to exit immediately. (when (eq exit-after-next 'now) (throw 'exit t)) + ;; Continue setting tags in the loop. + ;; Update the currently active tags indication in the completion buffer. (goto-char (point-min)) - (beginning-of-line 2) + (forward-line 1) (delete-region (point) (line-end-position)) - (org-fast-tag-insert "Current" current c-face) - (org-set-current-tags-overlay current ov-prefix) + (org-fast-tag-insert "Current" current-tags current-face) + ;; Update the active tags displayed in the overlay in Org buffer. + (org-set-current-tags-overlay current-tags ov-prefix) + ;; Update tag faces in the displayed tag grid. (let ((tag-re (concat "\\[.\\] \\(" org-tag-re "\\)"))) (while (re-search-forward tag-re nil t) (let ((tag (match-string 1))) - (add-text-properties - (match-beginning 1) (match-end 1) - (list 'face + (add-text-properties + (match-beginning 1) (match-end 1) + (list 'face (cond - ((member tag current) c-face) - ((member tag inherited) i-face) - (t 'default))))))) + ((member tag current-tags) current-face) + ((member tag inherited-tags) inherited-face) + (t 'default))))))) (goto-char (point-min))))) - (delete-overlay org-tags-overlay) - (if rtn - (mapconcat 'identity current ":") + ;; Clear the tag overlay in Org buffer. + (delete-overlay org-tags-overlay) + ;; Return the new tag list. + (if rtn + (mapconcat 'identity current-tags ":") nil))))) (defun org-make-tag-string (tags) @@ -12078,24 +12480,26 @@ TAGS is a list of strings." (if (null tags) "" (format ":%s:" (mapconcat #'identity tags ":")))) -(defun org--get-local-tags () - "Return list of tags for the current headline. -Assume point is at the beginning of the headline." - (let* ((cached (and (org-element--cache-active-p) (org-element-at-point nil 'cached))) - (cached-tags (org-element-property :tags cached))) - (if cached - ;; If we do not explicitly copy the result, reference would - ;; be returned and cache element might be modified directly. - (mapcar #'copy-sequence cached-tags) - ;; Parse tags manually. - (and (looking-at org-tag-line-re) - (split-string (match-string-no-properties 2) ":" t))))) - -(defun org-get-tags (&optional pos-or-element local) - "Get the list of tags specified in the current headline. - -When argument POS-OR-ELEMENT is non-nil, retrieve tags for headline at -POS. +(defun org--get-local-tags (&optional epom) + "Return list of tags for headline at EPOM. +When EPOM is non-nil, it should be a marker, point, or element +representing headline." + ;; If we do not explicitly copy the result, reference would + ;; be returned and cache element might be modified directly. + (mapcar + #'copy-sequence + (org-element-property + :tags + (org-element-lineage + (org-element-at-point epom) + '(headline inlinetask) + 'with-self)))) + +(defun org-get-tags (&optional epom local) + "Get the list of tags specified in the headline at EPOM. + +When argument EPOM is non-nil, it should be point, marker, or headline +element. According to `org-use-tag-inheritance', tags may be inherited from parent headlines, and from the whole document, through @@ -12107,62 +12511,41 @@ only the most local tag is returned. However, when optional argument LOCAL is non-nil, only return tags specified at the headline. -Inherited tags have the `inherited' text property." - (save-match-data - (if (and org-trust-scanner-tags - (or (not pos-or-element) (eq pos-or-element (point))) - (not local)) - org-scanner-tags - (org-with-point-at (unless (org-element-type pos-or-element) - (or pos-or-element (point))) - (unless (or (org-element-type pos-or-element) - (org-before-first-heading-p)) - (org-back-to-heading t)) - (let ((ltags (if (org-element-type pos-or-element) - (org-element-property :tags (org-element-lineage pos-or-element '(headline inlinetask) t)) - (org--get-local-tags))) - itags) - (if (or local (not org-use-tag-inheritance)) ltags - (let ((cached (and (org-element--cache-active-p) - (if (org-element-type pos-or-element) - (org-element-lineage pos-or-element '(headline org-data inlinetask) t) - (org-element-at-point nil 'cached))))) - (if cached - (while (setq cached (org-element-property :parent cached)) - (setq itags (nconc (mapcar #'org-add-prop-inherited - ;; If we do explicitly copy the result, reference would - ;; be returned and cache element might be modified directly. - (mapcar #'copy-sequence (org-element-property :tags cached))) - itags))) - (while (org-up-heading-safe) - (setq itags (nconc (mapcar #'org-add-prop-inherited - (org--get-local-tags)) - itags))))) - (setq itags (append org-file-tags itags)) - (nreverse - (delete-dups - (nreverse (nconc (org-remove-uninherited-tags itags) ltags)))))))))) +Inherited tags have the `inherited' text property. + +This function may modify the match data." + (if (and org-trust-scanner-tags + (or (not epom) (eq epom (point))) + (not local)) + org-scanner-tags + (setq epom (org-element-lineage + (org-element-at-point epom) + '(headline inlinetask) + 'with-self)) + (let ((ltags (org--get-local-tags epom)) + itags) + (if (or local (not org-use-tag-inheritance)) ltags + (setq + itags + (mapcar + #'org-add-prop-inherited + (org-element-property-inherited :tags epom nil 'acc))) + (setq itags (append org-file-tags itags)) + (nreverse + (delete-dups + (nreverse (nconc (org-remove-uninherited-tags itags) ltags)))))))) (defun org-get-buffer-tags () "Get a table of all tags used in the buffer, for completion." - (if (org-element--cache-active-p) - ;; `org-element-cache-map' is about 2x faster compared to regexp - ;; search. - (let ((hashed (make-hash-table :test #'equal))) - (org-element-cache-map - (lambda (el) - (dolist (tag (org-element-property :tags el)) - ;; Do not carry over the text properties. They may look - ;; ugly in the completion. - (puthash (list (substring-no-properties tag)) t hashed)))) - (dolist (tag org-file-tags) (puthash (list tag) t hashed)) - (hash-table-keys hashed)) - (org-with-point-at 1 - (let (tags) - (while (re-search-forward org-tag-line-re nil t) - (setq tags (nconc (split-string (match-string-no-properties 2) ":") - tags))) - (mapcar #'list (delete-dups (append org-file-tags tags))))))) + (let ((hashed (make-hash-table :test #'equal))) + (org-element-cache-map + (lambda (el) + (dolist (tag (org-element-property :tags el)) + ;; Do not carry over the text properties. They may look + ;; ugly in the completion. + (puthash (list (substring-no-properties tag)) t hashed)))) + (dolist (tag org-file-tags) (puthash (list tag) t hashed)) + (hash-table-keys hashed))) ;;;; The mapping API @@ -12277,7 +12660,7 @@ a *different* entry, you cannot use these techniques." ;; agenda cache for non-file buffers. (when buffer-file-name (org-agenda-prepare-buffers - (and buffer-file-name (list buffer-file-name)))) + (and buffer-file-name (list (current-buffer))))) (setq res (org-scan-tags func matcher org--matcher-tags-todo-only start-level))) @@ -12376,7 +12759,7 @@ FORCE is non-nil, or return nil." (defun org-at-property-drawer-p () "Non-nil when point is at the first line of a property drawer." (org-with-wide-buffer - (beginning-of-line) + (forward-line 0) (and (looking-at org-property-drawer-re) (or (bobp) (progn @@ -12396,7 +12779,7 @@ FORCE is non-nil, or return nil." "Non-nil when point is inside a property drawer. See `org-property-re' for match data, if applicable." (save-excursion - (beginning-of-line) + (forward-line 0) (and (looking-at org-property-re) (let ((property-drawer (save-match-data (org-get-property-block)))) (and property-drawer @@ -12452,21 +12835,17 @@ variables is set." ;; Maybe update the effort value: (unless (equal current value) (org-entry-put nil org-effort-property value)) - (unless (org-element--cache-active-p) - (org-refresh-property '((effort . identity) - (effort-minutes . org-duration-to-minutes)) - value)) (when (equal (org-get-heading t t t t) (bound-and-true-p org-clock-current-task)) (setq org-clock-effort value) (org-clock-update-mode-line)) (message "%s is now %s" org-effort-property value))) -(defun org-entry-properties (&optional pom which) +(defun org-entry-properties (&optional epom which) "Get all properties of the current entry. -When POM is a buffer position, get all properties from the entry -there instead. +When EPOM is a buffer position, marker, or element, get all properties +from the entry there instead. This includes the TODO keyword, the tags, time strings for deadline, scheduled, and clocking, and any additional properties @@ -12478,7 +12857,7 @@ a string, only get that property. Return value is an alist. Keys are properties, as upcased strings." - (org-with-point-at pom + (org-with-point-at epom (when (and (derived-mode-p 'org-mode) (org-back-to-heading-or-point-min t)) (catch 'exit @@ -12572,8 +12951,8 @@ strings." (member specific '("TIMESTAMP" "TIMESTAMP_IA"))) (let ((find-ts (lambda (end ts) - ;; Fix next time-stamp before END. TS is the - ;; list of time-stamps found so far. + ;; Fix next timestamp before END. TS is the + ;; list of timestamps found so far. (let ((ts ts) (regexp (cond ((string= specific "TIMESTAMP") @@ -12591,8 +12970,8 @@ strings." (let ((object (org-element-context))) ;; Accept to match timestamps in node ;; properties, too. - (when (memq (org-element-type object) - '(node-property timestamp)) + (when (org-element-type-p + object '(node-property timestamp)) (let ((type (org-element-property :type object))) (cond @@ -12664,41 +13043,25 @@ strings." ;; Return value. props))))) -(defun org--property-local-values (property literal-nil &optional element) - "Return value for PROPERTY in current entry or ELEMENT. +(defun org--property-local-values (property literal-nil &optional epom) + "Return value for PROPERTY in current entry or at EPOM. +EPOM can be point, marker, or syntax node. + Value is a list whose car is the base value for PROPERTY and cdr a list of accumulated values. Return nil if neither is found in the entry. Also return nil when PROPERTY is set to \"nil\", unless LITERAL-NIL is non-nil." - (let ((element (or element - (and (org-element--cache-active-p) - (org-element-at-point nil 'cached))))) - (if element - (let* ((element (org-element-lineage element '(headline org-data inlinetask) 'with-self)) - (base-value (org-element-property (intern (concat ":" (upcase property))) element)) - (base-value (if literal-nil base-value (org-not-nil base-value))) - (extra-value (org-element-property (intern (concat ":" (upcase property) "+")) element)) - (extra-value (if (listp extra-value) extra-value (list extra-value))) - (value (cons base-value extra-value))) - (and (not (equal value '(nil))) value)) - (let ((range (org-get-property-block))) - (when range - (goto-char (car range)) - (let* ((case-fold-search t) - (end (cdr range)) - (value - ;; Base value. - (save-excursion - (let ((v (and (re-search-forward - (org-re-property property nil t) end t) - (match-string-no-properties 3)))) - (list (if literal-nil v (org-not-nil v))))))) - ;; Find additional values. - (let* ((property+ (org-re-property (concat property "+") nil t))) - (while (re-search-forward property+ end t) - (push (match-string-no-properties 3) value))) - ;; Return final values. - (and (not (equal value '(nil))) (nreverse value)))))))) + (setq epom + (org-element-lineage + (org-element-at-point epom) + '(headline inlinetask org-data) + 'with-self)) + (let* ((base-value (org-element-property (intern (concat ":" (upcase property) )) epom)) + (extra-value (org-element-property (intern (concat ":" (upcase property) "+")) epom)) + (extra-value (if (listp extra-value) extra-value (list extra-value))) + (value (if literal-nil (cons base-value extra-value) + (cons (org-not-nil base-value) (org-not-nil extra-value))))) + (and (not (equal value '(nil))) value))) (defun org--property-global-or-keyword-value (property literal-nil) "Return value for PROPERTY as defined by global properties or by keyword. @@ -12711,8 +13074,10 @@ globally or by keyword. Also return nil when PROPERTY is set to (assoc-string property org-global-properties-fixed t))))) (if literal-nil global (org-not-nil global)))) -(defun org-entry-get (pom property &optional inherit literal-nil) - "Get value of PROPERTY for entry or content at point-or-marker POM. +(defun org-entry-get (epom property &optional inherit literal-nil) + "Get value of PROPERTY for entry or content at EPOM. + +EPOM is an element, marker, or buffer position. If INHERIT is non-nil and the entry does not have the property, then also check higher levels of the hierarchy. If INHERIT is @@ -12728,21 +13093,20 @@ If LITERAL-NIL is set, return the string value \"nil\" as a string, do not interpret it as the list atom nil. This is used for inheritance when a \"nil\" value can supersede a non-nil value higher up the hierarchy." - (org-with-point-at pom - (cond - ((member-ignore-case property (cons "CATEGORY" org-special-properties)) - ;; We need a special property. Use `org-entry-properties' to - ;; retrieve it, but specify the wanted property. - (cdr (assoc-string property (org-entry-properties nil property)))) - ((and inherit - (or (not (eq inherit 'selective)) (org-property-inherit-p property))) - (org-entry-get-with-inheritance property literal-nil)) - (t - (let* ((local (org--property-local-values property literal-nil)) - (value (and local (mapconcat #'identity - (delq nil local) - (org--property-get-separator property))))) - (if literal-nil value (org-not-nil value))))))) + (cond + ((member-ignore-case property (cons "CATEGORY" org-special-properties)) + ;; We need a special property. Use `org-entry-properties' to + ;; retrieve it, but specify the wanted property. + (cdr (assoc-string property (org-entry-properties epom property)))) + ((and inherit + (or (not (eq inherit 'selective)) (org-property-inherit-p property))) + (org-entry-get-with-inheritance property literal-nil epom)) + (t + (let* ((local (org--property-local-values property literal-nil epom)) + (value (and local (mapconcat #'identity + (delq nil local) + (org--property-get-separator property))))) + (if literal-nil value (org-not-nil value)))))) (defun org-property-or-variable-value (var &optional inherit) "Check if there is a property fixing the value of VAR. @@ -12752,11 +13116,11 @@ If yes, return this value. If not, return the current value of the variable." (read prop) (symbol-value var)))) -(defun org-entry-delete (pom property) - "Delete PROPERTY from entry at point-or-marker POM. +(defun org-entry-delete (epom property) + "Delete PROPERTY from entry at element, point, or marker EPOM. Accumulated properties, i.e. PROPERTY+, are also removed. Return non-nil when a property was removed." - (org-with-point-at pom + (org-with-point-at epom (pcase (org-get-property-block) (`(,begin . ,origin) (let* ((end (copy-marker origin)) @@ -12775,27 +13139,30 @@ non-nil when a property was removed." ;; Multi-values properties are properties that contain multiple values ;; These values are assumed to be single words, separated by whitespace. -(defun org-entry-add-to-multivalued-property (pom property value) - "Add VALUE to the words in the PROPERTY in entry at point-or-marker POM." - (let* ((old (org-entry-get pom property)) +(defun org-entry-add-to-multivalued-property (epom property value) + "Add VALUE to the words in the PROPERTY in entry at EPOM. +EPOM is an element, marker, or buffer position." + (let* ((old (org-entry-get epom property)) (values (and old (split-string old)))) (setq value (org-entry-protect-space value)) (unless (member value values) (setq values (append values (list value))) - (org-entry-put pom property (mapconcat #'identity values " "))))) + (org-entry-put epom property (mapconcat #'identity values " "))))) -(defun org-entry-remove-from-multivalued-property (pom property value) - "Remove VALUE from words in the PROPERTY in entry at point-or-marker POM." - (let* ((old (org-entry-get pom property)) +(defun org-entry-remove-from-multivalued-property (epom property value) + "Remove VALUE from words in the PROPERTY in entry at EPOM. +EPOM is an element, marker, or buffer position." + (let* ((old (org-entry-get epom property)) (values (and old (split-string old)))) (setq value (org-entry-protect-space value)) (when (member value values) (setq values (delete value values)) - (org-entry-put pom property (mapconcat #'identity values " "))))) + (org-entry-put epom property (mapconcat #'identity values " "))))) -(defun org-entry-member-in-multivalued-property (pom property value) - "Is VALUE one of the words in the PROPERTY in entry at point-or-marker POM?" - (let* ((old (org-entry-get pom property)) +(defun org-entry-member-in-multivalued-property (epom property value) + "Is VALUE one of the words in the PROPERTY in EPOM? +EPOM is an element, marker, or buffer position." + (let* ((old (org-entry-get epom property)) (values (and old (split-string old)))) (setq value (org-entry-protect-space value)) (member value values))) @@ -12806,11 +13173,12 @@ non-nil when a property was removed." (values (and value (split-string value)))) (mapcar #'org-entry-restore-space values))) -(defun org-entry-put-multivalued-property (pom property &rest values) - "Set multivalued PROPERTY at point-or-marker POM to VALUES. -VALUES should be a list of strings. Spaces will be protected." - (org-entry-put pom property (mapconcat #'org-entry-protect-space values " ")) - (let* ((value (org-entry-get pom property)) +(defun org-entry-put-multivalued-property (epom property &rest values) + "Set multivalued PROPERTY at EPOM to VALUES. +VALUES should be a list of strings. Spaces will be protected. +EPOM is an element, marker, or buffer position." + (org-entry-put epom property (mapconcat #'org-entry-protect-space values " ")) + (let* ((value (org-entry-get epom property)) (values (and value (split-string value)))) (mapcar #'org-entry-restore-space values))) @@ -12838,80 +13206,55 @@ no match, the marker will point nowhere. Note that also `org-entry-get' calls this function, if the INHERIT flag is set.") -(defun org-entry-get-with-inheritance (property &optional literal-nil element) - "Get PROPERTY of entry or content at point, search higher levels if needed. +(defun org-entry-get-with-inheritance (property &optional literal-nil epom) + "Get PROPERTY of entry or content at EPOM, search higher levels if needed. +EPOM can be a point, marker, or syntax node. The search will stop at the first ancestor which has the property defined. If the value found is \"nil\", return nil to show that the property should be considered as undefined (this is the meaning of nil here). However, if LITERAL-NIL is set, return the string value \"nil\" instead." (move-marker org-entry-property-inherited-from nil) - (org-with-wide-buffer - (let (value at-bob-no-heading) - (catch 'exit - (let ((element (or element - (and (org-element--cache-active-p) - (org-element-at-point nil 'cached)))) - (separator (org--property-get-separator property))) - (if element - (let ((element (org-element-lineage element '(headline org-data inlinetask) 'with-self))) - (while t - (let* ((v (org--property-local-values property literal-nil element)) - (v (if (listp v) v (list v)))) - (when v - (setq value - (concat (mapconcat #'identity (delq nil v) separator) - (and value separator) - value))) - (cond - ((car v) - (move-marker org-entry-property-inherited-from (org-element-property :begin element)) - (throw 'exit nil)) - ((org-element-property :parent element) - (setq element (org-element-property :parent element))) - (t - (let ((global (org--property-global-or-keyword-value property literal-nil))) - (cond ((not global)) - (value (setq value (concat global separator value))) - (t (setq value global)))) - (throw 'exit nil)))))) - (while t - (let ((v (org--property-local-values property literal-nil))) - (when v - (setq value - (concat (mapconcat #'identity (delq nil v) separator) - (and value separator) - value))) - (cond - ((car v) - (org-back-to-heading-or-point-min t) - (move-marker org-entry-property-inherited-from (point)) - (throw 'exit nil)) - ((or (org-up-heading-safe) - (and (not (bobp)) - (goto-char (point-min)) - nil) - ;; `org-up-heading-safe' returned nil. We are at low - ;; level heading or bob. If there is headline - ;; there, do not try to fetch its properties. - (and (bobp) - (not at-bob-no-heading) - (not (org-at-heading-p)) - (setq at-bob-no-heading t)))) - (t - (let ((global (org--property-global-or-keyword-value property literal-nil))) - (cond ((not global)) - (value (setq value (concat global separator value))) - (t (setq value global)))) - (throw 'exit nil)))))))) - (if literal-nil value (org-not-nil value))))) + (let (values found-inherited?) + (org-element-lineage-map + (org-element-at-point epom) + (lambda (el) + (pcase-let ((`(,val . ,val+) + ;; Force LITERAL-NIL t. + (org--property-local-values property t el))) + (if (not val) + ;; PROPERTY+ + (prog1 nil ; keep looking for PROPERTY + (when val+ (setq values (nconc (delq nil val+) values)))) + (setq values (cons val (nconc (delq nil val+) values))) + (move-marker + org-entry-property-inherited-from + (org-element-begin el) + (org-element-property :buffer el)) + ;; Found inherited direct PROPERTY. + (setq found-inherited? t)))) + '(inlinetask headline org-data) + 'with-self 'first-match) + ;; Consider global properties, if we found no PROPERTY (or maybe + ;; only PROPERTY+). + (unless found-inherited? + (when-let* ((global (org--property-global-or-keyword-value + property t))) + (setq values (cons global values)))) + (when values + (setq values (mapconcat + #'identity values + (org--property-get-separator property)))) + (if literal-nil values (org-not-nil values)))) (defvar org-property-changed-functions nil "Hook called when the value of a property has changed. Each hook function should accept two arguments, the name of the property and the new value.") -(defun org-entry-put (pom property value) - "Set PROPERTY to VALUE for entry at point-or-marker POM. +(defun org-entry-put (epom property value) + "Set PROPERTY to VALUE for entry at EPOM. + +EPOM is an element, marker, or buffer position. If the value is nil, it is converted to the empty string. If it is not a string, an error is raised. Also raise an error on @@ -12929,7 +13272,7 @@ decreases scheduled or deadline date by one day." ((not (org--valid-property-p property)) (user-error "Invalid property name: \"%s\"" property))) (org-no-read-only - (org-with-point-at pom + (org-with-point-at epom (if (or (not (featurep 'org-inlinetask)) (org-inlinetask-in-task-p)) (org-back-to-heading-or-point-min t) (org-with-limited-levels (org-back-to-heading-or-point-min t))) @@ -12940,10 +13283,10 @@ decreases scheduled or deadline date by one day." ((not (member value org-todo-keywords-1)) (user-error "\"%s\" is not a valid TODO state" value))) (org-todo value) - (org-align-tags)) + (when org-auto-align-tags (org-align-tags))) ((equal property "PRIORITY") (org-priority (if (org-string-nw-p value) (string-to-char value) ?\s)) - (org-align-tags)) + (when org-auto-align-tags (org-align-tags))) ((equal property "SCHEDULED") (forward-line) (if (and (looking-at-p org-planning-line-re) @@ -13044,7 +13387,7 @@ COLUMN formats in the current buffer." (goto-char (point-min)) (while (re-search-forward "^[ \t]*\\(?:#\\+\\|:\\)COLUMNS:" nil t) (let ((element (org-element-at-point))) - (when (memq (org-element-type element) '(keyword node-property)) + (when (org-element-type-p element '(keyword node-property)) (let ((value (org-element-property :value element)) (start 0)) (while (string-match "%[0-9]*\\([[:alnum:]_-]+\\)\\(([^)]+)\\)?\ @@ -13059,9 +13402,9 @@ COLUMN formats in the current buffer." ;; for each xxx_ALL property, make sure the bare ;; xxx property is also included (delq nil (mapcar (lambda (p) - (and (string-match-p "._ALL\\'" p) - (substring p 0 -4))) - props)))) + (and (string-match-p "._ALL\\'" p) + (substring p 0 -4))) + props)))) (lambda (a b) (string< (upcase a) (upcase b)))))) (defun org-property-values (key) @@ -13097,7 +13440,7 @@ drawer is immediately hidden." (inhibit-read-only t)) (unless (bobp) (insert "\n")) (insert ":PROPERTIES:\n:END:") - (org-fold-region (line-end-position 0) (point) t (if (eq org-fold-core-style 'text-properties) 'drawer 'outline)) + (org-fold-region (line-end-position 0) (point) t 'drawer) (when (or (eobp) (= begin (point-min))) (insert "\n")) (org-indent-region begin (point)))))) @@ -13118,7 +13461,17 @@ Point is left between drawer's boundaries." (or drawer (read-from-minibuffer "Drawer: "))))) (cond ;; With C-u, fall back on `org-insert-property-drawer' - (arg (org-insert-property-drawer)) + (arg + (org-insert-property-drawer) + (org-back-to-heading-or-point-min t) + ;; Move inside. + (re-search-forward org-property-end-re) + (forward-line 0) + (unless (org-element-contents-begin (org-element-at-point)) + ;; Empty drawer. + (insert "\n") + (forward-char -1)) + (org-reveal)) ;; Check validity of suggested drawer's name. ((not (string-match-p org-drawer-regexp (format ":%s:" drawer))) (user-error "Invalid drawer name")) @@ -13135,7 +13488,7 @@ Point is left between drawer's boundaries." (unwind-protect (progn (goto-char rbeg) - (beginning-of-line) + (forward-line 0) (when (save-excursion (re-search-forward org-outline-regexp-bol rend t)) (user-error "Drawers cannot contain headlines")) @@ -13143,7 +13496,7 @@ Point is left between drawer's boundaries." ;; non-blank line in region. Insert drawer's opening ;; there, then indent it. (org-skip-whitespace) - (beginning-of-line) + (forward-line 0) (insert ":" drawer ":\n") (forward-line -1) (indent-for-tab-command) @@ -13155,7 +13508,10 @@ Point is left between drawer's boundaries." (insert "\n:END:") (deactivate-mark t) (indent-for-tab-command) - (unless (eolp) (insert "\n"))) + (unless (eolp) (insert "\n")) + ;; Leave point inside drawer boundaries. + (search-backward ":END:") + (forward-char -1)) ;; Clear marker, whatever the outcome of insertion is. (set-marker rend nil))))))) @@ -13174,23 +13530,27 @@ This is computed according to `org-property-set-functions-alist'." (or (cdr (assoc property org-property-set-functions-alist)) 'org-completing-read)) -(defun org-read-property-value (property &optional pom default) +(defun org-read-property-value (property &optional epom default) "Read value for PROPERTY, as a string. -When optional argument POM is non-nil, completion uses additional -information, i.e., allowed or existing values at point or marker -POM. +When optional argument EPOM is non-nil, completion uses additional +information, i.e., allowed or existing values at element, point, or +marker EPOM. Optional argument DEFAULT provides a default value for PROPERTY." (let* ((completion-ignore-case t) (allowed (or (org-property-get-allowed-values nil property 'table) - (and pom (org-property-get-allowed-values pom property 'table)))) + (and epom (org-property-get-allowed-values epom property 'table)))) (current (org-entry-get nil property)) (prompt (format "%s value%s: " property (if (org-string-nw-p current) (format " [%s]" current) ""))) - (set-function (org-set-property-function property))) + (set-function (org-set-property-function property)) + (default (cond + ((not allowed) default) + ((member default allowed) default) + (t nil)))) (org-trim (if allowed (funcall set-function @@ -13199,10 +13559,10 @@ Optional argument DEFAULT provides a default value for PROPERTY." default nil default) (let ((all (mapcar #'list (append (org-property-values property) - (and pom - (org-with-point-at pom + (and epom + (org-with-point-at epom (org-property-values property))))))) - (funcall set-function prompt all nil nil "" nil current)))))) + (funcall set-function prompt all nil nil default nil current)))))) (defvar org-last-set-property nil) (defvar org-last-set-property-value nil) @@ -13220,7 +13580,7 @@ Optional argument DEFAULT provides a default value for PROPERTY." nil nil nil nil default-prop))) (defun org-set-property-and-value (use-last) - "Allow to set [PROPERTY]: [value] direction from prompt. + "Allow setting [PROPERTY]: [value] direction from prompt. When use-default, don't even ask, just use the last \"[PROPERTY]: [value]\" string from the history." (interactive "P") @@ -13341,14 +13701,15 @@ completion, but that other values should be allowed too. The functions must return nil if they are not responsible for this property.") -(defun org-property-get-allowed-values (pom property &optional table) - "Get allowed values for the property PROPERTY. +(defun org-property-get-allowed-values (epom property &optional table) + "Get allowed values at EPOM for the property PROPERTY. +EPOM can be an element, marker, or buffer position. When TABLE is non-nil, return an alist that can directly be used for completion." (let (vals) (cond ((equal property "TODO") - (setq vals (org-with-point-at pom + (setq vals (org-with-point-at epom (append org-todo-keywords-1 '(""))))) ((equal property "PRIORITY") (let ((n org-priority-lowest)) @@ -13360,7 +13721,7 @@ completion." ((setq vals (run-hook-with-args-until-success 'org-property-allowed-value-functions property))) (t - (setq vals (org-entry-get pom (concat property "_ALL") 'inherit)) + (setq vals (org-entry-get epom (concat property "_ALL") 'inherit)) (when (and vals (string-match "\\S-" vals)) (setq vals (car (read-from-string (concat "(" vals ")")))) (setq vals (mapcar (lambda (x) @@ -13403,14 +13764,9 @@ completion." (org-at-property-p) (replace-match (concat " :" key ": " nval) t t) (org-indent-line) - (beginning-of-line 1) + (forward-line 0) (skip-chars-forward " \t") (when (equal prop org-effort-property) - (unless (org-element--cache-active-p) - (org-refresh-property - '((effort . identity) - (effort-minutes . org-duration-to-minutes)) - nval)) (when (string= org-clock-current-task heading) (setq org-clock-effort nval) (org-clock-update-mode-line))) @@ -13505,9 +13861,10 @@ Return the position where this entry starts, or nil if there is no such entry." (defvar org-last-changed-timestamp nil) (defvar org-last-inserted-timestamp nil - "The last time stamp inserted with `org-insert-time-stamp'.") + "The last time stamp inserted with `org-insert-timestamp'.") -(defun org-time-stamp (arg &optional inactive) +(defalias 'org-time-stamp #'org-timestamp) +(defun org-timestamp (arg &optional inactive) "Prompt for a date/time and insert a time stamp. If the user specifies a time like HH:MM or if this command is @@ -13549,10 +13906,12 @@ non-nil." inactive))))) (cond ((and ts - (memq last-command '(org-time-stamp org-time-stamp-inactive)) - (memq this-command '(org-time-stamp org-time-stamp-inactive))) + (memq last-command '( org-time-stamp org-time-stamp-inactive + org-timestamp org-timestamp-inactive)) + (memq this-command '( org-time-stamp org-time-stamp-inactive + org-timestamp org-timestamp-inactive))) (insert "--") - (org-insert-time-stamp time (or org-time-was-given arg) inactive)) + (org-insert-timestamp time (or org-time-was-given arg) inactive)) (ts ;; Make sure we're on a timestamp. When in the middle of a date ;; range, move arbitrarily to range end. @@ -13561,7 +13920,7 @@ non-nil." (org-at-timestamp-p 'lax)) (replace-match "") (setq org-last-changed-timestamp - (org-insert-time-stamp + (org-insert-timestamp time (or org-time-was-given arg) inactive nil nil (list org-end-time-was-given))) (when repeater @@ -13571,8 +13930,8 @@ non-nil." (concat (substring org-last-inserted-timestamp 0 -1) " " repeater ">"))) (message "Timestamp updated")) - ((equal arg '(16)) (org-insert-time-stamp time t inactive)) - (t (org-insert-time-stamp + ((equal arg '(16)) (org-insert-timestamp time t inactive)) + (t (org-insert-timestamp time (or org-time-was-given arg) inactive nil nil (list org-end-time-was-given)))))) @@ -13593,7 +13952,8 @@ non-nil." (concat t1 "+" (number-to-string dh) (and (/= 0 dm) (format ":%02d" dm))))))) -(defun org-time-stamp-inactive (&optional arg) +(defalias 'org-time-stamp-inactive #'org-timestamp-inactive) +(defun org-timestamp-inactive (&optional arg) "Insert an inactive time stamp. An inactive time stamp is enclosed in square brackets instead of @@ -13608,7 +13968,7 @@ Otherwise, only the date is included. When called with two universal prefix arguments, insert an inactive time stamp with the current time without prompting the user." (interactive "P") - (org-time-stamp arg 'inactive)) + (org-timestamp arg 'inactive)) (defvar org-date-ovl (make-overlay 1 1)) (overlay-put org-date-ovl 'face 'org-date-selected) @@ -13689,10 +14049,10 @@ the time/date that is used for everything that is not specified by the user." (require 'parse-time) (let* ((org-with-time with-time) - (org-time-stamp-rounding-minutes + (org-timestamp-rounding-minutes (if (equal org-with-time '(16)) '(0 0) - org-time-stamp-rounding-minutes)) + org-timestamp-rounding-minutes)) (ct (org-current-time)) (org-def (or org-overriding-default-time default-time ct)) (org-defdecode (decode-time org-def)) @@ -13705,7 +14065,11 @@ user." (calendar-view-holidays-initially-flag nil) ans (org-ans0 "") org-ans1 org-ans2 final cal-frame) ;; Rationalize `org-def' and `org-defdecode', if required. - (when (< (nth 2 org-defdecode) org-extend-today-until) + ;; Only consider `org-extend-today-until' when explicit reference + ;; time is not given. + (when (and (not default-time) + (not org-overriding-default-time) + (< (nth 2 org-defdecode) org-extend-today-until)) (setf (nth 2 org-defdecode) -1) (setf (nth 1 org-defdecode) 59) (setq org-def (org-encode-time org-defdecode)) @@ -13723,7 +14087,7 @@ user." (calendar) (when (eq calendar-setup 'calendar-only) (setq cal-frame - (window-frame (get-buffer-window "*Calendar*" 'visible))) + (window-frame (get-buffer-window calendar-buffer 'visible))) (select-frame cal-frame)) (org-eval-in-calendar '(setq cursor-type nil) t) (unwind-protect @@ -13759,7 +14123,7 @@ user." (when org-read-date-overlay (delete-overlay org-read-date-overlay) (setq org-read-date-overlay nil))))) - (bury-buffer "*Calendar*") + (bury-buffer calendar-buffer) (when cal-frame (delete-frame cal-frame) (select-frame-set-input-focus cur-frame)))))) @@ -13828,6 +14192,9 @@ user." (setq txt (concat txt " (=>F)"))) (setq org-read-date-overlay (make-overlay (1- (line-end-position)) (line-end-position))) + ;; Avoid priority race with overlay used by calendar.el. + ;; See bug#69271. + (overlay-put org-read-date-overlay 'priority 1) (org-overlay-display org-read-date-overlay txt 'secondary-selection))))) (defun org-read-date-analyze (ans def defdecode) @@ -14027,6 +14394,7 @@ user." (unless deltadef (let ((now (decode-time))) (setq day (nth 3 now) month (nth 4 now) year (nth 5 now)))) + ;; FIXME: Duplicated value in ‘cond’: "" (cond ((member deltaw '("h" "")) (when (boundp 'org-time-was-given) (setq org-time-was-given t)) @@ -14116,7 +14484,7 @@ user function argument order change dependent on argument order." Unless KEEPDATE is non-nil, update `org-ans2' to the cursor date." (let ((sf (selected-frame)) (sw (selected-window))) - (select-window (get-buffer-window "*Calendar*" t)) + (select-window (get-buffer-window calendar-buffer t)) (eval form t) (when (and (not keepdate) (calendar-cursor-to-date)) (let* ((date (calendar-cursor-to-date)) @@ -14126,6 +14494,92 @@ Unless KEEPDATE is non-nil, update `org-ans2' to the cursor date." (select-window sw) (select-frame-set-input-focus sf))) +(defun org-calendar-goto-today-or-insert-dot () + "Go to the current date, or insert a dot. + +If at the beginning of the prompt, behave as `org-calendar-goto-today' else +insert \".\"." + (interactive) + ;; Are we at the beginning of the prompt? + (if (looking-back "^[^:]+: " + (let ((inhibit-field-text-motion t)) + (line-beginning-position))) + (org-eval-in-calendar '(calendar-goto-today)) + (insert "."))) + +(defun org-calendar-goto-today () + "Reposition the calendar window so the current date is visible." + (interactive) + (org-eval-in-calendar '(calendar-goto-today))) + +(defun org-calendar-backward-month () + "Move the cursor backward by one month." + (interactive) + (org-eval-in-calendar '(calendar-backward-month 1))) + +(defun org-calendar-forward-month () + "Move the cursor forward by one month." + (interactive) + (org-eval-in-calendar '(calendar-forward-month 1))) + +(defun org-calendar-backward-year () + "Move the cursor backward by one year." + (interactive) + (org-eval-in-calendar '(calendar-backward-year 1))) + +(defun org-calendar-forward-year () + "Move the cursor forward by one year." + (interactive) + (org-eval-in-calendar '(calendar-forward-year 1))) + +(defun org-calendar-backward-week () + "Move the cursor backward by one week." + (interactive) + (org-eval-in-calendar '(calendar-backward-week 1))) + +(defun org-calendar-forward-week () + "Move the cursor forward by one week." + (interactive) + (org-eval-in-calendar '(calendar-forward-week 1))) + +(defun org-calendar-backward-day () + "Move the cursor backward by one day." + (interactive) + (org-eval-in-calendar '(calendar-backward-day 1))) + +(defun org-calendar-forward-day () + "Move the cursor forward by one day." + (interactive) + (org-eval-in-calendar '(calendar-forward-day 1))) + +(defun org-calendar-view-entries () + "Prepare and display a buffer with diary entries." + (interactive) + (org-eval-in-calendar '(diary-view-entries)) + (message "")) + +(defun org-calendar-scroll-month-left () + "Scroll the displayed calendar left by one month." + (interactive) + (org-eval-in-calendar '(calendar-scroll-left 1))) + +(defun org-calendar-scroll-month-right () + "Scroll the displayed calendar right by one month." + (interactive) + (org-eval-in-calendar '(calendar-scroll-right 1))) + +(defun org-calendar-scroll-three-months-left () + "Scroll the displayed calendar left by three months." + (interactive) + (org-eval-in-calendar + '(calendar-scroll-left-three-months 1))) + +(defun org-calendar-scroll-three-months-right () + "Scroll the displayed calendar right by three months." + (interactive) + (org-eval-in-calendar + '(calendar-scroll-right-three-months 1))) + (defun org-calendar-select () "Return to `org-read-date' with the date currently selected. This is used by `org-read-date' in a temporary keymap for the calendar buffer." @@ -14136,7 +14590,8 @@ This is used by `org-read-date' in a temporary keymap for the calendar buffer." (setq org-ans1 (format-time-string "%Y-%m-%d" time))) (when (active-minibuffer-window) (exit-minibuffer)))) -(defun org-insert-time-stamp (time &optional with-hm inactive pre post extra) +(defalias 'org-insert-time-stamp #'org-insert-timestamp) +(defun org-insert-timestamp (time &optional with-hm inactive pre post extra) "Insert a date stamp for the date given by the internal TIME. See `format-time-string' for the format of TIME. WITH-HM means use the stamp format that includes the time of the day. @@ -14163,7 +14618,8 @@ The command returns the inserted time stamp." (insert-before-markers-and-inherit (or post "")) (setq org-last-inserted-timestamp stamp)))) -(defun org-toggle-time-stamp-overlays () +(defalias 'org-toggle-time-stamp-overlays #'org-toggle-timestamp-overlays) +(defun org-toggle-timestamp-overlays () "Toggle the use of custom time stamp formats." (interactive) (setq org-display-custom-times (not org-display-custom-times)) @@ -14205,7 +14661,8 @@ Don't touch the rest." (let ((n 0)) (mapcar (lambda (x) (if (< (setq n (1+ n)) 7) (or x 0) x)) time))) -(defun org-time-stamp-to-now (timestamp-string &optional seconds) +(defalias 'org-time-stamp-to-now #'org-timestamp-to-now) +(defun org-timestamp-to-now (timestamp-string &optional seconds) "Difference between TIMESTAMP-STRING and now in days. If SECONDS is non-nil, return the difference in seconds." (let ((fdiff (if seconds #'float-time #'time-to-days))) @@ -14215,7 +14672,7 @@ If SECONDS is non-nil, return the difference in seconds." (defun org-deadline-close-p (timestamp-string &optional ndays) "Is the time in TIMESTAMP-STRING close to the current date?" (setq ndays (or ndays (org-get-wdays timestamp-string))) - (and (<= (org-time-stamp-to-now timestamp-string) ndays) + (and (<= (org-timestamp-to-now timestamp-string) ndays) (not (org-entry-is-done-p)))) (defun org-get-wdays (ts &optional delay zero-delay) @@ -14283,7 +14740,7 @@ Allowed values for TYPE are: inactive: only inactive timestamps ([...]) scheduled: only scheduled timestamps deadline: only deadline timestamps - closed: only closed time-stamps + closed: only closed timestamps When TYPE is nil, fall back on returning a regexp that matches both scheduled and deadline timestamps." @@ -14309,10 +14766,11 @@ both scheduled and deadline timestamps." (lambda () (let ((match (match-string 1))) (and (if (memq ts-type '(active inactive all)) - (eq (org-element-type (save-excursion - (backward-char) - (org-element-context))) - 'timestamp) + (org-element-type-p + (save-excursion + (backward-char) + (org-element-context)) + 'timestamp) (org-at-planning-p)) (time-less-p (org-time-string-to-time match) @@ -14331,14 +14789,15 @@ both scheduled and deadline timestamps." (lambda () (let ((match (match-string 1))) (and (if (memq ts-type '(active inactive all)) - (eq (org-element-type (save-excursion - (backward-char) - (org-element-context))) - 'timestamp) + (org-element-type-p + (save-excursion + (backward-char) + (org-element-context)) + 'timestamp) (org-at-planning-p)) (not (time-less-p - (org-time-string-to-time match) - (org-time-string-to-time d)))))))) + (org-time-string-to-time match) + (org-time-string-to-time d)))))))) (message "%d entries after %s" (org-occur regexp nil callback) d))) @@ -14355,14 +14814,15 @@ both scheduled and deadline timestamps." (let ((match (match-string 1))) (and (if (memq type '(active inactive all)) - (eq (org-element-type (save-excursion - (backward-char) - (org-element-context))) - 'timestamp) + (org-element-type-p + (save-excursion + (backward-char) + (org-element-context)) + 'timestamp) (org-at-planning-p)) (not (time-less-p - (org-time-string-to-time match) - (org-time-string-to-time start-date))) + (org-time-string-to-time match) + (org-time-string-to-time start-date))) (time-less-p (org-time-string-to-time match) (org-time-string-to-time end-date)))))))) @@ -14385,7 +14845,7 @@ days in order to avoid rounding problems." (goto-char (line-beginning-position)) (re-search-forward org-tr-regexp-both (line-end-position) t)) (unless (org-at-date-range-p t) - (user-error "Not at a time-stamp range, and none found in current line"))) + (user-error "Not at a timestamp range, and none found in current line"))) (let* ((ts1 (match-string 1)) (ts2 (match-string 2)) (havetime (or (> (length ts1) 15) (> (length ts2) 15))) @@ -14564,19 +15024,20 @@ This uses the icalendar.el library." (tmpfile (make-temp-name (expand-file-name "orgics" tmpdir))) buf rtn b e) - (with-current-buffer frombuf - (icalendar-export-region (point-min) (point-max) tmpfile) - (setq buf (find-buffer-visiting tmpfile)) - (set-buffer buf) - (goto-char (point-min)) - (when (re-search-forward "^BEGIN:VEVENT" nil t) - (setq b (match-beginning 0))) - (goto-char (point-max)) - (when (re-search-backward "^END:VEVENT" nil t) - (setq e (match-end 0))) - (setq rtn (if (and b e) (concat (buffer-substring b e) "\n") ""))) - (kill-buffer buf) - (delete-file tmpfile) + (unwind-protect + (with-current-buffer frombuf + (icalendar-export-region (point-min) (point-max) tmpfile) + (setq buf (find-buffer-visiting tmpfile)) + (set-buffer buf) + (goto-char (point-min)) + (when (re-search-forward "^BEGIN:VEVENT" nil t) + (setq b (match-beginning 0))) + (goto-char (point-max)) + (when (re-search-backward "^END:VEVENT" nil t) + (setq e (match-end 0))) + (setq rtn (if (and b e) (concat (buffer-substring b e) "\n") ""))) + (when (and buf (buffer-live-p buf)) (kill-buffer buf)) + (delete-file tmpfile)) rtn)) (defun org-closest-date (start current prefer) @@ -14751,12 +15212,12 @@ is considered `day' (i.e. only `bracket', `day', and `after' return values are possible). When matching, the match groups are the following: - group 1: year, if any - group 2: month, if any - group 3: day number, if any - group 4: day name, if any - group 5: hours, if any - group 6: minutes, if any" + group 2: year, if any + group 3: month, if any + group 4: day number, if any + group 5: day name, if any + group 7: hours, if any + group 8: minutes, if any" (let* ((regexp (if extended (if (eq extended 'agenda) @@ -14818,7 +15279,9 @@ When matching, the match groups are the following: (defun org-at-clock-log-p () "Non-nil if point is on a clock log line." (and (org-match-line org-clock-line-re) - (eq (org-element-type (save-match-data (org-element-at-point))) 'clock))) + (org-element-type-p + (save-match-data (org-element-at-point)) + 'clock))) (defvar org-clock-history) ; defined in org-clock.el (defvar org-clock-adjust-closest nil) ; defined in org-clock.el @@ -14830,7 +15293,7 @@ The date is changed by N times WHAT. WHAT can be `day', `month', position in the timestamp determines what is changed. When optional argument UPDOWN is non-nil, minutes are rounded -according to `org-time-stamp-rounding-minutes'. +according to `org-timestamp-rounding-minutes'. When SUPPRESS-TMP-DELAY is non-nil, suppress delays like \"--2d\"." @@ -14838,14 +15301,14 @@ When SUPPRESS-TMP-DELAY is non-nil, suppress delays like (timestamp? (org-at-timestamp-p 'lax)) origin-cat with-hm inactive - (dm (max (nth 1 org-time-stamp-rounding-minutes) 1)) + (dm (max (nth 1 org-timestamp-rounding-minutes) 1)) extra rem ts time time0 fixnext clrgx) (unless timestamp? (user-error "Not at a timestamp")) (if (and (not what) (eq timestamp? 'bracket)) (org-toggle-timestamp-type) - ;; Point isn't on brackets. Remember the part of the time-stamp - ;; the point was in. Indeed, size of time-stamps may change, + ;; Point isn't on brackets. Remember the part of the timestamp + ;; the point was in. Indeed, size of timestamps may change, ;; but point must be kept in the same category nonetheless. (setq origin-cat timestamp?) (when (and (not what) (not (eq timestamp? 'day)) @@ -14856,6 +15319,12 @@ When SUPPRESS-TMP-DELAY is non-nil, suppress delays like (setq timestamp? (or what timestamp?) inactive (= (char-after (match-beginning 0)) ?\[) ts (match-string 0)) + ;; FIXME: Instead of deleting everything and then inserting + ;; later, we should make use of `replace-match', which preserves + ;; markers. The current implementation suffers from + ;; `save-excursion' not preserving point inside the timestamp + ;; once we delete the timestamp here. The point moves to the + ;; updated timestamp end. (replace-match "") (when (string-match "\\(\\(-[012][0-9]:[0-5][0-9]\\)?\\( +[.+]?-?[-+][0-9]+[hdwmy]\\(/[0-9]+[hdwmy]\\)?\\)*\\)[]>]" @@ -14866,30 +15335,42 @@ When SUPPRESS-TMP-DELAY is non-nil, suppress delays like (when (string-match "^.\\{10\\}.*?[0-9]+:[0-9][0-9]" ts) (setq with-hm t)) (setq time0 (org-parse-time-string ts)) - (when (and updown - (eq timestamp? 'minute) - (not current-prefix-arg)) - ;; This looks like s-up and s-down. Change by one rounding step. - (setq n (* dm (cond ((> n 0) 1) ((< n 0) -1) (t 0)))) - (unless (= 0 (setq rem (% (nth 1 time0) dm))) - (setcar (cdr time0) (+ (nth 1 time0) - (if (> n 0) (- rem) (- dm rem)))))) - (setq time - (org-encode-time - (apply #'list - (or (car time0) 0) - (+ (if (eq timestamp? 'minute) n 0) (nth 1 time0)) - (+ (if (eq timestamp? 'hour) n 0) (nth 2 time0)) - (+ (if (eq timestamp? 'day) n 0) (nth 3 time0)) - (+ (if (eq timestamp? 'month) n 0) (nth 4 time0)) - (+ (if (eq timestamp? 'year) n 0) (nth 5 time0)) - (nthcdr 6 time0)))) + (let ((increment n)) + (if (and updown + (eq timestamp? 'minute) + (not current-prefix-arg)) + ;; This looks like s-up and s-down. Change by one rounding step. + (progn + (setq increment (* dm (cond ((> n 0) 1) ((< n 0) -1) (t 0)))) + (unless (= 0 (setq rem (% (nth 1 time0) dm))) + (setcar (cdr time0) (+ (nth 1 time0) + (if (> n 0) (- rem) (- dm rem)))))) + ;; Do not round anything in `org-modify-ts-extra' when prefix + ;; argument is supplied - just use whatever is provided by the + ;; prefix argument. + (setq dm 1)) + (setq time + (org-encode-time + (apply #'list + (or (car time0) 0) + (+ (if (eq timestamp? 'minute) increment 0) (nth 1 time0)) + (+ (if (eq timestamp? 'hour) increment 0) (nth 2 time0)) + (+ (if (eq timestamp? 'day) increment 0) (nth 3 time0)) + (+ (if (eq timestamp? 'month) increment 0) (nth 4 time0)) + (+ (if (eq timestamp? 'year) increment 0) (nth 5 time0)) + (nthcdr 6 time0))))) (when (and (memq timestamp? '(hour minute)) extra (string-match "-\\([012][0-9]\\):\\([0-5][0-9]\\)" extra)) + ;; When modifying the start time in HH:MM-HH:MM range, update + ;; end time as well. (setq extra (org-modify-ts-extra - extra - (if (eq timestamp? 'hour) 2 5) + extra ;; -HH:MM ... + ;; Fake position in EXTRA to force changing hours + ;; or minutes as needed. + (if (eq timestamp? 'hour) + 2 ;; -H:MM + 5) ;; -HH:M n dm))) (when (integerp timestamp?) (setq extra (org-modify-ts-extra extra timestamp? n dm))) @@ -14902,13 +15383,13 @@ When SUPPRESS-TMP-DELAY is non-nil, suppress delays like (setcar (nthcdr 1 time0) (or (nth 1 time0) 0)) (setcar (nthcdr 2 time0) (or (nth 2 time0) 0)) (setq time (org-encode-time time0)))) - ;; Insert the new time-stamp, and ensure point stays in the same + ;; Insert the new timestamp, and ensure point stays in the same ;; category as before (i.e. not after the last position in that ;; category). (let ((pos (point))) ;; Stay before inserted string. `save-excursion' is of no use. (setq org-last-changed-timestamp - (org-insert-time-stamp time with-hm inactive nil nil extra)) + (org-insert-timestamp time with-hm inactive nil nil extra)) (goto-char pos)) (save-match-data (looking-at org-ts-regexp3) @@ -14920,8 +15401,8 @@ When SUPPRESS-TMP-DELAY is non-nil, suppress delays like (`hour (min (match-end 7) origin)) (`minute (min (1- (match-end 8)) origin)) ((pred integerp) (min (1- (match-end 0)) origin)) - ;; Point was right after the time-stamp. However, the - ;; time-stamp length might have changed, so refer to + ;; Point was right after the timestamp. However, the + ;; timestamp length might have changed, so refer to ;; (match-end 0) instead. (`after (match-end 0)) ;; `year' and `month' have both fixed size: point couldn't @@ -14965,50 +15446,69 @@ When SUPPRESS-TMP-DELAY is non-nil, suppress delays like (org-get-heading t t))))))))) ;; Try to recenter the calendar window, if any. (when (and org-calendar-follow-timestamp-change - (get-buffer-window "*Calendar*" t) + (get-buffer-window calendar-buffer t) (memq timestamp? '(day month year))) (org-recenter-calendar (time-to-days time)))))) -(defun org-modify-ts-extra (s pos n dm) - "Change the different parts of the lead-time and repeat fields in timestamp." - (let ((idx '(("d" . 0) ("w" . 1) ("m" . 2) ("y" . 3) ("d" . -1) ("y" . 4))) - ng h m new rem) - (when (string-match "\\(-\\([012][0-9]\\):\\([0-5][0-9]\\)\\)?\\( +\\+\\([0-9]+\\)\\([dmwy]\\)\\)?\\( +-\\([0-9]+\\)\\([dmwy]\\)\\)?" s) +(defun org-modify-ts-extra (ts-string pos nincrements increment-step) + "Change the lead-time/repeat fields at POS in timestamp string TS-STRING. +POS is the position in the timestamp string to be changed. +NINCREMENTS is the number of increments/decrements. + +INCREMENT-STEP is step used for a single increment when POS in on +minutes. Before incrementing minutes, they are rounded to +INCREMENT-STEP divisor." + (let (;; increment order for dwmy: d-1=d; d+1=w; w+1=m; m+1=y; y+1=y. + (idx '(("d" . 0) ("w" . 1) ("m" . 2) ("y" . 3) ("d" . -1) ("y" . 4))) + pos-match-group hour minute new rem) + (when (string-match "\\(-\\([012][0-9]\\):\\([0-5][0-9]\\)\\)?\\( +\\+\\([0-9]+\\)\\([dmwy]\\)\\)?\\( +-\\([0-9]+\\)\\([dmwy]\\)\\)?" ts-string) (cond - ((or (org-pos-in-match-range pos 2) - (org-pos-in-match-range pos 3)) - (setq m (string-to-number (match-string 3 s)) - h (string-to-number (match-string 2 s))) - (if (org-pos-in-match-range pos 2) - (setq h (+ h n)) - (setq n (* dm (with-no-warnings (cl-signum n)))) - (unless (= 0 (setq rem (% m dm))) - (setq m (+ m (if (> n 0) (- rem) (- dm rem))))) - (setq m (+ m n))) - (when (< m 0) (setq m (+ m 60) h (1- h))) - (when (> m 59) (setq m (- m 60) h (1+ h))) - (setq h (mod h 24)) - (setq ng 1 new (format "-%02d:%02d" h m))) - ((org-pos-in-match-range pos 6) - (setq ng 6 new (car (rassoc (+ n (cdr (assoc (match-string 6 s) idx))) idx)))) - ((org-pos-in-match-range pos 5) - (setq ng 5 new (format "%d" (max 1 (+ n (string-to-number (match-string 5 s))))))) - - ((org-pos-in-match-range pos 9) - (setq ng 9 new (car (rassoc (+ n (cdr (assoc (match-string 9 s) idx))) idx)))) - ((org-pos-in-match-range pos 8) - (setq ng 8 new (format "%d" (max 0 (+ n (string-to-number (match-string 8 s)))))))) - - (when ng - (setq s (concat - (substring s 0 (match-beginning ng)) - new - (substring s (match-end ng)))))) - s)) + ((or (org-pos-in-match-range pos 2) ;; POS in end hours + (org-pos-in-match-range pos 3)) ;; POS in end minutes + (setq minute (string-to-number (match-string 3 ts-string)) + hour (string-to-number (match-string 2 ts-string))) + (if (org-pos-in-match-range pos 2) ;; POS in end hours + ;; INCREMENT-STEP is only applicable to MINUTE. + (setq hour (+ hour nincrements)) + (setq nincrements (* increment-step nincrements)) + (unless (= 0 (setq rem (% minute increment-step))) + ;; Round the MINUTE to INCREMENT-STEP. + (setq minute (+ minute (if (> nincrements 0) (- rem) (- increment-step rem))))) + (setq minute (+ minute nincrements))) + (when (< minute 0) (setq minute (+ minute 60) hour (1- hour))) + (when (> minute 59) (setq minute (- minute 60) hour (1+ hour))) + (setq hour (mod hour 24)) + (setq pos-match-group 1 + new (format "-%02d:%02d" hour minute))) + + ((org-pos-in-match-range pos 6) ;; POS on "dmwy" repeater char. + (setq pos-match-group 6 + new (car (rassoc (+ nincrements (cdr (assoc (match-string 6 ts-string) idx))) idx)))) + + ((org-pos-in-match-range pos 5) ;; POS on X in "Xd" repeater. + (setq pos-match-group 5 + ;; Never drop below X=1. + new (format "%d" (max 1 (+ nincrements (string-to-number (match-string 5 ts-string))))))) + + ((org-pos-in-match-range pos 9) ;; POS on "dmwy" repeater in warning interval. + (setq pos-match-group 9 + new (car (rassoc (+ nincrements (cdr (assoc (match-string 9 ts-string) idx))) idx)))) + + ((org-pos-in-match-range pos 8) ;; POS on X in "Xd" in warning interval. + (setq pos-match-group 8 + ;; Never drop below X=0. + new (format "%d" (max 0 (+ nincrements (string-to-number (match-string 8 ts-string)))))))) + + (when pos-match-group + (setq ts-string (concat + (substring ts-string 0 (match-beginning pos-match-group)) + new + (substring ts-string (match-end pos-match-group)))))) + ts-string)) (defun org-recenter-calendar (d) "If the calendar is visible, recenter it to date D." - (let ((cwin (get-buffer-window "*Calendar*" t))) + (let ((cwin (get-buffer-window calendar-buffer t))) (when cwin (let ((calendar-move-hook nil)) (with-selected-window cwin @@ -15035,7 +15535,7 @@ A prefix ARG can be used to force the current date." (defun org-get-date-from-calendar () "Return a list (month day year) of date at point in calendar." - (with-current-buffer "*Calendar*" + (with-current-buffer calendar-buffer (save-match-data (calendar-cursor-to-date)))) @@ -15046,7 +15546,7 @@ If there is already a time stamp at the cursor position, update it." (if (org-at-timestamp-p 'lax) (org-timestamp-change 0 'calendar) (let ((cal-date (org-get-date-from-calendar))) - (org-insert-time-stamp + (org-insert-timestamp (org-encode-time 0 0 0 (nth 1 cal-date) (car cal-date) (nth 2 cal-date)))))) (defcustom org-image-actual-width t @@ -15062,10 +15562,29 @@ When set to a number in a list, try to get the width from any and fall back on that number if none is found. -When set to nil, try to get the width from an #+ATTR.* keyword -and fall back on the original width if none is found. +When set to nil, first try to get the width from #+ATTR_ORG. If +that is not found, use the first #+ATTR_xxx :width specification. +If that is also not found, fall back on the original image width. + +Finally, Org mode is quite flexible in the width specifications it +supports and intelligently interprets width specifications for other +backends when rendering an image in an org buffer. This behavior is +described presently. -When set to any other non-nil value, always use the image width. +1. A floating point value between 0 and 2 is interpreted as the + percentage of the text area that should be taken up by the image. +2. A number followed by a percent sign is divided by 100 and then + interpreted as a floating point value. +3. If a number is followed by other text, extract the number and + discard the remaining text. That number is then interpreted as a + floating-point value. For example, + + #+ATTR_LATEX: :width 0.7\\linewidth + + would be interpreted as 70% of the text width. +4. If t is provided the original image width is used. This is useful + when you want to specify a width for a backend, but still want to + use the original image width in the org buffer. This requires Emacs >= 24.1, built with imagemagick support." :group 'org-appearance @@ -15077,6 +15596,26 @@ This requires Emacs >= 24.1, built with imagemagick support." (list :tag "Use #+ATTR* or a number of pixels" (integer)) (const :tag "Use #+ATTR* or don't resize" nil))) +(defcustom org-image-max-width 'fill-column + "When non-nil, limit the displayed image width. +This setting only takes effect when `org-image-actual-width' is set to +t or when #+ATTR* is set to t. + +Possible values: +- `fill-column' :: limit width to `fill-column' +- `window' :: limit width to window width +- integer :: limit width to number in pixels +- float :: limit width to that fraction of window width +- nil :: do not limit image width" + :group 'org-appearance + :package-version '(Org . "9.7") + :type '(choice + (const :tag "Do not limit image width" nil) + (const :tag "Limit to `fill-column'" fill-column) + (const :tag "Limit to window width" window) + (integer :tag "Limit to a number of pixels") + (float :tag "Limit to a fraction of window width"))) + (defcustom org-agenda-inhibit-startup nil "Inhibit startup when preparing agenda buffers. When this variable is t, the initialization of the Org agenda @@ -15092,15 +15631,10 @@ Properties are used to prepare buffers for effort estimates, appointments, statistics and subtree-local categories. If you don't use these in the agenda, you can add them to this list and agenda building will be a bit faster. -The value is a list, with zero or more of the symbols `effort', `appt', -`stats' or `category'." +The value is a list, with symbol `stats'." :type '(set :greedy t - (const effort) - (const appt) - (const stats) - (const category)) - :version "26.1" - :package-version '(Org . "8.3") + (const stats)) + :package-version '(Org . "9.7") :group 'org-agenda) ;;;; Files @@ -15186,7 +15720,7 @@ used by the agenda files. If ARCHIVE is `ifmode', do this only if (when (or (eq archives t) (and (eq archives 'ifmode) (eq org-agenda-archives-mode t))) (setq files (org-add-archive-files files))) - files)) + (delete-dups files))) (defun org-agenda-file-p (&optional file) "Return non-nil, if FILE is an agenda file. @@ -15383,15 +15917,8 @@ When a buffer is unmodified, it is just killed. When modified, it is saved (org-get-agenda-file-buffer file)) (org-with-wide-buffer (org-set-regexps-and-options 'tags-only) - (or (memq 'category org-agenda-ignore-properties) - (org-refresh-category-properties)) (or (memq 'stats org-agenda-ignore-properties) (org-refresh-stats-properties)) - (or (memq 'effort org-agenda-ignore-properties) - (unless org-element-use-cache - (org-refresh-effort-properties))) - (or (memq 'appt org-agenda-ignore-properties) - (org-refresh-properties "APPT_WARNTIME" 'org-appt-warntime)) (dolist (el org-todo-keywords-1) (unless (member el org-todo-keywords-for-agenda) (push el org-todo-keywords-for-agenda))) @@ -15440,34 +15967,40 @@ in Org mode. \\{org-cdlatex-mode-map}" :lighter " OCDL" (when org-cdlatex-mode - (require 'cdlatex) + ;; Try to load texmathp before cdlatex. Otherwise, cdlatex can + ;; bind `cdlatex--texmathp' to `ignore', not using `texmathp' at + ;; all. + (org-require-package 'texmathp "Auctex") + (org-require-package 'cdlatex) (run-hooks 'cdlatex-mode-hook) (cdlatex-compute-tables)) (unless org-cdlatex-texmathp-advice-is-done (setq org-cdlatex-texmathp-advice-is-done t) - (advice-add 'texmathp :around #'org--math-always-on))) + (advice-add 'texmathp :around #'org--math-p))) + +(defun org--math-p (orig-fun &rest args) + "Return t inside math fragments or running `cdlatex-math-symbol'. +This function is intended to be an :around advice for `texmathp'. -(defun org--math-always-on (orig-fun &rest args) - "Always return t in Org buffers. -This is because we want to insert math symbols without dollars even outside -the LaTeX math segments. If Org mode thinks that point is actually inside -an embedded LaTeX fragment, let `texmathp' do its job. +If Org mode thinks that point is actually inside +an embedded LaTeX environment, return t when the environment is math +or let `texmathp' do its job otherwise. `\\[org-cdlatex-mode-map]'" - (interactive) (cond ((not (derived-mode-p 'org-mode)) (apply orig-fun args)) ((eq this-command 'cdlatex-math-symbol) (setq texmathp-why '("cdlatex-math-symbol in org-mode" . 0)) t) (t - (let ((p (org-inside-LaTeX-fragment-p))) - (when p ;; FIXME: Shouldn't we return t when `p' is nil? - (if (member (car p) - (plist-get org-format-latex-options :matchers)) - (progn - (setq texmathp-why '("Org mode embedded math" . 0)) - t) - (apply orig-fun args))))))) + (let ((element (org-element-context))) + (when (org-inside-LaTeX-fragment-p element) + (pcase (substring-no-properties + (org-element-property :value element) + 0 2) + ((or "\\(" "\\[" (pred (string-match-p (rx string-start "$")))) + (setq texmathp-why '("Org mode embedded math" . 0)) + t) + (_ (apply orig-fun args)))))))) (defun turn-on-org-cdlatex () "Unconditionally turn on `org-cdlatex-mode'." @@ -15570,50 +16103,14 @@ environment remains unintended." ;;;; LaTeX fragments -(defun org-inside-LaTeX-fragment-p () - "Test if point is inside a LaTeX fragment. -I.e. after a \\begin, \\(, \\[, $, or $$, without the corresponding closing -sequence appearing also before point. -Even though the matchers for math are configurable, this function assumes -that \\begin, \\(, \\[, and $$ are always used. Only the single dollar -delimiters are skipped when they have been removed by customization. -The return value is nil, or a cons cell with the delimiter and the -position of this delimiter. - -This function does a reasonably good job, but can locally be fooled by -for example currency specifications. For example it will assume being in -inline math after \"$22.34\". The LaTeX fragment formatter will only format -fragments that are properly closed, but during editing, we have to live -with the uncertainty caused by missing closing delimiters. This function -looks only before point, not after." - (catch 'exit - (let ((pos (point)) - (dodollar (member "$" (plist-get org-format-latex-options :matchers))) - (lim (progn - (re-search-backward (concat "^\\(" paragraph-start "\\)") nil - 'move) - (point))) - dd-on str (start 0) m re) - (goto-char pos) - (when dodollar - (setq str (concat (buffer-substring lim (point)) "\000 X$.") - re (nth 1 (assoc "$" org-latex-regexps))) - (while (string-match re str start) - (cond - ((= (match-end 0) (length str)) - (throw 'exit (cons "$" (+ lim (match-beginning 0) 1)))) - ((= (match-end 0) (- (length str) 5)) - (throw 'exit nil)) - (t (setq start (match-end 0)))))) - (when (setq m (re-search-backward "\\(\\\\begin{[^}]*}\\|\\\\(\\|\\\\\\[\\)\\|\\(\\\\end{[^}]*}\\|\\\\)\\|\\\\\\]\\)\\|\\(\\$\\$\\)" lim t)) - (goto-char pos) - (and (match-beginning 1) (throw 'exit (cons (match-string 1) m))) - (and (match-beginning 2) (throw 'exit nil)) - ;; count $$ - (while (re-search-backward "\\$\\$" lim t) - (setq dd-on (not dd-on))) - (goto-char pos) - (when dd-on (cons "$$" m)))))) +(defun org-inside-LaTeX-fragment-p (&optional element) + "Test if point is inside a LaTeX fragment or environment. + +When optional argument ELEMENT is non-nil, it should be element/object +at point." + (org-element-type-p + (or element (org-element-context)) + '(latex-fragment latex-environment))) (defun org-inside-latex-macro-p () "Is point inside a LaTeX macro or its arguments?" @@ -15687,6 +16184,7 @@ fragments in the buffer." (interactive "P") (cond ((not (display-graphic-p)) nil) + ((and untrusted-content (not org--latex-preview-when-risky)) nil) ;; Clear whole buffer. ((equal arg '(64)) (org-clear-latex-preview (point-min) (point-max)) @@ -15713,9 +16211,9 @@ fragments in the buffer." (message "Creating LaTeX previews in region... done.")) ;; Toggle preview on LaTeX code at point. ((let ((datum (org-element-context))) - (and (memq (org-element-type datum) '(latex-environment latex-fragment)) - (let ((beg (org-element-property :begin datum)) - (end (org-element-property :end datum))) + (and (org-element-type-p datum '(latex-environment latex-fragment)) + (let ((beg (org-element-begin datum)) + (end (org-element-end datum))) (if (org-clear-latex-preview beg end) (message "LaTeX preview removed") (message "Creating LaTeX preview...") @@ -15754,6 +16252,8 @@ Some of the options can be changed using the variable (cnt 0) checkdir-flag) (goto-char (or beg (point-min))) + ;; FIXME: `overlay-recenter' is not needed (and has no effect) + ;; since Emacs 29. ;; Optimize overlay creation: (info "(elisp) Managing Overlays"). (when (and overlays (memq processing-type '(dvipng imagemagick))) (overlay-recenter (or end (point-max)))) @@ -15766,9 +16266,9 @@ Some of the options can be changed using the variable (when (memq type '(latex-environment latex-fragment)) (let ((block-type (eq type 'latex-environment)) (value (org-element-property :value context)) - (beg (org-element-property :begin context)) + (beg (org-element-begin context)) (end (save-excursion - (goto-char (org-element-property :end context)) + (goto-char (org-element-end context)) (skip-chars-backward " \r\t\n") (point)))) (cond @@ -15839,21 +16339,7 @@ Some of the options can be changed using the variable (unless (file-exists-p movefile) (org-create-formula-image value movefile options forbuffer processing-type)) - (if overlays - (progn - (dolist (o (overlays-in beg end)) - (when (eq (overlay-get o 'org-overlay-type) - 'org-latex-overlay) - (delete-overlay o))) - (org--make-preview-overlay beg end movefile imagetype) - (goto-char end)) - (delete-region beg end) - (insert - (org-add-props link - (list 'org-latex-src - (replace-regexp-in-string "\"" "" value) - 'org-latex-src-embed-type - (if block-type 'paragraph 'character))))))) + (org-place-formula-image link block-type beg end value overlays movefile imagetype))) ((eq processing-type 'mathml) ;; Process to MathML. (unless (org-format-latex-mathml-available-p) @@ -15868,6 +16354,25 @@ Some of the options can be changed using the variable (error "Unknown conversion process %s for LaTeX fragments" processing-type))))))))))) +(defun org-place-formula-image (link block-type beg end value overlays movefile imagetype) + "Place an overlay from BEG to END showing MOVEFILE. +The overlay will be above BEG if OVERLAYS is non-nil." + (if overlays + (progn + (dolist (o (overlays-in beg end)) + (when (eq (overlay-get o 'org-overlay-type) + 'org-latex-overlay) + (delete-overlay o))) + (org--make-preview-overlay beg end movefile imagetype) + (goto-char end)) + (delete-region beg end) + (insert + (org-add-props link + (list 'org-latex-src + (replace-regexp-in-string "\"" "" value) + 'org-latex-src-embed-type + (if block-type 'paragraph 'character)))))) + (defun org-create-math-formula (latex-frag &optional mathml-file) "Convert LATEX-FRAG to MathML and store it in MATHML-FILE. Use `org-latex-to-mathml-convert-command'. If the conversion is @@ -15896,7 +16401,7 @@ inspection." (expand-file-name org-latex-to-mathml-jar-file)))) (?I . ,(shell-quote-argument tmp-in-file)) - (?i . ,latex-frag) + (?i . ,(shell-quote-argument latex-frag)) (?o . ,(shell-quote-argument tmp-out-file))))) mathml shell-command-output) (when (called-interactively-p 'any) @@ -15906,14 +16411,15 @@ inspection." (setq shell-command-output (shell-command-to-string cmd)) (setq mathml (when (file-readable-p tmp-out-file) - (with-current-buffer (find-file-noselect tmp-out-file t) + (with-temp-buffer + (insert-file-contents tmp-out-file) (goto-char (point-min)) (when (re-search-forward (format "]*?%s[^>]*?>\\(.\\|\n\\)*" (regexp-quote "xmlns=\"http://www.w3.org/1998/Math/MathML\"")) nil t) - (prog1 (match-string 0) (kill-buffer)))))) + (match-string 0))))) (cond (mathml (setq mathml @@ -15963,7 +16469,7 @@ inspection." "Convert LATEX-FRAGMENT to HTML. This uses `org-latex-to-html-convert-command', which see." (let ((cmd (format-spec org-latex-to-html-convert-command - `((?i . ,latex-fragment))))) + `((?i . ,(shell-quote-argument latex-fragment)))))) (message "Running %s" cmd) (shell-command-to-string cmd))) @@ -16159,6 +16665,10 @@ SNIPPETS-P indicates if this is run to create snippet images for HTML." ;; Image display (defvar-local org-inline-image-overlays nil) +;; Preserve when switching modes or when restarting Org. +;; If we clear the overlay list and later enable Or mode, the existing +;; image overlays will never be cleared by `org-toggle-inline-images'. +(put 'org-inline-image-overlays 'permanent-local t) (defun org--inline-image-overlays (&optional beg end) "Return image overlays between BEG and END." @@ -16203,17 +16713,37 @@ Possible values of this option are: skip Don't display remote images. download Always download and display remote images. +t cache Display remote images, and open them in separate buffers for caching. Silently update the image buffer when a file change is detected." :group 'org-appearance - :package-version '(Org . "9.4") + :package-version '(Org . "9.7") :type '(choice (const :tag "Ignore remote images" skip) (const :tag "Always display remote images" download) (const :tag "Display and silently update remote images" cache)) :safe #'symbolp) +(defcustom org-image-align 'left + "How to align images previewed using `org-display-inline-images'. + +Only stand-alone image links are affected by this setting. These +are links without surrounding text. + +Possible values of this option are: + +left Insert image at specified position. +center Center image previews. +right Right-align image previews." + :group 'org-appearance + :package-version '(Org . "9.7") + :type '(choice + (const :tag "Left align (or don\\='t align) image previews" left) + (const :tag "Center image previews" center) + (const :tag "Right align image previews" right)) + :safe #'symbolp) + (defun org--create-inline-image (file width) "Create image located at FILE, or return nil. WIDTH is the width of the image. The image may not be created @@ -16226,9 +16756,10 @@ according to the value of `org-display-remote-inline-images'." (set-buffer-multibyte nil) (insert-file-contents-literally file) (buffer-string))) - (`cache (let ((revert-without-query '("."))) - (with-current-buffer (find-file-noselect file) - (buffer-string)))) + ((or `cache `t) + (let ((revert-without-query '("."))) + (with-current-buffer (find-file-noselect file) + (buffer-string)))) (`skip nil) (other (message "Invalid value of `org-display-remote-inline-images': %S" @@ -16240,7 +16771,17 @@ according to the value of `org-display-remote-inline-images'." width 'imagemagick) remote? - :width width :scale 1)))) + :width width + :max-width + (pcase org-image-max-width + (`fill-column (* fill-column (frame-char-width (selected-frame)))) + (`window (window-width nil t)) + ((pred integerp) org-image-max-width) + ((pred floatp) (floor (* org-image-max-width (window-width nil t)))) + (`nil nil) + (_ (error "Unsupported value of `org-image-max-width': %S" + org-image-max-width))) + :scale 1)))) (defun org-display-inline-images (&optional include-linked refresh beg end) "Display inline images. @@ -16291,7 +16832,7 @@ buffer boundaries with possible narrowing." (while (re-search-forward file-types-re end t) (let* ((link (org-element-lineage (save-match-data (org-element-context)) - '(link) t)) + 'link t)) (linktype (org-element-property :type link)) (inner-start (match-beginning 1)) (path @@ -16304,7 +16845,7 @@ buffer boundaries with possible narrowing." ;; contains filenames in both the path and the ;; description, prioritize the path only when ;; INCLUDE-LINKED is non-nil. - ((or (not (org-element-property :contents-begin link)) + ((or (not (org-element-contents-begin link)) include-linked) (and (or (equal "file" linktype) (equal "attachment" linktype)) @@ -16322,7 +16863,7 @@ buffer boundaries with possible narrowing." org-link-plain-re)) ;; File name must fill the whole ;; description. - (= (org-element-property :contents-end link) + (= (org-element-contents-end link) (match-end 0)) (progn (setq linktype (match-string 1)) @@ -16333,23 +16874,26 @@ buffer boundaries with possible narrowing." (require 'org-attach) (ignore-errors (org-attach-expand path))) (expand-file-name path)))) + ;; Expand environment variables. + (when file (setq file (substitute-in-file-name file))) (when (and file (file-exists-p file)) (let ((width (org-display-inline-image--width link)) - (old (get-char-property-and-overlay - (org-element-property :begin link) + (align (org-image--align link)) + (old (get-char-property-and-overlay + (org-element-begin link) 'org-image-overlay))) (if (and (car-safe old) refresh) (image-flush (overlay-get (cdr old) 'display)) (let ((image (org--create-inline-image file width))) (when image (let ((ov (make-overlay - (org-element-property :begin link) + (org-element-begin link) (progn (goto-char - (org-element-property :end link)) - (skip-chars-backward " \t") + (org-element-end link)) + (unless (eolp) (skip-chars-backward " \t")) (point))))) - ;; FIXME: See bug#59902. We cannot rely + ;; See bug#59902. We cannot rely ;; on Emacs to update image if the file ;; has changed. (image-flush image) @@ -16361,20 +16905,33 @@ buffer boundaries with possible narrowing." (list 'org-display-inline-remove-overlay)) (when (boundp 'image-map) (overlay-put ov 'keymap image-map)) + (when align + (overlay-put + ov 'before-string + (propertize + " " 'face 'default + 'display + (pcase align + ("center" `(space :align-to (- center (0.5 . ,image)))) + ("right" `(space :align-to (- right ,image))))))) (push ov org-inline-image-overlays)))))))))))))))) +(declare-function org-export-read-attribute "ox" + (attribute element &optional property)) (defvar visual-fill-column-width) ; Silence compiler warning (defun org-display-inline-image--width (link) "Determine the display width of the image LINK, in pixels. - When `org-image-actual-width' is t, the image's pixel width is used. - When `org-image-actual-width' is a number, that value will is used. -- When `org-image-actual-width' is nil or a list, the first :width attribute - set (if it exists) is used to set the image width. A width of X% is - divided by 100. - If no :width attribute is given and `org-image-actual-width' is a list with - a number as the car, then that number is used as the default value. - If the value is a float between 0 and 2, it interpreted as that proportion - of the text width in the buffer." +- When `org-image-actual-width' is nil or a list, :width attribute of + #+attr_org or the first #+attr_... (if it exists) is used to set the + image width. A width of X% is divided by 100. If the value is a + float between 0 and 2, it interpreted as that proportion of the text + width in the buffer. + + If no :width attribute is given and `org-image-actual-width' is a + list with a number as the car, then that number is used as the + default value." ;; Apply `org-image-actual-width' specifications. ;; Support subtree-level property "ORG-IMAGE-ACTUAL-WIDTH" specified ;; width. @@ -16382,26 +16939,46 @@ buffer boundaries with possible narrowing." (cond ((eq org-image-actual-width t) nil) ((listp org-image-actual-width) - (let* ((case-fold-search t) - (par (org-element-lineage link '(paragraph))) - (attr-re "^[ \t]*#\\+attr_.*?: +.*?:width +\\(\\S-+\\)") - (par-end (org-element-property :post-affiliated par)) + (require 'ox) + (let* ((par (org-element-lineage link 'paragraph)) ;; Try to find an attribute providing a :width. + ;; #+ATTR_ORG: :width ... + (attr-width (org-export-read-attribute :attr_org par :width)) + (width-unreadable? + (lambda (value) + (or (not (stringp value)) + (unless (string= value "t") + (or (not (string-match-p + (rx bos (opt "+") (opt ".") (in "0-9")) + value)) + (let ((number (string-to-number value))) + (and (floatp number) (not (<= 0.0 number 2.0))))))))) + ;; #+ATTR_BACKEND: :width ... + (attr-other + (catch :found + (org-element-properties-map + (lambda (prop _) + (when (and + (not (eq prop :attr_org)) + (string-match-p "^:attr_" (symbol-name prop)) + (not (funcall width-unreadable? (org-export-read-attribute prop par :width)))) + (throw :found prop))) + par))) (attr-width - (when (and par (org-with-point-at - (org-element-property :begin par) - (re-search-forward attr-re par-end t))) - (match-string 1))) + (if (not (funcall width-unreadable? attr-width)) + attr-width + ;; When #+attr_org: does not have readable :width + (and attr-other + (org-export-read-attribute attr-other par :width)))) (width (cond ;; Treat :width t as if `org-image-actual-width' were t. ((string= attr-width "t") nil) ;; Fallback to `org-image-actual-width' if no interprable width is given. - ((or (null attr-width) - (string-match-p "\\`[^0-9]" attr-width)) + ((funcall width-unreadable? attr-width) (car org-image-actual-width)) ;; Convert numeric widths to numbers, converting percentages. - ((string-match-p "\\`[0-9.]+%" attr-width) + ((string-match-p "\\`[[+]?[0-9.]+%" attr-width) (/ (string-to-number attr-width) 100.0)) (t (string-to-number attr-width))))) (if (and (floatp width) (<= 0.0 width 2.0)) @@ -16422,10 +16999,69 @@ buffer boundaries with possible narrowing." org-image-actual-width) (t nil)))) +(defun org-image--align (link) + "Determine the alignment of the image LINK. +LINK is a link object. + +In decreasing order of priority, this is controlled: +- Per image by the value of `:center' or `:align' in the +affiliated keyword `#+attr_org'. +- By the `#+attr_html' or `#+attr_latex` keywords with valid + `:center' or `:align' values. +- Globally by the user option `org-image-align'. + +The result is either nil or one of the strings \"left\", +\"center\" or \"right\". + +\"center\" will cause the image preview to be centered, \"right\" +will cause it to be right-aligned. A value of \"left\" or nil +implies no special alignment." + (let ((par (org-element-lineage link 'paragraph))) + ;; Only align when image is not surrounded by paragraph text: + (when (and par ; when image is not in paragraph, but in table/headline/etc, do not align + (= (org-element-begin link) + (save-excursion + (goto-char (org-element-contents-begin par)) + (skip-chars-forward "\t ") + (point))) ;account for leading space + ;before link + (<= (- (org-element-contents-end par) + (org-element-end link)) + 1)) ;account for trailing newline + ;at end of paragraph + (save-match-data + ;; Look for a valid ":center t" or ":align left|center|right" + ;; attribute. + ;; + ;; An attr_org keyword has the highest priority, with + ;; any attr.* next. Choosing between these is + ;; unspecified. + (let ((center-re ":\\(center\\)[[:space:]]+t\\b") + (align-re ":align[[:space:]]+\\(left\\|center\\|right\\)\\b") + attr-align) + (catch 'exit + (org-element-properties-mapc + (lambda (propname propval) + (when (and propval + (string-match-p ":attr.*" (symbol-name propname))) + (setq propval (car-safe propval)) + (when (or (string-match center-re propval) + (string-match align-re propval)) + (setq attr-align (match-string 1 propval)) + (when (eq propname :attr_org) + (throw 'exit t))))) + par)) + (if attr-align + (when (member attr-align '("center" "right")) attr-align) + ;; No image-specific keyword, check global alignment property + (when (memq org-image-align '(center right)) + (symbol-name org-image-align)))))))) + + (defun org-display-inline-remove-overlay (ov after _beg _end &optional _len) "Remove inline-display overlay if a corresponding region is modified." (when (and ov after) - (delete ov org-inline-image-overlays) + (setq org-inline-image-overlays (delete ov org-inline-image-overlays)) ;; Clear image from cache to avoid image not updating upon ;; changing on disk. See Emacs bug#59902. (when (overlay-get ov 'org-image-overlay) @@ -16458,19 +17094,23 @@ either not currently on a tagged headline or on a tag." (< (point) (match-beginning 1))) (org-align-tags))) +(defun org--speed-command-p () + "Return non-nil when current command is a speed command. +Set `org-speed-command' to the appropriate command as a side effect." + (and org-use-speed-commands + (let ((kv (this-command-keys-vector))) + (setq org-speed-command + (run-hook-with-args-until-success + 'org-speed-command-hook + (make-string 1 (aref kv (1- (length kv))))))))) + (defun org-self-insert-command (N) - "Like `self-insert-command', use overwrite-mode for whitespace in tables. + "Like `self-insert-command', use `overwrite-mode' for whitespace in tables. If the cursor is in a table looking at whitespace, the whitespace is overwritten, and the table is not marked as requiring realignment." (interactive "p") - (org-fold-check-before-invisible-edit 'insert) (cond - ((and org-use-speed-commands - (let ((kv (this-command-keys-vector))) - (setq org-speed-command - (run-hook-with-args-until-success - 'org-speed-command-hook - (make-string 1 (aref kv (1- (length kv)))))))) + ((org--speed-command-p) (cond ((commandp org-speed-command) (setq this-command org-speed-command) @@ -16501,7 +17141,9 @@ overwritten, and the table is not marked as requiring realignment." t) (looking-at "[^|\n]* |")) ;; There is room for insertion without re-aligning the table. - (self-insert-command N) + ;; Interactively, point should never be inside invisible regions + (org-fold-core-suppress-folding-fix + (self-insert-command N)) (org-table-with-shrunk-field (save-excursion (skip-chars-forward "^|") @@ -16511,8 +17153,10 @@ overwritten, and the table is not marked as requiring realignment." (delete-region (- (point) 2) (1- (point)))))) (t (setq org-table-may-need-update t) - (self-insert-command N) - (org-fix-tags-on-the-fly) + ;; Interactively, point should never be inside invisible regions + (org-fold-core-suppress-folding-fix + (self-insert-command N) + (when org-auto-align-tags (org-fix-tags-on-the-fly))) (when org-self-insert-cluster-for-undo (if (not (eq last-command 'org-self-insert-command)) (setq org-self-insert-command-undo-counter 1) @@ -16533,7 +17177,6 @@ still be marked for re-alignment if the field did fill the entire column, because, in this case the deletion might narrow the column." (interactive "p") (save-match-data - (org-fold-check-before-invisible-edit 'delete-backward) (if (and (= N 1) (not overwrite-mode) (not (org-region-active-p)) @@ -16543,7 +17186,7 @@ because, in this case the deletion might narrow the column." (org-at-table-p)) (progn (forward-char -1) (org-delete-char 1)) (funcall-interactively #'backward-delete-char N) - (org-fix-tags-on-the-fly)))) + (when org-auto-align-tags (org-fix-tags-on-the-fly))))) (defun org-delete-char (N) "Like `delete-char', but insert whitespace at field end in tables. @@ -16553,14 +17196,13 @@ still be marked for re-alignment if the field did fill the entire column, because, in this case the deletion might narrow the column." (interactive "p") (save-match-data - (org-fold-check-before-invisible-edit 'delete) (cond ((or (/= N 1) (eq (char-after) ?|) (save-excursion (skip-chars-backward " \t") (bolp)) (not (org-at-table-p))) (delete-char N) - (org-fix-tags-on-the-fly)) + (when org-auto-align-tags (org-fix-tags-on-the-fly))) ((looking-at ".\\(.*?\\)|") (let* ((update? org-table-may-need-update) (noalign (looking-at-p ".*? |"))) @@ -16580,8 +17222,9 @@ because, in this case the deletion might narrow the column." ;; Make `delete-selection-mode' work with Org mode and Orgtbl mode (put 'org-self-insert-command 'delete-selection (lambda () - (not (run-hook-with-args-until-success - 'self-insert-uses-region-functions)))) + (unless (org--speed-command-p) + (not (run-hook-with-args-until-success + 'self-insert-uses-region-functions))))) (put 'orgtbl-self-insert-command 'delete-selection (lambda () (not (run-hook-with-args-until-success @@ -16611,9 +17254,9 @@ word constituents." (call-interactively 'transpose-words))) (defvar org-ctrl-c-ctrl-c-hook nil - "Hook for functions attaching themselves to `C-c C-c'. + "Hook for functions attaching themselves to \\`C-c C-c'. -This can be used to add additional functionality to the `C-c C-c' +This can be used to add additional functionality to the \\`C-c C-c' key which executes context-dependent commands. This hook is run before any other test, while `org-ctrl-c-ctrl-c-final-hook' is run after the last test. @@ -16624,9 +17267,9 @@ it should do its thing and then return a non-nil value. If the context is wrong, just do nothing and return nil.") (defvar org-ctrl-c-ctrl-c-final-hook nil - "Hook for functions attaching themselves to `C-c C-c'. + "Hook for functions attaching themselves to \\`C-c C-c'. -This can be used to add additional functionality to the `C-c C-c' +This can be used to add additional functionality to the \\`C-c C-c' key which executes context-dependent commands. This hook is run after any other test, while `org-ctrl-c-ctrl-c-hook' is run before the first test. @@ -16661,27 +17304,63 @@ before indentation and \t insertion takes place.") (defvar org-metaleft-hook nil "Hook for functions attaching themselves to `M-left'. See `org-ctrl-c-ctrl-c-hook' for more information.") +(defvar org-metaleft-final-hook nil + "Hook for functions attaching themselves to `M-left'. +This one runs after all options have been excluded. +See `org-ctrl-c-ctrl-c-hook' for more information.") (defvar org-metaright-hook nil "Hook for functions attaching themselves to `M-right'. See `org-ctrl-c-ctrl-c-hook' for more information.") +(defvar org-metaright-final-hook nil + "Hook for functions attaching themselves to `M-right'. +This one runs after all options have been excluded. +See `org-ctrl-c-ctrl-c-hook' for more information.") (defvar org-metaup-hook nil "Hook for functions attaching themselves to `M-up'. See `org-ctrl-c-ctrl-c-hook' for more information.") +(defvar org-metaup-final-hook nil + "Hook for functions attaching themselves to `M-up'. +This one runs after all other options except +`org-drag-element-backward' have been excluded. See +`org-ctrl-c-ctrl-c-hook' for more information.") (defvar org-metadown-hook nil "Hook for functions attaching themselves to `M-down'. See `org-ctrl-c-ctrl-c-hook' for more information.") +(defvar org-metadown-final-hook nil + "Hook for functions attaching themselves to `M-down'. +This one runs after all other options except +`org-drag-element-forward' have been excluded. See +`org-ctrl-c-ctrl-c-hook' for more information.") (defvar org-shiftmetaleft-hook nil "Hook for functions attaching themselves to `M-S-left'. See `org-ctrl-c-ctrl-c-hook' for more information.") +(defvar org-shiftmetaleft-final-hook nil + "Hook for functions attaching themselves to `M-S-left'. +This one runs after all other options have been excluded. See +`org-ctrl-c-ctrl-c-hook' for more information.") (defvar org-shiftmetaright-hook nil "Hook for functions attaching themselves to `M-S-right'. See `org-ctrl-c-ctrl-c-hook' for more information.") +(defvar org-shiftmetaright-final-hook nil + "Hook for functions attaching themselves to `M-S-right'. +This one runs after all other options have been excluded. See +`org-ctrl-c-ctrl-c-hook' for more information.") (defvar org-shiftmetaup-hook nil "Hook for functions attaching themselves to `M-S-up'. See `org-ctrl-c-ctrl-c-hook' for more information.") +(defvar org-shiftmetaup-final-hook nil + "Hook for functions attaching themselves to `M-S-up'. +This one runs after all other options except +`org-drag-line-backward' have been excluded. See +`org-ctrl-c-ctrl-c-hook' for more information.") (defvar org-shiftmetadown-hook nil "Hook for functions attaching themselves to `M-S-down'. See `org-ctrl-c-ctrl-c-hook' for more information.") +(defvar org-shiftmetadown-final-hook nil + "Hook for functions attaching themselves to `M-S-down'. +This one runs after all other options except +`org-drag-line-forward' have been excluded. See +`org-ctrl-c-ctrl-c-hook' for more information.") (defvar org-metareturn-hook nil "Hook for functions attaching themselves to `M-RET'. See `org-ctrl-c-ctrl-c-hook' for more information.") @@ -16749,7 +17428,13 @@ When ARG is a numeric prefix, show contents of this level." "Promote subtree or delete table column. Calls `org-promote-subtree', `org-outdent-item-tree', or `org-table-delete-column', depending on context. See the -individual commands for more information." +individual commands for more information. + +This function runs the functions in `org-shiftmetaleft-hook' one +by one as a first step, and exits immediately if a function from +the hook returns non-nil. In the absence of a specific context, +the function also runs `org-shiftmetaleft-final-hook' using the +same logic." (interactive) (cond ((and (eq system-type 'darwin) @@ -16763,13 +17448,20 @@ individual commands for more information." (save-excursion (goto-char (region-beginning)) (org-at-item-p))) (call-interactively 'org-outdent-item-tree)) + ((run-hook-with-args-until-success 'org-shiftmetaleft-final-hook)) (t (org-modifier-cursor-error)))) (defun org-shiftmetaright () "Demote subtree or insert table column. Calls `org-demote-subtree', `org-indent-item-tree', or `org-table-insert-column', depending on context. See the -individual commands for more information." +individual commands for more information. + +This function runs the functions in `org-shiftmetaright-hook' one +by one as a first step, and exits immediately if a function from +the hook returns non-nil. In the absence of a specific context, +the function also runs `org-shiftmetaright-final-hook' using the +same logic." (interactive) (cond ((and (eq system-type 'darwin) @@ -16783,6 +17475,7 @@ individual commands for more information." (save-excursion (goto-char (region-beginning)) (org-at-item-p))) (call-interactively 'org-indent-item-tree)) + ((run-hook-with-args-until-success 'org-shiftmetaright-final-hook)) (t (org-modifier-cursor-error)))) (defun org-shiftmetaup (&optional _arg) @@ -16790,13 +17483,20 @@ individual commands for more information." In a table, kill the current row. On a clock timestamp, update the value of the timestamp like `S-' but also adjust the previous clocked item in the clock history. -Everywhere else, drag the line at point up." +Everywhere else, drag the line at point up. + +This function runs the functions in `org-shiftmetaup-hook' one by +one as a first step, and exits immediately if a function from the +hook returns non-nil. In the absence of a specific context, the +function also runs `org-shiftmetaup-final-hook' using the same +logic." (interactive "P") (cond ((run-hook-with-args-until-success 'org-shiftmetaup-hook)) ((org-at-table-p) (call-interactively 'org-table-kill-row)) ((org-at-clock-log-p) (let ((org-clock-adjust-closest t)) (call-interactively 'org-timestamp-up))) + ((run-hook-with-args-until-success 'org-shiftmetaup-final-hook)) (t (call-interactively 'org-drag-line-backward)))) (defun org-shiftmetadown (&optional _arg) @@ -16804,13 +17504,20 @@ Everywhere else, drag the line at point up." In a table, insert an empty row at the current line. On a clock timestamp, update the value of the timestamp like `S-' but also adjust the previous clocked item in the clock history. -Everywhere else, drag the line at point down." +Everywhere else, drag the line at point down. + +This function runs the functions in `org-shiftmetadown-hook' one +by one as a first step, and exits immediately if a function from +the hook returns non-nil. In the absence of a specific context, +the function also runs `org-shiftmetadown-final-hook' using the +same logic." (interactive "P") (cond ((run-hook-with-args-until-success 'org-shiftmetadown-hook)) ((org-at-table-p) (call-interactively 'org-table-insert-row)) ((org-at-clock-log-p) (let ((org-clock-adjust-closest t)) (call-interactively 'org-timestamp-down))) + ((run-hook-with-args-until-success 'org-shiftmetadown-final-hook)) (t (call-interactively 'org-drag-line-forward)))) (defsubst org-hidden-tree-error () @@ -16825,8 +17532,10 @@ depending on context. With no specific context, calls the Emacs default `backward-word'. See the individual commands for more information. -This function runs the hook `org-metaleft-hook' as a first step, -and returns at first non-nil value." +This function runs the functions in `org-metaleft-hook' one by +one as a first step, and exits immediately if a function from the +hook returns non-nil. In the absence of a specific context, the +function runs `org-metaleft-final-hook' using the same logic." (interactive "P") (cond ((run-hook-with-args-until-success 'org-metaleft-hook)) @@ -16849,6 +17558,7 @@ and returns at first non-nil value." (org-at-item-p)))) (when (org-check-for-hidden 'items) (org-hidden-tree-error)) (call-interactively 'org-outdent-item)) + ((run-hook-with-args-until-success 'org-metaleft-final-hook)) (t (call-interactively 'backward-word)))) (defun org-metaright (&optional _arg) @@ -16861,8 +17571,10 @@ Calls `org-do-demote', `org-indent-item', `org-table-move-column', With no specific context, calls the Emacs default `forward-word'. See the individual commands for more information. -This function runs the hook `org-metaright-hook' as a first step, -and returns at first non-nil value." +This function runs the functions in `org-metaright-hook' one by +one as a first step, and exits immediately if a function from the +hook returns non-nil. In the absence of a specific context, the +function runs `org-metaright-final-hook' using the same logic." (interactive "P") (cond ((run-hook-with-args-until-success 'org-metaright-hook)) @@ -16887,6 +17599,7 @@ and returns at first non-nil value." (org-at-item-p)))) (when (org-check-for-hidden 'items) (org-hidden-tree-error)) (call-interactively 'org-indent-item)) + ((run-hook-with-args-until-success 'org-metaright-final-hook)) (t (call-interactively 'forward-word)))) (defun org-check-for-hidden (what) @@ -16903,10 +17616,10 @@ this function returns t, nil otherwise." (catch 'exit (unless (org-region-active-p) (setq beg (line-beginning-position)) - (beginning-of-line 2) + (forward-line 1) (while (and (not (eobp)) ;; this is like `next-line' (org-invisible-p (1- (point)))) - (beginning-of-line 2)) + (forward-line 1)) (setq end (point)) (goto-char beg) (goto-char (line-end-position)) @@ -16919,74 +17632,154 @@ this function returns t, nil otherwise." (defun org-metaup (&optional _arg) "Move subtree up or move table row up. Calls `org-move-subtree-up' or `org-table-move-row' or -`org-move-item-up', depending on context. See the individual commands -for more information." +`org-move-item-up', depending on context. Everywhere else, move +backward the element at point. See the individual commands for +more information. + +This function runs the functions in `org-metaup-hook' one by one +as a first step, and exits immediately if a function from the +hook returns non-nil. In the absence of a specific context, the +function runs `org-metaup-final-hook' using the same logic." (interactive "P") (cond ((run-hook-with-args-until-success 'org-metaup-hook)) + ((and (org-region-active-p) + (org-with-limited-levels + (save-excursion + (goto-char (region-beginning)) + (org-at-heading-p)))) + (when (org-check-for-hidden 'headlines) (org-hidden-tree-error)) + (let ((beg (region-beginning)) + (end (region-end))) + (save-excursion + ;; Go a little earlier because `org-move-subtree-down' will + ;; insert before markers and we may overshoot in some cases. + (goto-char (max beg (1- end))) + (setq end (point-marker)) + (goto-char beg) + (let ((level (org-current-level))) + (when (or (and (> level 1) (re-search-forward (format "^\\*\\{1,%s\\} " (1- level)) end t)) + ;; Search previous subtree. + (progn + (goto-char beg) + (forward-line 0) + (not (re-search-backward (format "^\\*\\{%s\\} " level) nil t)))) + (user-error "Cannot move past superior level or buffer limit")) + ;; Drag first subtree above below the selected. + (while (< (point) end) + (let ((deactivate-mark nil)) + (call-interactively 'org-move-subtree-down))))))) ((org-region-active-p) (let* ((a (save-excursion - (goto-char (region-beginning)) - (line-beginning-position))) - (b (save-excursion - (goto-char (region-end)) - (if (bolp) (1- (point)) (line-end-position)))) - (c (save-excursion - (goto-char a) - (move-beginning-of-line 0) - (point))) - (d (save-excursion - (goto-char a) - (move-end-of-line 0) - (point)))) + (goto-char (region-beginning)) + (line-beginning-position))) + (b (save-excursion + (goto-char (region-end)) + (if (bolp) (1- (point)) (line-end-position)))) + (c (save-excursion + (goto-char a) + (move-beginning-of-line 0) + (point))) + (d (save-excursion + (goto-char a) + (move-end-of-line 0) + (point))) + (deactivate-mark nil) + (swap? (< (point) (mark)))) (transpose-regions a b c d) - (goto-char c))) + (set-mark c) + (goto-char (+ c (- b a))) + (when swap? (exchange-point-and-mark)))) ((org-at-table-p) (org-call-with-arg 'org-table-move-row 'up)) ((and (featurep 'org-inlinetask) (org-inlinetask-in-task-p)) (org-drag-element-backward)) ((org-at-heading-p) (call-interactively 'org-move-subtree-up)) ((org-at-item-p) (call-interactively 'org-move-item-up)) + ((run-hook-with-args-until-success 'org-metaup-final-hook)) (t (org-drag-element-backward)))) (defun org-metadown (&optional _arg) "Move subtree down or move table row down. Calls `org-move-subtree-down' or `org-table-move-row' or -`org-move-item-down', depending on context. See the individual -commands for more information." +`org-move-item-down', depending on context. Everywhere else, +move forward the element at point. See the individual commands +for more information. + +This function runs the functions in `org-metadown-hook' one by +one as a first step, and exits immediately if a function from the +hook returns non-nil. In the absence of a specific context, the +function runs `org-metadown-final-hook' using the same logic." (interactive "P") (cond ((run-hook-with-args-until-success 'org-metadown-hook)) + ((and (org-region-active-p) + (org-with-limited-levels + (save-excursion + (goto-char (region-beginning)) + (org-at-heading-p)))) + (when (org-check-for-hidden 'headlines) (org-hidden-tree-error)) + (let ((beg (region-beginning)) + (end (region-end))) + (save-excursion + (goto-char beg) + (setq beg (point-marker)) + (let ((level (org-current-level))) + (when (or (and (> level 1) (re-search-forward (format "^\\*\\{1,%s\\} " (1- level)) end t)) + ;; Search next subtree. + (progn + (goto-char end) + (not (re-search-forward (format "^\\*\\{%s\\} " level) nil t)))) + (user-error "Cannot move past superior level or buffer limit")) + ;; Drag first subtree below above the selected. + (while (> (point) beg) + (let ((deactivate-mark nil)) + (call-interactively 'org-move-subtree-up))))))) ((org-region-active-p) (let* ((a (save-excursion - (goto-char (region-beginning)) - (line-beginning-position))) + (goto-char (region-beginning)) + (line-beginning-position))) (b (save-excursion - (goto-char (region-end)) - (if (bolp) (1- (point)) (line-end-position)))) + (goto-char (region-end)) + (if (bolp) (1- (point)) (line-end-position)))) (c (save-excursion - (goto-char b) - (move-beginning-of-line (if (bolp) 1 2)) - (point))) + (goto-char b) + (move-beginning-of-line (if (bolp) 1 2)) + (point))) (d (save-excursion - (goto-char b) - (move-end-of-line (if (bolp) 1 2)) - (point)))) + (goto-char b) + (move-end-of-line (if (bolp) 1 2)) + (point))) + (deactivate-mark nil) + (swap? (< (point) (mark)))) (transpose-regions a b c d) - (goto-char d))) + (set-mark (+ 1 a (- d c))) + (goto-char (+ 1 a (- d c) (- b a))) + (when swap? (exchange-point-and-mark)))) ((org-at-table-p) (call-interactively 'org-table-move-row)) ((and (featurep 'org-inlinetask) (org-inlinetask-in-task-p)) (org-drag-element-forward)) ((org-at-heading-p) (call-interactively 'org-move-subtree-down)) ((org-at-item-p) (call-interactively 'org-move-item-down)) + ((run-hook-with-args-until-success 'org-metadown-final-hook)) (t (org-drag-element-forward)))) (defun org-shiftup (&optional arg) "Act on current element according to context. Call `org-timestamp-up' or `org-priority-up', or `org-previous-item', or `org-table-move-cell-up'. See the -individual commands for more information." +individual commands for more information. + +This function runs the functions in `org-shiftup-hook' one by one +as a first step, and exits immediately if a function from the +hook returns non-nil. In the absence of a specific context, the +function also runs `org-shiftup-final-hook' using the same logic. + +If none of the previous steps succeed and +`org-support-shift-select' is non-nil, the function runs +`shift-select-mode' associated command. See that variable for +more information." (interactive "P") (cond ((run-hook-with-args-until-success 'org-shiftup-hook)) @@ -17014,7 +17807,18 @@ individual commands for more information." "Act on current element according to context. Call `org-timestamp-down' or `org-priority-down', or `org-next-item', or `org-table-move-cell-down'. See the -individual commands for more information." +individual commands for more information. + +This function runs the functions in `org-shiftdown-hook' one by +one as a first step, and exits immediately if a function from the +hook returns non-nil. In the absence of a specific context, the +function also runs `org-shiftdown-final-hook' using the same +logic. + +If none of the previous steps succeed and +`org-support-shift-select' is non-nil, the function runs +`shift-select-mode' associated command. See that variable for +more information." (interactive "P") (cond ((run-hook-with-args-until-success 'org-shiftdown-hook)) @@ -17047,7 +17851,16 @@ This does one of the following: - on an item, switch entire list to the next bullet type - on a property line, switch to the next allowed value - on a clocktable definition line, move time block into the future -- in a table, move a single cell right" +- in a table, move a single cell right + +This function runs the functions in `org-shiftright-hook' one by +one as a first step, and exits immediately if a function from the +hook returns non-nil. In the absence of a specific context, the +function runs `org-shiftright-final-hook' using the same logic. + +If none of the above succeeds and `org-support-shift-select' is +non-nil, runs `shift-select-mode' specific command. See that +variable for more information." (interactive "P") (cond ((run-hook-with-args-until-success 'org-shiftright-hook)) @@ -17087,7 +17900,16 @@ This does one of the following: - on an item, switch entire list to the previous bullet type - on a property line, switch to the previous allowed value - on a clocktable definition line, move time block into the past -- in a table, move a single cell left" +- in a table, move a single cell left + +This function runs the functions in `org-shiftleft-hook' one by +one as a first step, and exits immediately if a function from the +hook returns non-nil. In the absence of a specific context, the +function runs `org-shiftleft-final-hook' using the same logic. + +If none of the above succeeds and `org-support-shift-select' is +non-nil, runs `shift-select-mode' specific command. See that +variable for more information." (interactive "P") (cond ((run-hook-with-args-until-success 'org-shiftleft-hook)) @@ -17200,18 +18022,11 @@ this numeric value." (interactive "r") (let ((result "")) (while (/= beg end) - (if (eq org-fold-core-style 'text-properties) - (progn - (while (org-invisible-p beg) - (setq beg (org-fold-next-visibility-change beg end))) - (let ((next (org-fold-next-visibility-change beg end))) - (setq result (concat result (buffer-substring beg next))) - (setq beg next))) - (when (invisible-p beg) - (setq beg (next-single-char-property-change beg 'invisible nil end))) - (let ((next (next-single-char-property-change beg 'invisible nil end))) - (setq result (concat result (buffer-substring beg next))) - (setq beg next)))) + (while (org-invisible-p beg) + (setq beg (org-fold-next-visibility-change beg end))) + (let ((next (org-fold-next-visibility-change beg end))) + (setq result (concat result (buffer-substring beg next))) + (setq beg next))) ;; Prevent Emacs from adding full selected text to `kill-ring' ;; when `select-enable-primary' is non-nil. This special value of ;; `deactivate-mark' only works since Emacs 29. @@ -17247,7 +18062,11 @@ See the individual commands for more information." (defun org-edit-special (&optional arg) "Call a special editor for the element at point. When at a table, call the formula editor with `org-table-edit-formulas'. -When in a source code block, call `org-edit-src-code'. +When at table.el table, edit it in dedicated buffer. +When in a source code block, call `org-edit-src-code'; with prefix + argument, switch to session buffer. +When in an example block, call `org-edit-src-code'. +When in an inline code block, call `org-edit-inline-src-code'. When in a fixed-width region, call `org-edit-fixed-width-region'. When in an export block, call `org-edit-export-block'. When in a comment block, call `org-edit-comment-block'. @@ -17255,8 +18074,8 @@ When in a LaTeX environment, call `org-edit-latex-environment'. When at an INCLUDE, SETUPFILE or BIBLIOGRAPHY keyword, visit the included file. When at a footnote reference, call `org-edit-footnote-reference'. When at a planning line call, `org-deadline' and/or `org-schedule'. -When at an active timestamp, call `org-time-stamp'. -When at an inactive timestamp, call `org-time-stamp-inactive'. +When at an active timestamp, call `org-timestamp'. +When at an inactive timestamp, call `org-timestamp-inactive'. On a link, call `ffap' to visit the link at point. Otherwise, return a user error." (interactive "P") @@ -17316,8 +18135,8 @@ Otherwise, return a user error." (`inline-src-block (org-edit-inline-src-code)) (`latex-fragment (org-edit-latex-fragment)) (`timestamp (if (eq 'inactive (org-element-property :type context)) - (call-interactively #'org-time-stamp-inactive) - (call-interactively #'org-time-stamp))) + (call-interactively #'org-timestamp-inactive) + (call-interactively #'org-timestamp))) (`link (call-interactively #'ffap)) (_ (user-error "No special environment to edit here")))))))) @@ -17399,10 +18218,10 @@ This command does many different things, depending on context: ;; For convenience: at the first line of a paragraph on the same ;; line as an item, apply function on that item instead. (when (eq type 'paragraph) - (let ((parent (org-element-property :parent context))) - (when (and (eq (org-element-type parent) 'item) + (let ((parent (org-element-parent context))) + (when (and (org-element-type-p parent 'item) (= (line-beginning-position) - (org-element-property :begin parent))) + (org-element-begin parent))) (setq context parent) (setq type 'item)))) ;; Act according to type of element or object at point. @@ -17432,14 +18251,14 @@ This command does many different things, depending on context: (org-clock-update-time-maybe))) (`dynamic-block (save-excursion - (goto-char (org-element-property :post-affiliated context)) + (goto-char (org-element-post-affiliated context)) (org-update-dblock))) (`footnote-definition - (goto-char (org-element-property :post-affiliated context)) + (goto-char (org-element-post-affiliated context)) (call-interactively 'org-footnote-action)) (`footnote-reference (call-interactively #'org-footnote-action)) ((or `headline `inlinetask) - (save-excursion (goto-char (org-element-property :begin context)) + (save-excursion (goto-char (org-element-begin context)) (call-interactively #'org-set-tags-command))) (`item ;; At an item: `C-u C-u' sets checkbox to "[-]" @@ -17457,7 +18276,7 @@ This command does many different things, depending on context: (prevs (org-list-prevs-alist struct)) (orderedp (org-not-nil (org-entry-get nil "ORDERED")))) (org-list-set-checkbox - (org-element-property :begin context) struct + (org-element-begin context) struct (cond ((equal arg '(16)) "[-]") ((and (not box) (equal arg '(4))) "[ ]") ((or (not box) (equal arg '(4))) nil) @@ -17493,7 +18312,7 @@ This command does many different things, depending on context: (and (boundp org-list-checkbox-radio-mode) org-list-checkbox-radio-mode)) (org-toggle-radio-button arg) - (let* ((begin (org-element-property :contents-begin context)) + (let* ((begin (org-element-contents-begin context)) (struct (org-element-property :structure context)) (old-struct (copy-tree struct)) (first-box (save-excursion @@ -17541,7 +18360,7 @@ This command does many different things, depending on context: ;; send the table if necessary. (cond ((and (org-match-line "[ \t]*#\\+plot:") - (< (point) (org-element-property :post-affiliated context))) + (< (point) (org-element-post-affiliated context))) (org-plot/gnuplot)) ;; If the table has a `table.el' type, just give up. ((eq (org-element-property :type context) 'table.el) @@ -17552,12 +18371,12 @@ Use `\\[org-edit-special]' to edit table.el tables"))) ((or (eq type 'table) ;; Check if point is at a TBLFM line. (and (eq type 'table-row) - (= (point) (org-element-property :end context)))) + (= (point) (org-element-end context)))) (save-excursion (if (org-at-TBLFM-p) (progn (require 'org-table) (org-table-calc-current-TBLFM)) - (goto-char (org-element-property :contents-begin context)) + (goto-char (org-element-contents-begin context)) (org-call-with-arg 'org-table-recalculate (or arg t)) (orgtbl-send-table 'maybe)))) (t @@ -17604,47 +18423,78 @@ Use `\\[org-edit-special]' to edit table.el tables"))) (org-fold-show-branches) (org-fold-hide-archived-subtrees beg end))))) -(defun org-delete-indentation (&optional arg) +(defun org-delete-indentation (&optional arg beg end) "Join current line to previous and fix whitespace at join. If previous line is a headline add to headline title. Otherwise the function calls `delete-indentation'. -I.e. with a non-nil optional argument, join the line with the -following one. If there is a region then join the lines in that -region." - (interactive "*P") +If there is a region (BEG END), then join the lines in that region. + +With a non-nil prefix ARG, join the line with the following one, +ignoring region." + (interactive + (cons current-prefix-arg + (when (and (not current-prefix-arg) (use-region-p)) + (list (region-beginning) (region-end))))) + (unless (and beg end) + ;; No region selected or BEG/END arguments not passed. + (setq beg (line-beginning-position (if arg 1 0)) + end (line-end-position (if arg 2 1)))) (if (save-excursion - (beginning-of-line (if arg 1 0)) - (let ((case-fold-search nil)) - (looking-at org-complex-heading-regexp))) + (goto-char beg) + (forward-line 0) + (and (< (line-end-position) end) + (let ((case-fold-search nil)) + (looking-at org-complex-heading-regexp)))) ;; At headline. (let ((tags-column (when (match-beginning 5) (save-excursion (goto-char (match-beginning 5)) (current-column)))) - (string (concat " " (progn (when arg (forward-line 1)) - (org-trim (delete-and-extract-region - (line-beginning-position) - (line-end-position))))))) - (unless (bobp) (delete-region (point) (1- (point)))) + string) + (goto-char beg) + ;; Join all but headline. + (save-excursion + (save-match-data + (if (version<= "27" emacs-version) + (delete-indentation nil (line-beginning-position 2) end) + ;; FIXME: Emacs 26. `delete-indentation' does not yet + ;; accept BEG/END arguments. + (save-restriction + (narrow-to-region beg end) + (goto-char beg) + (forward-line 2) + (while (< (point) (point-max)) + (delete-indentation) + (forward-line 1)))))) + (setq string (org-trim (delete-and-extract-region (line-end-position) (line-end-position 2)))) (goto-char (or (match-end 4) (match-beginning 5) (match-end 0))) (skip-chars-backward " \t") - (save-excursion (insert string)) + (save-excursion (insert " " string)) ;; Adjust alignment of tags. (cond ((not tags-column)) ;no tags (org-auto-align-tags (org-align-tags)) (t (org--align-tags-here tags-column)))) ;preserve tags column - (let ((current-prefix-arg arg)) - (call-interactively #'delete-indentation)))) + (if (version<= "27" emacs-version) + (funcall-interactively #'delete-indentation arg beg end) + ;; FIXME: Emacs 26. `delete-indentation' does not yet + ;; accept BEG/END arguments. + (save-restriction + (narrow-to-region beg end) + (goto-char beg) + (forward-line 1) + (while (< (point) (point-max)) + (delete-indentation) + (forward-line 1)))))) (defun org-open-line (n) "Insert a new row in tables, call `open-line' elsewhere. If `org-special-ctrl-o' is nil, just call `open-line' everywhere. -As a special case, when a document starts with a table, allow to -call `open-line' on the very first character." +As a special case, when a document starts with a table, allow +calling `open-line' on the very first character." (interactive "*p") (if (and org-special-ctrl-o (/= (point) 1) (org-at-table-p)) (org-table-insert-row) @@ -17670,8 +18520,8 @@ When optional INDENT argument is non-nil, call and INTERACTIVE. When `org-return-follows-link' is non-nil and point is on -a timestamp or a link, call `org-open-at-point'. However, it -will not happen if point is in a table or on a \"dead\" +a timestamp, a link or a citation, call `org-open-at-point'. +However, it will not happen if point is in a table or on a \"dead\" object (e.g., within a comment). In these case, you need to use `org-open-at-point' directly." (interactive "i\nP\np") @@ -17683,27 +18533,28 @@ object (e.g., within a comment). In these case, you need to use ;; column or after last one, split the table. ((or (and (eq 'table element-type) (not (eq 'table.el (org-element-property :type context))) - (>= (point) (org-element-property :contents-begin context)) - (< (point) (org-element-property :contents-end context))) + (>= (point) (org-element-contents-begin context)) + (< (point) (org-element-contents-end context))) (org-element-lineage context '(table-row table-cell) t)) (if (or (looking-at-p "[ \t]*$") (save-excursion (skip-chars-backward " \t") (bolp))) (insert "\n") (org-table-justify-field-maybe) (call-interactively #'org-table-next-row))) - ;; On a link or a timestamp, call `org-open-at-point' if - ;; `org-return-follows-link' allows it. Tolerate fuzzy + ;; On a link, a timestamp or a citation, call `org-open-at-point' + ;; if `org-return-follows-link' allows it. Tolerate fuzzy ;; locations, e.g., in a comment, as `org-open-at-point'. ((and org-return-follows-link (or (and (eq 'link element-type) ;; Ensure point is not on the white spaces after ;; the link. (let ((origin (point))) - (org-with-point-at (org-element-property :end context) + (org-with-point-at (org-element-end context) (skip-chars-backward " \t") (> (point) origin)))) (org-in-regexp org-ts-regexp-both nil t) (org-in-regexp org-tsr-regexp-both nil t) + (org-element-lineage context '(citation citation-reference) 'include-self) (org-in-regexp org-link-any-re nil t))) (call-interactively #'org-open-at-point)) ;; Insert newline in heading, but preserve tags. @@ -17730,7 +18581,7 @@ object (e.g., within a comment). In these case, you need to use (when string (save-excursion (insert (org-trim string)))))) ;; In a list, make sure indenting keeps trailing text within. ((and (not (eolp)) - (org-element-lineage context '(item))) + (org-element-lineage context 'item)) (let ((trailing-data (delete-and-extract-region (point) (line-end-position)))) (org--newline indent arg interactive) @@ -17913,7 +18764,6 @@ Calls `org-insert-heading', `org-insert-item' or `org-table-wrap-region', depending on context. When called with an argument, unconditionally call `org-insert-heading'." (interactive "P") - (org-fold-check-before-invisible-edit 'insert) (or (run-hook-with-args-until-success 'org-metareturn-hook) (call-interactively (cond (arg #'org-insert-heading) ((org-at-table-p) #'org-table-wrap-region) @@ -18037,8 +18887,8 @@ an argument, unconditionally call `org-insert-heading'." ["Column view of properties" org-columns t] ["Insert Column View DBlock" org-columns-insert-dblock t]) ("Dates and Scheduling" - ["Timestamp" org-time-stamp (not (org-before-first-heading-p))] - ["Timestamp (inactive)" org-time-stamp-inactive (not (org-before-first-heading-p))] + ["Timestamp" org-timestamp (not (org-before-first-heading-p))] + ["Timestamp (inactive)" org-timestamp-inactive (not (org-before-first-heading-p))] ("Change Date" ["1 Day Later" org-shiftright (org-at-timestamp-p 'lax)] ["1 Day Earlier" org-shiftleft (org-at-timestamp-p 'lax)] @@ -18048,7 +18898,7 @@ an argument, unconditionally call `org-insert-heading'." ["Schedule Item" org-schedule (not (org-before-first-heading-p))] ["Deadline" org-deadline (not (org-before-first-heading-p))] "--" - ["Custom time format" org-toggle-time-stamp-overlays + ["Custom time format" org-toggle-timestamp-overlays :style radio :selected org-display-custom-times] "--" ["Goto Calendar" org-goto-calendar t] @@ -18187,6 +19037,8 @@ With optional NODE, go directly to that node." (interactive) (browse-url "https://orgmode.org/Changes.html")) +(defvar org--warnings nil + "List of warnings to be added to the bug reports.") ;;;###autoload (defun org-submit-bug-report () "Submit a bug report on Org via mail. @@ -18207,8 +19059,9 @@ information about your Org version and configuration." (org-version nil 'full) (let (list) (save-window-excursion - (pop-to-buffer-same-window (get-buffer-create "*Warn about privacy*")) - (delete-other-windows) + (pop-to-buffer + (get-buffer-create "*Warn about privacy*") + '(org-display-buffer-full-frame)) (erase-buffer) (insert "You are about to submit a bug report to the Org mailing list. @@ -18230,13 +19083,14 @@ appear in the form of file names, tags, todo states or search strings. If you answer \"yes\" to the prompt, you might want to check and remove such private information before sending the email.") (add-text-properties (point-min) (point-max) '(face org-warning)) - (when (yes-or-no-p "Include your Org configuration ") + (when (yes-or-no-p "Include your Org configuration and Org warning log?") (mapatoms (lambda (v) (and (boundp v) (string-match "\\`\\(org-\\|outline-\\)" (symbol-name v)) (or (and (symbol-value v) (string-match "\\(-hook\\|-function\\)\\'" (symbol-name v))) + (eq v 'org--warnings) (and (get v 'custom-type) (get v 'standard-value) (not (equal (symbol-value v) @@ -18413,23 +19267,24 @@ With prefix arg UNCOMPILED, load the uncompiled versions." (setq s (replace-match "\\vert" t t s))) s) -(defun org-uuidgen-p (s) - "Is S an ID created by UUIDGEN?" - (string-match "\\`[0-9a-f]\\{8\\}-[0-9a-f]\\{4\\}-[0-9a-f]\\{4\\}-[0-9a-f]\\{4\\}-[0-9a-f]\\{12\\}\\'" (downcase s))) - (defun org-in-src-block-p (&optional inside element) - "Whether point is in a code source block. -When INSIDE is non-nil, don't consider we are within a source -block when point is at #+BEGIN_SRC or #+END_SRC. + "Return t when point is at a source block element. +When INSIDE is non-nil, return t only when point is between #+BEGIN_SRC +and #+END_SRC lines. + +Note that affiliated keywords and blank lines after are considered a +part of a source block. + When ELEMENT is provided, it is considered to be element at point." (save-match-data (setq element (or element (org-element-at-point)))) - (when (eq 'src-block (org-element-type element)) + (when (org-element-type-p element 'src-block) (or (not inside) - (not (or (= (line-beginning-position) - (org-element-property :post-affiliated element)) - (= (1+ (line-end-position)) - (- (org-element-property :end element) - (org-element-property :post-blank element)))))))) + (not (or (<= (line-beginning-position) + (org-element-post-affiliated element)) + (>= (line-end-position) + (org-with-point-at (org-element-end element) + (skip-chars-backward " \t\n\r") + (point)))))))) (defun org-context () "Return a list of contexts of the current cursor position. @@ -18470,7 +19325,7 @@ and :keyword." (line-end-position)) clist) (when (progn - (beginning-of-line 1) + (forward-line 0) (looking-at org-todo-line-tags-regexp)) (push (org-point-in-group p 1 :headline-stars) clist) (push (org-point-in-group p 2 :todo-keyword) clist) @@ -18614,24 +19469,40 @@ block from point." (interactive "sOrg-files matching: ") (let* ((files (org-agenda-files)) (tnames (mapcar #'file-truename files)) - (extra org-agenda-text-search-extra-files)) - (when (eq (car extra) 'agenda-archives) + (extra org-agenda-text-search-extra-files) + (narrows nil)) + (when (and (eq (car extra) 'agenda-archives) + (not org-agenda-restrict)) (setq extra (cdr extra)) (setq files (org-add-archive-files files))) - (dolist (f extra) - (unless (member (file-truename f) tnames) - (unless (member f files) (setq files (append files (list f)))) - (setq tnames (append tnames (list (file-truename f)))))) + (unless org-agenda-restrict + (dolist (f extra) + (unless (member (file-truename f) tnames) + (unless (member f files) (setq files (append files (list f)))) + (setq tnames (append tnames (list (file-truename f))))))) (multi-occur (mapcar (lambda (x) (with-current-buffer ;; FIXME: Why not just (find-file-noselect x)? ;; Is it to avoid the "revert buffer" prompt? (or (get-file-buffer x) (find-file-noselect x)) - (widen) + (if (eq (current-buffer) org-agenda-restrict) + (progn + ;; Save the narrowing state. + (push (list (current-buffer) (point-min) (point-max)) + narrows) + (widen) + (narrow-to-region org-agenda-restrict-begin + org-agenda-restrict-end)) + (widen)) (current-buffer))) files) - regexp))) + regexp) + ;; Restore the narrowing. + (dolist (narrow narrows) + (with-current-buffer (car narrow) + (widen) + (narrow-to-region (nth 1 narrow) (nth 2 narrow)))))) (add-hook 'occur-mode-find-occurrence-hook (lambda () (when (derived-mode-p 'org-mode) (org-fold-reveal)))) @@ -18654,7 +19525,7 @@ Returns the number of empty lines passed." (skip-chars-backward " \t\n\r") (unless (eobp) (forward-line -1))) - (beginning-of-line 2) + (forward-line 1) (goto-char (min (point) pos)) (count-lines (point) pos))) @@ -18702,7 +19573,7 @@ the end. If a numeric prefix UP is given, move up into the hierarchy of headlines by UP levels before marking the subtree." (interactive "P") (org-with-limited-levels - (cond ((org-at-heading-p) (beginning-of-line)) + (cond ((org-at-heading-p) (forward-line 0)) ((org-before-first-heading-p) (user-error "Not in a subtree")) (t (outline-previous-visible-heading 1)))) (when up (while (and (> up 0) (org-up-heading-safe)) (cl-decf up))) @@ -18723,12 +19594,12 @@ Optional argument ELEMENT contains element at BEG." (org-with-wide-buffer (when beg (goto-char beg)) (setq element (or element (org-element-at-point))) - (if (or (eq (org-element-type element) 'headline) + (if (or (org-element-type-p element 'headline) (not (org-element-lineage element '(headline inlinetask)))) nil ; Not inside heading. ;; Skip to top-level parent in section. - (while (not (eq 'section (org-element-type (org-element-property :parent element)))) - (setq element (org-element-property :parent element))) + (while (not (org-element-type-p (org-element-parent element) 'section)) + (setq element (org-element-parent element))) (pcase (org-element-type element) ((or `planning `property-drawer) t) @@ -18739,7 +19610,7 @@ Optional argument ELEMENT contains element at BEG." (org-element-property :drawer-name element))) (`clock ;; Previous element must be headline metadata or headline. - (goto-char (1- (org-element-property :begin element))) + (goto-char (1- (org-element-begin element))) (or (org-at-heading-p) (org--at-headline-data-p))))))) @@ -18750,8 +19621,8 @@ ELEMENT is an element containing point. CONTENTSP is non-nil when indentation is to be computed according to contents of ELEMENT." (let ((type (org-element-type element)) - (start (org-element-property :begin element)) - (post-affiliated (org-element-property :post-affiliated element))) + (start (org-element-begin element)) + (post-affiliated (org-element-post-affiliated element))) (org-with-wide-buffer (cond (contentsp @@ -18759,7 +19630,7 @@ ELEMENT." ((diary-sexp footnote-definition) 0) (section (org--get-expected-indentation - (org-element-property :parent element) + (org-element-parent element) t)) ((headline inlinetask nil) (if (not org-adapt-indentation) 0 @@ -18767,7 +19638,7 @@ ELEMENT." (if level (1+ level) 0)))) ((item plain-list) (org-list-item-body-column post-affiliated)) (t - (goto-char start) + (when start (goto-char start)) (current-indentation)))) ((memq type '(headline inlinetask nil)) (if (org-match-line "[ \t]*$") @@ -18776,30 +19647,30 @@ ELEMENT." ((memq type '(diary-sexp footnote-definition)) 0) ;; First paragraph of a footnote definition or an item. ;; Indent like parent. - ((< (line-beginning-position) start) + ((and start (< (line-beginning-position) start)) (org--get-expected-indentation - (org-element-property :parent element) t)) + (org-element-parent element) t)) ;; At first line: indent according to previous sibling, if any, ;; ignoring footnote definitions and inline tasks, or parent's ;; contents. If `org-adapt-indentation' is `headline-data', ignore ;; previous headline data siblings. - ((= (line-beginning-position) start) + ((and start (= (line-beginning-position) start)) (catch 'exit (while t (if (= (point-min) start) (throw 'exit 0) (goto-char (1- start)) (let* ((previous (org-element-at-point)) (parent previous)) - (while (and parent (<= (org-element-property :end parent) start)) + (while (and parent (<= (org-element-end parent) start)) (setq previous parent - parent (org-element-property :parent parent))) + parent (org-element-parent parent))) (cond ((not previous) (throw 'exit 0)) - ((> (org-element-property :end previous) start) + ((> (org-element-end previous) start) (throw 'exit (org--get-expected-indentation previous t))) - ((memq (org-element-type previous) - '(footnote-definition inlinetask)) - (setq start (org-element-property :begin previous))) + ((org-element-type-p + previous '(footnote-definition inlinetask)) + (setq start (org-element-begin previous))) ;; Do not indent like previous when the previous ;; element is headline data and `org-adapt-indentation' ;; is set to `headline-data'. @@ -18808,16 +19679,16 @@ ELEMENT." (or (org-at-heading-p) (org--at-headline-data-p (1- start) previous))) (throw 'exit 0)) - (t (goto-char (org-element-property :begin previous)) + (t (goto-char (org-element-begin previous)) (throw 'exit (if (bolp) (current-indentation) ;; At first paragraph in an item or ;; a footnote definition. (org--get-expected-indentation - (org-element-property :parent previous) t)))))))))) + (org-element-parent previous) t)))))))))) ;; Otherwise, move to the first non-blank line above. (t - (beginning-of-line) + (forward-line 0) (let ((pos (point))) (skip-chars-backward " \r\t\n") (cond @@ -18833,18 +19704,18 @@ ELEMENT." ;; Line above is the first one of a paragraph at the ;; beginning of an item or a footnote definition. Indent ;; like parent. - ((< (line-beginning-position) start) + ((and start (< (line-beginning-position) start)) (org--get-expected-indentation - (org-element-property :parent element) t)) + (org-element-parent element) t)) ;; Line above is the beginning of an element, i.e., point ;; was originally on the blank lines between element's start ;; and contents. - ((= (line-beginning-position) post-affiliated) + ((and post-affiliated (= (line-beginning-position) post-affiliated)) (org--get-expected-indentation element t)) ;; POS is after contents in a greater element. Indent like ;; the beginning of the element. ((and (memq type org-element-greater-elements) - (let ((cend (org-element-property :contents-end element))) + (let ((cend (org-element-contents-end element))) (and cend (<= cend pos)))) ;; As a special case, if point is at the end of a footnote ;; definition or an item, indent like the very last element @@ -18854,19 +19725,17 @@ ELEMENT." (let ((last (org-element-at-point))) (goto-char pos) (org--get-expected-indentation - last (eq (org-element-type last) 'item))) + last (org-element-type-p last 'item))) (goto-char start) (current-indentation))) ;; In any other case, indent like the current line. - (t (current-indentation))))) - ;; Finally, no indentation is needed, fall back to 0. - (t (current-indentation)))))) + (t (current-indentation))))))))) (defun org--align-node-property () "Align node property at point. Alignment is done according to `org-property-format', which see." (when (save-excursion - (beginning-of-line) + (forward-line 0) (looking-at org-property-re)) (org-combine-change-calls (match-beginning 0) (match-end 0) (let ((newtext (concat (match-string 4) @@ -18921,50 +19790,51 @@ list structure. Instead, use \\`\\[org-shiftmetaleft]' or \ Also align node properties according to `org-property-format'." (interactive) - (let* ((element (save-excursion (beginning-of-line) (org-element-at-point-no-context))) + (let* ((element (save-excursion (forward-line 0) (org-element-at-point-no-context))) (type (org-element-type element))) - (unless (or (org-at-heading-p) + (unless (or (org-at-heading-p) ; headline has no indent ever. + ;; Do not indent first element after headline data. (and (eq org-adapt-indentation 'headline-data) (not (org--at-headline-data-p nil element)) - (save-excursion - (goto-char (1- (org-element-property :begin element))) - (or (org-at-heading-p) - (org--at-headline-data-p))))) + ;; Not at headline data and previous is headline data/headline. + (or (memq type '(headline inlinetask)) ; blank lines after heading + (and element + (save-excursion + (goto-char (1- (org-element-begin element))) + (or (org-at-heading-p) + (org--at-headline-data-p))))))) (cond ((and (memq type '(plain-list item)) (= (line-beginning-position) - (org-element-property :post-affiliated element))) + (org-element-post-affiliated element))) nil) ((and (eq type 'latex-environment) - (>= (point) (org-element-property :post-affiliated element)) + (>= (point) (org-element-post-affiliated element)) (< (point) - (org-with-point-at (org-element-property :end element) + (org-with-point-at (org-element-end element) (skip-chars-backward " \t\n") (line-beginning-position 2)))) nil) ((and (eq type 'src-block) org-src-tab-acts-natively (> (line-beginning-position) - (org-element-property :post-affiliated element)) + (org-element-post-affiliated element)) (< (line-beginning-position) - (org-with-point-at (org-element-property :end element) + (org-with-point-at (org-element-end element) (skip-chars-backward " \t\n") (line-beginning-position)))) - ;; At the beginning of a blank line, do some preindentation. This - ;; signals org-src--edit-element to preserve the indentation on exit - (when (and (looking-at-p "^[[:space:]]*$") - (not org-src-preserve-indentation)) - (let ((element (org-element-at-point)) - block-content-ind some-ind) - (org-with-point-at (org-element-property :begin element) - (setq block-content-ind (+ (org-current-text-indentation) - org-edit-src-content-indentation)) - (forward-line) - (save-match-data (re-search-forward "^[ \t]*\\S-" nil t)) - (backward-char) - (setq some-ind (if (looking-at-p "#\\+end_src") - block-content-ind (org-current-text-indentation)))) - (indent-line-to (min block-content-ind some-ind)))) - (org-babel-do-key-sequence-in-edit-buffer (kbd "TAB"))) + (let ((block-content-ind + (when (not (org-src-preserve-indentation-p element)) + (org-with-point-at (org-element-property :begin element) + (+ (org-current-text-indentation) + org-edit-src-content-indentation))))) + (ignore-errors ; do not err when there is no proper major mode + ;; It is important to call `indent-according-to-mode' + ;; rather than `indent-line-function' here or we may + ;; sometimes break `electric-indent-mode' + ;; https://orgmode.org/list/5O9VMGb6WRaqeHR5_NXTb832Z2Lek_5L40YPDA52-S3kPwGYJspI8kLWaGtuq3DXyhtHpj1J7jTIXb39RX9BtCa2ecrWHjijZqI8QAD742U=@proton.me + (org-babel-do-in-edit-buffer (indent-according-to-mode))) + (when (and block-content-ind (looking-at-p "^$")) + (indent-line-to block-content-ind)))) (t (let ((column (org--get-expected-indentation element nil))) ;; Preserve current column. @@ -18987,7 +19857,7 @@ assumed to be significant there." (save-excursion (goto-char start) (skip-chars-forward " \r\t\n") - (unless (eobp) (beginning-of-line)) + (unless (eobp) (forward-line 0)) (let ((indent-to (lambda (ind pos) ;; Set IND as indentation for all lines between point and @@ -19003,7 +19873,7 @@ assumed to be significant there." (if (or (looking-at-p " \r\t\n") (org-at-heading-p)) (forward-line) (let* ((element (org-element-at-point)) (type (org-element-type element)) - (element-end (copy-marker (org-element-property :end element))) + (element-end (copy-marker (org-element-end element))) (ind (org--get-expected-indentation element nil))) (cond ;; Element indented as a single block. Example blocks @@ -19012,13 +19882,11 @@ assumed to be significant there." ;; boundaries can. ((or (memq type '(export-block latex-environment)) (and (eq type 'example-block) - (not - (or org-src-preserve-indentation - (org-element-property :preserve-indent element))))) + (not (org-src-preserve-indentation-p element)))) (let ((offset (- ind (current-indentation)))) (unless (zerop offset) - (indent-rigidly (org-element-property :begin element) - (org-element-property :end element) + (indent-rigidly (org-element-begin element) + (org-element-end element) offset))) (goto-char element-end)) ;; Elements indented line wise. Be sure to exclude @@ -19026,11 +19894,11 @@ assumed to be significant there." ;; blocks from this category as they are treated ;; specially later. ((or (memq type '(paragraph table table-row)) - (not (or (org-element-property :contents-begin element) - (memq type '(example-block src-block))))) + (not (or (org-element-contents-begin element) + (memq type '(example-block src-block))))) (when (eq type 'node-property) (org--align-node-property) - (beginning-of-line)) + (forward-line 0)) (funcall indent-to ind (min element-end end))) ;; Elements consisting of three parts: before the ;; contents, the contents, and after the contents. The @@ -19039,11 +19907,11 @@ assumed to be significant there." ;; indented as a single block. (t (let* ((post (copy-marker - (org-element-property :post-affiliated element))) + (org-element-post-affiliated element))) (cbeg (copy-marker (cond - ((not (org-element-property :contents-begin element)) + ((not (org-element-contents-begin element)) ;; Fake contents for source blocks. (org-with-wide-buffer (goto-char post) @@ -19058,9 +19926,9 @@ assumed to be significant there." (end-of-line) (skip-chars-forward " \r\t\n") (if (eobp) (point) (line-beginning-position)))) - (t (org-element-property :contents-begin element))))) + (t (org-element-contents-begin element))))) (cend (copy-marker - (or (org-element-property :contents-end element) + (or (org-element-contents-end element) ;; Fake contents for source blocks. (org-with-wide-buffer (goto-char element-end) @@ -19073,8 +19941,8 @@ assumed to be significant there." (cond ((eq type 'plain-list) (let ((offset (- ind (org-current-text-indentation)))) (unless (zerop offset) - (indent-rigidly (org-element-property :begin element) - (org-element-property :end element) + (indent-rigidly (org-element-begin element) + (org-element-end element) offset)) (goto-char cbeg))) ((eq type 'item) (goto-char cbeg)) @@ -19101,37 +19969,31 @@ assumed to be significant there." (set-marker end nil)))) (defun org-indent-drawer () - "Indent the drawer at point." + "Indent the drawer at point. +Signal an error when not at a drawer." (interactive) - (unless (save-excursion - (beginning-of-line) - (looking-at-p org-drawer-regexp)) - (user-error "Not at a drawer")) - (let ((element (org-element-at-point-no-context))) - (unless (memq (org-element-type element) '(drawer property-drawer)) + (let ((element (org-element-at-point))) + (unless (org-element-type-p element '(drawer property-drawer)) (user-error "Not at a drawer")) (org-with-wide-buffer - (org-indent-region (org-element-property :begin element) - (org-element-property :end element)))) + (org-indent-region (org-element-begin element) + (org-element-end element)))) (message "Drawer at point indented")) (defun org-indent-block () - "Indent the block at point." + "Indent the block at point. +Signal an error when not at a block." (interactive) - (unless (save-excursion - (beginning-of-line) - (let ((case-fold-search t)) - (looking-at-p "[ \t]*#\\+\\(begin\\|end\\)_"))) - (user-error "Not at a block")) - (let ((element (org-element-at-point-no-context))) - (unless (memq (org-element-type element) - '(comment-block center-block dynamic-block example-block - export-block quote-block special-block - src-block verse-block)) + (let ((element (org-element-at-point))) + (unless (org-element-type-p + element + '(comment-block center-block dynamic-block example-block + export-block quote-block special-block + src-block verse-block)) (user-error "Not at a block")) (org-with-wide-buffer - (org-indent-region (org-element-property :begin element) - (org-element-property :end element)))) + (org-indent-region (org-element-begin element) + (org-element-end element)))) (message "Block at point indented")) @@ -19202,15 +20064,15 @@ matches in paragraphs or comments, use it." (unless (org-at-heading-p) (let* ((p (line-beginning-position)) (element (save-excursion - (beginning-of-line) + (forward-line 0) (org-element-at-point))) (type (org-element-type element)) - (post-affiliated (org-element-property :post-affiliated element))) + (post-affiliated (org-element-post-affiliated element))) (unless (< p post-affiliated) (cl-case type (comment (save-excursion - (beginning-of-line) + (forward-line 0) (looking-at "[ \t]*") (concat (match-string 0) "# "))) (footnote-definition "") @@ -19219,12 +20081,12 @@ matches in paragraphs or comments, use it." (paragraph ;; Fill prefix is usually the same as the current line, ;; unless the paragraph is at the beginning of an item. - (let ((parent (org-element-property :parent element))) + (let ((parent (org-element-parent element))) (save-excursion - (beginning-of-line) - (cond ((eq (org-element-type parent) 'item) + (forward-line 0) + (cond ((org-element-type-p parent 'item) (make-string (org-list-item-body-column - (org-element-property :begin parent)) + (org-element-begin parent)) ?\s)) ((and adaptive-fill-regexp ;; Locally disable @@ -19234,7 +20096,7 @@ matches in paragraphs or comments, use it." (let (adaptive-fill-function) (fill-context-prefix post-affiliated - (org-element-property :end element))))) + (org-element-end element))))) ((looking-at "[ \t]+") (match-string 0)) (t ""))))) (comment-block @@ -19243,11 +20105,11 @@ matches in paragraphs or comments, use it." (forward-line) (point))) (cend (save-excursion - (goto-char (org-element-property :end element)) + (goto-char (org-element-end element)) (skip-chars-backward " \r\t\n") (line-beginning-position)))) (when (and (>= p cbeg) (< p cend)) - (if (save-excursion (beginning-of-line) (looking-at "[ \t]+")) + (if (save-excursion (forward-line 0) (looking-at "[ \t]+")) (match-string 0) "")))))))))) @@ -19291,15 +20153,15 @@ a footnote definition, try to fill the first paragraph within." (table (when (eq (org-element-property :type element) 'org) (save-excursion - (goto-char (org-element-property :post-affiliated element)) + (goto-char (org-element-post-affiliated element)) (org-table-align))) t) (paragraph ;; Paragraphs may contain `line-break' type objects. (let ((beg (max (point-min) - (org-element-property :contents-begin element))) + (org-element-contents-begin element))) (end (min (point-max) - (org-element-property :contents-end element)))) + (org-element-contents-end element)))) ;; Do nothing if point is at an affiliated keyword. (if (< (line-end-position) beg) t ;; Fill paragraph, taking line breaks into account. @@ -19307,10 +20169,10 @@ a footnote definition, try to fill the first paragraph within." (goto-char beg) (let ((cuts (list beg))) (while (re-search-forward "\\\\\\\\[ \t]*\n" end t) - (when (eq 'line-break - (org-element-type - (save-excursion (backward-char) - (org-element-context)))) + (when (org-element-type-p + (save-excursion (backward-char) + (org-element-context)) + 'line-break) (push (point) cuts))) (dolist (c (delq end cuts)) (fill-region-as-paragraph c end justify) @@ -19322,12 +20184,12 @@ a footnote definition, try to fill the first paragraph within." (comment-block (let* ((case-fold-search t) (beg (save-excursion - (goto-char (org-element-property :begin element)) + (goto-char (org-element-begin element)) (re-search-forward "^[ \t]*#\\+begin_comment" nil t) (forward-line) (point))) (end (save-excursion - (goto-char (org-element-property :end element)) + (goto-char (org-element-end element)) (re-search-backward "^[ \t]*#\\+end_comment" nil t) (line-beginning-position)))) (if (or (< (point) beg) (> (point) end)) t @@ -19335,14 +20197,14 @@ a footnote definition, try to fill the first paragraph within." (save-excursion (end-of-line) (re-search-backward "^[ \t]*$" beg 'move) (line-beginning-position)) - (save-excursion (beginning-of-line) + (save-excursion (forward-line 0) (re-search-forward "^[ \t]*$" end 'move) (line-beginning-position)) justify)))) ;; Fill comments. (comment - (let ((begin (org-element-property :post-affiliated element)) - (end (org-element-property :end element))) + (let ((begin (org-element-post-affiliated element)) + (end (org-element-end element))) (when (and (>= (point) begin) (<= (point) end)) (let ((begin (save-excursion (end-of-line) @@ -19359,7 +20221,7 @@ a footnote definition, try to fill the first paragraph within." (when (> end begin) (let ((fill-prefix (save-excursion - (beginning-of-line) + (forward-line 0) (looking-at "[ \t]*#") (let ((comment-prefix (match-string 0))) (goto-char (match-end 0)) @@ -19480,7 +20342,7 @@ region only contains such lines." ;; elements or at the beginning of a headline or an inlinetask, ;; and before any one-line elements (e.g., a clock). (progn - (beginning-of-line) + (forward-line 0) (let* ((element (org-element-at-point)) (type (org-element-type element))) (cond @@ -19491,14 +20353,14 @@ region only contains such lines." ((and (memq type '(babel-call clock comment diary-sexp headline horizontal-rule keyword paragraph planning)) - (<= (org-element-property :post-affiliated element) (point))) + (<= (org-element-post-affiliated element) (point))) (skip-chars-forward " \t") (insert ": ")) ((and (looking-at-p "[ \t]*$") (or (eq type 'inlinetask) (save-excursion (skip-chars-forward " \r\t\n") - (<= (org-element-property :end element) (point))))) + (<= (org-element-end element) (point))))) (delete-region (point) (line-end-position)) (org-indent-line) (insert ": ")) @@ -19510,7 +20372,7 @@ region only contains such lines." (end (copy-marker (save-excursion (goto-char (region-end)) - (unless (eolp) (beginning-of-line)) + (unless (eolp) (forward-line 0)) (if (save-excursion (re-search-backward "\\S-" begin t)) (progn (skip-chars-backward " \r\t\n") (point)) (point))))) @@ -19522,8 +20384,8 @@ region only contains such lines." (when (eobp) (throw 'not-all-p nil)) (while (< (point) end) (let ((element (org-element-at-point))) - (if (eq (org-element-type element) 'fixed-width) - (goto-char (org-element-property :end element)) + (if (org-element-type-p element 'fixed-width) + (goto-char (org-element-end element)) (throw 'not-all-p nil)))) t)))) (if all-fixed-width-p @@ -19562,8 +20424,8 @@ region only contains such lines." (forward-line))) ((looking-at-p "[ \t]*:\\( \\|$\\)") (let* ((element (org-element-at-point)) - (element-end (org-element-property :end element))) - (if (eq (org-element-type element) 'fixed-width) + (element-end (org-element-end element))) + (if (org-element-type-p element 'fixed-width) (progn (goto-char element-end) (skip-chars-backward " \r\t\n") (forward-line)) @@ -19588,11 +20450,12 @@ Optional arguments START and END can be used to limit the range." (end (or end (point-max)))) (save-excursion (goto-char start) - (while (and (< (point) end) (re-search-forward org-block-regexp end t)) + (while (and (< (point) end) (re-search-forward "^[ \t]*#\\+begin" end t)) (save-excursion (save-match-data (goto-char (match-beginning 0)) - (funcall function))))))) + (when (org-at-block-p) + (funcall function)))))))) (defun org-next-block (arg &optional backward block-regexp) "Jump to the next block. @@ -19614,21 +20477,23 @@ Throw an error if no block is found." (count (or arg 1)) (origin (point)) last-element) - (if backward (beginning-of-line) (end-of-line)) + (if backward (forward-line 0) + (let ((inhibit-field-text-motion t)) (end-of-line))) (while (and (> count 0) (funcall search-fn re nil t)) (let ((element (save-excursion (goto-char (match-beginning 0)) (save-match-data (org-element-at-point))))) - (when (and (memq (org-element-type element) - '(center-block comment-block dynamic-block - example-block export-block quote-block - special-block src-block verse-block)) + (when (and (org-element-type-p + element + '(center-block comment-block dynamic-block + example-block export-block quote-block + special-block src-block verse-block)) (<= (match-beginning 0) - (org-element-property :post-affiliated element))) + (org-element-post-affiliated element))) (setq last-element element) (cl-decf count)))) (if (= count 0) - (prog1 (goto-char (org-element-property :post-affiliated last-element)) + (prog1 (goto-char (org-element-post-affiliated last-element)) (save-match-data (org-fold-show-context))) (goto-char origin) (user-error "No %s code blocks" (if backward "previous" "further"))))) @@ -19674,18 +20539,18 @@ If the line is empty, insert comment at its beginning. When point is within a source block, comment according to the related major mode." (if (let ((element (org-element-at-point))) - (and (eq (org-element-type element) 'src-block) + (and (org-element-type-p element 'src-block) (< (save-excursion - (goto-char (org-element-property :post-affiliated element)) + (goto-char (org-element-post-affiliated element)) (line-end-position)) (point)) (> (save-excursion - (goto-char (org-element-property :end element)) + (goto-char (org-element-end element)) (skip-chars-backward " \r\t\n") (line-beginning-position)) (point)))) (org-babel-do-in-edit-buffer (call-interactively 'comment-dwim)) - (beginning-of-line) + (forward-line 0) (if (looking-at "\\s-*$") (delete-region (point) (line-end-position)) (open-line 1)) (org-indent-line) @@ -19698,23 +20563,27 @@ Uncomment each non-blank line between BEG and END if it only contains commented lines. Otherwise, comment them. If region is strictly within a source block, use appropriate comment syntax." (if (let ((element (org-element-at-point))) - (and (eq (org-element-type element) 'src-block) + (and (org-element-type-p element 'src-block) (< (save-excursion - (goto-char (org-element-property :post-affiliated element)) + (goto-char (org-element-post-affiliated element)) (line-end-position)) beg) (>= (save-excursion - (goto-char (org-element-property :end element)) + (goto-char (org-element-end element)) (skip-chars-backward " \r\t\n") (line-beginning-position)) end))) ;; Translate region boundaries for the Org buffer to the source ;; buffer. - (let ((offset (- end beg))) + (let (src-end) + (save-excursion + (goto-char end) + (org-babel-do-in-edit-buffer + (setq src-end (point)))) (save-excursion (goto-char beg) (org-babel-do-in-edit-buffer - (comment-or-uncomment-region (point) (+ offset (point)))))) + (comment-or-uncomment-region (point) src-end)))) (save-restriction ;; Restrict region (narrow-to-region (save-excursion (goto-char beg) @@ -19730,7 +20599,7 @@ strictly within a source block, use appropriate comment syntax." (goto-char (point-min)) (while (and (not (eobp)) (let ((element (org-element-at-point))) - (and (eq (org-element-type element) 'comment) + (and (org-element-type-p element 'comment) (goto-char (min (point-max) (org-element-property :end element))))))) @@ -19767,12 +20636,10 @@ strictly within a source block, use appropriate comment syntax." (defun org-comment-dwim (_arg) "Call the comment command you mean. Call `org-toggle-comment' if on a heading, otherwise call -`comment-dwim', within a source edit buffer if needed." +`comment-dwim'." (interactive "*P") (cond ((org-at-heading-p) (call-interactively #'org-toggle-comment)) - ((org-in-src-block-p) - (org-babel-do-in-edit-buffer (call-interactively #'comment-dwim))) (t (call-interactively #'comment-dwim)))) @@ -19853,6 +20720,7 @@ Return a new timestamp object." ;; Set new type. (org-element-put-property split-ts :type (if (eq type 'active-range) 'active 'inactive)) + (org-element-put-property split-ts :range-type nil) ;; Copy start properties over end properties if END is ;; non-nil. Otherwise, copy end properties over `start' ones. (let ((p-alist '((:minute-start . :minute-end) @@ -19874,7 +20742,7 @@ Return a new timestamp object." (defun org-timestamp-translate (timestamp &optional boundary) "Translate TIMESTAMP object to custom format. -Format string is defined in `org-time-stamp-custom-formats', +Format string is defined in `org-timestamp-custom-formats', which see. When optional argument BOUNDARY is non-nil, it is either the @@ -19895,6 +20763,281 @@ it has a `diary' type." (org-format-timestamp timestamp fmt t)) (org-format-timestamp timestamp fmt (eq boundary 'end))))))) +;;; Yank media handler and DND +(defun org-setup-yank-dnd-handlers () + "Setup the `yank-media' and DND handlers for buffer." + (let ((handler (if (>= emacs-major-version 30) + #'org--dnd-multi-local-file-handler + #'org--dnd-local-file-handler))) + (setq-local dnd-protocol-alist + (append + (list (cons "^file:///" handler) + (cons "^file:/[^/]" handler) + (cons "^file:[^/]" handler)) + dnd-protocol-alist))) + (when (fboundp 'yank-media-handler) + (yank-media-handler "image/.*" #'org--image-yank-media-handler) + ;; Looks like different DEs go for different handler names, + ;; https://larsee.com/blog/2019/05/clipboard-files/. + (yank-media-handler "x/special-\\(?:gnome\\|KDE\\|mate\\)-files" + #'org--copied-files-yank-media-handler)) + (when (boundp 'x-dnd-direct-save-function) + (setq-local x-dnd-direct-save-function #'org--dnd-xds-function))) + +(defcustom org-yank-image-save-method 'attach + "Method to save images yanked from clipboard and dropped to Emacs. +It can be the symbol `attach' to add it as an attachment, or a +directory name to copy/cut the image to that directory." + :group 'org + :package-version '(Org . "9.7") + :type '(choice (const :tag "Add it as attachment" attach) + (directory :tag "Save it in directory")) + :safe (lambda (x) (eq x 'attach))) + +(defcustom org-yank-image-file-name-function #'org-yank-image-autogen-filename + "Function to generate filename for image yanked from clipboard. +By default, this autogenerates a filename based on the current +time. +It is called with no arguments and should return a string without +any extension which is used as the filename." + :group 'org + :package-version '(Org . "9.7") + :type '(radio (function-item :doc "Autogenerate filename" + org-yank-image-autogen-filename) + (function-item :doc "Ask for filename" + org-yank-image-read-filename) + function)) + +(defun org-yank-image-autogen-filename () + "Autogenerate filename for image in clipboard." + (format-time-string "clipboard-%Y%m%dT%H%M%S.%6N")) + +(defun org-yank-image-read-filename () + "Read filename for image in clipboard." + (read-string "Basename for image file without extension: ")) + +(declare-function org-attach-attach "org-attach" (file &optional visit-dir method)) + +(defun org--image-yank-media-handler (mimetype data) + "Save image DATA of mime-type MIMETYPE and insert link at point. +It is saved as per `org-yank-image-save-method'. The name for the +image is prompted and the extension is automatically added to the +end." + (cl-assert (fboundp 'mailcap-mime-type-to-extension)) ; Emacs >=29 + (cl-assert (fboundp 'file-name-with-extension)) ; Emacs >=28 + (let* ((ext (symbol-name + (with-no-warnings ; Suppress warning in Emacs <29 + (mailcap-mime-type-to-extension mimetype)))) + (iname (funcall org-yank-image-file-name-function)) + (filename (with-no-warnings ; Suppress warning in Emacs <28 + (file-name-with-extension iname ext))) + (absname (expand-file-name + filename + (if (eq org-yank-image-save-method 'attach) + temporary-file-directory + org-yank-image-save-method))) + link) + (when (and (not (eq org-yank-image-save-method 'attach)) + (not (file-directory-p org-yank-image-save-method))) + (make-directory org-yank-image-save-method t)) + ;; DATA is a raw image. Tell Emacs to write it raw, without + ;; trying to auto-detect the coding system. + (let ((coding-system-for-write 'emacs-internal)) + (with-temp-file absname + (insert data))) + (if (null (eq org-yank-image-save-method 'attach)) + (setq link (org-link-make-string (concat "file:" (file-relative-name absname)))) + (require 'org-attach) + (org-attach-attach absname nil 'mv) + (setq link (org-link-make-string (concat "attachment:" filename)))) + (insert link))) + +;; I cannot find a spec for this but +;; https://indigo.re/posts/2021-12-21-clipboard-data.html and pcmanfm +;; suggests that this is the format. +(defun org--copied-files-yank-media-handler (_mimetype data) + "Handle copied or cut files from file manager. +They are handled as per `org-yank-dnd-method'. +DATA is a string where the first line is the operation to +perform: copy or cut. Rest of the lines are file: links to the +concerned files." + ;; pcmanfm adds a null byte at the end for some reason. + (let* ((data (split-string data "[\0\n\r]" t)) + (files (cdr data)) + (action (if (equal (car data) "cut") + 'copy + 'move)) + (sep (if (= (length files) 1) "" " "))) + (dolist (f files) + (if (file-readable-p f) + (org--dnd-local-file-handler f action sep) + (message "File `%s' is not readable, skipping" f))))) + +(defcustom org-yank-dnd-method 'ask + "Action to perform on the dropped and the pasted files. +When the value is the symbol, + . `attach' -- attach dropped/pasted file + . `open' -- visit/open dropped/pasted file in Emacs + . `file-link' -- insert file: link to dropped/pasted file + . `ask' -- ask what to do out of the above." + :group 'org + :package-version '(Org . "9.7") + :type '(choice (const :tag "Attach" attach) + (const :tag "Open/Visit file" open) + (const :tag "Insert file: link" file-link) + (const :tag "Ask what to do" ask))) + +(defcustom org-yank-dnd-default-attach-method nil + "Default attach method to use when DND action is unspecified. +This attach method is used when the DND action is `private'. +This is also used when `org-yank-image-save-method' is nil. +When nil, use `org-attach-method'." + :group 'org + :package-version '(Org . "9.7") + :type '(choice (const :tag "Default attach method" nil) + (const :tag "Copy" cp) + (const :tag "Move" mv) + (const :tag "Hard link" ln) + (const :tag "Symbolic link" lns))) + +(declare-function mailcap-file-name-to-mime-type "mailcap" (file-name)) +(defvar org-attach-method) + +(defun org--dnd-rmc (prompt choices) + "Display a menu or dialog and select with PROMPT among CHOICES. +PROMPT is the prompt string. CHOICES is a list of choices. Each +choice is a list of (key description value). VALUE from the selected +choice is returned." + (if (null (and + ;; Emacs <=28 does not have `use-dialog-box-p'. + (fboundp 'use-dialog-box-p) + (use-dialog-box-p))) + (progn + (setq choices + (mapcar + (pcase-lambda (`(,key ,message ,val)) + ;; `read-multiple-choice' expects VAL to be a long + ;; description of the choice - string or nil. Move VAL + ;; further, so that it is not seen by the extended + ;; help in `read-multiple-choice'. + (list key message nil val)) + choices)) + (nth 3 (read-multiple-choice prompt choices))) + (setq choices + (mapcar + (pcase-lambda (`(_key ,message ,val)) + (cons (capitalize message) val)) + choices)) + (x-popup-menu t (list prompt (cons "" choices))))) + +(defun org--dnd-multi-local-file-handler (urls action) + "Handle file URLS as per ACTION. +URLS is a list of file URL." + (let ((sep (if (= (length urls) 1) "" " "))) + (dolist (u urls) + (org--dnd-local-file-handler u action sep)))) + +(put 'org--dnd-multi-local-file-handler 'dnd-multiple-handler t) + +(defun org--dnd-local-file-handler (url action &optional separator) + "Handle file URL as per ACTION. +SEPARATOR is the string to insert after each link. It may be nil +in which case, space is inserted." + (unless separator + (setq separator " ")) + (let ((method (if (eq org-yank-dnd-method 'ask) + (org--dnd-rmc + "What to do with file?" + '((?a "attach" attach) + (?o "open" open) + (?f "insert file: link" file-link))) + org-yank-dnd-method))) + (pcase method + (`attach (org--dnd-attach-file url action separator)) + (`open (dnd-open-local-file url action)) + (`file-link + (let ((filename (dnd-get-local-file-name url))) + (insert (org-link-make-string (concat "file:" filename)) separator)))))) + +(defun org--dnd-attach-file (url action separator) + "Attach filename given by URL using method pertaining to ACTION. +If ACTION is `move', use `mv' attach method. +If `copy', use `cp' attach method. +If `ask', ask the user. +If `private', use the method denoted in `org-yank-dnd-default-attach-method'. +The action `private' is always returned. + +SEPARATOR is the string to insert after each link." + (require 'mailcap) + (require 'org-attach) + (let* ((filename (dnd-get-local-file-name url)) + (mimetype (mailcap-file-name-to-mime-type filename)) + (separatep (and (string-prefix-p "image/" mimetype) + (not (eq 'attach org-yank-image-save-method)))) + (method (pcase action + ('copy 'cp) + ('move 'mv) + ('ask (org--dnd-rmc + "Attach using method" + '((?c "copy" cp) + (?m "move" mv) + (?l "hard link" ln) + (?s "symbolic link" lns)))) + ('private (or org-yank-dnd-default-attach-method + org-attach-method))))) + (if separatep + (progn + (unless (file-directory-p org-yank-image-save-method) + (make-directory org-yank-image-save-method t)) + (funcall + (pcase method + ('cp #'copy-file) + ('mv #'rename-file) + ('ln #'add-name-to-file) + ('lns #'make-symbolic-link)) + filename + (expand-file-name (file-name-nondirectory filename) + org-yank-image-save-method))) + (org-attach-attach filename nil method)) + (insert + (org-link-make-string + (concat (if separatep + "file:" + "attachment:") + (if separatep + (expand-file-name (file-name-nondirectory filename) + org-yank-image-save-method) + (file-name-nondirectory filename)))) + separator) + 'private)) + +(defvar-local org--dnd-xds-method nil + "The method to use for dropped file.") +(defun org--dnd-xds-function (need-name filename) + "Handle file with FILENAME dropped via XDS protocol. +When NEED-NAME is t, FILENAME is the base name of the file to be +saved. +When NEED-NAME is nil, the drop is complete." + (if need-name + (let ((method (if (eq org-yank-dnd-method 'ask) + (org--dnd-rmc + "What to do with dropped file?" + '((?a "attach" attach) + (?o "open" open) + (?f "insert file: link" file-link))) + org-yank-dnd-method))) + (setq-local org--dnd-xds-method method) + (pcase method + (`attach (expand-file-name filename (org-attach-dir 'create))) + (`open (expand-file-name (make-temp-name "emacs.") temporary-file-directory)) + (`file-link (read-file-name "Write file to: " nil nil nil filename)))) + (pcase org--dnd-xds-method + (`attach (insert (org-link-make-string + (concat "attachment:" (file-name-nondirectory filename))))) + (`file-link (insert (org-link-make-string (concat "file:" filename)))) + (`open (find-file filename))) + (setq-local org--dnd-xds-method nil))) + ;;; Other stuff (defvar reftex-docstruct-symbol) @@ -19954,7 +21097,7 @@ With argument N not nil or 1, move forward N - 1 lines first." ;; characters if line starts with such of these (e.g., with ;; a link at column 0). Really move to the beginning of the ;; current visible line. - (beginning-of-line)) + (forward-line 0)) (cond ;; No special behavior. Point is already at the beginning of ;; a line, logical or visual. @@ -19972,11 +21115,12 @@ With argument N not nil or 1, move forward N - 1 lines first." (if (eq special 'reversed) (when (and (= origin bol) (eq last-command this-command)) (goto-char refpos)) - (when (or (> origin refpos) (= origin bol)) + (when (or (> origin refpos) (<= origin bol)) (goto-char refpos))))) ((and (looking-at org-list-full-item-re) - (memq (org-element-type (save-match-data (org-element-at-point))) - '(item plain-list))) + (org-element-type-p + (save-match-data (org-element-at-point)) + '(item plain-list))) ;; Set special position at first white space character after ;; bullet, and check-box, if any. (let ((after-bullet @@ -19987,7 +21131,7 @@ With argument N not nil or 1, move forward N - 1 lines first." (if (eq special 'reversed) (when (and (= (point) origin) (eq last-command this-command)) (goto-char after-bullet)) - (when (or (> origin after-bullet) (= (point) origin)) + (when (or (> origin after-bullet) (>= (point) origin)) (goto-char after-bullet))))) ;; No special context. Point is already at beginning of line. (t nil)))) @@ -20017,7 +21161,7 @@ With argument N not nil or 1, move forward N - 1 lines first." ;; At a headline, with tags. ((and special (save-excursion - (beginning-of-line) + (forward-line 0) (let ((case-fold-search nil)) (looking-at org-complex-heading-regexp))) (match-end 5)) @@ -20042,7 +21186,7 @@ With argument N not nil or 1, move forward N - 1 lines first." (goto-char tags) (end-of-line))) (t - (if (or (< origin tags) (= origin (line-end-position))) + (if (or (< origin tags) (>= origin (line-end-position))) (goto-char tags) (end-of-line)))))) ((bound-and-true-p visual-line-mode) @@ -20061,18 +21205,18 @@ This will call `backward-sentence' or `org-table-beginning-of-field', depending on context." (interactive) (let* ((element (org-element-at-point)) - (contents-begin (org-element-property :contents-begin element)) - (table (org-element-lineage element '(table) t))) + (contents-begin (org-element-contents-begin element)) + (table (org-element-lineage element 'table t))) (if (and table (> (point) contents-begin) - (<= (point) (org-element-property :contents-end table))) + (<= (point) (org-element-contents-end table))) (call-interactively #'org-table-beginning-of-field) (save-restriction (when (and contents-begin (< (point-min) contents-begin) (> (point) contents-begin)) (narrow-to-region contents-begin - (org-element-property :contents-end element))) + (org-element-contents-end element))) (call-interactively #'backward-sentence))))) (defun org-forward-sentence (&optional _arg) @@ -20086,20 +21230,20 @@ depending on context." (narrow-to-region (line-beginning-position) (line-end-position)) (call-interactively #'forward-sentence)) (let* ((element (org-element-at-point)) - (contents-end (org-element-property :contents-end element)) - (table (org-element-lineage element '(table) t))) + (contents-end (org-element-contents-end element)) + (table (org-element-lineage element 'table t))) (if (and table - (>= (point) (org-element-property :contents-begin table)) + (>= (point) (org-element-contents-begin table)) (< (point) contents-end)) (call-interactively #'org-table-end-of-field) (save-restriction (when (and contents-end (> (point-max) contents-end) ;; Skip blank lines between elements. - (< (org-element-property :end element) + (< (org-element-end element) (save-excursion (goto-char contents-end) (skip-chars-forward " \r\t\n")))) - (narrow-to-region (org-element-property :contents-begin element) + (narrow-to-region (org-element-contents-begin element) contents-end)) ;; End of heading is considered as the end of a sentence. (let ((sentence-end (concat (sentence-end) "\\|^\\*+ .*$"))) @@ -20134,7 +21278,7 @@ see)." (kill-region (point) (line-end-position)) (kill-region (point) end))) ;; Only align tags when we are still on a heading: - (if (org-at-heading-p) (org-align-tags))) + (if (and (org-at-heading-p) org-auto-align-tags) (org-align-tags))) (t (kill-region (point) (line-end-position))))) (defun org-yank (&optional arg) @@ -20199,7 +21343,7 @@ interactive command with similar behavior." (goto-char beg) (when (and (bolp) subtreep (not (setq swallowp - (org-yank-folding-would-swallow-text beg end)))) + (org-yank-folding-would-swallow-text beg end)))) (org-with-limited-levels (or (looking-at org-outline-regexp) (re-search-forward org-outline-regexp-bol end t)) @@ -20215,7 +21359,7 @@ interactive command with similar behavior." (goto-char end) (skip-chars-forward " \t\n\r") - (beginning-of-line 1) + (forward-line 0) (push-mark beg 'nomsg))) ((and subtreep org-yank-adjusted-subtrees) (let ((beg (line-beginning-position))) @@ -20240,53 +21384,23 @@ interactive command with similar behavior." (<= (org-outline-level) level)))))))) (defun org-back-to-heading (&optional invisible-ok) - "Go back to beginning of heading." - (beginning-of-line) + "Go back to beginning of heading or inlinetask." + (forward-line 0) (or (and (org-at-heading-p (not invisible-ok)) (not (and (featurep 'org-inlinetask) (fboundp 'org-inlinetask-end-p) (org-inlinetask-end-p)))) - (if (org-element--cache-active-p) - (let ((heading (org-element-lineage (org-element-at-point) - '(headline inlinetask) - 'include-self))) - (when heading - (goto-char (org-element-property :begin heading))) - (while (and (not invisible-ok) - heading - (org-fold-folded-p)) - (goto-char (org-fold-core-previous-visibility-change)) - (setq heading (org-element-lineage (org-element-at-point) - '(headline inlinetask) - 'include-self)) - (when heading - (goto-char (org-element-property :begin heading)))) - (unless heading - (user-error "Before first headline at position %d in buffer %s" - (point) (current-buffer))) - (point)) - (let (found) - (save-excursion - ;; At inlinetask end. Move to bol, so that the following - ;; search goes to the beginning of the inlinetask. - (when (and (featurep 'org-inlinetask) - (fboundp 'org-inlinetask-end-p) - (org-inlinetask-end-p)) - (goto-char (line-beginning-position))) - (while (not found) - (or (re-search-backward (concat "^\\(?:" outline-regexp "\\)") - nil t) - (user-error "Before first headline at position %d in buffer %s" - (point) (current-buffer))) - ;; Skip inlinetask end. - (if (and (featurep 'org-inlinetask) - (fboundp 'org-inlinetask-end-p) - (org-inlinetask-end-p)) - (org-inlinetask-goto-beginning) - (setq found (and (or invisible-ok (not (org-fold-folded-p))) - (point)))))) - (goto-char found) - found)))) + (unless + (org-element-lineage-map + (org-element-at-point) + (lambda (el) + (goto-char (org-element-begin el)) + (or invisible-ok (not (org-fold-folded-p)))) + '(headline inlinetask) + 'with-self 'first-match) + (user-error "Before first headline at position %d in buffer %s" + (point) (current-buffer)))) + (point)) (defun org-back-to-heading-or-point-min (&optional invisible-ok) "Go back to heading or first point in buffer. @@ -20301,9 +21415,9 @@ instead of back to heading." Respect narrowing." (let ((cached (org-element-at-point nil 'cached))) (if cached - (let ((cached-headline (org-element-lineage cached '(headline) t))) + (let ((cached-headline (org-element-lineage cached 'headline t))) (or (not cached-headline) - (< (org-element-property :begin cached-headline) (point-min)))) + (< (org-element-begin cached-headline) (point-min)))) (org-with-limited-levels (save-excursion (end-of-line) @@ -20313,8 +21427,8 @@ Respect narrowing." "Return t if point is on a (possibly invisible) heading line. If INVISIBLE-NOT-OK is non-nil, an invisible heading line is not ok." (save-excursion - (beginning-of-line) - (and (bolp) (or (not invisible-not-ok) (not (org-fold-folded-p))) + (forward-line 0) + (and (or (not invisible-not-ok) (not (org-fold-folded-p))) (looking-at outline-regexp)))) (defun org-in-commented-heading-p (&optional no-inheritance element) @@ -20323,20 +21437,15 @@ This function also checks ancestors of the current headline, unless optional argument NO-INHERITANCE is non-nil. Optional argument ELEMENT contains element at point." - (save-match-data - (let ((el (or element - (org-element-at-point nil 'cached) - (org-with-wide-buffer - (org-back-to-heading-or-point-min t) - (org-element-at-point))))) - (catch :found - (setq el (org-element-lineage el '(headline inlinetask) 'include-self)) - (if no-inheritance - (org-element-property :commentedp el) - (while el - (when (org-element-property :commentedp el) - (throw :found t)) - (setq el (org-element-property :parent el)))))))) + (unless element + (setq + element + (org-element-lineage + (org-element-at-point) + '(headline inlinetask) 'with-self))) + (if no-inheritance + (org-element-property :commentedp element) + (org-element-property-inherited :commentedp element 'with-self))) (defun org-in-archived-heading-p (&optional no-inheritance element) "Non-nil if point is under an archived heading. @@ -20344,29 +21453,21 @@ This function also checks ancestors of the current headline, unless optional argument NO-INHERITANCE is non-nil. Optional argument ELEMENT contains element at point." - (cond - ((and (not element) (org-before-first-heading-p)) nil) - ((if element - (org-element-property :archivedp element) - (let ((tags (org-get-tags element 'local))) - (and tags - (cl-some (apply-partially #'string= org-archive-tag) tags))))) - (no-inheritance nil) - (t - (if (or element (org-element--cache-active-p)) - (catch :archived - (unless element (setq element (org-element-at-point))) - (while element - (when (org-element-property :archivedp element) - (throw :archived t)) - (setq element (org-element-property :parent element)))) - (save-excursion (and (org-up-heading-safe) (org-in-archived-heading-p))))))) + (unless element + (setq + element + (org-element-lineage + (org-element-at-point) + '(headline inlinetask) 'with-self))) + (if no-inheritance + (org-element-property :archivedp element) + (org-element-property-inherited :archivedp element 'with-self))) (defun org-at-comment-p nil "Return t if cursor is in a commented line." (save-excursion (save-match-data - (beginning-of-line) + (forward-line 0) (looking-at org-comment-regexp)))) (defun org-at-keyword-p nil @@ -20395,7 +21496,7 @@ empty." (and (looking-at "[ \t]*$") org-todo-line-regexp (save-excursion - (beginning-of-line) + (forward-line 0) (looking-at org-todo-line-regexp) (string= (match-string 3) ""))))) @@ -20408,55 +21509,37 @@ This function considers both visible and invisible heading lines. With argument, move up ARG levels." (outline-up-heading arg t)) -(defvar-local org--up-heading-cache nil - "Buffer-local `org-up-heading-safe' cache.") -(defvar-local org--up-heading-cache-tick nil - "Buffer `buffer-chars-modified-tick' in `org--up-heading-cache'.") (defun org-up-heading-safe () "Move to the heading line of which the present line is a subheading. -This version will not throw an error. It will return the level of the -headline found, or nil if no higher level is found. - -Also, this function will be a lot faster than `outline-up-heading', -because it relies on stars being the outline starters. This can really -make a significant difference in outlines with very many siblings." - (let ((element (and (org-element--cache-active-p) - (org-element-at-point nil t)))) - (if element - (let* ((current-heading (org-element-lineage element '(headline inlinetask) 'with-self)) - (parent (org-element-lineage current-heading '(headline)))) - (if (and parent - (<= (point-min) (org-element-property :begin parent))) - (progn - (goto-char (org-element-property :begin parent)) - (org-element-property :level parent)) - (when (and current-heading - (<= (point-min) (org-element-property :begin current-heading))) - (goto-char (org-element-property :begin current-heading)) - nil))) - (when (ignore-errors (org-back-to-heading t)) - (let (level-cache) - (unless org--up-heading-cache - (setq org--up-heading-cache (make-hash-table))) - (if (and (eq (buffer-chars-modified-tick) org--up-heading-cache-tick) - (setq level-cache (gethash (point) org--up-heading-cache))) - (when (<= (point-min) (car level-cache) (point-max)) - ;; Parent is inside accessible part of the buffer. - (progn (goto-char (car level-cache)) - (cdr level-cache))) - ;; Buffer modified. Invalidate cache. - (unless (eq (buffer-chars-modified-tick) org--up-heading-cache-tick) - (setq-local org--up-heading-cache-tick - (buffer-chars-modified-tick)) - (clrhash org--up-heading-cache)) - (let* ((level-up (1- (funcall outline-level))) - (pos (point)) - (result (and (> level-up 0) - (re-search-backward - (format "^\\*\\{1,%d\\} " level-up) nil t) - (funcall outline-level)))) - (when result (puthash pos (cons (point) result) org--up-heading-cache)) - result))))))) +Return the true heading level, as number or nil when there is no such +heading. + +When point is not at heading, go to the parent of the current heading. +When point is at or inside an inlinetask, go to the containing +heading. + +This version will not throw an error. It will return the true level +of the headline found, or nil if no higher level is found. + +When no higher level is found, the still move point to the containing +heading, if there is any in the accessible portion of the buffer. + +When narrowing is in effect, ignore headings starting before the +available portion of the buffer." + (let* ((current-heading (org-element-lineage + (org-element-at-point) + '(headline inlinetask) + 'with-self)) + (parent (org-element-lineage current-heading 'headline))) + (if (and parent + (<= (point-min) (org-element-begin parent))) + (progn + (goto-char (org-element-begin parent)) + (org-element-property :true-level parent)) + (when (and current-heading + (<= (point-min) (org-element-begin current-heading))) + (goto-char (org-element-begin current-heading)) + nil)))) (defun org-up-heading-or-point-min () "Move to the heading line of which the present is a subheading, or point-min. @@ -20473,7 +21556,6 @@ point before the first headline or at point-min." (defun org-first-sibling-p () "Is this heading the first child of its parents?" - (interactive) (let ((re org-outline-regexp-bol) level l) (unless (org-at-heading-p t) @@ -20486,7 +21568,7 @@ point before the first headline or at point-min." (< l level))))) (defun org-goto-sibling (&optional previous) - "Goto the next sibling, even if it is invisible. + "Goto the next sibling heading, even if it is invisible. When PREVIOUS is set, go to the previous sibling instead. Returns t when a sibling was found. When none is found, return nil and don't move point." @@ -20495,6 +21577,8 @@ move point." (re org-outline-regexp-bol) level l) (when (ignore-errors (org-back-to-heading t)) + (when (org-element-type-p (org-element-at-point) 'inlinetask) + (org-up-heading-safe)) (setq level (funcall outline-level)) (catch 'exit (or previous (forward-char 1)) @@ -20509,29 +21593,21 @@ move point." "Goto the first child, even if it is invisible. Return t when a child was found. Otherwise don't move point and return nil." - (if (org-element--cache-active-p) - (let ((heading (org-element-lineage - (or element (org-element-at-point)) - '(headline inlinetask org-data) - t))) - (when heading - (unless (or (eq 'inlinetask (org-element-type heading)) - (not (org-element-property :contents-begin heading))) - (let ((pos (point))) - (goto-char (org-element-property :contents-begin heading)) - (if (re-search-forward - org-outline-regexp-bol - (org-element-property :end heading) - t) - (progn (goto-char (match-beginning 0)) t) - (goto-char pos) nil))))) - (let (level (pos (point)) (re org-outline-regexp-bol)) - (when (org-back-to-heading-or-point-min t) - (setq level (org-outline-level)) - (forward-char 1) - (if (and (re-search-forward re nil t) (> (org-outline-level) level)) - (progn (goto-char (match-beginning 0)) t) - (goto-char pos) nil))))) + (let ((heading (org-element-lineage + (or element (org-element-at-point)) + '(headline inlinetask org-data) + 'with-self))) + (when heading + (unless (or (org-element-type-p heading 'inlinetask) + (not (org-element-contents-begin heading))) + (let ((pos (point))) + (goto-char (org-element-contents-begin heading)) + (if (re-search-forward + org-outline-regexp-bol + (org-element-end heading) + t) + (progn (goto-char (match-beginning 0)) t) + (goto-char pos) nil)))))) (defun org-get-next-sibling () "Move to next heading of the same level, and return point. @@ -20558,58 +21634,49 @@ If there is no such heading, return nil." (point))))) (defun org-end-of-subtree (&optional invisible-ok to-heading element) - "Goto to the end of a subtree at point or for ELEMENT heading." - ;; This contains an exact copy of the original function, but it uses - ;; `org-back-to-heading-or-point-min', to make it work also in invisible - ;; trees and before first headline. And is uses an invisible-ok argument. - ;; Under Emacs this is not needed, but the old outline.el needs this fix. - ;; Furthermore, when used inside Org, finding the end of a large subtree - ;; with many children and grandchildren etc, this can be much faster - ;; than the outline version. - (if element - (setq element (org-element-lineage element '(headline inlinetask) 'include-self)) - (org-back-to-heading-or-point-min invisible-ok)) - (unless (and (org-element--cache-active-p) - (let ((cached (or element (org-element-at-point nil t)))) - (and cached - (eq 'headline (org-element-type cached)) - (goto-char (org-element-property - :end cached))))) - (let ((first t) - (level (funcall outline-level))) - (cond ((= level 0) - (goto-char (point-max))) - ((and (derived-mode-p 'org-mode) (< level 1000)) - ;; A true heading (not a plain list item), in Org - ;; This means we can easily find the end by looking - ;; only for the right number of stars. Using a regexp to do - ;; this is so much faster than using a Lisp loop. - (let ((re (concat "^\\*\\{1," (number-to-string level) "\\} "))) - (forward-char 1) - (and (re-search-forward re nil 'move) (beginning-of-line 1)))) - (t - ;; something else, do it the slow way - (while (and (not (eobp)) - (or first (> (funcall outline-level) level))) - (setq first nil) - (outline-next-heading)))))) + "Goto to the end of a visible subtree at point or ELEMENT and return point. +The subtree is considered at first heading parent containing point or +ELEMENT. + +When end of the subtree has blank lines, move point before these blank +lines. + +When INVISIBLE-OK is non-nil, ignore visibility. + +When before first heading, goto `point-max' minus blank lines. +When TO-HEADING is non-nil, go to the next heading or `point-max'." + (when element + (setq element (org-element-lineage + element + '(headline) + 'include-self)) + (goto-char (org-element-begin element))) + (unless (and invisible-ok element) + (org-back-to-heading-or-point-min invisible-ok) + (setq element + (org-element-lineage + (org-element-at-point) + '(headline) + 'include-self))) + (if (org-element-type-p element 'headline) + (goto-char (org-element-end element)) + (goto-char (point-max))) (unless to-heading (when (memq (preceding-char) '(?\n ?\^M)) ;; Go to end of line before heading (forward-char -1) - (when (memq (preceding-char) '(?\n ?\^M)) - ;; leave blank line before heading - (forward-char -1)))) + ;; Skip blank lines + (skip-chars-backward "\n\r\t "))) (point)) (defun org-end-of-meta-data (&optional full) "Skip planning line and properties drawer in current entry. When optional argument FULL is t, also skip planning information, -clocking lines and any kind of drawer. +clocking lines, any kind of drawer, and blank lines When FULL is non-nil but not t, skip planning information, -properties, clocking lines and logbook drawers." +properties, clocking lines, logbook drawers, and blank lines." (org-back-to-heading t) (forward-line) ;; Skip planning information. @@ -20624,7 +21691,7 @@ properties, clocking lines and logbook drawers." (let ((end (save-excursion (outline-next-heading) (point))) (re (concat "[ \t]*$" "\\|" org-clock-line-re))) (while (not (eobp)) - (cond ;; Skip clock lines. + (cond ;; Skip clock lines and blank lines. ((looking-at-p re) (forward-line)) ;; Skip logbook drawer. ((looking-at-p org-logbook-drawer-re) @@ -20680,7 +21747,7 @@ non-nil it will also look at invisible ones." (cl-decf count) (when (= l level) (setq result (point))))))) (goto-char result)) - (beginning-of-line)))) + (forward-line 0)))) (defun org-backward-heading-same-level (arg &optional invisible-ok) "Move backward to the ARG'th subheading at same level as this one. @@ -20694,22 +21761,22 @@ With ARG, repeats or can move backward if negative." (interactive "p") (let ((regexp (concat "^" (org-get-limited-outline-regexp)))) (if (< arg 0) - (beginning-of-line) + (forward-line 0) (end-of-line)) (while (and (< arg 0) (re-search-backward regexp nil :move)) (unless (bobp) - (when (org-fold-folded-p) + (when (org-invisible-p nil t) (goto-char (org-fold-previous-visibility-change)) (unless (looking-at-p regexp) (re-search-backward regexp nil :mode)))) (cl-incf arg)) (while (and (> arg 0) (re-search-forward regexp nil :move)) - (when (org-fold-folded-p) + (when (org-invisible-p nil t) (goto-char (org-fold-next-visibility-change)) (skip-chars-forward " \t\n") (end-of-line)) (cl-decf arg)) - (if (> arg 0) (goto-char (point-max)) (beginning-of-line)))) + (if (> arg 0) (goto-char (point-max)) (forward-line 0)))) (defun org-previous-visible-heading (arg) "Move to the previous visible heading. @@ -20766,7 +21833,7 @@ It also provides the following special moves for convenience: arg)) (defvar org--single-lines-list-is-paragraph t - "Treat plain lists with single line items as a whole paragraph") + "Treat plain lists with single line items as a whole paragraph.") (defun org--paragraph-at-point () "Return paragraph, or equivalent, element at point. @@ -20795,48 +21862,49 @@ Function may return a real element, or a pseudo-element with type (triplet (cond ((memq type '(table property-drawer)) - (list (org-element-property :begin e) - (org-element-property :end e) - (org-element-property :parent e))) + (list (org-element-begin e) + (org-element-end e) + (org-element-parent e))) ((memq type '(node-property table-row)) - (let ((e (org-element-property :parent e))) - (list (org-element-property :begin e) - (org-element-property :end e) - (org-element-property :parent e)))) + (let ((e (org-element-parent e))) + (list (org-element-begin e) + (org-element-end e) + (org-element-parent e)))) ((memq type '(clock diary-sexp keyword)) (let* ((regexp (pcase type (`clock org-clock-line-re) (`diary-sexp "%%(") (_ org-keyword-regexp))) - (end (if (< 0 (org-element-property :post-blank e)) - (org-element-property :end e) + (end (if (< 0 (org-element-post-blank e)) + (org-element-end e) (org-with-wide-buffer (forward-line) (while (looking-at regexp) (forward-line)) (skip-chars-forward " \t\n") (line-beginning-position)))) - (begin (org-with-point-at (org-element-property :begin e) + (begin (org-with-point-at (org-element-begin e) (while (and (not (bobp)) (looking-at regexp)) (forward-line -1)) ;; We may have gotten one line too far. (if (looking-at regexp) (point) (line-beginning-position 2))))) - (list begin end (org-element-property :parent e)))) + (list begin end (org-element-parent e)))) ;; Find the full plain list containing point, the check it ;; contains exactly one line per item. - ((let ((l (org-element-lineage e '(plain-list) t))) - (while (memq (org-element-type (org-element-property :parent l)) - '(item plain-list)) - (setq l (org-element-property :parent l))) + ((let ((l (org-element-lineage e 'plain-list t))) + (while (org-element-type-p + (org-element-parent l) + '(item plain-list)) + (setq l (org-element-parent l))) (and l org--single-lines-list-is-paragraph - (org-with-point-at (org-element-property :post-affiliated l) + (org-with-point-at (org-element-post-affiliated l) (forward-line (length (org-element-property :structure l))) - (= (point) (org-element-property :contents-end l))) + (= (point) (org-element-contents-end l))) ;; Return value. - (list (org-element-property :begin l) - (org-element-property :end l) - (org-element-property :parent l))))) + (list (org-element-begin l) + (org-element-end l) + (org-element-parent l))))) (t nil)))) ;no triplet: return element (pcase triplet (`(,b ,e ,p) @@ -20862,9 +21930,9 @@ See `org-forward-paragraph'." (t (let* ((element (org--paragraph-at-point)) (type (org-element-type element)) - (contents-begin (org-element-property :contents-begin element)) - (end (org-element-property :end element)) - (post-affiliated (org-element-property :post-affiliated element))) + (contents-begin (org-element-contents-begin element)) + (end (org-element-end element)) + (post-affiliated (org-element-post-affiliated element))) (cond ((eq type 'plain-list) (forward-char) @@ -20935,11 +22003,11 @@ See `org-backward-paragraph'." (t (let* ((element (org--paragraph-at-point)) (type (org-element-type element)) - (begin (org-element-property :begin element)) - (post-affiliated (org-element-property :post-affiliated element)) - (contents-end (org-element-property :contents-end element)) - (end (org-element-property :end element)) - (parent (org-element-property :parent element)) + (begin (org-element-begin element)) + (post-affiliated (org-element-post-affiliated element)) + (contents-end (org-element-contents-end element)) + (end (org-element-end element)) + (parent (org-element-parent element)) (reach ;; Move to the visible empty line above position P, or ;; to position P. Return t. @@ -20962,9 +22030,9 @@ See `org-backward-paragraph'." ;; At the beginning of the first element within a greater ;; element. Move to the beginning of the greater element. ((and parent - (not (eq 'section (org-element-type parent))) - (= begin (org-element-property :contents-begin parent))) - (funcall reach (org-element-property :begin parent))) + (not (org-element-type-p parent 'section)) + (= begin (org-element-contents-begin parent))) + (funcall reach (org-element-begin parent))) ;; Since we have to move anyway, find the beginning ;; position of the element above. (t @@ -21024,10 +22092,10 @@ Move to the next element at the same level, when possible." (user-error "Cannot move further down")))) (t (let* ((elem (org-element-at-point)) - (end (org-element-property :end elem)) - (parent (org-element-property :parent elem))) - (cond ((and parent (= (org-element-property :contents-end parent) end)) - (goto-char (org-element-property :end parent))) + (end (org-element-end elem)) + (parent (org-element-parent elem))) + (cond ((and parent (= (org-element-contents-end parent) end)) + (goto-char (org-element-end parent))) ((integer-or-marker-p end) (goto-char end)) (t (message "No element at point"))))))) @@ -21049,7 +22117,7 @@ Move to the previous element at the same level, when possible." (user-error "Cannot move further up")))))) (t (let* ((elem (org-element-at-point)) - (beg (org-element-property :begin elem))) + (beg (org-element-begin elem))) (cond ;; Move to beginning of current element if point isn't ;; there already. @@ -21059,10 +22127,10 @@ Move to the previous element at the same level, when possible." (skip-chars-backward " \r\t\n") (unless (bobp) (let ((prev (org-element-at-point))) - (goto-char (org-element-property :begin prev)) - (while (and (setq prev (org-element-property :parent prev)) - (<= (org-element-property :end prev) beg)) - (goto-char (org-element-property :begin prev))))))))))) + (goto-char (org-element-begin prev)) + (while (and (setq prev (org-element-parent prev)) + (<= (org-element-end prev) beg)) + (goto-char (org-element-begin prev))))))))))) (defun org-up-element () "Move to upper element." @@ -21070,13 +22138,13 @@ Move to the previous element at the same level, when possible." (if (org-with-limited-levels (org-at-heading-p)) (unless (org-up-heading-safe) (user-error "No surrounding element")) (let* ((elem (org-element-at-point)) - (parent (org-element-property :parent elem))) + (parent (org-element-parent elem))) ;; Skip sections - (when (eq 'section (org-element-type parent)) - (setq parent (org-element-property :parent parent))) + (when (org-element-type-p parent 'section) + (setq parent (org-element-parent parent))) (if (and parent - (not (eq (org-element-type parent) 'org-data))) - (goto-char (org-element-property :begin parent)) + (not (org-element-type-p parent 'org-data))) + (goto-char (org-element-begin parent)) (if (org-with-limited-levels (org-before-first-heading-p)) (user-error "No surrounding element") (org-with-limited-levels (org-back-to-heading))))))) @@ -21086,13 +22154,13 @@ Move to the previous element at the same level, when possible." (interactive) (let ((element (org-element-at-point))) (cond - ((memq (org-element-type element) '(plain-list table)) - (goto-char (org-element-property :contents-begin element)) + ((org-element-type-p element '(plain-list table)) + (goto-char (org-element-contents-begin element)) (forward-char)) - ((memq (org-element-type element) org-element-greater-elements) + ((org-element-type-p element org-element-greater-elements) ;; If contents are hidden, first disclose them. (when (org-invisible-p (line-end-position)) (org-cycle)) - (goto-char (or (org-element-property :contents-begin element) + (goto-char (or (org-element-contents-begin element) (user-error "No content for this element")))) (t (user-error "No inner element"))))) @@ -21101,7 +22169,7 @@ Move to the previous element at the same level, when possible." (interactive) (let ((elem (or (org-element-at-point) (user-error "No element at point")))) - (if (eq (org-element-type elem) 'headline) + (if (org-element-type-p elem 'headline) ;; Preserve point when moving a whole tree, even if point was ;; on blank lines below the headline. (let ((offset (skip-chars-backward " \t\n"))) @@ -21109,14 +22177,14 @@ Move to the previous element at the same level, when possible." (forward-char (- offset)))) (let ((prev-elem (save-excursion - (goto-char (org-element-property :begin elem)) + (goto-char (org-element-begin elem)) (skip-chars-backward " \r\t\n") (unless (bobp) - (let* ((beg (org-element-property :begin elem)) + (let* ((beg (org-element-begin elem)) (prev (org-element-at-point)) (up prev)) - (while (and (setq up (org-element-property :parent up)) - (<= (org-element-property :end up) beg)) + (while (and (setq up (org-element-parent up)) + (<= (org-element-end up) beg)) (setq prev up)) prev))))) ;; Error out if no previous element or previous element is @@ -21125,8 +22193,8 @@ Move to the previous element at the same level, when possible." (user-error "Cannot drag element backward") (let ((pos (point))) (org-element-swap-A-B prev-elem elem) - (goto-char (+ (org-element-property :begin prev-elem) - (- pos (org-element-property :begin elem)))))))))) + (goto-char (+ (org-element-begin prev-elem) + (- pos (org-element-begin elem)))))))))) (defun org-drag-element-forward () "Move forward element at point." @@ -21134,29 +22202,29 @@ Move to the previous element at the same level, when possible." (let* ((pos (point)) (elem (or (org-element-at-point) (user-error "No element at point")))) - (when (= (point-max) (org-element-property :end elem)) + (when (= (point-max) (org-element-end elem)) (user-error "Cannot drag element forward")) - (goto-char (org-element-property :end elem)) + (goto-char (org-element-end elem)) (let ((next-elem (org-element-at-point))) (when (or (org-element-nested-p elem next-elem) - (and (eq (org-element-type next-elem) 'headline) - (not (eq (org-element-type elem) 'headline)))) + (and (org-element-type-p next-elem 'headline) + (not (org-element-type-p elem 'headline)))) (goto-char pos) (user-error "Cannot drag element forward")) ;; Compute new position of point: it's shifted by NEXT-ELEM ;; body's length (without final blanks) and by the length of ;; blanks between ELEM and NEXT-ELEM. (let ((size-next (- (save-excursion - (goto-char (org-element-property :end next-elem)) + (goto-char (org-element-end next-elem)) (skip-chars-backward " \r\t\n") (forward-line) ;; Small correction if buffer doesn't end ;; with a newline character. (if (and (eolp) (not (bolp))) (1+ (point)) (point))) - (org-element-property :begin next-elem))) - (size-blank (- (org-element-property :end elem) + (org-element-begin next-elem))) + (size-blank (- (org-element-end elem) (save-excursion - (goto-char (org-element-property :end elem)) + (goto-char (org-element-end elem)) (skip-chars-backward " \r\t\n") (forward-line) (point))))) @@ -21170,11 +22238,11 @@ Move to the previous element at the same level, when possible." (let ((c (current-column))) (if (< 0 arg) (progn - (beginning-of-line 2) + (forward-line 1) (transpose-lines 1) - (beginning-of-line 0)) + (forward-line -1)) (transpose-lines 1) - (beginning-of-line -1)) + (forward-line -2)) (org-move-to-column c)))) (defun org-drag-line-backward (arg) @@ -21196,37 +22264,38 @@ ones already marked." (set-mark (save-excursion (goto-char (mark)) - (goto-char (org-element-property :end (org-element-at-point))) + (goto-char (org-element-end (org-element-at-point))) (point))) (let ((element (org-element-at-point))) (end-of-line) - (push-mark (min (point-max) (org-element-property :end element)) t t) - (goto-char (org-element-property :begin element)))))) + (push-mark (min (point-max) (org-element-end element)) t t) + (goto-char (org-element-begin element)))))) (defun org-narrow-to-element () - "Narrow buffer to current element." + "Narrow buffer to current element. +Use the command `\\[widen]' to see the whole buffer again." (interactive) (let ((elem (org-element-at-point))) (cond ((eq (car elem) 'headline) (narrow-to-region - (org-element-property :begin elem) - (org-element-property :end elem))) + (org-element-begin elem) + (org-element-end elem))) ((memq (car elem) org-element-greater-elements) (narrow-to-region - (org-element-property :contents-begin elem) - (org-element-property :contents-end elem))) + (org-element-contents-begin elem) + (org-element-contents-end elem))) (t (narrow-to-region - (org-element-property :begin elem) - (org-element-property :end elem)))))) + (org-element-begin elem) + (org-element-end elem)))))) (defun org-transpose-element () "Transpose current and previous elements, keeping blank lines between. Point is moved after both elements." (interactive) (org-skip-whitespace) - (let ((end (org-element-property :end (org-element-at-point)))) + (let ((end (org-element-end (org-element-at-point)))) (org-drag-element-backward) (goto-char end))) @@ -21237,17 +22306,17 @@ modified." (interactive) (unless (eq major-mode 'org-mode) (user-error "Cannot un-indent a buffer not in Org mode")) - (letrec ((parse-tree (org-element-parse-buffer 'greater-element)) + (letrec ((parse-tree (org-element-parse-buffer 'greater-element nil 'defer)) (unindent-tree (lambda (contents) (dolist (element (reverse contents)) - (if (memq (org-element-type element) '(headline section)) + (if (org-element-type-p element '(headline section)) (funcall unindent-tree (org-element-contents element)) (save-excursion (save-restriction (narrow-to-region - (org-element-property :begin element) - (org-element-property :end element)) + (org-element-begin element) + (org-element-end element)) (org-do-remove-indentation)))))))) (funcall unindent-tree (org-element-contents parse-tree)))) diff --git a/elpa/org-9.6.7/org.info b/elpa/org-9.7.17/org.info similarity index 90% rename from elpa/org-9.6.7/org.info rename to elpa/org-9.7.17/org.info index 26024bd1..8f901d05 100644 --- a/elpa/org-9.6.7/org.info +++ b/elpa/org-9.7.17/org.info @@ -1,8 +1,8 @@ -This is org.info, produced by makeinfo version 6.7 from org.texi. +This is org.info, produced by makeinfo version 6.8 from org.texi. -This manual is for Org version 9.6. +This manual is for Org version 9.7. - Copyright © 2004–2023 Free Software Foundation, Inc. + Copyright © 2004–2024 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, @@ -26,9 +26,9 @@ File: org.info, Node: Top, Next: Introduction, Up: (dir) The Org Manual ************** -This manual is for Org version 9.6. +This manual is for Org version 9.7. - Copyright © 2004–2023 Free Software Foundation, Inc. + Copyright © 2004–2024 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, @@ -309,9 +309,9 @@ Exporting * Org Export:: Exporting to Org. * Texinfo Export:: Exporting to Texinfo. * iCalendar Export:: Exporting to iCalendar. -* Other Built-in Back-ends:: Exporting to a man page. +* Other Built-in Backends:: Exporting to a man page. * Advanced Export Configuration:: Fine-tuning the export output. -* Export in Foreign Buffers:: Author tables and lists in Org syntax. +* Export Region:: Author tables and lists in Org syntax. Beamer Export @@ -328,6 +328,7 @@ HTML Export * HTML specific export settings:: Settings for HTML export. * HTML doctypes:: Exporting various (X)HTML flavors. * HTML preamble and postamble:: Inserting preamble and postamble. +* Bare HTML:: Exporting HTML without CSS, Javascript, etc. * Quoting HTML tags:: Using direct HTML in Org files. * Headlines in HTML export:: Formatting headlines. * Links in HTML export:: Inserting and formatting links. @@ -341,7 +342,7 @@ HTML Export LaTeX Export * LaTeX/PDF export commands:: For producing LaTeX and PDF documents. -* LaTeX specific export settings:: Unique to this LaTeX back-end. +* LaTeX specific export settings:: Unique to this LaTeX backend. * LaTeX header and sectioning:: Setting up the export file structure. * Quoting LaTeX code:: Incorporating literal LaTeX code. * Tables in LaTeX export:: Options for exporting tables to LaTeX. @@ -392,10 +393,6 @@ Texinfo Export * Special blocks in Texinfo export:: Special block attributes. * A Texinfo example:: Processing Org to Texinfo. -Export in Foreign Buffers - -* Bare HTML:: Exporting HTML without CSS, Javascript, etc. - Publishing * Configuration:: Defining projects. @@ -427,7 +424,7 @@ Citation handling Bibliography printing -* Bibliography options in the ``biblatex'' and ``csl'' export processors:: +* Bibliography options in the biblatex and csl export processors:: Working with Source Code @@ -466,6 +463,7 @@ Miscellaneous * Protocols:: External access to Emacs and Org. * Org Crypt:: Encrypting Org files. * Org Mobile:: Viewing and capture on a mobile device. +* Drag and Drop & yank-media:: Dropping and pasting files and images Clean View @@ -494,7 +492,7 @@ Hacking * Hooks:: How to reach into Org’s internals. * Add-on Packages:: Available extensions. * Adding Hyperlink Types:: New custom link types. -* Adding Export Back-ends:: How to write new export back-ends. +* Adding Export Backends:: How to write new export backends. * Tables in Arbitrary Syntax:: Orgtbl for LaTeX and other programs. * Dynamic Blocks:: Automatically filled blocks. * Special Agenda Views:: Customized views. @@ -534,6 +532,9 @@ Org Mode is an authoring tool and a TODO lists manager for GNU Emacs. It relies on a lightweight plain-text markup language used in files with the ‘.org’ extension. + Authoring Org files is best supported by Emacs, but you can view, +understand, and change them with any text editor. + As an authoring tool, Org helps you write structured documents and provides exporting facilities. Org files can also be used for literate programming and reproducible research. As a TODO lists manager, Org @@ -606,6 +607,10 @@ installation method. that Org stable versions are meant to be fully compatible with the last three stable versions of Emacs but not with older Emacsen. + Some Org components also depend on third-party packages available +through package archives. Org is only guaranteed to be compatible with +the latest stable versions of these third-party packages. + Using Emacs packaging system ---------------------------- @@ -618,6 +623,14 @@ with ‘M-x list-packages’. See *note Package Menu: (emacs)Package Menu. loaded. Otherwise autoload Org functions will mess up the installation. + To avoid interference with built-in Org mode, you can use command +line: + + emacs -Q -batch -eval "(progn (require 'package) (package-initialize) (package-refresh-contents) (package-upgrade 'org))" + + This approach has the advantage of isolating the upgrade process from +a running Emacs session, ensuring that version conflicts can not arise. + Using Org’s git repository -------------------------- @@ -678,7 +691,8 @@ list. not just in Org buffers. To that effect, you need to bind them to globally available keys, like the ones reserved for users (see *note (elisp)Key Binding Conventions::). Here are suggested bindings, please -modify the keys to your own liking. +modify the keys to your own liking in your *note personal init file: +(emacs)Init File. (global-set-key (kbd "C-c l") #'org-store-link) (global-set-key (kbd "C-c a") #'org-agenda) @@ -712,11 +726,11 @@ File: org.info, Node: Feedback, Next: Conventions, Prev: Activation, Up: Int If you find problems with Org, or if you have questions, remarks, or ideas about it, please send an email to the Org mailing list -. You can subscribe to the list from this web -page (https://lists.gnu.org/mailman/listinfo/emacs-orgmode). If you are -not a member of the mailing list, your mail will be passed to the list -after a moderator has approved it(1). We ask you to read and respect -the GNU Kind Communications Guidelines +. You can subscribe to the list from this +web page (https://lists.gnu.org/mailman/listinfo/emacs-orgmode). If you +are not a member of the mailing list, your mail will be passed to the +list after a moderator has approved it(1). We ask you to read and +respect the GNU Kind Communications Guidelines (https://www.gnu.org/philosophy/kind-communication.html) when sending messages on this mailing list. Please allow up to one month for the response and followup if no response is received on the bug report. @@ -776,6 +790,10 @@ information about: 2. What did you expect to happen? 3. What happened instead? + If you experience degraded performance, you can record a “profile” +and share it on the Org mailing list. See below for the instructions +how to record a useful profile. + Thank you for helping to improve this program. How to create a useful backtrace @@ -808,6 +826,65 @@ occurred. Here is how to produce a useful backtrace: screen. Save this buffer to a file—for example using ‘C-x C-w’—and attach it to your bug report. +How to profile Org performance +------------------------------ + +Sometimes, Org is becoming slow for no apparent reason. Such slowdown +is often caused by interaction between third-party packages and Org +mode. However, identifying the root cause is not always +straightforward. + + Emacs is able to record performance statistics, which can then be +used to find out which functions are taking most of the time to execute. +To record the statistics, one can use so-called profiler. To use the +Emacs profiler, we recommend the following steps: + + 1. Make sure that no profiler is currently active: + + M-x profiler-stop + + 2. Start a new CPU profiler session: + + M-x profiler-start cpu + + 3. Use Emacs as usual, performing the actions that are deemed slow. + + 4. Display and examine the recorded performance statistics: + + M-x profiler-report + + This command will display a summary of the commands and functions + that have been executed between ‘profiler-start’ and + ‘profiler-report’ invocations, with command taking most of the time + displayed on top. + + ‘’ key can be used to fold and unfold lines in the profiler + buffer. The child items revealed upon unfolding are the functions + and commands called by the unfolded parent. + + The root causes are often buried deep inside sub-children items in + the profiler. You can press ‘B’ + (‘profiler-report-render-reversed-calltree’) to quickly reveal the + actual function/command that takes most of the time to run. + + Pressing ‘C’ ‘profiler-report-render-calltree’ will recover the + original view. + + 5. If you need further help, you can share the statistics data. + + Just save the data by issuing + + M-x profiler-report-write-profile + /path/to/profile-file-to-be-saved + + Then, you can attached the saved file to your email to the Org + mailing list, alongside with details about what you did to trigger + the slowdown. + + Note that the saved statistics will only contain the function names + and how long their execution takes. No private data will be + recorded. + ---------- Footnotes ---------- (1) Please consider subscribing to the mailing list in order to @@ -908,7 +985,7 @@ it as a title for your own headings. Some people find the many stars too noisy and would prefer an outline that has whitespace followed by a single star as headline starters. -This can be achieved using a Org Indent minor mode. See *note Clean +This can be achieved using an Org Indent minor mode. See *note Clean View:: for more information. Headlines are not numbered. However, you may want to dynamically @@ -974,7 +1051,7 @@ visibility in the buffer. very beginning of the buffer, but not on a headline, and ‘org-cycle-global-at-bob’ is set to a non-‘nil’ value. -‘C-u C-u ’ (‘org-set-startup-visibility’) +‘C-u C-u ’ (‘org-cycle-set-startup-visibility’) Switch back to the startup visibility of the buffer (see *note Initial visibility::). @@ -1041,7 +1118,7 @@ Properties and Columns::) get their visibility adapted accordingly. Allowed values for this property are ‘folded’, ‘children’, ‘content’, and ‘all’. -‘C-u C-u ’ (‘org-set-startup-visibility’) +‘C-u C-u ’ (‘org-cycle-set-startup-visibility’) Switch back to the startup visibility of the buffer, i.e., whatever is requested by startup options and ‘VISIBILITY’ properties in individual entries. @@ -1059,10 +1136,15 @@ File: org.info, Node: Catching invisible edits, Prev: Initial visibility, Up: ------------------------------ Sometimes you may inadvertently edit an invisible part of the buffer and -be confused on what has been edited and how to undo the mistake. -Setting ‘org-fold-catch-invisible-edits’ to non-‘nil’ helps preventing -this. See the docstring of this option on how Org should catch -invisible edits and process them. +be confused on what has been edited and how to undo the mistake. By +default, Org prevents such edits for a limited set of user commands. +Users can control which commands are affected by customizing +‘org-fold-catch-invisible-edits-commands’. + + The strategy used to decide if a given edit is dangerous is +controlled by ‘org-fold-catch-invisible-edits’. See the docstring of +this option on the available strategies. Set the option to ‘nil’ to +disable catching invisible edits completely.  File: org.info, Node: Motion, Next: Structure Editing, Prev: Visibility Cycling, Up: Document Structure @@ -1188,7 +1270,9 @@ File: org.info, Node: Structure Editing, Next: Sparse Trees, Prev: Motion, U Yank subtree from kill ring. This does modify the level of the subtree to make sure the tree fits in nicely at the yank position. The yank level can also be specified with a numeric prefix - argument, or by yanking after a headline marker like ‘****’. + argument, or by yanking after a headline marker like ‘****’. With + ‘C-u’ prefix, force inserting as a sibling. With ‘C-u C-u’ prefix + argument, force inserting as a child. ‘C-y’ (‘org-yank’) Depending on the variables ‘org-yank-adjusted-subtrees’ and @@ -1356,6 +1440,7 @@ example: 3. Peter Jackson being shot by Legolas - on DVD only He makes a really funny face when it happens. + 8. [@8] But in the end, no individual scenes matter but the film as a whole. Important actors in this film are: - Elijah Wood :: He plays Frodo @@ -2353,6 +2438,16 @@ to read than the equivalent: '(substring $1 (string-to-number $2) (string-to-number $3)) + When the formula itself contains ‘;’ symbol, Org mode may incorrectly +interpret everything past ‘;’ as format specifier: + + '(concat $1 ";") + +You can put an extra tailing ‘;’ to indicate that all the earlier +instances of ‘;’ belong to the formula itself: + + '(concat $1 ";"); +  File: org.info, Node: Durations and time values, Next: Field and range formulas, Prev: Formula syntax for Lisp, Up: The Spreadsheet @@ -2850,13 +2945,17 @@ Plot options ‘ind’ Specify which column of the table to use as the ‘x’ axis. +‘timeind’ + Specify which column of the table to use as the ‘x’ axis as a time + value. + ‘deps’ Specify the columns to graph as a Lisp style list, surrounded by parentheses and separated by spaces for example ‘dep:(3 4)’ to graph the third and fourth columns. Defaults to graphing all other columns aside from the ‘ind’ column. -transpose +‘transpose’ When ‘y’, ‘yes’, or ‘t’ attempt to transpose the table data before plotting. Also recognizes the shorthand option ‘trans’. @@ -2885,19 +2984,19 @@ transpose When plotting ‘3d’ or ‘grid’ types, set this to ‘t’ to graph a flat mapping rather than a ‘3d’ slope. -min +‘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 +‘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 +‘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 @@ -2918,7 +3017,7 @@ ticks ASCII bar plots --------------- -While point is on a column, typing ‘C-c `` a’ or ‘M-x orgtbl-ascii-plot’ +While point is on a column, typing ‘C-c " a’ or ‘M-x orgtbl-ascii-plot’ create a new column containing an ASCII-art bars plot. The plot is implemented through a regular column formula. When the source column changes, the bar plot may be updated by refreshing the table, for @@ -3016,7 +3115,9 @@ displayed text and press ‘’, you remove the—invisible—bracket at that location(2). This makes the link incomplete and the internals are again displayed as plain text. Inserting the missing bracket hides the link internals again. To show the internal structure of all links, use -the menu: Org → Hyperlinks → Literal links. +the menu: Org → Hyperlinks → Literal links, customize +‘org-link-descriptive’, or use ‘literallinks’ *note startup option: +In-buffer Settings. ---------- Footnotes ---------- @@ -3132,10 +3233,6 @@ colon. ‘file’ 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. - As a special case, “file” prefix may be omitted if the file name is complete, e.g., it starts with ‘./’, or ‘/’. @@ -3159,7 +3256,7 @@ colon. Execute an Elisp command upon activation. ‘gnus’, ‘rmail’, ‘mhe’ - Link to messages or folders from a given Emacs’ MUA. + Link to messages or folders from a given Emacs MUA. ‘help’ Display documentation of a symbol in ‘*Help*’ buffer. @@ -3185,11 +3282,15 @@ colon. ‘shell’ Execute a shell command upon activation. + For ‘file:’ and ‘id:’ links, you can additionally specify a line +number, or a text search string, separated by ‘::’. In Org files, you +may link to a headline name, a custom ID, or a code reference instead. + The following table illustrates the link types above, along with their options: Link Type Example ------------------------------------------------------------------------- +---------------------------------------------------------------------------------- http ‘http://staff.science.uva.nl/c.dominik/’ https ‘https://orgmode.org/’ doi ‘doi:10.1000/182’ @@ -3208,6 +3309,7 @@ attachment ‘attachment:projects.org’ ‘attachment:projects.org::some words’ (text search) docview ‘docview:papers/last.pdf::NNN’ id ‘id:B7423F4D-2E8A-471B-8810-C40F074717E9’ + ‘id:B7423F4D-2E8A-471B-8810-C40F074717E9::*task’ (headline search) news ‘news:comp.emacs’ mailto ‘mailto:adent@galaxy.net’ mhe ‘mhe:folder’ (folder link) @@ -3283,8 +3385,9 @@ current buffer: _Org mode buffers_ For Org files, if there is a ‘<>’ at point, the link points - to the target. Otherwise it points to the current headline, which - is also the description. + to the target. If there is a named block (using ‘#+name:’) at + point, the link points to that name. Otherwise it points to the + current headline, which is also the description. If the headline has a ‘CUSTOM_ID’ property, store a link to this custom ID. In addition or alternatively, depending on the value of @@ -3297,6 +3400,25 @@ _Org mode buffers_ ‘org-id-method’. Later, when inserting the link, you need to decide which one to use. + When ‘org-id-link-consider-parent-id’ is ‘t’(2), parent ‘ID’ + properties are considered. This allows linking to specific + targets, named blocks, or headlines (which may not have a globally + unique ‘ID’ themselves) within the context of a parent headline or + file which does. + + For example, given this org file: + + * Parent + :PROPERTIES: + :ID: abc + :END: + ** Child 1 + ** Child 2 + + Storing a link with point at “Child 1” will produce a link + ‘’, which precisely links to the “Child 1” + headline even though it does not have its own ID. + _Email/News clients: VM, Rmail, Wanderlust, MH-E, Gnus_ Pretty much all Emacs mail clients are supported. The link points to the current article, or, in some Gnus buffers, to the group. @@ -3336,11 +3458,11 @@ _Agenda view_ generally, act on links. ‘C-c C-l’ (‘org-insert-link’) - Insert a link(2). This prompts for a link to be inserted into the + Insert a link(3). This prompts for a link to be inserted into the buffer. You can just type a link, using text for an internal link, or one of the link type prefixes mentioned in the examples above. The link is inserted into the buffer, along with a descriptive - text(3). If some text was selected at this time, it becomes the + text(4). If some text was selected at this time, it becomes the default description. _Inserting stored links_ @@ -3353,7 +3475,7 @@ generally, act on links. prefixes like ‘http’ or ‘ftp’, including the prefixes defined through link abbreviations (see *note Link Abbreviations::). If you press ‘’ after inserting only the prefix, Org - offers specific completion support for some link types(4). + offers specific completion support for some link types(5). For example, if you type ‘f i l e ’—alternative access: ‘C-u C-c C-l’, see below—Org offers file name completion, and after ‘b b d b ’ you can complete contact names. @@ -3403,7 +3525,7 @@ generally, act on links. ‘mouse-3’ Like ‘mouse-2’, but force file links to be opened with Emacs, and - internal links to be displayed in another window(5). + internal links to be displayed in another window(6). ‘C-c %’ (‘org-mark-ring-push’) Push the current position onto the Org mark ring, to be able to @@ -3433,21 +3555,24 @@ generally, act on links. ‘org-customize’, by enabling ‘id’ in ‘org-modules’, or by adding ‘(require 'org-id)’ in your Emacs init file. - (2) Note that you do not have to use this command to insert a link. + (2) Also, ‘org-link-context-for-files’ and ‘org-id-link-use-context’ +should be both enabled (which they are, by default). + + (3) Note that you do not have to use this command to insert a link. Links in Org are plain text, and you can type or paste them straight into the buffer. By using this command, the links are automatically enclosed in double brackets, and you will be asked for the optional descriptive text. - (3) After insertion of a stored link, the link will be removed from + (4) After insertion of a stored link, the link will be removed from the list of stored links. To keep it in the list for later use, use a triple ‘C-u’ prefix argument to ‘C-c C-l’, or configure the option ‘org-link-keep-stored-after-insertion’. - (4) This works if a function has been defined in the ‘:complete’ + (5) This works if a function has been defined in the ‘:complete’ property of a link in ‘org-link-parameters’. - (5) See the variable ‘org-link-use-indirect-buffer-for-internals’. + (6) See the variable ‘org-link-use-indirect-buffer-for-internals’.  File: org.info, Node: Using Links Outside Org, Next: Link Abbreviations, Prev: Handling Links, Up: Hyperlinks @@ -3481,7 +3606,7 @@ resolved according to the information in the variable Here is an example: (setq org-link-abbrev-alist - '(("bugzilla" . "http://10.1.2.9/bugzilla/show_bug.cgi?id=") + '(("bugzilla" . "https://10.1.2.9/bugzilla/show_bug.cgi?id=") ("Nu Html Checker" . "https://validator.w3.org/nu/?doc=%h") ("duckduckgo" . "https://duckduckgo.com/?q=%s") ("omap" . "https://nominatim.openstreetmap.org/search?q=%s&polygon=1") @@ -3503,7 +3628,7 @@ argument. With the above setting, you could link to a specific bug with ‘[[bugzilla:129]]’, search the web for ‘OrgMode’ with ‘[[duckduckgo:OrgMode]]’, show the map location of the Free Software -Foundation ‘[[gmap:51 Franklin Street, Boston]]’ or of Carsten office +Foundation ‘[[omap:31 Milk Street, Boston]]’ or of Carsten’s office ‘[[omap:Science Park 904, Amsterdam, The Netherlands]]’ and find out what the Org author is doing besides Emacs hacking with ‘[[ads:Dominik,C]]’. @@ -3540,8 +3665,8 @@ Links::) to a file, it encodes the words in the current line as a search string that can be used to find this line back later when following the link with ‘C-c C-o’. - Note that all search options apply for Attachment links in the same -way that they apply for File links. + Note that all search options apply for Attachment and ID links in the +same way that they apply for File links. Here is the syntax of the different ways to attach a search to a file link, together with explanations for each: @@ -3851,19 +3976,13 @@ selection character after each keyword, in parentheses(1). For example: If you then press ‘C-c C-t’ followed by the selection key, the entry is switched to this state. ‘’ can be used to remove any TODO -keyword from an entry(2). +keyword from an entry. ---------- Footnotes ---------- (1) All characters are allowed except ‘@’, ‘^’ and ‘!’, which have a special meaning here. - (2) Check also the variable ‘org-fast-tag-selection-include-todo’, it -allows you to change the TODO state through the tags interface (see -*note Setting Tags::), in case you like to mingle the two concepts. -Note that this means you need to come up with unique keys across both -sets of keywords. -  File: org.info, Node: Per-file keywords, Next: Faces for TODO keywords, Prev: Fast access to TODO states, Up: TODO Extensions @@ -4146,8 +4265,10 @@ module by customizing the variable ‘org-modules’. 3. The TODO has a scheduled date, usually with a ‘.+’ style repeat interval. A ‘++’ style may be appropriate for habits with time - constraints, e.g., must be done on weekends, or a ‘+’ style for an - unusual habit that can have a backlog, e.g., weekly reports. + constraints, e.g., must be done on specific days of week (‘++1w’), + or a ‘+’ style for an unusual habit that can have a backlog, e.g., + weekly reports. See *note Repeated tasks:: for more details about + repeat intervals. 4. The TODO may also have minimum and maximum ranges specified by using the syntax ‘.+2d/3d’, which says that you want to do the task @@ -4332,7 +4453,7 @@ all children are done, you can use the following setup: (defun org-summary-todo (n-done n-not-done) "Switch entry to DONE when all subentries are done, to TODO otherwise." - (let (org-log-done org-log-states) ; turn off logging + (let (org-log-done org-todo-log-states) ; turn off logging (org-todo (if (= n-not-done 0) "DONE" "TODO")))) (add-hook 'org-after-todo-statistics-hook #'org-summary-todo) @@ -4369,11 +4490,6 @@ them in a shopping list. - [ ] think about what music to play - [X] talk to the neighbors - Checkboxes work hierarchically, so if a checkbox item has children -that are checkboxes, toggling one of the children checkboxes makes the -parent checkbox reflect if none, some, or all of the children are -checked. - The ‘[2/4]’ and ‘[1/3]’ in the first and second line are cookies indicating how many checkboxes present in this entry have been checked off, and the total number of checkboxes present. This can give you an @@ -4394,6 +4510,34 @@ or ‘todo’ to resolve this issue. must be checked off in sequence, and an error is thrown if you try to check off a box while there are unchecked boxes above it. + A checkbox can be in one of the three states: + 1. not checked ‘[ ]’ + 2. partially checked ‘[-]’ + 3. checked ‘[X]’ + + Checkboxes work hierarchically, so if a checkbox item has children +that are checkboxes, toggling one of the children checkboxes makes the +parent checkbox reflect if none, some, or all of the children are +checked. + + If all child checkboxes are not checked, the parent checkbox is also +not checked. + - [ ] call people + - [ ] Peter + - [ ] Sarah + + If some but not all child checkboxes are checked, the parent checkbox +is partially checked. + - [-] call people + - [X] Peter + - [ ] Sarah + + If all child checkboxes are checked, the parent checkbox is also +checked. + - [X] call people + - [X] Peter + - [X] Sarah + The following commands work with checkboxes: ‘C-c C-c’ (‘org-toggle-checkbox’) @@ -4456,7 +4600,7 @@ check off a box while there are unchecked boxes above it. (1) With the exception of description lists. But you can allow it by modifying ‘org-list-automatic-rules’ accordingly. - (2) Set the variable ‘org-hierarchical-checkbox-statistics’ if you + (2) Set the variable ‘org-checkbox-hierarchical-statistics’ if you want such cookies to count all checkboxes below the cookie, not just those belonging to direct children. @@ -4515,12 +4659,6 @@ the entire file. Use a line like this(1) entirely, use the variables ‘org-use-tag-inheritance’ and ‘org-tags-exclude-from-inheritance’. - When a headline matches during a tags search while tag inheritance is -turned on, all the sublevels in the same tree—for a simple match -form—match as well(2). The list of matches may then become very long. -If you only want to see the first tags match in a subtree, configure the -variable ‘org-tags-match-list-sublevels’ (not recommended). - Tag inheritance is relevant when the agenda search tries to match a tag, either in the ‘tags’ or ‘tags-todo’ agenda types. In other agenda types, ‘org-use-tag-inheritance’ has no effect. Still, you may want to @@ -4534,9 +4672,6 @@ this to ‘nil’ can really speed up agenda generation. (1) As with all these in-buffer settings, pressing ‘C-c C-c’ activates any changes in the line. - (2) This is only true if the search does not involve more complex -tests including properties (see *note Property Searches::). -  File: org.info, Node: Setting Tags, Next: Tag Hierarchy, Prev: Tag Inheritance, Up: Tags @@ -4689,6 +4824,10 @@ for the current tag selection process (in effect: start selection with value ‘expert’, the special window is not even shown for single-key tag selection, it comes up only when you press an extra ‘C-c’. + The number of tags displayed in the fast tag selection interface is +limited by ‘org-fast-tag-selection-maximum-tags’ to avoid running out of +keyboard keys. You can customize this variable. + ---------- Footnotes ---------- (1) To extend this default list to all tags used in all agenda files @@ -4809,8 +4948,7 @@ information into special lists. ‘M-x org-agenda M’ (‘org-tags-view’) Create a global list of tag matches from all agenda files, but - check only TODO items and force checking subitems (see the option - ‘org-tags-match-list-sublevels’). + check only TODO items. These commands all prompt for a match string which allows basic Boolean logic like ‘+boss+urgent-project1’, to find entries with tags @@ -4894,10 +5032,10 @@ box like this: :Publisher_ALL: "Deutsche Grammophon" Philips EMI :END: - Properties can be inserted on buffer level. That means they apply -before the first headline and can be inherited by all entries in a file. -Property blocks defined before first headline needs to be located at the -top of the buffer, allowing only comments above. + Properties can be inserted at the buffer level. That means they +apply before the first headline and can be inherited by all entries in a +file. Property blocks defined before the first headline must be at the +top of the buffer with only comments above them. Properties can also be defined using lines like: @@ -4999,10 +5137,18 @@ used as keys in the properties drawer: ‘PRIORITY’ The priority of the entry, a string with a single letter. ‘SCHEDULED’ The scheduling timestamp. ‘TAGS’ The tags defined directly in the headline. -‘TIMESTAMP’ The first keyword-less timestamp in the entry. -‘TIMESTAMP_IA’ The first inactive timestamp in the entry. +‘TIMESTAMP’ The first active keyword-less timestamp in the entry.(1) +‘TIMESTAMP_IA’ The first inactive keyword-less timestamp in the entry. ‘TODO’ The TODO keyword of the entry. + ---------- Footnotes ---------- + + (1) For both ‘TIMESTAMP’ and ‘TIMESTAMP_IA’: the word “first” refers +to the first occurrence in the entry, not the earliest in time; the +prefix ‘CLOCK:’ at the beginning of a clock entry is considered a +keyword in this context; and timestamps inside property drawers are +ignored. +  File: org.info, Node: Property Searches, Next: Property Inheritance, Prev: Special Properties, Up: Properties and Columns @@ -5022,8 +5168,7 @@ Tag Searches::). ‘M-x org-agenda M’ (‘org-tags-view’) Create a global list of tag matches from all agenda files, but - check only TODO items and force checking of subitems (see the - option ‘org-tags-match-list-sublevels’). + check only TODO items. The syntax for the search string is described in *note Matching tags and properties::. @@ -5328,6 +5473,18 @@ Modifying column view on-the-fly ‘S-M-’ (‘org-columns-delete’) Delete the current column. +‘M-’ (‘org-columns-move-left’) + Move the current column left. + +‘M-’ (‘org-columns-move-right’) + Move the current column right. + +‘M-’ (‘org-columns-move-row-up’) + Move the current row up. + +‘M-’ (‘org-columns-move-row-down’) + Move the current row down. +  File: org.info, Node: Capturing column view, Prev: Using column view, Up: Column View @@ -5393,10 +5550,18 @@ this block looks like this: ‘:indent’ When non-‘nil’, indent each ‘ITEM’ field according to its level. +‘:link’ + When non-‘nil’, link the ‘ITEM’ headlines in the table to their + origins. + ‘:format’ Specify a column attribute (see *note Column attributes::) for the dynamic block. +‘:formatter’ + A function to format column view data and insert it into the + buffer. See the option ‘org-columns-dblock-formatter’. + The following commands insert or update the dynamic block: ‘org-columns-insert-dblock’ @@ -5408,7 +5573,7 @@ this block looks like this: “columnview” (see *note Dynamic Blocks::). ‘C-c C-c’ ‘C-c C-x C-u’ (‘org-dblock-update’) - Update dynamic block at point. point needs to be in the ‘#+BEGIN’ + Update dynamic block at point. Point needs to be on the ‘#+BEGIN’ line of the dynamic block. ‘C-u C-c C-x C-u’ (‘org-update-all-dblocks’) @@ -5446,6 +5611,11 @@ confusing because timestamp is often used as indicating when something was created or last changed. However, in Org mode this term is used in a much wider sense. + Timestamps can be used to plan appointments, schedule tasks, set +deadlines, track time, and more. The following sections describe the +timestamp format and tooling that Org mode provides for common use cases +dealing with time and time intervals. + * Menu: * Timestamps:: Assigning a time to a tree entry. @@ -5461,23 +5631,27 @@ File: org.info, Node: Timestamps, Next: Creating Timestamps, Up: Dates and Ti 8.1 Timestamps ============== -A timestamp is a specification of a date (possibly with a time or a -range of times) in a special format, either ‘<2003-09-16 Tue>’ or -‘<2003-09-16 Tue 09:39>’ or ‘<2003-09-16 Tue 12:00-12:30>’(1). A -timestamp can appear anywhere in the headline or body of an Org tree -entry. Its presence causes entries to be shown on specific dates in the -agenda (see *note Weekly/daily agenda::). We distinguish: +A timestamp is a specification of a date—possibly with a time or time +range—in a special format, either ‘<2003-09-16 Tue>’ or ‘<2003-09-16 Tue +09:39>’ or ‘<2003-09-16 Tue 12:00-12:30>’(1). A timestamp can appear +anywhere in the headline or body of an Org tree entry. Its presence +causes entries to be shown on specific dates in the agenda (see *note +Weekly/daily agenda::). We distinguish: Plain timestamp; Event; Appointment A simple timestamp just assigns a date/time to an item. This is just like writing down an appointment or event in a paper agenda. In the agenda display, the headline of an entry associated with a - plain timestamp is shown exactly on that date. + plain timestamp is shown exactly on that date. There can be + multiple timestamps in an item. * Meet Peter at the movies <2006-11-01 Wed 19:15> * Discussion on climate change - <2006-11-02 Thu 20:00-22:00> + <2006-11-02 Thu 10:00-12:00> + * My days off + <2006-11-03 Fri> + <2006-11-06 Mon> Timestamp with repeater interval A timestamp may contain a _repeater interval_, indicating that it @@ -5497,15 +5671,26 @@ Diary-style expression entries with optional time: * 22:00-23:00 The nerd meeting on every 2nd Thursday of the month - <%%(diary-float t 4 2)> + <%%(diary-float t 4 2) 22:00-23:00> + +Time range + + Time range is a timestamp having two time units connected by ‘-’ + + * Discussion on climate change + <2006-11-02 Thu 10:00-12:00> Time/Date range - Two timestamps connected by ‘--’ denote a range. The headline is - shown on the first and last day of the range, and on any dates that - are displayed and fall in the range. Here is an example: + Two timestamps connected by ‘--’ denote a range. In the agenda, + the headline is shown on the first and last day of the range, and + on any dates that are displayed and fall in the range. The first + example specifies just the dates of the range while the second + example specifies a time range for each date. ** Meeting in Amsterdam <2004-08-23 Mon>--<2004-08-26 Thu> + ** This weeks committee meetings + <2004-08-23 Mon 10:00-11:00>--<2004-08-26 Thu 10:00-11:00> Inactive timestamp Just like a plain timestamp, but with square brackets instead of @@ -5530,8 +5715,8 @@ specify a date December 1, 2005, the call might look like ‘(diary-date 12 1 2005)’ or ‘(diary-date 1 12 2005)’ or ‘(diary-date 2005 12 1)’, depending on the settings. This has been the source of much confusion. Org mode users can resort to special versions of these functions, namely -‘org-date’, ‘org-anniversary’, ‘org-cyclic, and ~org-block’. These work -just like the corresponding ‘diary-’ functions, but with stable ISO +‘org-date’, ‘org-anniversary’, ‘org-cyclic’, and ‘org-block’. These +work just like the corresponding ‘diary-’ functions, but with stable ISO order of arguments (year, month, day) wherever applicable, independent of the value of ‘calendar-date-style’. @@ -5545,7 +5730,7 @@ For Org mode to recognize timestamps, they need to be in the specific format. All commands listed below produce timestamps in the correct format. -‘C-c .’ (‘org-time-stamp’) +‘C-c .’ (‘org-timestamp’) Prompt for a date and insert a corresponding timestamp. When point is at an existing timestamp in the buffer, the command is used to modify this timestamp instead of inserting a new one. When this @@ -5554,12 +5739,12 @@ format. When called with a prefix argument, use the alternative format which contains date and time. The default time can be rounded to multiples of 5 minutes. See the option - ‘org-time-stamp-rounding-minutes’. + ‘org-timestamp-rounding-minutes’. With two prefix arguments, insert an active timestamp with the current time without prompting. -‘C-c !’ (‘org-time-stamp-inactive’) +‘C-c !’ (‘org-timestamp-inactive’) Like ‘C-c .’, but insert an inactive timestamp that does not cause an agenda entry. @@ -5737,9 +5922,9 @@ Org mode uses the standard ISO notation for dates and times as it is defined in ISO 8601. If you cannot get used to this and require another representation of date and time to keep you happy, you can get it by customizing the variables ‘org-display-custom-times’ and -‘org-time-stamp-custom-formats’. +‘org-timestamp-custom-formats’. -‘C-c C-x C-t’ (‘org-toggle-time-stamp-overlays’) +‘C-c C-x C-t’ (‘org-toggle-timestamp-overlays’) Toggle the display of custom formats for dates and times. Org mode needs the default format for scanning, so the custom @@ -5942,6 +6127,9 @@ actually switch the date like this: ** TODO Pay the rent DEADLINE: <2005-11-01 Tue +1m> + When task contains multiple timestamps with repeater interval, all +these timestamps are shifted. + To mark a task with a repeater as DONE, use ‘C-- 1 C-c C-t’, i.e., ‘org-todo’ with a numeric prefix argument of ‘-1’. @@ -5988,12 +6176,11 @@ repeaters ‘++’ and ‘.+’. For example: You may have both scheduling and deadline information for a specific task. If the repeater is set for the scheduling information only, you probably want the repeater to be ignored after the deadline. If so, set -the variable ‘org-agenda-skip-scheduled-if-deadline-is-shown’ to -‘repeated-after-deadline’. However, any scheduling information without -a repeater is no longer relevant once the task is done, and thus, -removed upon repeating the task. If you want both scheduling and -deadline information to repeat after the same interval, set the same -repeater for both timestamps. +the variable ‘org-agenda-skip-scheduled-repeats-after-deadline’ to ‘t’. +However, any scheduling information without a repeater is no longer +relevant once the task is done, and thus, removed upon repeating the +task. If you want both scheduling and deadline information to repeat +after the same interval, set the same repeater for both timestamps. An alternative to using a repeater is to create a number of copies of a task subtree, with dates shifted in each copy. The command ‘C-c C-x @@ -6121,6 +6308,9 @@ File: org.info, Node: Clocking commands, Next: The clock table, Up: Clocking clocked-out timestamp by five minutes, then the clocked-in timestamp of the next clock is increased by five minutes. + Only ‘CLOCK’ logs created during current Emacs session are + considered when adjusting next/previous timestamp. + ‘C-c C-t’ (‘org-todo’) Changing the TODO state of an item to DONE automatically stops the clock if it is running in this same item. @@ -6231,16 +6421,16 @@ selected: absolutely, or relative to the current time and may be any of these formats: - ‘2007-12-31’ New year eve 2007 - ‘2007-12’ December 2007 - ‘2007-W50’ ISO-week 50 in 2007 - ‘2007-Q2’ 2nd quarter in 2007 - ‘2007’ the year 2007 - ‘today’, ‘yesterday’, ‘today-N’ a relative day - ‘thisweek’, ‘lastweek’, ‘thisweek-N’ a relative week - ‘thismonth’, ‘lastmonth’, ‘thismonth-N’ a relative month - ‘thisyear’, ‘lastyear’, ‘thisyear-N’ a relative year - ‘untilnow’(1) all clocked time ever + ‘2007-12-31’ New year eve 2007 + ‘2007-12’ December 2007 + ‘2007-W50’ ISO-week 50 in 2007 + ‘2007-Q2’ 2nd quarter in 2007 + ‘2007’ the year 2007 + ‘today’, ‘yesterday’, ‘today-N’ a relative day + ‘thisweek’, ‘lastweek’, ‘thisweek-N’ a relative week + ‘thismonth’, ‘lastmonth’, ‘thismonth-N’ a relative month + ‘thisyear’, ‘lastyear’, ‘thisyear-N’ a relative year + ‘untilnow’(1) all clocked time ever When this option is not set, Org falls back to the value in ‘org-clock-display-default-range’, which defaults to the current @@ -6493,9 +6683,9 @@ on or off. ---------- Footnotes ---------- (1) 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 ‘org-contrib/’ repository, or -install the xprintidle package and set it to the variable +idleness, not just Emacs’s 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. @@ -6925,7 +7115,7 @@ with prefix commands: Visit the last stored capture item in its buffer. You can also jump to the bookmark ‘org-capture-last-stored’, which is -automatically created unless you set ‘org-capture-bookmark’ to ‘nil’. +automatically created unless you customize ‘org-bookmark-names-plist’. To insert the capture at point in an Org buffer, call ‘org-capture’ with a ‘C-0’ prefix argument. @@ -7072,6 +7262,9 @@ target ‘(clock)’ File to the entry that is currently being clocked. + ‘(here)’ + The position of ‘point’. + ‘(function function-finding-location)’ Most general way: write your own function which both visits the file and moves point to the right location. @@ -7168,6 +7361,7 @@ properties ‘:hook’ A nullary function or list of nullary functions run before ‘org-capture-mode-hook’ when the template is selected. + ‘:prepare-finalize’ A nullary function or list of nullary functions run before ‘org-capture-prepare-finalize-hook’ when the template is @@ -7194,13 +7388,12 @@ properties. Please rewrite your date/week-tree targets using (2) A date tree is an outline structure with years on the highest level, months or ISO weeks as sublevels and then dates on the lowest level. - * 2022 ** 2022-10 October *** 2022-10-07 Friday *** 2022-10-08 Saturday - - Tags are allowed in the tree structure. + TODO state, priority, tags, statistics cookies, and COMMENT keywords +are allowed in the tree structure. (3) When the file name is not absolute, Org assumes it is relative to ‘org-directory’. @@ -7298,6 +7491,11 @@ of content. The templates are expanded in the order given here: Prompt the user for a value for property PROP. You may specify a default value with ‘%^{PROP|default}’. +‘%^{PROMPT}X’, X is one of g,G,t,T,u,U,C,L + Prompt the user as in ‘%^X’, but use the custom prompt string. You + may specify a default value and completions with + ‘%^{PROMPT|default|completion1|completion2|completion3...}X’. + ‘%^{PROMPT}’ Prompt the user for a string and replace this sequence with it. You may specify a default value and a completion table with @@ -7855,7 +8053,7 @@ commands: ‘< <’ If there is an active region, restrict the following agenda command - to the region. Otherwise, restrict it to the current subtree(2). + to the region. Otherwise, restrict it to the current subtree. After pressing ‘< <’, you still need to press the character selecting the command. @@ -7881,9 +8079,6 @@ a number of special tags matches. See *note Custom Agenda Views::. (1) For backward compatibility, you can also press ‘1’ to restrict to the current buffer. - (2) For backward compatibility, you can also press ‘0’ to restrict to -the current region/subtree. -  File: org.info, Node: Built-in Agenda Views, Next: Presentation and Sorting, Prev: Agenda Dispatcher, Up: Agenda Views @@ -8124,10 +8319,8 @@ creating sparse trees with ‘C-c / m’. Dispatcher::). ‘M-x org-agenda M’ (‘org-tags-view’) - Like ‘m’, but only select headlines that are also TODO items and - force checking subitems (see the variable - ‘org-tags-match-list-sublevels’). To exclude scheduled/deadline - items, see the variable + Like ‘m’, but only select headlines that are also TODO items. To + exclude scheduled/deadline items, see the variable ‘org-agenda-tags-todo-honor-ignore-options’. Matching specific TODO keywords together with a tags match is also possible, see *note Tag Searches::. @@ -8191,14 +8384,16 @@ number of stars, but ‘LEVEL=2’ corresponds to 3 stars etc. When matching properties, a number of different operators can be used to test the value of a property. Here is a complex example: - +work-boss+PRIORITY="A"+Coffee="unlimited"+Effort<2 + +work-boss+PRIORITY="A"+Coffee="unlimited"+Effort<*2 +With={Sarah\|Denny}+SCHEDULED>="<2008-10-11>" The type of comparison depends on how the comparison value is written: • If the comparison value is a plain number, a numerical comparison is done, and the allowed operators are ‘<’, ‘=’, ‘>’, ‘<=’, ‘>=’, - and ‘<>’. + and ‘<>’. As a synonym for the equality operator ‘=’, there is + also ‘==’; ‘!=’ and ‘/=’ are synonyms of the inequality operator + ‘<>’. • If the comparison value is enclosed in double-quotes, a string comparison is done, and the same operators are allowed. @@ -8217,6 +8412,13 @@ The type of comparison depends on how the comparison value is written: is performed, with ‘=’ meaning that the regexp matches the property value, and ‘<>’ meaning that it does not match. + • All operators may be optionally followed by an asterisk ‘*’, like + in ‘<*’, ‘!=*’, etc. Such _starred operators_ work like their + regular, unstarred counterparts except that they match only + headlines where the tested property is actually present. This is + most useful for search terms that logically exclude results, like + the inequality operator. + 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 @@ -8224,6 +8426,25 @@ smaller than 2, a ‘With’ property that is matched by the regular expression ‘Sarah\|Denny’, and that are scheduled on or after October 11, 2008. + Note that the test on the ‘EFFORT’ property uses operator ‘<*’, so +that the search result will include only entries that actually have an +‘EFFORT’ property defined and with numerical value smaller than 2. With +the regular ‘<’ operator, the search would handle entries without an +‘EFFORT’ property as having a zero effort and would include them in the +result as well. + + You can use all characters valid in property names when matching +properties. However, you have to quote some characters in property +names with backslashes when using them in search strings, namely all +characters different from alphanumerics and underscores(1). For +example, to search for all entries having a property ‘boss-prio’, +‘boss:prio’, or ‘boss\prio’, respectively, with value ‘C’, use search +strings + + boss\-prio="C" + boss\:prio="C" + boss\\prio="C" + You can configure Org mode to use property inheritance during a search, but beware that this can slow down searches considerably. See *note Property Inheritance::, for details. @@ -8253,6 +8474,11 @@ Examples: Select ‘work’-tagged TODO lines that are either ‘WAITING’ or ‘NEXT’. + ---------- Footnotes ---------- + + (1) If you quote alphanumeric characters or underscores with a +backslash, that backslash is ignored. +  File: org.info, Node: Search view, Next: Stuck projects, Prev: Matching tags and properties, Up: Built-in Agenda Views @@ -8447,15 +8673,15 @@ done depends on the type of view. beginning of the list, as a _schedule_ for the day. After that, items remain grouped in categories, in the sequence given by ‘org-agenda-files’. Within each category, items are sorted by - priority (see *note Priorities::), which is composed of the base - priority (2000 for priority ‘A’, 1000 for ‘B’, and 0 for ‘C’), plus - additional increments for overdue scheduled or deadline items. + urgency, which is composed of the base priority (see *note + Priorities::; 2000 for priority ‘A’, 1000 for ‘B’, and 0 for ‘C’), + plus additional increments for overdue scheduled or deadline items. • For the TODO list, items remain in the order of categories, but - within each category, sorting takes place according to priority - (see *note Priorities::). The priority used for sorting derives - from the priority cookie, with additions depending on how close an - item is to its due or scheduled date. + within each category, sorting takes place according to urgency. + The urgency used for sorting derives from the priority cookie, with + additions depending on how close an item is to its due or scheduled + date. • For tags matches, items are not sorted at all, but just appear in the sequence in which they are found in the agenda files. @@ -8471,7 +8697,7 @@ File: org.info, Node: Filtering/limiting agenda items, Prev: Sorting of agenda -------------------------------------- Agenda built-in or custom commands are statically defined. Agenda -filters and limits allow to flexibly narrow down the list of agenda +filters and limits allow flexibly narrowing down the list of agenda entries. _Filters_ only change the visibility of items, are very fast and are @@ -8790,7 +9016,10 @@ Change display ‘v a’ (‘org-agenda-archives-mode’) Toggle Archives mode. In Archives mode, trees that are archived (see *note Internal archiving::) are also scanned when producing - the agenda. To exit archives mode, press ‘v a’ again. + the agenda. To exit archives mode, press ‘v a’ again. The initial + setting for this mode in new agenda buffers can set with the + variable ‘org-agenda-start-with-archives-mode’, which can be set + with the same values as ‘org-agenda-archives-mode’. ‘v A’ Toggle Archives mode. Include all archive files as well. @@ -9257,7 +9486,7 @@ as they operate on the current buffer only. cons cell with the prefix and the description. (2) _Planned_ means here that these entries have some planning -information attached to them, like a time-stamp, a scheduled or a +information attached to them, like a timestamp, a scheduled or a deadline string. See ‘org-agenda-entry-types’ on how to set what planning information is taken into account. @@ -9628,11 +9857,21 @@ File: org.info, Node: Emphasis and Monospace, Next: Subscripts and Superscript You can make words ‘*bold*’, ‘/italic/’, ‘_underlined_’, ‘=verbatim=’ and ‘~code~’, and, if you must, ‘+strike-through+’. Text in the code and verbatim string is not processed for Org specific syntax; it is -exported verbatim. +exported verbatim. Org provides a single command as entry point for +inserting the marker character. + +‘C-c C-x C-f’ (‘org-emphasize’) + Prompt for a marker character and insert or change an emphasis. If + there is an active region, change that region to a new emphasis. + If there is no region, just insert the marker characters and + position the cursor between them. To turn off fontification for marked up text, you can set -‘org-fontify-emphasized-text’ to ‘nil’. To narrow down the list of -available markup syntax, you can customize ‘org-emphasis-alist’. +‘org-fontify-emphasized-text’ to ‘nil’. To narrow down the list of the +fontified markup syntax, you can customize ‘org-emphasis-alist’(1). + + To hide the emphasis markup characters in your buffers, set +‘org-hide-emphasis-markers’ to ‘t’. Sometimes, when marked text also contains the marker character itself, the result may be unsettling. For example, @@ -9644,6 +9883,11 @@ itself, the result may be unsettling. For example, You can use zero width space to help Org sorting out the ambiguity. See *note Escape Character:: for more details. + ---------- Footnotes ---------- + + (1) The markup will still be recognized. Just not highlighted +visually in Emacs. +  File: org.info, Node: Subscripts and Superscripts, Next: Special Symbols, Prev: Emphasis and Monospace, Up: Markup for Rich Contents @@ -9659,14 +9903,16 @@ multi-character sub- and superscripts with curly braces. For example If you write a text where the underscore is often used in a different context, Org’s convention to always interpret these as subscripts can -get in your way. Configure the variable ‘org-use-sub-superscripts’ to -change this convention. For example, when setting this variable to -‘{}’, ‘a_b’ is not interpreted as a subscript, but ‘a_{b}’ is. +get in your way. Configure the variable ‘org-use-sub-superscripts’ +and/or ‘org-export-with-sub-superscripts’ to change this convention. +For example, when setting these variables to ‘{}’, ‘a_b’ is not +displayed/exported(1) as a subscript, but ‘a_{b}’ is. - You can set ‘org-use-sub-superscripts’ in a file using the export -option ‘^:’ (see *note Export Settings::). For example, ‘#+OPTIONS: -^:{}’ sets ‘org-use-sub-superscripts’ to ‘{}’ and limits super- and -subscripts to the curly bracket notation. + You can set both ‘org-use-sub-superscripts’ +‘org-export-with-sub-superscripts’ in a file using the export option +‘^:’ (see *note Export Settings::). For example, ‘#+OPTIONS: ^:{}’ sets +the two options to ‘{}’ and limits super- and subscripts to the curly +bracket notation. You can also toggle the visual display of super- and subscripts: @@ -9678,6 +9924,11 @@ subscripts to the curly bracket notation. super- and subscripts _visually_ interpreted as specified by the option ‘org-use-sub-superscripts’. + ---------- Footnotes ---------- + + (1) The underlying markup still remains a sub/superscript. Only the +visual display and export behavior changes. +  File: org.info, Node: Special Symbols, Next: Embedded LaTeX, Prev: Subscripts and Superscripts, Up: Markup for Rich Contents @@ -9701,7 +9952,7 @@ possible to provide your own special symbols in the variable ‘org-entities-user’. During export, these symbols are transformed into the native format -of the exporter back-end. Strings like ‘\alpha’ are exported as +of the exporter backend. Strings like ‘\alpha’ are exported as ‘α’ in the HTML output, and as ‘\(\alpha\)’ in the LaTeX output. Similarly, ‘\nbsp’ becomes ‘ â€™ in HTML and ‘~’ in LaTeX. @@ -9740,7 +9991,7 @@ symbols and the occasional formula. LaTeX(1) is widely used to typeset scientific documents. Org mode supports embedding LaTeX code into its files, because many academics are used to writing and reading LaTeX source code, and because it can be readily processed to produce pretty -output for a number of export back-ends. +output for a number of export backends. * Menu: @@ -9761,8 +10012,8 @@ File: org.info, Node: LaTeX fragments, Next: Previewing LaTeX fragments, Up: ---------------------- 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 +process these for several export backends. When exporting to LaTeX, the +code is left as it is. When exporting to HTML, Org can use either MathJax (https://www.mathjax.org) (see *note Math formatting in HTML export::) or transcode the math into images (see *note Previewing LaTeX fragments::). @@ -9774,27 +10025,33 @@ following snippets are identified as LaTeX source code: ‘\begin’ statement appears on a new line, preceded by only whitespace. - • Text within the usual LaTeX math delimiters. To avoid conflicts - with currency specifications, single ‘$’ characters are only - recognized as math delimiters if the enclosed text contains at most - two line breaks, is directly attached to the ‘$’ characters with no - whitespace in between, and if the closing ‘$’ is followed by - whitespace, punctuation or a dash. For the other delimiters, there - is no such restriction, so when in doubt, use ‘\(...\)’ as inline - math delimiters. + • Text within the usual LaTeX math delimiters. Prefer ‘\(...\)’ for + inline fragments. The ‘$...$’ alternative has some restrictions + and may be a source of confusion. To avoid conflicts with currency + specifications, single ‘$’ characters are only recognized as math + delimiters if the enclosed text contains at most two line breaks, + is directly attached to the ‘$’ characters with no whitespace in + between, and if the closing ‘$’ is followed by whitespace or + punctuation (but not a dash). + + Sometimes, it may necessary to have a literal dollar symbol even + when it is recognized as LaTeX math delimiter. Org provides + ‘\dollar’ and ‘\USD’ entities (see *note Special Symbols::) that + are rendered as ‘$’ for such scenarios. Also, see *note Escape + Character::. For example: \begin{equation} % arbitrary environments, - x=\sqrt{b} % even tables, figures - \end{equation} % etc + x=\sqrt{b} % even tables, figures, etc + \end{equation} If $a^2=b$ and \( b=2 \), then the solution must be either $$ a=+\sqrt{2} $$ or \[ a=-\sqrt{2} \]. LaTeX processing can be configured with the variable ‘org-export-with-latex’. The default setting is ‘t’ which means MathJax -for HTML, and no processing for ASCII and LaTeX back-ends. You can also +for HTML, and no processing for ASCII and LaTeX backends. You can also set this variable on a per-file basis using one of these lines: ‘#+OPTIONS: tex:t’ Do the right thing automatically (MathJax) @@ -9962,11 +10219,11 @@ Structure Templates:: for shortcuts to easily insert code blocks. (defun org-xor (a b) "Exclusive or." (if a (not b) b)) - #+END_SRC + #+END_SRC Both in ‘example’ and in ‘src’ snippets, you can add a ‘-n’ switch to -the end of the ‘#+BEGIN’ line, to get the lines of the example numbered. -The ‘-n’ takes an optional numeric argument specifying the starting line +the ‘#+BEGIN’ line(3), to get the lines of the example numbered. The +‘-n’ takes an optional numeric argument specifying the starting line number of the block. If you use a ‘+n’ switch, the numbering from the previous numbered snippet is continued in the current one. The ‘+n’ switch can also take a numeric argument. This adds the value of the @@ -9985,12 +10242,12 @@ starting line number. In literal examples, Org interprets strings like ‘(ref:name)’ as labels, and use them as targets for special hyperlinks like -‘[[(name)]]’—i.e., the reference name enclosed in single parenthesis. +‘[[(name)]]’—i.e., the reference name enclosed in single parentheses. In HTML, hovering the mouse over such a link remote-highlights the -corresponding code line, which is kind of cool. +corresponding code line(4), which is kind of cool. You can also add a ‘-r’ switch which _removes_ the labels from the -source code(3). With the ‘-n’ switch, links to these references are +source code(5). With the ‘-n’ switch, links to these references are labeled by the line numbers from the code listing. Otherwise links use the labels with no parentheses. Here is an example: @@ -10027,7 +10284,7 @@ a shortcut is provided (see *note Structure Templates::). need to exit by pressing ‘C-c '’ again. The edited version then replaces the old version in the Org buffer. Fixed-width regions—where each line starts with a colon followed by a space—are - edited using Artist mode(4) to allow creating ASCII drawings + edited using Artist mode(6) to allow creating ASCII drawings easily. Using this command in an empty line creates a new fixed-width region. @@ -10052,11 +10309,20 @@ Refer to ‘org-latex-src-block-backend’ for details. interactively or on export. See *note Working with Source Code:: for more information on evaluating code blocks. - (3) Adding ‘-k’ to ‘-n -r’ _keeps_ the labels in the source code + (3) In the ‘src’ snippets, switches must be placed right after the +language name and before the *note header arguments: Structure of Code +Blocks. + + (4) This requires some Javascript which is _not_ automatically +included in the HTML output: you have to customize the variable +‘org-html-head-include-scripts’ to ‘t’ to have it included (it is ‘nil’ +by default). + + (5) Adding ‘-k’ to ‘-n -r’ _keeps_ the labels in the source code while using line numbers for the links, which might be useful to explain those in an Org mode example code. - (4) You may select a different mode with the variable + (6) You may select a different mode with the variable ‘org-edit-fixed-width-region-mode’.  @@ -10071,7 +10337,7 @@ part, for example ./img/cat.jpg If you wish to define a caption for the image (see *note Captions::) -and maybe a label for internal cross references (see *note Internal +and maybe a label for internal cross-references (see *note Internal Links::), make sure that the link is on a line by itself and precede it with ‘CAPTION’ and ‘NAME’ keywords as follows: @@ -10090,19 +10356,60 @@ command: ‘org-startup-with-inline-images’(2). By default, Org mode displays inline images according to their actual -width. You can customize the displayed image width using +width, but no wider than ‘fill-column’ characters. + + You can customize the displayed image width using ‘org-image-actual-width’ variable (globally) or ‘ORG-IMAGE-ACTUAL-WIDTH’ property (subtree-level)(3). Their value can be the following: - • (default) Non-nil, use the actual width of images when inlining - them. + • (default) Non-‘nil’, use the actual width of images when inlining + them. If the actual width is too wide, limit it according to + ‘org-image-max-width’. • When set to a number, use imagemagick (when available) to set the image’s width to this value. • When set to a number in a list, try to get the width from any ‘#+ATTR.*’ keyword if it matches a width specification like: #+ATTR_HTML: :width 300px and fall back on that number if none is found. - • When set to nil, try to get the width from an ‘#+ATTR.*’ keyword - and fall back on the original width if none is found. + • When set to ‘nil’, try to get the width from an ‘#+ATTR.*’ keyword + and fall back on the original width or ‘org-image-max-width’ if + none is found. + + ‘org-image-max-width’ limits the maximum displayed image width, but +only when the image width is not set explicitly. Possible maximum width +can be set to: + • (default) ‘fill-column’, limit width to ‘fill-column’ number of + characters. + • ‘window’, limit width to current window width. + • integer number, limit width to that specified number of pixels. + • ‘nil’, do not limit the width. + + Org mode can left-align, center or right-align the display of inline +images. This setting is controlled (globally) by ‘org-image-align’. +Only standalone images are affected, corresponding to links with no +surrounding text in their paragraph except for whitespace. Its value +can be the following: + • (default) The symbol ‘left’, which inserts the image where the link + appears in the buffer. + • The symbol ‘center’, which will preview links centered in the Emacs + window. + • The symbol ‘right’, which will preview links right-aligned in the + Emacs window. + + Inline image alignment can be specified for each link using the +‘#+ATTR.*’ keyword if it matches an alignment specification like: + #+ATTR_HTML: :align center + Org will use the alignment specification from any ‘#+ATTR.*’ keyword, +such as ‘#+ATTR_HTML’ or ‘#+ATTR_LATEX’, but ‘#+ATTR_ORG’ (if present) +will override the others. For instance, this link + #+ATTR_HTML: :align right + #+ATTR_ORG: :align center + [[/path/to/image/file.png]] + will be displayed centered in Emacs but exported right-aligned to +HTML. + + When ‘#+ATTR_ORG’ is not set, inline image alignment is also read +from the ‘:center’ attribute supported by some export backends (like +HTML, LaTeX and Beamer.) Inline images can also be displayed when cycling the folding state. When custom option ‘org-cycle-inline-images-display’ is set, the visible @@ -10138,7 +10445,7 @@ You can assign a caption to a specific part of a document by inserting a Even though images and tables are prominent examples of captioned structures, the same caption mechanism can apply to many others—e.g., -LaTeX equations, source code blocks. Depending on the export back-end, +LaTeX equations, source code blocks. Depending on the export backend, those may or may not be handled.  @@ -10164,7 +10471,7 @@ start with ‘fn:’. For example: The Org website[fn:1] now looks a lot better than it used to. ... - [fn:55] The link is: https://orgmode.org + [fn:50] The link is: https://orgmode.org Org mode extends the number-based syntax to _named_ footnotes and optional inline definition. Here are the valid references: @@ -10246,8 +10553,8 @@ structure (see *note Document Structure::) and markup (see *note Markup for Rich Contents::) as possible. The libraries responsible for translating Org files to other formats -are called _back-ends_. Org ships with support for the following -back-ends: +are called _backends_. Org ships with support for the following +backends: • _ascii_ (ASCII format) • _beamer_ (LaTeX Beamer format) @@ -10263,14 +10570,14 @@ back-ends: 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 NAME is a format. For example, -‘ox-koma-letter’ for _koma-letter_ back-end. More libraries can be -found in the ‘org-contrib’ repository (see *note Installation::). +‘ox-koma-letter’ for _koma-letter_ backend. More libraries can be found +in the ‘org-contrib’ repository (see *note Installation::). - Org only loads back-ends for the following formats by default: ASCII, -HTML, iCalendar, LaTeX, and ODT. Additional back-ends can be loaded in + Org only loads backends for the following formats by default: ASCII, +HTML, iCalendar, LaTeX, and ODT. Additional backends can be loaded in either of two ways: by configuring the ‘org-export-backends’ variable, or by requiring libraries in the Emacs init file. For example, to load -the Markdown back-end, add this to your Emacs config: +the Markdown backend, add this to your Emacs config: (require 'ox-md) @@ -10291,9 +10598,9 @@ the Markdown back-end, add this to your Emacs config: * Org Export:: Exporting to Org. * Texinfo Export:: Exporting to Texinfo. * iCalendar Export:: Exporting to iCalendar. -* Other Built-in Back-ends:: Exporting to a man page. +* Other Built-in Backends:: Exporting to a man page. * Advanced Export Configuration:: Fine-tuning the export output. -* Export in Foreign Buffers:: Author tables and lists in Org syntax. +* Export Region:: Author tables and lists in Org syntax.  File: org.info, Node: The Export Dispatcher, Next: Export Settings, Up: Exporting @@ -10343,9 +10650,24 @@ further alter what is exported, and how. ‘C-b’ Toggle body-only export. Useful for excluding headers and footers - in the export. Affects only those back-end formats that have + in the export. Affects only those backend formats that have sections like ‘...’ in HTML. + To make body-only export the default, customize the variable + ‘org-export-body-only’. + +‘C-f’ + + Toggle force-publishing export. Publish functions normally only + publish changed files (see [BROKEN LINK: **Triggering + Publication]). Forced publishing causes files to be published even + if their timestamps do not indicate the file has been changed. + + To make forced publishing the default, customize the variable + ‘org-export-force-publishing’. (This is similar to + ‘org-publish-use-timestamps-flag’, but only affects the export + dispatcher.) + ‘C-s’ Toggle subtree export. When turned on, Org exports only the @@ -10364,6 +10686,9 @@ further alter what is exported, and how. certain parts of an Org document by adjusting the visibility of particular headings. See also *note Sparse Trees::. + To make visible-only export the default, customize the variable + ‘org-export-visible-only’. +  File: org.info, Node: Export Settings, Next: Table of Contents, Prev: The Export Dispatcher, Up: Exporting @@ -10379,14 +10704,14 @@ specific level override options set at a more general level. In-buffer settings may appear anywhere in the file, either directly or indirectly through a file included using ‘#+SETUPFILE: filename or -URL’ syntax. Option keyword sets tailored to a particular back-end can +URL’ syntax. Option keyword sets tailored to a particular backend can be inserted from the export dispatcher (see *note The Export Dispatcher::) using the ‘Insert template’ command by pressing ‘#’. To insert keywords individually, a good way to make sure the keyword is correct is to type ‘#+’ and then to use ‘M-’(1) for completion. - The export keywords available for every back-end, and their -equivalent global variables, include: + The export keywords available for every backend, and their equivalent +global variables, include: ‘AUTHOR’ The document author (‘user-full-name’). @@ -10396,7 +10721,7 @@ equivalent global variables, include: (‘org-export-creator-string’). ‘DATE’ - A date or a time-stamp(2). + A date or a timestamp(2). ‘EMAIL’ The email address (‘user-mail-address’). @@ -10408,20 +10733,35 @@ equivalent global variables, include: des matières’(3). ‘SELECT_TAGS’ - The default value is ‘("export")’. When a tree is tagged with - ‘export’ (‘org-export-select-tags’), Org selects that tree and its - subtrees for export. Org excludes trees with ‘noexport’ tags, see - below. When selectively exporting files with ‘export’ tags set, - Org does not export any text that appears before the first - headline. + List of tags that will, if present, be selected for export. The + default value is ‘org-export-select-tags’ ‘("export")’. When a + tree is tagged with ‘export’, Org selects that tree and its + subtrees for export, ignoring all the other sections that do not + possess the ‘export’ tag. + + When selectively exporting files with ‘export’ tags set, Org does + not export any text that appears before the first headline. + + Note that a file without the ‘export’ tags will export all its + sections. + + To select non-default tags for export, customize + ‘org-export-select-tags’ (globally) or add ‘#+SELECT_TAGS: tag1 + tag2’ to the document. ‘EXCLUDE_TAGS’ - The default value is ‘("noexport")’. When a tree is tagged with - ‘noexport’ (‘org-export-exclude-tags’), Org excludes that tree and - its subtrees from export. Entries tagged with ‘noexport’ are - unconditionally excluded from the export, even if they have an - ‘export’ tag. Even if a subtree is not exported, Org executes any - code blocks contained there. + List of tags that will be excluded from export. The default value + is ‘org-export-exclude-tags’ ‘("noexport")’. When a tree is tagged + with ‘noexport’, Org excludes that tree and its subtrees from + export. + + Entries tagged with ‘noexport’ are unconditionally excluded from + the export, even if they have an ‘export’ tag. Even if a subtree + is not exported, Org executes any code blocks contained there. + + To select non-default tags for the exclusion, customize + ‘org-export-exclude-tags’ (globally) or add ‘#+EXCLUDE_TAGS: tag1 + tag2’ to the document. ‘TITLE’ Org displays this title. For long titles, use multiple ‘#+TITLE’ @@ -10430,7 +10770,7 @@ equivalent global variables, include: ‘EXPORT_FILE_NAME’ The name of the output file to be generated. Otherwise, Org generates the file name based on the buffer name and the extension - based on the back-end format. + based on the backend format. The ‘OPTIONS’ keyword is a compact form. To configure multiple options, use several ‘OPTIONS’ lines. ‘OPTIONS’ recognizes the @@ -10474,6 +10814,10 @@ following arguments. Toggle inclusion of author name into exported file (‘org-export-with-author’). +‘expand-links’ + Toggle expansion of environment variables in file paths + (‘org-export-expand-links’). + ‘broken-links’ Toggles if Org should continue exporting upon finding a broken internal link. When set to ‘mark’, Org clearly marks the problem @@ -10507,7 +10851,7 @@ following arguments. ‘H’ Set the number of headline levels for export (‘org-export-headline-levels’). Below that level, headlines are - treated differently. In most back-ends, they become list items. + treated differently. In most backends, they become list items. ‘inline’ Toggle inclusion of inlinetasks (‘org-export-with-inlinetasks’). @@ -10552,7 +10896,7 @@ following arguments. ‘timestamp’ Toggle inclusion of the creation time in the exported file - (‘org-export-time-stamp-file’). + (‘org-export-timestamp-file’). ‘title’ Toggle inclusion of title (‘org-export-with-title’). @@ -10615,11 +10959,11 @@ all its children, set the ‘UNNUMBERED’ property to ‘notoc’ value. :UNNUMBERED: notoc :END: - Org normally inserts the table of contents directly before the first -headline of the file. To move the table of contents to a different -location, first turn off the default with ‘org-export-with-toc’ variable -or with ‘#+OPTIONS: toc:nil’. Then insert ‘#+TOC: headlines N’ at the -desired location(s). + Org normally inserts the table of contents in front of the exported +document. To move the table of contents to a different location, first +turn off the default with ‘org-export-with-toc’ variable or with +‘#+OPTIONS: toc:nil’. Then insert ‘#+TOC: headlines N’ at the desired +location(s). #+OPTIONS: toc:nil ... @@ -10665,7 +11009,7 @@ specified for the table of contents. ---------- Footnotes ---------- - (1) At the moment, some export back-ends do not obey this + (1) At the moment, some export backends do not obey this specification. For example, LaTeX export excludes every unnumbered headline from the table of contents. @@ -10675,21 +11019,23 @@ File: org.info, Node: Include Files, Next: Macro Replacement, Prev: Table of 13.4 Include Files ================== -During export, you can include the content of another file. For -example, to include your ‘.emacs’ file, you could use: +*note During export: Summary of the export process, you can include the +content of another file. For example, to include your ‘.emacs’ file, +you could use: #+INCLUDE: "~/.emacs" src emacs-lisp -The first parameter is the file name to include. The optional second -parameter specifies the block type: ‘example’, ‘export’ or ‘src’. The -optional third parameter specifies the source code language to use for -formatting the contents. This is relevant to both ‘export’ and ‘src’ -block types. - - If an included file is specified as having a markup language, Org -neither checks for valid syntax nor changes the contents in any way. -For example and source blocks, Org code-escapes the contents before -inclusion. +There are three positional arguments after the include keyword, they +are: + 1. The file name, this is the sole mandatory argument. Org neither + checks for correctness or validates the content in any way. + 2. The block name to wrap the file content in. When this is + ‘example’, ‘export’, or ‘src’ the content is escaped by + ‘org-escape-code-in-string’. Arbitrary block names may be given, + however block names starting with ‘:’ must be quoted, i.e. + ‘":name"’. + 3. The source code language to use for formatting the contents. This + is relevant to both ‘export’ and ‘src’ block types. If an included file is not specified as having any markup language, Org assumes it be in Org format and proceeds as usual with a few @@ -10718,7 +11064,7 @@ omitted to use the obvious defaults. ‘org-link-search’(1) (see *note Search Options::). The ranges for ‘:lines’ keyword are relative to the requested element. Therefore, - #+INCLUDE: "./paper.org::*conclusion" :lines 1-20 + #+INCLUDE: "./paper.org::*conclusion" :lines "1-20" includes the first 20 lines of the headline named ‘conclusion’. @@ -10774,7 +11120,7 @@ turns ‘{{{gnustamp(linux)}}}’ into ‘GNU/Linux’ during export. Org recognizes macro references in following Org markup areas: paragraphs, headlines, verse blocks, tables cells and lists. Org also recognizes macro references in keywords, such as ‘CAPTION’, ‘TITLE’, -‘AUTHOR’, ‘DATE’, and for some back-end specific export options. +‘AUTHOR’, ‘DATE’, and for some backend specific export options. Org comes with following pre-defined macros: @@ -10910,7 +11256,7 @@ ASCII export commands ASCII specific export settings ------------------------------ -The ASCII export back-end has one extra keyword for customizing ASCII +The ASCII export backend has one extra keyword for customizing ASCII output. Setting this keyword works similar to the general options (see *note Export Settings::). @@ -10929,7 +11275,7 @@ cut-off point where levels become lists, see *note Export Settings::. Quoting ASCII text ------------------ -To insert text within the Org file by the ASCII back-end, use one the +To insert text within the Org file by the ASCII backend, use one the following constructs, inline, keyword, or export block: Inline text @@ascii:and additional text@@ within a paragraph. @@ -10937,13 +11283,13 @@ following constructs, inline, keyword, or export block: #+ASCII: Some text #+BEGIN_EXPORT ascii - Org exports text in this block only when using ASCII back-end. + Org exports text in this block only when using ASCII backend. #+END_EXPORT ASCII specific attributes ------------------------- -ASCII back-end recognizes only one attribute, ‘:width’, which specifies +ASCII backend recognizes only one attribute, ‘:width’, which specifies the width of a horizontal rule in number of characters. The keyword and syntax for specifying widths is: @@ -10953,7 +11299,7 @@ syntax for specifying widths is: ASCII special blocks -------------------- -Besides ‘#+BEGIN_CENTER’ blocks (see *note Paragraphs::), ASCII back-end +Besides ‘#+BEGIN_CENTER’ blocks (see *note Paragraphs::), ASCII backend has these two left and right justification blocks: #+BEGIN_JUSTIFYLEFT @@ -11014,7 +11360,7 @@ File: org.info, Node: Beamer specific export settings, Next: Frames and Blocks 13.8.2 Beamer specific export settings -------------------------------------- -Beamer export back-end has several additional keywords for customizing +Beamer export backend has several additional keywords for customizing Beamer output. These keywords work similar to the general options settings (see *note Export Settings::). @@ -11103,7 +11449,7 @@ principle be exportable as a Beamer presentation. headline as an overlay or action specification. When enclosed in square brackets, Org export makes the overlay specification a default. Use ‘BEAMER_OPT’ to set any options applicable to the - current Beamer frame or block. The Beamer export back-end wraps + current Beamer frame or block. The Beamer export backend wraps with appropriate angular or square brackets. It also adds the ‘fragile’ option for any code that may require a verbatim block. @@ -11131,9 +11477,9 @@ File: org.info, Node: Beamer specific syntax, Next: Editing support, Prev: Fr 13.8.4 Beamer specific syntax ----------------------------- -Since Org’s Beamer export back-end is an extension of the LaTeX -back-end, it recognizes other LaTeX specific syntax—for example, -‘#+LATEX:’ or ‘#+ATTR_LATEX:’. See *note LaTeX Export::, for details. +Since Org’s Beamer export backend is an extension of the LaTeX backend, +it recognizes other LaTeX specific syntax—for example, ‘#+LATEX:’ or +‘#+ATTR_LATEX:’. See *note LaTeX Export::, for details. Beamer export wraps the table of contents generated with ‘toc:t’ ‘OPTION’ keyword in a ‘frame’ environment. Beamer export does not wrap @@ -11147,7 +11493,7 @@ Contents::). Use square brackets for specifying options. #+BEAMER: \pause #+BEGIN_EXPORT beamer - Only Beamer export back-end exports this. + Only Beamer export backend exports this. #+END_EXPORT Text @@beamer:some code@@ within a paragraph. @@ -11249,6 +11595,7 @@ compatible with XHTML 1.0 strict standard. * HTML specific export settings:: Settings for HTML export. * HTML doctypes:: Exporting various (X)HTML flavors. * HTML preamble and postamble:: Inserting preamble and postamble. +* Bare HTML:: Exporting HTML without CSS, Javascript, etc. * Quoting HTML tags:: Using direct HTML in Org files. * Headlines in HTML export:: Formatting headlines. * Links in HTML export:: Inserting and formatting links. @@ -11367,8 +11714,8 @@ introduced with the HTML5 standard. To enable them, set ‘org-html-html5-fancy’ to non-‘nil’. Or use an ‘OPTIONS’ line in the file to set ‘html5-fancy’. - HTML5 documents can now have arbitrary ‘#+BEGIN’ ... ‘#+END’ blocks. -For example: + HTML5 documents can have arbitrary ‘#+BEGIN’ ... ‘#+END’ blocks. For +example: #+BEGIN_aside Lorem ipsum @@ -11407,7 +11754,7 @@ the headline and its contents in ‘
’ or ‘
’ tags, set the ‘HTML_CONTAINER’ property for the headline.  -File: org.info, Node: HTML preamble and postamble, Next: Quoting HTML tags, Prev: HTML doctypes, Up: HTML Export +File: org.info, Node: HTML preamble and postamble, Next: Bare HTML, Prev: HTML doctypes, Up: HTML Export 13.9.4 HTML preamble and postamble ---------------------------------- @@ -11430,13 +11777,30 @@ postamble from looking up author’s name, email address, creator’s name, and date.  -File: org.info, Node: Quoting HTML tags, Next: Headlines in HTML export, Prev: HTML preamble and postamble, Up: HTML Export +File: org.info, Node: Bare HTML, Next: Quoting HTML tags, Prev: HTML preamble and postamble, Up: HTML Export -13.9.5 Quoting HTML tags +13.9.5 Exporting to minimal HTML +-------------------------------- + +If you want to output a minimal HTML file, with no CSS, no Javascript, +no preamble or postamble, here are the variable you would need to set: + + (setq org-html-head "" + org-html-head-extra "" + org-html-head-include-default-style nil + org-html-head-include-scripts nil + org-html-preamble nil + org-html-postamble nil + org-html-use-infojs nil) + + +File: org.info, Node: Quoting HTML tags, Next: Headlines in HTML export, Prev: Bare HTML, Up: HTML Export + +13.9.6 Quoting HTML tags ------------------------ -The HTML export back-end transforms ‘<’ and ‘>’ to ‘<’ and ‘>’. -To include raw HTML code in the Org file so the HTML export back-end can +The HTML export backend transforms ‘<’ and ‘>’ to ‘<’ and ‘>’. To +include raw HTML code in the Org file so the HTML export backend can insert that HTML code in the output, use this inline syntax: ‘@@html:...@@’. For example: @@ -11453,7 +11817,7 @@ insert that HTML code in the output, use this inline syntax:  File: org.info, Node: Headlines in HTML export, Next: Links in HTML export, Prev: Quoting HTML tags, Up: HTML Export -13.9.6 Headlines in HTML export +13.9.7 Headlines in HTML export ------------------------------- Headlines are exported to ‘

’, ‘

’, etc. Each headline gets the @@ -11467,27 +11831,27 @@ text of the headlines is also wrapped in ‘’ tags. These tags have a  File: org.info, Node: Links in HTML export, Next: Tables in HTML export, Prev: Headlines in HTML export, Up: HTML Export -13.9.7 Links in HTML export +13.9.8 Links in HTML export --------------------------- -The HTML export back-end transforms Org’s internal links (see *note -Internal Links::) to equivalent HTML links in the output. The back-end +The HTML export backend transforms Org’s internal links (see *note +Internal Links::) to equivalent HTML links in the output. The backend similarly handles Org’s automatic links created by radio targets (see *note Radio Targets::) similarly. For Org links to external files, the -back-end transforms the links to _relative_ paths. +backend transforms the links to _relative_ paths. - For Org links to other ‘.org’ files, the back-end automatically + For Org links to other ‘.org’ files, the backend automatically changes the file extension to ‘.html’ and makes file paths relative. If the ‘.org’ files have an equivalent ‘.html’ version at the same location, then the converted links should work without any further manual intervention. However, to disable this automatic path translation, set ‘org-html-link-org-files-as-html’ to ‘nil’. When -disabled, the HTML export back-end substitutes the ID-based links in the +disabled, the HTML export backend substitutes the ID-based links in the HTML output. For more about linking files when publishing to a directory, see *note Publishing links::. Org files can also have special directives to the HTML export -back-end. For example, by using ‘#+ATTR_HTML’ lines to specify new +backend. For example, by using ‘#+ATTR_HTML’ lines to specify new format attributes to ‘’ or ‘’ tags. This example shows changing the link’s title and style: @@ -11497,10 +11861,10 @@ the link’s title and style:  File: org.info, Node: Tables in HTML export, Next: Images in HTML export, Prev: Links in HTML export, Up: HTML Export -13.9.8 Tables in HTML export +13.9.9 Tables in HTML export ---------------------------- -The HTML export back-end uses ‘org-html-table-default-attributes’ when +The HTML export backend uses ‘org-html-table-default-attributes’ when exporting Org tables to HTML. By default, the exporter does not draw frames and cell borders. To change for this for a table, use the following lines before the table in the Org file: @@ -11508,8 +11872,8 @@ following lines before the table in the Org file: #+CAPTION: This is a table with lines around and between cells #+ATTR_HTML: :border 2 :rules all :frame border - The HTML export back-end preserves column groupings in Org tables -(see *note Column Groups::) when exporting to HTML. + The HTML export backend preserves column groupings in Org tables (see +*note Column Groups::) when exporting to HTML. Additional options for customizing tables for HTML export. @@ -11538,22 +11902,22 @@ following lines before the table in the Org file:  File: org.info, Node: Images in HTML export, Next: Math formatting in HTML export, Prev: Tables in HTML export, Up: HTML Export -13.9.9 Images in HTML export ----------------------------- +13.9.10 Images in HTML export +----------------------------- -The HTML export back-end has features to convert Org image links to HTML +The HTML export backend has features to convert Org image links to HTML inline images and HTML clickable image links. When the link in the Org file has no description, the HTML export -back-end by default in-lines that image. For example: +backend by default in-lines that image. For example: ‘[[file:myimg.jpg]]’ is in-lined, while ‘[[file:myimg.jpg][the image]]’ links to the text, ‘the image’. For more details, see the variable ‘org-html-inline-images’. On the other hand, if the description part of the Org link is itself another link, such as ‘file:’ or ‘http:’ URL pointing to an image, the -HTML export back-end in-lines this image and links to the main image. -This Org syntax enables the back-end to link low-resolution thumbnail to +HTML export backend in-lines this image and links to the main image. +This Org syntax enables the backend to link low-resolution thumbnail to the high-resolution version of the image, as shown in this example: [[file:highres.jpg][file:thumb.jpg]] @@ -11567,13 +11931,13 @@ accessibility standards. #+ATTR_HTML: :alt cat/spider image :title Action! :align right [[./img/a.jpg]] - The HTML export back-end copies the ‘http’ links from the Org file + The HTML export backend copies the ‘http’ links from the Org file as-is.  File: org.info, Node: Math formatting in HTML export, Next: Text areas in HTML export, Prev: Images in HTML export, Up: HTML Export -13.9.10 Math formatting in HTML export +13.9.11 Math formatting in HTML export -------------------------------------- LaTeX math snippets (see *note LaTeX fragments::) can be displayed in @@ -11621,7 +11985,7 @@ MathJax TeX and LaTeX in HTML documents  File: org.info, Node: Text areas in HTML export, Next: CSS support, Prev: Math formatting in HTML export, Up: HTML Export -13.9.11 Text areas in HTML export +13.9.12 Text areas in HTML export --------------------------------- Before Org mode’s Babel, one popular approach to publishing code in HTML @@ -11629,15 +11993,14 @@ was by using ‘:textarea’. The advantage of this approach was that copying and pasting was built into browsers with simple JavaScript commands. Even editing before pasting was made simple. - The HTML export back-end can create such text areas. It requires an + The HTML export backend can create such text areas. It requires an ‘#+ATTR_HTML’ line as shown in the example below with the ‘:textarea’ option. This must be followed by either an example or a source code block. Other Org block types do not honor the ‘:textarea’ option. - By default, the HTML export back-end creates a text area 80 -characters wide and height just enough to fit the content. Override -these defaults with ‘:width’ and ‘:height’ options on the ‘#+ATTR_HTML’ -line. + By default, the HTML export backend creates a text area 80 characters +wide and height just enough to fit the content. Override these defaults +with ‘:width’ and ‘:height’ options on the ‘#+ATTR_HTML’ line. #+ATTR_HTML: :textarea t :width 40 #+BEGIN_EXAMPLE @@ -11649,7 +12012,7 @@ line.  File: org.info, Node: CSS support, Next: JavaScript support, Prev: Text areas in HTML export, Up: HTML Export -13.9.12 CSS support +13.9.13 CSS support ------------------- You can modify the CSS style definitions for the exported file. The @@ -11690,7 +12053,7 @@ tables, etc. ‘.footnum’ footnote number in footnote definition (always ) ‘.org-svg’ default class for a linked ‘.svg’ image - The HTML export back-end includes a compact default style in each + The HTML export backend includes a compact default style in each exported HTML file. To override the default style with another style, use these keywords in the Org file. They will replace the global defaults the HTML exporter uses. @@ -11726,7 +12089,7 @@ the variables ‘org-html-todo-kwd-class-prefix’ and  File: org.info, Node: JavaScript support, Prev: CSS support, Up: HTML Export -13.9.13 JavaScript supported display of web pages +13.9.14 JavaScript supported display of web pages ------------------------------------------------- Sebastian Rose has written a JavaScript program especially designed to @@ -11803,7 +12166,7 @@ File: org.info, Node: LaTeX Export, Next: Markdown Export, Prev: HTML Export, 13.10 LaTeX Export ================== -The LaTeX export back-end can handle complex documents, incorporate +The LaTeX export backend can handle complex documents, incorporate standard or custom LaTeX document classes, generate documents using alternate LaTeX engines, and produce fully linked PDF files with indexes, bibliographies, and tables of contents, destined for @@ -11815,14 +12178,19 @@ quick references to variables for the impatient: for engines, see for packages, see ‘org-latex-default-packages-alist’ and ‘org-latex-packages-alist’. - An important note about the LaTeX export back-end: it is sensitive to + An important note about the LaTeX export backend: it is sensitive to blank lines in the Org document. That’s because LaTeX itself depends on blank lines to tell apart syntactical elements, such as paragraphs. + The following sections expect users to be familiar with common LaTeX +terminology. You may refer to to get +familiar with LaTeX basics. Users with LaTeX installed may also run +‘texdoc latex’ from terminal to open LaTeX introduction (1) + * Menu: * LaTeX/PDF export commands:: For producing LaTeX and PDF documents. -* LaTeX specific export settings:: Unique to this LaTeX back-end. +* LaTeX specific export settings:: Unique to this LaTeX backend. * LaTeX header and sectioning:: Setting up the export file structure. * Quoting LaTeX code:: Incorporating literal LaTeX code. * Tables in LaTeX export:: Options for exporting tables to LaTeX. @@ -11835,6 +12203,12 @@ blank lines to tell apart syntactical elements, such as paragraphs. * Verse blocks in LaTeX export:: Attributes specific to special blocks. * Quote blocks in LaTeX export:: Attributes specific to quote blocks. + ---------- Footnotes ---------- + + (1) The command will open a PDF file, which is also available for +download from + +  File: org.info, Node: LaTeX/PDF export commands, Next: LaTeX specific export settings, Up: LaTeX Export @@ -11860,10 +12234,10 @@ File: org.info, Node: LaTeX/PDF export commands, Next: LaTeX specific export s mode syntax before. This is a global command that can be invoked in any buffer. - The LaTeX export back-end can use any of these LaTeX engines: + The LaTeX export backend can use any of these LaTeX engines: ‘pdflatex’, ‘xelatex’, and ‘lualatex’. These engines compile LaTeX files with different compilers, packages, and output options. The LaTeX -export back-end finds the compiler version to use from +export backend finds the compiler version to use from ‘org-latex-compiler’ variable or the ‘#+LATEX_COMPILER’ keyword in the Org file. See the docstring for the ‘org-latex-default-packages-alist’ for loading packages with certain compilers. Also see @@ -11881,9 +12255,9 @@ File: org.info, Node: LaTeX specific export settings, Next: LaTeX header and s 13.10.2 LaTeX specific export settings -------------------------------------- -The LaTeX export back-end has several additional keywords for -customizing LaTeX output. Setting these keywords works similar to the -general options (see *note Export Settings::). +The LaTeX export backend has several additional keywords for customizing +LaTeX output. Setting these keywords works similar to the general +options (see *note Export Settings::). ‘DESCRIPTION’ The document’s description. The description along with author @@ -11896,7 +12270,9 @@ general options (see *note Export Settings::). ‘LANGUAGE’ - Language code of the primary document language. + Language code of the primary document language. When ‘LANGUAGE’ + keyword is not not specified use the value of + ‘org-export-default-language’ (by default - ‘en’, American English) The list of language codes supported by Org is stored in the variable ‘org-latex-language-alist’. @@ -11916,13 +12292,13 @@ general options (see *note Export Settings::). ‘LATEX_CLASS’ This is LaTeX document class, such as _article_, _report_, _book_, and so on, which contain predefined preamble and headline level - mapping that the LaTeX export back-end needs. The back-end reads - the default class name from the ‘org-latex-default-class’ variable. + mapping that the LaTeX export backend needs. The backend reads the + default class name from the ‘org-latex-default-class’ variable. Org has _article_ as the default class. A valid default class must be an element of ‘org-latex-classes’. ‘LATEX_CLASS_OPTIONS’ - Options the LaTeX export back-end uses when calling the LaTeX + Options the LaTeX export backend uses when calling the LaTeX document class. ‘LATEX_COMPILER’ @@ -11960,12 +12336,12 @@ File: org.info, Node: LaTeX header and sectioning, Next: Quoting LaTeX code, 13.10.3 LaTeX header and sectioning structure --------------------------------------------- -The LaTeX export back-end converts the first three of Org’s outline +The LaTeX export backend converts the first three of Org’s outline levels into LaTeX headlines. The remaining Org levels are exported as lists. To change this globally for the cut-off point between levels and lists, (see *note Export Settings::). - By default, the LaTeX export back-end uses the _article_ class. + By default, the LaTeX export backend uses the _article_ class. To change the default class globally, edit ‘org-latex-default-class’. To change the default class locally in an Org file, add option lines @@ -11977,17 +12353,17 @@ exporter splices the values of ‘org-latex-default-packages-alist’ and ‘org-latex-packages-alist’. Use the same three variables to define custom sectioning or custom classes. - The LaTeX export back-end sends the ‘LATEX_CLASS_OPTIONS’ keyword and + The LaTeX export backend sends the ‘LATEX_CLASS_OPTIONS’ keyword and ‘EXPORT_LATEX_CLASS_OPTIONS’ property as options to the LaTeX ‘\documentclass’ macro. The options and the syntax for specifying them, including enclosing them in square brackets, follow LaTeX conventions. #+LATEX_CLASS_OPTIONS: [a4paper,11pt,twoside,twocolumn] - The LaTeX export back-end appends values from ‘LATEX_HEADER’ and + The LaTeX export backend appends values from ‘LATEX_HEADER’ and ‘LATEX_HEADER_EXTRA’ keywords to the LaTeX header. The docstring for ‘org-latex-classes’ explains in more detail. Also note that LaTeX -export back-end does not append ‘LATEX_HEADER_EXTRA’ to the header when +export backend does not append ‘LATEX_HEADER_EXTRA’ to the header when previewing LaTeX snippets (see *note Previewing LaTeX fragments::). A sample Org file with the above headers: @@ -12045,9 +12421,10 @@ File: org.info, Node: Quoting LaTeX code, Next: Tables in LaTeX export, Prev: 13.10.4 Quoting LaTeX code -------------------------- -The LaTeX export back-end can insert any arbitrary LaTeX code, see *note -Embedded LaTeX::. There are three ways to embed such code in the Org -file and they all use different quoting syntax. +When the available LaTeX export customizations are not sufficient to +fine-tune the desired output, it is possible to insert any arbitrary +LaTeX code (see *note Embedded LaTeX::). There are three ways to embed +such code in the Org file and they all use different quoting syntax. Inserting in-line quoted with @ symbols: @@ -12057,7 +12434,7 @@ file and they all use different quoting syntax. #+LATEX: any arbitrary LaTeX code - Inserting as an export block in the Org file, where the back-end + Inserting as an export block in the Org file, where the backend exports any code between begin and end markers: #+BEGIN_EXPORT latex @@ -12070,35 +12447,35 @@ File: org.info, Node: Tables in LaTeX export, Next: Images in LaTeX export, P 13.10.5 Tables in LaTeX export ------------------------------ -The LaTeX export back-end can pass several LaTeX attributes for table +The LaTeX export backend can pass several LaTeX attributes for table contents and layout. Besides specifying a label (see *note Internal Links::) and a caption (see *note Captions::), the other valid LaTeX attributes include: ‘:mode’ - The LaTeX export back-end wraps the table differently depending on + The LaTeX export backend wraps the table differently depending on the mode for accurate rendering of math symbols. Mode is either ‘table’, ‘math’, ‘inline-math’, ‘verbatim’ or ‘tabbing’. - For ‘math’ or ‘inline-math’ mode, LaTeX export back-end wraps the + For ‘math’ or ‘inline-math’ mode, LaTeX export backend wraps the table in a math environment, but every cell in it is exported as-is. For ‘tabbing’ the LaTeX tabbing environment is used and the - correct tabbing delimiters ‘\>’ are used. The LaTeX export - back-end determines the default mode from - ‘org-latex-default-table-mode’. The LaTeX export back-end merges - contiguous tables in the same mode into a single environment. + correct tabbing delimiters ‘\>’ are used. The LaTeX export backend + determines the default mode from ‘org-latex-default-table-mode’. + The LaTeX export backend merges contiguous tables in the same mode + into a single environment. ‘:environment’ Set the default LaTeX table environment for the LaTeX export - back-end to use when exporting Org tables. Common LaTeX table + backend to use when exporting Org tables. Common LaTeX table environments are provided by these packages: tabularx, longtable, array, tabu, and bmatrix. For packages, such as tabularx and tabu, or any newer replacements, include them in the - ‘org-latex-packages-alist’ variable so the LaTeX export back-end - can insert the appropriate load package headers in the converted - LaTeX file. Look in the docstring for the - ‘org-latex-packages-alist’ variable for configuring these packages - for LaTeX snippet previews, if any. + ‘org-latex-packages-alist’ variable so the LaTeX export backend can + insert the appropriate load package headers in the converted LaTeX + file. Look in the docstring for the ‘org-latex-packages-alist’ + variable for configuring these packages for LaTeX snippet previews, + if any. ‘:caption’ Use ‘CAPTION’ keyword to set a simple caption for a table (see @@ -12120,12 +12497,12 @@ attributes include: LaTeX floats can also have additional layout ‘:placement’ attributes. These are the usual ‘[h t b p ! H]’ permissions specified in square brackets. Note that for ‘:float sideways’ - tables, the LaTeX export back-end ignores ‘:placement’ attributes. + tables, the LaTeX export backend ignores ‘:placement’ attributes. ‘:align’ ‘:font’ ‘:width’ - The LaTeX export back-end uses these attributes for regular tables + The LaTeX export backend uses these attributes for regular tables to set their alignments, fonts, and widths. ‘:options’ @@ -12136,7 +12513,7 @@ attributes include: ‘:options remark{Note}={note},remark{Source}={source}’. ‘:spread’ - When ‘:spread’ is non-‘nil’, the LaTeX export back-end spreads or + When ‘:spread’ is non-‘nil’, the LaTeX export backend spreads or shrinks the table by the ‘:width’ for tabu and longtabu environments. ‘:spread’ has no effect if ‘:width’ is not set. @@ -12153,10 +12530,10 @@ attributes include: ‘:math-prefix’ ‘:math-suffix’ ‘:math-arguments’ - The LaTeX export back-end inserts ‘:math-prefix’ string value in a - math environment before the table. The LaTeX export back-end + The LaTeX export backend inserts ‘:math-prefix’ string value in a + math environment before the table. The LaTeX export backend inserts ‘:math-suffix’ string value in a math environment after the - table. The LaTeX export back-end inserts ‘:math-arguments’ string + table. The LaTeX export backend inserts ‘:math-arguments’ string value between the macro name and the table’s contents. ‘:math-arguments’ comes in use for matrix macros that require more than one argument, such as ‘qbordermatrix’. @@ -12188,13 +12565,13 @@ File: org.info, Node: Images in LaTeX export, Next: Plain lists in LaTeX expor 13.10.6 Images in LaTeX export ------------------------------ -The LaTeX export back-end processes image links in Org files that do not +The LaTeX export backend processes image links in Org files that do not have descriptions, such as these links ‘[[file:img.jpg]]’ or ‘[[./img.jpg]]’, as direct image insertions in the final PDF output. In the PDF, they are no longer links but actual images embedded on the -page. The LaTeX export back-end uses ‘\includegraphics’ macro to insert +page. The LaTeX export backend uses ‘\includegraphics’ macro to insert the image. But for TikZ () -images, the back-end uses an ‘\input’ macro wrapped within a +images, the backend uses an ‘\input’ macro wrapped within a ‘tikzpicture’ environment. For specifying image ‘:width’, ‘:height’, ‘:scale’ and other @@ -12213,7 +12590,7 @@ overrides the default ‘#+CAPTION’ value: [[./img/sed-hr4049.pdf]] When captions follow the method as described in *note Captions::, the -LaTeX export back-end wraps the picture in a floating ‘figure’ +LaTeX export backend wraps the picture in a floating ‘figure’ environment. To float an image without specifying a caption, set the ‘:float’ attribute to one of the following: @@ -12221,7 +12598,7 @@ environment. To float an image without specifying a caption, set the For a default ‘figure’ environment. ‘multicolumn’ - To span the image across multiple columns of a page; the back-end + To span the image across multiple columns of a page; the backend wraps the image in a ‘figure*’ environment. ‘wrap’ @@ -12245,12 +12622,12 @@ placement. #+ATTR_LATEX: :float wrap :width 0.38\textwidth :placement {r}{0.4\textwidth} [[./img/hst.png]] - The LaTeX export back-end centers all images by default. Setting + The LaTeX export backend centers all images by default. Setting ‘:center’ to ‘nil’ disables centering. To disable centering globally, 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. +export backend to comment out the ‘\includegraphics’ macro.  File: org.info, Node: Plain lists in LaTeX export, Next: Source blocks in LaTeX export, Prev: Images in LaTeX export, Up: LaTeX Export @@ -12258,7 +12635,7 @@ File: org.info, Node: Plain lists in LaTeX export, Next: Source blocks in LaTe 13.10.7 Plain lists in LaTeX export ----------------------------------- -The LaTeX export back-end accepts the ‘environment’ and ‘options’ +The LaTeX export backend accepts the ‘environment’ and ‘options’ attributes for plain lists. Both attributes work together for customizing lists, as shown in the examples: @@ -12289,7 +12666,15 @@ File: org.info, Node: Source blocks in LaTeX export, Next: Example blocks in L 13.10.8 Source blocks in LaTeX export ------------------------------------- -The LaTeX export back-end can make source code blocks into floating +LaTeX export backend provides multiple ways to render src blocks in +LaTeX, according to the value of ‘org-latex-src-block-backend’. The +default value ‘verbatim’ renders the src code verbatim, without any +extra styling. Alternative values allow more colorful styling, but +require additional LaTeX (‘listings’, ‘minted’), system (‘minted’), or +Emacs (‘engraved’) packages. See the ‘org-latex-src-block-backend’ +docstring for more details. + + The LaTeX export backend can make source code blocks into floating objects through the attributes ‘:float’ and ‘:options’. For ‘:float’: ‘t’ @@ -12308,7 +12693,7 @@ objects through the attributes ‘:float’ and ‘:options’. For ‘:float Lisp code that may not fit in a single page. #+END_SRC - The LaTeX export back-end passes string values in ‘:options’ to LaTeX + The LaTeX export backend passes string values in ‘:options’ to LaTeX packages for customization of that specific source block. In the example below, the ‘:options’ are set for Engraved or Minted. Minted is a source code highlighting LaTeX package with many configurable @@ -12338,7 +12723,7 @@ File: org.info, Node: Example blocks in LaTeX export, Next: Special blocks in 13.10.9 Example blocks in LaTeX export -------------------------------------- -The LaTeX export back-end wraps the contents of example blocks in a +The LaTeX export backend wraps the contents of example blocks in a ‘verbatim’ environment. To change this behavior to use another environment globally, specify an appropriate export filter (see *note Advanced Export Configuration::). To change this behavior to use @@ -12356,8 +12741,8 @@ File: org.info, Node: Special blocks in LaTeX export, Next: Horizontal rules i 13.10.10 Special blocks in LaTeX export --------------------------------------- -For other special blocks in the Org file, the LaTeX export back-end -makes a special environment of the same name. The back-end also takes +For other special blocks in the Org file, the LaTeX export backend makes +a special environment of the same name. The backend also takes ‘:options’, if any, and appends as-is to that environment’s opening string. For example: @@ -12396,7 +12781,7 @@ File: org.info, Node: Horizontal rules in LaTeX export, Next: Verse blocks in 13.10.11 Horizontal rules in LaTeX export ----------------------------------------- -The LaTeX export back-end converts horizontal rules by the specified +The LaTeX export backend converts horizontal rules by the specified ‘:width’ and ‘:thickness’ attributes. For example: #+ATTR_LATEX: :width .6\textwidth :thickness 0.8pt @@ -12408,10 +12793,10 @@ File: org.info, Node: Verse blocks in LaTeX export, Next: Quote blocks in LaTe 13.10.12 Verse 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 backend accepts five attributes for verse blocks: +‘:lines’, ‘:center’, ‘:versewidth’, ‘:latexcode’ and ‘:literal’. 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 @@ -12426,6 +12811,17 @@ the standard LaTeX environment. ‘:latexcode’ It accepts any arbitrary LaTeX code that can be included within a LaTeX ‘verse’ environment. +‘:literal’ + With value t, all blank lines are preserved and exported as + ‘\vspace*{\baselineskip}’, including the blank lines before or + after contents. Note that without the ‘:literal’ attribute, one or + more blank lines between stanzas are exported as a single blank + line, and any blank lines before or after the content are removed, + which is more consistent with the syntax of the LaTeX ‘verse’ + environment, and the one provided by the ‘verse’ package. If the + ‘verse’ package is loaded, the vertical spacing between all stanzas + can be controlled by the global length ‘\stanzaskip’ (see + ). A complete example with Shakespeare’s first sonnet: @@ -12454,7 +12850,7 @@ File: org.info, Node: Quote blocks in LaTeX export, Prev: Verse blocks in LaTe 13.10.13 Quote blocks in LaTeX export ------------------------------------- -The LaTeX export back-end accepts two attributes for quote blocks: +The LaTeX export backend 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’, @@ -12486,13 +12882,19 @@ File: org.info, Node: Markdown Export, Next: OpenDocument Text Export, Prev: 13.11 Markdown Export ===================== -The Markdown export back-end, “md”, converts an Org file to Markdown +The Markdown export backend, “md”, converts an Org file to Markdown format, as defined at . +This is the original Markdown specification, developed by John Gruber +and Aaron Swartz. - Since it is built on top of the HTML back-end (see *note HTML -Export::), it converts every Org construct not defined in Markdown + Since “md” backend is built on top of the HTML backend (see *note +HTML Export::), it converts every Org construct not defined in Markdown syntax, such as tables, to HTML. + Do note that the original markdown syntax has differences with other +commonly used Markdown flavors. See + for more details. + Markdown export commands ------------------------ @@ -12510,10 +12912,12 @@ Header and sectioning structure ------------------------------- Based on ‘org-md-headline-style’, Markdown export can generate headlines -of both _atx_ and _setext_ types. _atx_ limits headline levels to two -whereas _setext_ limits headline levels to six. Beyond these limits, -the export back-end converts headlines to lists. To set a limit to a -level before the absolute limit (see *note Export Settings::). +of both _atx_ and _setext_ types. _setext_ limits headline levels to +two whereas _atx_ limits headline levels to six. _mixed_ exports +headline levels one and two in _setext_-style, and headline levels three +through six as _atx_-style headlines. Beyond these limits, the export +backend converts headlines to lists. To set a limit to a level before +the absolute limit (see *note Export Settings::).  File: org.info, Node: OpenDocument Text Export, Next: Org Export, Prev: Markdown Export, Up: Exporting @@ -12521,7 +12925,7 @@ File: org.info, Node: OpenDocument Text Export, Next: Org Export, Prev: Markd 13.12 OpenDocument Text Export ============================== -The ODT export back-end handles creating of OpenDocument Text (ODT) +The ODT export backend handles creating of OpenDocument Text (ODT) format. Documents created by this exporter use the ‘OpenDocument-v1.2 specification’(1) and are compatible with LibreOffice 3.4. @@ -12552,7 +12956,7 @@ File: org.info, Node: Pre-requisites for ODT export, Next: ODT export commands 13.12.1 Pre-requisites for ODT export ------------------------------------- -The ODT export back-end relies on the zip program to create the final +The ODT export backend relies on the zip program to create the final compressed ODT output. Check if ‘zip’ is locally available and executable. Without it, export cannot finish. @@ -12566,16 +12970,16 @@ File: org.info, Node: ODT export commands, Next: ODT specific export settings, Export as OpenDocument Text file. If ‘org-odt-preferred-output-format’ is specified, the ODT export - back-end automatically converts the exported file to that format. + backend automatically converts the exported file to that format. For ‘myfile.org’, Org exports to ‘myfile.odt’, overwriting without - warning. The ODT export back-end exports a region only if a region + warning. The ODT export backend exports a region only if a region was active. - If the selected region is a single tree, the ODT export back-end + If the selected region is a single tree, the ODT export backend makes the tree head the document title. Incidentally, ‘C-c @’ selects the current subtree. If the tree head entry has, or - inherits, an ‘EXPORT_FILE_NAME’ property, the ODT export back-end + inherits, an ‘EXPORT_FILE_NAME’ property, the ODT export backend uses that for file name. ‘C-c C-e o O’ @@ -12591,23 +12995,23 @@ File: org.info, Node: ODT specific export settings, Next: Extending ODT export 13.12.3 ODT specific export settings ------------------------------------ -The ODT export back-end has several additional keywords for customizing +The ODT export backend has several additional keywords for customizing ODT output. Setting these keywords works similar to the general options (see *note Export Settings::). ‘DESCRIPTION’ - This is the document’s description, which the ODT export back-end + This is the document’s description, which the ODT export backend inserts as document metadata. For long descriptions, use multiple lines, prefixed with ‘DESCRIPTION’. ‘KEYWORDS’ - The keywords for the document. The ODT export back-end inserts the + The keywords for the document. The ODT export backend inserts the description along with author name, keywords, and related file metadata as metadata in the output file. Use multiple ‘KEYWORDS’ if necessary. ‘ODT_STYLES_FILE’ - The ODT export back-end uses the ‘org-odt-styles-file’ by default. + The ODT export backend uses the ‘org-odt-styles-file’ by default. See *note Applying custom styles:: for details. ‘SUBTITLE’ @@ -12619,7 +13023,7 @@ File: org.info, Node: Extending ODT export, Next: Applying custom styles, Pre 13.12.4 Extending ODT export ---------------------------- -The ODT export back-end can produce documents in other formats besides +The ODT export backend can produce documents in other formats besides ODT using a specialized ODT converter process. Its common interface works with popular converters to produce formats such as ‘doc’, or convert a document from one format, say ‘csv’, to another format, say @@ -12636,16 +13040,16 @@ Automatically exporting to other formats If ODT format is just an intermediate step to get to other formats, such as ‘doc’, ‘docx’, ‘rtf’, or ‘pdf’, etc., then extend the ODT export -back-end to directly produce that format. Specify the final format in +backend to directly produce that format. Specify the final format in the ‘org-odt-preferred-output-format’ variable. This is one way to extend (see *note ODT export commands::). Converting between document formats ................................... -The Org export back-end is made to be inter-operable with a wide range -of text document format converters. Newer generation converters, such -as LibreOffice and Pandoc, can handle hundreds of formats at once. Org +The Org export backend is made to be inter-operable with a wide range of +text document format converters. Newer generation converters, such as +LibreOffice and Pandoc, can handle hundreds of formats at once. Org provides a consistent interaction with whatever converter is installed. Here are some generic commands: @@ -12659,7 +13063,7 @@ File: org.info, Node: Applying custom styles, Next: Links in ODT export, Prev 13.12.5 Applying custom styles ------------------------------ -The ODT export back-end comes with many OpenDocument styles (see *note +The ODT export backend comes with many OpenDocument styles (see *note Working with OpenDocument style files::). To expand or further customize these built-in style sheets, either edit the style sheets directly or generate them using an application such as LibreOffice. The @@ -12694,7 +13098,7 @@ Applying custom styles: the easy way Using third-party styles and templates ...................................... -The ODT export back-end relies on many templates and style names. Using +The ODT export backend relies on many templates and style names. Using third-party styles and templates can lead to mismatches. Templates derived from built-in ODT templates and styles seem to have fewer problems. @@ -12722,19 +13126,19 @@ File: org.info, Node: Tables in ODT export, Next: Images in ODT export, Prev: 13.12.7 Tables in ODT export ---------------------------- -The ODT export back-end handles native Org mode tables (see *note +The ODT export backend handles native Org mode tables (see *note Tables::) and simple ‘table.el’ tables. Complex ‘table.el’ tables having column or row spans are not supported. Such tables are stripped from the exported document. - By default, the ODT export back-end exports a table with top and + By default, the ODT export backend exports a table with top and bottom frames and with ruled lines separating row and column groups (see *note Column Groups::). All tables are typeset to occupy the same -width. The ODT export back-end honors any table alignments and relative +width. The ODT export backend honors any table alignments and relative widths for columns (see *note Column Width and Alignment::). - Note that the ODT export back-end interprets column widths as -weighted ratios, the default weight being 1. + Note that the ODT export backend interprets column widths as weighted +ratios, the default weight being 1. Specifying ‘:rel-width’ property on an ‘ATTR_ODT’ line controls the width of the table. For example: @@ -12769,7 +13173,7 @@ File: org.info, Node: Images in ODT export, Next: Math formatting in ODT expor Embedding images ................ -The ODT export back-end processes image links in Org files that do not +The ODT export backend processes image links in Org files that do not have descriptions, such as these links ‘[[file:img.jpg]]’ or ‘[[./img.jpg]]’, as direct image insertions in the final output. Either of these examples works: @@ -12794,18 +13198,17 @@ Sizing and scaling of embedded images Control the size and scale of the embedded images with the ‘ATTR_ODT’ attribute. - The ODT export back-end starts with establishing the size of the -image in the final document. The dimensions of this size are measured -in centimeters. The back-end then queries the image file for its -dimensions measured in pixels. For this measurement, the back-end -relies on ImageMagick’s identify program or Emacs ‘create-image’ and -‘image-size’ API. ImageMagick is the preferred choice for large file -sizes or frequent batch operations. The back-end then converts the -pixel dimensions using ‘org-odt-pixels-per-inch’ into the familiar 72 -dpi or 96 dpi. The default value for this is in -‘display-pixels-per-inch’, which can be tweaked for better results based -on the capabilities of the output device. Here are some common image -scaling operations: + The ODT export backend starts with establishing the size of the image +in the final document. The dimensions of this size are measured in +centimeters. The backend then queries the image file for its dimensions +measured in pixels. For this measurement, the backend relies on +ImageMagick’s identify program or Emacs ‘create-image’ and ‘image-size’ +API. ImageMagick is the preferred choice for large file sizes or +frequent batch operations. The backend then converts the pixel +dimensions using ‘org-odt-pixels-per-inch’ into the familiar 72 dpi or +96 dpi. The default value for this is in ‘display-pixels-per-inch’, +which can be tweaked for better results based on the capabilities of the +output device. Here are some common image scaling operations: Explicitly size the image To embed ‘img.png’ as a 10 cm x 10 cm image, do the following: @@ -12836,7 +13239,7 @@ Scale the image to a specific height Anchoring of images ................... -The ODT export back-end can anchor images to ‘as-char’, ‘paragraph’, or +The ODT export backend can anchor images to ‘as-char’, ‘paragraph’, or ‘page’. Set the preferred anchor using the ‘:anchor’ property of the ‘ATTR_ODT’ line. @@ -12893,7 +13296,7 @@ MathML or, to use LaTeX​ML(2) instead, (setq org-latex-to-mathml-convert-command - "latexmlmath \"%i\" --presentationmathml=%o") + "latexmlmath %i --presentationmathml=%o") To quickly verify the reliability of the LaTeX-to-MathML converter, use the following commands: @@ -12987,12 +13390,12 @@ File: org.info, Node: Literal examples in ODT export, Next: Advanced topics in 13.12.11 Literal examples in ODT export --------------------------------------- -The ODT export back-end supports literal examples (see *note Literal -Examples::) with full fontification. Internally, the ODT export -back-end relies on ‘htmlfontify.el’ to generate the style definitions -needed for fancy listings. The auto-generated styles get ‘OrgSrc’ -prefix and inherit colors from the faces used by Emacs Font Lock library -for that source language. +The ODT export backend supports literal examples (see *note Literal +Examples::) with full fontification. Internally, the ODT export backend +relies on ‘htmlfontify.el’ to generate the style definitions needed for +fancy listings. The auto-generated styles get ‘OrgSrc’ prefix and +inherit colors from the faces used by Emacs Font Lock library for that +source language. For custom fontification styles, customize the ‘org-odt-create-custom-styles-for-srcblocks’ option. @@ -13006,13 +13409,13 @@ File: org.info, Node: Advanced topics in ODT export, Prev: Literal examples in 13.12.12 Advanced topics in ODT export -------------------------------------- -The ODT export back-end has extensive features useful for power users -and frequent uses of ODT formats. +The ODT export backend has extensive features useful for power users and +frequent uses of ODT formats. Configuring a document converter ................................ -The ODT export back-end works with popular converters with little or no +The ODT export backend works with popular converters with little or no extra configuration. See *note Extending ODT export::. The following is for unsupported converters or tweaking existing defaults. @@ -13072,7 +13475,7 @@ Customize these variables to override the factory styles used by the exporter. ‘org-odt-styles-file’ - The ODT export back-end uses the file pointed to by this variable, + The ODT export backend uses the file pointed to by this variable, such as ‘styles.xml’, for the final output. It can take one of the following values: @@ -13101,7 +13504,7 @@ exporter. Creating one-off styles ....................... -The ODT export back-end can read embedded raw OpenDocument XML from the +The ODT export backend can read embedded raw OpenDocument XML from the Org file. Such direct formatting is useful for one-off instances. Embedding ODT tags as part of regular text @@ -13120,7 +13523,7 @@ Embedding ODT tags as part of regular text Embedding a one-line OpenDocument XML - The ODT export back-end can read one-liner options with ‘#+ODT:’ in + The ODT export backend can read one-liner options with ‘#+ODT:’ in the Org file. For example, to force a page break: #+ODT: @@ -13135,7 +13538,7 @@ Embedding a one-line OpenDocument XML Embedding a block of OpenDocument XML - The ODT export back-end can also read ODT export blocks for + The ODT export backend can also read ODT export blocks for OpenDocument XML. Such blocks use the ‘#+BEGIN_EXPORT odt’ ... ‘#+END_EXPORT’ constructs. @@ -13271,7 +13674,7 @@ editing—of XML files: *note (nxml-mode)Introduction::. Customize ‘org-odt-schema-dir’ to point to a directory with OpenDocument RNC files and the needed schema-locating rules. The ODT -export back-end takes care of updating the ‘rng-schema-locating-files’. +export backend takes care of updating the ‘rng-schema-locating-files’. ---------- Footnotes ---------- @@ -13293,10 +13696,9 @@ File: org.info, Node: Org Export, Next: Texinfo Export, Prev: OpenDocument Te 13.13 Org Export ================ -_org_ export back-end creates a normalized version of the Org document -in current buffer. The exporter evaluates Babel code (see *note -Evaluating Code Blocks::) and removes content specific to other -back-ends. +_org_ export backend creates a normalized version of the Org document in +current buffer. The exporter evaluates Babel code (see *note Evaluating +Code Blocks::) and removes content specific to other backends. Org export commands ------------------- @@ -13353,7 +13755,7 @@ File: org.info, Node: Texinfo specific export settings, Next: Texinfo file hea 13.14.2 Texinfo specific export settings ---------------------------------------- -The Texinfo export back-end has several additional keywords for +The Texinfo export backend has several additional keywords for customizing Texinfo output. Setting these keywords works similar to the general options (see *note Export Settings::). @@ -13377,13 +13779,22 @@ general options (see *note Export Settings::). Arbitrary lines inserted after the end of the header. ‘TEXINFO_DIR_CATEGORY’ - The directory category of the document. + The directory category of the document. Defaults to ‘Misc’. -‘TEXINFO_DIR_TITLE’ - The directory title of the document. +‘TEXINFO_DIR_NAME’ + The directory name of the document. This is the short name under + which the ‘m’ command will find your manual in the main Info + directory. It defaults to the base name of the Texinfo file. + + The full form of the Texinfo entry is ‘* DIRNAME: NODE.’ where + ‘NODE’ is usually just ‘(FILENAME)’. Normally this option only + provides the ‘DIRNAME’ part, but if you need more control, it can + also be the full entry (recognized by the presence of parentheses + or a leading ~* ~). ‘TEXINFO_DIR_DESC’ - The directory description of the document. + The directory description of the document. Defaults to the title + of the document. ‘TEXINFO_PRINTED_TITLE’ The printed title of the document. @@ -13394,7 +13805,7 @@ File: org.info, Node: Texinfo file header, Next: Texinfo title and copyright p 13.14.3 Texinfo file header --------------------------- -After creating the header for a Texinfo file, the Texinfo back-end +After creating the header for a Texinfo file, the Texinfo backend automatically generates a name and destination path for the Info file. To override this default with a more sensible path and name, specify the ‘TEXINFO_FILENAME’ keyword. @@ -13431,7 +13842,7 @@ keywords. They have to be set in raw Texinfo code. #+TEXINFO_PRINTED_TITLE: This Long Title@@inlinefmt{tex,@*} Is Broken in @TeX{} Copying material is defined in a dedicated headline with a non-‘nil’ -‘COPYING’ property. The back-end inserts the contents within a +‘COPYING’ property. The backend inserts the contents within a ‘@copying’ command at the beginning of the document. The heading itself does not appear in the structure of the document. @@ -13454,14 +13865,14 @@ File: org.info, Node: Info directory file, Next: Headings and sectioning struc The end result of the Texinfo export process is the creation of an Info file. This Info file’s metadata has variables for category, title, and -description: ‘TEXINFO_DIR_CATEGORY’, ‘TEXINFO_DIR_TITLE’, and +description: ‘TEXINFO_DIR_CATEGORY’, ‘TEXINFO_DIR_NAME’, and ‘TEXINFO_DIR_DESC’ keywords that establish where in the Info hierarchy the file fits. Here is an example that writes to the Info directory file: #+TEXINFO_DIR_CATEGORY: Emacs - #+TEXINFO_DIR_TITLE: Org Mode: (org) + #+TEXINFO_DIR_NAME: Org Mode #+TEXINFO_DIR_DESC: Outline-based notes management and organizer  @@ -13470,7 +13881,7 @@ File: org.info, Node: Headings and sectioning structure, Next: Indices, Prev: 13.14.6 Headings and sectioning structure ----------------------------------------- -The Texinfo export back-end uses a pre-defined scheme to convert Org +The Texinfo export backend uses a pre-defined scheme to convert Org headlines to equivalent Texinfo structuring commands. A scheme like this maps top-level headlines to numbered chapters tagged as ‘@chapter’ and lower-level headlines to unnumbered chapters tagged as @@ -13478,17 +13889,17 @@ and lower-level headlines to unnumbered chapters tagged as Texinfo structuring commands, define a new class in ‘org-texinfo-classes’. Activate the new class with the ‘TEXINFO_CLASS’ keyword. When no new class is defined and activated, the Texinfo export -back-end defaults to the ‘org-texinfo-default-class’. +backend defaults to the ‘org-texinfo-default-class’. If an Org headline’s level has no associated Texinfo structuring command, or is below a certain threshold (see *note Export Settings::), -then the Texinfo export back-end makes it into a list item. +then the Texinfo export backend makes it into a list item. - The Texinfo export back-end makes any headline with a non-‘nil’ + The Texinfo export backend makes any headline with a non-‘nil’ ‘APPENDIX’ property into an appendix. This happens independent of the Org headline level or the ‘TEXINFO_CLASS’ keyword. - The Texinfo export back-end creates a menu entry after the Org + The Texinfo export backend creates a menu entry after the Org headline for each regular sectioning structure. To override this with a shorter menu entry, use the ‘ALT_TITLE’ property (see *note Table of Contents::). Texinfo menu entries also have an option for a longer @@ -13512,18 +13923,18 @@ File: org.info, Node: Indices, Next: Quoting Texinfo code, Prev: Headings and 13.14.7 Indices --------------- -The Texinfo export back-end recognizes these indexing keywords if used -in the Org file: ‘CINDEX’, ‘FINDEX’, ‘KINDEX’, ‘PINDEX’, ‘TINDEX’ and +The Texinfo export backend recognizes these indexing keywords if used in +the Org file: ‘CINDEX’, ‘FINDEX’, ‘KINDEX’, ‘PINDEX’, ‘TINDEX’ and ‘VINDEX’. Write their value as verbatim Texinfo code; in particular, ‘{’, ‘}’ and ‘@’ characters need to be escaped with ‘@’ if they do not belong to a Texinfo command. #+CINDEX: Defining indexing entries - For the back-end to generate an index entry for a headline, set the + For the backend to generate an index entry for a headline, set the ‘INDEX’ property to ‘cp’ or ‘vr’. These abbreviations come from Texinfo that stand for concept index and variable index. The Texinfo manual has -abbreviations for all other kinds of indexes. The back-end exports the +abbreviations for all other kinds of indexes. The backend exports the headline as an unnumbered chapter or section command, and then inserts the index after its contents. @@ -13557,7 +13968,7 @@ File: org.info, Node: Plain lists in Texinfo export, Next: Tables in Texinfo e 13.14.9 Plain lists in Texinfo export ------------------------------------- -The Texinfo export back-end converts unordered and ordered lists in the +The Texinfo export backend converts unordered and ordered lists in the Org file using the default command ‘@itemize’. Ordered lists are numbered when exported to Texinfo format. Such @@ -13570,19 +13981,19 @@ specific number, or switch to a lettered list, as illustrated here: 2. Bravo 3. Charlie - The Texinfo export back-end by default converts description lists in + The Texinfo export backend by default converts description lists in the Org file using the default command ‘@table’, which results in a table with two columns. To change this behavior, set ‘:table-type’ attribute to either ‘ftable’ or ‘vtable’ value. For more information, see *note (texinfo)Two-column Tables::. - The Texinfo export back-end by default also applies a text highlight + The Texinfo export backend by default also applies a text highlight based on the defaults stored in ‘org-texinfo-table-default-markup’. To override the default highlight command, specify another one with the ‘:indic’ attribute. Org syntax is limited to one entry per list item. Nevertheless, the -Texinfo export back-end can split that entry according to any text +Texinfo export backend can split that entry according to any text provided through the ‘:sep’ attribute. Each part then becomes a new entry in the first column of the table. @@ -13601,8 +14012,8 @@ becomes The ‘:compact’ attribute is an alternative to the ‘:sep’ attribute, which allows writing each entry on its own line. If this attribute is -non-nil and an item in a description list has no body but is followed by -another item, then the second item is transcoded to ‘@itemx’. This +non-‘nil’ and an item in a description list has no body but is followed +by another item, then the second item is transcoded to ‘@itemx’. This example is transcoded to the same output as above. #+ATTR_TEXINFO: :table-type vtable :indic asis :compact t @@ -13614,17 +14025,17 @@ example is transcoded to the same output as above. a file using the ‘compact-itemx’ export option, or globally using the variable ‘org-texinfo-compact-itemx’. - The Texinfo export back-end also supports two approaches to writing + The Texinfo export backend also supports two approaches to writing Texinfo definition commands (see *note (texinfo)Definition Commands::). One of them uses description lists and is described below, the other relies on special blocks (see *note Special blocks in Texinfo export::). - Items in a description list in a Org file that begin with ‘Function:’ -or certain other prefixes are converted using Texinfo definition -commands. This works even if other items in the same list do not have -such a prefix; if necessary a single description list is converted using -multiple tables (such as ‘@vtable’) and definition commands (such as -‘@defun’). + Items in a description list in an Org file that begin with +‘Function:’ or certain other prefixes are converted using Texinfo +definition commands. This works even if other items in the same list do +not have such a prefix; if necessary a single description list is +converted using multiple tables (such as ‘@vtable’) and definition +commands (such as ‘@defun’). - Function: org-texinfo-drawer drawer contents info :: Transcode a DRAWER element from Org to Texinfo. @@ -13674,7 +14085,7 @@ File: org.info, Node: Tables in Texinfo export, Next: Images in Texinfo export 13.14.10 Tables in Texinfo export --------------------------------- -When exporting tables, the Texinfo export back-end uses the widest cell +When exporting tables, the Texinfo export backend uses the widest cell width in each column. To override this and instead specify as fractions of line length, use the ‘:columns’ attribute. See example below. @@ -13688,7 +14099,7 @@ File: org.info, Node: Images in Texinfo export, Next: Quotations in Texinfo ex --------------------------------- Insert a file link to the image in the Org file, and the Texinfo export -back-end inserts the image. These links must have the usual supported +backend inserts the image. These links must have the usual supported image extensions and no descriptions. To scale the image, use ‘:width’ and ‘:height’ attributes. For alternate text, use ‘:alt’ and specify the text using Texinfo code, as shown in the example: @@ -13750,11 +14161,11 @@ File: org.info, Node: Special blocks in Texinfo export, Next: A Texinfo exampl 13.14.14 Special blocks in Texinfo export ----------------------------------------- -The Texinfo export back-end supports two approaches to writing Texinfo +The Texinfo export backend supports two approaches to writing Texinfo definition commands. One of them is described here, the other in *note Plain lists in Texinfo export::. - The Texinfo export back-end converts special blocks to commands with + The Texinfo export backend converts special blocks to commands with the same name. It also adds any ‘:options’ attributes to the end of the command, as shown in this example: @@ -13793,7 +14204,7 @@ Texts:: for an equivalent example using Texinfo code. #+TEXINFO_HEADER: @syncodeindex pg cp #+TEXINFO_DIR_CATEGORY: Texinfo documentation system - #+TEXINFO_DIR_TITLE: sample: (sample) + #+TEXINFO_DIR_NAME: sample #+TEXINFO_DIR_DESC: Invoking sample #+TEXINFO_PRINTED_TITLE: GNU Sample @@ -13842,36 +14253,40 @@ Texts:: for an equivalent example using Texinfo code. :END:  -File: org.info, Node: iCalendar Export, Next: Other Built-in Back-ends, Prev: Texinfo Export, Up: Exporting +File: org.info, Node: iCalendar Export, Next: Other Built-in Backends, Prev: Texinfo Export, Up: Exporting 13.15 iCalendar Export ====================== A large part of Org mode’s interoperability success is its ability to easily export to or import from external applications. The iCalendar -export back-end takes calendar data from Org files and exports to the +export backend takes calendar data from Org files and exports to the standard iCalendar format. - The iCalendar export back-end can also incorporate TODO entries based + By default, iCalendar export only includes headings that contain +active timestamps or diary sexps(1). + + The iCalendar export backend can also incorporate TODO entries based on the configuration of the ‘org-icalendar-include-todo’ variable. The -back-end exports plain timestamps as ‘VEVENT’, TODO items as ‘VTODO’, -and also create events from deadlines that are in non-TODO items. The -back-end uses the deadlines and scheduling dates in Org TODO items for -setting the start and due dates for the iCalendar TODO entry. Consult -the ‘org-icalendar-use-deadline’ and ‘org-icalendar-use-scheduled’ -variables for more details. - - For tags on the headline, the iCalendar export back-end makes them +backend exports plain timestamps as ‘VEVENT’, TODO items as ‘VTODO’, and +also create events from deadlines that are in non-TODO items. + + The backend uses the deadlines and scheduling dates in Org TODO items +for setting the start and due dates for the iCalendar TODO entry. +Consult the ‘org-icalendar-use-deadline’, ‘org-icalendar-use-scheduled’, +and ‘org-icalendar-todo-unscheduled-start’ variables for more details. + + For tags on the headline, the iCalendar export backend makes them into iCalendar categories. To tweak the inheritance of tags and TODO states, configure the variable ‘org-icalendar-categories’. To assign clock alarms based on time, configure the ‘org-icalendar-alarm-time’ variable. The iCalendar format standard requires globally unique identifier—or -UID—for each entry. The iCalendar export back-end creates UIDs during +UID—for each entry. The iCalendar export backend creates UIDs during export. To save a copy of the UID in the Org file set the variable -‘org-icalendar-store-UID’. The back-end looks for the ‘ID’ property of -the entry for re-using the same UID for subsequent exports. +‘org-icalendar-store-UID’. The backend looks for the ‘ID’ property of +the entry for reusing the same UID for subsequent exports. Since a single Org entry can result in multiple iCalendar entries—timestamp, deadline, scheduled item, or TODO item—Org adds @@ -13892,14 +14307,26 @@ unique, yet enable synchronization programs trace the connections. ‘org-agenda-files’ and write it to ‘org-icalendar-combined-agenda-file’ file name. - The iCalendar export back-end includes ‘SUMMARY’, ‘DESCRIPTION’, + The iCalendar export backend includes ‘SUMMARY’, ‘DESCRIPTION’, ‘LOCATION’, ‘TIMEZONE’ and ‘CLASS’ properties from the Org entries when -exporting. To force the back-end to inherit the ‘LOCATION’, ‘TIMEZONE’ +exporting. To force the backend to inherit the ‘LOCATION’, ‘TIMEZONE’ and ‘CLASS’ properties, configure the ‘org-use-property-inheritance’ variable. + ‘SUMMARY’, ‘LOCATION’, and ‘DESCRIPTION’ properties can define +multi-line summary, location, or description using ‘+’ syntax +(see *note Property Syntax::): + + * Meeting at location with multi-line address + <2024-01-08 Mon 14:20-15:00> + :PROPERTIES: + :LOCATION: Someplace + :LOCATION+: Some Street 5 + :LOCATION+: 12345 Small Town + :END: + When Org entries do not have ‘SUMMARY’, ‘DESCRIPTION’, ‘LOCATION’ and -‘CLASS’ properties, the iCalendar export back-end derives the summary +‘CLASS’ properties, the iCalendar export backend derives the summary from the headline, and derives the description from the body of the Org item. The ‘org-icalendar-include-body’ variable limits the maximum number of characters of the content are turned into its description. @@ -13922,30 +14349,42 @@ information. The iCalendar standard defines three visibility classes: The server should treat unknown class properties the same as ‘PRIVATE’. + The exported iCalendar file can advise clients how often to check for +updates. This duration can be set globally with the ‘org-icalendar-ttl’ +variable, or on a per-document basis with the ‘ICAL-TTL’ keyword. This +option should be set using the iCalendar notation for time durations; +consult the docstring of ‘org-icalendar-ttl’ for more details. + Exporting to iCalendar format depends in large part on the capabilities of the destination application. Some are more lenient than others. Consult the Org mode FAQ for advice on specific applications. + ---------- Footnotes ---------- + + (1) Diary sexp events, except certain built-in types (see +‘icalendar-export-sexp-enumerate-all’), are exported up to +‘icalendar-export-sexp-enumeration-days’ into future. +  -File: org.info, Node: Other Built-in Back-ends, Next: Advanced Export Configuration, Prev: iCalendar Export, Up: Exporting +File: org.info, Node: Other Built-in Backends, Next: Advanced Export Configuration, Prev: iCalendar Export, Up: Exporting -13.16 Other Built-in Back-ends -============================== +13.16 Other Built-in Backends +============================= -Other export back-ends included with Org are: +Other export backends included with Org are: • ‘ox-man.el’: Export to a man page. - To activate such back-ends, either customize ‘org-export-backends’ or -load directly with ‘(require 'ox-man)’. On successful load, the -back-end adds new keys in the export dispatcher (see *note The Export + To activate such backends, either customize ‘org-export-backends’ or +load directly with ‘(require 'ox-man)’. On successful load, the backend +adds new keys in the export dispatcher (see *note The Export Dispatcher::). Follow the comment section of such files, for example, ‘ox-man.el’, for usage and configuration details.  -File: org.info, Node: Advanced Export Configuration, Next: Export in Foreign Buffers, Prev: Other Built-in Back-ends, Up: Exporting +File: org.info, Node: Advanced Export Configuration, Next: Export Region, Prev: Other Built-in Backends, Up: Exporting 13.17 Advanced Export Configuration =================================== @@ -13954,34 +14393,34 @@ Export hooks ------------ The export process executes two hooks before the actual exporting -begins. The first hook, ‘org-export-before-processing-hook’, runs +begins. The first hook, ‘org-export-before-processing-functions’, runs before any expansions of macros, Babel code, and include keywords in the -buffer. The second hook, ‘org-export-before-parsing-hook’, runs before -the buffer is parsed. +buffer. The second hook, ‘org-export-before-parsing-functions’, runs +before the buffer is parsed. Functions added to these hooks are called with a single argument: the -export back-end actually used, as a symbol. You may use them for heavy +export backend actually used, as a symbol. You may use them for heavy duty structural modifications of the document. For example, you can remove every headline in the buffer during export like this: (defun my-headline-removal (backend) "Remove all headlines in the current buffer. - BACKEND is the export back-end being used, as a symbol." + BACKEND is the export backend being used, as a symbol." (org-map-entries (lambda () (delete-region (point) (line-beginning-position 2)) ;; We need to tell `org-map-entries' to not skip over heading at - ;; point. Otherwise, it would continue from _next_ heading. See + ;; point. Otherwise, it would continue from _next_ heading. See ;; the docstring of `org-map-entries' for details. (setq org-map-continue-from (point))))) - (add-hook 'org-export-before-parsing-hook #'my-headline-removal) + (add-hook 'org-export-before-parsing-functions #'my-headline-removal) Filters ------- Filters are lists of functions to be applied to certain parts for a -given back-end. The output from the first function in the filter is +given backend. The output from the first function in the filter is passed on to the next function in the filter. The final output is the output from the final function in the filter. @@ -14010,8 +14449,8 @@ superscript table table-cell table-row target timestamp underline verbatim verse-block - Here is an example filter that replaces non-breaking spaces ‘ ’ in -the Org buffer with ‘~’ for the LaTeX back-end. + Here is an example filter that replaces non-breaking spaces ~ ~ in +the Org buffer with ‘~’ for the LaTeX backend. (defun my-latex-filter-nobreaks (text backend info) "Ensure \" \" are properly handled in LaTeX export." @@ -14022,15 +14461,15 @@ the Org buffer with ‘~’ for the LaTeX back-end. 'my-latex-filter-nobreaks) A filter requires three arguments: the code to be transformed, the -name of the back-end, and some optional information about the export +name of the backend, and some optional information about the export process. The third argument can be safely ignored. Note the use of -‘org-export-derived-backend-p’ predicate that tests for _latex_ back-end -or any other back-end, such as _beamer_, derived from _latex_. +‘org-export-derived-backend-p’ predicate that tests for _latex_ backend +or any other backend, such as _beamer_, derived from _latex_. Defining filters for individual files ------------------------------------- -The Org export can filter not just for back-ends, but also for specific +The Org export can filter not just for backends, but also for specific files through the ‘BIND’ keyword. Here is an example with two filters; one removes brackets from time stamps, and the other removes strike-through text. The filter functions are defined in a code block @@ -14044,24 +14483,164 @@ in the same Org file, which is a handy location for debugging. (defun tmp-f-strike-through (s backend info) "") #+END_SRC -Extending an existing back-end ------------------------------- +Summary of the export process +----------------------------- + +Org mode export is a multi-step process that works on a temporary copy +of the buffer. The export process consists of 4 major steps: + + 1. Process the temporary copy, making necessary changes to the buffer + text; + + 2. Parse the buffer, converting plain Org markup into an abstract + syntax tree (AST); + + 3. Convert the AST to text, as prescribed by the selected export + backend; + + 4. Post-process the resulting exported text. + +Process temporary copy of the source Org buffer (1): + + 1. Execute ‘org-export-before-processing-functions’ (see *note Export + hooks::); + + 2. Expand ‘#+include’ keywords in the whole buffer (see *note Include + Files::); + + 3. Remove commented subtrees in the whole buffer (see *note Comment + Lines::); + + 4. Replace macros in the whole buffer (see *note Macro Replacement::); + + 5. When ‘org-export-use-babel’ is non-nil (default), process code + blocks: + + • Leave code blocks inside archived subtrees (see *note Internal + archiving::) as is; + + • Evaluate all the other code blocks according to code block + headers (see *note Limit code block evaluation::); + + • Remove code, results of evaluation, both, or neither according + to ‘:exports’ header argument (see *note Exporting Code + Blocks::). + +Parse the temporary buffer, creating AST: + + 1. Execute ‘org-export-before-parsing-functions’ (see *note Export + hooks::). The hook functions may still modify the buffer; + + 2. Calculate export option values according to subtree-specific export + settings, in-buffer keywords, ‘#+BIND’ keywords, and buffer-local + and global customization. The whole buffer is considered; + + 3. When ‘org-org-with-cite-processors’ is non-nil (default), determine + contributing bibliographies and record them into export options + (see *note Citations::). The whole buffer is considered; + + 4. Execute ‘org-export-filter-options-functions’; + + 5. Parse the accessible portion of the temporary buffer to generate an + AST. The AST is a nested list of lists representing Org syntax + elements (see Org Element API + (https://orgmode.org/worg/dev/org-element-api.html) for more + details): + + (org-data ... + (heading + (section + (paragraph (plain-text) (bold (plain-text)))) + (heading) + (heading (section ...)))) + + Past this point, modifications to the temporary buffer no longer + affect the export; Org export works only with the AST; + + 6. Remove elements that are not exported from the AST: + + • Headings according to ‘SELECT_TAGS’ and ‘EXCLUDE_TAGS’ export + keywords; ‘task’, ‘inline’, ‘arch’ export options (see *note + Export Settings::); + + • Comments; + + • Clocks, drawers, fixed-width environments, footnotes, LaTeX + environments and fragments, node properties, planning lines, + property drawers, statistics cookies, timestamps, etc + according to ‘#+OPTIONS’ keyword (see *note Export + Settings::); + + • Table rows containing width and alignment markers, unless the + selected export backend changes ‘:with-special-rows’ export + option to non-nil (see *note Column Width and Alignment::); + + • Table columns containing recalc marks (see *note Advanced + features::). + + 7. Expand environment variables in file link AST nodes according to + the ‘expand-links’ export option (see *note Export Settings::); + + 8. Execute ‘org-export-filter-parse-tree-functions’. These functions + can modify the AST by side effects; + + 9. When ‘org-org-with-cite-processors’ is non-nil (default), replace + citation AST nodes and ‘#+print_bibliography’ keyword AST nodes as + prescribed by the selected citation export processor (see *note + Citation export processors::). + +Convert the AST to text by traversing the AST nodes, depth-first: + + 1. Convert the leaf nodes (without children) to text as prescribed by + “transcoders” in the selected export backend (2); + + 2. Pass the converted nodes through the corresponding export filters + (see *note Filters::); + + 3. Concatenate all the converted child nodes to produce parent node + contents; + + 4. Convert the nodes with children to text, passing the nodes + themselves and their exported contents to the corresponding + transcoders and then to the export filters (see *note Filters::). + +Post-process the exported text: + + 1. Post-process the converted AST, as prescribed by the export + backend. (3) This step usually adds generated content (like Table + of Contents) to the exported text; + + 2. Execute ‘org-export-filter-body-functions’; + + 3. Unless body-only export is selected (see *note The Export + Dispatcher::), add the necessary metadata to the final document, as + prescribed by the export backend. Examples: Document author/title; + HTML headers/footers; LaTeX preamble; + + 4. When ‘org-org-with-cite-processors’ is non-nil (default), add + bibliography metadata, as prescribed by the citation export + processor; + + 5. Execute ‘org-export-filter-final-output-functions’. + +Extending an existing backend +----------------------------- Some parts of the conversion process can be extended for certain elements so as to introduce a new or revised translation. That is how -the HTML export back-end was extended to handle Markdown format. The +the HTML export backend was extended to handle Markdown format. The extensions work seamlessly so any aspect of filtering not done by the -extended back-end is handled by the original back-end. Of all the -export customization in Org, extending is very powerful as it operates -at the parser level. +extended backend is handled by the original backend. Of all the export +customization in Org, extending is very powerful as it operates at the +parser level. - For this example, make the _ascii_ back-end display the language used + For this example, make the _ascii_ backend display the language used in a source code block. Also make it display only when some attribute is non-‘nil’, like the following: #+ATTR_ASCII: :language t - Then extend ASCII back-end with a custom “my-ascii” back-end. + Then extend ASCII backend with a custom “my-ascii” backend. (defun my-ascii-src-block (src-block contents info) "Transcode a SRC-BLOCK element from Org to ASCII. @@ -14081,75 +14660,70 @@ is non-‘nil’, like the following: :translate-alist '((src-block . my-ascii-src-block))) The ‘my-ascii-src-block’ function looks at the attribute above the -current element. If not true, hands over to _ascii_ back-end. If true, +current element. If not true, hands over to _ascii_ backend. If true, which it is in this example, it creates a box around the code and leaves room for the inserting a string for language. The last form creates the -new back-end that springs to action only when translating ‘src-block’ +new backend that springs to action only when translating ‘src-block’ type elements. - To use the newly defined back-end, evaluate the following from an Org + To use the newly defined backend, evaluate the following from an Org buffer: (org-export-to-buffer 'my-ascii "*Org MY-ASCII Export*") Further steps to consider would be an interactive function, self-installing an item in the export dispatcher menu, and other -user-friendly improvements. +user-friendly improvements. See + for more +details. + + ---------- Footnotes ---------- + + (1) Unless otherwise specified, each step of the export process only +operates on the accessible portion of the buffer. When subtree export +is selected (see *note The Export Dispatcher::), the buffer is narrowed +to the body of the selected subtree, so that the rest of the buffer +text, except export keywords, does not contribute to the export output. + + (2) See transcoders and ‘:translate-alist’ in the docstrings of +‘org-export-define-backend’ and ‘org-export-define-derived-backend’. + + (3) See ‘inner-template’ in the docstring of +‘org-export-define-backend’.  -File: org.info, Node: Export in Foreign Buffers, Prev: Advanced Export Configuration, Up: Exporting +File: org.info, Node: Export Region, Prev: Advanced Export Configuration, Up: Exporting -13.18 Export in Foreign Buffers -=============================== +13.18 Export Region +=================== -The export back-ends in Org often include commands to convert selected -regions. A convenient feature of this in-place conversion is that the -exported output replaces the original source. Here are such functions: +Some export backends include commands to convert a region of Org +formatted text to another format, such as HTML or LaTeX. The conversion +replaces the original source. Here are such commands: -‘org-ascii-convert-region-to-ascii’ +‘org-export-region-to-ascii’ Convert the selected region into ASCII. -‘org-ascii-convert-region-to-utf8’ +‘org-export-region-to-utf8’ Convert the selected region into UTF-8. -‘org-html-convert-region-to-html’ +‘org-export-region-to-html’ Convert the selected region into HTML. -‘org-latex-convert-region-to-latex’ +‘org-export-region-to-latex’ Convert the selected region into LaTeX. -‘org-texinfo-convert-region-to-texinfo’ +‘org-export-region-to-texinfo’ Convert the selected region into Texinfo. -‘org-md-convert-region-to-md’ +‘org-export-region-to-md’ Convert the selected region into Markdown. - In-place conversions are particularly handy for quick conversion of -tables and lists in foreign buffers. For example, in an HTML buffer, + The in-place conversion is particularly handy for quick conversion of +tables and lists in non-Org buffers. For example, in an HTML buffer, write a list in Org syntax, select it, and convert it to HTML with ‘M-x org-html-convert-region-to-html’. -* Menu: - -* Bare HTML:: Exporting HTML without CSS, Javascript, etc. - - -File: org.info, Node: Bare HTML, Up: Export in Foreign Buffers - -13.18.1 Exporting to minimal HTML ---------------------------------- - -If you want to output a minimal HTML file, with no CSS, no Javascript, -no preamble or postamble, here are the variable you would need to set: - - (setq org-html-head "" - org-html-head-extra "" - org-html-head-include-default-style nil - org-html-head-include-scripts nil - org-html-preamble nil - org-html-postamble nil - org-html-use-infojs nil) -  File: org.info, Node: Publishing, Next: Citation handling, Prev: Exporting, Up: Top @@ -14345,36 +14919,47 @@ Settings::), however, override everything. Generic properties .................. -‘:archived-trees’ ‘org-export-with-archived-trees’ -‘:exclude-tags’ ‘org-export-exclude-tags’ -‘:headline-levels’ ‘org-export-headline-levels’ -‘:language’ ‘org-export-default-language’ -‘:preserve-breaks’ ‘org-export-preserve-breaks’ -‘:section-numbers’ ‘org-export-with-section-numbers’ -‘:select-tags’ ‘org-export-select-tags’ -‘:with-author’ ‘org-export-with-author’ -‘:with-broken-links’ ‘org-export-with-broken-links’ -‘:with-clocks’ ‘org-export-with-clocks’ -‘:with-creator’ ‘org-export-with-creator’ -‘:with-date’ ‘org-export-with-date’ -‘:with-drawers’ ‘org-export-with-drawers’ -‘:with-email’ ‘org-export-with-email’ -‘:with-emphasize’ ‘org-export-with-emphasize’ -‘:with-fixed-width’ ‘org-export-with-fixed-width’ -‘:with-footnotes’ ‘org-export-with-footnotes’ -‘:with-latex’ ‘org-export-with-latex’ -‘:with-planning’ ‘org-export-with-planning’ -‘:with-priority’ ‘org-export-with-priority’ -‘:with-properties’ ‘org-export-with-properties’ -‘:with-special-strings’ ‘org-export-with-special-strings’ -‘:with-sub-superscript’ ‘org-export-with-sub-superscripts’ -‘:with-tables’ ‘org-export-with-tables’ -‘:with-tags’ ‘org-export-with-tags’ -‘:with-tasks’ ‘org-export-with-tasks’ -‘:with-timestamps’ ‘org-export-with-timestamps’ -‘:with-title’ ‘org-export-with-title’ -‘:with-toc’ ‘org-export-with-toc’ -‘:with-todo-keywords’ ‘org-export-with-todo-keywords’ +‘:author’ ‘user-full-name’ +‘:email’ ‘user-mail-address’ +‘:language’ ‘org-export-default-language’ +‘:select-tags’ ‘org-export-select-tags’ +‘:exclude-tags’ ‘org-export-exclude-tags’ +‘:creator’ ‘org-export-creator-string’ +‘:headline-levels’ ‘org-export-headline-levels’ +‘:preserve-breaks’ ‘org-export-preserve-breaks’ +‘:section-numbers’ ‘org-export-with-section-numbers’ +‘:time-stamp-file’ ‘org-export-timestamp-file’ +‘:with-archived-trees’ ‘org-export-with-archived-trees’ +‘:with-author’ ‘org-export-with-author’ +‘:expand-links’ ‘org-export-expand-links’ +‘:with-broken-links’ ‘org-export-with-broken-links’ +‘:with-clocks’ ‘org-export-with-clocks’ +‘:with-creator’ ‘org-export-with-creator’ +‘:with-date’ ‘org-export-with-date’ +‘:with-drawers’ ‘org-export-with-drawers’ +‘:with-email’ ‘org-export-with-email’ +‘:with-emphasize’ ‘org-export-with-emphasize’ +‘:with-entities’ ‘org-export-with-entities’ +‘:with-fixed-width’ ‘org-export-with-fixed-width’ +‘:with-footnotes’ ‘org-export-with-footnotes’ +‘:with-inlinetasks’ ‘org-export-with-inlinetasks’ +‘:with-latex’ ‘org-export-with-latex’ +‘:with-planning’ ‘org-export-with-planning’ +‘:with-priority’ ‘org-export-with-priority’ +‘:with-properties’ ‘org-export-with-properties’ +‘:with-smart-quotes’ ‘org-export-with-smart-quotes’ +‘:with-special-strings’ ‘org-export-with-special-strings’ +‘:with-statistics-cookies’ ‘org-export-with-statistics-cookies’ +‘:with-sub-superscript’ ‘org-export-with-sub-superscripts’ +‘:with-toc’ ‘org-export-with-toc’ +‘:with-tables’ ‘org-export-with-tables’ +‘:with-tags’ ‘org-export-with-tags’ +‘:with-tasks’ ‘org-export-with-tasks’ +‘:with-timestamps’ ‘org-export-with-timestamps’ +‘:with-title’ ‘org-export-with-title’ +‘:with-todo-keywords’ ‘org-export-with-todo-keywords’ +‘:with-cite-processors’ ‘org-export-process-citations’ +‘:cite-export’ ‘org-cite-export-processors’ ASCII specific properties ......................... @@ -14403,22 +14988,35 @@ ASCII specific properties Beamer specific properties .......................... -‘:beamer-theme’ ‘org-beamer-theme’ +‘:headline-levels’ ‘org-beamer-frame-level’ +‘:beamer-subtitle-format’ ‘org-beamer-subtitle-format’ ‘:beamer-column-view-format’ ‘org-beamer-column-view-format’ +‘:beamer-theme’ ‘org-beamer-theme’ ‘:beamer-environments-extra’ ‘org-beamer-environments-extra’ ‘:beamer-frame-default-options’ ‘org-beamer-frame-default-options’ ‘:beamer-outline-frame-options’ ‘org-beamer-outline-frame-options’ ‘:beamer-outline-frame-title’ ‘org-beamer-outline-frame-title’ -‘:beamer-subtitle-format’ ‘org-beamer-subtitle-format’ HTML specific properties ........................ +‘:html-doctype’ ‘org-html-doctype’ +‘:html-container’ ‘org-html-container-element’ +‘:html-content-class’ ‘org-html-content-class’ +‘:html-html5-fancy’ ‘org-html-html5-fancy’ +‘:html-link-use-abs-url’ ‘org-html-link-use-abs-url’ +‘:html-link-home’ ‘org-html-link-home’ +‘:html-link-up’ ‘org-html-link-up’ +‘:html-equation-reference-format’ ‘org-html-equation-reference-format’ +‘:html-postamble’ ‘org-html-postamble’ +‘:html-preamble’ ‘org-html-preamble’ +‘:html-head’ ‘org-html-head’ +‘:html-head-extra’ ‘org-html-head-extra’ +‘:html-head-include-default-style’ ‘org-html-head-include-default-style’ +‘:html-head-include-scripts’ ‘org-html-head-include-scripts’ ‘:html-allow-name-attribute-in-anchors’ ‘org-html-allow-name-attribute-in-anchors’ +‘:html-divs’ ‘org-html-divs’ ‘:html-checkbox-type’ ‘org-html-checkbox-type’ -‘:html-container’ ‘org-html-container-element’ -‘:html-divs’ ‘org-html-divs’ -‘:html-doctype’ ‘org-html-doctype’ ‘:html-extension’ ‘org-html-extension’ ‘:html-footnote-format’ ‘org-html-footnote-format’ ‘:html-footnote-separator’ ‘org-html-footnote-separator’ @@ -14426,36 +15024,23 @@ HTML specific properties ‘:html-format-drawer-function’ ‘org-html-format-drawer-function’ ‘:html-format-headline-function’ ‘org-html-format-headline-function’ ‘:html-format-inlinetask-function’ ‘org-html-format-inlinetask-function’ -‘:html-head-extra’ ‘org-html-head-extra’ -‘:html-head-include-default-style’ ‘org-html-head-include-default-style’ -‘:html-head-include-scripts’ ‘org-html-head-include-scripts’ -‘:html-head’ ‘org-html-head’ ‘:html-home/up-format’ ‘org-html-home/up-format’ -‘:html-html5-fancy’ ‘org-html-html5-fancy’ ‘:html-indent’ ‘org-html-indent’ ‘:html-infojs-options’ ‘org-html-infojs-options’ ‘:html-infojs-template’ ‘org-html-infojs-template’ ‘:html-inline-image-rules’ ‘org-html-inline-image-rules’ -‘:html-inline-images’ ‘org-html-inline-images’ -‘:html-link-home’ ‘org-html-link-home’ ‘:html-link-org-files-as-html’ ‘org-html-link-org-files-as-html’ -‘:html-link-up’ ‘org-html-link-up’ -‘:html-link-use-abs-url’ ‘org-html-link-use-abs-url’ ‘:html-mathjax-options’ ‘org-html-mathjax-options’ ‘:html-mathjax-template’ ‘org-html-mathjax-template’ -‘:html-equation-reference-format’ ‘org-html-equation-reference-format’ ‘:html-metadata-timestamp-format’ ‘org-html-metadata-timestamp-format’ ‘:html-postamble-format’ ‘org-html-postamble-format’ -‘:html-postamble’ ‘org-html-postamble’ ‘:html-preamble-format’ ‘org-html-preamble-format’ -‘:html-preamble’ ‘org-html-preamble’ +‘:html-prefer-user-labels’ ‘org-html-prefer-user-labels’ ‘:html-self-link-headlines’ ‘org-html-self-link-headlines’ -‘:html-table-align-individual-field’ ‘org-html-table-align-individual-fields’ -‘:html-table-attributes’ ‘org-html-table-default-attributes’ +‘:html-table-align-individual-fields’ ‘org-html-table-align-individual-fields’ ‘:html-table-caption-above’ ‘org-html-table-caption-above’ ‘:html-table-data-tags’ ‘org-html-table-data-tags’ ‘:html-table-header-tags’ ‘org-html-table-header-tags’ -‘:html-table-row-tags’ ‘org-html-table-row-tags’ ‘:html-table-use-header-tags-for-first-column’ ‘org-html-table-use-header-tags-for-first-column’ ‘:html-tag-class-prefix’ ‘org-html-tag-class-prefix’ ‘:html-text-markup-alist’ ‘org-html-text-markup-alist’ @@ -14464,20 +15049,31 @@ HTML specific properties ‘:html-use-infojs’ ‘org-html-use-infojs’ ‘:html-validation-link’ ‘org-html-validation-link’ ‘:html-viewport’ ‘org-html-viewport’ -‘:html-wrap-src-lines’ ‘org-html-wrap-src-lines’ +‘:html-inline-images’ ‘org-html-inline-images’ +‘:html-table-attributes’ ‘org-html-table-default-attributes’ +‘:html-table-row-open-tag’ ‘org-html-table-row-open-tag’ +‘:html-table-row-close-tag’ ‘org-html-table-row-close-tag’ ‘:html-xml-declaration’ ‘org-html-xml-declaration’ +‘:html-wrap-src-lines’ ‘org-html-wrap-src-lines’ +‘:html-klipsify-src’ ‘org-html-klipsify-src’ +‘:html-klipse-css’ ‘org-html-klipse-css’ +‘:html-klipse-js’ ‘org-html-klipse-js’ +‘:html-klipse-selection-script’ ‘org-html-klipse-selection-script’ +‘:creator’ ‘org-html-creator-string’ +‘:with-latex’ ‘org-html-with-latex’ LaTeX specific properties ......................... +‘:latex-class’ ‘org-latex-default-class’ ‘:latex-active-timestamp-format’ ‘org-latex-active-timestamp-format’ ‘:latex-caption-above’ ‘org-latex-caption-above’ ‘:latex-classes’ ‘org-latex-classes’ -‘:latex-class’ ‘org-latex-default-class’ -‘:latex-compiler’ ‘org-latex-compiler’ ‘:latex-default-figure-position’ ‘org-latex-default-figure-position’ ‘:latex-default-table-environment’ ‘org-latex-default-table-environment’ +‘:latex-default-quote-environment’ ‘org-latex-default-quote-environment’ ‘:latex-default-table-mode’ ‘org-latex-default-table-mode’ +‘:latex-default-footnote-command’ ‘org-latex-default-footnote-command’ ‘:latex-diary-timestamp-format’ ‘org-latex-diary-timestamp-format’ ‘:latex-engraved-options’ ‘org-latex-engraved-options’ ‘:latex-engraved-preamble’ ‘org-latex-engraved-preamble’ @@ -14488,6 +15084,7 @@ LaTeX specific properties ‘:latex-format-headline-function’ ‘org-latex-format-headline-function’ ‘:latex-format-inlinetask-function’ ‘org-latex-format-inlinetask-function’ ‘:latex-hyperref-template’ ‘org-latex-hyperref-template’ +‘:latex-image-default-scale’ ‘org-latex-image-default-scale’ ‘:latex-image-default-height’ ‘org-latex-image-default-height’ ‘:latex-image-default-option’ ‘org-latex-image-default-option’ ‘:latex-image-default-width’ ‘org-latex-image-default-width’ @@ -14495,20 +15092,22 @@ LaTeX specific properties ‘:latex-inactive-timestamp-format’ ‘org-latex-inactive-timestamp-format’ ‘:latex-inline-image-rules’ ‘org-latex-inline-image-rules’ ‘:latex-link-with-unknown-path-format’ ‘org-latex-link-with-unknown-path-format’ +‘:latex-src-block-backend’ ‘org-latex-src-block-backend’ ‘:latex-listings-langs’ ‘org-latex-listings-langs’ ‘:latex-listings-options’ ‘org-latex-listings-options’ +‘:latex-listings-src-omit-language’ ‘org-latex-listings-src-omit-language’ ‘:latex-minted-langs’ ‘org-latex-minted-langs’ ‘:latex-minted-options’ ‘org-latex-minted-options’ ‘:latex-prefer-user-labels’ ‘org-latex-prefer-user-labels’ ‘:latex-subtitle-format’ ‘org-latex-subtitle-format’ ‘:latex-subtitle-separate’ ‘org-latex-subtitle-separate’ -‘:latex-src-block-backend’ ‘org-latex-src-block-backend’ ‘:latex-table-scientific-notation’ ‘org-latex-table-scientific-notation’ ‘:latex-tables-booktabs’ ‘org-latex-tables-booktabs’ ‘:latex-tables-centered’ ‘org-latex-tables-centered’ ‘:latex-text-markup-alist’ ‘org-latex-text-markup-alist’ ‘:latex-title-command’ ‘org-latex-title-command’ ‘:latex-toc-command’ ‘org-latex-toc-command’ +‘:latex-compiler’ ‘org-latex-compiler’ Markdown specific properties ............................ @@ -14521,6 +15120,7 @@ Markdown specific properties ODT specific properties ....................... +‘:odt-styles-file’ ‘org-odt-styles-file’ ‘:odt-content-template-file’ ‘org-odt-content-template-file’ ‘:odt-display-outline-level’ ‘org-odt-display-outline-level’ ‘:odt-fontify-srcblocks’ ‘org-odt-fontify-srcblocks’ @@ -14530,29 +15130,29 @@ ODT specific properties ‘:odt-inline-formula-rules’ ‘org-odt-inline-formula-rules’ ‘:odt-inline-image-rules’ ‘org-odt-inline-image-rules’ ‘:odt-pixels-per-inch’ ‘org-odt-pixels-per-inch’ -‘:odt-styles-file’ ‘org-odt-styles-file’ ‘:odt-table-styles’ ‘org-odt-table-styles’ ‘:odt-use-date-fields’ ‘org-odt-use-date-fields’ +‘:with-latex’ ‘org-odt-with-latex’ Texinfo specific properties ........................... -‘:texinfo-active-timestamp-format’ ‘org-texinfo-active-timestamp-format’ -‘:texinfo-classes’ ‘org-texinfo-classes’ ‘:texinfo-class’ ‘org-texinfo-default-class’ -~:texinfo-compact-itemx ‘org-texinfo-compact-itemx’ -‘:texinfo-table-default-markup’ ‘org-texinfo-table-default-markup’ -‘:texinfo-diary-timestamp-format’ ‘org-texinfo-diary-timestamp-format’ -‘:texinfo-filename’ ‘org-texinfo-filename’ -‘:texinfo-format-drawer-function’ ‘org-texinfo-format-drawer-function’ +‘:texinfo-classes’ ‘org-texinfo-classes’ ‘:texinfo-format-headline-function’ ‘org-texinfo-format-headline-function’ -‘:texinfo-format-inlinetask-function’ ‘org-texinfo-format-inlinetask-function’ +‘:texinfo-node-description-column’ ‘org-texinfo-node-description-column’ +‘:texinfo-active-timestamp-format’ ‘org-texinfo-active-timestamp-format’ ‘:texinfo-inactive-timestamp-format’ ‘org-texinfo-inactive-timestamp-format’ +‘:texinfo-diary-timestamp-format’ ‘org-texinfo-diary-timestamp-format’ ‘:texinfo-link-with-unknown-path-format’ ‘org-texinfo-link-with-unknown-path-format’ -‘:texinfo-node-description-column’ ‘org-texinfo-node-description-column’ -‘:texinfo-table-scientific-notation’ ‘org-texinfo-table-scientific-notation’ ‘:texinfo-tables-verbatim’ ‘org-texinfo-tables-verbatim’ +‘:texinfo-table-scientific-notation’ ‘org-texinfo-table-scientific-notation’ +‘:texinfo-table-default-markup’ ‘org-texinfo-table-default-markup’ ‘:texinfo-text-markup-alist’ ‘org-texinfo-text-markup-alist’ +‘:texinfo-format-drawer-function’ ‘org-texinfo-format-drawer-function’ +‘:texinfo-format-inlinetask-function’ ‘org-texinfo-format-inlinetask-function’ +‘:texinfo-compact-itemx’ ‘org-texinfo-compact-itemx’ +‘:with-latex’ ‘org-texinfo-with-latex’  File: org.info, Node: Publishing links, Next: Site map, Prev: Publishing options, Up: Configuration @@ -14606,6 +15206,11 @@ files for a given project. ‘:sitemap-title’ Title of sitemap page. Defaults to name of file. +‘:sitemap-style’ + Can be ‘list’ (site-map is just an itemized list of the titles of + the files involved) or ‘tree’ (the directory structure of the + source files is reflected in the site-map). Defaults to ‘tree’. + ‘:sitemap-format-entry’ With this option one can tell how a site-map entry is formatted in the site-map. It is a function called with three arguments: the @@ -14643,19 +15248,6 @@ files for a given project. ‘:sitemap-ignore-case’ Should sorting be case-sensitive? Default ‘nil’. -‘:sitemap-file-entry-format’ - With this option one can tell how a sitemap’s entry is formatted in - the sitemap. This is a format string with some escape sequences: - ‘%t’ stands for the title of the file, ‘%a’ stands for the author - of the file and ‘%d’ stands for the date of the file. The date is - retrieved with the ‘org-publish-find-date’ function and formatted - with ‘org-publish-sitemap-date-format’. Default ‘%t’. - -‘:sitemap-date-format’ - Format string for the ‘format-time-string’ function that tells how - a sitemap entry’s date is to be formatted. This property bypasses - ‘org-publish-sitemap-date-format’ which defaults to ‘%Y-%m-%d’. -  File: org.info, Node: Generating an index, Prev: Site map, Up: Configuration @@ -14774,12 +15366,12 @@ You can accomplish this by setting up an ‘images/’ folder in the right place on the web server, and publishing images to it. (setq org-publish-project-alist - '(("orgfiles" + `(("orgfiles" :base-directory "~/org/" :base-extension "org" :publishing-directory "/ssh:user@host:~/html/notebook/" :publishing-function org-html-publish-to-html - :exclude "PrivatePage.org" ;; regexp + :exclude ,(rx (or "PrivateFile.org" (seq line-start "private/"))) ;; regexp :headline-levels 3 :section-numbers nil :with-toc nil @@ -14834,9 +15426,57 @@ File: org.info, Node: Citation handling, Next: Working with Source Code, Prev 15 Citation handling ******************** -The ‘oc.el’ library provides tooling to handle citations in Org via -“citation processors” that offer some or all of the following -capabilities: +While links (see *note Hyperlinks::) are often sufficient to refer to +external or internal information from Org, they have their limitations +when referring to multiple targets or typesetting printed publications. + + Org mode provides a more sophisticated markup to “cite” external +resources. For example, consider the following Org mode snippet + + #+bibliography: citationdata.bib + + Org mode is used by various communities [cite:teaching: @orgteaching; + and TeX: @orgtex]. [cite/author/caps:@orgtex] uses Org mode to simplify + writing scientific publications, while [cite/author/caps:@orgteaching] + experiment with Org babel to improve teaching. + + #+print_bibliography: + + Org mode will gather citation metadata from the ‘#+bibliography’ +database and use it to typeset the exported document in arbitrary +formats. For example, the snippet below shows ASCII export output. + + Org mode is used by various communities (teaching: Birkenkrahe, Marcus, + 2023, and TeX: Somma, Emmanuele F, 2023). Somma, Emmanuele F uses Org + mode to simplify writing scientific publications, while Birkenkrahe, + Marcus experiment with Org babel to improve teaching. + + Birkenkrahe, Marcus (2023). /Teaching Data Science with Literate + Programming Tools/, MDPI. + + Somma, Emmanuele F (2023). /Simplifying LaTeX with ORG-mode in Emacs/, + TUGboat volume. + + In addition to export, users can use completion to search and insert +citations from the bibliography (via ‘org-cite-insert’). Citations also +act like ordinary links, jumping to the citation metadata when +“following” them using ‘org-open-at-point’. + + You can customize every aspect (_capability_) of citation handling +using built-in or external _citation processors_. + + Org mode ships with several built-in citation processors tailored to +work with LaTeX export and BibTeX bibliographies (‘bibtex’, ‘biblatex’, +and ‘natbib’ processors), or with more generic formats described using +Citation Style Language (https://citationstyles.org/) (‘csl’ processor). +The default citation processor is ‘basic’ - it works with arbitrary +export formats and recognizes both BibTeX and CSL bibliographies. More +citation processors are distributed as Emacs packages. + + Multiple citation processors can be mixed to meet your preferences. +Configure ‘org-cite-activate-processor’, ‘org-cite-follow-processor’, +‘org-cite-insert-processor’, and ‘org-cite-export-processors’ to select +which processor to use for every citation capability: activate Fontification, tooltip preview, etc. @@ -14847,16 +15487,6 @@ insert export Via different libraries for different target formats. - To use a “citation processor”, the user must load them; for example; - - (require 'oc-bibtex) - - They can then configure them with ‘org-cite-activate-processor’, -‘org-cite-follow-processor’, ‘org-cite-insert-processor’, and -‘org-cite-export-processors’ respectively. - - The included “basic” processor provides all four capabilities. - * Menu: * Citations:: @@ -14877,6 +15507,9 @@ more “bibliography” keywords. #+bibliography: /some/other/file.json #+bibliography: "/some/file/with spaces/in its name.bib" + Org mode uses all the local and global bibliographies combined to +search for citation keys. + One can then insert and edit citations using ‘org-cite-insert’, called with ‘C-c C-x @’. @@ -14887,20 +15520,39 @@ identifying a reference in the bibliography. • Each key starts with the character ‘@’. + [cite:@key] + • Each key can be qualified by a _prefix_ (e.g. “see ”) and/or a _suffix_ (e.g. “p. 123”), giving information useful or necessary for the comprehension of the citation but not included in the reference. + [cite:see @key p. 123] + • 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. + [cite:@key1;@key2;@key3] + • 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 usually makes sense only for the author-year styles. - [cite/style:common prefix ;prefix @key suffix; ... ; common suffix] + [cite/style:common prefix ;prefix @key suffix; ... ; common suffix] + + When ‘style’ is not specified, one of the two default styles are + used + + • either the default style specified in the ‘CITE_EXPORT’ + keyword (see *note Citation export processors::) + + #+cite_export: basic numeric noauthor/bare + [cite:@key] is the same as [cite/noauthor/bare:@key] + + • or, if ‘CITE_EXPORT’ is not set, using the default ‘nil’ style + + [cite:@key] is the same as [cite/nil:@key] The only mandatory elements are: @@ -14951,18 +15603,18 @@ Org currently includes the following export processors: 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) + The ‘CITE_EXPORT’ keyword specifies the export processor, citation +style, and bibliography style; for example (all arguments are optional) - #+cite_export: basic author author-year + #+cite_export: [export processor name] [bibliography style] [default citation style] + #+cite_export: basic author-year author -specifies the “basic” export processor with citations inserted as +specifies the ‘basic’ export processor with citations inserted as author’s name and references indexed by author’s names and year; #+cite_export: csl /some/path/to/vancouver-brackets.csl -specifies the “csl” processor and CSL style, which in this case defines +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; @@ -14974,6 +15626,20 @@ 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. + #+cite_export: biblatex numeric,backend=bibtex + +specifies the ‘biblatex’ export processor with the default ‘numeric’ +style and the ‘bibtex’ backend. Always define the style first and then +the rest of load-time options for the ‘biblatex’ package. +Alternatively, you can use the ‘key=val,key=val’ format for the options +as documented in the ‘biblatex’ package documentation: + + #+cite_export: biblatex backend=bibtex,style=numeric + + The ‘org-cite-biblatex-options’ variable in your Emacs configuration +uses this format. It will only export to PDF, since it relies on the +‘biblatex’ processor of your LaTeX installation. +  File: org.info, Node: Bibliography printing, Prev: Citation export processors, Up: Citation handling @@ -14986,8 +15652,8 @@ be printed (note the colon): #+print_bibliography: The bibliography printed by the LaTeX-based export processors -“bibtex”, “natbib” and “biblatex” has a chapter or section heading by -default, while the “basic” and “csl” processors print the list of +‘bibtex’, ‘natbib’ and ‘biblatex’ has a chapter or section heading by +default, while the ‘basic’ and ‘csl’ processors print the list of bibliography entries without a heading. A document may contain more than one ‘PRINT_BIBLIOGRAPHY’ keywords. @@ -15002,29 +15668,30 @@ support passing options. * Menu: -* Bibliography options in the ``biblatex'' and ``csl'' export processors:: +* Bibliography options in the biblatex and csl export processors::  -File: org.info, Node: Bibliography options in the ``biblatex'' and ``csl'' export processors, Up: Bibliography printing +File: org.info, Node: Bibliography options in the biblatex and csl export processors, Up: Bibliography printing -15.3.1 Bibliography options in the “biblatex” and “csl” export processors +15.3.1 Bibliography options in the ‘biblatex’ and ‘csl’ export processors ------------------------------------------------------------------------- -The “biblatex” and “csl” export processors support bibliography options +The ‘biblatex’ and ‘csl’ export processors support bibliography options through a property list attached to the ‘PRINT_BIBLIOGRAPHY’ keyword. For example, - #print_bibliography: :keyword algebra :type book + #+print_bibliography: :keyword algebra :type book Values including spaces must be surrounded with double quotes. If you need to use a key multiple times, you can separate its values with commas, but without any space in-between: - #print_bibliography: :keyword "algebraic logic" :nottype article,book + #+print_bibliography: :keyword "algebraic logic" :nottype article,book - The “biblatex” export processor accepts all options supported by -BibLaTeX’s ‘\printbibliography’ command, while the “csl” processor -accepts the following ones: + The ‘biblatex’ export processor accepts all options supported by +BibLaTeX’s ‘\printbibliography’ command. + + The ‘csl’ processor accepts the following options: ‘:keyword ’ Print only entries whose keyword field contains all given keywords. @@ -15130,8 +15797,8 @@ designed for source code in that language. or more source files—a process known as _tangling_ in literate programming terminology. - For exporting and publishing, Org’s back-ends can format a source -code block appropriately, often with native syntax highlighting. + For exporting and publishing, Org’s backends can format a source code +block appropriately, often with native syntax highlighting. For executing and compiling a source code block, the user can configure Org to select the appropriate compiler. Org provides @@ -15197,7 +15864,8 @@ or table formulas (see *note The Spreadsheet::) can use the name to reference a source block. This naming serves the same purpose as naming Org tables. Org mode requires unique names. For duplicate - names, Org mode’s behavior is undefined. + names, Org mode’s behavior is undefined. Inline code blocks cannot + have a name. ‘#+BEGIN_SRC’ ... ‘#+END_SRC’ Mandatory. They mark the start and end of a block that Org @@ -15205,10 +15873,17 @@ or described next. ‘’ - Mandatory. It is the identifier of the source code language in the + Optional. It is the identifier of the source code language in the block. See *note Languages::, for identifiers of supported languages. + When ‘’ identifier is omitted, the block also cannot have + ‘’ and ‘
’. + + Language identifier is also used to fontify code blocks in Org + buffers, when ‘org-src-fontify-natively’ is set to non-‘nil’. See + *note Editing Source Code::. + ‘’ Optional. Switches provide finer control of the code execution, export, and format (see the discussion of switches in *note Literal @@ -15431,6 +16106,10 @@ to separate the filename from the reference. :var NAME=FILE:REFERENCE + When ‘FILE’ does not exist, the reference is searched in the current +file, using the verbatim reference. This way, ‘:var table=tbl:example’ +will be searched inside the current buffer. + Here are examples of passing values by reference: table @@ -15459,9 +16138,9 @@ table names—because the second row is a horizontal rule—then Org removes the column names, processes the table, puts back the column names, and then writes the table to the results block. Using ‘yes’, Org - does the same to the first row, even if the initial table does not - contain any horizontal rule. When set to ‘no’, Org does not - pre-process column names at all. + does the same to the first non-hline row, even if the initial table + does not contain any horizontal rule. When set to ‘no’, Org does + not pre-process column names at all. #+NAME: less-cols | a | @@ -15470,7 +16149,7 @@ table | c | #+BEGIN_SRC python :var tab=less-cols :colnames nil - return [[val + '*' for val in row] for row in tab] + return [[val + '*' for val in row] for row in tab] #+END_SRC #+RESULTS: @@ -15492,7 +16171,7 @@ table | two | 6 | 7 | 8 | 9 | 10 | #+BEGIN_SRC python :var tab=with-rownames :rownames yes - return [[val + 10 for val in row] for row in tab] + return [[val + 10 for val in row] for row in tab] #+END_SRC #+RESULTS: @@ -15535,6 +16214,7 @@ code block without arguments code block with arguments A code block name, as assigned by ‘NAME’ keyword, followed by parentheses and optional arguments passed within the parentheses. + The block is evaluated with point at its location. #+NAME: double #+BEGIN_SRC emacs-lisp :var input=8 @@ -16038,7 +16718,7 @@ Languages::. #+NAME: no-hline #+BEGIN_SRC python :var tab=many-cols :hlines no - return tab + return tab #+END_SRC #+RESULTS: no-hline @@ -16048,7 +16728,7 @@ Languages::. #+NAME: hlines #+BEGIN_SRC python :var tab=many-cols :hlines yes - return tab + return tab #+END_SRC #+RESULTS: hlines @@ -16087,6 +16767,9 @@ Languages::. extension from the ‘file-ext’ header argument. In that case, both the name and the extension are mandatory. + Result can also be interpreted as path to file. See ‘:results + link’. + #+name: circle #+BEGIN_SRC asymptote :results value file :file-ext pdf size(2cm); @@ -16119,14 +16802,19 @@ Format pertains to the type of the result returned by the code block. Choose one of the options; they are mutually exclusive. The default follows from the type specified above. +‘raw’ + Interpreted as raw Org mode. Inserted directly into the buffer. + Aligned if it is a table. Usage example: ‘:results value raw’. + ‘code’ Result enclosed in a code block. Useful for parsing. Usage example: ‘:results value code’. ‘drawer’ - Result wrapped in a ‘RESULTS’ drawer. Useful for containing ‘raw’ - or ‘org’ results for later scripting and automated processing. - Usage example: ‘:results value drawer’. + Results are added directly to the Org file as with ‘raw’, but are + wrapped in a ‘RESULTS’ drawer or results macro (for inline code + blocks), for later scripting and automated processing. Usage + example: ‘:results value drawer’. ‘html’ Results enclosed in a ‘BEGIN_EXPORT html’ block. Usage example: @@ -16151,6 +16839,9 @@ follows from the type specified above. #+RESULTS: [[file:org-mode-unicorn.svg]] + If ‘:file’ header argument is omitted, interpret source block + result as the file path. + ‘org’ Results enclosed in a ‘BEGIN_SRC org’ block. For comma-escape, either ‘’ in the block, or export the file. Usage example: @@ -16161,10 +16852,6 @@ follows from the type specified above. block. Languages supported: Emacs Lisp, Python, and Ruby. Usage example: ‘:results value pp’. -‘raw’ - Interpreted as raw Org mode. Inserted directly into the buffer. - Aligned if it is a table. Usage example: ‘:results value raw’. - The ‘wrap’ header argument unconditionally marks the results block by appending strings to ‘#+BEGIN_’ and ‘#+END_’. If no string is specified, Org wraps the results in a ‘#+BEGIN_results’ ... @@ -16205,7 +16892,7 @@ options; they are mutually exclusive. but no processing is performed on the return value. Calling the code block programmatically (see *note How to evaluate source code::) or by reference (see *note Passing arguments:: and *note - Noweb Reference Syntax::) will always yield nil. + Noweb Reference Syntax::) will always yield ‘nil’. ‘append’ Append results to the Org buffer. Latest results are at the @@ -16584,6 +17271,9 @@ group ‘org-edit-structure’. edit buffer uses that major mode. Use this variable to arbitrarily map language identifiers to major modes. + When language identifier is omitted in the src block, Org mode’s + behavior is undefined. + ‘org-src-window-setup’ For specifying Emacs window arrangement when the new edit buffer is created. @@ -16600,13 +17290,16 @@ group ‘org-edit-structure’. When ‘nil’, Org returns to the edit buffer without further prompts. The default prompts for a confirmation. - Set ‘org-src-fontify-natively’ to non-‘nil’ to turn on native code -fontification in the _Org_ buffer. Fontification of code blocks can -give visual separation of text and code on the display page. To further -customize the appearance of ‘org-block’ for specific languages, -customize ‘org-src-block-faces’. The following example shades the -background of regular blocks, and colors source blocks only for Python -and Emacs Lisp languages. + Fontification of code blocks can give visual separation of text and +code on the display page. Set ‘org-src-fontify-natively’ to non-‘nil’ +to turn on native code fontification in the _Org_ buffer. The +fontification follows the major mode used to edit the code block (see +‘org-src-lang-modes’ above). + + To further customize the appearance of ‘org-block’ for specific +languages, customize ‘org-src-block-faces’. The following example +shades the background of regular blocks, and colors source blocks only +for Python and Emacs Lisp languages. (require 'color) (set-face-attribute 'org-block nil :background @@ -16688,6 +17381,9 @@ the second code block is expanded as (reverse sentence) #+END_SRC + Note that noweb expansion does not automatically carry over ‘:var’ +header arguments(2). + You may also include the contents of multiple blocks sharing a common ‘noweb-ref’ header argument, which can be set at the file, subtree, or code block level. In the example Org file shown next, the body of the @@ -16721,9 +17417,9 @@ file when tangled. To use a different separator, edit the ‘noweb-sep’ header argument. Alternatively, Org can include the results of evaluation of a single -code block rather than its body. Evaluation occurs when parentheses, -possibly including arguments, are appended to the code block name, as -shown below. +code block rather than its body [(3). Evaluation occurs when +parentheses, possibly including arguments, are appended to the code +block name, as shown below. <> @@ -16737,7 +17433,7 @@ Given: #+NAME: some-code #+BEGIN_SRC python :var num=0 :results output :exports none - print(num*10) + print(num*10) #+END_SRC this code block: @@ -16795,21 +17491,21 @@ exported code snippets. With: #+NAME: if-true #+BEGIN_SRC python :exports none - print('do things when true') + print('do things when true') #+end_src #+name: if-false #+begin_src python :exports none - print('do things when false') + print('do things when false') #+end_src this code block: #+begin_src python :noweb yes :results output - if true: - <> - else: - <> + if true: + <> + else: + <> #+end_src expands to: @@ -16843,6 +17539,27 @@ can preview the results with the following command: (1) For noweb literate programming details, see . + (2) In the following example, attempting to evaluate the second code +block will give an error, because the variables defined in the first +code block will not be defined in the second block. + #+NAME: get-prompt + #+BEGIN_SRC emacs-lisp :var prompt="root> " :var command="ls" + (concat prompt command) + #+END_SRC + #+RESULTS: get-prompt + : root> ls + #+BEGIN_SRC emacs-lisp :noweb yes + <> + #+END_SRC + The previous block is expanded without setting ‘prompt’ and ‘command’ +values. + #+BEGIN_SRC emacs-lisp + (concat prompt command) + #+END_SRC + + (3) The reference is evaluated with point at the referenced block, +using its header arguments (including inherited) +  File: org.info, Node: Library of Babel, Next: Key bindings and Useful Functions, Prev: Noweb Reference Syntax, Up: Working with Source Code @@ -16955,6 +17672,7 @@ File: org.info, Node: Miscellaneous, Next: Hacking, Prev: Working with Source * Protocols:: External access to Emacs and Org. * Org Crypt:: Encrypting Org files. * Org Mobile:: Viewing and capture on a mobile device. +* Drag and Drop & yank-media:: Dropping and pasting files and images  File: org.info, Node: Completion, Next: Structure Templates, Up: Miscellaneous @@ -17338,14 +18056,18 @@ and reopening the Org file in Emacs also activates the changes. ‘#+SETUPFILE: file’ The setup file or a URL pointing to such file is for additional in-buffer settings. Org loads this file and parses it for any - settings in it only when Org opens the main file. If URL is - specified, the contents are downloaded and stored in a temporary - file cache. ‘C-c C-c’ on the settings line parses and loads the - file, and also resets the temporary file cache. Org also parses - and loads the document during normal exporting process. Org parses - the contents of this document as if it was included in the buffer. - It can be another Org file. To visit the file—not a URL—use ‘C-c - '’ while point is on the line with the file name. + settings in it when Org opens the main file. If URL is specified, + the contents are downloaded and stored in a temporary file cache. + ‘C-c C-c’ on the settings line re-parses and re-loads the file, and + also resets the temporary file cache. + + Org also parses and loads _in-buffer settings_ from the setup file + during normal exporting process. Org parses the _in-buffer + settings_ as if it was included in the containing Org buffer. The + rest of the contents of setup file is ignored. + + To visit the setup file—not a URL—use ‘C-c '’ while point is on the + line with the setup file name. ‘#+STARTUP:’ Startup options Org uses when first visiting a file. @@ -17394,6 +18116,16 @@ and reopening the Org file in Emacs also activates the changes. ‘inlineimages’ Show inline images. ‘noinlineimages’ Do not show inline images on startup. + Bracket links in Org buffers are displayed hiding the link path and + brackets. For example, ‘[[https://orgmode.org][Org Website]]’ is, + by default, displayed as “Org Website”, hiding the link itself and + just displaying its description. Alternatively, the links can be + displayed in full. The corresponding variable is + ‘org-link-descriptive’. + + ‘descriptivelinks’ Hide path and brackets in links. + ‘literallinks’ Do not hide anything. + Logging the closing and reopening of TODO items and clock intervals can be configured using these options (see variables ‘org-log-done’, ‘org-log-note-clock-out’, and ‘org-log-repeat’). @@ -17429,8 +18161,8 @@ and reopening the Org file in Emacs also activates the changes. ‘oddeven’ Allow all outline levels. To turn on custom format overlays over timestamps (variables - ‘org-put-time-stamp-overlays’ and - ‘org-time-stamp-overlay-formats’), use: + ‘org-display-custom-times’ and ‘org-timestamp-custom-formats’), + use: ‘customtime’ Overlay custom time format. @@ -17452,6 +18184,7 @@ and reopening the Org file in Emacs also activates the changes. ‘fnconfirm’ Offer automatic label for editing or confirmation. ‘fnadjust’ Automatically renumber and sort footnotes. ‘nofnadjust’ Do not renumber and sort automatically. + ‘fnanon’ Create anonymous footnotes with ‘org-footnote-new’. To hide blocks or drawers on startup, use these keywords. The corresponding variables are ‘org-hide-block-startup’ and @@ -17506,12 +18239,11 @@ File: org.info, Node: Org Syntax, Next: Documentation Access, Prev: Regular E ================ A reference document providing a formal description of Org’s syntax is -available as a draft on Worg -(https://orgmode.org/worg/dev/org-syntax.html), written and maintained -by Nicolas Goaziou. It defines Org’s core internal concepts such as -“headlines”, “sections”, “affiliated keywords”, “(greater) elements” and -“objects”. Each part of an Org document belongs to one of the previous -categories. +available as a draft on Worg (https://orgmode.org/worg/org-syntax.html), +initially written by Nicolas Goaziou. It defines Org’s core internal +concepts such as “headlines”, “sections”, “affiliated keywords”, +“(greater) elements” and “objects”. Each part of an Org document +belongs to one of the previous categories. To explore the abstract structure of an Org buffer, run this in a buffer: @@ -17669,9 +18401,9 @@ File: org.info, Node: Cooperation, Next: Conflicts, Up: Interaction also use calculation suffixes for units, such as ‘M’ for ‘Mega’. For a standard collection of such constants, install the ‘constants’ package. Install version 2.0 of this package, - available at . Org checks - if the function ‘constants-get’ has been autoloaded. Installation - instructions are in the file ‘constants.el’. + available at . + Org checks if the function ‘constants-get’ has been autoloaded. + Installation instructions are in the file ‘constants.el’. ‘cdlatex.el’ by Carsten Dominik @@ -17690,6 +18422,10 @@ File: org.info, Node: Cooperation, Next: Conflicts, Up: Interaction By default the index is two levels deep—you can modify the depth using the option ‘org-imenu-depth’. + Org activates Imenu support only in the buffers opened after + loading Imenu library. To enable Imenu support in an already + opened Org buffer, reload Org. + ‘speedbar.el’ by Eric M. Ludlam Speedbar package creates a special Emacs frame for displaying files @@ -17851,6 +18587,7 @@ Default Alternative 1 Speed key Alternative 2 ‘S-’ ‘C-c ’ ‘C-S-’ ‘C-c C-x ’ ‘C-S-’ ‘C-c C-x ’ +‘C-c C-,’ ‘C-c C-x s’  File: org.info, Node: Protocols, Next: Org Crypt, Prev: TTY Keys, Up: Miscellaneous @@ -18023,8 +18760,9 @@ adding ‘:rewrites’ rules like this: ("example.com/$" . "index.php"))))) Since ‘example.com/$’ is used as a regular expression, it maps -‘http://example.com/’, ‘https://example.com’, ‘http://www.example.com/’ -and similar to ‘/home/user/example/index.php’. +‘https://example.com/’, ‘https://example.com’, +‘https://www.example.com/’ and similar to +‘/home/user/example/index.php’. The ‘:rewrites’ rules are searched as a last resort if and only if no existing file name is matched. @@ -18077,15 +18815,15 @@ specifying the respective key as property ‘CRYPTKEY’, e.g.: :CRYPTKEY: 0x0123456789012345678901234567890123456789 :END: - Note that ‘CRYPTKEY’ property is only effective when ‘org-crypt-key’ -is set to non-nil. ‘nil’ value of ‘org-crypt-key’ makes Org use + Note that the ‘CRYPTKEY’ property is only effective when +‘org-crypt-key’ is non-‘nil’. If ‘org-crypt-key’ is ‘nil’, Org uses symmetric encryption unconditionally. Excluding the ‘crypt’ tag from inheritance prevents already encrypted text from being encrypted again.  -File: org.info, Node: Org Mobile, Prev: Org Crypt, Up: Miscellaneous +File: org.info, Node: Org Mobile, Next: Drag and Drop & yank-media, Prev: Org Crypt, Up: Miscellaneous 17.18 Org Mobile ================ @@ -18236,6 +18974,46 @@ pull again. (1) The file will be empty after this operation. + +File: org.info, Node: Drag and Drop & yank-media, Prev: Org Mobile, Up: Miscellaneous + +17.19 Drag and Drop & ‘yank-media’ +================================== + +Org mode supports drag and drop (DnD) of files. By default, Org asks +the user what must be done with the dropped file: attach it, insert +‘file:’ link, or open the file. Customize ‘org-yank-dnd-method’ to set +the default DnD action. + + When DnD method is “attach”, Org mode first consults DnD metadata to +decide the attach method. For example, when file/files are dragged from +a file manager, Org may attach by copying or by moving. + + If Org cannot figure out which attachment method to use from the +metadata, it defaults to ‘org-yank-dnd-default-attach-method’ (1) + + Starting from Emacs 29, Org mode supports ‘yank-media’ command to +yank images from the clipboard and files from a file manager. + + When yanking images from clipboard, Org saves the image on disk and +inserts the image link to Org buffer. Images are either saved as +attachments to heading (default) or to a globally defined directory. +The save location is controlled by ‘org-yank-image-save-method’. + + The yanked images are saved under automatically generated name. You +can customize ‘org-yank-image-file-name-function’ to make Org query the +image names or change the naming scheme. + + When yanking files copied from a file manager, Org respects the value +of ‘org-yank-dnd-method’. Image files pasted this way also respect the +value of ‘org-yank-image-save-method’ when the action to perform is +‘attach’. + + ---------- Footnotes ---------- + + (1) By default, ‘org-yank-dnd-default-attach-method’ is set to nil – +use the same value as ‘org-attach-method’ (‘cp’ by default). +  File: org.info, Node: Hacking, Next: History and Acknowledgments, Prev: Miscellaneous, Up: Top @@ -18250,7 +19028,7 @@ Org. * Hooks:: How to reach into Org’s internals. * Add-on Packages:: Available extensions. * Adding Hyperlink Types:: New custom link types. -* Adding Export Back-ends:: How to write new export back-ends. +* Adding Export Backends:: How to write new export backends. * Tables in Arbitrary Syntax:: Orgtbl for LaTeX and other programs. * Dynamic Blocks:: Automatically filled blocks. * Special Agenda Views:: Customized views. @@ -18265,10 +19043,9 @@ File: org.info, Node: Hooks, Next: Add-on Packages, Up: Hacking A.1 Hooks ========= -Org has a large number of hook variables for adding functionality. This -appendix illustrates using a few. A complete list of hooks with -documentation is maintained by the Worg project at -. +Org has a large number of hook variables for adding functionality. A +complete list of hooks with documentation is maintained by the Worg +project at .  File: org.info, Node: Add-on Packages, Next: Adding Hyperlink Types, Prev: Hooks, Up: Hacking @@ -18283,7 +19060,7 @@ now hosted in a separate ‘org-contrib’ repository here is at: .  -File: org.info, Node: Adding Hyperlink Types, Next: Adding Export Back-ends, Prev: Add-on Packages, Up: Hacking +File: org.info, Node: Adding Hyperlink Types, Next: Adding Export Backends, Prev: Add-on Packages, Up: Hacking A.3 Adding Hyperlink Types ========================== @@ -18314,7 +19091,7 @@ The following ‘ol-man.el’ file implements it PATH should be a topic that can be thrown at the man command." (funcall org-man-command path)) - (defun org-man-store-link () + (defun org-man-store-link (&optional _interactive?) "Store a link to a man page." (when (memq major-mode '(Man-mode woman-mode)) ;; This is a man page, we do make this link. @@ -18365,7 +19142,10 @@ A review of ‘ol-man.el’: For example, ‘org-man-store-link’ is responsible for storing a link when ‘org-store-link’ (see *note Handling Links::) is called from a - buffer displaying a man page. It first checks if the major mode is + buffer displaying a man page. It is passed an argument + ‘interactive?’ which this function does not use, but other store + functions use to behave differently when a link is stored + interactively by the user. It first checks if the major mode is appropriate. If check fails, the function returns ‘nil’, which means it isn’t responsible for creating a link to the current buffer. Otherwise the function makes a link string by combining @@ -18374,36 +19154,35 @@ A review of ‘ol-man.el’: into an Org buffer later on.  -File: org.info, Node: Adding Export Back-ends, Next: Tables in Arbitrary Syntax, Prev: Adding Hyperlink Types, Up: Hacking +File: org.info, Node: Adding Export Backends, Next: Tables in Arbitrary Syntax, Prev: Adding Hyperlink Types, Up: Hacking -A.4 Adding Export Back-ends -=========================== +A.4 Adding Export Backends +========================== -Org’s export engine makes it easy for writing new back-ends. The +Org’s export engine makes it easy for writing new backends. The framework on which the engine was built makes it easy to derive new -back-ends from existing ones. +backends from existing ones. The two main entry points to the export engine are: ‘org-export-define-backend’ and ‘org-export-define-derived-backend’. To grok these functions, see ‘ox-latex.el’ for an example of defining a new -back-end from scratch, and ‘ox-beamer.el’ for an example of deriving -from an existing engine. +backend from scratch, and ‘ox-beamer.el’ for an example of deriving from +an existing engine. - For creating a new back-end from scratch, first set its name as a + For creating a new backend from scratch, first set its name as a symbol in an alist consisting of elements and export functions. To make -the back-end visible to the export dispatcher, set ‘:menu-entry’ -keyword. For export options specific to this back-end, set the -‘:options-alist’. +the backend visible to the export dispatcher, set ‘:menu-entry’ keyword. +For export options specific to this backend, set the ‘:options-alist’. - For creating a new back-end from an existing one, set + For creating a new backend from an existing one, set ‘:translate-alist’ to an alist of export functions. This alist replaces -the parent back-end functions. +the parent backend functions. For complete documentation, see the Org Export Reference on Worg (https://orgmode.org/worg/dev/org-export-reference.html).  -File: org.info, Node: Tables in Arbitrary Syntax, Next: Dynamic Blocks, Prev: Adding Export Back-ends, Up: Hacking +File: org.info, Node: Tables in Arbitrary Syntax, Next: Dynamic Blocks, Prev: Adding Export Backends, Up: Hacking A.5 Tables in Arbitrary Syntax ============================== @@ -18596,7 +19375,7 @@ Orgtbl mode has built-in translator functions: ‘orgtbl-to-csv’ ‘orgtbl-to-latex’, ‘orgtbl-to-html’, ‘orgtbl-to-texinfo’, ‘orgtbl-to-unicode’ and ‘orgtbl-to-orgtbl’. They use the generic translator, ‘orgtbl-to-generic’, which delegates translations to various -export back-ends. +export backends. Properties passed to the function through the ‘ORGTBL SEND’ line take precedence over properties defined inside the function. For example, @@ -18630,7 +19409,7 @@ table. The first argument is the table whose lines are a list of fields or the symbol ‘hline’. The second argument is the property list consisting of parameters specified in the ‘#+ORGTBL: SEND’ line. Please share your translator functions by posting them to the Org users mailing -list, at . +list, at .  File: org.info, Node: Dynamic Blocks, Next: Special Agenda Views, Prev: Tables in Arbitrary Syntax, Up: Hacking @@ -18785,7 +19564,7 @@ special function: (1) 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. +time specification ‘[h]h:mm’ in their timestamps. (2) Note that, for ‘org-odd-levels-only’, a level number corresponds to order in the hierarchy, not to the number of stars. @@ -18817,13 +19596,11 @@ number. Here are tips to speed up: (setq org-agenda-use-tag-inheritance nil) - • Disable parsing of some drawer properties: + • Disable parsing of some properties: - (setq org-agenda-ignore-properties '(effort appt stats category)) + (setq org-agenda-ignore-properties '(stats)) - The drawer properties you can disable in the agenda are effort - estimates (‘effort’), appointments (‘appt’), statistics (‘stats’) - and subtree-local categories (‘category’). + This will disable parsing and updating statistic cookies. These options can be applied to selected agenda views. For more details about generation of agenda views, see the docstrings for the @@ -18973,7 +19750,7 @@ properties. Get all property keys in the current buffer. -- Function: org-insert-property-drawer - Insert a property drawer for the current entry. Also + Insert a property drawer for the current entry. -- Function: org-entry-put-multivalued-property pom property &rest values @@ -19141,13 +19918,13 @@ features, and to incorporate project planning functionality directly into a notes file. Since the first release, literally thousands of emails to me or to -the mailing list have provided a constant stream -of bug reports, feedback, new ideas, and sometimes patches and add-on -code. Many thanks to everyone who has helped to improve this package. -I am trying to keep here a list of the people who had significant -influence in shaping one or more aspects of Org. The list may not be -complete, if I have forgotten someone, please accept my apologies and -let me know. +the mailing list have provided a constant +stream of bug reports, feedback, new ideas, and sometimes patches and +add-on code. Many thanks to everyone who has helped to improve this +package. I am trying to keep here a list of the people who had +significant influence in shaping one or more aspects of Org. The list +may not be complete, if I have forgotten someone, please accept my +apologies and let me know. Before I get to this list, a few special mentions are in order: @@ -19968,7 +20745,7 @@ D Main Index * Menu: * *this*, in post header argument: Results of Evaluation. - (line 271) + (line 278) * + suffix, in properties: Property Syntax. (line 52) * _ALL suffix, in properties: Property Syntax. (line 50) * abbreviation, links: Link Abbreviations. (line 6) @@ -19981,7 +20758,7 @@ D Main Index * agenda: Weekly/daily agenda. (line 6) * agenda dispatcher: Agenda Dispatcher. (line 6) * agenda files: Agenda Files. (line 6) -* agenda files, removing buffers: Agenda Commands. (line 497) +* agenda files, removing buffers: Agenda Commands. (line 500) * agenda filtering: Filtering/limiting agenda items. (line 20) * agenda views: Agenda Views. (line 6) @@ -20008,7 +20785,7 @@ D Main Index * ALT_TITLE, property <1>: Headings and sectioning structure. (line 24) * angle bracket links: Link Format. (line 6) -* angular brackets, around links: External Links. (line 136) +* angular brackets, around links: External Links. (line 137) * anniversaries, from BBDB: Weekly/daily agenda. (line 79) * API, for mapping: Using the Mapping API. (line 6) @@ -20078,7 +20855,7 @@ D Main Index * ATTR_ODT, keyword <1>: Images in ODT export. (line 31) * ATTR_ODT, keyword <2>: Images in ODT export. - (line 76) + (line 75) * ATTR_ODT, keyword <3>: Advanced topics in ODT export. (line 151) * ATTR_TEXINFO, keyword: Plain lists in Texinfo export. @@ -20100,7 +20877,7 @@ D Main Index * babel, languages: Languages. (line 6) * babel, library of: Library of Babel. (line 6) * backslashes, in links: Link Format. (line 17) -* backtrace of an error: Feedback. (line 77) +* backtrace of an error: Feedback. (line 81) * BBDB links: External Links. (line 6) * BBDB, anniversaries: Weekly/daily agenda. (line 79) * Beamer export: Beamer Export. (line 6) @@ -20137,7 +20914,7 @@ D Main Index * BEGIN_EXPORT beamer: Beamer specific syntax. (line 19) * BEGIN_EXPORT html: Quoting HTML tags. (line 13) -* BEGIN_EXPORT latex: Quoting LaTeX code. (line 18) +* BEGIN_EXPORT latex: Quoting LaTeX code. (line 19) * BEGIN_EXPORT texinfo: Quoting Texinfo code. (line 9) * BEGIN_JUSTIFYLEFT: ASCII/Latin-1/UTF-8 export. @@ -20149,15 +20926,17 @@ D Main Index * BEGIN_SRC <1>: Structure of Code Blocks. (line 6) * BEGIN_VERSE: Paragraphs. (line 13) -* BIND, keyword: Export Settings. (line 210) +* bibliography: Citations. (line 6) +* BIBLIOGRAPHY, keyword: Citations. (line 10) +* BIND, keyword: Export Settings. (line 229) * block agenda: Block agenda. (line 6) * BLOCKED, special property: Special Properties. (line 13) -* blocking, of checkboxes: Checkboxes. (line 45) +* blocking, of checkboxes: Checkboxes. (line 40) * blocks, folding: Blocks. (line 6) * bold text, markup rules: Emphasis and Monospace. (line 6) * boolean logic, for agenda searches: Matching tags and properties. - (line 32) + (line 30) * bracket links: Link Format. (line 9) * bug reports: Feedback. (line 6) * C-c C-c, overview: The Very Busy C-c C-c Key. @@ -20171,7 +20950,7 @@ D Main Index * calculations, in tables: Built-in Table Editor. (line 181) * calculations, in tables <1>: The Spreadsheet. (line 6) -* calendar commands, from agenda: Agenda Commands. (line 447) +* calendar commands, from agenda: Agenda Commands. (line 450) * calendar integration: Weekly/daily agenda. (line 33) * calendar, for selecting date: The date/time prompt. (line 78) @@ -20188,12 +20967,12 @@ D Main Index * capture <1>: Capture. (line 6) * capture protocol: The capture protocol. (line 6) -* capturing, from agenda: Agenda Commands. (line 346) +* capturing, from agenda: Agenda Commands. (line 349) * category: Categories. (line 6) * category filtering, in agenda: Filtering/limiting agenda items. (line 20) * category, for tags/property match: Matching tags and properties. - (line 65) + (line 63) * CATEGORY, keyword: Categories. (line 6) * CATEGORY, keyword <1>: In-buffer Settings. (line 20) * CATEGORY, property: Property Inheritance. @@ -20205,15 +20984,18 @@ D Main Index * center image in LaTeX export: Images in LaTeX export. (line 63) * change agenda display: Agenda Commands. (line 63) -* checkbox blocking: Checkboxes. (line 45) -* checkbox statistics: Checkboxes. (line 29) +* checkbox blocking: Checkboxes. (line 40) +* checkbox statistics: Checkboxes. (line 24) * checkboxes: Checkboxes. (line 6) * checkboxes and TODO dependencies: TODO dependencies. (line 53) * children, subtree visibility state: Global and local cycling. (line 6) * CINDEX, keyword: Indices. (line 6) * citation: Citation handling. (line 6) -* CLASS, property: iCalendar Export. (line 51) +* citation processor: Citation handling. (line 6) +* CITE_EXPORT, keyword: Citation export processors. + (line 43) +* CLASS, property: iCalendar Export. (line 55) * clean outline view: Clean View. (line 6) * clocking time: Clocking Work Time. (line 6) * CLOCKSUM, special property: Special Properties. (line 13) @@ -20245,7 +21027,7 @@ D Main Index * code text, markup rules: Emphasis and Monospace. (line 6) * colnames, header argument: Environment of a Code Block. - (line 52) + (line 56) * column formula: Column formulas. (line 6) * column view, for properties: Defining columns. (line 6) * column view, in agenda: Agenda Column View. (line 6) @@ -20264,9 +21046,9 @@ D Main Index * comments, header argument: Extracting Source Code. (line 46) * completion, of dictionary words: Completion. (line 6) -* completion, of file names: Handling Links. (line 94) +* completion, of file names: Handling Links. (line 114) * completion, of link abbreviations: Completion. (line 6) -* completion, of links: Handling Links. (line 71) +* completion, of links: Handling Links. (line 91) * completion, of option keywords: Per-file keywords. (line 26) * completion, of option keywords <1>: Completion. (line 6) * completion, of property keys: Completion. (line 6) @@ -20280,6 +21062,7 @@ D Main Index * CONSTANTS, keyword: References. (line 114) * CONSTANTS, keyword <1>: In-buffer Settings. (line 29) * constants.el: Cooperation. (line 14) +* contact: Feedback. (line 6) * contents, global visibility state: Global and local cycling. (line 20) * continuous clocking: Resolving idle time. (line 78) @@ -20290,7 +21073,7 @@ D Main Index * converter: Advanced topics in ODT export. (line 12) * COOKIE_DATA, property: Breaking Down Tasks. (line 21) -* COOKIE_DATA, property <1>: Checkboxes. (line 29) +* COOKIE_DATA, property <1>: Checkboxes. (line 24) * coordinates, of field: References. (line 90) * copying notes: Refiling and Archiving. (line 6) @@ -20307,9 +21090,9 @@ D Main Index * custom date/time format: Custom time format. (line 6) * custom search strings: Custom Searches. (line 6) * CUSTOM_ID, property: Internal Links. (line 11) -* CUSTOM_ID, property <1>: Handling Links. (line 21) +* CUSTOM_ID, property <1>: Handling Links. (line 22) * cutting, of subtrees: Structure Editing. (line 6) -* cycling, in plain lists: Plain Lists. (line 70) +* cycling, in plain lists: Plain Lists. (line 71) * cycling, of agenda files: Agenda Files. (line 26) * cycling, of TODO states: TODO Basics. (line 14) * cycling, visibility: Visibility Cycling. (line 6) @@ -20317,7 +21100,7 @@ D Main Index * dash, special symbol: Special Symbols. (line 36) * data type index, in Texinfo export: Indices. (line 6) * date format, custom: Custom time format. (line 6) -* date range: Timestamps. (line 45) +* date range: Timestamps. (line 56) * date stamp: Dates and Times. (line 6) * date stamps: Timestamps. (line 6) * date tree: Template elements. (line 50) @@ -20347,14 +21130,14 @@ D Main Index (line 11) * DESCRIPTION, property: Headings and sectioning structure. (line 24) -* DESCRIPTION, property <1>: iCalendar Export. (line 51) -* diary entries, creating from agenda: Agenda Commands. (line 456) +* DESCRIPTION, property <1>: iCalendar Export. (line 55) +* diary entries, creating from agenda: Agenda Commands. (line 459) * diary integration: Weekly/daily agenda. (line 33) -* diary style timestamps: Timestamps. (line 35) +* diary style timestamps: Timestamps. (line 39) * dictionary word completion: Completion. (line 6) * dir file, in Texinfo export: Info directory file. (line 6) * dir, header argument: Environment of a Code Block. - (line 310) + (line 315) * DIR, property: Attachment defaults and dispatcher. (line 68) * DIR, property <1>: Attachment defaults and dispatcher. @@ -20365,17 +21148,25 @@ D Main Index (line 6) * dispatching agenda commands: Agenda Dispatcher. (line 6) * display changing, in agenda: Agenda Commands. (line 63) +* dnd: Drag and Drop & yank-media. + (line 6) * doc, docx, rtf: Advanced topics in ODT export. (line 12) * document structure: Document Structure. (line 6) -* document title: Export Settings. (line 60) +* document title: Export Settings. (line 75) * documentation: Documentation Access. (line 6) * DONE, final TODO keyword: Per-file keywords. (line 29) +* drag and drop: Drag and Drop & yank-media. + (line 6) +* dragging files: Drag and Drop & yank-media. + (line 6) * drawer, for properties: Property Syntax. (line 6) * drawer, for state change recording: Tracking TODO state changes. (line 6) * drawers: Drawers. (line 6) +* dropping files: Drag and Drop & yank-media. + (line 6) * duration, computing: Durations and time values. (line 6) * dvipng: Math formatting in HTML export. @@ -20407,7 +21198,7 @@ D Main Index * enum, Texinfo attribute: Plain lists in Texinfo export. (line 6) * epilogue, header argument: Environment of a Code Block. - (line 367) + (line 372) * escape character: Escape Character. (line 6) * escape syntax, for links: Link Format. (line 17) * eval, header argument: Evaluating Code Blocks. @@ -20416,17 +21207,18 @@ D Main Index * example block: Literal Examples. (line 10) * example blocks, in LaTeX export: Example blocks in LaTeX export. (line 6) -* EXCLUDE_TAGS, keyword: Export Settings. (line 52) +* EXCLUDE_TAGS, keyword: Export Settings. (line 61) * excluding entries from table of contents: Table of Contents. (line 15) * export back-end: Exporting. (line 12) +* export backend: Exporting. (line 12) * export, dispatcher: The Export Dispatcher. (line 6) * export, include files: Include Files. (line 6) * export, OpenDocument: OpenDocument Text Export. (line 6) * Export, settings: Export Settings. (line 6) -* Export, writing back-ends: Adding Export Back-ends. +* Export, writing backends: Adding Export Backends. (line 6) * exporting: Exporting. (line 6) * exporting agenda views: Exporting Agenda Views. @@ -20434,7 +21226,7 @@ D Main Index * exporting, not: Comment Lines. (line 6) * exports, header argument: Exporting Code Blocks. (line 15) -* EXPORT_FILE_NAME, keyword: Export Settings. (line 64) +* EXPORT_FILE_NAME, keyword: Export Settings. (line 79) * EXPORT_FILE_NAME, property: ODT export commands. (line 9) * EXPORT_LATEX_CLASS, property: LaTeX header and sectioning. (line 23) @@ -20447,7 +21239,8 @@ D Main Index (line 6) * faces, for TODO keywords: Faces for TODO keywords. (line 6) -* FAQ: Summary. (line 55) +* FAQ: Summary. (line 58) +* feature requests: Feedback. (line 6) * feedback: Feedback. (line 6) * field coordinates: References. (line 90) * field formula: Field and range formulas. @@ -20455,16 +21248,16 @@ D Main Index * field references: References. (line 15) * file links: External Links. (line 6) * file links, searching: Search Options. (line 6) -* file name completion: Handling Links. (line 94) +* file name completion: Handling Links. (line 114) * file, header argument: Results of Evaluation. (line 123) * FILE, special property: Special Properties. (line 13) * file-desc, header argument: Results of Evaluation. - (line 144) + (line 147) * file-ext, header argument: Results of Evaluation. (line 133) * file-mode, header argument: Results of Evaluation. - (line 155) + (line 158) * files for agenda: Agenda Files. (line 6) * files, adding to agenda list: Agenda Files. (line 16) * files, selecting for publishing: Selecting files. (line 6) @@ -20481,13 +21274,15 @@ D Main Index * folded, subtree visibility state: Global and local cycling. (line 6) * folding, sparse trees: Sparse Trees. (line 6) -* following links: Handling Links. (line 104) +* following links: Handling Links. (line 124) * footers, in code blocks: Environment of a Code Block. - (line 359) + (line 364) * footnotes: Creating Footnotes. (line 6) * format specifier, in spreadsheet: Formula syntax for Calc. (line 17) * format, of links: Link Format. (line 6) +* formatter, dynamic block parameter: Capturing column view. + (line 74) * formatting source code, markup rules: Literal Examples. (line 31) * formula debugging: Editing and debugging formulas. (line 132) @@ -20513,7 +21308,7 @@ D Main Index * graph, in tables: Org Plot. (line 6) * group tags: Tag Hierarchy. (line 6) * group tags, as regular expressions: Matching tags and properties. - (line 58) + (line 56) * grouping columns in tables: Column Groups. (line 6) * habits: Tracking your habits. (line 6) @@ -20521,7 +21316,7 @@ D Main Index * header arguments per language: Using Header Arguments. (line 94) * header arguments, in code blocks: Structure of Code Blocks. - (line 57) + (line 65) * header lines, in tables: Built-in Table Editor. (line 6) * header, for LaTeX files: LaTeX header and sectioning. @@ -20529,7 +21324,7 @@ D Main Index * HEADER, keyword: Using Header Arguments. (line 134) * headers, in code blocks: Environment of a Code Block. - (line 359) + (line 364) * headline navigation: Motion. (line 6) * headline tagging: Tags. (line 6) * headline, promotion and demotion: Structure Editing. (line 6) @@ -20578,11 +21373,14 @@ D Main Index * hyperlinks: Hyperlinks. (line 6) * hyperlinks, adding new types: Adding Hyperlink Types. (line 6) +* ICAL-TTL, keyword: iCalendar Export. (line 97) * iCalendar export: iCalendar Export. (line 6) -* ID, property: Handling Links. (line 21) +* id links, searching: Search Options. (line 6) +* ID, property: Handling Links. (line 22) * ID, property <1>: Capturing column view. (line 34) -* ID, property <2>: iCalendar Export. (line 26) +* ID, property <2>: iCalendar Export. (line 30) +* ideas: Feedback. (line 6) * identify, ImageMagick: Images in ODT export. (line 34) * idle, resolve, dangling: Resolving idle time. (line 9) @@ -20600,11 +21398,11 @@ D Main Index * images, markup rules: Images. (line 6) * imenu.el: Cooperation. (line 29) * in-buffer settings: In-buffer Settings. (line 6) -* inactive timestamp: Timestamps. (line 53) +* inactive timestamp: Timestamps. (line 68) * include files, during export: Include Files. (line 6) * INCLUDE, keyword: Include Files. (line 6) * Indent mode: Org Indent Mode. (line 6) -* indentation, in code blocks: Editing Source Code. (line 32) +* indentation, in code blocks: Editing Source Code. (line 35) * indentation, in source blocks: Literal Examples. (line 81) * index, in a publishing project: Generating an index. (line 6) * INDEX, keyword: Generating an index. (line 17) @@ -20620,14 +21418,14 @@ D Main Index * inheritance, of properties: Property Inheritance. (line 6) * inheritance, of tags: Tag Inheritance. (line 6) -* inline, in LaTeX export: Quoting LaTeX code. (line 10) +* inline, in LaTeX export: Quoting LaTeX code. (line 11) * inlining images: Images. (line 6) * inlining images in HTML: Images in HTML export. (line 6) * inlining images in LaTeX: Images in LaTeX export. (line 6) * input-file, macro: Macro Replacement. (line 64) -* inserting links: Handling Links. (line 71) +* inserting links: Handling Links. (line 91) * insertion, of templates: Structure Templates. (line 6) * insertion, of templates <1>: Structure Templates. (line 21) * install-info, in Texinfo export: Info directory file. (line 6) @@ -20651,16 +21449,17 @@ D Main Index * KEYWORDS, keyword <1>: HTML specific export settings. (line 46) * KEYWORDS, keyword <2>: LaTeX specific export settings. - (line 61) + (line 63) * KEYWORDS, keyword <3>: ODT specific export settings. (line 16) * KINDEX, keyword: Indices. (line 6) +* laggy: Feedback. (line 72) * language specific default header arguments: Using Header Arguments. (line 56) * language specific header arguments properties: Using Header Arguments. (line 94) * language, in code blocks: Structure of Code Blocks. - (line 47) + (line 48) * LANGUAGE, keyword: Export Settings. (line 38) * LANGUAGE, keyword <1>: LaTeX specific export settings. (line 20) @@ -20679,27 +21478,27 @@ D Main Index * LaTeX sectioning structure: LaTeX header and sectioning. (line 6) * LaTeX, and Orgtbl mode: A LaTeX example. (line 6) -* LATEX, keyword: Quoting LaTeX code. (line 14) +* LATEX, keyword: Quoting LaTeX code. (line 15) * LATEX_CLASS, keyword: LaTeX specific export settings. - (line 39) + (line 41) * LATEX_CLASS, keyword <1>: LaTeX header and sectioning. (line 23) * LATEX_CLASS_OPTIONS, keyword: LaTeX specific export settings. - (line 47) + (line 49) * LATEX_CLASS_OPTIONS, keyword <1>: LaTeX header and sectioning. (line 23) * LATEX_COMPILER, keyword: LaTeX/PDF export commands. (line 25) * LATEX_COMPILER, keyword <1>: LaTeX specific export settings. - (line 51) + (line 53) * LATEX_HEADER, keyword: HTML specific export settings. (line 51) * LATEX_HEADER, keyword <1>: LaTeX specific export settings. - (line 56) + (line 58) * LATEX_HEADER, keyword <2>: LaTeX header and sectioning. (line 30) * LATEX_HEADER_EXTRA, keyword: LaTeX specific export settings. - (line 56) + (line 58) * LATEX_HEADER_EXTRA, keyword <1>: LaTeX header and sectioning. (line 30) * Latin-1 export: ASCII/Latin-1/UTF-8 export. @@ -20707,21 +21506,21 @@ D Main Index * lettered lists, in Texinfo export: Plain lists in Texinfo export. (line 6) * level, for tags/property match: Matching tags and properties. - (line 65) + (line 63) * LibreOffice: OpenDocument Text Export. (line 6) * limits, in agenda: Filtering/limiting agenda items. (line 129) * line breaks, markup rules: Paragraphs. (line 9) -* lines, include: Include Files. (line 36) +* lines, include: Include Files. (line 38) * link abbreviations: Link Abbreviations. (line 6) * link abbreviations, completion of: Completion. (line 6) -* link completion: Handling Links. (line 71) +* link completion: Handling Links. (line 91) * link format: Link Format. (line 6) * LINK, keyword: Link Abbreviations. (line 49) * LINK, keyword <1>: In-buffer Settings. (line 39) * links, external: External Links. (line 6) -* links, finding next/previous: Handling Links. (line 153) +* links, finding next/previous: Handling Links. (line 173) * links, handling: Handling Links. (line 6) * links, in HTML export: Links in HTML export. (line 6) @@ -20729,8 +21528,8 @@ D Main Index * links, internal: Internal Links. (line 6) * links, publishing: Publishing links. (line 6) * links, radio targets: Radio Targets. (line 6) -* links, returning to: Handling Links. (line 146) -* linter: Org Syntax. (line 24) +* links, returning to: Handling Links. (line 166) +* linter: Org Syntax. (line 23) * Lisp forms, as table formulas: Formula syntax for Lisp. (line 6) * list of listings: Table of Contents. (line 6) @@ -20740,7 +21539,7 @@ D Main Index * lists, ordered: Plain Lists. (line 6) * lists, plain: Plain Lists. (line 6) * literal examples, markup rules: Literal Examples. (line 6) -* LOCATION, property: iCalendar Export. (line 51) +* LOCATION, property: iCalendar Export. (line 55) * logging, of progress: Progress Logging. (line 6) * LOGGING, property: Tracking TODO state changes. (line 45) @@ -20758,8 +21557,8 @@ D Main Index * mapping entries, API: Using the Mapping API. (line 6) * mappings in open-source protocol: The open-source protocol. - (line 67) -* mark ring: Handling Links. (line 141) + (line 68) +* mark ring: Handling Links. (line 161) * Markdown export: Markdown Export. (line 6) * marking characters, tables: Advanced features. (line 39) * match view: Matching tags and properties. @@ -20774,10 +21573,10 @@ D Main Index (line 6) * MathML: LaTeX math snippets. (line 10) * MH-E links: External Links. (line 6) -* minlevel, include: Include Files. (line 22) +* minlevel, include: Include Files. (line 24) * minor mode for tables: Orgtbl Mode. (line 6) * mkdirp, header argument: Environment of a Code Block. - (line 310) + (line 315) * mkdirp, header argument <1>: Extracting Source Code. (line 42) * mode, for Calc: Formula syntax for Calc. @@ -20803,12 +21602,13 @@ D Main Index * no-expand, header argument: Extracting Source Code. (line 107) * NOBLOCKING, property: TODO dependencies. (line 29) +* not responsive: Feedback. (line 72) * noweb, header argument: Noweb Reference Syntax. (line 18) * noweb-ref, header argument: Noweb Reference Syntax. (line 6) * noweb-sep, header argument: Noweb Reference Syntax. - (line 101) + (line 104) * number headlines: Dynamic Headline Numbering. (line 6) * occur, command: Sparse Trees. (line 6) @@ -20822,11 +21622,13 @@ D Main Index (line 22) * ODT_STYLES_FILE, keyword <1>: Applying custom styles. (line 29) -* only-contents, include: Include Files. (line 53) +* only-contents, include: Include Files. (line 55) * open-source protocol: The open-source protocol. (line 6) * OpenDocument: OpenDocument Text Export. (line 6) +* operator, for property search: Matching tags and properties. + (line 89) * option keyword completion: Completion. (line 6) * options, for custom agenda views: Setting options. (line 6) * options, for export: Export Settings. (line 6) @@ -20834,9 +21636,9 @@ D Main Index * OPTIONS, keyword: Export Settings. (line 6) * ordered lists: Plain Lists. (line 6) * ORDERED, property: TODO dependencies. (line 6) -* ORDERED, property <1>: Checkboxes. (line 45) +* ORDERED, property <1>: Checkboxes. (line 40) * Org export: Org Export. (line 6) -* Org mode, turning on: Activation. (line 24) +* Org mode, turning on: Activation. (line 25) * Org Num mode: Dynamic Headline Numbering. (line 6) * Org protocol, set-up: Protocols. (line 14) @@ -20859,25 +21661,30 @@ D Main Index * paragraphs, markup rules: Paragraphs. (line 6) * passing arguments to code blocks: Environment of a Code Block. (line 9) +* pasting files, images from clipboard: Drag and Drop & yank-media. + (line 18) * pasting, of subtrees: Structure Editing. (line 6) * PDF export: LaTeX Export. (line 6) * pdflatex: LaTeX/PDF export commands. (line 25) * per-file keywords: Per-file keywords. (line 6) +* performance: Feedback. (line 72) * PINDEX, keyword: Indices. (line 6) * plain links: Link Format. (line 6) * plain lists: Plain Lists. (line 6) * plain lists, in LaTeX export: Plain lists in LaTeX export. (line 6) -* plain text external links: External Links. (line 136) +* plain text external links: External Links. (line 137) * plot tables using Gnuplot: Org Plot. (line 6) * PLOT, keyword: Org Plot. (line 12) * post, header argument: Results of Evaluation. - (line 271) + (line 278) * presentation, of agenda items: Presentation and Sorting. (line 6) -* print edition: Summary. (line 60) +* print edition: Summary. (line 63) * printing sparse trees: Sparse Trees. (line 52) +* PRINT_BIBLIOGRAPHY, keyword: Bibliography printing. + (line 6) * priorities: Priorities. (line 6) * PRIORITIES, keyword: Priorities. (line 52) * PRIORITIES, keyword <1>: In-buffer Settings. (line 44) @@ -20885,11 +21692,13 @@ D Main Index (line 6) * priority cookie: Priorities. (line 6) * PRIORITY, special property: Special Properties. (line 13) +* profile: Feedback. (line 72) +* profiler: Feedback. (line 111) * program index, in Texinfo export: Indices. (line 6) * progress logging: Progress Logging. (line 6) * projects, for publishing: Project alist. (line 6) * prologue, header argument: Environment of a Code Block. - (line 359) + (line 364) * promotion, of subtrees: Structure Editing. (line 6) * proof, in LaTeX export: Special blocks in LaTeX export. (line 6) @@ -20914,7 +21723,7 @@ D Main Index * protocol, open-source rewritten URL: The open-source protocol. (line 32) * protocol, open-source, set-up mapping: The open-source protocol. - (line 67) + (line 68) * protocol, store-link: The store-link protocol. (line 6) * protocols, for external access: Capture and Attachments. @@ -20927,7 +21736,7 @@ D Main Index * quote blocks: Paragraphs. (line 25) * quote blocks, in LaTeX export: Quote blocks in LaTeX export. (line 6) -* radio button, checkbox as: Checkboxes. (line 75) +* radio button, checkbox as: Checkboxes. (line 98) * radio tables: Radio tables. (line 6) * radio targets: Radio Targets. (line 6) * range formula: Field and range formulas. @@ -20949,16 +21758,17 @@ D Main Index * regular expressions syntax: Regular Expressions. (line 6) * regular expressions, in searches: Regular Expressions. (line 6) * regular expressions, with tags search: Matching tags and properties. - (line 53) + (line 51) * relative timer: Timers. (line 6) * reminders: Weekly/daily agenda. (line 126) -* remote editing, bulk, from agenda: Agenda Commands. (line 353) -* remote editing, from agenda: Agenda Commands. (line 224) -* remote editing, undo: Agenda Commands. (line 228) +* remote editing, bulk, from agenda: Agenda Commands. (line 356) +* remote editing, from agenda: Agenda Commands. (line 227) +* remote editing, undo: Agenda Commands. (line 231) * remote references: References. (line 135) * repeated tasks: Repeated tasks. (line 6) * report, of clocked time: The clock table. (line 6) * reporting a bug: Feedback. (line 6) +* request a feature: Feedback. (line 6) * resolve idle time: Resolving idle time. (line 9) * results, header argument: Results of Evaluation. (line 6) @@ -20974,7 +21784,7 @@ D Main Index (line 6) * row, of field coordinates: References. (line 90) * rownames, header argument: Environment of a Code Block. - (line 77) + (line 81) * RSS feeds: Capture and Attachments. (line 6) * RSS feeds <1>: RSS Feeds. (line 6) @@ -20986,6 +21796,7 @@ D Main Index * scripts, for agenda processing: Extracting Agenda Information. (line 6) * search option in file links: Search Options. (line 6) +* search option in id links: Search Options. (line 6) * search strings, custom: Custom Searches. (line 6) * search view: Search view. (line 6) * searching for tags: Tag Searches. (line 6) @@ -20995,22 +21806,22 @@ D Main Index (line 6) * SELECT_TAGS, keyword: Export Settings. (line 44) * sep, header argument: Results of Evaluation. - (line 151) + (line 154) * sep, Texinfo attribute: Plain lists in Texinfo export. (line 30) * SEQ_TODO, keyword: Per-file keywords. (line 6) -* SEQ_TODO, keyword <1>: In-buffer Settings. (line 192) +* SEQ_TODO, keyword <1>: In-buffer Settings. (line 207) * session, header argument: Environment of a Code Block. - (line 280) + (line 285) * setting tags: Setting Tags. (line 6) * SETUPFILE, keyword: Export Settings. (line 13) * SETUPFILE, keyword <1>: In-buffer Settings. (line 54) -* sexp timestamps: Timestamps. (line 35) +* sexp timestamps: Timestamps. (line 39) * shebang, header argument: Extracting Source Code. (line 83) * shell links: External Links. (line 6) * shift-selection: Conflicts. (line 6) -* shift-selection-mode: Plain Lists. (line 95) +* shift-selection-mode: Plain Lists. (line 96) * show all, command: Global and local cycling. (line 40) * show all, global visibility state: Global and local cycling. @@ -21022,10 +21833,12 @@ D Main Index * show hidden text: Visibility Cycling. (line 6) * shy hyphen, special symbol: Special Symbols. (line 36) * sitemap, of published pages: Site map. (line 6) +* slow: Feedback. (line 72) +* slowdown: Feedback. (line 72) * smartphone: Org Mobile. (line 6) * sorting, of agenda items: Sorting of agenda items. (line 6) -* sorting, of plain list: Plain Lists. (line 159) +* sorting, of plain list: Plain Lists. (line 160) * sorting, of subtrees: Structure Editing. (line 6) * source block: Literal Examples. (line 38) * source blocks, in LaTeX export: Source blocks in LaTeX export. @@ -21063,15 +21876,15 @@ D Main Index * special symbols: Special Symbols. (line 6) * special symbols, in-buffer display: Special Symbols. (line 27) * speed keys: Speed Keys. (line 6) -* speedbar.el: Cooperation. (line 41) +* speedbar.el: Cooperation. (line 45) * spreadsheet capabilities: The Spreadsheet. (line 6) -* square brackets, around links: External Links. (line 136) +* square brackets, around links: External Links. (line 137) * startup visibility: Global and local cycling. (line 36) * STARTUP, keyword: Initial visibility. (line 11) * STARTUP, keyword <1>: Blocks. (line 14) -* STARTUP, keyword <2>: In-buffer Settings. (line 66) -* statistics, for checkboxes: Checkboxes. (line 29) +* STARTUP, keyword <2>: In-buffer Settings. (line 70) +* statistics, for checkboxes: Checkboxes. (line 24) * statistics, for TODO items: Breaking Down Tasks. (line 6) * store-link protocol: The store-link protocol. (line 6) @@ -21102,7 +21915,7 @@ D Main Index * SUBTITLE, keyword <2>: HTML specific export settings. (line 56) * SUBTITLE, keyword <3>: LaTeX specific export settings. - (line 70) + (line 72) * SUBTITLE, keyword <4>: ODT specific export settings. (line 26) * SUBTITLE, keyword <5>: Texinfo specific export settings. @@ -21116,19 +21929,19 @@ D Main Index (line 6) * subtrees, cut and paste: Structure Editing. (line 6) * summary: Summary. (line 6) -* SUMMARY, property: iCalendar Export. (line 51) +* SUMMARY, property: iCalendar Export. (line 55) * superscript: Subscripts and Superscripts. (line 6) * switches, in code blocks: Structure of Code Blocks. - (line 52) -* syntax checker: Org Syntax. (line 24) + (line 60) +* syntax checker: Org Syntax. (line 23) * syntax, noweb: Noweb Reference Syntax. (line 6) * syntax, of formulas: Formula syntax for Calc. (line 6) * table editor, built-in: Built-in Table Editor. (line 6) -* table editor, table.el: Cooperation. (line 49) +* table editor, table.el: Cooperation. (line 53) * table indirection: References. (line 148) * table lookup functions: Lookup functions. (line 6) * table of contents: Table of Contents. (line 6) @@ -21137,7 +21950,7 @@ D Main Index (line 6) * table-type, Texinfo attribute: Plain lists in Texinfo export. (line 19) -* table.el: Cooperation. (line 49) +* table.el: Cooperation. (line 53) * tables: Tables. (line 6) * tables, in HTML: Tables in HTML export. (line 6) @@ -21161,7 +21974,7 @@ D Main Index * tags, as an agenda view: Storing searches. (line 11) * tags, groups: Tag Hierarchy. (line 6) * TAGS, keyword: Setting Tags. (line 22) -* TAGS, keyword <1>: In-buffer Settings. (line 187) +* TAGS, keyword <1>: In-buffer Settings. (line 202) * tags, setting: Setting Tags. (line 6) * TAGS, special property: Special Properties. (line 13) * tags-todo: Storing searches. (line 11) @@ -21203,11 +22016,11 @@ D Main Index (line 30) * TEXINFO_DIR_CATEGORY, keyword <1>: Info directory file. (line 6) * TEXINFO_DIR_DESC, keyword: Texinfo specific export settings. - (line 36) + (line 44) * TEXINFO_DIR_DESC, keyword <1>: Info directory file. (line 6) -* TEXINFO_DIR_TITLE, keyword: Texinfo specific export settings. +* TEXINFO_DIR_NAME, keyword: Texinfo specific export settings. (line 33) -* TEXINFO_DIR_TITLE, keyword <1>: Info directory file. (line 6) +* TEXINFO_DIR_NAME, keyword <1>: Info directory file. (line 6) * TEXINFO_FILENAME, keyword: Texinfo specific export settings. (line 17) * TEXINFO_FILENAME, keyword <1>: Texinfo file header. (line 6) @@ -21217,7 +22030,7 @@ D Main Index * TEXINFO_POST_HEADER, keyword: Texinfo specific export settings. (line 27) * TEXINFO_PRINTED_TITLE, keyword: Texinfo specific export settings. - (line 39) + (line 48) * TEXINFO_PRINTED_TITLE, keyword <1>: Texinfo title and copyright page. (line 6) * text areas, in HTML: Text areas in HTML export. @@ -21227,6 +22040,8 @@ D Main Index * time format, custom: Custom time format. (line 6) * time grid: Time-of-day specifications. (line 31) +* time range: Timestamps. (line 49) +* time range <1>: Timestamps. (line 56) * time, computing: Durations and time values. (line 6) * time, macro: Macro Replacement. (line 56) @@ -21234,18 +22049,18 @@ D Main Index (line 6) * time-of-day specification: Time-of-day specifications. (line 6) -* timerange: Timestamps. (line 45) +* timerange: Timestamps. (line 56) * times: Dates and Times. (line 6) * timestamp: Dates and Times. (line 6) * timestamp <1>: Timestamps. (line 14) -* timestamp, inactive: Timestamps. (line 53) +* timestamp, inactive: Timestamps. (line 68) * TIMESTAMP, special property: Special Properties. (line 13) -* timestamp, with repeater interval: Timestamps. (line 25) +* timestamp, with repeater interval: Timestamps. (line 29) * timestamps: Timestamps. (line 6) * TIMESTAMP_IA, special property: Special Properties. (line 13) -* TIMEZONE, property: iCalendar Export. (line 51) +* TIMEZONE, property: iCalendar Export. (line 55) * TINDEX, keyword: Indices. (line 6) -* TITLE, keyword: Export Settings. (line 60) +* TITLE, keyword: Export Settings. (line 75) * title, macro: Macro Replacement. (line 41) * toc, in OPTIONS keyword: Table of Contents. (line 6) * TOC, keyword: Table of Contents. (line 24) @@ -21254,7 +22069,7 @@ D Main Index * TODO items: TODO Items. (line 6) * TODO keyword matching: Global TODO list. (line 18) * TODO keyword matching, with tags search: Matching tags and properties. - (line 65) + (line 63) * TODO keyword sets: Multiple sets in one file. (line 6) * TODO keywords completion: Completion. (line 6) @@ -21263,7 +22078,7 @@ D Main Index * TODO workflow: Workflow states. (line 6) * todo, as an agenda view: Storing searches. (line 11) * TODO, keyword: Per-file keywords. (line 6) -* TODO, keyword <1>: In-buffer Settings. (line 192) +* TODO, keyword <1>: In-buffer Settings. (line 207) * TODO, special property: Special Properties. (line 13) * todo-tree: Storing searches. (line 11) * top headline filtering, in agenda: Filtering/limiting agenda items. @@ -21280,19 +22095,19 @@ D Main Index (line 19) * types as TODO keywords: TODO types. (line 6) * TYP_TODO, keyword: Per-file keywords. (line 6) -* TYP_TODO, keyword <1>: In-buffer Settings. (line 192) +* TYP_TODO, keyword <1>: In-buffer Settings. (line 207) * underlined text, markup rules: Emphasis and Monospace. (line 6) -* undoing remote-editing events: Agenda Commands. (line 228) +* undoing remote-editing events: Agenda Commands. (line 231) * unison: Uploading Files. (line 6) -* UNNUMBERED, property: Export Settings. (line 149) +* UNNUMBERED, property: Export Settings. (line 168) * unoconv: Extending ODT export. (line 12) * updating, table: Updating the table. (line 6) * URL links: External Links. (line 6) * Usenet links: External Links. (line 6) * using sessions in code blocks: Environment of a Code Block. - (line 280) + (line 285) * UTF-8 export: ASCII/Latin-1/UTF-8 export. (line 6) * var, header argument: Environment of a Code Block. @@ -21314,15 +22129,15 @@ D Main Index * visibility cycling, drawers: Drawers. (line 6) * VISIBILITY, property: Initial visibility. (line 20) * visible text, printing: Sparse Trees. (line 52) -* VM links: External Links. (line 109) -* Wanderlust links: External Links. (line 109) +* VM links: External Links. (line 110) +* Wanderlust links: External Links. (line 110) * weekly agenda: Weekly/daily agenda. (line 6) * windmove.el: Conflicts. (line 60) * workflow states as TODO keywords: Workflow states. (line 6) * working directory, in a code block: Environment of a Code Block. - (line 310) + (line 315) * wrap, header argument: Results of Evaluation. - (line 216) + (line 223) * xelatex: LaTeX/PDF export commands. (line 25) * yasnippet.el: Conflicts. (line 74) @@ -21342,20 +22157,20 @@ E Key Index * !: Setting Tags. (line 127) * ! (Agenda dispatcher): Stuck projects. (line 17) * # (Agenda dispatcher): Stuck projects. (line 14) -* $: Agenda Commands. (line 266) -* %: Agenda Commands. (line 380) +* $: Agenda Commands. (line 269) +* %: Agenda Commands. (line 383) * ': CDLaTeX mode. (line 57) -* *: Agenda Commands. (line 360) +* *: Agenda Commands. (line 363) * * (Agenda dispatcher): Agenda Dispatcher. (line 55) -* +: Agenda Commands. (line 285) -* ,: Agenda Commands. (line 280) -* -: Agenda Commands. (line 290) +* +: Agenda Commands. (line 288) +* ,: Agenda Commands. (line 283) +* -: Agenda Commands. (line 293) * .: The date/time prompt. (line 84) * . <1>: Agenda Commands. (line 118) * / (Agenda dispatcher): Agenda Dispatcher. (line 30) * 1..9,0: Using column view. (line 35) -* :: Agenda Commands. (line 276) +* :: Agenda Commands. (line 279) * <: Using column view. (line 67) * < <1>: The date/time prompt. (line 84) @@ -21364,7 +22179,7 @@ E Key Index * >: Using column view. (line 67) * > <1>: The date/time prompt. (line 84) -* > <2>: Agenda Commands. (line 329) +* > <2>: Agenda Commands. (line 332) * ? (Agenda dispatcher): Pulling from the mobile application. (line 39) * [: Agenda Commands. (line 142) @@ -21373,14 +22188,14 @@ E Key Index * `: CDLaTeX mode. (line 51) * a: Using column view. (line 57) * A: Agenda Commands. (line 64) -* a <1>: Agenda Commands. (line 253) +* a <1>: Agenda Commands. (line 256) * a (Agenda dispatcher): Weekly/daily agenda. (line 10) * b: Agenda Commands. (line 115) -* B: Agenda Commands. (line 384) +* B: Agenda Commands. (line 387) * C: Resolving idle time. (line 46) -* c: Agenda Commands. (line 448) -* c <1>: Agenda Commands. (line 451) -* C <1>: Agenda Commands. (line 482) +* c: Agenda Commands. (line 451) +* c <1>: Agenda Commands. (line 454) +* C <1>: Agenda Commands. (line 485) * C (Agenda dispatcher): Storing searches. (line 11) * C (Capture menu: Capture templates. (line 11) * C-#: Advanced features. (line 11) @@ -21392,23 +22207,23 @@ E Key Index * C-2 C-c C-w: Refile and Copy. (line 38) * C-3 C-c C-w: Refile and Copy. (line 41) * C-c !: Creating Timestamps. (line 25) -* C-c #: Checkboxes. (line 98) +* C-c #: Checkboxes. (line 121) * C-c $: Moving subtrees. (line 10) -* C-c %: Handling Links. (line 141) -* C-c &: Handling Links. (line 146) +* C-c %: Handling Links. (line 161) +* C-c &: Handling Links. (line 166) * C-c ': Editing and debugging formulas. (line 37) * C-c ' <1>: Literal Examples. (line 102) -* C-c ' <2>: Include Files. (line 63) +* C-c ' <2>: Include Files. (line 65) * C-c ' <3>: Editing Source Code. (line 6) -* C-c ' <4>: Cooperation. (line 59) -* C-c *: Structure Editing. (line 129) -* C-c * <1>: Plain Lists. (line 143) +* C-c ' <4>: Cooperation. (line 63) +* C-c *: Structure Editing. (line 131) +* C-c * <1>: Plain Lists. (line 144) * C-c * <2>: Updating the table. (line 14) * C-c +: Built-in Table Editor. (line 182) * C-c ,: Priorities. (line 33) -* C-c -: Plain Lists. (line 131) +* C-c -: Plain Lists. (line 132) * C-c - <1>: Built-in Table Editor. (line 127) * C-c .: Creating Timestamps. (line 11) @@ -21423,7 +22238,7 @@ E Key Index (line 26) * C-c / m: Tag Searches. (line 10) * C-c / m <1>: Property Searches. (line 11) -* C-c / p: Property Searches. (line 29) +* C-c / p: Property Searches. (line 28) * C-c / r: Sparse Trees. (line 20) * C-c / t: TODO Basics. (line 35) * C-c ;: Comment Lines. (line 20) @@ -21435,11 +22250,11 @@ E Key Index * C-c ?: Editing and debugging formulas. (line 25) * C-c @: Structure Editing. (line 66) -* C-c C-*: Plain Lists. (line 148) +* C-c C-*: Plain Lists. (line 149) * C-c C-,: Structure Templates. (line 11) * C-c C-a: Attachment defaults and dispatcher. (line 20) -* C-c C-a <1>: Agenda Commands. (line 301) +* C-c C-a <1>: Agenda Commands. (line 304) * C-c C-a a: Attachment defaults and dispatcher. (line 25) * C-c C-a b: Attachment defaults and dispatcher. @@ -21472,7 +22287,7 @@ E Key Index (line 42) * C-c C-b: Motion. (line 18) * C-c C-b <1>: Editing support. (line 12) -* C-c C-c: Plain Lists. (line 126) +* C-c C-c: Plain Lists. (line 127) * C-c C-c <1>: Built-in Table Editor. (line 61) * C-c C-c <2>: Column Width and Alignment. @@ -21483,14 +22298,14 @@ E Key Index (line 91) * C-c C-c <5>: Editing and debugging formulas. (line 98) -* C-c C-c <6>: Checkboxes. (line 52) +* C-c C-c <6>: Checkboxes. (line 75) * C-c C-c <7>: Setting Tags. (line 20) * C-c C-c <8>: Setting Tags. (line 131) * C-c C-c <9>: Property Syntax. (line 100) * C-c C-c <10>: Using column view. (line 26) * C-c C-c <11>: Using column view. (line 49) * C-c C-c <12>: Capturing column view. - (line 80) + (line 88) * C-c C-c <13>: Creating Timestamps. (line 29) * C-c C-c <14>: Clocking commands. (line 53) * C-c C-c <15>: The clock table. (line 20) @@ -21505,26 +22320,28 @@ E Key Index * C-c C-c c: Property Syntax. (line 117) * C-c C-c d: Property Syntax. (line 111) * C-c C-c D: Property Syntax. (line 114) -* C-c C-c m m: Markdown Export. (line 17) -* C-c C-c m M: Markdown Export. (line 21) +* C-c C-c m m: Markdown Export. (line 23) +* C-c C-c m M: Markdown Export. (line 27) * C-c C-c s: Property Syntax. (line 103) * C-c C-d: Inserting deadline/schedule. (line 10) -* C-c C-d <1>: Agenda Commands. (line 308) +* C-c C-d <1>: Agenda Commands. (line 311) * C-c C-e: The Export Dispatcher. (line 16) -* C-c C-e c a: iCalendar Export. (line 43) -* C-c C-e c c: iCalendar Export. (line 47) -* C-c C-e c f: iCalendar Export. (line 39) +* C-c C-e c a: iCalendar Export. (line 47) +* C-c C-e c c: iCalendar Export. (line 51) +* C-c C-e c f: iCalendar Export. (line 43) * C-c C-e C-a: The Export Dispatcher. (line 28) * C-c C-e C-b: The Export Dispatcher. (line 46) +* C-c C-e C-f: The Export Dispatcher. + (line 55) * C-c C-e C-s: The Export Dispatcher. - (line 52) + (line 67) * C-c C-e C-v: Sparse Trees. (line 52) * C-c C-e C-v <1>: The Export Dispatcher. - (line 64) + (line 79) * C-c C-e h h: HTML export commands. (line 7) * C-c C-e h H: HTML export commands. @@ -21551,11 +22368,11 @@ E Key Index (line 16) * C-c C-e l p: LaTeX/PDF export commands. (line 14) -* C-c C-e m o: Markdown Export. (line 24) +* C-c C-e m o: Markdown Export. (line 30) * C-c C-e o o: ODT export commands. (line 7) * C-c C-e o O: ODT export commands. (line 23) -* C-c C-e O o: Org Export. (line 15) -* C-c C-e O v: Org Export. (line 19) +* C-c C-e O o: Org Export. (line 14) +* C-c C-e O v: Org Export. (line 18) * C-c C-e P a: Triggering Publication. (line 19) * C-c C-e P f: Triggering Publication. @@ -21581,10 +22398,10 @@ E Key Index * C-c C-k: Global and local cycling. (line 52) * C-c C-k (Capture buffer): Using capture. (line 31) -* C-c C-l: Handling Links. (line 71) +* C-c C-l: Handling Links. (line 91) * C-c C-M-w: Refile and Copy. (line 55) * C-c C-n: Motion. (line 9) -* C-c C-o: Handling Links. (line 108) +* C-c C-o: Handling Links. (line 128) * C-c C-o <1>: Creating Timestamps. (line 40) * C-c C-o <2>: Agenda Commands. (line 56) * C-c C-o <3>: Creating Footnotes. (line 71) @@ -21600,9 +22417,9 @@ E Key Index (line 52) * C-c C-s: Inserting deadline/schedule. (line 18) -* C-c C-s <1>: Agenda Commands. (line 304) +* C-c C-s <1>: Agenda Commands. (line 307) * C-c C-t: TODO Basics. (line 14) -* C-c C-t <1>: Clocking commands. (line 71) +* C-c C-t <1>: Clocking commands. (line 74) * C-c C-TAB: Internal archiving. (line 51) * C-c C-u: Motion. (line 21) * C-c C-v a: Key bindings and Useful Functions. @@ -21650,7 +22467,7 @@ E Key Index * C-c C-v C-u: Key bindings and Useful Functions. (line 20) * C-c C-v C-v: Noweb Reference Syntax. - (line 219) + (line 222) * C-c C-v C-v <1>: Key bindings and Useful Functions. (line 20) * C-c C-v C-x: Key bindings and Useful Functions. @@ -21697,16 +22514,16 @@ E Key Index * C-c C-v u: Key bindings and Useful Functions. (line 20) * C-c C-v v: Noweb Reference Syntax. - (line 219) + (line 222) * C-c C-v v <1>: Key bindings and Useful Functions. (line 20) * C-c C-v x: Key bindings and Useful Functions. (line 20) * C-c C-v z: Key bindings and Useful Functions. (line 20) -* C-c C-w: Structure Editing. (line 104) +* C-c C-w: Structure Editing. (line 106) * C-c C-w <1>: Refile and Copy. (line 13) -* C-c C-w <2>: Agenda Commands. (line 250) +* C-c C-w <2>: Agenda Commands. (line 253) * C-c C-w (Capture buffer): Using capture. (line 22) * C-c C-x ,: Timers. (line 44) * C-c C-x -: Timers. (line 36) @@ -21715,39 +22532,41 @@ E Key Index * C-c C-x ;: Timers. (line 23) * C-c C-x <: Agenda Files. (line 43) * C-c C-x >: Agenda Files. (line 52) -* C-c C-x > <1>: Agenda Commands. (line 207) -* C-c C-x @: Citations. (line 14) +* C-c C-x > <1>: Agenda Commands. (line 210) +* C-c C-x @: Citations. (line 17) * C-c C-x a: Internal archiving. (line 39) * C-c C-x A: Internal archiving. (line 54) -* C-c C-x a <1>: Agenda Commands. (line 258) -* C-c C-x A <1>: Agenda Commands. (line 262) +* C-c C-x a <1>: Agenda Commands. (line 261) +* C-c C-x A <1>: Agenda Commands. (line 265) * C-c C-x b: Global and local cycling. (line 59) * C-c C-x b <1>: Agenda Commands. (line 49) -* C-c C-x c: Structure Editing. (line 96) +* C-c C-x c: Structure Editing. (line 98) * C-c C-x C-a: Archiving. (line 12) -* C-c C-x C-a <1>: Agenda Commands. (line 253) -* C-c C-x C-b: Checkboxes. (line 58) +* C-c C-x C-a <1>: Agenda Commands. (line 256) +* C-c C-x C-b: Checkboxes. (line 81) * C-c C-x C-c: Using column view. (line 10) -* C-c C-x C-c <1>: Agenda Commands. (line 198) +* C-c C-x C-c <1>: Agenda Commands. (line 201) * C-c C-x C-c <2>: Agenda Column View. (line 12) -* C-c C-x C-d: Clocking commands. (line 84) +* C-c C-x C-d: Clocking commands. (line 87) * C-c C-x C-e: Clocking commands. (line 50) * C-c C-x C-e <1>: Effort Estimates. (line 24) +* C-c C-x C-f: Emphasis and Monospace. + (line 13) * C-c C-x C-i: Clocking commands. (line 7) -* C-c C-x C-j: Clocking commands. (line 79) +* C-c C-x C-j: Clocking commands. (line 82) * C-c C-x C-l: Previewing LaTeX fragments. (line 18) -* C-c C-x C-n: Handling Links. (line 153) +* C-c C-x C-n: Handling Links. (line 173) * C-c C-x C-o: Clocking commands. (line 36) -* C-c C-x C-p: Handling Links. (line 153) -* C-c C-x C-q: Clocking commands. (line 75) -* C-c C-x C-r: Checkboxes. (line 75) +* C-c C-x C-p: Handling Links. (line 173) +* C-c C-x C-q: Clocking commands. (line 78) +* C-c C-x C-r: Checkboxes. (line 98) * C-c C-x C-s: Moving subtrees. (line 10) -* C-c C-x C-s <1>: Agenda Commands. (line 266) +* C-c C-x C-s <1>: Agenda Commands. (line 269) * C-c C-x C-t: Custom time format. (line 13) * C-c C-x C-u: Capturing column view. - (line 80) + (line 88) * C-c C-x C-u <1>: The clock table. (line 20) * C-c C-x C-u <2>: Dynamic Blocks. (line 25) * C-c C-x C-v: Images. (line 24) @@ -21760,7 +22579,7 @@ E Key Index (line 162) * C-c C-x d: Drawers. (line 18) * C-c C-x e: Effort Estimates. (line 19) -* C-c C-x e <1>: Agenda Commands. (line 293) +* C-c C-x e <1>: Agenda Commands. (line 296) * C-c C-x f: Creating Footnotes. (line 42) * C-c C-x g: RSS Feeds. (line 23) * C-c C-x G: RSS Feeds. (line 27) @@ -21770,7 +22589,7 @@ E Key Index * C-c C-x M-w <1>: Built-in Table Editor. (line 152) * C-c C-x o: TODO dependencies. (line 38) -* C-c C-x o <1>: Checkboxes. (line 90) +* C-c C-x o <1>: Checkboxes. (line 113) * C-c C-x p: Property Syntax. (line 90) * C-c C-x p <1>: Using Header Arguments. (line 90) @@ -21778,17 +22597,17 @@ E Key Index * C-c C-x v: Global and local cycling. (line 65) * C-c C-x x: Capturing column view. - (line 72) + (line 80) * C-c C-x x <1>: The clock table. (line 11) * C-c C-x x <2>: Dynamic Blocks. (line 10) * C-c C-x \: Subscripts and Superscripts. - (line 27) + (line 29) * C-c C-x \ <1>: Special Symbols. (line 31) * C-c C-x _: Timers. (line 47) * C-c C-y: Creating Timestamps. (line 62) * C-c C-y <1>: Clocking commands. (line 53) * C-c C-z: Drawers. (line 40) -* C-c C-z <1>: Agenda Commands. (line 296) +* C-c C-z <1>: Agenda Commands. (line 299) * C-c M-w: Refile and Copy. (line 51) * C-c RET: Built-in Table Editor. (line 131) @@ -21800,8 +22619,8 @@ E Key Index * C-c \: Tag Searches. (line 10) * C-c \ <1>: Property Searches. (line 11) * C-c ]: Agenda Files. (line 22) -* C-c ^: Structure Editing. (line 108) -* C-c ^ <1>: Plain Lists. (line 159) +* C-c ^: Structure Editing. (line 110) +* C-c ^ <1>: Plain Lists. (line 160) * C-c ^ <2>: Built-in Table Editor. (line 135) * C-c `: Built-in Table Editor. @@ -21817,18 +22636,18 @@ E Key Index (line 29) * C-c } <1>: Editing and debugging formulas. (line 83) -* C-c ~: Cooperation. (line 63) +* C-c ~: Cooperation. (line 67) * C-g: Setting Tags. (line 121) -* C-k: Agenda Commands. (line 244) +* C-k: Agenda Commands. (line 247) * C-RET: Structure Editing. (line 26) * C-S-DOWN: Clocking commands. (line 59) * C-S-LEFT: Multiple sets in one file. (line 28) -* C-S-LEFT <1>: Agenda Commands. (line 241) +* C-S-LEFT <1>: Agenda Commands. (line 244) * C-S-RET: Structure Editing. (line 33) * C-S-RIGHT: Multiple sets in one file. (line 28) -* C-S-RIGHT <1>: Agenda Commands. (line 238) +* C-S-RIGHT <1>: Agenda Commands. (line 241) * C-S-UP: Clocking commands. (line 59) * C-u C-c !: Creating Timestamps. (line 25) * C-u C-c *: Updating the table. (line 19) @@ -21838,13 +22657,13 @@ E Key Index * C-u C-c = <1>: Editing and debugging formulas. (line 14) * C-u C-c C-c: Updating the table. (line 19) -* C-u C-c C-l: Handling Links. (line 94) +* C-u C-c C-l: Handling Links. (line 114) * C-u C-c C-t: Progress Logging. (line 10) * C-u C-c C-w: Refile and Copy. (line 32) * C-u C-c C-x a: Internal archiving. (line 44) * C-u C-c C-x C-s: Moving subtrees. (line 14) * C-u C-c C-x C-u: Capturing column view. - (line 84) + (line 92) * C-u C-c C-x C-u <1>: The clock table. (line 24) * C-u C-c C-x C-u <2>: Dynamic Blocks. (line 28) * C-u C-c TAB: Column Width and Alignment. @@ -21874,40 +22693,40 @@ E Key Index (line 84) * C-x C-s: Editing and debugging formulas. (line 45) -* C-x C-s <1>: Agenda Commands. (line 194) +* C-x C-s <1>: Agenda Commands. (line 197) * C-x C-s <2>: Editing Source Code. (line 11) * C-x C-w: Exporting Agenda Views. (line 13) -* C-x n b: Structure Editing. (line 123) -* C-x n s: Structure Editing. (line 120) -* C-x n w: Structure Editing. (line 126) -* C-y: Structure Editing. (line 84) -* C-_: Agenda Commands. (line 228) +* C-x n b: Structure Editing. (line 125) +* C-x n s: Structure Editing. (line 122) +* C-x n w: Structure Editing. (line 128) +* C-y: Structure Editing. (line 86) +* C-_: Agenda Commands. (line 231) * d: Agenda Commands. (line 71) * D: Agenda Commands. (line 127) * e: Using column view. (line 43) -* E: Agenda Commands. (line 174) -* e <1>: Agenda Commands. (line 293) +* E: Agenda Commands. (line 177) +* e <1>: Agenda Commands. (line 296) * e (Agenda dispatcher): Exporting Agenda Views. (line 53) * F: Agenda Commands. (line 42) * f: Agenda Commands. (line 110) * g: Using column view. (line 22) -* G: Agenda Commands. (line 182) -* g <1>: Agenda Commands. (line 187) -* H: Agenda Commands. (line 486) -* I: Agenda Commands. (line 333) -* i: Agenda Commands. (line 455) +* G: Agenda Commands. (line 185) +* g <1>: Agenda Commands. (line 190) +* H: Agenda Commands. (line 489) +* I: Agenda Commands. (line 336) +* i: Agenda Commands. (line 458) * j: Agenda Commands. (line 121) * J: Agenda Commands. (line 124) -* J <1>: Agenda Commands. (line 343) +* J <1>: Agenda Commands. (line 346) * k: Resolving idle time. (line 23) * K: Resolving idle time. (line 29) -* k <1>: Agenda Commands. (line 346) +* k <1>: Agenda Commands. (line 349) * k c (Agenda): Using capture. (line 33) * l: Agenda Commands. (line 131) -* m: Agenda Commands. (line 354) -* M: Agenda Commands. (line 473) +* m: Agenda Commands. (line 357) +* M: Agenda Commands. (line 476) * m (Agenda dispatcher): Tag Searches. (line 15) * M (Agenda dispatcher): Tag Searches. (line 19) * m (Agenda dispatcher) <1>: Property Searches. (line 15) @@ -21916,17 +22735,18 @@ E Key Index (line 13) * M (Agenda dispatcher) <2>: Matching tags and properties. (line 21) -* M-*: Agenda Commands. (line 376) +* M-*: Agenda Commands. (line 379) * M-a: Built-in Table Editor. (line 79) * M-DOWN: Structure Editing. (line 63) -* M-DOWN <1>: Plain Lists. (line 102) +* M-DOWN <1>: Plain Lists. (line 103) * M-DOWN <2>: Built-in Table Editor. (line 105) * M-DOWN <3>: Editing and debugging formulas. (line 80) -* M-DOWN <4>: Agenda Commands. (line 218) -* M-DOWN <5>: Key bindings and Useful Functions. +* M-DOWN <4>: Using column view. (line 85) +* M-DOWN <5>: Agenda Commands. (line 221) +* M-DOWN <6>: Key bindings and Useful Functions. (line 11) * M-e: Built-in Table Editor. (line 83) @@ -21935,34 +22755,36 @@ E Key Index * M-g n: Sparse Trees. (line 32) * M-g p: Sparse Trees. (line 35) * M-LEFT: Structure Editing. (line 44) -* M-LEFT <1>: Plain Lists. (line 108) +* M-LEFT <1>: Plain Lists. (line 109) * M-LEFT <2>: Built-in Table Editor. (line 89) -* M-m: Agenda Commands. (line 372) +* M-LEFT <3>: Using column view. (line 76) +* M-m: Agenda Commands. (line 375) * M-RET: Structure Editing. (line 7) -* M-RET <1>: Plain Lists. (line 83) +* M-RET <1>: Plain Lists. (line 84) * M-RET <2>: Built-in Table Editor. (line 169) * M-RET <3>: Timers. (line 40) * M-RIGHT: Structure Editing. (line 44) -* M-RIGHT <1>: Plain Lists. (line 108) +* M-RIGHT <1>: Plain Lists. (line 109) * M-RIGHT <2>: Built-in Table Editor. (line 92) +* M-RIGHT <3>: Using column view. (line 79) * M-S-DOWN: Built-in Table Editor. (line 123) * M-S-DOWN <1>: Editing and debugging formulas. (line 74) * M-S-LEFT: Structure Editing. (line 54) -* M-S-LEFT <1>: Plain Lists. (line 113) +* M-S-LEFT <1>: Plain Lists. (line 114) * M-S-LEFT <2>: Built-in Table Editor. (line 95) * M-S-LEFT <3>: The date/time prompt. (line 84) * M-S-RET: Structure Editing. (line 29) -* M-S-RET <1>: Plain Lists. (line 91) -* M-S-RET <2>: Checkboxes. (line 86) +* M-S-RET <1>: Plain Lists. (line 92) +* M-S-RET <2>: Checkboxes. (line 109) * M-S-RIGHT: Structure Editing. (line 57) -* M-S-RIGHT <1>: Plain Lists. (line 113) +* M-S-RIGHT <1>: Plain Lists. (line 114) * M-S-RIGHT <2>: Built-in Table Editor. (line 98) * M-S-RIGHT <3>: The date/time prompt. @@ -21978,52 +22800,53 @@ E Key Index * M-TAB <3>: Property Syntax. (line 86) * M-TAB <4>: Completion. (line 15) * M-UP: Structure Editing. (line 60) -* M-UP <1>: Plain Lists. (line 102) +* M-UP <1>: Plain Lists. (line 103) * M-UP <2>: Built-in Table Editor. (line 102) * M-UP <3>: Editing and debugging formulas. (line 77) -* M-UP <4>: Agenda Commands. (line 211) -* M-UP <5>: Key bindings and Useful Functions. +* M-UP <4>: Using column view. (line 82) +* M-UP <5>: Agenda Commands. (line 214) +* M-UP <6>: Key bindings and Useful Functions. (line 11) * M-v: The date/time prompt. (line 84) -* mouse-1: Handling Links. (line 133) +* mouse-1: Handling Links. (line 153) * mouse-1 <1>: The date/time prompt. (line 84) * mouse-1 <2>: Creating Footnotes. (line 71) -* mouse-2: Handling Links. (line 133) +* mouse-2: Handling Links. (line 153) * mouse-2 <1>: Agenda Commands. (line 36) * mouse-2 <2>: Creating Footnotes. (line 71) -* mouse-3: Handling Links. (line 137) +* mouse-3: Handling Links. (line 157) * mouse-3 <1>: Agenda Commands. (line 29) * n: Using column view. (line 39) * n <1>: Agenda Commands. (line 20) * o: Agenda Commands. (line 68) -* O: Agenda Commands. (line 337) +* O: Agenda Commands. (line 340) * p: Using column view. (line 39) * p <1>: Agenda Commands. (line 23) * q: Setting Tags. (line 124) * q <1>: Using column view. (line 26) -* q <2>: Agenda Commands. (line 492) +* q <2>: Agenda Commands. (line 495) * r: Using column view. (line 22) * r <1>: Global TODO list. (line 25) -* R: Agenda Commands. (line 154) -* r <2>: Agenda Commands. (line 187) +* R: Agenda Commands. (line 157) +* r <2>: Agenda Commands. (line 190) * RET: Built-in Table Editor. (line 74) -* RET <1>: Handling Links. (line 129) +* RET <1>: Handling Links. (line 149) * RET <2>: Setting Tags. (line 118) * RET <3>: The date/time prompt. (line 84) * RET <4>: Agenda Commands. (line 39) * s: Resolving idle time. (line 35) * S: Resolving idle time. (line 40) -* s <1>: Agenda Commands. (line 194) -* S <1>: Agenda Commands. (line 477) +* s <1>: Agenda Commands. (line 197) +* S <1>: Agenda Commands. (line 480) * s (Agenda dispatcher): Agenda Dispatcher. (line 25) * s (Agenda dispatcher) <1>: Search view. (line 10) -* S-DOWN: Plain Lists. (line 95) +* S-DOWN: Plain Lists. (line 96) * S-DOWN <1>: Built-in Table Editor. (line 114) * S-DOWN <2>: Editing and debugging formulas. @@ -22032,8 +22855,8 @@ E Key Index * S-DOWN <4>: Creating Timestamps. (line 50) * S-DOWN <5>: The date/time prompt. (line 84) -* S-DOWN <6>: Agenda Commands. (line 290) -* S-LEFT: Plain Lists. (line 154) +* S-DOWN <6>: Agenda Commands. (line 293) +* S-LEFT: Plain Lists. (line 155) * S-LEFT <1>: Built-in Table Editor. (line 117) * S-LEFT <2>: Editing and debugging formulas. @@ -22047,7 +22870,7 @@ E Key Index * S-LEFT <8>: The date/time prompt. (line 84) * S-LEFT <9>: The clock table. (line 29) -* S-LEFT <10>: Agenda Commands. (line 325) +* S-LEFT <10>: Agenda Commands. (line 328) * S-M-DOWN: Clocking commands. (line 64) * S-M-LEFT: Using column view. (line 73) * S-M-RET: TODO Basics. (line 54) @@ -22055,7 +22878,7 @@ E Key Index * S-M-UP: Clocking commands. (line 64) * S-RET: Built-in Table Editor. (line 187) -* S-RIGHT: Plain Lists. (line 154) +* S-RIGHT: Plain Lists. (line 155) * S-RIGHT <1>: Built-in Table Editor. (line 120) * S-RIGHT <2>: Editing and debugging formulas. @@ -22069,12 +22892,12 @@ E Key Index * S-RIGHT <8>: The date/time prompt. (line 84) * S-RIGHT <9>: The clock table. (line 29) -* S-RIGHT <10>: Agenda Commands. (line 312) +* S-RIGHT <10>: Agenda Commands. (line 315) * S-TAB: Global and local cycling. (line 20) * S-TAB <1>: Built-in Table Editor. (line 71) -* S-UP: Plain Lists. (line 95) +* S-UP: Plain Lists. (line 96) * S-UP <1>: Built-in Table Editor. (line 111) * S-UP <2>: Editing and debugging formulas. @@ -22083,18 +22906,18 @@ E Key Index * S-UP <4>: Creating Timestamps. (line 50) * S-UP <5>: The date/time prompt. (line 84) -* S-UP <6>: Agenda Commands. (line 285) +* S-UP <6>: Agenda Commands. (line 288) * SPC: Setting Tags. (line 115) * SPC <1>: Agenda Commands. (line 29) -* t: Agenda Commands. (line 232) -* T: Agenda Commands. (line 271) +* t: Agenda Commands. (line 235) +* T: Agenda Commands. (line 274) * t (Agenda dispatcher): TODO Basics. (line 46) * t (Agenda dispatcher) <1>: Global TODO list. (line 10) * T (Agenda dispatcher): Global TODO list. (line 18) * TAB: Global and local cycling. (line 11) * TAB <1>: Structure Editing. (line 37) -* TAB <2>: Plain Lists. (line 70) +* TAB <2>: Plain Lists. (line 71) * TAB <3>: Built-in Table Editor. (line 64) * TAB <4>: Editing and debugging formulas. @@ -22102,26 +22925,26 @@ E Key Index * TAB <5>: Setting Tags. (line 108) * TAB <6>: Agenda Commands. (line 36) * TAB <7>: CDLaTeX mode. (line 29) -* u: Agenda Commands. (line 364) -* U: Agenda Commands. (line 368) +* u: Agenda Commands. (line 367) +* U: Agenda Commands. (line 371) * v: Using column view. (line 53) * v a: Agenda Commands. (line 146) -* v A: Agenda Commands. (line 151) -* v c: Agenda Commands. (line 166) +* v A: Agenda Commands. (line 154) +* v c: Agenda Commands. (line 169) * v d: Agenda Commands. (line 71) -* v E: Agenda Commands. (line 174) +* v E: Agenda Commands. (line 177) * v l: Agenda Commands. (line 131) * v L: Agenda Commands. (line 131) * v m: Agenda Commands. (line 91) -* v R: Agenda Commands. (line 154) +* v R: Agenda Commands. (line 157) * v SPC: Agenda Commands. (line 107) * v w: Agenda Commands. (line 81) * v y: Agenda Commands. (line 101) * v [: Agenda Commands. (line 142) * w: Agenda Commands. (line 81) -* X: Agenda Commands. (line 340) -* x: Agenda Commands. (line 496) -* z: Agenda Commands. (line 296) +* X: Agenda Commands. (line 343) +* x: Agenda Commands. (line 499) +* z: Agenda Commands. (line 299)  File: org.info, Node: Command and Function Index, Next: Variable Index, Prev: Key Index, Up: Top @@ -22135,43 +22958,43 @@ F Command and Function Index * lisp-complete-symbol: Editing and debugging formulas. (line 63) * next-error: Sparse Trees. (line 32) -* or-clock-goto: Clocking commands. (line 79) +* or-clock-goto: Clocking commands. (line 82) * org-agenda: Activation. (line 13) -* org-agenda-add-note: Agenda Commands. (line 296) -* org-agenda-archive: Agenda Commands. (line 266) +* org-agenda-add-note: Agenda Commands. (line 299) +* org-agenda-archive: Agenda Commands. (line 269) * org-agenda-archive-default-with-confirmation: Agenda Commands. - (line 253) -* org-agenda-archive-to-archive-sibling: Agenda Commands. (line 262) + (line 256) +* org-agenda-archive-to-archive-sibling: Agenda Commands. (line 265) * org-agenda-archives-mode: Agenda Commands. (line 146) -* org-agenda-bulk-action: Agenda Commands. (line 384) -* org-agenda-bulk-mark: Agenda Commands. (line 354) -* org-agenda-bulk-mark-all: Agenda Commands. (line 360) -* org-agenda-bulk-mark-regexp: Agenda Commands. (line 380) -* org-agenda-bulk-toggle: Agenda Commands. (line 372) -* org-agenda-bulk-toggle-all: Agenda Commands. (line 376) -* org-agenda-bulk-unmark: Agenda Commands. (line 364) -* org-agenda-bulk-unmark-all: Agenda Commands. (line 368) -* org-agenda-capture: Agenda Commands. (line 346) -* org-agenda-clock-cancel: Agenda Commands. (line 340) +* org-agenda-bulk-action: Agenda Commands. (line 387) +* org-agenda-bulk-mark: Agenda Commands. (line 357) +* org-agenda-bulk-mark-all: Agenda Commands. (line 363) +* org-agenda-bulk-mark-regexp: Agenda Commands. (line 383) +* org-agenda-bulk-toggle: Agenda Commands. (line 375) +* org-agenda-bulk-toggle-all: Agenda Commands. (line 379) +* org-agenda-bulk-unmark: Agenda Commands. (line 367) +* org-agenda-bulk-unmark-all: Agenda Commands. (line 371) +* org-agenda-capture: Agenda Commands. (line 349) +* org-agenda-clock-cancel: Agenda Commands. (line 343) * org-agenda-clock-goto: Agenda Commands. (line 124) -* org-agenda-clock-goto <1>: Agenda Commands. (line 343) -* org-agenda-clock-in: Agenda Commands. (line 333) -* org-agenda-clock-out: Agenda Commands. (line 337) -* org-agenda-clockreport-mode: Agenda Commands. (line 154) -* org-agenda-columns: Agenda Commands. (line 198) +* org-agenda-clock-goto <1>: Agenda Commands. (line 346) +* org-agenda-clock-in: Agenda Commands. (line 336) +* org-agenda-clock-out: Agenda Commands. (line 340) +* org-agenda-clockreport-mode: Agenda Commands. (line 157) +* org-agenda-columns: Agenda Commands. (line 201) * org-agenda-columns <1>: Agenda Column View. (line 12) -* org-agenda-convert-date: Agenda Commands. (line 482) -* org-agenda-date-prompt: Agenda Commands. (line 329) +* org-agenda-convert-date: Agenda Commands. (line 485) +* org-agenda-date-prompt: Agenda Commands. (line 332) * org-agenda-day-view: Agenda Commands. (line 71) -* org-agenda-deadline: Agenda Commands. (line 308) -* org-agenda-diary-entry: Agenda Commands. (line 455) -* org-agenda-do-date-earlier: Agenda Commands. (line 325) -* org-agenda-do-date-later: Agenda Commands. (line 312) -* org-agenda-drag-line-backward: Agenda Commands. (line 211) -* org-agenda-drag-line-forward: Agenda Commands. (line 218) +* org-agenda-deadline: Agenda Commands. (line 311) +* org-agenda-diary-entry: Agenda Commands. (line 458) +* org-agenda-do-date-earlier: Agenda Commands. (line 328) +* org-agenda-do-date-later: Agenda Commands. (line 315) +* org-agenda-drag-line-backward: Agenda Commands. (line 214) +* org-agenda-drag-line-forward: Agenda Commands. (line 221) * org-agenda-earlier: Agenda Commands. (line 115) -* org-agenda-entry-text-mode: Agenda Commands. (line 174) -* org-agenda-exit: Agenda Commands. (line 496) +* org-agenda-entry-text-mode: Agenda Commands. (line 177) +* org-agenda-exit: Agenda Commands. (line 499) * org-agenda-file-to-front: Agenda Files. (line 16) * org-agenda-filter: Filtering/limiting agenda items. (line 73) @@ -22187,11 +23010,11 @@ F Command and Function Index (line 68) * org-agenda-follow-mode: Agenda Commands. (line 42) * org-agenda-goto: Agenda Commands. (line 36) -* org-agenda-goto-calendar: Agenda Commands. (line 448) +* org-agenda-goto-calendar: Agenda Commands. (line 451) * org-agenda-goto-date: Agenda Commands. (line 121) * org-agenda-goto-today: Agenda Commands. (line 118) -* org-agenda-holidays: Agenda Commands. (line 486) -* org-agenda-kill: Agenda Commands. (line 244) +* org-agenda-holidays: Agenda Commands. (line 489) +* org-agenda-kill: Agenda Commands. (line 247) * org-agenda-later: Agenda Commands. (line 110) * org-agenda-limit-interactively: Filtering/limiting agenda items. (line 165) @@ -22202,56 +23025,54 @@ F Command and Function Index * org-agenda-month-view: Agenda Commands. (line 91) * org-agenda-next-line: Agenda Commands. (line 20) * org-agenda-open-link: Agenda Commands. (line 56) -* org-agenda-phases-of-moon: Agenda Commands. (line 473) +* org-agenda-phases-of-moon: Agenda Commands. (line 476) * org-agenda-previous-line: Agenda Commands. (line 23) -* org-agenda-priority: Agenda Commands. (line 280) -* org-agenda-priority-down: Agenda Commands. (line 290) -* org-agenda-priority-up: Agenda Commands. (line 285) -* org-agenda-quit: Agenda Commands. (line 492) +* org-agenda-priority: Agenda Commands. (line 283) +* org-agenda-priority-down: Agenda Commands. (line 293) +* org-agenda-priority-up: Agenda Commands. (line 288) +* org-agenda-quit: Agenda Commands. (line 495) * org-agenda-recenter: Agenda Commands. (line 33) -* org-agenda-redo: Agenda Commands. (line 187) -* org-agenda-refile: Agenda Commands. (line 250) +* org-agenda-redo: Agenda Commands. (line 190) +* org-agenda-refile: Agenda Commands. (line 253) * org-agenda-remove-restriction-lock: Agenda Files. (line 52) * org-agenda-remove-restriction-lock <1>: Agenda Files. (line 65) -* org-agenda-remove-restriction-lock <2>: Agenda Commands. (line 207) +* org-agenda-remove-restriction-lock <2>: Agenda Commands. (line 210) * org-agenda-reset-view: Agenda Commands. (line 107) -* org-agenda-schedule: Agenda Commands. (line 304) -* org-agenda-set-effort: Agenda Commands. (line 293) +* org-agenda-schedule: Agenda Commands. (line 307) +* org-agenda-set-effort: Agenda Commands. (line 296) * org-agenda-set-restriction-lock: Agenda Files. (line 43) -* org-agenda-set-tags: Agenda Commands. (line 276) +* org-agenda-set-tags: Agenda Commands. (line 279) * org-agenda-show-and-scroll-up: Agenda Commands. (line 29) -* org-agenda-show-tags: Agenda Commands. (line 271) +* org-agenda-show-tags: Agenda Commands. (line 274) * org-agenda-skip-entry-if: Special Agenda Views. (line 41) * org-agenda-skip-subtree-if: Special Agenda Views. (line 41) -* org-agenda-sunrise-sunset: Agenda Commands. (line 477) +* org-agenda-sunrise-sunset: Agenda Commands. (line 480) * org-agenda-switch-to: Agenda Commands. (line 39) -* org-agenda-todo: Agenda Commands. (line 232) -* org-agenda-todo-nextset: Agenda Commands. (line 238) -* org-agenda-toggle-archive-tag: Agenda Commands. (line 258) +* org-agenda-todo: Agenda Commands. (line 235) +* org-agenda-todo-nextset: Agenda Commands. (line 241) +* org-agenda-toggle-archive-tag: Agenda Commands. (line 261) * org-agenda-toggle-diary: Agenda Commands. (line 127) * org-agenda-tree-to-indirect-buffer: Agenda Commands. (line 49) -* org-agenda-undo: Agenda Commands. (line 228) +* org-agenda-undo: Agenda Commands. (line 231) * org-agenda-week-view: Agenda Commands. (line 81) * org-agenda-write: Exporting Agenda Views. (line 13) * org-agenda-year-view: Agenda Commands. (line 101) -* org-anniversary: Timestamps. (line 36) +* org-anniversary: Timestamps. (line 40) * org-archive-subtree: Moving subtrees. (line 10) * org-archive-subtree-default: Archiving. (line 12) * org-archive-to-archive-sibling: Internal archiving. (line 54) -* org-ascii-convert-region-to-ascii: Export in Foreign Buffers. - (line 11) -* org-ascii-convert-region-to-utf8: Export in Foreign Buffers. - (line 14) +* org-ascii-convert-region-to-ascii: Export Region. (line 11) +* org-ascii-convert-region-to-utf8: Export Region. (line 14) * org-ascii-export-as-ascii: ASCII/Latin-1/UTF-8 export. (line 35) * org-ascii-export-to-ascii: ASCII/Latin-1/UTF-8 export. (line 26) * org-attach: Attachment defaults and dispatcher. (line 20) -* org-attach <1>: Agenda Commands. (line 301) +* org-attach <1>: Agenda Commands. (line 304) * org-attach-attach: Attachment defaults and dispatcher. (line 25) * org-attach-buffer: Attachment defaults and dispatcher. @@ -22288,7 +23109,7 @@ F Command and Function Index * org-babel-execute-subtree: Key bindings and Useful Functions. (line 20) * org-babel-expand-src-block: Noweb Reference Syntax. - (line 219) + (line 222) * org-babel-expand-src-block <1>: Key bindings and Useful Functions. (line 20) * org-babel-goto-named-result: Key bindings and Useful Functions. @@ -22346,10 +23167,10 @@ F Command and Function Index * org-beamer-export-to-pdf: Beamer export commands. (line 16) * org-beamer-select-environment: Editing support. (line 12) -* org-block: Timestamps. (line 36) +* org-block: Timestamps. (line 40) * org-buffer-property-keys: Using the Property API. (line 34) -* org-calendar-goto-agenda: Agenda Commands. (line 451) +* org-calendar-goto-agenda: Agenda Commands. (line 454) * org-capture: Activation. (line 13) * org-capture <1>: Using capture. (line 7) * org-capture-finalize: Using capture. (line 15) @@ -22361,27 +23182,29 @@ F Command and Function Index (line 33) * org-check-deadlines: Inserting deadline/schedule. (line 26) -* org-cite-insert: Citations. (line 14) -* org-clock-cancel: Clocking commands. (line 75) -* org-clock-display: Clocking commands. (line 84) +* org-cite-insert: Citations. (line 17) +* org-clock-cancel: Clocking commands. (line 78) +* org-clock-display: Clocking commands. (line 87) * org-clock-in: Clocking commands. (line 7) * org-clock-in-last: Clocking commands. (line 44) * org-clock-modify-effort-estimate: Clocking commands. (line 50) * org-clock-modify-effort-estimate <1>: Effort Estimates. (line 24) * org-clock-out: Clocking commands. (line 36) * org-clock-report: The clock table. (line 11) -* org-clock-timestamp-down: Clocking commands. (line 64) -* org-clock-timestamp-up: Clocking commands. (line 64) * org-clock-timestamps-down: Clocking commands. (line 59) * org-clock-timestamps-up: Clocking commands. (line 59) * org-clocktable-try-shift: The clock table. (line 29) * org-clocktable-write-default: The clock table. (line 118) -* org-clone-subtree-with-time-shift: Structure Editing. (line 96) +* org-clone-subtree-with-time-shift: Structure Editing. (line 98) * org-columns-delete: Using column view. (line 73) * org-columns-edit-allowed: Using column view. (line 57) * org-columns-edit-value: Using column view. (line 43) * org-columns-insert-dblock: Capturing column view. - (line 72) + (line 80) +* org-columns-move-left: Using column view. (line 76) +* org-columns-move-right: Using column view. (line 79) +* org-columns-move-row-down: Using column view. (line 85) +* org-columns-move-row-up: Using column view. (line 82) * org-columns-narrow: Using column view. (line 67) * org-columns-new: Using column view. (line 70) * org-columns-next-allowed-value: Using column view. (line 39) @@ -22399,13 +23222,16 @@ F Command and Function Index * org-cycle: Global and local cycling. (line 11) * org-cycle <1>: Structure Editing. (line 37) -* org-cycle <2>: Plain Lists. (line 70) +* org-cycle <2>: Plain Lists. (line 71) * org-cycle-agenda-files: Agenda Files. (line 26) -* org-cyclic: Timestamps. (line 36) -* org-date: Timestamps. (line 36) +* org-cycle-set-startup-visibility: Global and local cycling. + (line 36) +* org-cycle-set-startup-visibility <1>: Initial visibility. (line 26) +* org-cyclic: Timestamps. (line 40) +* org-date: Timestamps. (line 40) * org-date-from-calendar: Creating Timestamps. (line 32) * org-dblock-update: Capturing column view. - (line 80) + (line 88) * org-dblock-update <1>: The clock table. (line 20) * org-dblock-update <2>: Dynamic Blocks. (line 25) * org-deadline: Inserting deadline/schedule. @@ -22419,8 +23245,10 @@ F Command and Function Index * org-do-promote: Structure Editing. (line 44) * org-dynamic-block-insert-dblock: Dynamic Blocks. (line 10) * org-edit-special: Literal Examples. (line 102) -* org-edit-special <1>: Include Files. (line 63) -* org-edit-special <2>: Cooperation. (line 59) +* org-edit-special <1>: Include Files. (line 65) +* org-edit-special <2>: Cooperation. (line 63) +* org-emphasize: Emphasis and Monospace. + (line 13) * org-entities-help: Special Symbols. (line 16) * org-entry-add-to-multivalued-property: Using the Property API. (line 49) @@ -22442,35 +23270,42 @@ F Command and Function Index (line 53) * org-evaluate-time-range: Creating Timestamps. (line 62) * org-evaluate-time-range <1>: Clocking commands. (line 53) -* org-export-define-backend: Adding Export Back-ends. +* org-export-as: Advanced Export Configuration. + (line 103) +* org-export-define-backend: Adding Export Backends. (line 10) -* org-export-define-derived-backend: Adding Export Back-ends. +* org-export-define-derived-backend: Adding Export Backends. (line 10) * org-export-dispatch: The Export Dispatcher. (line 16) +* org-export-region-to-ascii: Export Region. (line 11) +* org-export-region-to-html: Export Region. (line 17) +* org-export-region-to-latex: Export Region. (line 20) +* org-export-region-to-md: Export Region. (line 26) +* org-export-region-to-texinfo: Export Region. (line 23) +* org-export-region-to-utf8: Export Region. (line 14) * org-forward-heading-same-level: Motion. (line 15) * org-global-cycle: Global and local cycling. (line 20) * org-goto: Motion. (line 24) * org-goto-calendar: Creating Timestamps. (line 35) -* org-html-convert-region-to-html: Export in Foreign Buffers. - (line 17) +* org-html-convert-region-to-html: Export Region. (line 17) * org-html-export-as-html: HTML export commands. (line 13) * org-html-export-to-html: HTML export commands. (line 7) -* org-icalendar-combine-agenda-files: iCalendar Export. (line 47) -* org-icalendar-export-agenda-files: iCalendar Export. (line 43) -* org-icalendar-export-to-ics: iCalendar Export. (line 39) +* org-icalendar-combine-agenda-files: iCalendar Export. (line 51) +* org-icalendar-export-agenda-files: iCalendar Export. (line 47) +* org-icalendar-export-to-ics: iCalendar Export. (line 43) * org-indent-mode: Org Indent Mode. (line 6) * org-info-find-node: Documentation Access. (line 6) * org-insert-drawer: Drawers. (line 18) * org-insert-drawer <1>: Property Syntax. (line 94) -* org-insert-heading: Plain Lists. (line 83) +* org-insert-heading: Plain Lists. (line 84) * org-insert-heading <1>: Timers. (line 40) * org-insert-heading-respect-content: Structure Editing. (line 26) -* org-insert-link: Handling Links. (line 71) +* org-insert-link: Handling Links. (line 91) * org-insert-link-global: Using Links Outside Org. (line 6) * org-insert-property-drawer: Using the Property API. @@ -22480,10 +23315,9 @@ F Command and Function Index * org-insert-structure-template: Structure Templates. (line 11) * org-insert-todo-heading: Structure Editing. (line 29) * org-insert-todo-heading <1>: TODO Basics. (line 54) -* org-insert-todo-heading <2>: Checkboxes. (line 86) +* org-insert-todo-heading <2>: Checkboxes. (line 109) * org-insert-todo-heading-respect-content: Structure Editing. (line 33) -* org-latex-convert-region-to-latex: Export in Foreign Buffers. - (line 20) +* org-latex-convert-region-to-latex: Export Region. (line 20) * org-latex-export-as-latex: LaTeX/PDF export commands. (line 11) * org-latex-export-to-latex~: LaTeX/PDF export commands. @@ -22495,22 +23329,21 @@ F Command and Function Index * org-link-escape: Link Format. (line 25) * org-link-set-parameters: Adding Hyperlink Types. (line 74) -* org-lint: Org Syntax. (line 24) -* org-list-checkbox-radio-mode: Checkboxes. (line 81) +* org-lint: Org Syntax. (line 23) +* org-list-checkbox-radio-mode: Checkboxes. (line 104) * org-lookup-all: Lookup functions. (line 23) * org-lookup-first: Lookup functions. (line 9) * org-lookup-last: Lookup functions. (line 19) * org-map-entries: Using the Mapping API. (line 12) -* org-mark-ring-goto: Handling Links. (line 146) -* org-mark-ring-push: Handling Links. (line 141) +* org-mark-ring-goto: Handling Links. (line 166) +* org-mark-ring-push: Handling Links. (line 161) * org-mark-subtree: Structure Editing. (line 66) * org-match-sparse-tree: Tag Searches. (line 10) * org-match-sparse-tree <1>: Property Searches. (line 11) -* org-md-convert-region-to-md: Export in Foreign Buffers. - (line 26) -* org-md-export-as-markdown: Markdown Export. (line 21) -* org-md-export-to-markdown: Markdown Export. (line 17) +* org-md-convert-region-to-md: Export Region. (line 26) +* org-md-export-as-markdown: Markdown Export. (line 27) +* org-md-export-to-markdown: Markdown Export. (line 23) * org-meta-return: Structure Editing. (line 7) * org-mobile-pull: Pulling from the mobile application. (line 6) @@ -22518,22 +23351,22 @@ F Command and Function Index (line 6) * org-move-subtree-down: Structure Editing. (line 63) * org-move-subtree-up: Structure Editing. (line 60) -* org-narrow-to-block: Structure Editing. (line 123) +* org-narrow-to-block: Structure Editing. (line 125) * org-narrow-to-block <1>: Dynamic Blocks. (line 58) -* org-narrow-to-subtree: Structure Editing. (line 120) -* org-next-link: Handling Links. (line 153) +* org-narrow-to-subtree: Structure Editing. (line 122) +* org-next-link: Handling Links. (line 173) * org-next-visible-heading: Motion. (line 9) * org-occur: Sparse Trees. (line 20) * org-odt-convert: Extending ODT export. (line 37) * org-odt-export-to-odt: ODT export commands. (line 7) -* org-open-at-point: Handling Links. (line 108) +* org-open-at-point: Handling Links. (line 128) * org-open-at-point <1>: Creating Timestamps. (line 40) * org-open-at-point-global: Using Links Outside Org. (line 6) -* org-org-export-to-org: Org Export. (line 15) +* org-org-export-to-org: Org Export. (line 14) * org-paste-subtree: Structure Editing. (line 78) -* org-previous-link: Handling Links. (line 153) +* org-previous-link: Handling Links. (line 173) * org-previous-visible-heading: Motion. (line 12) * org-priority: Priorities. (line 33) * org-priority <1>: Using the Mapping API. @@ -22545,9 +23378,9 @@ F Command and Function Index * org-promote-subtree: Structure Editing. (line 54) * org-property-action: Property Syntax. (line 100) * org-protocol-create: The open-source protocol. - (line 67) + (line 68) * org-protocol-create-for-org: The open-source protocol. - (line 67) + (line 68) * org-publish: Triggering Publication. (line 9) * org-publish-all: Triggering Publication. @@ -22556,10 +23389,10 @@ F Command and Function Index (line 16) * org-publish-current-project: Triggering Publication. (line 13) -* org-publish-find-date: Site map. (line 21) -* org-publish-find-property: Site map. (line 21) -* org-publish-find-title: Site map. (line 21) -* org-refile: Structure Editing. (line 104) +* org-publish-find-date: Site map. (line 26) +* org-publish-find-property: Site map. (line 26) +* org-publish-find-title: Site map. (line 26) +* org-refile: Structure Editing. (line 106) * org-refile <1>: Refile and Copy. (line 13) * org-refile-cache-clear: Refile and Copy. (line 46) * org-refile-copy: Refile and Copy. (line 51) @@ -22568,7 +23401,7 @@ F Command and Function Index * org-remove-file: Agenda Files. (line 22) * org-reveal: Global and local cycling. (line 43) -* org-save-all-org-buffers: Agenda Commands. (line 194) +* org-save-all-org-buffers: Agenda Commands. (line 197) * org-schedule: Inserting deadline/schedule. (line 18) * org-search-view: Search view. (line 10) @@ -22577,10 +23410,11 @@ F Command and Function Index * org-set-property <1>: Property Syntax. (line 103) * org-set-property <2>: Using Header Arguments. (line 90) -* org-set-startup-visibility: Global and local cycling. - (line 36) -* org-set-startup-visibility <1>: Initial visibility. (line 26) * org-set-tags-command: Setting Tags. (line 11) +* org-shiftcontroldown: Clocking commands. (line 59) +* org-shiftcontrolup: Clocking commands. (line 59) +* org-shiftmetadown: Clocking commands. (line 64) +* org-shiftmetaup: Clocking commands. (line 64) * org-show-all: Global and local cycling. (line 40) * org-show-branches: Global and local cycling. @@ -22588,7 +23422,7 @@ F Command and Function Index * org-show-children: Global and local cycling. (line 55) * org-show-todo-tree: TODO Basics. (line 35) -* org-sort: Structure Editing. (line 108) +* org-sort: Structure Editing. (line 110) * org-sparse-tree: Sparse Trees. (line 16) * org-speed-command-help: Speed Keys. (line 18) * org-speedbar-set-agenda-restriction: Agenda Files. (line 58) @@ -22614,7 +23448,7 @@ F Command and Function Index (line 43) * org-table-create-or-convert-from-region <1>: Built-in Table Editor. (line 222) -* org-table-create-with-table.el: Cooperation. (line 63) +* org-table-create-with-table.el: Cooperation. (line 67) * org-table-cut-region: Built-in Table Editor. (line 158) * org-table-delete-column: Built-in Table Editor. @@ -22729,8 +23563,7 @@ F Command and Function Index (line 13) * org-tags-view <3>: Matching tags and properties. (line 21) -* org-texinfo-convert-region-to-texinfo: Export in Foreign Buffers. - (line 23) +* org-texinfo-convert-region-to-texinfo: Export Region. (line 23) * org-texinfo-export-to-info: Texinfo export commands. (line 11) * org-texinfo-export-to-texinfo: Texinfo export commands. @@ -22743,35 +23576,40 @@ F Command and Function Index * org-timer-set-timer: Timers. (line 23) * org-timer-start: Timers. (line 13) * org-timer-stop: Timers. (line 47) +* org-timestamp: Creating Timestamps. (line 11) +* org-timestamp-down: Clocking commands. (line 64) * org-timestamp-down-day: Creating Timestamps. (line 45) +* org-timestamp-inactive: Creating Timestamps. (line 25) +* org-timestamp-up: Clocking commands. (line 64) * org-timestamp-up-day: Creating Timestamps. (line 45) -* org-todo: Clocking commands. (line 71) +* org-todo: Clocking commands. (line 74) * org-todo <1>: Using the Mapping API. (line 77) * org-todo-list: Global TODO list. (line 10) * org-todo-list <1>: Global TODO list. (line 18) * org-toggle-archive-tag: Internal archiving. (line 39) -* org-toggle-checkbox: Checkboxes. (line 52) +* org-toggle-checkbox: Checkboxes. (line 75) * org-toggle-comment: Comment Lines. (line 20) -* org-toggle-heading: Structure Editing. (line 129) +* org-toggle-heading: Structure Editing. (line 131) * org-toggle-inline-images: Images. (line 24) * org-toggle-ordered-property: TODO dependencies. (line 38) -* org-toggle-ordered-property <1>: Checkboxes. (line 90) +* org-toggle-ordered-property <1>: Checkboxes. (line 113) * org-toggle-pretty-entities: Subscripts and Superscripts. - (line 27) + (line 29) * org-toggle-pretty-entities <1>: Special Symbols. (line 31) -* org-toggle-radio-button: Checkboxes. (line 75) +* org-toggle-radio-button: Checkboxes. (line 98) * org-toggle-sticky-agenda: Agenda Dispatcher. (line 55) * org-toggle-tag: Using the Mapping API. (line 85) * org-toggle-tags-groups: Tag Hierarchy. (line 87) * org-toggle-time-stamp-overlays: Custom time format. (line 13) +* org-toggle-timestamp-overlays: Custom time format. (line 13) * org-tree-to-indirect-buffer: Global and local cycling. (line 59) -* org-update-statistics-cookies: Checkboxes. (line 98) +* org-update-statistics-cookies: Checkboxes. (line 121) * org-version: Feedback. (line 17) -* org-yank: Structure Editing. (line 84) -* orgtbl-ascii-draw: Org Plot. (line 144) +* org-yank: Structure Editing. (line 86) +* orgtbl-ascii-draw: Org Plot. (line 148) * orgtbl-mode: Orgtbl Mode. (line 6) * orgtbl-to-csv: Translator functions. (line 6) @@ -22792,7 +23630,7 @@ F Command and Function Index * outline-up-heading: Motion. (line 21) * pcomplete: Property Syntax. (line 86) * previous-error: Sparse Trees. (line 35) -* widen: Structure Editing. (line 126) +* widen: Structure Editing. (line 128)  File: org.info, Node: Variable Index, Prev: Command and Function Index, Up: Top @@ -22809,34 +23647,35 @@ org-customize’ and then click yourself through the tree. * cdlatex-simplify-sub-super-scripts: CDLaTeX mode. (line 43) * constants-unit-system: References. (line 121) -* constants-unit-system <1>: In-buffer Settings. (line 152) +* constants-unit-system <1>: In-buffer Settings. (line 166) +* icalendar-export-sexp-enumeration-days: iCalendar Export. (line 11) * LaTeX-verbatim-environments: A LaTeX example. (line 19) * org-adapt-indentation: Hard indentation. (line 16) * org-agenda-auto-exclude-function: Filtering/limiting agenda items. (line 99) -* org-agenda-bulk-custom-functions: Agenda Commands. (line 353) -* org-agenda-bulk-custom-functions <1>: Agenda Commands. (line 432) -* org-agenda-bulk-persistent-marks: Agenda Commands. (line 384) +* org-agenda-bulk-custom-functions: Agenda Commands. (line 356) +* org-agenda-bulk-custom-functions <1>: Agenda Commands. (line 435) +* org-agenda-bulk-persistent-marks: Agenda Commands. (line 387) * org-agenda-category-filter-preset: Filtering/limiting agenda items. (line 6) * org-agenda-category-icon-alist: Categories. (line 16) -* org-agenda-clock-consistency-checks: Agenda Commands. (line 166) +* org-agenda-clock-consistency-checks: Agenda Commands. (line 169) * org-agenda-columns-add-appointments-to-effort-sum: Effort Estimates. (line 45) -* org-agenda-confirm-kill: Agenda Commands. (line 244) +* org-agenda-confirm-kill: Agenda Commands. (line 247) * org-agenda-custom-commands: Sparse Trees. (line 37) * org-agenda-custom-commands <1>: Storing searches. (line 11) * org-agenda-custom-commands <2>: Setting options. (line 6) * org-agenda-custom-commands <3>: Extracting Agenda Information. (line 10) * org-agenda-custom-commands-contexts: Setting options. (line 59) -* org-agenda-diary-file: Agenda Commands. (line 461) +* org-agenda-diary-file: Agenda Commands. (line 464) * org-agenda-dim-blocked-tasks: TODO dependencies. (line 48) * org-agenda-dim-blocked-tasks <1>: Speeding Up Your Agendas. (line 15) * org-agenda-effort-filter-preset: Filtering/limiting agenda items. (line 6) -* org-agenda-entry-text-maxlines: Agenda Commands. (line 174) +* org-agenda-entry-text-maxlines: Agenda Commands. (line 177) * org-agenda-exporter-settings: Exporting Agenda Views. (line 14) * org-agenda-exporter-settings <1>: Exporting Agenda Views. @@ -22868,7 +23707,7 @@ org-customize’ and then click yourself through the tree. * org-agenda-restore-windows-after-quit: Agenda Views. (line 42) * org-agenda-search-headline-for-time: Time-of-day specifications. (line 16) -* org-agenda-show-inherited-tags: Agenda Commands. (line 271) +* org-agenda-show-inherited-tags: Agenda Commands. (line 274) * org-agenda-show-inherited-tags <1>: Speeding Up Your Agendas. (line 23) * org-agenda-skip-archived-trees: Internal archiving. (line 23) @@ -22886,18 +23725,19 @@ org-customize’ and then click yourself through the tree. (line 6) * org-agenda-skip-scheduled-delay-if-deadline: Deadlines and Scheduling. (line 42) -* org-agenda-skip-scheduled-if-deadline-is-shown: Repeated tasks. - (line 80) * org-agenda-skip-scheduled-if-done: Deadlines and Scheduling. (line 34) +* org-agenda-skip-scheduled-repeats-after-deadline: Repeated tasks. + (line 83) * org-agenda-sorting-strategy: Sorting of agenda items. (line 28) * org-agenda-span: Weekly/daily agenda. (line 15) * org-agenda-span <1>: Agenda Commands. (line 107) * org-agenda-start-day: Weekly/daily agenda. (line 15) * org-agenda-start-on-weekday: Weekly/daily agenda. (line 15) -* org-agenda-start-with-clockreport-mode: Agenda Commands. (line 154) -* org-agenda-start-with-entry-text-mode: Agenda Commands. (line 174) +* org-agenda-start-with-archives-mode: Agenda Commands. (line 146) +* org-agenda-start-with-clockreport-mode: Agenda Commands. (line 157) +* org-agenda-start-with-entry-text-mode: Agenda Commands. (line 177) * org-agenda-start-with-follow-mode: Agenda Commands. (line 42) * org-agenda-sticky: Agenda Dispatcher. (line 55) * org-agenda-tag-filter-preset: Filtering/limiting agenda items. @@ -22910,23 +23750,23 @@ org-customize’ and then click yourself through the tree. * org-agenda-text-search-extra-files <1>: Search view. (line 34) * org-agenda-time-grid: Time-of-day specifications. (line 46) -* org-agenda-time-grid <1>: Agenda Commands. (line 182) +* org-agenda-time-grid <1>: Agenda Commands. (line 185) * org-agenda-todo-ignore-deadlines: Global TODO list. (line 42) * org-agenda-todo-ignore-scheduled: Global TODO list. (line 42) * org-agenda-todo-ignore-timestamp: Global TODO list. (line 42) * org-agenda-todo-ignore-with-date: Global TODO list. (line 42) * org-agenda-todo-list-sublevels: Breaking Down Tasks. (line 6) * org-agenda-todo-list-sublevels <1>: Global TODO list. (line 53) -* org-agenda-use-tag-inheritance: Tag Inheritance. (line 32) +* org-agenda-use-tag-inheritance: Tag Inheritance. (line 26) * org-agenda-use-tag-inheritance <1>: Speeding Up Your Agendas. (line 23) * org-agenda-use-time-grid: Time-of-day specifications. (line 46) -* org-agenda-use-time-grid <1>: Agenda Commands. (line 182) +* org-agenda-use-time-grid <1>: Agenda Commands. (line 185) * org-agenda-window-setup: Agenda Views. (line 42) * org-alphabetical-lists: Plain Lists. (line 15) * org-archive-default-command: Archiving. (line 12) -* org-archive-default-command <1>: Agenda Commands. (line 253) +* org-archive-default-command <1>: Agenda Commands. (line 256) * org-archive-location: Moving subtrees. (line 10) * org-archive-location <1>: In-buffer Settings. (line 16) * org-archive-save-context-info: Moving subtrees. (line 41) @@ -22973,14 +23813,22 @@ org-customize’ and then click yourself through the tree. (line 10) * org-beamer-theme: Beamer specific export settings. (line 11) +* org-bookmark-names-plist: Using capture. (line 48) * org-calc-default-modes: Formula syntax for Calc. (line 17) -* org-capture-bookmark: Using capture. (line 48) * org-capture-last-stored: Using capture. (line 48) * org-capture-templates: Capture templates. (line 11) * org-capture-templates-contexts: Templates in contexts. (line 6) -* org-capture-use-agenda-date: Agenda Commands. (line 346) +* org-capture-use-agenda-date: Agenda Commands. (line 349) +* org-checkbox-hierarchical-statistics: Checkboxes. (line 24) +* org-cite-activate-processor: Citation handling. (line 53) +* org-cite-biblatex-options: Citation export processors. + (line 68) +* org-cite-export-processor: Citation handling. (line 53) +* org-cite-follow-processor: Citation handling. (line 53) +* org-cite-global-bibliography: Citations. (line 6) +* org-cite-insert-processor: Citation handling. (line 53) * org-clock-auto-clockout-timer: Resolving idle time. (line 91) * org-clock-continuously: Clocking commands. (line 7) * org-clock-continuously <1>: Clocking commands. (line 44) @@ -22991,15 +23839,17 @@ org-customize’ and then click yourself through the tree. * org-clock-into-drawer: Clocking commands. (line 7) * org-clock-mode-line-total: Clocking commands. (line 21) * org-clock-persist: Clocking Work Time. (line 19) -* org-clock-report-include-clocking-task: Agenda Commands. (line 154) +* org-clock-report-include-clocking-task: Agenda Commands. (line 157) * org-clock-x11idle-program-name: Resolving idle time. (line 14) * org-clocktable-defaults: The clock table. (line 39) * org-closed-keep-when-no-todo: Closing items. (line 11) * org-coderef-label-format: Literal Examples. (line 88) * org-columns: Using column view. (line 10) +* org-columns-dblock-formatter: Capturing column view. + (line 74) * org-columns-default-format: Using column view. (line 10) * org-columns-default-format <1>: Effort Estimates. (line 35) -* org-columns-default-format <2>: Agenda Commands. (line 198) +* org-columns-default-format <2>: Agenda Commands. (line 201) * org-columns-default-format <3>: Agenda Column View. (line 19) * org-columns-default-format-for-agenda: Agenda Column View. (line 19) * org-columns-skip-archived-trees: Internal archiving. (line 33) @@ -23015,8 +23865,8 @@ org-customize’ and then click yourself through the tree. (line 16) * org-cycle-global-at-bob: Global and local cycling. (line 31) -* org-cycle-include-plain-lists: Plain Lists. (line 70) -* org-cycle-inline-images-display: Images. (line 45) +* org-cycle-include-plain-lists: Plain Lists. (line 71) +* org-cycle-inline-images-display: Images. (line 86) * org-cycle-open-archived-trees: Internal archiving. (line 13) * org-cycle-separator-lines: Headlines. (line 29) * org-deadline-warning-days: Deadlines and Scheduling. @@ -23027,6 +23877,7 @@ org-customize’ and then click yourself through the tree. * org-default-notes-file <1>: Template elements. (line 50) * org-directory: Template elements. (line 50) * org-display-custom-times: Custom time format. (line 6) +* org-display-custom-times <1>: In-buffer Settings. (line 160) * org-disputed-keys: Conflicts. (line 27) * org-done, face: Faces for TODO keywords. (line 6) @@ -23036,25 +23887,34 @@ org-customize’ and then click yourself through the tree. * org-enforce-todo-dependencies <1>: TODO dependencies. (line 53) * org-entities-user: Special Symbols. (line 16) * org-execute-file-search-functions: Custom Searches. (line 12) -* org-export-allow-bind-keywords: Export Settings. (line 210) +* org-export-allow-bind-keywords: Export Settings. (line 229) * org-export-async-init-file: The Export Dispatcher. (line 42) * org-export-backends: Exporting. (line 33) * org-export-before-parsing-hook: Advanced Export Configuration. (line 9) +* org-export-before-processing-functions: Advanced Export Configuration. + (line 9) * org-export-before-processing-hook: Advanced Export Configuration. (line 9) +* org-export-body-only: The Export Dispatcher. + (line 51) * org-export-creator-string: HTML preamble and postamble. (line 6) * org-export-date-timestamp-format: Export Settings. (line 32) * org-export-default-language: Export Settings. (line 38) -* org-export-default-language <1>: LaTeX header and sectioning. +* org-export-default-language <1>: LaTeX specific export settings. + (line 20) +* org-export-default-language <2>: LaTeX header and sectioning. (line 47) * org-export-dispatch-use-expert-ui: The Export Dispatcher. (line 10) -* org-export-exclude-tags: Export Settings. (line 52) +* org-export-exclude-tags: Export Settings. (line 61) +* org-export-expand-links: Export Settings. (line 126) +* org-export-force-publishing: The Export Dispatcher. + (line 61) * org-export-global-macros: Macro Replacement. (line 6) -* org-export-headline-levels: Export Settings. (line 141) +* org-export-headline-levels: Export Settings. (line 160) * org-export-html-table-tag: Tables in HTML export. (line 6) * org-export-html-tag-class-prefix: CSS support. (line 6) @@ -23063,7 +23923,7 @@ org-customize’ and then click yourself through the tree. * org-export-in-background: The Export Dispatcher. (line 39) * org-export-initial-scope: The Export Dispatcher. - (line 60) + (line 75) * org-export-odt-convert-capabilities: Advanced topics in ODT export. (line 22) * org-export-odt-convert-process: Advanced topics in ODT export. @@ -23074,64 +23934,70 @@ org-customize’ and then click yourself through the tree. (line 25) * org-export-odt-schema-dir: Advanced topics in ODT export. (line 269) -* org-export-preserve-breaks: Export Settings. (line 93) +* org-export-preserve-breaks: Export Settings. (line 108) * org-export-select-tags: Export Settings. (line 44) -* org-export-time-stamp-file: Export Settings. (line 187) +* org-export-time-stamp-file: Export Settings. (line 206) * org-export-time-stamp-file <1>: HTML preamble and postamble. (line 6) +* org-export-timestamp-file: Export Settings. (line 206) * org-export-use-babel: Exporting Code Blocks. (line 66) +* org-export-visible-only: The Export Dispatcher. + (line 84) * org-export-with-archived-trees: Internal archiving. (line 29) -* org-export-with-archived-trees <1>: Export Settings. (line 102) -* org-export-with-author: Export Settings. (line 107) -* org-export-with-broken-links: Export Settings. (line 111) -* org-export-with-clocks: Export Settings. (line 116) -* org-export-with-creator: Export Settings. (line 119) -* org-export-with-date: Export Settings. (line 127) -* org-export-with-drawers: Export Settings. (line 123) -* org-export-with-email: Export Settings. (line 134) -* org-export-with-emphasize: Export Settings. (line 79) -* org-export-with-entities: Export Settings. (line 131) -* org-export-with-fixed-width: Export Settings. (line 86) -* org-export-with-footnotes: Export Settings. (line 138) -* org-export-with-inlinetasks: Export Settings. (line 146) -* org-export-with-latex: LaTeX fragments. (line 38) -* org-export-with-latex <1>: Export Settings. (line 183) -* org-export-with-planning: Export Settings. (line 157) -* org-export-with-priority: Export Settings. (line 163) -* org-export-with-properties: Export Settings. (line 166) -* org-export-with-section-numbers: Export Settings. (line 149) -* org-export-with-smart-quotes: Export Settings. (line 73) -* org-export-with-special-strings: Export Settings. (line 82) -* org-export-with-statistics-cookies: Export Settings. (line 170) -* org-export-with-sub-superscripts: Export Settings. (line 97) -* org-export-with-tables: Export Settings. (line 202) -* org-export-with-tags: Export Settings. (line 174) -* org-export-with-tasks: Export Settings. (line 178) -* org-export-with-timestamps: Export Settings. (line 89) -* org-export-with-title: Export Settings. (line 191) -* org-export-with-toc: Export Settings. (line 194) +* org-export-with-archived-trees <1>: Export Settings. (line 117) +* org-export-with-author: Export Settings. (line 122) +* org-export-with-broken-links: Export Settings. (line 130) +* org-export-with-clocks: Export Settings. (line 135) +* org-export-with-creator: Export Settings. (line 138) +* org-export-with-date: Export Settings. (line 146) +* org-export-with-drawers: Export Settings. (line 142) +* org-export-with-email: Export Settings. (line 153) +* org-export-with-emphasize: Export Settings. (line 94) +* org-export-with-entities: Export Settings. (line 150) +* org-export-with-fixed-width: Export Settings. (line 101) +* org-export-with-footnotes: Export Settings. (line 157) +* org-export-with-inlinetasks: Export Settings. (line 165) +* org-export-with-latex: LaTeX fragments. (line 44) +* org-export-with-latex <1>: Export Settings. (line 202) +* org-export-with-planning: Export Settings. (line 176) +* org-export-with-priority: Export Settings. (line 182) +* org-export-with-properties: Export Settings. (line 185) +* org-export-with-section-numbers: Export Settings. (line 168) +* org-export-with-smart-quotes: Export Settings. (line 88) +* org-export-with-special-strings: Export Settings. (line 97) +* org-export-with-statistics-cookies: Export Settings. (line 189) +* org-export-with-sub-superscripts: Subscripts and Superscripts. + (line 13) +* org-export-with-sub-superscripts <1>: Export Settings. (line 112) +* org-export-with-tables: Export Settings. (line 221) +* org-export-with-tags: Export Settings. (line 193) +* org-export-with-tasks: Export Settings. (line 197) +* org-export-with-timestamps: Export Settings. (line 104) +* org-export-with-title: Export Settings. (line 210) +* org-export-with-toc: Export Settings. (line 213) * org-export-with-toc <1>: Table of Contents. (line 6) -* org-export-with-todo-keywords: Export Settings. (line 198) +* org-export-with-todo-keywords: Export Settings. (line 217) * org-expot-creator-string: Export Settings. (line 28) * org-faces-easy-properties: Faces for TODO keywords. (line 17) -* org-fast-tag-selection-include-todo: Fast access to TODO states. - (line 16) +* org-fast-tag-selection-maximum-tags: Setting Tags. (line 152) * org-fast-tag-selection-single-key: Setting Tags. (line 142) -* org-file-apps: Handling Links. (line 108) +* org-file-apps: Handling Links. (line 128) * org-file-apps <1>: Attachment defaults and dispatcher. (line 46) * org-fold-catch-invisible-edits: Catching invisible edits. (line 6) +* org-fold-catch-invisible-edits-commands: Catching invisible edits. + (line 6) * org-fontify-emphasized-text: Emphasis and Monospace. - (line 11) + (line 18) * org-footnote-auto-adjust: Creating Footnotes. (line 60) -* org-footnote-auto-adjust <1>: In-buffer Settings. (line 158) +* org-footnote-auto-adjust <1>: In-buffer Settings. (line 172) * org-footnote-auto-label: Creating Footnotes. (line 32) -* org-footnote-auto-label <1>: In-buffer Settings. (line 158) +* org-footnote-auto-label <1>: In-buffer Settings. (line 172) * org-footnote-define-inline: Creating Footnotes. (line 45) -* org-footnote-define-inline <1>: In-buffer Settings. (line 158) +* org-footnote-define-inline <1>: In-buffer Settings. (line 172) * org-footnote-section: Headlines. (line 18) * org-footnote-section <1>: Creating Footnotes. (line 45) * org-format-latex-header: LaTeX fragments. (line 6) @@ -23145,21 +24011,22 @@ org-customize’ and then click yourself through the tree. * org-goto-interface: Motion. (line 41) * org-group-tags: Tag Hierarchy. (line 87) * org-habit-following-days: Tracking your habits. - (line 91) + (line 93) * org-habit-graph-column: Tracking your habits. - (line 82) + (line 84) * org-habit-preceding-days: Tracking your habits. - (line 87) + (line 89) * org-habit-show-habits-only-for-today: Tracking your habits. - (line 94) + (line 96) * org-hide, face: Hard indentation. (line 21) * org-hide-block-startup: Blocks. (line 6) -* org-hide-block-startup <1>: In-buffer Settings. (line 171) -* org-hide-drawer-startup: In-buffer Settings. (line 171) +* org-hide-block-startup <1>: In-buffer Settings. (line 186) +* org-hide-drawer-startup: In-buffer Settings. (line 186) +* org-hide-emphasis-markers: Emphasis and Monospace. + (line 22) * org-hide-leading-stars: Hard indentation. (line 21) -* org-hide-leading-stars <1>: In-buffer Settings. (line 134) +* org-hide-leading-stars <1>: In-buffer Settings. (line 148) * org-hide-macro-markers: Macro Replacement. (line 88) -* org-hierarchical-checkbox-statistics: Checkboxes. (line 29) * org-hierarchical-todo-statistics: Breaking Down Tasks. (line 25) * org-html-container-element: HTML specific export settings. (line 22) @@ -23169,14 +24036,14 @@ org-customize’ and then click yourself through the tree. * org-html-doctype-alist: HTML doctypes. (line 8) * org-html-head: HTML specific export settings. (line 38) -* org-html-head <1>: CSS support. (line 44) -* org-html-head <2>: Bare HTML. (line 9) +* org-html-head <1>: Bare HTML. (line 9) +* org-html-head <2>: CSS support. (line 44) * org-html-head-extra: HTML specific export settings. (line 42) -* org-html-head-extra <1>: CSS support. (line 44) -* org-html-head-extra <2>: Bare HTML. (line 9) -* org-html-head-include-default-style: CSS support. (line 52) -* org-html-head-include-default-style <1>: Bare HTML. (line 9) +* org-html-head-extra <1>: Bare HTML. (line 9) +* org-html-head-extra <2>: CSS support. (line 44) +* org-html-head-include-default-style: Bare HTML. (line 9) +* org-html-head-include-default-style <1>: CSS support. (line 52) * org-html-head-include-scripts: Bare HTML. (line 9) * org-html-html5-elements: HTML doctypes. (line 60) * org-html-html5-fancy: HTML doctypes. (line 25) @@ -23224,38 +24091,44 @@ org-customize’ and then click yourself through the tree. * org-html-use-infojs: Bare HTML. (line 9) * org-html-validation-link: HTML preamble and postamble. (line 6) -* org-icalendar-alarm-time: iCalendar Export. (line 20) -* org-icalendar-categories: iCalendar Export. (line 20) -* org-icalendar-combined-agenda-file: iCalendar Export. (line 47) -* org-icalendar-include-body: iCalendar Export. (line 57) -* org-icalendar-include-todo: iCalendar Export. (line 11) -* org-icalendar-store-UID: iCalendar Export. (line 26) -* org-icalendar-use-deadline: iCalendar Export. (line 11) -* org-icalendar-use-scheduled: iCalendar Export. (line 11) -* org-id-link-to-org-use-id: Handling Links. (line 21) +* org-icalendar-alarm-time: iCalendar Export. (line 24) +* org-icalendar-categories: iCalendar Export. (line 24) +* org-icalendar-combined-agenda-file: iCalendar Export. (line 51) +* org-icalendar-include-body: iCalendar Export. (line 73) +* org-icalendar-include-todo: iCalendar Export. (line 14) +* org-icalendar-store-UID: iCalendar Export. (line 30) +* org-icalendar-todo-unscheduled-start: iCalendar Export. (line 19) +* org-icalendar-ttl: iCalendar Export. (line 97) +* org-icalendar-use-deadline: iCalendar Export. (line 19) +* org-icalendar-use-scheduled: iCalendar Export. (line 19) +* org-id-link-consider-parent-id: Handling Links. (line 33) +* org-id-link-to-org-use-id: Handling Links. (line 22) +* org-id-link-use-context: Handling Links. (line 33) * org-image-actual-width: Images. (line 30) +* org-image-align: Images. (line 58) +* org-image-max-width: Images. (line 30) * org-imenu-depth: Cooperation. (line 37) * org-indent-indentation-per-level: Org Indent Mode. (line 11) * org-indent-mode-turns-off-org-adapt-indentation: Org Indent Mode. (line 15) * org-indent-mode-turns-on-hiding-stars: Org Indent Mode. (line 15) * org-infojs-options: JavaScript support. (line 70) -* org-insert-mode-line-in-empty-file: Activation. (line 30) -* org-irc-links-to-logs: Handling Links. (line 47) +* org-insert-mode-line-in-empty-file: Activation. (line 31) +* org-irc-links-to-logs: Handling Links. (line 67) * org-latex-bibtex-compiler: LaTeX/PDF export commands. (line 25) * org-latex-classes: LaTeX specific export settings. - (line 39) + (line 41) * org-latex-classes <1>: LaTeX specific export settings. - (line 56) + (line 58) * org-latex-classes <2>: LaTeX header and sectioning. (line 13) * org-latex-compiler: LaTeX/PDF export commands. (line 25) * org-latex-compiler <1>: LaTeX specific export settings. - (line 51) + (line 53) * org-latex-default-class: LaTeX specific export settings. - (line 39) + (line 41) * org-latex-default-class <1>: LaTeX header and sectioning. (line 13) * org-latex-default-packages-alist: LaTeX/PDF export commands. @@ -23267,28 +24140,30 @@ org-customize’ and then click yourself through the tree. * org-latex-default-table-mode: Tables in LaTeX export. (line 12) * org-latex-engraved-options: Source blocks in LaTeX export. - (line 25) + (line 33) * org-latex-hyperref-template: LaTeX specific export settings. (line 11) * org-latex-hyperref-template <1>: LaTeX specific export settings. - (line 61) + (line 63) * org-latex-images-centered: Images in LaTeX export. (line 63) * org-latex-language-alist: LaTeX specific export settings. (line 20) * org-latex-listings-options: Source blocks in LaTeX export. - (line 25) + (line 33) * org-latex-minted-options: Source blocks in LaTeX export. - (line 25) + (line 33) * org-latex-packages-alist: LaTeX specific export settings. (line 20) * org-latex-packages-alist <1>: LaTeX header and sectioning. (line 13) * org-latex-src-block-backend: Literal Examples. (line 31) +* org-latex-src-block-backend <1>: Source blocks in LaTeX export. + (line 6) * org-latex-subtitle-format: LaTeX specific export settings. - (line 70) + (line 72) * org-latex-subtitle-separate: LaTeX specific export settings. - (line 70) + (line 72) * org-latex-tables-booktabs: Tables in LaTeX export. (line 79) * org-latex-tables-centered: Tables in LaTeX export. @@ -23296,42 +24171,44 @@ org-customize’ and then click yourself through the tree. * org-latex-title-command: LaTeX specific export settings. (line 11) * org-latex-title-command <1>: LaTeX specific export settings. - (line 61) + (line 63) * org-latex-to-mathml-convert-command: LaTeX math snippets. (line 20) * org-latex-to-mathml-jar-file: LaTeX math snippets. (line 20) * org-link-abbrev-alist: Link Abbreviations. (line 12) * org-link-abbrev-alist <1>: In-buffer Settings. (line 39) +* org-link-context-for-files: Handling Links. (line 33) +* org-link-descriptive: In-buffer Settings. (line 116) * org-link-elisp-confirm-function: Code Evaluation Security. (line 52) -* org-link-email-description-format: Handling Links. (line 33) -* org-link-frame-setup: Handling Links. (line 123) -* org-link-from-user-regexp: Template expansion. (line 108) -* org-link-keep-stored-after-insertion: Handling Links. (line 71) +* org-link-email-description-format: Handling Links. (line 53) +* org-link-frame-setup: Handling Links. (line 143) +* org-link-from-user-regexp: Template expansion. (line 113) +* org-link-keep-stored-after-insertion: Handling Links. (line 91) * org-link-parameters: Adding Hyperlink Types. (line 74) * org-link-search-must-match-exact-headline: Internal Links. (line 31) * org-link-shell-confirm-function: Code Evaluation Security. (line 49) -* org-link-use-indirect-buffer-for-internals: Handling Links. (line 137) -* org-list-automatic-rules: Plain Lists. (line 63) +* org-link-use-indirect-buffer-for-internals: Handling Links. (line 157) +* org-list-automatic-rules: Plain Lists. (line 64) * org-list-automatic-rules <1>: Checkboxes. (line 6) -* org-list-demote-modify-bullet: Plain Lists. (line 57) -* org-list-indent-offset: Plain Lists. (line 57) -* org-list-use-circular-motion: Plain Lists. (line 95) +* org-list-demote-modify-bullet: Plain Lists. (line 58) +* org-list-indent-offset: Plain Lists. (line 58) +* org-list-use-circular-motion: Plain Lists. (line 96) * org-log-done: Tracking TODO state changes. (line 25) * org-log-done <1>: Agenda Commands. (line 131) -* org-log-done <2>: In-buffer Settings. (line 112) +* org-log-done <2>: In-buffer Settings. (line 126) * org-log-into-drawer: Tracking TODO state changes. (line 6) -* org-log-into-drawer <1>: Agenda Commands. (line 296) +* org-log-into-drawer <1>: Agenda Commands. (line 299) * org-log-note-clock-out: Clocking commands. (line 36) -* org-log-note-clock-out <1>: In-buffer Settings. (line 112) +* org-log-note-clock-out <1>: In-buffer Settings. (line 126) * org-log-redeadline: Inserting deadline/schedule. (line 10) * org-log-refile: Refile and Copy. (line 13) -* org-log-repeat: Repeated tasks. (line 40) -* org-log-repeat <1>: In-buffer Settings. (line 112) +* org-log-repeat: Repeated tasks. (line 43) +* org-log-repeat <1>: In-buffer Settings. (line 126) * org-log-reschedule: Inserting deadline/schedule. (line 18) * org-log-states-order-reversed: Tracking TODO state changes. @@ -23339,8 +24216,8 @@ org-customize’ and then click yourself through the tree. * org-loop-over-headlines-in-active-region: Execute commands in the active region. (line 6) * org-M-RET-may-split-line: Structure Editing. (line 7) -* org-M-RET-may-split-line <1>: Plain Lists. (line 83) -* org-md-headline-style: Markdown Export. (line 29) +* org-M-RET-may-split-line <1>: Plain Lists. (line 84) +* org-md-headline-style: Markdown Export. (line 35) * org-mobile-directory: Setting up the staging area. (line 6) * org-mobile-encryption: Setting up the staging area. @@ -23364,9 +24241,9 @@ org-customize’ and then click yourself through the tree. * org-num-skip-unnumbered: Dynamic Headline Numbering. (line 10) * org-odd-levels-only: Matching tags and properties. - (line 65) + (line 63) * org-odd-levels-only <1>: Hard indentation. (line 29) -* org-odd-levels-only <2>: In-buffer Settings. (line 134) +* org-odd-levels-only <2>: In-buffer Settings. (line 148) * org-odd-levels-only <3>: Special Agenda Views. (line 41) * org-odt-category-map-alist: Labels and captions in ODT export. @@ -23392,14 +24269,14 @@ org-customize’ and then click yourself through the tree. (line 226) * org-outline-path-complete-in-steps: Refile and Copy. (line 13) * org-plain-list-ordered-item-terminator: Plain Lists. (line 15) -* org-plain-list-ordered-item-terminator <1>: Plain Lists. (line 131) +* org-plain-list-ordered-item-terminator <1>: Plain Lists. (line 132) * org-popup-calendar-for-date-prompt: The date/time prompt. (line 78) * org-pretty-entities: Subscripts and Superscripts. - (line 29) -* org-pretty-entities <1>: In-buffer Settings. (line 180) + (line 31) +* org-pretty-entities <1>: In-buffer Settings. (line 195) * org-pretty-entities-include-sub-superscripts: Subscripts and Superscripts. - (line 29) + (line 31) * org-preview-latex-default-process: Previewing LaTeX fragments. (line 6) * org-priority-default: Priorities. (line 46) @@ -23418,9 +24295,9 @@ org-customize’ and then click yourself through the tree. (line 13) * org-publish-project-alist: Project alist. (line 6) * org-publish-project-alist <1>: Publishing options. (line 12) +* org-publish-project-alist <2>: Site map. (line 6) * org-publish-use-timestamps-flag: Triggering Publication. (line 21) -* org-put-time-stamp-overlays: In-buffer Settings. (line 146) * org-read-date-display-live: The date/time prompt. (line 98) * org-read-date-force-compatible-dates: The date/time prompt. @@ -23433,9 +24310,9 @@ org-customize’ and then click yourself through the tree. * org-refile-use-cache: Refile and Copy. (line 46) * org-refile-use-outline-path: Refile and Copy. (line 13) * org-remove-highlights-with-change: Sparse Trees. (line 20) -* org-remove-highlights-with-change <1>: Clocking commands. (line 84) +* org-remove-highlights-with-change <1>: Clocking commands. (line 87) * org-replace-disputed-keys: Conflicts. (line 17) -* org-return-follows-link: Handling Links. (line 129) +* org-return-follows-link: Handling Links. (line 149) * org-reverse-note-order: Refile and Copy. (line 13) * org-scheduled-delay-days: Deadlines and Scheduling. (line 42) @@ -23447,36 +24324,36 @@ org-customize’ and then click yourself through the tree. * org-special-ctrl-k: Headlines. (line 6) * org-speed-commands: Speed Keys. (line 18) * org-src-ask-before-returning-to-edit-buffer: Editing Source Code. - (line 40) -* org-src-block-faces: Editing Source Code. (line 43) -* org-src-fontify-natively: Editing Source Code. (line 43) + (line 43) +* org-src-block-faces: Editing Source Code. (line 46) +* org-src-fontify-natively: Editing Source Code. (line 46) * org-src-lang-modes: Editing Source Code. (line 22) -* org-src-preserve-indentation: Editing Source Code. (line 32) -* org-src-window-setup: Editing Source Code. (line 28) +* org-src-preserve-indentation: Editing Source Code. (line 35) +* org-src-window-setup: Editing Source Code. (line 31) * org-startup-align-all-tables: Column Width and Alignment. (line 19) -* org-startup-align-all-tables <1>: In-buffer Settings. (line 94) +* org-startup-align-all-tables <1>: In-buffer Settings. (line 98) * org-startup-folded: Initial visibility. (line 6) -* org-startup-folded <1>: In-buffer Settings. (line 68) +* org-startup-folded <1>: In-buffer Settings. (line 72) * org-startup-folded <2>: Speeding Up Your Agendas. (line 19) * org-startup-indented: Org Indent Mode. (line 22) -* org-startup-indented <1>: In-buffer Settings. (line 82) +* org-startup-indented <1>: In-buffer Settings. (line 86) * org-startup-numerated: Dynamic Headline Numbering. (line 22) -* org-startup-numerated <1>: In-buffer Settings. (line 88) +* org-startup-numerated <1>: In-buffer Settings. (line 92) * org-startup-shrink-all-tables: Column Width and Alignment. (line 64) -* org-startup-shrink-all-tables <1>: In-buffer Settings. (line 101) +* org-startup-shrink-all-tables <1>: In-buffer Settings. (line 105) * org-startup-with-inline-images: Images. (line 24) -* org-startup-with-inline-images <1>: In-buffer Settings. (line 105) +* org-startup-with-inline-images <1>: In-buffer Settings. (line 109) * org-startup-with-latex-preview: Previewing LaTeX fragments. (line 28) -* org-store-link-props: Template expansion. (line 106) +* org-store-link-props: Template expansion. (line 111) * org-structure-template-alist: Structure Templates. (line 17) * org-stuck-projects: Stuck projects. (line 17) -* org-support-shift-select: Plain Lists. (line 95) -* org-support-shift-select <1>: Plain Lists. (line 154) +* org-support-shift-select: Plain Lists. (line 96) +* org-support-shift-select <1>: Plain Lists. (line 155) * org-support-shift-select <2>: Conflicts. (line 6) * org-table-automatic-realign: Column Width and Alignment. (line 10) @@ -23497,16 +24374,11 @@ org-customize’ and then click yourself through the tree. * org-table-use-standard-references: Editing and debugging formulas. (line 6) * org-tag-alist: Setting Tags. (line 22) -* org-tag-alist <1>: In-buffer Settings. (line 187) +* org-tag-alist <1>: In-buffer Settings. (line 202) * org-tag-faces: Tags. (line 10) * org-tag-persistent-alist: Setting Tags. (line 37) * org-tags-column: Setting Tags. (line 11) * org-tags-exclude-from-inheritance: Tag Inheritance. (line 22) -* org-tags-match-list-sublevels: Tag Inheritance. (line 26) -* org-tags-match-list-sublevels <1>: Tag Searches. (line 19) -* org-tags-match-list-sublevels <2>: Property Searches. (line 18) -* org-tags-match-list-sublevels <3>: Matching tags and properties. - (line 21) * org-tempo-keywords-alist: Structure Templates. (line 21) * org-texinfo-classes: Texinfo file header. (line 19) * org-texinfo-classes <1>: Headings and sectioning structure. @@ -23521,9 +24393,12 @@ org-customize’ and then click yourself through the tree. * org-texinfo-table-default-markup: Plain lists in Texinfo export. (line 25) * org-time-stamp-custom-formats: Custom time format. (line 6) -* org-time-stamp-overlay-formats: In-buffer Settings. (line 146) +* org-time-stamp-custom-formats <1>: In-buffer Settings. (line 160) * org-time-stamp-rounding-minutes: Creating Timestamps. (line 16) * org-timer-default-timer: Timers. (line 23) +* org-timestamp-custom-formats: Custom time format. (line 6) +* org-timestamp-custom-formats <1>: In-buffer Settings. (line 160) +* org-timestamp-rounding-minutes: Creating Timestamps. (line 16) * org-todo, face: Faces for TODO keywords. (line 6) * org-todo-keyword-faces: Faces for TODO keywords. @@ -23531,11 +24406,11 @@ org-customize’ and then click yourself through the tree. * org-todo-keywords: TODO Basics. (line 35) * org-todo-keywords <1>: TODO Extensions. (line 6) * org-todo-keywords <2>: Global TODO list. (line 18) -* org-todo-keywords <3>: In-buffer Settings. (line 192) +* org-todo-keywords <3>: In-buffer Settings. (line 207) * org-todo-repeat-to-state: Repeated tasks. (line 22) * org-todo-state-tags-triggers: TODO Basics. (line 56) * org-track-ordered-property-with-tag: TODO dependencies. (line 38) -* org-track-ordered-property-with-tag <1>: Checkboxes. (line 90) +* org-track-ordered-property-with-tag <1>: Checkboxes. (line 113) * org-treat-insert-todo-heading-as-state-change: Structure Editing. (line 29) * org-treat-S-cursor-todo-selection-as-state-change: TODO Basics. @@ -23550,8 +24425,16 @@ org-customize’ and then click yourself through the tree. * org-use-sub-superscripts: Subscripts and Superscripts. (line 13) * org-use-tag-inheritance: Tag Inheritance. (line 22) -* org-yank-adjusted-subtrees: Structure Editing. (line 84) -* org-yank-folded-subtrees: Structure Editing. (line 84) +* org-yank-adjusted-subtrees: Structure Editing. (line 86) +* org-yank-dnd-default-attach-method: Drag and Drop & yank-media. + (line 15) +* org-yank-dnd-method: Drag and Drop & yank-media. + (line 6) +* org-yank-folded-subtrees: Structure Editing. (line 86) +* org-yank-image-file-name-function: Drag and Drop & yank-media. + (line 26) +* org-yank-image-save-method: Drag and Drop & yank-media. + (line 21) * parse-time-months: The date/time prompt. (line 58) * parse-time-weekdays: The date/time prompt. @@ -23563,582 +24446,597 @@ org-customize’ and then click yourself through the tree.  Tag Table: Node: Top884 -Node: Introduction22994 -Node: Summary23456 -Node: Installation26491 -Ref: Using Emacs packaging system27214 -Ref: Using Org's git repository27722 -Ref: Installing Org's contributed packages28680 -Node: Activation29310 -Ref: Activation-Footnote-130933 -Node: Feedback31061 -Ref: How to create a useful backtrace34092 -Ref: Feedback-Footnote-135244 -Node: Conventions35370 -Ref: TODO keywords tags properties etc35541 -Ref: Key bindings and commands36434 -Node: Document Structure37064 -Node: Headlines38236 -Ref: Headlines-Footnote-139534 -Node: Visibility Cycling39813 -Node: Global and local cycling40203 -Ref: Global and local cycling-Footnote-142908 -Ref: Global and local cycling-Footnote-242970 -Node: Initial visibility43274 -Ref: Initial visibility-Footnote-144458 -Node: Catching invisible edits44651 -Node: Motion45133 -Node: Structure Editing46597 -Node: Sparse Trees53057 -Ref: Sparse Trees-Footnote-155654 -Ref: Sparse Trees-Footnote-255769 -Node: Plain Lists55845 -Ref: Plain Lists-Footnote-163370 -Ref: Plain Lists-Footnote-263734 -Ref: Plain Lists-Footnote-363834 -Ref: Plain Lists-Footnote-464091 -Ref: Plain Lists-Footnote-564268 -Ref: Plain Lists-Footnote-664372 -Ref: Plain Lists-Footnote-764478 -Node: Drawers64548 -Ref: Drawers-Footnote-166243 -Node: Blocks66355 -Node: Tables66948 -Node: Built-in Table Editor67631 -Ref: Creation and conversion69367 -Ref: Re-aligning and field motion70305 -Ref: Column and row editing71240 -Ref: Regions73670 -Ref: Calculations75069 -Ref: Miscellaneous (1)75882 -Ref: Built-in Table Editor-Footnote-178359 -Node: Column Width and Alignment78467 -Node: Column Groups81804 -Node: Orgtbl Mode83371 -Node: The Spreadsheet84186 -Node: References85660 -Ref: Field references86119 -Ref: Range references88558 -Ref: Field coordinates in formulas89817 -Ref: Named references90802 -Ref: Remote references91773 -Ref: References-Footnote-192695 -Ref: References-Footnote-292923 -Ref: References-Footnote-393026 -Node: Formula syntax for Calc93351 -Ref: Formula syntax for Calc-Footnote-199213 -Node: Formula syntax for Lisp99552 -Node: Durations and time values101785 -Node: Field and range formulas103172 -Node: Column formulas105641 -Node: Lookup functions107753 -Node: Editing and debugging formulas109722 -Ref: Using multiple TBLFM lines114239 -Ref: Debugging formulas115082 -Node: Updating the table115500 -Node: Advanced features116872 -Ref: Advanced features-Footnote-1121323 -Node: Org Plot121431 -Ref: Graphical plots using Gnuplot121632 -Ref: Plot options124155 -Ref: ASCII bar plots126947 -Node: Hyperlinks128197 -Node: Link Format129061 -Ref: Link Format-Footnote-1131124 -Ref: Link Format-Footnote-2131356 -Node: Internal Links131488 -Ref: Internal Links-Footnote-1134050 -Ref: Internal Links-Footnote-2134290 -Node: Radio Targets134431 -Node: External Links135148 -Ref: External Links-Footnote-1140632 -Node: Handling Links141056 -Ref: Handling Links-Footnote-1148812 -Ref: Handling Links-Footnote-2149002 -Ref: Handling Links-Footnote-3149298 -Ref: Handling Links-Footnote-4149560 -Ref: Handling Links-Footnote-5149682 -Node: Using Links Outside Org149757 -Node: Link Abbreviations150232 -Node: Search Options153193 -Ref: Search Options-Footnote-1155331 -Node: Custom Searches155412 -Node: TODO Items156446 -Ref: TODO Items-Footnote-1157571 -Node: TODO Basics157685 -Node: TODO Extensions160320 -Node: Workflow states161373 -Ref: Workflow states-Footnote-1162772 -Node: TODO types162888 -Ref: TODO types-Footnote-1164707 -Node: Multiple sets in one file164779 -Node: Fast access to TODO states166724 -Ref: Fast access to TODO states-Footnote-1167607 -Ref: Fast access to TODO states-Footnote-2167714 -Node: Per-file keywords168016 -Ref: Per-file keywords-Footnote-1169486 -Node: Faces for TODO keywords169690 -Node: TODO dependencies170763 -Node: Progress Logging173254 -Node: Closing items174391 -Ref: Closing items-Footnote-1175391 -Ref: Closing items-Footnote-2175465 -Node: Tracking TODO state changes175543 -Ref: Tracking TODO state changes-Footnote-1178678 -Ref: Tracking TODO state changes-Footnote-2178740 -Ref: Tracking TODO state changes-Footnote-3178898 -Node: Tracking your habits179176 -Node: Priorities183596 -Ref: Priorities-Footnote-1186108 -Node: Breaking Down Tasks186181 -Ref: Breaking Down Tasks-Footnote-1188223 -Node: Checkboxes188330 -Ref: Checkboxes-Footnote-1193473 -Ref: Checkboxes-Footnote-2193601 -Ref: Checkboxes-Footnote-3193781 -Node: Tags193895 -Node: Tag Inheritance194988 -Ref: Tag Inheritance-Footnote-1196860 -Ref: Tag Inheritance-Footnote-2196964 -Node: Setting Tags197094 -Ref: Setting Tags-Footnote-1203665 -Ref: Setting Tags-Footnote-2203843 -Node: Tag Hierarchy203921 -Node: Tag Searches207521 -Node: Properties and Columns208832 -Node: Property Syntax210220 -Node: Special Properties214824 -Node: Property Searches216514 -Node: Property Inheritance217989 -Node: Column View219861 -Node: Defining columns221112 -Node: Scope of column definitions221497 -Node: Column attributes222556 -Ref: Column attributes-Footnote-1226967 -Ref: Column attributes-Footnote-2227098 -Ref: Column attributes-Footnote-3227296 -Node: Using column view227435 -Ref: Turning column view on or off227601 -Ref: Editing values228642 -Ref: Modifying column view on-the-fly230045 -Node: Capturing column view230417 -Ref: Capturing column view-Footnote-1234145 -Node: Dates and Times234282 -Node: Timestamps235201 -Ref: Timestamps-Footnote-1237616 -Ref: Timestamps-Footnote-2237912 -Node: Creating Timestamps238695 -Node: The date/time prompt241709 -Ref: The date/time prompt-Footnote-1246670 -Ref: The date/time prompt-Footnote-2246841 -Ref: The date/time prompt-Footnote-3246952 -Ref: The date/time prompt-Footnote-4247207 -Node: Custom time format247305 -Node: Deadlines and Scheduling249074 -Ref: Deadlines and Scheduling-Footnote-1252644 -Node: Inserting deadline/schedule252807 -Ref: Inserting deadline/schedule-Footnote-1254799 -Ref: Inserting deadline/schedule-Footnote-2254960 -Ref: Inserting deadline/schedule-Footnote-3255086 -Node: Repeated tasks255212 -Ref: Repeated tasks-Footnote-1259847 -Ref: Repeated tasks-Footnote-2259930 -Ref: Repeated tasks-Footnote-3260213 -Node: Clocking Work Time260435 -Ref: Clocking Work Time-Footnote-1261640 -Ref: Clocking Work Time-Footnote-2261793 -Node: Clocking commands261935 -Ref: Clocking commands-Footnote-1267040 -Ref: Clocking commands-Footnote-2267155 -Ref: Clocking commands-Footnote-3267237 -Ref: Clocking commands-Footnote-4267300 -Node: The clock table267383 -Ref: The clock table-Footnote-1276201 -Ref: The clock table-Footnote-2276310 -Ref: The clock table-Footnote-3276408 -Node: Resolving idle time276534 -Ref: Resolving idle time (1)276730 -Ref: Continuous clocking279927 -Ref: Clocking out automatically after some idle time280433 -Ref: Resolving idle time-Footnote-1281065 -Node: Effort Estimates281513 -Ref: Effort Estimates-Footnote-1284470 -Node: Timers284581 -Node: Refiling and Archiving286794 -Node: Refile and Copy287357 -Ref: Refile and Copy-Footnote-1290185 -Node: Archiving290299 -Node: Moving subtrees291012 -Node: Internal archiving293138 -Node: Capture and Attachments295867 -Node: Capture296672 -Node: Setting up capture297196 -Node: Using capture297559 -Node: Capture templates299957 -Node: Template elements301996 -Ref: Template elements-Footnote-1310202 -Ref: Template elements-Footnote-2310535 -Ref: Template elements-Footnote-3310818 -Node: Template expansion310913 -Ref: Template expansion-Footnote-1314980 -Ref: Template expansion-Footnote-2315071 -Ref: Template expansion-Footnote-3315261 -Node: Templates in contexts315360 -Node: Attachments316205 -Node: Attachment defaults and dispatcher317235 -Ref: Attachment defaults and dispatcher-Footnote-1320585 -Node: Attachment options320736 -Node: Attachment links324755 -Node: Automatic version-control with Git325394 -Node: Attach from Dired325909 -Node: RSS Feeds327273 -Node: Agenda Views328724 -Node: Agenda Files331131 -Ref: Agenda Files-Footnote-1334042 -Ref: Agenda Files-Footnote-2334186 -Node: Agenda Dispatcher334384 -Ref: Agenda Dispatcher-Footnote-1337261 -Ref: Agenda Dispatcher-Footnote-2337359 -Node: Built-in Agenda Views337465 -Node: Weekly/daily agenda338062 -Ref: Calendar/Diary integration339519 -Ref: Anniversaries from BBDB341595 -Ref: Appointment reminders343386 -Ref: Weekly/daily agenda-Footnote-1343936 -Ref: Weekly/daily agenda-Footnote-2344180 -Node: Global TODO list344400 -Node: Matching tags and properties347251 -Node: Search view354360 -Node: Stuck projects356007 -Node: Presentation and Sorting358144 -Node: Categories359121 -Node: Time-of-day specifications359867 -Ref: Time-of-day specifications-Footnote-1361858 -Node: Sorting of agenda items361981 -Node: Filtering/limiting agenda items363599 -Ref: Filtering in the agenda364304 -Ref: Computed tag filtering368438 -Ref: Setting limits for the agenda369932 -Ref: Filtering/limiting agenda items-Footnote-1371481 -Node: Agenda Commands372033 -Ref: Motion (1)372766 -Ref: View/Go to Org file372969 -Ref: Change display374475 -Ref: Remote editing382032 -Ref: Bulk remote editing selected entries387385 -Ref: Calendar commands390474 -Ref: Quit and exit392355 -Ref: Agenda Commands-Footnote-1392717 -Ref: Agenda Commands-Footnote-2392793 -Ref: Agenda Commands-Footnote-3392897 -Node: Custom Agenda Views392984 -Node: Storing searches393636 -Ref: Storing searches-Footnote-1396588 -Ref: Storing searches-Footnote-2396705 -Node: Block agenda396952 -Node: Setting options398281 -Node: Exporting Agenda Views401895 -Ref: Exporting Agenda Views-Footnote-1406434 -Ref: Exporting Agenda Views-Footnote-2406655 -Ref: Exporting Agenda Views-Footnote-3406805 -Ref: Exporting Agenda Views-Footnote-4406992 -Node: Agenda Column View407074 -Node: Markup for Rich Contents410422 -Node: Paragraphs411720 -Node: Emphasis and Monospace412855 -Node: Subscripts and Superscripts413914 -Node: Special Symbols415532 -Ref: Special Symbols-Footnote-1417445 -Ref: Special Symbols-Footnote-2417610 -Node: Embedded LaTeX417707 -Ref: Embedded LaTeX-Footnote-1418556 -Node: LaTeX fragments418752 -Ref: LaTeX fragments-Footnote-1420909 -Node: Previewing LaTeX fragments421102 -Ref: Previewing LaTeX fragments-Footnote-1422585 -Node: CDLaTeX mode422834 -Ref: CDLaTeX mode-Footnote-1425583 -Node: Literal Examples425730 -Ref: Literal Examples-Footnote-1430841 -Ref: Literal Examples-Footnote-2431297 -Ref: Literal Examples-Footnote-3431475 -Ref: Literal Examples-Footnote-4431660 -Node: Images431758 -Ref: Images-Footnote-1433885 -Ref: Images-Footnote-2434008 -Ref: Images-Footnote-3434169 -Node: Captions434255 -Node: Horizontal Rules434955 -Node: Creating Footnotes435211 -Ref: Creating Footnotes-Footnote-1438340 -Ref: Creating Footnotes-Footnote-2438446 -Node: Exporting438553 -Node: The Export Dispatcher441327 -Node: Export Settings444081 -Ref: Export Settings-Footnote-1452174 -Ref: Export Settings-Footnote-2452286 -Ref: Export Settings-Footnote-3452387 -Node: Table of Contents452585 -Ref: Table of Contents-Footnote-1455259 -Node: Include Files455426 -Ref: Include Files-Footnote-1458363 -Node: Macro Replacement458541 -Ref: Macro Replacement-Footnote-1462422 -Node: Comment Lines462639 -Ref: Comment Lines-Footnote-1463502 -Node: ASCII/Latin-1/UTF-8 export463606 -Ref: ASCII export commands464460 -Ref: ASCII specific export settings464993 -Ref: Header and sectioning structure465437 -Ref: Quoting ASCII text465711 -Ref: ASCII specific attributes466083 -Ref: ASCII special blocks466360 -Node: Beamer Export466707 -Node: Beamer export commands467457 -Node: Beamer specific export settings468162 -Node: Frames and Blocks in Beamer470067 -Ref: Frames and Blocks in Beamer-Footnote-1473425 -Node: Beamer specific syntax473584 -Node: Editing support475563 -Node: A Beamer example476034 -Node: HTML Export477288 -Node: HTML export commands478398 -Node: HTML specific export settings478940 -Node: HTML doctypes481159 -Node: HTML preamble and postamble483334 -Node: Quoting HTML tags484399 -Node: Headlines in HTML export485098 -Node: Links in HTML export485693 -Node: Tables in HTML export487162 -Node: Images in HTML export488619 -Node: Math formatting in HTML export490109 -Ref: Math formatting in HTML export-Footnote-1491499 -Ref: Math formatting in HTML export-Footnote-2491691 -Node: Text areas in HTML export491974 -Node: CSS support493119 -Ref: CSS support-Footnote-1496770 -Node: JavaScript support496950 -Node: LaTeX Export500137 -Node: LaTeX/PDF export commands502057 -Ref: LaTeX/PDF export commands-Footnote-1503560 -Node: LaTeX specific export settings503762 -Node: LaTeX header and sectioning507246 -Node: Quoting LaTeX code511076 -Node: Tables in LaTeX export511872 -Node: Images in LaTeX export517138 -Node: Plain lists in LaTeX export519795 -Node: Source blocks in LaTeX export520815 -Ref: Source blocks in LaTeX export-Footnote-1522471 -Node: Example blocks in LaTeX export522629 -Node: Special blocks in LaTeX export523355 -Node: Horizontal rules in LaTeX export524618 -Node: Verse blocks in LaTeX export525055 -Node: Quote blocks in LaTeX export527069 -Node: Markdown Export528188 -Ref: Markdown export commands528656 -Ref: Header and sectioning structure (1)529093 -Node: OpenDocument Text Export529510 -Ref: OpenDocument Text Export-Footnote-1530616 -Node: Pre-requisites for ODT export530766 -Node: ODT export commands531144 -Node: ODT specific export settings532328 -Node: Extending ODT export533379 -Ref: Automatically exporting to other formats534190 -Ref: Converting between document formats534616 -Node: Applying custom styles535158 -Ref: Applying custom styles the easy way535690 -Ref: Using third-party styles and templates536648 -Node: Links in ODT export536945 -Node: Tables in ODT export537607 -Node: Images in ODT export539617 -Ref: Embedding images539821 -Ref: Embedding clickable images540138 -Ref: Sizing and scaling of embedded images540472 -Ref: Anchoring of images542156 -Node: Math formatting in ODT export542478 -Node: LaTeX math snippets542907 -Ref: LaTeX math snippets-Footnote-1545160 -Ref: LaTeX math snippets-Footnote-2545236 -Node: MathML and OpenDocument formula files545282 -Node: Labels and captions in ODT export545790 -Node: Literal examples in ODT export547066 -Node: Advanced topics in ODT export547907 -Ref: Configuring a document converter548217 -Ref: Working with OpenDocument style files549158 -Ref: x-orgodtstyles-xml549624 -Ref: x-orgodtcontenttemplate-xml549966 -Ref: x-overriding-factory-styles550610 -Ref: Creating one-off styles551854 -Ref: Customizing tables in ODT export553858 -Ref: Validating OpenDocument XML558718 -Ref: Advanced topics in ODT export-Footnote-1559515 -Ref: Advanced topics in ODT export-Footnote-2559620 -Ref: Advanced topics in ODT export-Footnote-3559713 -Node: Org Export560061 -Ref: Org export commands560417 -Node: Texinfo Export560723 -Node: Texinfo export commands561763 -Node: Texinfo specific export settings562388 -Node: Texinfo file header563541 -Node: Texinfo title and copyright page564524 -Node: Info directory file565888 -Node: Headings and sectioning structure566613 -Node: Indices568643 -Node: Quoting Texinfo code569672 -Node: Plain lists in Texinfo export570170 -Node: Tables in Texinfo export574896 -Node: Images in Texinfo export575392 -Node: Quotations in Texinfo export576030 -Node: Key bindings in Texinfo export576982 -Node: Special blocks in Texinfo export577785 -Node: A Texinfo example578620 -Node: iCalendar Export580722 -Node: Other Built-in Back-ends585011 -Node: Advanced Export Configuration585643 -Ref: Export hooks585855 -Ref: Filters587060 -Ref: Defining filters for individual files589569 -Ref: Extending an existing back-end590375 -Node: Export in Foreign Buffers592615 -Node: Bare HTML593856 -Node: Publishing594398 -Node: Configuration595274 -Node: Project alist596056 -Node: Sources and destinations597198 -Node: Selecting files598516 -Node: Publishing action599471 -Ref: Publishing action-Footnote-1601304 -Node: Publishing options601467 -Ref: Generic properties602219 -Ref: ASCII specific properties604106 -Ref: Beamer specific properties605706 -Ref: HTML specific properties606271 -Ref: LaTeX specific properties610754 -Ref: Markdown specific properties613920 -Ref: ODT specific properties614217 -Ref: Texinfo specific properties615149 -Node: Publishing links616571 -Node: Site map618025 -Node: Generating an index621342 -Node: Uploading Files622134 -Node: Sample Configuration623917 -Node: Simple example624415 -Node: Complex example625131 -Node: Triggering Publication627180 -Node: Citation handling628206 -Node: Citations629205 -Node: Citation export processors630898 -Node: Bibliography printing633638 -Node: Bibliography options in the ``biblatex'' and ``csl'' export processors634794 -Node: Working with Source Code636918 -Node: Features Overview639257 -Node: Structure of Code Blocks642016 -Node: Using Header Arguments644525 -Ref: System-wide header arguments645252 -Ref: Header arguments in Org mode properties646923 -Ref: Code block specific header arguments648749 -Ref: Header arguments in function calls650248 -Node: Environment of a Code Block650922 -Ref: Passing arguments651136 -Ref: Using sessions659422 -Ref: Choosing a working directory660821 -Ref: Inserting headers and footers663126 -Node: Evaluating Code Blocks663636 -Ref: How to evaluate source code664091 -Ref: Limit code block evaluation667041 -Ref: Cache results of evaluation668027 -Ref: Evaluating Code Blocks-Footnote-1670540 -Ref: Evaluating Code Blocks-Footnote-2670674 -Node: Results of Evaluation670832 -Ref: Collection671639 -Ref: Type673100 -Ref: Format677043 -Ref: Handling679476 -Ref: Post-processing680861 -Ref: Results of Evaluation-Footnote-1682611 -Node: Exporting Code Blocks682769 -Node: Extracting Source Code686440 -Ref: Header arguments687421 -Ref: Functions691656 -Ref: Tangle hooks691907 -Ref: Jumping between code and Org692683 -Node: Languages693193 -Node: Editing Source Code694194 -Node: Noweb Reference Syntax696924 -Ref: Noweb Reference Syntax-Footnote-1703564 -Node: Library of Babel703655 -Node: Key bindings and Useful Functions704373 -Node: Batch Execution706798 -Node: Miscellaneous707581 -Node: Completion708975 -Node: Structure Templates710900 -Ref: Structure Templates-Footnote-1712650 -Node: Speed Keys712742 -Node: Clean View713911 -Node: Org Indent Mode715113 -Ref: Org Indent Mode-Footnote-1716319 -Node: Hard indentation716543 -Ref: Hard indentation-Footnote-1718026 -Ref: Hard indentation-Footnote-2718132 -Node: Execute commands in the active region718276 -Node: Dynamic Headline Numbering719288 -Node: The Very Busy C-c C-c Key720454 -Node: In-buffer Settings722442 -Ref: In-buffer Settings-Footnote-1731730 -Node: Regular Expressions731928 -Node: Org Syntax732550 -Node: Documentation Access734208 -Node: Escape Character734629 -Node: Code Evaluation Security735490 -Node: Interaction738357 -Node: Cooperation738780 -Node: Conflicts741672 -Node: TTY Keys746274 -Node: Protocols747876 -Node: The store-link protocol749337 -Node: The capture protocol750480 -Node: The open-source protocol752113 -Node: Org Crypt755354 -Node: Org Mobile757233 -Node: Setting up the staging area758589 -Ref: Setting up the staging area-Footnote-1759829 -Ref: Setting up the staging area-Footnote-2760036 -Node: Pushing to the mobile application760208 -Ref: Pushing to the mobile application-Footnote-1761219 -Ref: Pushing to the mobile application-Footnote-2761310 -Ref: Pushing to the mobile application-Footnote-3761677 -Node: Pulling from the mobile application761753 -Ref: Pulling from the mobile application-Footnote-1764066 -Node: Hacking764119 -Node: Hooks765070 -Node: Add-on Packages765394 -Node: Adding Hyperlink Types765863 -Node: Adding Export Back-ends769458 -Node: Tables in Arbitrary Syntax770715 -Node: Radio tables771984 -Node: A LaTeX example774121 -Ref: A LaTeX example-Footnote-1777973 -Ref: A LaTeX example-Footnote-2778016 -Ref: A LaTeX example-Footnote-3778177 -Node: Translator functions778629 -Node: Dynamic Blocks780805 -Node: Special Agenda Views783051 -Ref: Special Agenda Views-Footnote-1786762 -Ref: Special Agenda Views-Footnote-2786969 -Node: Speeding Up Your Agendas787101 -Node: Extracting Agenda Information788492 -Node: Using the Property API792297 -Node: Using the Mapping API795652 -Node: History and Acknowledgments799685 -Ref: From Carsten799883 -Ref: From Bastien803314 -Ref: List of Contributions805446 -Node: GNU Free Documentation License814108 -Ref: ADDENDUM How to use this License for your documents838066 -Node: Main Index839459 -Node: Key Index937284 -Node: Command and Function Index993940 -Node: Variable Index1041550 +Node: Introduction23025 +Node: Summary23487 +Node: Installation26642 +Ref: Using Emacs packaging system27565 +Ref: Using Org's git repository28423 +Ref: Installing Org's contributed packages29381 +Node: Activation30011 +Ref: Activation-Footnote-131685 +Node: Feedback31813 +Ref: How to create a useful backtrace35028 +Ref: How to profile Org performance36144 +Ref: Feedback-Footnote-138369 +Node: Conventions38495 +Ref: TODO keywords tags properties etc38666 +Ref: Key bindings and commands39559 +Node: Document Structure40189 +Node: Headlines41361 +Ref: Headlines-Footnote-142660 +Node: Visibility Cycling42939 +Node: Global and local cycling43329 +Ref: Global and local cycling-Footnote-146040 +Ref: Global and local cycling-Footnote-246102 +Node: Initial visibility46406 +Ref: Initial visibility-Footnote-147596 +Node: Catching invisible edits47789 +Node: Motion48531 +Node: Structure Editing49995 +Node: Sparse Trees56584 +Ref: Sparse Trees-Footnote-159181 +Ref: Sparse Trees-Footnote-259296 +Node: Plain Lists59372 +Ref: Plain Lists-Footnote-166959 +Ref: Plain Lists-Footnote-267323 +Ref: Plain Lists-Footnote-367423 +Ref: Plain Lists-Footnote-467680 +Ref: Plain Lists-Footnote-567857 +Ref: Plain Lists-Footnote-667961 +Ref: Plain Lists-Footnote-768067 +Node: Drawers68137 +Ref: Drawers-Footnote-169832 +Node: Blocks69944 +Node: Tables70537 +Node: Built-in Table Editor71220 +Ref: Creation and conversion72956 +Ref: Re-aligning and field motion73894 +Ref: Column and row editing74829 +Ref: Regions77259 +Ref: Calculations78658 +Ref: Miscellaneous (1)79471 +Ref: Built-in Table Editor-Footnote-181948 +Node: Column Width and Alignment82056 +Node: Column Groups85393 +Node: Orgtbl Mode86960 +Node: The Spreadsheet87775 +Node: References89249 +Ref: Field references89708 +Ref: Range references92147 +Ref: Field coordinates in formulas93406 +Ref: Named references94391 +Ref: Remote references95362 +Ref: References-Footnote-196284 +Ref: References-Footnote-296512 +Ref: References-Footnote-396615 +Node: Formula syntax for Calc96940 +Ref: Formula syntax for Calc-Footnote-1102802 +Node: Formula syntax for Lisp103141 +Node: Durations and time values105676 +Node: Field and range formulas107063 +Node: Column formulas109532 +Node: Lookup functions111644 +Node: Editing and debugging formulas113613 +Ref: Using multiple TBLFM lines118130 +Ref: Debugging formulas118973 +Node: Updating the table119391 +Node: Advanced features120763 +Ref: Advanced features-Footnote-1125214 +Node: Org Plot125322 +Ref: Graphical plots using Gnuplot125523 +Ref: Plot options128046 +Ref: ASCII bar plots130965 +Node: Hyperlinks132214 +Node: Link Format133078 +Ref: Link Format-Footnote-1135247 +Ref: Link Format-Footnote-2135479 +Node: Internal Links135611 +Ref: Internal Links-Footnote-1138173 +Ref: Internal Links-Footnote-2138413 +Node: Radio Targets138554 +Node: External Links139271 +Ref: External Links-Footnote-1144900 +Node: Handling Links145324 +Ref: Handling Links-Footnote-1153846 +Ref: Handling Links-Footnote-2154036 +Ref: Handling Links-Footnote-3154170 +Ref: Handling Links-Footnote-4154466 +Ref: Handling Links-Footnote-5154728 +Ref: Handling Links-Footnote-6154850 +Node: Using Links Outside Org154925 +Node: Link Abbreviations155400 +Node: Search Options158362 +Ref: Search Options-Footnote-1160507 +Node: Custom Searches160588 +Node: TODO Items161622 +Ref: TODO Items-Footnote-1162747 +Node: TODO Basics162861 +Node: TODO Extensions165496 +Node: Workflow states166549 +Ref: Workflow states-Footnote-1167948 +Node: TODO types168064 +Ref: TODO types-Footnote-1169883 +Node: Multiple sets in one file169955 +Node: Fast access to TODO states171900 +Ref: Fast access to TODO states-Footnote-1172780 +Node: Per-file keywords172887 +Ref: Per-file keywords-Footnote-1174357 +Node: Faces for TODO keywords174561 +Node: TODO dependencies175634 +Node: Progress Logging178125 +Node: Closing items179262 +Ref: Closing items-Footnote-1180262 +Ref: Closing items-Footnote-2180336 +Node: Tracking TODO state changes180414 +Ref: Tracking TODO state changes-Footnote-1183549 +Ref: Tracking TODO state changes-Footnote-2183611 +Ref: Tracking TODO state changes-Footnote-3183769 +Node: Tracking your habits184047 +Node: Priorities188572 +Ref: Priorities-Footnote-1191084 +Node: Breaking Down Tasks191157 +Ref: Breaking Down Tasks-Footnote-1193204 +Node: Checkboxes193311 +Ref: Checkboxes-Footnote-1199030 +Ref: Checkboxes-Footnote-2199158 +Ref: Checkboxes-Footnote-3199338 +Node: Tags199452 +Node: Tag Inheritance200545 +Ref: Tag Inheritance-Footnote-1202066 +Node: Setting Tags202170 +Ref: Setting Tags-Footnote-1208939 +Ref: Setting Tags-Footnote-2209117 +Node: Tag Hierarchy209195 +Node: Tag Searches212795 +Node: Properties and Columns214020 +Node: Property Syntax215408 +Node: Special Properties220009 +Ref: Special Properties-Footnote-1221758 +Node: Property Searches222058 +Node: Property Inheritance223444 +Node: Column View225316 +Node: Defining columns226567 +Node: Scope of column definitions226952 +Node: Column attributes228011 +Ref: Column attributes-Footnote-1232422 +Ref: Column attributes-Footnote-2232553 +Ref: Column attributes-Footnote-3232751 +Node: Using column view232890 +Ref: Turning column view on or off233056 +Ref: Editing values234097 +Ref: Modifying column view on-the-fly235500 +Node: Capturing column view236195 +Ref: Capturing column view-Footnote-1240176 +Node: Dates and Times240313 +Node: Timestamps241482 +Ref: Timestamps-Footnote-1244448 +Ref: Timestamps-Footnote-2244744 +Node: Creating Timestamps245532 +Node: The date/time prompt248543 +Ref: The date/time prompt-Footnote-1253504 +Ref: The date/time prompt-Footnote-2253675 +Ref: The date/time prompt-Footnote-3253786 +Ref: The date/time prompt-Footnote-4254041 +Node: Custom time format254139 +Node: Deadlines and Scheduling255906 +Ref: Deadlines and Scheduling-Footnote-1259476 +Node: Inserting deadline/schedule259639 +Ref: Inserting deadline/schedule-Footnote-1261631 +Ref: Inserting deadline/schedule-Footnote-2261792 +Ref: Inserting deadline/schedule-Footnote-3261918 +Node: Repeated tasks262044 +Ref: Repeated tasks-Footnote-1266759 +Ref: Repeated tasks-Footnote-2266842 +Ref: Repeated tasks-Footnote-3267125 +Node: Clocking Work Time267347 +Ref: Clocking Work Time-Footnote-1268552 +Ref: Clocking Work Time-Footnote-2268705 +Node: Clocking commands268847 +Ref: Clocking commands-Footnote-1274077 +Ref: Clocking commands-Footnote-2274192 +Ref: Clocking commands-Footnote-3274274 +Ref: Clocking commands-Footnote-4274337 +Node: The clock table274420 +Ref: The clock table-Footnote-1282538 +Ref: The clock table-Footnote-2282647 +Ref: The clock table-Footnote-3282745 +Node: Resolving idle time282871 +Ref: Resolving idle time (1)283067 +Ref: Continuous clocking286264 +Ref: Clocking out automatically after some idle time286770 +Ref: Resolving idle time-Footnote-1287402 +Node: Effort Estimates287851 +Ref: Effort Estimates-Footnote-1290808 +Node: Timers290919 +Node: Refiling and Archiving293132 +Node: Refile and Copy293695 +Ref: Refile and Copy-Footnote-1296523 +Node: Archiving296637 +Node: Moving subtrees297350 +Node: Internal archiving299476 +Node: Capture and Attachments302205 +Node: Capture303010 +Node: Setting up capture303534 +Node: Using capture303897 +Node: Capture templates306292 +Node: Template elements308331 +Ref: Template elements-Footnote-1316596 +Ref: Template elements-Footnote-2316929 +Ref: Template elements-Footnote-3317274 +Node: Template expansion317369 +Ref: Template expansion-Footnote-1321686 +Ref: Template expansion-Footnote-2321777 +Ref: Template expansion-Footnote-3321967 +Node: Templates in contexts322066 +Node: Attachments322911 +Node: Attachment defaults and dispatcher323941 +Ref: Attachment defaults and dispatcher-Footnote-1327291 +Node: Attachment options327442 +Node: Attachment links331461 +Node: Automatic version-control with Git332100 +Node: Attach from Dired332615 +Node: RSS Feeds333979 +Node: Agenda Views335430 +Node: Agenda Files337837 +Ref: Agenda Files-Footnote-1340748 +Ref: Agenda Files-Footnote-2340892 +Node: Agenda Dispatcher341090 +Ref: Agenda Dispatcher-Footnote-1343964 +Node: Built-in Agenda Views344062 +Node: Weekly/daily agenda344659 +Ref: Calendar/Diary integration346116 +Ref: Anniversaries from BBDB348192 +Ref: Appointment reminders349983 +Ref: Weekly/daily agenda-Footnote-1350533 +Ref: Weekly/daily agenda-Footnote-2350777 +Node: Global TODO list350997 +Node: Matching tags and properties353848 +Ref: Matching tags and properties-Footnote-1362331 +Node: Search view362436 +Node: Stuck projects364083 +Node: Presentation and Sorting366220 +Node: Categories367197 +Node: Time-of-day specifications367943 +Ref: Time-of-day specifications-Footnote-1369934 +Node: Sorting of agenda items370057 +Node: Filtering/limiting agenda items371645 +Ref: Filtering in the agenda372350 +Ref: Computed tag filtering376484 +Ref: Setting limits for the agenda377978 +Ref: Filtering/limiting agenda items-Footnote-1379527 +Node: Agenda Commands380079 +Ref: Motion (1)380812 +Ref: View/Go to Org file381015 +Ref: Change display382521 +Ref: Remote editing390292 +Ref: Bulk remote editing selected entries395645 +Ref: Calendar commands398734 +Ref: Quit and exit400615 +Ref: Agenda Commands-Footnote-1400977 +Ref: Agenda Commands-Footnote-2401053 +Ref: Agenda Commands-Footnote-3401157 +Node: Custom Agenda Views401244 +Node: Storing searches401896 +Ref: Storing searches-Footnote-1404848 +Ref: Storing searches-Footnote-2404965 +Node: Block agenda405211 +Node: Setting options406540 +Node: Exporting Agenda Views410154 +Ref: Exporting Agenda Views-Footnote-1414693 +Ref: Exporting Agenda Views-Footnote-2414914 +Ref: Exporting Agenda Views-Footnote-3415064 +Ref: Exporting Agenda Views-Footnote-4415251 +Node: Agenda Column View415333 +Node: Markup for Rich Contents418681 +Node: Paragraphs419979 +Node: Emphasis and Monospace421114 +Ref: Emphasis and Monospace-Footnote-1422695 +Node: Subscripts and Superscripts422781 +Ref: Subscripts and Superscripts-Footnote-1424521 +Node: Special Symbols424638 +Ref: Special Symbols-Footnote-1426550 +Ref: Special Symbols-Footnote-2426715 +Node: Embedded LaTeX426812 +Ref: Embedded LaTeX-Footnote-1427660 +Node: LaTeX fragments427856 +Ref: LaTeX fragments-Footnote-1430309 +Node: Previewing LaTeX fragments430502 +Ref: Previewing LaTeX fragments-Footnote-1431985 +Node: CDLaTeX mode432234 +Ref: CDLaTeX mode-Footnote-1434983 +Node: Literal Examples435130 +Ref: Literal Examples-Footnote-1440236 +Ref: Literal Examples-Footnote-2440692 +Ref: Literal Examples-Footnote-3440870 +Ref: Literal Examples-Footnote-4441024 +Ref: Literal Examples-Footnote-5441252 +Ref: Literal Examples-Footnote-6441437 +Node: Images441535 +Ref: Images-Footnote-1445602 +Ref: Images-Footnote-2445725 +Ref: Images-Footnote-3445886 +Node: Captions445972 +Node: Horizontal Rules446671 +Node: Creating Footnotes446927 +Ref: Creating Footnotes-Footnote-1450056 +Ref: Creating Footnotes-Footnote-2450162 +Node: Exporting450269 +Node: The Export Dispatcher453037 +Node: Export Settings456497 +Ref: Export Settings-Footnote-1465253 +Ref: Export Settings-Footnote-2465365 +Ref: Export Settings-Footnote-3465466 +Node: Table of Contents465664 +Ref: Table of Contents-Footnote-1468325 +Node: Include Files468491 +Ref: Include Files-Footnote-1471579 +Node: Macro Replacement471757 +Ref: Macro Replacement-Footnote-1475637 +Node: Comment Lines475854 +Ref: Comment Lines-Footnote-1476717 +Node: ASCII/Latin-1/UTF-8 export476821 +Ref: ASCII export commands477675 +Ref: ASCII specific export settings478208 +Ref: Header and sectioning structure478651 +Ref: Quoting ASCII text478925 +Ref: ASCII specific attributes479295 +Ref: ASCII special blocks479571 +Node: Beamer Export479917 +Node: Beamer export commands480667 +Node: Beamer specific export settings481372 +Node: Frames and Blocks in Beamer483276 +Ref: Frames and Blocks in Beamer-Footnote-1486633 +Node: Beamer specific syntax486792 +Node: Editing support488768 +Node: A Beamer example489239 +Node: HTML Export490493 +Node: HTML export commands491681 +Node: HTML specific export settings492223 +Node: HTML doctypes494442 +Node: HTML preamble and postamble496614 +Node: Bare HTML497671 +Node: Quoting HTML tags498259 +Node: Headlines in HTML export498939 +Node: Links in HTML export499534 +Node: Tables in HTML export500997 +Node: Images in HTML export502452 +Node: Math formatting in HTML export503939 +Ref: Math formatting in HTML export-Footnote-1505329 +Ref: Math formatting in HTML export-Footnote-2505521 +Node: Text areas in HTML export505804 +Node: CSS support506947 +Ref: CSS support-Footnote-1510597 +Node: JavaScript support510777 +Node: LaTeX Export513964 +Ref: LaTeX Export-Footnote-1516190 +Node: LaTeX/PDF export commands516337 +Ref: LaTeX/PDF export commands-Footnote-1517838 +Node: LaTeX specific export settings518040 +Node: LaTeX header and sectioning521673 +Node: Quoting LaTeX code525498 +Node: Tables in LaTeX export526381 +Node: Images in LaTeX export531633 +Node: Plain lists in LaTeX export534283 +Node: Source blocks in LaTeX export535302 +Ref: Source blocks in LaTeX export-Footnote-1537428 +Node: Example blocks in LaTeX export537586 +Node: Special blocks in LaTeX export538311 +Node: Horizontal rules in LaTeX export539572 +Node: Verse blocks in LaTeX export540008 +Node: Quote blocks in LaTeX export542737 +Node: Markdown Export543855 +Ref: Markdown export commands544592 +Ref: Header and sectioning structure (1)545029 +Node: OpenDocument Text Export545573 +Ref: OpenDocument Text Export-Footnote-1546678 +Node: Pre-requisites for ODT export546828 +Node: ODT export commands547205 +Node: ODT specific export settings548385 +Node: Extending ODT export549432 +Ref: Automatically exporting to other formats550242 +Ref: Converting between document formats550667 +Node: Applying custom styles551208 +Ref: Applying custom styles the easy way551739 +Ref: Using third-party styles and templates552697 +Node: Links in ODT export552993 +Node: Tables in ODT export553655 +Node: Images in ODT export555661 +Ref: Embedding images555865 +Ref: Embedding clickable images556181 +Ref: Sizing and scaling of embedded images556515 +Ref: Anchoring of images558195 +Node: Math formatting in ODT export558516 +Node: LaTeX math snippets558945 +Ref: LaTeX math snippets-Footnote-1561194 +Ref: LaTeX math snippets-Footnote-2561270 +Node: MathML and OpenDocument formula files561316 +Node: Labels and captions in ODT export561824 +Node: Literal examples in ODT export563100 +Node: Advanced topics in ODT export563939 +Ref: Configuring a document converter564248 +Ref: Working with OpenDocument style files565188 +Ref: x-orgodtstyles-xml565654 +Ref: x-orgodtcontenttemplate-xml565996 +Ref: x-overriding-factory-styles566640 +Ref: Creating one-off styles567883 +Ref: Customizing tables in ODT export569884 +Ref: Validating OpenDocument XML574744 +Ref: Advanced topics in ODT export-Footnote-1575540 +Ref: Advanced topics in ODT export-Footnote-2575645 +Ref: Advanced topics in ODT export-Footnote-3575738 +Node: Org Export576086 +Ref: Org export commands576440 +Node: Texinfo Export576746 +Node: Texinfo export commands577786 +Node: Texinfo specific export settings578411 +Node: Texinfo file header580119 +Node: Texinfo title and copyright page581101 +Node: Info directory file582464 +Node: Headings and sectioning structure583180 +Node: Indices585205 +Node: Quoting Texinfo code586231 +Node: Plain lists in Texinfo export586729 +Node: Tables in Texinfo export591457 +Node: Images in Texinfo export591952 +Node: Quotations in Texinfo export592589 +Node: Key bindings in Texinfo export593541 +Node: Special blocks in Texinfo export594344 +Node: A Texinfo example595177 +Node: iCalendar Export597268 +Ref: iCalendar Export-Footnote-1602491 +Node: Other Built-in Backends602674 +Node: Advanced Export Configuration603300 +Ref: Export hooks603499 +Ref: Filters604719 +Ref: Defining filters for individual files607219 +Ref: Summary of the export process608024 +Ref: Extending an existing backend613377 +Ref: Advanced Export Configuration-Footnote-1615722 +Ref: Advanced Export Configuration-Footnote-2616078 +Ref: Advanced Export Configuration-Footnote-3616227 +Node: Export Region616313 +Node: Publishing617371 +Node: Configuration618247 +Node: Project alist619029 +Node: Sources and destinations620171 +Node: Selecting files621489 +Node: Publishing action622444 +Ref: Publishing action-Footnote-1624277 +Node: Publishing options624440 +Ref: Generic properties625192 +Ref: ASCII specific properties627880 +Ref: Beamer specific properties629480 +Ref: HTML specific properties630112 +Ref: LaTeX specific properties635348 +Ref: Markdown specific properties638856 +Ref: ODT specific properties639153 +Ref: Texinfo specific properties640150 +Node: Publishing links641578 +Node: Site map643032 +Node: Generating an index645858 +Node: Uploading Files646650 +Node: Sample Configuration648433 +Node: Simple example648931 +Node: Complex example649647 +Node: Triggering Publication651735 +Node: Citation handling652761 +Node: Citations655811 +Node: Citation export processors658185 +Node: Bibliography printing661667 +Node: Bibliography options in the biblatex and csl export processors662815 +Node: Working with Source Code664934 +Node: Features Overview667273 +Node: Structure of Code Blocks670031 +Node: Using Header Arguments672897 +Ref: System-wide header arguments673624 +Ref: Header arguments in Org mode properties675295 +Ref: Code block specific header arguments677121 +Ref: Header arguments in function calls678620 +Node: Environment of a Code Block679294 +Ref: Passing arguments679508 +Ref: Using sessions688053 +Ref: Choosing a working directory689452 +Ref: Inserting headers and footers691757 +Node: Evaluating Code Blocks692267 +Ref: How to evaluate source code692722 +Ref: Limit code block evaluation695672 +Ref: Cache results of evaluation696658 +Ref: Evaluating Code Blocks-Footnote-1699171 +Ref: Evaluating Code Blocks-Footnote-2699305 +Node: Results of Evaluation699463 +Ref: Collection700270 +Ref: Type701731 +Ref: Format705755 +Ref: Handling708347 +Ref: Post-processing709738 +Ref: Results of Evaluation-Footnote-1711488 +Node: Exporting Code Blocks711646 +Node: Extracting Source Code715317 +Ref: Header arguments716298 +Ref: Functions720533 +Ref: Tangle hooks720784 +Ref: Jumping between code and Org721560 +Node: Languages722070 +Node: Editing Source Code723071 +Node: Noweb Reference Syntax726013 +Ref: Noweb Reference Syntax-Footnote-1732740 +Ref: Noweb Reference Syntax-Footnote-2732831 +Ref: Noweb Reference Syntax-Footnote-3733444 +Node: Library of Babel733564 +Node: Key bindings and Useful Functions734282 +Node: Batch Execution736707 +Node: Miscellaneous737490 +Node: Completion738953 +Node: Structure Templates740878 +Ref: Structure Templates-Footnote-1742628 +Node: Speed Keys742720 +Node: Clean View743889 +Node: Org Indent Mode745091 +Ref: Org Indent Mode-Footnote-1746297 +Node: Hard indentation746521 +Ref: Hard indentation-Footnote-1748004 +Ref: Hard indentation-Footnote-2748110 +Node: Execute commands in the active region748254 +Node: Dynamic Headline Numbering749266 +Node: The Very Busy C-c C-c Key750432 +Node: In-buffer Settings752420 +Ref: In-buffer Settings-Footnote-1762368 +Node: Regular Expressions762566 +Node: Org Syntax763188 +Node: Documentation Access764837 +Node: Escape Character765258 +Node: Code Evaluation Security766119 +Node: Interaction768986 +Node: Cooperation769409 +Node: Conflicts772478 +Node: TTY Keys777080 +Node: Protocols778717 +Node: The store-link protocol780178 +Node: The capture protocol781321 +Node: The open-source protocol782954 +Node: Org Crypt786197 +Node: Org Mobile788072 +Node: Setting up the staging area789463 +Ref: Setting up the staging area-Footnote-1790703 +Ref: Setting up the staging area-Footnote-2790910 +Node: Pushing to the mobile application791082 +Ref: Pushing to the mobile application-Footnote-1792093 +Ref: Pushing to the mobile application-Footnote-2792184 +Ref: Pushing to the mobile application-Footnote-3792551 +Node: Pulling from the mobile application792627 +Ref: Pulling from the mobile application-Footnote-1794940 +Node: Drag and Drop & yank-media794993 +Ref: Drag and Drop & yank-media-Footnote-1796622 +Node: Hacking796770 +Node: Hooks797720 +Node: Add-on Packages798004 +Node: Adding Hyperlink Types798473 +Node: Adding Export Backends802285 +Node: Tables in Arbitrary Syntax803530 +Node: Radio tables804798 +Node: A LaTeX example806935 +Ref: A LaTeX example-Footnote-1810787 +Ref: A LaTeX example-Footnote-2810830 +Ref: A LaTeX example-Footnote-3810991 +Node: Translator functions811443 +Node: Dynamic Blocks813625 +Node: Special Agenda Views815871 +Ref: Special Agenda Views-Footnote-1819582 +Ref: Special Agenda Views-Footnote-2819788 +Node: Speeding Up Your Agendas819920 +Node: Extracting Agenda Information821143 +Node: Using the Property API824948 +Node: Using the Mapping API828297 +Node: History and Acknowledgments832330 +Ref: From Carsten832528 +Ref: From Bastien835967 +Ref: List of Contributions838099 +Node: GNU Free Documentation License846761 +Ref: ADDENDUM How to use this License for your documents870719 +Node: Main Index872112 +Node: Key Index972666 +Node: Command and Function Index1029889 +Node: Variable Index1078613  End Tag Table diff --git a/elpa/org-9.6.7/orgguide.info b/elpa/org-9.7.17/orgguide.info similarity index 88% rename from elpa/org-9.6.7/orgguide.info rename to elpa/org-9.7.17/orgguide.info index e87d10db..00da7128 100644 --- a/elpa/org-9.6.7/orgguide.info +++ b/elpa/org-9.7.17/orgguide.info @@ -1,7 +1,7 @@ -This is orgguide.info, produced by makeinfo version 6.7 from +This is orgguide.info, produced by makeinfo version 6.8 from orgguide.texi. -Copyright © 2004–2023 Free Software Foundation, Inc. +Copyright © 2004–2024 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, @@ -26,7 +26,7 @@ File: orgguide.info, Node: Top, Next: Introduction, Up: (dir) Org Mode Compact Guide ********************** -Copyright © 2004–2023 Free Software Foundation, Inc. +Copyright © 2004–2024 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, @@ -179,8 +179,8 @@ Feedback If you find problems with Org, or if you have questions, remarks, or ideas about it, please mail to the Org mailing list -. For information on how to submit bug reports, -see the main manual. +. For information on how to submit bug +reports, see the *note main manual: (org)Top.  File: orgguide.info, Node: Document Structure, Next: Tables, Prev: Introduction, Up: Top @@ -244,10 +244,10 @@ File: orgguide.info, Node: Visibility Cycling, Next: Motion, Prev: Headlines, ====================== Outlines make it possible to hide parts of the text in the buffer. Org -uses just two commands, bound to ‘’ and ‘S-’ to change the -visibility in the buffer. +uses just two commands, bound to ‘’ and ‘S-’ (‘org-cycle’ and +‘org-shifttab’) to change the visibility in the buffer. -‘’ +‘’ (‘org-cycle’) _Subtree cycling_: Rotate current subtree among the states ,-> FOLDED -> CHILDREN -> SUBTREE --. @@ -256,18 +256,18 @@ visibility in the buffer. When called with a prefix argument (‘C-u ’), or with the Shift key, global cycling is invoked. -‘S-’ -‘C-u ’ +‘S-’ (‘org-global-cycle’) +‘C-u ’ (‘org-cycle’) _Global cycling_: Rotate the entire buffer among the states ,-> OVERVIEW -> CONTENTS -> SHOW ALL --. '--------------------------------------' -‘C-u C-u C-u ’ +‘C-u C-u C-u ’ (‘org-show-all’) Show all, including drawers. When Emacs first visits an Org file, the global state is set to -OVERVIEW, i.e., only the top level headlines are visible. This can be +‘showeverything’, i.e., all file content is visible. This can be configured through the variable ‘org-startup-folded’, or on a per-file basis by adding a ‘STARTUP’ keyword to ‘overview’, ‘content’, ‘showall’, ‘showeverything’ or ‘showlevels’ (n = 2..5) like this: @@ -282,19 +282,18 @@ File: orgguide.info, Node: Motion, Next: Structure Editing, Prev: Visibility The following commands jump to other headlines in the buffer. -‘C-c C-n’ +‘C-c C-n’ (‘org-next-visible-heading’) Next heading. - -‘C-c C-p’ +‘C-c C-p’ (‘org-previous-visible-heading’) Previous heading. -‘C-c C-f’ +‘C-c C-f’ (‘org-backward-heading-same-level’) Next heading same level. -‘C-c C-b’ +‘C-c C-b’ (‘outline-backward-same-level’) Previous heading same level. -‘C-c C-u’ +‘C-c C-u’ (‘outline-up-heading’) Backward to higher level heading.  @@ -303,35 +302,35 @@ File: orgguide.info, Node: Structure Editing, Next: Sparse Trees, Prev: Motio 2.4 Structure Editing ===================== -‘M-’ +‘M-’ (‘org-meta-return’) Insert new heading with same level as current. If point is in a plain list item, a new item is created (see *note Plain Lists::). When this command is used in the middle of a line, the line is split and the rest of the line becomes the new headline(1). -‘M-S-’ +‘M-S-’ (‘org-insert-todo-heading’) Insert new TODO entry with same level as current heading. -‘’ in new +‘’ (‘org-cycle’) in new empty entry In a new entry with no text yet, ‘’ cycles through reasonable levels. -‘M-’ -‘M-’ +‘M-’ (‘org-metaleft’) +‘M-’ (‘org-metaright’) Promote or demote current heading by one level. -‘M-’ -‘M-’ +‘M-’ (‘org-move-subtree-up’) +‘M-’ (‘org-move-subtree-down’) Move subtree up or down, i.e., swap with previous or next subtree of same level. -‘C-c C-w’ +‘C-c C-w’ (‘org-refile’) Refile entry or region to a different location. See *note Refile and Copy::. -‘C-x n s’ -‘C-x n w’ +‘C-x n s’ (‘org-narrow-to-subtree’) +‘C-x n w’ (‘widen’) Narrow buffer to current subtree and widen it again. When there is an active region (Transient Mark mode), promotion and @@ -357,11 +356,11 @@ out and you will see immediately how it works. Org mode contains several commands creating such trees, all these commands can be accessed through a dispatcher: -‘C-c /’ +‘C-c /’ (‘org-sparse-tree’) This prompts for an extra key to select a sparse-tree creating command. -‘C-c / r’ +‘C-c / r’ (‘org-occur’) Occur. Prompts for a regexp and shows a sparse tree with all matches. Each match is also highlighted; the highlights disappear by pressing ‘C-c C-c’. @@ -413,37 +412,37 @@ before two blank lines. An example: The following commands act on items when point is in the first line of an item (the line with the bullet or number). -‘’ +‘’ (‘org-cycle’) Items can be folded just like headline levels. -‘M-’ +‘M-’ (‘org-insert-heading’) Insert new item at current level. With a prefix argument, force a new heading (see *note Structure Editing::). -‘M-S-’ +‘M-S-’ (‘org-insert-todo-heading’) Insert a new item with a checkbox (see *note Checkboxes::). -‘M-S-’ -‘M-S-’ +‘M-’ (‘org-move-item-up’) +‘M-’ (‘org-move-item-down’) Move the item including subitems up/down (swap with previous/next item of same indentation). If the list is ordered, renumbering is automatic. -‘M-’ -‘M-’ +‘M-’ (‘org-do-promote’) +‘M-’ (‘org-do-demote’) Decrease/increase the indentation of an item, leaving children alone. -‘M-S-’ -‘M-S-’ +‘M-S-’ (‘org-promote-subtree’) +‘M-S-’ (‘org-demote-subtree’) Decrease/increase the indentation of the item, including subitems. -‘C-c C-c’ +‘C-c C-c’ (‘org-toggle-checkbox’) If there is a checkbox (see *note Checkboxes::) in the item line, toggle the state of the checkbox. Also verify bullets and indentation consistency in the whole list. -‘C-c -’ +‘C-c -’ (‘org-cycle-list-bullet’) Cycle the entire list level through the different itemize/enumerate bullets (‘-’, ‘+’, ‘*’, ‘1.’, ‘1)’). @@ -490,7 +489,7 @@ the field is automatically made blank. Creation and conversion ======================= -‘C-c |’ +‘C-c |’ (‘org-table-create-or-convert-from-region’) Convert the active region to table. If every line contains at least one ‘’ character, the function assumes that the material is tab separated. If every line contains a comma, comma-separated @@ -504,58 +503,58 @@ Creation and conversion Re-aligning and field motion ============================ -‘C-c C-c’ +‘C-c C-c’ (‘org-table-align’) Re-align the table without moving point. -‘’ +‘’ (‘org-table-next-field’) Re-align the table, move to the next field. Creates a new row if necessary. -‘S-’ +‘S-’ (‘org-table-previous-field’) Re-align, move to previous field. -‘’ +‘’ (‘org-table-next-row’) Re-align the table and move down to next row. Creates a new row if necessary. -‘S-’ -‘S-’ -‘S-’ -‘S-’ +‘S-’ (‘org-table-move-cell-up’) +‘S-’ (‘org-table-move-cell-down’) +‘S-’ (‘org-table-move-cell-left’) +‘S-’ (‘org-table-move-cell-right’) Move a cell up, down, left, and right by swapping with adjacent cell. Column and row editing ====================== -‘M-’, ‘M-’ +‘M-’ (‘org-table-move-column-left’), ‘M-’ (‘org-table-move-column-right’) Move the current column left/right. -‘M-S-’ +‘M-S-’ (‘org-table-delete-column’) Kill the current column. -‘M-S-’ +‘M-S-’ (‘org-table-insert-column’) Insert a new column to the left of point position. -‘M-’, ‘M-’ +‘M-’ (‘org-table-move-row-up’), ‘M-’ (‘org-table-move-row-down’) Move the current row up/down. -‘M-S-’ +‘M-S-’ (‘org-table-kill-row’) Kill the current row or horizontal line. -‘M-S-’ +‘M-S-’ (‘org-table-insert-row’) Insert a new row above the current row. With a prefix argument, the line is created below the current one. -‘C-c -’ +‘C-c -’ (‘org-table-insert-hline’) Insert a horizontal line below current row. With a prefix argument, the line is created above the current line. -‘C-c ’ +‘C-c ’ (‘org-table-hline-and-move’) Insert a horizontal line below current row, and move the point into the row below that line. -‘C-c ^’ +‘C-c ^’ (‘org-table-sort-lines’) Sort the table lines in the region. The position of point indicates the column to be used for sorting, and the range of lines is the range between the nearest horizontal separator lines, or the @@ -648,7 +647,7 @@ buffer—see below. From an Org buffer, the following commands create, navigate or, more generally, act on links. -‘C-c C-l’ +‘C-c C-l’ (‘org-insert-link’) Insert a link. This prompts for a link to be inserted into the buffer. You can just type a link, or use history keys ‘’ and ‘’ to access stored links. You will be prompted for the @@ -657,14 +656,14 @@ generally, act on links. When called with a ‘C-u’ prefix argument, file name completion is used to link to a file. -‘C-c C-l’ (with point on existing link) +‘C-c C-l’ (with point on existing link) (‘org-insert-link’) When point is on an existing link, ‘C-c C-l’ allows you to edit the link and description parts of the link. -‘C-c C-o’ +‘C-c C-o’ (‘open-link-at-point’) Open link at point. -‘C-c &’ +‘C-c &’ (‘org-mark-ring-goto’) Jump back to a recorded position. A position is recorded by the commands following internal links, and by ‘C-c %’. Using this command several times in direct succession moves through a ring of @@ -707,7 +706,7 @@ for example: The most important commands to work with TODO entries are: -‘C-c C-t’ +‘C-c C-t’ (‘org-todo’) Rotate the TODO state of the current item among ,-> (unmarked) -> TODO -> DONE --. @@ -716,21 +715,21 @@ for example: The same rotation can also be done “remotely” from the agenda buffer with the ‘t’ command key (see *note Agenda Commands::). -‘S-’ -‘S-’ +‘S-’ (‘org-shiftright’) +‘S-’ (‘org-shiftleft’) Select the following/preceding TODO state, similar to cycling. -‘C-c / t’ +‘C-c / t’ (‘org-show-todo-tree’) View TODO items in a _sparse tree_ (see *note Sparse Trees::). Folds the entire buffer, but shows all TODO items—with not-DONE state—and the headings hierarchy above them. -‘M-x org-agenda t’ +‘M-x org-agenda t’ (‘org-todo-list’) Show the global TODO list. Collects the TODO items (with not-DONE states) from all agenda files (see *note Agenda Views::) into a single buffer. See *note Global TODO List::, for more information. -‘S-M-’ +‘S-M-’ (‘org-insert-todo-heading’) Insert a new TODO entry below the current one. Changing a TODO state can also trigger tag changes. See the @@ -789,7 +788,7 @@ File: orgguide.info, Node: Progress Logging, Next: Priorities, Prev: Multi-st To record a timestamp and a note when changing a TODO state, call the command ‘org-todo’ with a prefix argument. -‘C-u C-c C-t’ +‘C-u C-c C-t’ (‘org-todo’) Prompt for a note and record a the time of the TODO state change. Org mode can also automatically record a timestamp and optionally a @@ -862,7 +861,7 @@ like this highest, ‘B’ the default if none is given. Priorities make a difference only in the agenda. -‘C-c ,’ +‘C-c ,’ (‘org-priority’) Set the priority of the current headline. Press ‘A’, ‘B’ or ‘C’ to select a priority, or ‘’ to remove the cookie. @@ -917,11 +916,11 @@ checked. The following commands work with checkboxes: -‘C-c C-c’ +‘C-c C-c’, ‘C-u C-c C-c’ (‘org-toggle-checkbox’) Toggle checkbox status or—with prefix argument—checkbox presence at point. -‘M-S-’ +‘M-S-’ (‘org-insert-todo-heading’) Insert a new item with a checkbox. This works only if point is already in a plain list item (see *note Plain Lists::). @@ -968,12 +967,12 @@ Tags can simply be typed into the buffer at the end of a headline. After a colon, ‘M-’ offers completion on tags. There is also a special command for inserting tags: -‘C-c C-q’ +‘C-c C-q’ (‘org-set-tags-command’) Enter new tags for the current headline. Org mode either offers completion or a special single-key interface for setting tags, see below. -‘C-c C-c’ +‘C-c C-c’ (‘org-set-tags-command’) When point is in a headline, this does the same as ‘C-c C-q’. Org supports tag insertion based on a _list of tags_. By default @@ -1028,19 +1027,18 @@ support with ‘org-toggle-tags-groups’, bound to ‘C-c C-x q’. Tag searches ============ -‘C-c / m’ or ‘C-c \’ +‘C-c / m’ or ‘C-c \’ (‘org-match-sparse-tree’) Create a sparse tree with all headlines matching a tags search. With a ‘C-u’ prefix argument, ignore headlines that are not a TODO line. -‘M-x org-agenda m’ +‘M-x org-agenda m’ (‘org-tags-view’) Create a global list of tag matches from all agenda files. See *note Matching Tags and Properties::. -‘M-x org-agenda M’ +‘M-x org-agenda M’ (‘org-tags-view’) Create a global list of tag matches from all agenda files, but - check only TODO items and force checking subitems (see the option - ‘org-tags-match-list-sublevels’). + check only TODO items. These commands all prompt for a match string which allows basic Boolean logic like ‘+boss+urgent-project1’, to find entries with tags @@ -1097,10 +1095,10 @@ file, use a line like: The following commands help to work with properties: -‘C-c C-x p’ +‘C-c C-x p’ (‘org-set-property’) Set a property. This prompts for a property name and a value. -‘C-c C-c d’ +‘C-c C-c d’ (‘org-delete-property’) Remove a property from the current entry. To create sparse trees and special lists with selection based on @@ -1116,7 +1114,15 @@ File: orgguide.info, Node: Dates and Times, Next: Capture Refile Archive, Pre To assist project planning, TODO items can be labeled with a date and/or a time. The specially formatted string carrying the date and time -information is called a _timestamp_ in Org mode. +information is called a _timestamp_ in Org mode. This may be a little +confusing because timestamp is often used as indicating when something +was created or last changed. However, in Org mode this term is used in +a much wider sense. + + Timestamps can be used to plan appointments, schedule tasks, set +deadlines, track time, and more. The following sections describe the +timestamp format and tooling that Org mode provides for common use cases +dealing with time and time intervals. * Menu: @@ -1141,11 +1147,15 @@ Built-in Agenda Views::). We distinguish: Plain timestamp; Event; Appointment A simple timestamp just assigns a date/time to an item. This is just like writing down an appointment or event in a paper agenda. + There can be multiple timestamps in an item. * Meet Peter at the movies <2006-11-01 Wed 19:15> * Discussion on climate change <2006-11-02 Thu 20:00-22:00> + * My days off + <2006-11-03 Fri> + <2006-11-06 Mon> Timestamp with repeater interval A timestamp may contain a _repeater interval_, indicating that it @@ -1165,11 +1175,23 @@ Diary-style expression entries * 22:00-23:00 The nerd meeting on every 2nd Thursday of the month <%%(diary-float t 4 2)> +Time range + Time range is a timestamp having two time units connected by ‘-’ + + * Discussion on climate change + <2006-11-02 Thu 10:00-12:00> + Time/Date range - Two timestamps connected by ‘--’ denote a range. + Two timestamps connected by ‘--’ denote a range. In the agenda, + the headline is shown on the first and last day of the range, and + on any dates that are displayed and fall in the range. The first + example specifies just the dates of the range while the second + example specifies a time range for each date. ** Meeting in Amsterdam <2004-08-23 Mon>--<2004-08-26 Thu> + ** This weeks committee meetings + <2004-08-23 Mon 10:00-11:00>--<2004-08-26 Thu 10:00-11:00> Inactive timestamp Just like a plain timestamp, but with square brackets instead of @@ -1189,23 +1211,23 @@ For Org mode to recognize timestamps, they need to be in the specific format. All commands listed below produce timestamps in the correct format. -‘C-c .’ +‘C-c .’ (‘org-timestamp’) Prompt for a date and insert a corresponding timestamp. When point is at an existing timestamp in the buffer, the command is used to modify this timestamp instead of inserting a new one. When this command is used twice in succession, a time range is inserted. With a prefix argument, it also adds the current time. -‘C-c !’ +‘C-c !’ (‘org-timestamp-inactive’) Like ‘C-c .’, but insert an inactive timestamp that does not cause an agenda entry. -‘S-’ -‘S-’ +‘S-’ (‘org-timestamp-down-day’) +‘S-’ (‘org-timestamp-up-day’) Change date at point by one day. -‘S-’ -‘S-’ +‘S-’ (‘org-timestamp-up’) +‘S-’ (‘org-timestamp-down’) On the beginning or enclosing bracket of a timestamp, change its type. Within a timestamp, change the item under point. Point can be on a year, month, day, hour or minute. When the timestamp @@ -1217,8 +1239,8 @@ format. containing some date and/or time information, and intelligently interprets the string, deriving defaults for unspecified information from the current date and time. You can also select a date in the -pop-up calendar. See the manual for more information on how exactly the -date/time prompt works. +pop-up calendar. See the *note manual: (org)Top. for more information +on how exactly the date/time prompt works.  File: orgguide.info, Node: Deadlines and Scheduling, Next: Clocking Work Time, Prev: Creating Timestamps, Up: Dates and Times @@ -1228,7 +1250,7 @@ File: orgguide.info, Node: Deadlines and Scheduling, Next: Clocking Work Time, A timestamp may be preceded by special keywords to facilitate planning: -‘C-c C-d’ +‘C-c C-d’ (‘org-deadline’) Insert ‘DEADLINE’ keyword along with a time stamp, in the line following the headline. @@ -1245,7 +1267,7 @@ A timestamp may be preceded by special keywords to facilitate planning: DEADLINE: <2004-02-29 Sun> The editor in charge is [[bbdb:Ford Prefect]] -‘C-c C-s’ +‘C-c C-s’ (‘org-schedule’) Insert ‘SCHEDULED’ keyword along with a stamp, in the line following the headline. @@ -1290,26 +1312,26 @@ File: orgguide.info, Node: Clocking Work Time, Prev: Deadlines and Scheduling, Org mode allows you to clock the time you spend on specific tasks in a project. -‘C-c C-x C-i’ +‘C-c C-x C-i’ (‘org-clock-in’) Start the clock on the current item (clock-in). This inserts the ‘CLOCK’ keyword together with a timestamp. When called with a ‘C-u’ prefix argument, select the task from a list of recently clocked tasks. -‘C-c C-x C-o’ +‘C-c C-x C-o’ (‘org-clock-out’) Stop the clock (clock-out). This inserts another timestamp at the same location where the clock was last started. It also directly computes the resulting time in inserts it after the time range as ‘=>HH:MM’. -‘C-c C-x C-e’ +‘C-c C-x C-e’ (‘org-clock-modify-effort-estimate’) Update the effort estimate for the current clock task. -‘C-c C-x C-q’ +‘C-c C-x C-q’ (‘org-clock-cancel’) Cancel the current clock. This is useful if a clock was started by mistake, or if you ended up working on something else. -‘C-c C-x C-j’ +‘C-c C-x C-j’ (‘org-clock-goto’) Jump to the headline of the currently clocked in task. With a ‘C-u’ prefix argument, select the target task from a list of recently clocked tasks. @@ -1360,21 +1382,21 @@ The following customization sets a default target(1) file for notes. Using capture ------------- -‘M-x org-capture’ +‘M-x org-capture’ (‘org-capture’) Start a capture process, placing you into a narrowed indirect buffer to edit. -‘C-c C-c’ +‘C-c C-c’ (‘org-capture-finalize’) Once you have finished entering information into the capture buffer, ‘C-c C-c’ returns you to the window configuration before the capture process, so that you can resume your work without further distraction. -‘C-c C-w’ +‘C-c C-w’ (‘org-capture-refile’) Finalize the capture process by refiling the note to a different place (see *note Refile and Copy::). -‘C-c C-k’ +‘C-c C-k’ (‘org-capture-kill’) Abort the capture process and return to the previous state. Capture templates @@ -1401,7 +1423,7 @@ template for you like this: During expansion of the template, special %-escapes(2) allow dynamic insertion of content. Here is a small selection of the possibilities, -consult the manual for more. +consult the *note manual: (org)Top. for more. ‘%a’ annotation, normally the link created with ‘org-store-link’ ‘%i’ initial content, the region when capture is called with ‘C-u’ @@ -1429,7 +1451,7 @@ Cutting, finding the right location, and then pasting the note is cumbersome. To simplify this process, you can use the following special command: -‘C-c C-w’ +‘C-c C-w’ (‘org-agenda-refile’) Refile the entry or region at point. This command offers possible locations for refiling the entry and lets you select one with completion. The item (or all items in the region) is filed below @@ -1440,13 +1462,13 @@ command: across a number of files. See the variable ‘org-refile-targets’ for details. -‘C-u C-c C-w’ +‘C-u C-c C-w’ (‘org-agenda-refile’) Use the refile interface to jump to a heading. -‘C-u C-u C-c C-w’ +‘C-u C-u C-c C-w’ (‘org-refile-goto-last-stored’) Jump to the location where ‘org-refile’ last moved a tree to. -‘C-c M-w’ +‘C-c M-w’ (‘org-refile-copy’) Copying works like refiling, except that the original note is not deleted. @@ -1464,11 +1486,11 @@ global searches like the construction of agenda views fast. The most common archiving action is to move a project tree to another file, the archive file. -‘C-c C-x C-a’ +‘C-c C-x C-a’ (‘org-archive-subtree-default’) Archive the current entry using the command specified in the variable ‘org-archive-default-command’. -‘C-c C-x C-s’ or short ‘C-c $’ +‘C-c C-x C-s’ or short ‘C-c $’ (‘org-archive-subtree’) Archive the subtree starting at point position to the location given by ‘org-archive-location’. @@ -1524,17 +1546,17 @@ File: orgguide.info, Node: Agenda Files, Next: Agenda Dispatcher, Up: Agenda The information to be shown is normally collected from all _agenda files_, the files listed in the variable ‘org-agenda-files’. -‘C-c [’ +‘C-c [’ (‘org-agenda-file-to-front’) Add current file to the list of agenda files. The file is added to the front of the list. If it was already in the list, it is moved to the front. With a prefix argument, file is added/moved to the end. -‘C-c ]’ +‘C-c ]’ (‘org-remove-file’) Remove current file from the list of agenda files. ‘C-'’ -‘C-,’ +‘C-,’ (‘org-cycle-agenda-files’) Cycle through agenda file list, visiting one file after the other.  @@ -1576,7 +1598,7 @@ File: orgguide.info, Node: Built-in Agenda Views, Next: Global TODO List, Pre The purpose of the weekly/daily _agenda_ is to act like a page of a paper agenda, showing all the tasks for the current week or day. -‘M-x org-agenda a’ +‘M-x org-agenda a’ (‘org-agenda-list’) Compile an agenda for the current week from a list of Org files. The agenda shows the entries for each day. @@ -1611,11 +1633,11 @@ collected into a single place. Remote editing of TODO items lets you can change the state of a TODO entry with a single key press. For commands available in the TODO list, see *note Agenda Commands::. -‘M-x org-agenda t’ +‘M-x org-agenda t’ (‘org-todo-list’) Show the global TODO list. This collects the TODO items from all agenda files (see *note Agenda Views::) into a single buffer. -‘M-x org-agenda T’ +‘M-x org-agenda T’ (‘org-todo-list’) Like the above, but allows selection of a specific TODO keyword.  @@ -1630,7 +1652,7 @@ headlines based on this metadata and collect them into an agenda buffer. The match syntax described here also applies when creating sparse trees with ‘C-c / m’. -‘M-x org-agenda m’ +‘M-x org-agenda m’ (‘org-tags-view’) Produce a list of all headlines that match a given set of tags. The command prompts for a selection criterion, which is a boolean logic expression with tags, like ‘+work+urgent-withboss’ or @@ -1638,7 +1660,7 @@ with ‘C-c / m’. search, define a custom command for it (see *note Agenda Dispatcher::). -‘M-x org-agenda M’ +‘M-x org-agenda M’ (‘org-tags-view’) Like ‘m’, but only select headlines that are also TODO items. A search string can use Boolean operators ‘&’ for AND and ‘|’ for OR. @@ -1663,7 +1685,7 @@ tags. ‘night’. You may also test for properties at the same time as matching tags, -see the manual for more information. +see the *note manual: (org)Top. for more information.  File: orgguide.info, Node: Search View, Next: Agenda Commands, Prev: Matching Tags and Properties, Up: Agenda Views @@ -1702,57 +1724,57 @@ file where they originate. You are not allowed to edit the agenda buffer itself, but commands are provided to show and jump to the original entry location, and to edit the Org files “remotely” from the agenda buffer. This is just a selection of the many commands, explore -the agenda menu and the manual for a complete list. +the agenda menu and the *note manual: (org)Top. for a complete list. Motion ------ -‘n’ +‘n’ (‘org-agenda-next-line’) Next line (same as ‘’ and ‘C-n’). -‘p’ +‘p’ (‘org-agenda-previous-line’) Previous line (same as ‘’ and ‘C-p’). View/Go to Org file ------------------- -‘’ +‘’ (‘org-agenda-show-and-scroll-up’) Display the original location of the item in another window. With a prefix argument, make sure that drawers stay folded. -‘’ +‘’ (‘org-agenda-goto’) Go to the original location of the item in another window. -‘’ +‘’ (‘org-agenda-switch-to’) Go to the original location of the item and delete other windows. Change display -------------- -‘o’ +‘o’ (‘delete-other-windows’) Delete other windows. -‘v d’ or short ‘d’ +‘v d’ or short ‘d’ (‘org-agenda-day-view’) Switch to day view. -‘v w’ or short ‘w’ +‘v w’ or short ‘w’ (‘org-agenda-week-view’) Switch to week view. -‘f’ +‘f’ (‘org-agenda-later’) Go forward in time to display the span following the current one. For example, if the display covers a week, switch to the following week. -‘b’ +‘b’ (‘org-agenda-earlier’) Go backward in time to display earlier dates. -‘.’ +‘.’ (‘org-agenda-goto-today’) Go to today. -‘j’ +‘j’ (‘org-agenda-goto-date’) Prompt for a date and go there. -‘v l’ or ‘v L’ or short ‘l’ +‘v l’ or ‘v L’ or short ‘l’ (‘org-agenda-log-mode’) Toggle Logbook mode. In Logbook mode, entries that were marked as done while logging was on (see the variable ‘org-log-done’) are shown in the agenda, as are entries that have been clocked on that @@ -1760,11 +1782,11 @@ Change display logbook entries, including state changes. ‘r’ -‘g’ +‘g’ (‘org-agenda-redo’) Recreate the agenda buffer, for example to reflect the changes after modification of the timestamps of items. -‘s’ +‘s’ (‘org-save-all-org-buffers’) Save all Org buffers in the current Emacs session, and also the locations of IDs. @@ -1774,59 +1796,59 @@ Remote editing ‘0--9’ Digit argument. -‘t’ +‘t’ (‘org-agenda-todo’) Change the TODO state of the item, both in the agenda and in the original Org file. -‘C-k’ +‘C-k’ (‘org-agenda-kill’) Delete the current agenda item along with the entire subtree belonging to it in the original Org file. -‘C-c C-w’ +‘C-c C-w’ (‘org-agenda-refile’) Refile the entry at point. -‘a’ +‘a’ (‘org-agenda-archive-default-with-confirmation’) Archive the subtree corresponding to the entry at point using the default archiving command set in ‘org-archive-default-command’. -‘$’ +‘$’ (‘org-agenda-archive’) Archive the subtree corresponding to the current headline. -‘C-c C-s’ +‘C-c C-s’ (‘org-agenda-schedule’) Schedule this item. With a prefix argument, remove the scheduling timestamp -‘C-c C-d’ +‘C-c C-d’ (‘org-agenda-deadline’) Set a deadline for this item. With a prefix argument, remove the deadline. -‘S-’ +‘S-’ (‘org-agenda-do-date-later’) Change the timestamp associated with the current line by one day into the future. -‘S-’ +‘S-’ (‘org-agenda-do-date-earlier’) Change the timestamp associated with the current line by one day into the past. -‘I’ +‘I’ (‘org-agenda-clock-in’) Start the clock on the current item. -‘O’ +‘O’ (‘org-agenda-clock-out’) Stop the previously started clock. -‘X’ +‘X’ (‘org-agenda-clock-cancel’) Cancel the currently running clock. -‘J’ +‘J’ (‘org-agenda-clock-goto’) Jump to the running clock in another window. Quit and exit ------------- -‘q’ +‘q’ (‘org-agenda-quit’) Quit agenda, remove the agenda buffer. -‘x’ +‘x’ (‘org-agenda-exit’) Exit agenda, remove the agenda buffer and all buffers loaded by Emacs for the compilation of the agenda. @@ -2031,14 +2053,14 @@ For example: The following commands handle footnotes: -‘C-c C-x f’ +‘C-c C-x f’ (‘org-footnote-action’) The footnote action command. When point is on a footnote reference, jump to the definition. When it is at a definition, jump to the (first) reference. Otherwise, create a new footnote. When this command is called with a prefix argument, a menu of additional options including renumbering is offered. -‘C-c C-c’ +‘C-c C-c’ (‘org-ctrl-c-ctrl-c’) Jump between definition and reference.  @@ -2073,7 +2095,7 @@ The export dispatcher is the main interface for Org’s exports. A hierarchical menu presents the currently configured export formats. Options are shown as easy toggle switches on the same screen. -‘C-c C-e’ +‘C-c C-e’ (‘org-export-dispatch’) Invokes the export dispatcher interface. Org exports the entire buffer by default. If the Org buffer has an @@ -2156,7 +2178,7 @@ are not exported. any other keyword or priority cookie, comments out the entire subtree. The command below helps changing the comment status of a headline. -‘C-c ;’ +‘C-c ;’ (‘org-toggle-comment’) Toggle the ‘COMMENT’ keyword at the beginning of an entry.  @@ -2171,7 +2193,7 @@ not contain any Org markup. UTF-8 export uses additional characters and symbols available in this encoding standards. ‘C-c C-e t a’ -‘C-c C-e t u’ +‘C-c C-e t u’ (‘org-ascii-export-to-ascii’) Export as an ASCII file with a ‘.txt’ extension. For ‘myfile.org’, Org exports to ‘myfile.txt’, overwriting without warning. For ‘myfile.txt’, Org exports to ‘myfile.txt.txt’ in order to prevent @@ -2186,13 +2208,13 @@ File: orgguide.info, Node: HTML Export, Next: LaTeX Export, Prev: ASCII/UTF-8 Org mode contains an HTML exporter with extensive HTML formatting compatible with XHTML 1.0 strict standard. -‘C-c C-e h h’ +‘C-c C-e h h’ (‘org-html-export-to-html’) Export as HTML file with a ‘.html’ extension. For ‘myfile.org’, Org exports to ‘myfile.html’, overwriting without warning. ‘C-c C-e h o’ exports to HTML and opens it in a web browser. - The HTML export back-end transforms ‘<’ and ‘>’ to ‘<’ and ‘>’. -To include raw HTML code in the Org file so the HTML export back-end can + The HTML export backend transforms ‘<’ and ‘>’ to ‘<’ and ‘>’. +To include raw HTML code in the Org file so the HTML export backend can insert that HTML code in the output, use this inline syntax: ‘@@html:...@@’. For example: @@ -2212,7 +2234,7 @@ File: orgguide.info, Node: LaTeX Export, Next: iCalendar Export, Prev: HTML E 12.8 LaTeX Export ================= -The LaTeX export back-end can handle complex documents, incorporate +The LaTeX export backend can handle complex documents, incorporate standard or custom LaTeX document classes, generate documents using alternate LaTeX engines, and produce fully linked PDF files with indexes, bibliographies, and tables of contents, destined for @@ -2222,18 +2244,18 @@ interactive online viewing or high-quality print publication. change this by adding an option like ‘#+LATEX_CLASS: myclass’ in your file. The class must be listed in ‘org-latex-classes’. -‘C-c C-e l l’ +‘C-c C-e l l’ (‘org-latex-export-to-latex’) Export to a LaTeX file with a ‘.tex’ extension. For ‘myfile.org’, Org exports to ‘myfile.tex’, overwriting without warning. -‘C-c C-e l p’ +‘C-c C-e l p’ (‘org-latex-export-to-pdf’) Export as LaTeX file and convert it to PDF file. -‘C-c C-e l o’ +‘C-c C-e l o’ (‘’) Export as LaTeX file and convert it to PDF, then open the PDF using the default viewer. - The LaTeX export back-end can insert any arbitrary LaTeX code, see + The LaTeX export backend can insert any arbitrary LaTeX code, see *note Embedded LaTeX::. There are three ways to embed such code in the Org file and they all use different quoting syntax. @@ -2245,7 +2267,7 @@ Org file and they all use different quoting syntax. #+LATEX: any arbitrary LaTeX code - Inserting as an export block in the Org file, where the back-end + Inserting as an export block in the Org file, where the backend exports any code between begin and end markers: #+BEGIN_EXPORT latex @@ -2260,14 +2282,14 @@ File: orgguide.info, Node: iCalendar Export, Prev: LaTeX Export, Up: Exportin A large part of Org mode’s interoperability success is its ability to easily export to or import from external applications. The iCalendar -export back-end takes calendar data from Org files and exports to the +export backend takes calendar data from Org files and exports to the standard iCalendar format. -‘C-c C-e c f’ +‘C-c C-e c f’ (‘org-icalendar-export-to-ics’) Create iCalendar entries from the current Org buffer and store them in the same directory, using a file extension ‘.ics’. -‘C-c C-e c c’ +‘C-c C-e c c’ (‘org-icalendar-combine-agenda-files’) Create a combined iCalendar file from Org files in ‘org-agenda-files’ and write it to ‘org-icalendar-combined-agenda-file’ file name. @@ -2288,8 +2310,8 @@ files, to a web server. and PDF conversion so that files are available in both formats on the server. - For detailed instructions about setup, see the manual. Here is an -example: + For detailed instructions about setup, see the *note manual: +(org)Top. Here is an example: (setq org-publish-project-alist '(("org" @@ -2302,17 +2324,17 @@ example: href=\"../other/mystyle.css\" type=\"text/css\"/>"))) -‘C-c C-e P x’ +‘C-c C-e P x’ (‘org-publish’) Prompt for a specific project and publish all files that belong to it. -‘C-c C-e P p’ +‘C-c C-e P p’ (‘org-publish-current-project’) Publish the project containing the current file. -‘C-c C-e P f’ +‘C-c C-e P f’ (‘org-publish-current-file’) Publish only the current file. -‘C-c C-e P a’ +‘C-c C-e P a’ (‘org-publish-all’) Publish every project. Org uses timestamps to track when a file has changed. The above @@ -2398,7 +2420,8 @@ Use ‘C-c C-c’ to evaluate the current code block and insert its results in the Org document. By default, evaluation is only turned on for ‘emacs-lisp’ code blocks, however support exists for evaluating blocks in many languages. For a complete list of supported languages see the -manual. The following shows a code block and its results. +*note manual: (org)Top. The following shows a code block and its +results. #+BEGIN_SRC emacs-lisp (+ 1 2 3 4) @@ -2468,7 +2491,7 @@ source blocks in the current buffer. This is referred to as During tangling of code blocks their bodies are expanded using ‘org-babel-expand-src-block’, which can expand both variable and “Noweb” style references. In order to tangle a code block it must have a -‘tangle’ header argument, see the manual for details. +‘tangle’ header argument, see the *note manual: (org)Top. for details.  File: orgguide.info, Node: Miscellaneous, Prev: Working with Source Code, Up: Top @@ -2493,7 +2516,7 @@ Structure Templates To quickly insert empty structural blocks, such as ‘#+BEGIN_SRC’ ... ‘#+END_SRC’, or to wrap existing text in such a block, use -‘C-c C-,’ +‘C-c C-,’ (‘org-insert-structure-template’) Prompt for a type of block structure, and insert the block at point. If the region is active, it is wrapped in the block. @@ -2539,100 +2562,100 @@ Node: Introduction5668 Ref: Installation6354 Ref: Activation7066 Ref: Feedback7509 -Node: Document Structure7743 -Node: Headlines8814 -Ref: Headlines-Footnote-19696 -Node: Visibility Cycling9819 -Node: Motion11091 -Node: Structure Editing11513 -Ref: Structure Editing-Footnote-112707 -Node: Sparse Trees12811 -Ref: Sparse Trees-Footnote-113879 -Node: Plain Lists13994 -Node: Tables16500 -Ref: Creation and conversion18193 -Ref: Re-aligning and field motion18745 -Ref: Column and row editing19261 -Node: Hyperlinks20266 -Ref: Internal links21024 -Ref: External Links21477 -Ref: Handling Links23307 -Node: TODO Items24696 -Node: TODO Basics25673 -Node: Multi-state Workflow27068 -Node: Progress Logging28859 -Ref: Closing items29606 -Ref: Tracking TODO state changes30161 -Ref: Progress Logging-Footnote-131160 -Ref: Progress Logging-Footnote-231233 -Node: Priorities31311 -Node: Breaking Down Tasks32207 -Node: Checkboxes33010 -Node: Tags34070 -Ref: Tag inheritance34695 -Ref: Setting tags35433 -Ref: Tag groups37153 -Ref: Tag searches37949 -Ref: Tags-Footnote-139041 -Node: Properties39145 -Node: Dates and Times40904 -Node: Timestamps41506 -Node: Creating Timestamps43569 -Node: Deadlines and Scheduling45230 -Ref: Deadlines and Scheduling-Footnote-147254 -Ref: Deadlines and Scheduling-Footnote-247415 -Node: Clocking Work Time47578 -Node: Capture Refile Archive48881 -Node: Capture49689 -Ref: Setting up capture49991 -Ref: Using capture50262 -Ref: Capture templates50857 -Ref: Capture-Footnote-152273 -Ref: Capture-Footnote-252384 -Node: Refile and Copy52475 -Node: Archiving53673 -Node: Agenda Views54985 -Node: Agenda Files56440 -Node: Agenda Dispatcher57100 -Node: Built-in Agenda Views58020 -Node: Global TODO List59109 -Node: Matching Tags and Properties59826 -Node: Search View61795 -Node: Agenda Commands62905 -Ref: Motion (1)63491 -Ref: View/Go to Org file63632 -Ref: Change display63979 -Ref: Remote editing65067 -Ref: Quit and exit66258 -Node: Custom Agenda Views66464 -Node: Markup67940 -Node: Paragraphs68766 -Node: Emphasis and Monospace69888 -Node: Embedded LaTeX70306 -Node: Literal examples71175 -Node: Images72265 -Node: Creating Footnotes72866 -Node: Exporting73786 -Node: The Export Dispatcher74662 -Node: Export Settings75192 -Node: Table of Contents76017 -Node: Include Files76750 -Node: Comment Lines77436 -Node: ASCII/UTF-8 Export78134 -Node: HTML Export78833 -Node: LaTeX Export79841 -Node: iCalendar Export81480 -Node: Publishing82181 -Node: Working with Source Code83783 -Ref: Using header arguments85050 -Ref: Evaluating code blocks86228 -Ref: Results of evaluation87103 -Ref: Exporting code blocks88325 -Ref: Extracting source code88789 -Node: Miscellaneous89316 -Ref: Completion89439 -Ref: Structure Templates89776 -Ref: Clean view90102 +Node: Document Structure7766 +Node: Headlines8837 +Ref: Headlines-Footnote-19719 +Node: Visibility Cycling9842 +Node: Motion11236 +Node: Structure Editing11830 +Ref: Structure Editing-Footnote-113262 +Node: Sparse Trees13366 +Ref: Sparse Trees-Footnote-114476 +Node: Plain Lists14591 +Node: Tables17380 +Ref: Creation and conversion19073 +Ref: Re-aligning and field motion19673 +Ref: Column and row editing20433 +Node: Hyperlinks21784 +Ref: Internal links22542 +Ref: External Links22995 +Ref: Handling Links24825 +Node: TODO Items26316 +Node: TODO Basics27293 +Node: Multi-state Workflow28831 +Node: Progress Logging30622 +Ref: Closing items31386 +Ref: Tracking TODO state changes31941 +Ref: Progress Logging-Footnote-132940 +Ref: Progress Logging-Footnote-233013 +Node: Priorities33091 +Node: Breaking Down Tasks34008 +Node: Checkboxes34811 +Node: Tags35950 +Ref: Tag inheritance36575 +Ref: Setting tags37313 +Ref: Tag groups39091 +Ref: Tag searches39887 +Ref: Tags-Footnote-140967 +Node: Properties41071 +Node: Dates and Times42883 +Node: Timestamps43920 +Node: Creating Timestamps46676 +Node: Deadlines and Scheduling48519 +Ref: Deadlines and Scheduling-Footnote-150585 +Ref: Deadlines and Scheduling-Footnote-250746 +Node: Clocking Work Time50909 +Node: Capture Refile Archive52344 +Node: Capture53152 +Ref: Setting up capture53454 +Ref: Using capture53725 +Ref: Capture templates54421 +Ref: Capture-Footnote-155854 +Ref: Capture-Footnote-255965 +Node: Refile and Copy56056 +Node: Archiving57366 +Node: Agenda Views58742 +Node: Agenda Files60197 +Node: Agenda Dispatcher60945 +Node: Built-in Agenda Views61865 +Node: Global TODO List62978 +Node: Matching Tags and Properties63739 +Node: Search View65769 +Node: Agenda Commands66879 +Ref: Motion (1)67482 +Ref: View/Go to Org file67685 +Ref: Change display68123 +Ref: Remote editing69493 +Ref: Quit and exit71081 +Node: Custom Agenda Views71335 +Node: Markup72811 +Node: Paragraphs73637 +Node: Emphasis and Monospace74759 +Node: Embedded LaTeX75177 +Node: Literal examples76046 +Node: Images77136 +Node: Creating Footnotes77737 +Node: Exporting78711 +Node: The Export Dispatcher79587 +Node: Export Settings80145 +Node: Table of Contents80970 +Node: Include Files81703 +Node: Comment Lines82389 +Node: ASCII/UTF-8 Export83114 +Node: HTML Export83847 +Node: LaTeX Export84885 +Node: iCalendar Export86628 +Node: Publishing87407 +Node: Working with Source Code89138 +Ref: Using header arguments90405 +Ref: Evaluating code blocks91583 +Ref: Results of evaluation92474 +Ref: Exporting code blocks93696 +Ref: Extracting source code94160 +Node: Miscellaneous94704 +Ref: Completion94827 +Ref: Structure Templates95164 +Ref: Clean view95528  End Tag Table diff --git a/elpa/org-9.6.7/ox-ascii.el b/elpa/org-9.7.17/ox-ascii.el similarity index 95% rename from elpa/org-9.6.7/ox-ascii.el rename to elpa/org-9.7.17/ox-ascii.el index 692dd216..2a3d4c6f 100644 --- a/elpa/org-9.6.7/ox-ascii.el +++ b/elpa/org-9.7.17/ox-ascii.el @@ -1,10 +1,9 @@ -;;; ox-ascii.el --- ASCII Back-End for Org Export Engine -*- lexical-binding: t; -*- +;;; ox-ascii.el --- ASCII Backend for Org Export Engine -*- lexical-binding: t; -*- -;; Copyright (C) 2012-2023 Free Software Foundation, Inc. +;; Copyright (C) 2012-2024 Free Software Foundation, Inc. ;; Author: Nicolas Goaziou -;; Maintainer: Nicolas Goaziou -;; Keywords: outlines, hypermedia, calendar, wp +;; Keywords: outlines, hypermedia, calendar, text ;; This file is part of GNU Emacs. @@ -23,7 +22,7 @@ ;;; Commentary: ;; -;; This library implements an ASCII back-end for Org generic exporter. +;; This library implements an ASCII backend for Org generic exporter. ;; See Org manual for more information. ;;; Code: @@ -42,7 +41,7 @@ (declare-function org-back-to-heading "org" (&optional invisible-ok)) (declare-function org-next-visible-heading "org" (arg)) -;;; Define Back-End +;;; Define Backend ;; ;; The following setting won't allow modifying preferred charset ;; through a buffer keyword or an option item, but, since the property @@ -507,7 +506,7 @@ that is according to the widest non blank line in CONTENTS." (let ((text-width (org-ascii--current-text-width element info)) (how (org-ascii--current-justification element))) (cond - ((eq (org-element-type element) 'paragraph) + ((org-element-type-p element 'paragraph) ;; Paragraphs are treated specially as they need to be filled. (org-ascii--fill-string contents text-width info how)) ((eq how 'left) contents) @@ -575,13 +574,13 @@ INFO is a plist used as a communication channel." ;; inline task among ELEMENT parents. (total-width (if (cl-some (lambda (parent) - (eq (org-element-type parent) 'inlinetask)) + (org-element-type-p parent 'inlinetask)) genealogy) (plist-get info :ascii-inlinetask-width) ;; No inlinetask: Remove global margin from text width. (- (plist-get info :ascii-text-width) (plist-get info :ascii-global-margin) - (let ((parent (org-export-get-parent-headline element))) + (let ((parent (org-element-lineage element 'headline))) ;; Inner margin doesn't apply to text before first ;; headline. (if (not parent) 0 @@ -596,8 +595,8 @@ INFO is a plist used as a communication channel." ;; Each `quote-block' and `verse-block' above narrows text ;; width by twice the standard margin size. (+ (* (cl-count-if (lambda (parent) - (memq (org-element-type parent) - '(quote-block verse-block))) + (org-element-type-p + parent '(quote-block verse-block))) genealogy) 2 (plist-get info :ascii-quote-margin)) @@ -605,9 +604,9 @@ INFO is a plist used as a communication channel." ;; containing current line (* (cl-count-if (lambda (e) - (and (eq (org-element-type e) 'plain-list) - (not (eq (org-element-type (org-export-get-parent e)) - 'item)))) + (and (org-element-type-p e 'plain-list) + (not (org-element-type-p + (org-element-parent e) 'item)))) genealogy) (plist-get info :ascii-list-margin)) ;; Compute indentation offset due to current list. It is @@ -616,8 +615,8 @@ INFO is a plist used as a communication channel." (let ((indentation 0)) (dolist (e genealogy) (cond - ((not (eq 'item (org-element-type e)))) - ((eq (org-element-property :type (org-export-get-parent e)) + ((not (org-element-type-p e 'item))) + ((eq (org-element-property :type (org-element-parent e)) 'descriptive) (cl-incf indentation org-ascii-quote-margin)) (t @@ -632,16 +631,19 @@ INFO is a plist used as a communication channel." "Return expected justification for ELEMENT's contents. Return value is a symbol among `left', `center', `right' and `full'." - (let (justification) - (while (and (not justification) - (setq element (org-element-property :parent element))) - (pcase (org-element-type element) - (`center-block (setq justification 'center)) - (`special-block - (let ((name (org-element-property :type element))) - (cond ((string= name "JUSTIFYRIGHT") (setq justification 'right)) - ((string= name "JUSTIFYLEFT") (setq justification 'left))))))) - (or justification 'left))) + (or (org-element-lineage-map + element + (lambda (el) + (pcase (org-element-type el) + (`center-block 'center) + (`special-block + (let ((name (org-element-property :type el))) + (cond ((string= name "JUSTIFYRIGHT") 'right) + ((string= name "JUSTIFYLEFT") 'left)))))) + '(center-block special-block) + nil 'first-match) + ;; default + 'left)) (defun org-ascii--build-title (element info text-width &optional underline notags toc) @@ -660,7 +662,7 @@ the title. When optional argument TOC is non-nil, use optional title if possible. It doesn't apply to `inlinetask' elements." - (let* ((headlinep (eq (org-element-type element) 'headline)) + (let* ((headlinep (org-element-type-p element 'headline)) (numbers ;; Numbering is specific to headlines. (and headlinep @@ -886,7 +888,7 @@ is a plist used as a communication channel." (gethash link (plist-get info :exported-data))) (not (member footprint seen))) (push footprint seen) link))))) - (org-element-map (if (eq (org-element-type element) 'section) + (org-element-map (if (org-element-type-p element 'section) element ;; In a headline, only retrieve links in title ;; and relative section, not in children. @@ -952,14 +954,15 @@ channel." ;; Only links with a description need an entry. Other are ;; already handled in `org-ascii-link'. (when description - (let ((dest (if (equal type "fuzzy") - (org-export-resolve-fuzzy-link link info) - ;; Ignore broken links. On broken link, - ;; `org-export-resolve-id-link' will throw an - ;; error and we will return nil. - (condition-case nil - (org-export-resolve-id-link link info) - (org-link-broken nil))))) + (let ((dest + ;; Ignore broken links. On broken link, + ;; `org-export-resolve-id-link' will throw an + ;; error and we will return nil. + (condition-case nil + (if (equal type "fuzzy") + (org-export-resolve-fuzzy-link link info) + (org-export-resolve-id-link link info)) + (org-link-broken nil)))) (when dest (concat (org-ascii--fill-string @@ -1118,7 +1121,7 @@ holding export options." ;; paragraph (FIRST), if any, to be sure ;; filling will take it into consideration. (let ((first (car (org-element-contents def)))) - (if (not (eq (org-element-type first) 'paragraph)) + (if (not (org-element-type-p first 'paragraph)) (concat id "\n" (org-export-data def info)) (push id (nthcdr 2 first)) (org-export-data def info))) @@ -1338,7 +1341,7 @@ holding contextual information." (if (not (org-string-nw-p links)) contents (let* ((contents (org-element-contents headline)) (section (let ((first (car contents))) - (and (eq (org-element-type first) 'section) + (and (org-element-type-p first 'section) first)))) (concat (and section (concat (org-element-normalize-string @@ -1395,7 +1398,7 @@ contextual information." (_todo _type _priority _name _tags contents width inlinetask info) "Format an inline task element for ASCII export. See `org-ascii-format-inlinetask-function' for a description -of the parameters." +of the parameters CONTENTS, WIDTH, INLINETASK, and INFO." (let* ((utf8p (eq (plist-get info :ascii-charset) 'utf-8)) (width (or width (plist-get info :ascii-inlinetask-width)))) (org-ascii--indent-string @@ -1416,7 +1419,7 @@ of the parameters." (make-string width (if utf8p ?━ ?_))) ;; Flush the inlinetask to the right. (- (plist-get info :ascii-text-width) (plist-get info :ascii-global-margin) - (if (not (org-export-get-parent-headline inlinetask)) 0 + (if (not (org-element-lineage inlinetask 'headline)) 0 (plist-get info :ascii-inner-margin)) (org-ascii--current-text-width inlinetask info))))) @@ -1462,7 +1465,7 @@ CONTENTS holds the contents of the item. INFO is a plist holding contextual information." (let* ((utf8p (eq (plist-get info :ascii-charset) 'utf-8)) (checkbox (org-ascii--checkbox item info)) - (list-type (org-element-property :type (org-export-get-parent item))) + (list-type (org-element-property :type (org-element-parent item))) (bullet ;; First parent of ITEM is always the plain-list. Get ;; `:type' property from it. @@ -1479,11 +1482,11 @@ contextual information." (org-element-property :bullet item))) (num (number-to-string (car (last (org-list-get-item-number - (org-element-property :begin item) + (org-element-begin item) struct (org-list-prevs-alist struct) (org-list-parents-alist struct))))))) - (replace-regexp-in-string "[0-9]+" num bul))) + (replace-regexp-in-string "[0-9A-Za-z]+" num bul))) (_ (let ((bul (org-list-bullet-string (org-element-property :bullet item)))) ;; Change bullets into more visible form if UTF-8 is active. @@ -1604,9 +1607,9 @@ INFO is a plist holding contextual information." ((guard desc) (if (plist-get info :ascii-links-to-notes) (format "[%s]" desc) - (concat desc - (format " (%s)" - (org-ascii--describe-datum destination info))))) + (format "[%s] (%s)" + desc + (org-ascii--describe-datum destination info)))) ;; External file. (`plain-text destination) (`headline @@ -1649,14 +1652,20 @@ information." "Transcode a PARAGRAPH element from Org to ASCII. CONTENTS is the contents of the paragraph, as a string. INFO is the plist used as a communication channel." + ;; Ensure that we do not create multiple paragraphs, when a single + ;; paragraph is expected. + ;; Multiple newlines may appear in CONTENTS, for example, when + ;; certain objects are stripped from export, leaving single newlines + ;; before and after. + (setq contents (org-remove-blank-lines contents)) (org-ascii--justify-element (let ((indented-line-width (plist-get info :ascii-indented-line-width))) (if (not (wholenump indented-line-width)) contents (concat ;; Do not indent first paragraph in a section. (unless (and (not (org-export-get-previous-element paragraph info)) - (eq (org-element-type (org-export-get-parent paragraph)) - 'section)) + (org-element-type-p + (org-element-parent paragraph) 'section)) (make-string indented-line-width ?\s)) (replace-regexp-in-string "\\`[ \t]+" "" contents)))) paragraph info)) @@ -1670,7 +1679,7 @@ CONTENTS is the contents of the list. INFO is a plist holding contextual information." (let ((margin (plist-get info :ascii-list-margin))) (if (or (< margin 1) - (eq (org-element-type (org-export-get-parent plain-list)) 'item)) + (org-element-type-p (org-element-parent plain-list) 'item)) contents (org-ascii--indent-string contents margin)))) @@ -1757,7 +1766,7 @@ contextual information." (let ((links (and (plist-get info :ascii-links-to-notes) ;; Take care of links in first section of the document. - (not (org-element-lineage section '(headline))) + (not (org-element-lineage section 'headline)) (org-ascii--describe-links (org-ascii--unique-links section info) (org-ascii--current-text-width section info) @@ -1766,7 +1775,7 @@ contextual information." (if (not (org-string-nw-p links)) contents (concat (org-element-normalize-string contents) "\n\n" links)) ;; Do not apply inner margin if parent headline is low level. - (let ((headline (org-export-get-parent-headline section))) + (let ((headline (org-element-lineage section 'headline))) (if (or (not headline) (org-export-low-level-p headline info)) 0 (plist-get info :ascii-inner-margin)))))) @@ -1856,7 +1865,7 @@ contextual information." (cond ((eq (org-element-property :type table) 'org) contents) ((and (plist-get info :ascii-table-use-ascii-art) (eq (plist-get info :ascii-charset) 'utf-8) - (require 'ascii-art-to-unicode nil t)) + (org-require-package 'ascii-art-to-unicode nil 'noerror)) (with-temp-buffer (insert (org-remove-indentation (org-element-property :value table))) @@ -1884,8 +1893,8 @@ column. When `org-ascii-table-widen-columns' is non-nil, width cookies are ignored." - (let* ((row (org-export-get-parent table-cell)) - (table (org-export-get-parent row)) + (let* ((row (org-element-parent table-cell)) + (table (org-element-parent row)) (col (let ((cells (org-element-contents row))) (- (length cells) (length (memq table-cell cells))))) (cache @@ -2048,10 +2057,10 @@ contextual information." "Filter controlling number of blank lines after a headline. HEADLINE is a string representing a transcoded headline. BACKEND -is symbol specifying back-end used for export. INFO is plist +is symbol specifying backend used for export. INFO is plist containing the communication channel. -This function only applies to `ascii' back-end. See +This function only applies to `ascii' backend. See `org-ascii-headline-spacing' for information." (let ((headline-spacing (plist-get info :ascii-headline-spacing))) (if (not headline-spacing) headline @@ -2062,7 +2071,7 @@ This function only applies to `ascii' back-end. See "Filter controlling number of blank lines between paragraphs. TREE is the parse tree. BACKEND is the symbol specifying -back-end used for export. INFO is a plist used as +backend used for export. INFO is a plist used as a communication channel. See `org-ascii-paragraph-spacing' for information." @@ -2070,20 +2079,21 @@ See `org-ascii-paragraph-spacing' for information." (when (wholenump paragraph-spacing) (org-element-map tree 'paragraph (lambda (p) - (when (eq (org-element-type (org-export-get-next-element p info)) - 'paragraph) + (when (org-element-type-p + (org-export-get-next-element p info) 'paragraph) (org-element-put-property p :post-blank paragraph-spacing)))))) tree) (defun org-ascii-filter-comment-spacing (tree _backend info) "Filter removing blank lines between comments. TREE is the parse tree. BACKEND is the symbol specifying -back-end used for export. INFO is a plist used as +backend used for export. INFO is a plist used as a communication channel." (org-element-map tree '(comment comment-block) (lambda (c) - (when (memq (org-element-type (org-export-get-next-element c info)) - '(comment comment-block)) + (when (org-element-type-p + (org-export-get-next-element c info) + '(comment comment-block)) (org-element-put-property c :post-blank 0)))) tree) @@ -2098,6 +2108,8 @@ a communication channel." (let ((org-ascii-charset 'ascii)) (org-export-replace-region-by 'ascii))) +(defalias 'org-export-region-to-ascii #'org-ascii-convert-region-to-ascii) + ;;;###autoload (defun org-ascii-convert-region-to-utf8 () "Assume region has Org syntax, and convert it to UTF-8." @@ -2105,6 +2117,8 @@ a communication channel." (let ((org-ascii-charset 'utf-8)) (org-export-replace-region-by 'ascii))) +(defalias 'org-export-region-to-utf8 #'org-ascii-convert-region-to-utf8) + ;;;###autoload (defun org-ascii-export-as-ascii (&optional async subtreep visible-only body-only ext-plist) diff --git a/elpa/org-9.6.7/ox-beamer.el b/elpa/org-9.7.17/ox-beamer.el similarity index 89% rename from elpa/org-9.6.7/ox-beamer.el rename to elpa/org-9.7.17/ox-beamer.el index 689bf155..d49cccde 100644 --- a/elpa/org-9.6.7/ox-beamer.el +++ b/elpa/org-9.7.17/ox-beamer.el @@ -1,11 +1,10 @@ -;;; ox-beamer.el --- Beamer Back-End for Org Export Engine -*- lexical-binding: t; -*- +;;; ox-beamer.el --- Beamer Backend for Org Export Engine -*- lexical-binding: t; -*- -;; Copyright (C) 2007-2023 Free Software Foundation, Inc. +;; Copyright (C) 2007-2024 Free Software Foundation, Inc. ;; Author: Carsten Dominik ;; Nicolas Goaziou -;; Maintainer: Nicolas Goaziou -;; Keywords: org, wp, tex +;; Keywords: org, text, tex ;; This file is part of GNU Emacs. @@ -24,7 +23,7 @@ ;;; Commentary: ;; -;; This library implements both a Beamer back-end, derived from the +;; This library implements both a Beamer backend, derived from the ;; LaTeX one and a minor mode easing structure edition of the ;; document. See Org manual for more information. @@ -116,10 +115,10 @@ open The opening template for the environment, with the following escapes %r the raw headline text (i.e. without any processing) %H if there is headline text, that raw text in {} braces %U if there is headline text, that raw text in [] brackets + %l the label, obtained from `org-beamer--get-label' close The closing string of the environment." :group 'org-export-beamer - :version "24.4" - :package-version '(Org . "8.1") + :package-version '(Org . "9.7") :type '(repeat (list (string :tag "Environment") @@ -148,6 +147,22 @@ which is replaced with the subtitle." :package-version '(Org . "8.3") :type '(string :tag "Format string")) +(defcustom org-beamer-frame-environment "orgframe" + "Name of the alternative beamer frame environment. +In frames marked as fragile, this environment is used in place of +the usual frame environment. + +This permits insertion of a beamer frame inside example blocks, +working around beamer limitations. See +https://list.orgmode.org/87a5nux3zr.fsf@t14.reltub.ca/T/#mc7221e93f138bdd56c916b194b9230d3a6c3de09 + +This option may need to be changed when \"\\end{orgframe}\" string is +used inside beamer slides." + :group 'org-export-beamer + :package-version '(Org . "9.7") + :type '(string :tag "Beamer frame") + :safe (lambda (str) (string-match-p "^[A-Za-z]+$" str))) + ;;; Internal Variables @@ -165,7 +180,7 @@ which is replaced with the subtitle." ("ignoreheading" "i") ("note" "n") ("noteNH" "N")) - "Alist of environments treated in a special way by the back-end. + "Alist of environments treated in a special way by the backend. Keys are environment names, as strings, values are bindings used in `org-beamer-select-environment'. Environments listed here, along with their binding, are hard coded and cannot be modified @@ -178,10 +193,10 @@ through `org-beamer-environments-extra' variable.") ("quotation" "q" "\\begin{quotation}%a %% %h" "\\end{quotation}") ("quote" "Q" "\\begin{quote}%a %% %h" "\\end{quote}") ("structureenv" "s" "\\begin{structureenv}%a %% %h" "\\end{structureenv}") - ("theorem" "t" "\\begin{theorem}%a[%h]" "\\end{theorem}") - ("definition" "d" "\\begin{definition}%a[%h]" "\\end{definition}") - ("example" "e" "\\begin{example}%a[%h]" "\\end{example}") - ("exampleblock" "E" "\\begin{exampleblock}%a{%h}" "\\end{exampleblock}") + ("theorem" "t" "\\begin{theorem}%a[%h]%l" "\\end{theorem}") + ("definition" "d" "\\begin{definition}%a[%h]%l" "\\end{definition}") + ("example" "e" "\\begin{example}%a[%h]%l" "\\end{example}") + ("exampleblock" "E" "\\begin{exampleblock}%a{%h}%l" "\\end{exampleblock}") ("proof" "p" "\\begin{proof}%a[%h]" "\\end{proof}") ("beamercolorbox" "o" "\\begin{beamercolorbox}%o{%h}" "\\end{beamercolorbox}")) "Environments triggered by properties in Beamer export. @@ -221,14 +236,14 @@ An element has an overlay specification when it starts with an `beamer' export-snippet whose value is between angular brackets. Return overlay specification, as a string, or nil." (let ((first-object (car (org-element-contents element)))) - (when (eq (org-element-type first-object) 'export-snippet) + (when (org-element-type-p first-object 'export-snippet) (let ((value (org-element-property :value first-object))) (and (string-prefix-p "<" value) (string-suffix-p ">" value) value))))) -;;; Define Back-End +;;; Define Backend (org-export-define-derived-backend 'beamer 'latex :menu-entry @@ -273,7 +288,7 @@ Return overlay specification, as a string, or nil." ;;;; Bold (defun org-beamer-bold (bold contents _info) - "Transcode BLOCK object into Beamer code. + "Transcode BOLD object into Beamer code. CONTENTS is the text being bold. INFO is a plist used as a communication channel." (format "\\alert%s{%s}" @@ -376,7 +391,7 @@ CONTENTS holds the contents of the headline. INFO is a plist used as a communication channel." (let ((latex-headline (org-export-with-backend - ;; We create a temporary export back-end which behaves the + ;; We create a temporary export backend which behaves the ;; same as current one, but adds "\protect" in front of the ;; output of some objects. (org-export-create-backend @@ -408,12 +423,27 @@ used as a communication channel." "Format HEADLINE as a frame. CONTENTS holds the contents of the headline. INFO is a plist used as a communication channel." - (let ((fragilep - ;; FRAGILEP is non-nil when HEADLINE contains an element - ;; among `org-beamer-verbatim-elements'. - (org-element-map headline org-beamer-verbatim-elements 'identity - info 'first-match))) - (concat "\\begin{frame}" + (let* ((fragilep + ;; FRAGILEP is non-nil when HEADLINE contains an element + ;; among `org-beamer-verbatim-elements'. + (org-element-map headline org-beamer-verbatim-elements 'identity + info 'first-match)) + ;; If FRAGILEP is non-nil and CONTENTS contains an occurrence + ;; of \begin{frame} or \end{frame}, then set the FRAME + ;; environment to be `org-beamer-frame-environment'; + ;; otherwise, use "frame". If the selected environment is not + ;; "frame", then add the property :beamer-define-frame to + ;; INFO and set it to t. + (frame (let ((selection + (or (and fragilep + (or (string-match-p "\\\\begin{frame}" contents) + (string-match-p "\\\\end{frame}" contents)) + org-beamer-frame-environment) + "frame"))) + (unless (string= selection "frame") + (setq info (plist-put info :beamer-define-frame t))) + selection))) + (concat "\\begin{" frame "}" ;; Overlay specification, if any. When surrounded by ;; square brackets, consider it as a default ;; specification. @@ -480,7 +510,7 @@ used as a communication channel." ;; output. (if (not fragilep) contents (replace-regexp-in-string "\\`\n*" "\\& " (or contents ""))) - "\\end{frame}"))) + "\\end{" frame "}"))) (defun org-beamer--format-block (headline contents info) "Format HEADLINE as a block. @@ -512,21 +542,33 @@ used as a communication channel." (options (if raw-options (org-beamer--normalize-argument raw-options 'option) "")) + ;; also process actions + (raw-action (org-element-property :BEAMER_ACT headline)) + (action (if raw-action + ;; If BEAMER_act property has its value enclosed in square + ;; brackets, it is a default overlay specification and + ;; overlay specification is empty. Otherwise, it is an + ;; overlay specification and the default one is nil. + (org-beamer--normalize-argument + raw-action + (if (string-match "\\`\\[.*\\]\\'" raw-action) 'defaction + 'action)) + "")) ;; Start a "columns" environment when explicitly requested or ;; when there is no previous headline or the previous ;; headline do not have a BEAMER_column property. (parent-env (org-element-property - :BEAMER_ENV (org-export-get-parent-headline headline))) + :BEAMER_ENV (org-element-lineage headline 'headline))) (start-columns-p (or (equal environment "columns") (and column-width (not (and parent-env - (equal (downcase parent-env) "columns"))) + (equal (downcase parent-env) "columns"))) (or (org-export-first-sibling-p headline info) (not (org-element-property - :BEAMER_COL - (org-export-get-previous-element - headline info))))))) + :BEAMER_COL + (org-export-get-previous-element + headline info))))))) ;; End the "columns" environment when explicitly requested or ;; when there is no next headline or the next headline do not ;; have a BEAMER_column property. @@ -534,11 +576,11 @@ used as a communication channel." (or (equal environment "columns") (and column-width (not (and parent-env - (equal (downcase parent-env) "columns"))) + (equal (downcase parent-env) "columns"))) (or (org-export-last-sibling-p headline info) (not (org-element-property - :BEAMER_COL - (org-export-get-next-element headline info)))))))) + :BEAMER_COL + (org-export-get-next-element headline info)))))))) (concat (when start-columns-p ;; Column can accept options only when the environment is @@ -546,10 +588,13 @@ used as a communication channel." (if (not (equal environment "columns")) "\\begin{columns}\n" (format "\\begin{columns}%s\n" options))) (when column-width - (format "\\begin{column}%s{%s}\n" + (format "\\begin{column}%s%s{%s}\n" ;; One can specify placement for column only when ;; HEADLINE stands for a column on its own. - (if (equal environment "column") options "") + options + (if env-format + "" ; Inner environment is specified - pass actions later. + action) (format "%s\\columnwidth" column-width))) ;; Block's opening string. (when (nth 2 env-format) @@ -557,27 +602,23 @@ used as a communication channel." (org-fill-template (nth 2 env-format) (nconc - ;; If BEAMER_act property has its value enclosed in square - ;; brackets, it is a default overlay specification and - ;; overlay specification is empty. Otherwise, it is an - ;; overlay specification and the default one is nil. - (let ((action (org-element-property :BEAMER_ACT headline))) - (cond - ((not action) (list (cons "a" "") (cons "A" "") (cons "R" ""))) - ((and (string-prefix-p "[" action) - (string-suffix-p "]" action)) - (list - (cons "A" (org-beamer--normalize-argument action 'defaction)) - (cons "a" "") - (cons "R" action))) - (t - (list (cons "a" (org-beamer--normalize-argument action 'action)) - (cons "A" "") - (cons "R" action))))) + (cond + ((not action) (list (cons "a" "") (cons "A" "") (cons "R" ""))) + ((and (string-prefix-p "[" action) + (string-suffix-p "]" action)) + (list + (cons "A" (org-beamer--normalize-argument action 'defaction)) + (cons "a" "") + (cons "R" raw-action))) + (t + (list (cons "a" action) + (cons "A" "") + (cons "R" raw-action)))) (list (cons "o" options) (cons "O" (or raw-options "")) (cons "h" title) (cons "r" raw-title) + (cons "l" (format "\\label{%s}" (org-beamer--get-label headline info))) (cons "H" (if (equal raw-title "") "" (format "{%s}" raw-title))) (cons "U" (if (equal raw-title "") "" @@ -693,7 +734,7 @@ contextual information." (lambda (item _c _i) (let ((action (let ((first (car (org-element-contents item)))) - (and (eq (org-element-type first) 'paragraph) + (and (org-element-type-p first 'paragraph) (org-beamer--element-has-overlay-p first)))) (output (org-latex-item item contents info))) (if (not (and action (string-match "\\\\item" output))) output @@ -713,7 +754,7 @@ channel." (let ((key (org-element-property :key keyword)) (value (org-element-property :value keyword))) ;; Handle specifically BEAMER and TOC (headlines only) keywords. - ;; Otherwise, fallback to `latex' back-end. + ;; Otherwise, fallback to `latex' backend. (cond ((equal key "BEAMER") value) ((and (equal key "TOC") (string-match "\\" value)) @@ -738,7 +779,7 @@ used as a communication channel." ;; Fall-back to LaTeX export. However, prefer "\hyperlink" over ;; "\hyperref" since the former handles overlay specifications. (let* ((latex-link (org-export-with-backend 'latex link contents info)) - (parent (org-export-get-parent-element link)) + (parent (org-element-parent-element link)) (attr (org-export-read-attribute :attr_beamer parent)) (overlay (plist-get attr :overlay))) (cond ((string-match "\\`\\\\hyperref\\[\\(.*?\\)\\]" latex-link) @@ -803,10 +844,9 @@ contextual information." (org-export-get-reference radio-target info) text)) - ;;;; Template ;; -;; Template used is similar to the one used in `latex' back-end, +;; Template used is similar to the one used in `latex' backend, ;; excepted for the table of contents and Beamer themes. (defun org-beamer-template (contents info) @@ -816,13 +856,17 @@ holding export options." (let ((title (org-export-data (plist-get info :title) info)) (subtitle (org-export-data (plist-get info :subtitle) info))) (concat - ;; Time-stamp. + ;; Timestamp. (and (plist-get info :time-stamp-file) (format-time-string "%% Created %Y-%m-%d %a %H:%M\n")) ;; LaTeX compiler (org-latex--insert-compiler info) ;; Document class and packages. (org-latex-make-preamble info) + ;; Define the alternative frame environment, if needed. + (when (plist-get info :beamer-define-frame) + (format "\\newenvironment<>{%s}[1][]{\\begin{frame}#2[environment=%1$s,#1]}{\\end{frame}}\n" + org-beamer-frame-environment)) ;; Insert themes. (let ((format-theme (lambda (prop command) @@ -871,7 +915,7 @@ holding export options." (and (stringp template) (format-spec template (org-latex--format-spec info)))) ;; engrave-faces-latex preamble - (when (and (eq org-latex-src-block-backend 'engraved) + (when (and (eq (plist-get info :latex-src-block-backend) 'engraved) (org-element-map (plist-get info :parse-tree) '(src-block inline-src-block) #'identity info t)) @@ -924,13 +968,12 @@ holding export options." "Support for editing Beamer oriented Org mode files." :lighter " Bm") -(when (fboundp 'font-lock-add-keywords) - (font-lock-add-keywords - 'org-mode - '((":\\(B_[a-z]+\\|BMCOL\\):" 1 'org-beamer-tag prepend)) - 'prepend)) +(font-lock-add-keywords + 'org-mode + '((":\\(B_[a-z]+\\|BMCOL\\):" 1 'org-beamer-tag prepend)) + 'prepend) -(defface org-beamer-tag '((t (:box (:line-width 1 :color grey40)))) +(defface org-beamer-tag '((t (:box (:line-width 1 :color "grey40")))) "The special face for beamer tags." :group 'org-export-beamer) @@ -1009,7 +1052,10 @@ will be displayed when `org-export-show-temporary-export-buffer' is non-nil." (interactive) (org-export-to-buffer 'beamer "*Org BEAMER Export*" - async subtreep visible-only body-only ext-plist (lambda () (LaTeX-mode)))) + async subtreep visible-only body-only ext-plist + (if (fboundp 'major-mode-remap) + (major-mode-remap 'latex-mode) + #'LaTeX-mode))) ;;;###autoload (defun org-beamer-export-to-latex diff --git a/elpa/org-9.6.7/ox-html.el b/elpa/org-9.7.17/ox-html.el similarity index 94% rename from elpa/org-9.6.7/ox-html.el rename to elpa/org-9.7.17/ox-html.el index b27254b8..4eb3a511 100644 --- a/elpa/org-9.6.7/ox-html.el +++ b/elpa/org-9.7.17/ox-html.el @@ -1,11 +1,11 @@ -;;; ox-html.el --- HTML Back-End for Org Export Engine -*- lexical-binding: t; -*- +;;; ox-html.el --- HTML Backend for Org Export Engine -*- lexical-binding: t; -*- -;; Copyright (C) 2011-2023 Free Software Foundation, Inc. +;; Copyright (C) 2011-2024 Free Software Foundation, Inc. ;; Author: Carsten Dominik ;; Jambunathan K ;; Maintainer: TEC -;; Keywords: outlines, hypermedia, calendar, wp +;; Keywords: outlines, hypermedia, calendar, text ;; This file is part of GNU Emacs. @@ -24,7 +24,7 @@ ;;; Commentary: -;; This library implements a HTML back-end for Org generic exporter. +;; This library implements a HTML backend for Org generic exporter. ;; See Org manual for more information. ;;; Code: @@ -55,7 +55,7 @@ (defvar htmlize-output-type) (defvar htmlize-css-name-prefix) -;;; Define Back-End +;;; Define Backend (org-export-define-backend 'html '((bold . org-html-bold) @@ -239,6 +239,10 @@ property on the headline itself.") ("\\.\\.\\." . "…")) ; hellip "Regular expressions for special string conversion.") +(defvar org-html--id-attr-prefix "ID-" + "Prefix to use in ID attributes. +This affects IDs that are determined from the ID property.") + (defcustom org-html-scripts "