The Emacs doc string convention is to document values as-is when that
is clear, and surrounded by `single quotes' otherwise. For example, a
doc string "(a b c)" stands for a list of symbols, and the doc string
"`a'" stands for a single symbol. The doc string "\\=`a" is typically
not correct for that single symbol, because that is equivalent to
"(quote a)" and the typical intent is to talk about the symbol, not
about the Lisp quoting construct. One needs "\\=`X" only when talking
about something intended to be equivalent to "(quote X)", as in the
doc string "(provide \\='org-xyz)".
* lisp/ox-latex.el (org-latex--inline-image): Testing with TeXLive 2022
finds that while \includegraphics is fine with unicode characters in the
file path, \includesvg needs \detokenize{...} to prevent errors.
* lisp/org-macro.el (org-macro--vc-modified-time): Not all the vc
components needed are autoloaded, allowing for the error:
"vc-call-backend: Symbol’s value as variable is void: vc-log-view-type".
To prevent this issue from cropping up, vc is now required at the start
of `org-macro--vc-modified-time'.
As mentioned in 2e36ac2ac (Merge single quote fixes from Emacs's
master, 2022-07-24), this merge is keeping Org main's side of
org-babel-lua-read-string and org-agenda-sorting-strategy rather than
the variant introduced in the Emacs repo that's now in bugfix.
Note that for org-agenda-sorting-strategy docstring I think it'd
probably be preferable to change main's
\\='(time-up category-keep priority-down)
to a bare
(time-up category-keep priority-down)
but, at least for this merge, I'm sticking to choosing between the
variables that are in one of the sides.
This brings in ports of bbf389ea6de (Audit quoting the quote character
in doc strings, 2022-04-22), 2d71fd3b041 (Further doc string quoting
fixes, 2022-04-22), and b2bce107b15 (Further audits of single quotes
in Lisp doc strings, 2022-05-24) from Emacs's master branch, resolving
conflicts with 01b0fb14b (Backport from main: Escape single left
quotes in docstrings, 2022-07-24).
In all cases, take Emacs's side. There are two cases where I think
Org's version is preferable, org-babel-lua-read-string and
org-agenda-sorting-strategy. Don't keep those _on bugfix_ to avoid
conflicts when Emacs's emacs-28 branch is merged to its master branch.
When I merge bugfix to main, I'll keep Org's variant, so they'll
eventually make it to Emacs's tree, just not as part of the Org 9.5.x
to emacs-28 syncing.
* lisp/org.el (org-latex-to-html-convert-command):
* lisp/org-agenda.el (org-agenda-sorting-strategy): Audit use of
various single quotes in Lisp doc strings.
Further audits of single quotes in Lisp doc strings
b2bce107b15d6e0c2b773704179c6bf463525459
Lars Ingebrigtsen
Tue May 24 13:17:53 2022 +0200
[km] Org's bugfix branch is currently receiving commits from emacs-28,
but this commit comes from Emacs's master branch. I'm porting it
because it has conflicts with bugfix's 01b0fb14b (Backport from
main: Escape single left quotes in docstrings, 2022-07-24) and
only touches docstrings.
* lisp/ob-table.el (org-sbe): Further quoting fixes in doc strings.
Further doc string quoting fixes
2d71fd3b041506c68b5f1cd1e409e09e25778c34
Lars Ingebrigtsen
Fri Apr 22 17:16:42 2022 +0200
[km] Org's bugfix branch is currently receiving commits from emacs-28,
but this commit comes from Emacs's master branch. I'm porting it
because it has conflicts with bugfix's 01b0fb14b (Backport from
main: Escape single left quotes in docstrings, 2022-07-24) and
only touches docstrings.
* lisp/ox-publish.el (org-publish-find-property):
* lisp/ox-html.el (org-html--unlabel-latex-environment):
* lisp/org-table.el (org-table-collapse-header):
* lisp/org-plot.el (org--plot/prime-factors):
* lisp/org-agenda.el (org-agenda--mark-blocked-entry):
(org-agenda-set-restriction-lock):
* lisp/ob-lua.el (org-babel-lua-read-string):
* lisp/ob-julia.el (org-babel-julia-evaluate-external-process):
(org-babel-julia-evaluate-session):
* lisp/ob-core.el (org-babel-default-header-args): Fix
quoting in doc strings. In code examples, the ' character is
quoted with \\=, and regularize 'foo to `foo', and quote strings
like "foo" instead of 'foo'.
Audit quoting the quote character in doc strings
bbf389ea6deab229ba18dc519fe712ec982609d1
Lars Ingebrigtsen
Fri Apr 22 16:17:22 2022 +0200
[km] Org's bugfix branch is currently receiving commits from emacs-28,
but this commit comes from Emacs's master branch. I'm porting it
because it has conflicts with bugfix's 01b0fb14b (Backport from
main: Escape single left quotes in docstrings, 2022-07-24) and
only touches docstrings.
* lisp/org-compat.el (org-publish-cache-ctime-of-src):
New backward-compatibility alias.
* lisp/ox-publish.el (org-publish-cache-mtime-of-src):
Rename from org-publish-cache-ctime-of-src, since it
has always cached mtime not ctime. All uses changed.
* lisp/oc-biblatex.el (org-cite-biblatex-export-citation): Do not use
`seq-first'.
* lisp/org-persist.el (org-persist-collection-let): Suppress warnings.
* lisp/ox-latex.el (org-latex-src--engrave-mathescape-p): Do not use
`if-let'.
(org-latex-src--engrave-code): Do not use `string-trim-right'.
* lisp/ox.el (org-export-link-localise): Add require for subr-x for
`thread-first'.
* lisp/org-compat.el (org-replace-buffer-contents): Add compatibility
function for `replace-buffer-contents'.
* lisp/org-src.el (org-edit-src-save, org-edit-src-exit): Use
`org-replace-buffer-contents'.
* lisp/ob-core.el (org-babel-default-header-args):
* lisp/ob-julia.el (org-babel-julia-evaluate-external-process):
(org-babel-julia-evaluate-session):
* lisp/ob-lua.el (org-babel-lua-read-string):
* lisp/ob-table.el (org-sbe):
* lisp/oc-basic.el (org-cite-basic--shorten-names):
* lisp/org-agenda.el (org-agenda-sorting-strategy):
(org-agenda--mark-blocked-entry):
(org-agenda-set-restriction-lock):
* lisp/org-fold-core.el (org-fold-core--specs):
(org-fold-core-remove-folding-spec):
(org-fold-core-get-folding-spec):
(org-fold-core--isearch-overlays):
* lisp/org-plot.el (org--plot/prime-factors):
* lisp/org-table.el (org-table-collapse-header):
* lisp/org.el (org-special-ctrl-o):
(org-latex-to-html-convert-command):
* lisp/ox-html.el (org-html--unlabel-latex-environment):
* lisp/ox-publish.el (org-publish-find-property):
Use \\=' when there's a need for a single left quote in a docstring.
The emacs-29 byte compiler complains about such usage.
* lisp/org-plot.el (org-plot/gnuplot): Do not use `if-let'.
* lisp/ox-ascii.el (org-ascii--describe-links):
* lisp/ox-md.el (org-md--headline-referred-p): Do not use
`ignore-error'.
* testing/org-test.el (org-test-at-time): Fallback to older definition
of `decode-time' when it cannot accept 3 arguments.
* lisp/ox.el (org-export-data): Only catch 'org-link-broken on link
objects. Signaling 'org-link-broken for other element types, should
not happen and we should _not_ export such elements as "" or "[BROKEN
LINK...]".
* lisp/ox-md.el (org-md--headline-referred-p): Allow exporting
headlines when the document contains broken links and
`org-export-with-broken-links' is non-nil. For broken links,
`org-export-resolve-link' throws an error - catch it and do not match
the headline against such broken link.
(org-latex-language-alist): Unify in a single list
`org-latex-polyglossia-language-alist' and
`org-latex-babel-language-alist', and make the two variables
obsolete. However, it may be convenient in the future to replace this
list with a more robust one. (See:
https://list.orgmode.org/taeb0a$r62$1@ciao.gmane.io)
(org-latex-guess-babel-language): This function has been modified so
that the new Babel command `babelprovide' is also recognized. This
command is necessary to load the languages served by Babel exclusively
through an ini file. Therefore, the new Babel syntax is supported
alongside the old one. Note that languages that are served
exclusively via an ini file are not added to the Babel argument.
* lisp/ob-tangle.el (org-babel-tangle-jump-to-org): Allow fuzzy
matching when following the backlink to src block from tangles
source. The current default value of
`org-link-search-must-match-exact-headline` makes
`org-link-open-from-string` treat fuzzy links as headlines without
falling back to fuzzy text search. Bind it to nil to force fuzzy text
matching while detangling.
Fixes https://orgmode.org/list/87zgh1qxfk.fsf@posteo.net
* lisp/org-keys.el (org-mode-map): Bind `org-metaleft' to ESC <left>
by default, not just in terminals. This completes the ESC <arrow>
binding group. ESC <right>, <up>, and <down> are already bound and
missing ESC <left> can be confusing.
Reported in https://orgmode.org/list/Yf6lsTR3JSNSXRDX@x.local
* mk/default.mk (REPRO_DEBUG): New custom variable enabling extra
debugging facilities in Emacs instance open by make repro.
(REPRO_ARGS): Extra arguments passed to Emacs by make repro.
(REPRO_INIT):
(REPRO): Define Emacs cmd for testing.
* mk/targets.mk (.PHONY):
(repro): Add new target.
* doc/org-manual.org (Feedback): Describe the new make target.
* lisp/org.el (org-get-export-keywords): Add BIBLIOGRAPHY, CITE_EXPORT,
and PRINT_BIBLIOGRAPHY to `org-options-keywords'.
It's worth noting that while based on the variable name
PRINT_BIBLIOGRAPHY may not seem to fit, it is in good company with
INCLUDE, and this variable is (exclusively) used as a list of
non-affiliated, non-block, non-export-backend-specific keywords for
pcomplete. It may be a good idea to rename this for clarity, or split
it up in future.
* testing/lisp/test-ox.el: Bind `org-resource-download-policy' to t when
testing downloading.
* testing/lisp/test-org.el: Bind `org-resource-download-policy' to t
when testing downloading.
* lisp/ox-html.el (org-html-format-latex): Carry over buffer-local
variables when create LaTeX images. Use `org-export-with-buffer-copy'
instead of `with-temp-buffer'.
Fixes https://orgmode.org/list/m2fsqr75md.fsf@ego.team
* lisp/org-fold.el (org-fold-initialize): Do not extend the fold when
text is inserted right after it. This resembles folding overlay
behavior used in previous Org versions and in the 'overlays
`org-fold-core-style'.
Fixes https://orgmode.org/list/871quprrra.fsf@gmail.com
* lisp/ob-gnuplot.el (org-babel-gnuplot-process-vars): Use cons cell
of all the code block parameters and the actual assigned variable
value to generate filename for storing the data. This fixes a
scenario when code block has two or more variable assignments that
were wrongly saved into the same file. Before the commit, only the
last assigned variable value has been used by gnuplot for _all_ the
variables.
* lisp/org-src.el (org-src-font-lock-fontify-block): Copy
'font-lock-face text property in addition to 'face. This is required
because Emacs does not enable `font-lock-mode' inside buffers with
names starting from space character (Org fontification buffers are
such). Without `font-lock-mode' 'font-lock-face is not being remapped
to 'face text property and we may sometimes lose the information in
the major modes that do fontification by directly setting
'font-lock-face.
Reported in https://teddit.net/r/orgmode/comments/w2b0tw/syntax_highlighting_in_orgsource_blocks/igqdx18/
* lisp/org.el (org--get-expected-indentation): Remove the extra
condition added in e3b79ad2b in the cond branch for first line in an
element. Checking `org-adapt-indentation' t value here trigger the
last default cond branch that assumes that we are _not_ at the first
line.
The new logic explicitly avoids inheriting indentation from previous
sibling when `org-adapt-indentation' is set to 'headline-data and the
previous sibling is satisfying "headline data" condition as in
`org-indent-line'. The case when `org-adapt-indentation' is set to t
is already handled correctly when calculating the CONTENTSP
indentation for parent headline.
Fixes https://orgmode.org/list/c13cab60-bbc9-e69e-6d0d-7fe75c5908d6@kalysto.org
* lisp/org-agenda.el (org-agenda-remove-restriction-lock): Remove
agenda restriction set by `org-agenda-set-restriction-lock' called
with prefix argument. `org-agenda-restrict' may be nil while
`org-agenda-overriding-restriction' is non-nil.
Fixes https://list.orgmode.org/87v8w2qdgp.fsf@gmail.com
* lisp/org-agenda.el (org-agenda-current-time-string): Use more
commonly available "←" char indicator instead of "⭠". Suggested in
https://orgmode.org/list/875yk1e3h1.fsf@posteo.net. This patch does
not fully solve the problem with `char-displayable-p' returning
non-nil when the char cannot be actually displayed in agenda, but it
should at least make the issue less severe until we find a more
accurate test. In any case, the Unicode version of the agenda grid
will be available for more users with this patch.
* testing/lisp/test-org.el (test-org/org-time-string-to-time):
Check that no daylight saving time value is forced for
`org-parse-time-string' and `org-encode-time' calls.
* lisp/ol.el (org-store-link):
* lisp/org-agenda.el (org-agenda-get-timestamps)
(org-agenda-get-progress, agenda-bulk-action):
* lisp/org-capture.el (org-capture-fill-template):
* lisp/org-clock.el (org-clock-get-sum-start)
(org-clock-special-range, org-clocktable-shift)
(org-clocktable-steps):
* lisp/org-colview.el (org-colview-construct-allowed-dates):
* lisp/org-datetree.el (org-datetree-find-iso-week-create)
(org-datetree-insert-line):
* lisp/org-element.el (org-element-timestamp-interpreter):
* lisp/org-macro.el (org-macro--vc-modified-time):
* lisp/org-macs.el (org-matcher-time):
* lisp/org.el (org-current-time, org-current-effective-time)
(org-add-planning-info, org-read-date, org-read-date-display)
(org-read-date-analyze, org-eval-in-calendar)
(org-calendar-select, org-display-custom-time)
(org-calendar-select-mouse, org-time-string-to-time)
(org-time-from-absolute, org-at-clock-log-p)
(org-date-from-calendar, org-get-cursor-date)
(org-timestamp-to-time):
* testing/lisp/test-org-clock.el (org-test-clock-create-timestamp):
* lisp/ox-icalendar.el (org-icalendar-convert-timestamp):
Avoid direct calls of `encode-time', use `org-encode-time' instead.
Org supports Emacs-26, but the recommended way to call `encode-time'
changed in Emacs-27. In Emacs-29 DST and TZ elements of the single list
arguments became optional. In Org it is still convenient to call the
function with separate arguments without explicit DST and TZ arguments.
The `org-encode-time' should mitigate attempts to modernize Org code
directly in the Emacs repository.
* lisp/org-macs.el (org-encode-time): New compatibility and convenience
helper macro to allow a list for time components or separate arguments
independently of Emacs version.
* testing/lisp/test-org.el (org-test-with-timezone): New macro to ensure
that some code is executed with certain TZ environment value and thus
particular daylight saving time or other time shift rules are active.
* testing/lisp/test-org.el (test-org/org-encode-time): Tests for various
ways to call `org-encode-time'.
Ensure recommended way to call `encode-time' for Emacs-27 and newer with
hope to avoid bugs due to attempts to modernize the code similar to
bug#54731. 6-elements list may be allowed as `encode-time' argument
since Emacs-29, see bug#54764.
Juan Manuel Macias
Ihor Radchenko
TEC
Paul Eggert
Kyle Meyer
Stefan Kangas
Lars Ingebrigtsen
Robert Pluim
Max Nikulin