Agenda: Add missing option, document time stamp movement to future

* lisp/org-agenda.el (org-agenda-move-date-from-past-immediately-to-today):
New option.
(org-agenda-date-later): Improve the logical structure.

* doc/org.texi (Agenda commands): Document that S-right on a line
representing a past date will immediately shift that date to today.

doc/org.texi

@@ -8128,13 +8128,15 @@ command.
 @c
 @orgcmd{S-@key{right},org-agenda-do-date-later}
 Change the timestamp associated with the current line by one day into the
-future.  With a numeric prefix argument, change it by that many days.  For
+future.  If the date is in the past, the first call to this command will move
-example, @kbd{3 6 5 S-@key{right}} will change it by a year.  With a
+it to today.@*
-@kbd{C-u} prefix, change the time by one hour.  If you immediately repeat the
+With a numeric prefix argument, change it by that many days.  For example,
-command, it will continue to change hours even without the prefix arg.  With
+@kbd{3 6 5 S-@key{right}} will change it by a year.  With a @kbd{C-u} prefix,
-a double @kbd{C-u C-u} prefix, do the same for changing minutes.  The stamp
+change the time by one hour.  If you immediately repeat the command, it will
-is changed in the original Org file, but the change is not directly reflected
+continue to change hours even without the prefix arg.  With a double @kbd{C-u
-in the agenda buffer.  Use @kbd{r} or @kbd{g} to update the buffer.
+C-u} prefix, do the same for changing minutes.@*
+The stamp is changed in the original Org file, but the change is not directly
+reflected in the agenda buffer.  Use @kbd{r} or @kbd{g} to update the buffer.
 @c
 @orgcmd{S-@key{left},org-agenda-do-date-earlier}
 Change the timestamp associated with the current line by one day

lisp/org-agenda.el

@@ -1073,6 +1073,15 @@ and timeline buffers."
 	      (const :tag "Saturday" 6)
 	      (const :tag "Sunday" 0)))
 
+(defcustom org-agenda-move-date-from-past-immediately-to-today t
+  "Non-nil means jumpt to today when moving a past date forward in time.
+When using S-right in the agenda to move a a date forward, and the date
+stamp currently points to the past, the first key press will move it
+to today.  WHen nil, just move one day forward even if the date stays
+in the past."
+  :group 'org-agenda-daily/weekly
+  :type 'boolean)
+
 (defcustom org-agenda-include-diary nil
   "If non-nil, include in the agenda entries from the Emacs Calendar's diary.
 Custom commands can set this variable in the options section."
@@ -7535,14 +7544,14 @@ the same tree node, and the headline of the tree node in the Org-mode file."
 	(if (not (org-at-timestamp-p))
 	    (error "Cannot find time stamp"))
 	(when (and org-agenda-move-date-from-past-immediately-to-today
+		   (equal arg 1)
+		   (or (not what) (eq what 'day))
 		   (not (save-match-data (org-at-date-range-p))))
 	  (setq cdate (org-parse-time-string (match-string 0) 'nodefault)
 		cdate (calendar-absolute-from-gregorian 
 		       (list (nth 4 cdate) (nth 3 cdate) (nth 5 cdate)))
 		today (org-today))
-	  (if (and (equal arg 1)
+	  (if (> today cdate)
-		   (or (not what) (eq what 'day))
-		   (> today cdate))
 	      ;; immediately shift to today
 	      (setq arg (- today cdate))))
 	(org-timestamp-change arg (or what 'day))