* [PATCH] Improve docstrings of agenda date navigation commands
@ 2022-06-20 15:54 Stefan Kangas
2022-06-21 5:05 ` Daniel Fleischer
0 siblings, 1 reply; 2+ messages in thread
From: Stefan Kangas @ 2022-06-20 15:54 UTC (permalink / raw)
To: Org-mode
[-- Attachment #1.1: Type: text/plain, Size: 206 bytes --]
I found the docstrings of the agenda date navigation commands to be
somewhat lacking. The attached patch expands them slightly and adds
crossreferences, which I think makes them much more usable. Thanks.
[-- Attachment #1.2: Type: text/html, Size: 234 bytes --]
[-- Attachment #2: 0001-Improve-docstrings-of-agenda-date-navigation-command.patch --]
[-- Type: application/octet-stream, Size: 3153 bytes --]
From 21734facbcdb2a10104fb0d8d8f6159590951d1f Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefan@marxist.se>
Date: Mon, 20 Jun 2022 14:06:51 +0200
Subject: [PATCH] Improve docstrings of agenda date navigation commands
* lisp/org-agenda.el (org-agenda-goto-date)
(org-agenda-goto-today, org-agenda-later, org-agenda-earlier):
Improve documentation and add crossreferences.
---
lisp/org-agenda.el | 36 ++++++++++++++++++++++++++++++------
1 file changed, 30 insertions(+), 6 deletions(-)
diff --git a/lisp/org-agenda.el b/lisp/org-agenda.el
index b4e5547d7..477439401 100644
--- a/lisp/org-agenda.el
+++ b/lisp/org-agenda.el
@@ -8319,7 +8319,16 @@ Negative selection means regexp must not match for selection of an entry."
(set var (concat (symbol-value var) string)))
(defun org-agenda-goto-date (date)
- "Jump to DATE in agenda."
+ "Jump to DATE in the agenda buffer.
+
+When called interactively, prompt for the date.
+When called from Lisp, DATE should be a date as returned by
+`org-read-date'.
+
+See also:
+ `org-agenda-earlier' (\\[org-agenda-earlier])
+ `org-agenda-later' (\\[org-agenda-later])
+ `org-agenda-goto-today' (\\[org-agenda-goto-today])"
(interactive
(list
(let ((org-read-date-prefer-future org-agenda-jump-prefer-future))
@@ -8351,7 +8360,12 @@ Negative selection means regexp must not match for selection of an entry."
org-agenda-this-buffer-is-sticky org-agenda-sticky))))
(defun org-agenda-goto-today ()
- "Go to today."
+ "Go to today's date in the agenda buffer.
+
+See also:
+ `org-agenda-later' (\\[org-agenda-later])
+ `org-agenda-earlier' (\\[org-agenda-earlier])
+ `org-agenda-goto-date' (\\[org-agenda-goto-date])"
(interactive)
(org-agenda-check-type t 'agenda)
(let* ((args (get-text-property (min (1- (point-max)) (point)) 'org-last-args))
@@ -8410,8 +8424,13 @@ When optional argument BACKWARD is set, go backward."
(message "No %s block" (if backward "previous" "further")))))))
(defun org-agenda-later (arg)
- "Go forward in time by the current span.
-With prefix ARG, go forward that many times the current span."
+ "Go forward in time by the current span in the agenda buffer.
+With prefix ARG, go forward that many times the current span.
+
+See also:
+ `org-agenda-earlier' (\\[org-agenda-earlier])
+ `org-agenda-goto-today' (\\[org-agenda-goto-today])
+ `org-agenda-goto-date' (\\[org-agenda-goto-date])"
(interactive "p")
(org-agenda-check-type t 'agenda)
(let* ((wstart (window-start))
@@ -8452,8 +8471,13 @@ With prefix ARG, go forward that many times the current span."
(set-window-start nil wstart)))
(defun org-agenda-earlier (arg)
- "Go backward in time by the current span.
-With prefix ARG, go backward that many times the current span."
+ "Go backward in time by the current span in the agenda buffer.
+With prefix ARG, go backward that many times the current span.
+
+See also:
+ `org-agenda-later' (\\[org-agenda-later])
+ `org-agenda-goto-today' (\\[org-agenda-goto-today])
+ `org-agenda-goto-date' (\\[org-agenda-goto-date])"
(interactive "p")
(org-agenda-later (- arg)))
--
2.33.0
^ permalink raw reply related [flat|nested] 2+ messages in thread
* Re: [PATCH] Improve docstrings of agenda date navigation commands
2022-06-20 15:54 [PATCH] Improve docstrings of agenda date navigation commands Stefan Kangas
@ 2022-06-21 5:05 ` Daniel Fleischer
0 siblings, 0 replies; 2+ messages in thread
From: Daniel Fleischer @ 2022-06-21 5:05 UTC (permalink / raw)
To: Stefan Kangas; +Cc: Org-mode
Stefan Kangas [2022-06-20 Mon 17:54] wrote:
> I found the docstrings of the agenda date navigation commands to be somewhat lacking. The attached patch expands them
> slightly and adds crossreferences, which I think makes them much more usable. Thanks.
Thanks, looks good. Merged at e7e37c5b2.
Best,
--
Daniel Fleischer
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2022-06-21 5:08 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2022-06-20 15:54 [PATCH] Improve docstrings of agenda date navigation commands Stefan Kangas
2022-06-21 5:05 ` Daniel Fleischer
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).