emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
From: Stefan Kangas <stefan@marxist.se>
To: Org-mode <emacs-orgmode@gnu.org>
Subject: [PATCH] Improve docstrings of agenda date navigation commands
Date: Mon, 20 Jun 2022 17:54:52 +0200	[thread overview]
Message-ID: <CADwFkmmHYhCGBO92E2DObA16=xdgfoc3rDj+MZUDk-w77nFvKw@mail.gmail.com> (raw)


[-- 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


             reply	other threads:[~2022-06-20 15:56 UTC|newest]

Thread overview: 2+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-06-20 15:54 Stefan Kangas [this message]
2022-06-21  5:05 ` Daniel Fleischer

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://www.orgmode.org/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to='CADwFkmmHYhCGBO92E2DObA16=xdgfoc3rDj+MZUDk-w77nFvKw@mail.gmail.com' \
    --to=stefan@marxist.se \
    --cc=emacs-orgmode@gnu.org \
    --subject='Re: [PATCH] Improve docstrings of agenda date navigation commands' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

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).