emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
* [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	[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 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).