- publishing free software manuals
The Org Mode 7 Reference Manual
by Carsten Dominik and others
Paperback (6"x9"), 282 pages
ISBN 9781906966089
RRP £9.95 ($14.95)

Sales of this book support the Org project! Get a printed copy>>>

8.2.1 The date/time prompt

When Org-mode prompts for a date/time, the default is shown in default date/time format, and the prompt therefore seems to ask for a specific format. But it will in fact accept any string containing some date and/or time information, and it is really smart about interpreting your input. You can, for example, use C-y to paste a (possibly multi-line) string copied from an email message. Org-mode will find whatever information is in there and derive anything you have not specified from the default date and time. The default is usually the current date and time, but when modifying an existing timestamp, or when entering the second stamp of a range, it is taken from the stamp in the buffer. When filling in information, Org-mode assumes that most of the time you will want to enter a date in the future: if you omit the month/year and the given day/month is before today, it will assume that you mean a future date.(53) If the date has been automatically shifted into the future, the time prompt will show this with ‘(=>F).’

For example, let's assume that today is June 13, 2006. Here is how various inputs will be interpreted, the items filled in by Org-mode are in bold.

3-2-5         => 2003-02-05
2/5/3         => 2003-02-05
14            => 2006-06-14
12            => 2006-07-12
2/5           => 2007-02-05
Fri           => nearest Friday (default date or later)
sep 15        => 2006-09-15
feb 15        => 2007-02-15
sep 12 9      => 2009-09-12
12:45         => 2006-06-13 12:45
22 sept 0:34  => 2006-09-22 0:34
w4            => ISO week for of the current year 2006
2012 w4 fri   => Friday of ISO week 4 in 2012
2012-w04-5    => Same as above

Furthermore you can specify a relative date by giving, as the first thing in the input: a plus/minus sign, a number and a letter ([dwmy]) to indicate change in days, weeks, months, or years. With a single plus or minus, the date is always relative to today. With a double plus or minus, it is relative to the default date. If instead of a single letter, you use the abbreviation of day name, the date will be the Nth such day. E.g.

+0            => today
.             => today
+4d           => four days from today
+4            => same as above
+2w           => two weeks from today
++5           => five days from default date
+2tue         => second Tuesday from now.

The function understands English month and weekday abbreviations. If you want to use unabbreviated names and/or other languages, configure the variables parse-time-months and parse-time-weekdays.

You can specify a time range by giving start and end times or by giving a start time and a duration (in HH:MM format). Use `-' or `-{}-' as the separator in the former case and use '+' as the separator in the latter case. E.g.

11am-1:15pm    => 11:00-13:15
11am--1:15pm   => same as above
11am+2:15      => same as above

Parallel to the minibuffer prompt, a calendar is popped up.(54) When you exit the date prompt, either by clicking on a date in the calendar, or by pressing RET, the date selected in the calendar will be combined with the information entered at the prompt. You can control the calendar fully from the minibuffer:

RET Choose date at cursor in calendar.
mouse-1 Select date by clicking on it.
S-right/left One day forward/backward.
S-down/up One week forward/backward.
M-S-right/left One month forward/backward.
> / < Scroll calendar forward/backward by one month.
M-v / C-v Scroll calendar forward/backward by 3 months.
The actions of the date/time prompt may seem complex, but I assure you they will grow on you, and you will start getting annoyed by pretty much any other way of entering a date/time out there. To help you understand what is going on, the current interpretation of your input will be displayed live in the minibuffer.(55)
ISBN 9781906966089The Org Mode 7 Reference ManualSee the print edition