bug#15598: 24.3.50; documentation: org-mode calendar interaction

[Joe Corneli]

The org-mode manual (8.2.1 The date/time prompt) documents this keyboard
command for selecting dates for scheduling using the calendar:

    S-<right>/<left>     One day forward/backward.

However, the documentation string for `org-schedule' (which is the
command that pops up the calendar) doesn't talk about this at all:

  "Insert the SCHEDULED: string with a timestamp to schedule a TODO item.
With argument REMOVE, remove any scheduling date from the item.
With argument TIME, scheduled at the corresponding date.  TIME can
either be an Org date like \"2011-07-24\" or a delta like \"+2d\"."

The function `org-read-date' goes into a bit more detail, but it doesn't
describe this particular behavior either (and isn't it isn't linked to from
the documentation for `org-schedule'):

...
While prompting, a calendar is popped up - you can also select the
date with the mouse (button 1).  The calendar shows a period of three
months.  To scroll it to other months, use the keys `>' and `<'.
If you don't like the calendar, turn it off with
       \(setq org-read-date-popup-calendar nil)
...

Furthermore, and more confusingly, C-h m pressed in the minibuffer after
running `org-schedule' doesn't describe this command either.  If you
happen to know the command, you can type C-h k S-<right> RET
to get this explanation:

<S-right> runs the command #[nil "\300\301!\207" [org-eval-in-calendar
(calendar-forward-day 1)] 2 nil nil], which is an interactive compiled
Lisp function.

It seems like there are several missing steps in the documentation.



In GNU Emacs 24.3.50.1 (x86_64-unknown-linux-gnu, GTK+ Version 2.24.10)
 of 2013-02-28 on lwkm242457
Windowing system distributor `The X.Org Foundation', version 11.0.11103000
System Description:    Ubuntu 12.04.2 LTS

Important settings:
  value of $LANG: en_GB.UTF-8
  locale-coding-system: utf-8-unix
  default enable-multibyte-characters: t

Major mode: Shell

Minor modes in effect:
  show-paren-mode: t
  diff-auto-refine-mode: t
  shell-dirtrack-mode: t
  tooltip-mode: t
  mouse-wheel-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  line-number-mode: t
  transient-mark-mode: t

Recent input:
m C-x o C-s S - C-s C-x o C-h C-g C-h m C-x o C-x o
C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n
C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n
C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n
C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n
C-n C-n C-x b C-g C-x b o <tab> . <tab> <return> C-x
1 C-r S - C-r <down> C-s c a l e n d a r C-s C-n C-n
M-b M-b M-b M-b M-b C-SPC C-e M-w M-v C-l C-n C-n C-n
C-n C-n C-n C-n C-n C-n C-n C-n C-l C-n C-n C-n C-n
C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-l
C-x b <return> C-c C-s C-h k è C-x o C-x o C-h k <S-down>
C-x o C-x o C-SPC <C-right> <C-right> <C-right> <C-left>
M-w C-x o C-h k <S-right> <S-right> <S-right> C-x o
<S-right> <S-right> <S-left> <S-left> <S-left> <S-left>
<S-down> <S-left> <S-left> C-g C-x C-b C-x o <down>
<down> <return> C-x 1 C-s S - C-r C-r - <backspace>
c C-r C-r C-r C-r C-r C-r C-r C-r C-r <up> <C-left>
C-SPC <C-right> M-w M-v M-v M-v C-s S - c u r C-s C-s
C-s C-s C-s C-s C-s C-s M-< <down> <down> <down> <down>
<down> <down> M-f M-f M-f M-f M-b C-SPC C-e <left>
M-w <switch-frame> <switch-frame> C-SPC M-b M-b M-b
M-b M-b M-w C-x b . e m <tab> <return> C-v C-n C-n
<up> C-SPC <C-right> <C-right> M-w C-c a t C-h C-g
C-c a a C-x 1 C-z d a t e <return> <switch-frame> <switch-frame>
C-g M-x r e p <tab> o <tab> r <tab> <return>

Recent messages:
Press key for agenda command: [2 times]
Preparing diary...done
Preparing diary...done
Preparing diary...done
Preparing diary...done
Preparing diary...done
Preparing diary...done
Preparing diary...done
Quit
Making completion list... [2 times]

Load-path shadows:
/usr/share/emacs/site-lisp/dictionaries-common/ispell hides
/usr/local/share/emacs/24.3.50/lisp/textmodes/ispell
/usr/share/emacs/site-lisp/dictionaries-common/flyspell hides
/usr/local/share/emacs/24.3.50/lisp/textmodes/flyspell

Features:
(shadow sort mail-extr emacsbug message rfc822 mml mml-sec mm-decode
mm-bodies mm-encode mail-parse rfc2231 mailabbrev gmm-utils mailheader
sendmail rfc2047 rfc2045 ietf-drums mail-utils jka-compr sh-script smie
dired-aux apropos dabbrev org-element color crm cus-edit cus-start
cus-load wid-edit parse-time macros cal-iso org-clock org-attach org-id
org-wl org-w3m org-vm org-rmail org-mhe org-mew org-irc org-jsinfo
org-infojs org-html org-exp ob-exp org-exp-blocks org-agenda org-info
org-gnus org-docview org-bibtex bibtex org-bbdb org ob-tangle ob-ref
ob-lob ob-table org-footnote org-src ob-comint ob-keys org-pcomplete
org-list org-faces org-entities org-version ob-emacs-lisp ob org-compat
org-macs ob-eval org-loaddefs find-func tramp-cache tabify man js
warnings json imenu vc-git dired pcmpl-unix org-install help-mode debug
misearch multi-isearch cal-move caly view mule-util cal-china lunar
solar cal-dst cal-bahai cal-islam cal-hebrew holidays hol-loaddefs appt
whitespace tramp tramp-compat auth-source eieio gnus-util mm-util
mail-prsvr password-cache tramp-loaddefs trampver format-spec slime-repl
elp slime byte-opt bytecomp byte-compile cconv pp hyperspec paren
diary-lib diary-loaddefs cal-menu calendar cal-loaddefs ediff-merg
ediff-diff ediff-wind ediff-help ediff-util ediff-mult ediff-init ediff
ido ess-toolbar ess-mouse mouseme browse-url ess-menu ess-swv ess-noweb
ess-noweb-font-lock-mode ess-bugs-l essd-els ess-sas-d ess-sas-l
ess-sas-a ess-arc-d ess-vst-d ess-xls-d ess-lsp-l ess-sta-d ess-sta-l
make-regexp ess-sp6-d ess-sp5-d ess-sp3-d ess-julia ess-r-d ess-tracebug
ess-roxy advice hideshow ess-help info reporter ess-developer ess-r-args
eldoc help-fns ess-s-l ess ess-inf ess-mode ess-noweb-mode ess-utils
ess-custom executable ess-compat ess-site magit-bisect magit-key-mode
magit diff-mode log-edit pcvs-util add-log php-mode etags cc-langs
cc-mode cc-fonts cc-guess cc-menus cc-cmds cc-styles cc-align cc-engine
cc-vars cc-defs speedbar sb-image ezimage dframe markdown-mode edmacro
kmacro noutline outline easymenu tex-mode pcase cl-macs gv compile shell
pcomplete comint ansi-color ring skeleton compare-w derived wc-mode
litable easy-mmode thingatpt dash cl nadvice cl-lib server time-date
tooltip ediff-hook vc-hooks lisp-float-type mwheel x-win x-dnd tool-bar
dnd fontset image regexp-opt fringe tabulated-list newcomment lisp-mode
register page menu-bar rfn-eshadow timer select scroll-bar mouse
jit-lock font-lock syntax facemenu font-core frame cham georgian
utf-8-lang misc-lang vietnamese tibetan thai tai-viet lao korean
japanese hebrew greek romanian slovak czech european ethiopic indian
cyrillic chinese case-table epa-hook jka-cmpr-hook help simple abbrev
minibuffer loaddefs button faces cus-face macroexp files text-properties
overlay sha1 md5 base64 format env code-pages mule custom widget
hashtable-print-readable backquote make-network-process dbusbind inotify
dynamic-setting system-font-setting font-render-setting move-toolbar gtk
x-toolkit x multi-tty emacs)