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)".
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.
* 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/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-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.
* 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-agenda.el (org-agenda-block-separator)
(org-agenda-time-grid, org-agenda-current-time-string): Improve
default visual elements on graphical displays. Inspired by
org-modern.el by Daniel Mendler <mail@daniel-mendler.de>.
Emacs now advises using "website" (instead of "homepage") and
consequently to use the "URL" comment header instead of "Homepage".
* README:
* README_ELPA:
* doc/org-guide.org (Creating Footnotes):
* doc/org-manual.org (Creating Footnotes):
* etc/styles/README (URL): Prefer "website" to "homepage".
* lisp/*.el:
* mk/org-fixup.el: Replace the "Homepage" header comment with "URL".
* 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-agenda.el: Re-enable native compilation as it does not
cause any issues with agenda rendering without other custom changes
not included in this branch.
* lisp/ol.el (org-link--link-folding-spec):
(org-link--description-folding-spec): New variables controlling link
folding settings.
(org-link--reveal-maybe): Handle revealing folded links.
(org-link-descriptive-ensure): Implement `org-link-descriptive'
support with org-fold.
(org-toggle-link-display--overlays):
(org-toggle-link-display--text-properties):
(org-toggle-link-display): Provide text-properties and overlays
versions.
* lisp/org-agenda.el (org-agenda-mode): Use org-fold to fold links in
agenda.
* lisp/org.el (org-do-emphasis-faces): Use org-fold.
* lisp/org.el (org-at-heading-p): Use second argument to allow
checking for visible headings. Note that by default, unlike
`outline-on-heading-p', `org-at-heading-p' returns non-nil for
invisible headings. Passing second argument is just like
`(outline-on-heading-p)'.
(org-indent-line):
* lisp/org-agenda.el (org-agenda-add-entry-to-org-agenda-diary-file):
* lisp/org-colview.el (org-columns--call):
(org-columns-store-format): Update arguments in `org-at-heading-p'
calls.
* lisp/org-agenda.el (org-agenda-prepare):
(org-todo-list):
(org-agenda-align-tags):
(org-agenda-show-new-time): Calculate the maximum number of chars
fitting into window via `window-max-chars-per-line' instead of
`window-with' or `window-text-with'. The latter functions can return
larger number when fringes are disabled [1].
[1] https://debbugs.gnu.org/cgi/bugreport.cgi?bug=19395
Reported in https://orgmode.org/list/87czhdqi9p.fsf_-_@moondust.localdomain
* lisp/org-agenda.el (org-agenda-get-timestamps): Use
`org-at-timestamp-p' instead of org-element to check if at valid
timestamp. Agenda should consider timestamps inside node properties
even though they are not parsed by org-element.
* testing/lisp/test-org-agenda.el (test-org-agenda/property-timestamp):
Add new test checking active timestamp inside property drawer.
* testing/examples/agenda-file.org (test timestamp inside properties):
Add heading for `test-org-agenda/property-timestamp'.
Reported in https://list.orgmode.org/06d301d83d9e$f8b44340$ea1cc9c0$@tomdavey.com
* lisp/org-agenda.el (org-agenda-highlight-todo): Skip formatting
the to-do keyword when `org-agenda-todo-keyword-format' is the
empty string.
TINYCHANGE
* lisp/ob-tangle.el (org-id-link-to-org-use-id):
* lisp/org-agenda.el (org-agenda-overriding-header): Do not try set
value of a variable defined elsewhere. This may interfere with custom
interface. See
https://list.orgmode.org/orgmode/871r19ryxb.fsf@localhost/
(org-agenda-restrict):
* lisp/ol-bibtex.el (org-bibtex-description): Remove incorrect
comments.
* lisp/org-agenda.el (org-agenda-get-scheduled): Do not rely on regex
match to judge that current headline is scheduled with time when
WITH-HOUR argument is non-nil. Limit regexp search when looking for
scheduled timestamp in current headline and intentionally signal
search error if something went wrong (headline without scheduled
timestamp in planning line must not be encountered at this point in
the code).
This commit continues 77a9932b0 and 82197761.
* lisp/org-agenda.el (org-agenda-get-scheduled): First `deadline'
let-binding when element cache is enabled should not be timestamp
element, but a string. Make it so.
Reprted in https://list.orgmode.org/87tuhazs36.fsf@localhost/T/#t
* lisp/org-agenda.el (org-agenda-skip): Use
`org-in-archived-heading-p' and `org-in-commented-heading-p' in place
of text property cache.
(org-agenda-get-todos, org-agenda-get-timestamps,
org-agenda-get-sexps, org-agenda-get-progress,
org-agenda-get-deadlines, org-agenda-get-scheduled,
org-agenda-get-blocks): Do not use text property cache in favour of
Org API functions. The API functions use cache now.
* lisp/org-clock.el (org-element--cache-active-p): Declare function to
suppress compiler warning.
(org-clock-in): Do not use text property cache when element cache is
active.
* lisp/org-duration.el (org-duration-to-minutes): Do not change match
data. It is needed to not break agenda---agenda relies on match data
not being altered.
* lisp/org.el (org-run-like-in-org-mode): Use element cache.
(org-refresh-category-properties): Use element cache.
(org-make-tags-matcher, org-agenda-prepare-buffers): Do not rely on
text property cache.
* testing/lisp/test-org.el (test-org/refresh-category-properties): Do
not use text property cache.
* lisp/org-agenda.el (org-agenda-highlight-todo):
(org-agenda-set-mode-name):
* lisp/org-table.el (org-table-eval-formula): Avoid space before tab in
indent.
This is in preparation for syncing with the Emacs repo.
* org-agenda.el (org-agenda--insert-overriding-header): Allow
`org-agenda-overriding-header' to be a function in addition to a
string or nil. When the custom agenda is created or updated, call that
function and insert the string it returns as the agenda header.
This allows custom commands to produce dynamic headers that include
up-to-date information. For example, this produces a header with a
current timestamp:
(push '("DHD" "Dynamic header demo"
((alltodo
""
((org-agenda-overriding-header
(lambda ()
(propertize
(format-time-string "-- Get crackin’, it’s %H:%M:%S!!\n")
'face 'org-agenda-structure)))))))
org-agenda-custom-commands)
User is free to add any face properties, use Org links, and include a
blank line or not. I am using this to count how many items are in
various inboxes and display them in an agenda.
* lisp/ox-html.el (org-html-htmlize-output-type):
* lisp/org-agenda.el (org-agenda-do-in-region): Don't quote t and nil.
Don't quote nil and t in doc strings and comments
85e9e5f616fb0fd0819a04006d6d2a0fb6d93ad7
Lars Ingebrigtsen
Tue Sep 21 22:11:43 2021 +0200
* lisp/org-agenda.el (org-search-view): Don't use `format' on
strings that have no % format directives in them.
Don't use `format' on strings without % format directives
43c1ee90cb3333dc2643e58cf607399b0abebf43
Lars Ingebrigtsen
Tue Sep 21 17:52:53 2021 +0200
* lisp/org-agenda.el (org-search-view)
(org-agenda-propertize-selected-todo-keywords, org-todo-list)
(org-tags-view): Implement new org-agenda-structure-filter and
org-agenda-structure-secondary faces.
(org-agenda-get-day-face): Add condition for rendering the current
date heading in org-agenda-date-weekend-today.
* lisp/org-faces.el (org-agenda-structure-secondary)
(org-agenda-date-weekend-today, org-agenda-structure-filter)
(org-imminent-deadline): Add new faces.
(org-agenda-deadline-faces): Use the 'org-imminent-deadline' for
current deadlines instead of the generic 'org-warning'.
* lisp/org-agenda.el (org-compile-prefix-format): Use `read' instead
of pure regexp matching to determine bounds of %(sexp) expressions in
`org-agenda-prefix-format'.
Fixes https://orgmode.org/list/87fsy8yi1e.fsf@localhost/
* lisp/org.el (org-add-log-setup): Always run `org-add-log-note' via
`post-command-hook'. Otherwise, there is no way to know if a note was
requested for `this-command'. Running `org-add-log-note' directly
would, for example, break `org-auto-repeat-maybe' as reported in [1].
* lisp/org-agenda.el (org-agenda-todo): Avoid reintroducing the bug
fixed in c670379adf.
* testing/lisp/test-org.el: Add test checking the reported bug.
[1] https://orgmode.org/list/CAOn=hbcaW1R6vtun-E2r4LS=j3dp=VjqmjGtzy8UC1SyPArKbA@mail.gmail.com
* lisp/org-agenda.el (org-agenda-dim-blocked-tasks): When the blocked
task is the last line in agenda buffer and no trailing newline is
present, (move-beginning-of-line 2) would not move the point causing
infinite loop. Now, such case is handled correctly.
* lisp/org-agenda.el (org-agenda-get-restriction-and-command):
Using `error' here will trigger users with `debug-on-error' so use
`user-error' instead (bug#49920). It would probably be preferable
to rewrite this to not use the error system to do control flow.
Make `q' in `org-agenda' work even with `debug-on-error' set
6a3920c07eaae58408dd27e7db22bff7ad4d1f80
Lars Ingebrigtsen
Sat Aug 7 12:55:39 2021 +0200
* lisp/org-agenda.el (org-agenda-format-item): Call
`org-get-time-of-day' twice. Once to get proper time information, and
a second time to format it.
(org-get-time-of-day): Remove an optional argument. Extend the one
left, and document it. Rewrite function.
Reported-by: Eric S Fraga <e.fraga@ucl.ac.uk>
<https://orgmode.org/list/87lf84408r.fsf@ucl.ac.uk/>
* lisp/org.el (org-log-setup): New variable.
(org-auto-repeat-maybe): Check against `org-log-setup' if we are
currently logging.
(org-add-log-setup): Only use `post-command-hook' when logging a
note, otherwise use `org-log-setup'.
(org-add-log-note): Reset `org-log-setup' to nil.
(org-store-log-note): Remove useless code.
* lisp/org-agenda.el (org-agenda-bulk-action): Check
`org-log-setup' instead of `post-command-hook'.
This is a more correct fix that supersedes the previous attempt with
08a47b09 for the same problem.
Reported-by: Warren Lynn <wrn.lynn@gmail.com>
Link: https://orgmode.org/list/87v98a8mes.fsf@gnu.org/
* org-agenda.el (org-agenda-show-clocking-issues): Fix regex
to prevent false-positive clocking issue detection.
Regex was missing a grouping to restrict the alternative \| to the
literal parentheses.
TINYCHANGE
* lisp/org-agenda.el (org-get-time-of-day): Use "09:00" instead
of " 9:00" when displaying as a string.
This makes the string more readable, especially for users reading
the agenda with a screen reader.
Reported-by: Sébastien Hinderer
* lisp/org-agenda.el (org-agenda-highlight-todo): Skip formatting
the to-do keyword when `org-agenda-todo-keyword-format' is the
empty string.
TINYCHANGE
* lisp/org-agenda.el (org-agenda-highlight-todo): Skip formatting
the to-do keyword when `org-agenda-todo-keyword-format' is the
empty string.
TINYCHANGE
* lisp/org.el (org-stamp-time-of-day-regexp): Limit match group 2 to
first time.
* lisp/org-agenda.el (org-agenda-format-item): Compute duration before
formatting time with `org-get-time-of-day'.
* lisp/org.el (org-stamp-time-of-day-regexp): Limit match group 2 to
first time.
* lisp/org-agenda.el (org-agenda-format-item): Compute duration before
formatting time with `org-get-time-of-day'.
* lisp/org-agenda.el (org-agenda-later): Prevent window from
scrolling to the point when `scroll-conservatively' is > 101.
Reported-by: Gustavo Barros <gusbrs.2016@gmail.com>
Link: https://orgmode.org/list/87lfh2hk4k.fsf@gmail.com/