From 9c6ed406d5add908aac5b73cdfacc2272f2cf89e Mon Sep 17 00:00:00 2001 From: Teika kazura Date: Wed, 12 Nov 2014 17:08:00 +0900 Subject: [PATCH 2/2] org.texi: Timestamp sections. Section "Creating timestamp" is renamed to "Timestamp commands". `org-read-date-minibuffer-local-map' is described. Other contents improvement in that section. Minor whitespace cleanups. --- doc/org.texi | 99 ++++++++++++++++++++++++++++++------------------------------ 1 file changed, 49 insertions(+), 50 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index b01db2c..bfb5b4f 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -458,14 +458,14 @@ Defining columns Dates and times * Timestamps:: Assigning a time to a tree entry -* Creating timestamps:: Commands which insert timestamps +* Timestamp commands:: Commands which insert timestamps * Deadlines and scheduling:: Planning your work * Clocking work time:: Tracking how long you spend on a task * Effort estimates:: Planning work effort in advance * Relative timer:: Notes with a running timer * Countdown timer:: Starting a countdown timer for a task -Creating timestamps +Timestamp commands * The date/time prompt:: How Org mode helps you entering date and time * Custom time format:: Making dates look different @@ -4646,7 +4646,7 @@ and agenda buffer with the @kbd{,} command (@pxref{Agenda commands}). @vindex org-priority-start-cycle-with-default Increase/decrease priority of current headline@footnote{See also the option @code{org-priority-start-cycle-with-default}.}. Note that these keys are -also used to modify timestamps (@pxref{Creating timestamps}). See also +also used to modify timestamps (@pxref{Timestamp commands}). See also @ref{Conflicts}, for a discussion of the interaction with @code{shift-selection-mode}. @end table @@ -5771,7 +5771,7 @@ is used in a much wider sense. @menu * Timestamps:: Assigning a time to a tree entry -* Creating timestamps:: Commands which insert timestamps +* Timestamp commands:: Commands which insert timestamps * Deadlines and scheduling:: Planning your work * Clocking work time:: Tracking how long you spend on a task * Effort estimates:: Planning work effort in advance @@ -5874,14 +5874,18 @@ angular ones. These timestamps are inactive in the sense that they do @end table -@node Creating timestamps -@section Creating timestamps +@node Timestamp commands +@section Timestamp commands @cindex creating timestamps @cindex timestamps, creating +@cindex timestamp commands + +Below are commands to create and handle timestamps. For Org mode to recognize timestamps, they need to be in the specific -format. All commands listed below produce timestamps in the correct -format. +format. All commands listed below automatically fix incomplete existing timestamps. + +Many commands prompt for a date. Details for timestamp prompt will be explained in a later subsection. (@pxref{The date/time prompt}) @table @kbd @orgcmd{C-c .,org-time-stamp} @@ -5919,7 +5923,7 @@ Access the agenda for the date given by the timestamp or -range at point (@pxref{Weekly/daily agenda}). @c @orgcmdkkcc{S-@key{left},S-@key{right},org-timestamp-down-day,org-timestamp-up-day} -Change date at cursor by one day. These key bindings conflict with +Change date at cursor by one day. These key bindings conflict with shift-selection and related modes (@pxref{Conflicts}). @c @orgcmdkkcc{S-@key{up},S-@key{down},org-timestamp-up,org-timestamp-down-down} @@ -5934,12 +5938,11 @@ related modes (@pxref{Conflicts}). @c @orgcmd{C-c C-y,org-evaluate-time-range} @cindex evaluate time range -Evaluate a time range by computing the difference between start and end. +Calculate and show the time range span, e.g. ``1 days 2 hours 34 minutes''. With a prefix argument, insert result after the time range (in a table: into the following column). @end table - @menu * The date/time prompt:: How Org mode helps you entering date and time * Custom time format:: Making dates look different @@ -5951,22 +5954,19 @@ the following column). @cindex time, reading in minibuffer @vindex org-read-date-prefer-future -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 date/time information in a variety of -formats. Generally, the information should start at the beginning of the -string. Org mode will find whatever information is in -there and derive anything you have not specified from the @emph{default date -and time}. The default is usually the current date and time, but when +Date/time prompt is ``smart enough'', accepting shorthand notations, visual input while viewing the calendar, etc. + +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 -@i{before} today, it will assume that you mean a future date@footnote{See the -variable @code{org-read-date-prefer-future}. You may set that variable to -the symbol @code{time} to even make a time before now shift the date to -tomorrow.}. If the date has been automatically shifted into the future, the -time prompt will show this with @samp{(=>F).} +range, it is taken from the stamp in the buffer. + +When filling in lacking 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 @i{before} today, it will assume that you mean a +future date@footnote{See the variable @code{org-read-date-prefer-future}. +You may set that variable to the symbol @code{time} to even make a time +before now shift the date to tomorrow.}. If the date has been automatically +shifted into the future, the time prompt will show this with @samp{(=>F).} For example, let's assume that today is @b{June 13, 2006}. Here is how various inputs will be interpreted, the items filled in by Org mode are @@ -5989,12 +5989,11 @@ w4 @result{} ISO week for of the current year @b{2006} 2012-w04-5 @result{} Same as above @end example -Furthermore you can specify a relative date by giving, as the @emph{first} -thing in the input: a plus/minus sign, a number and a letter ([hdwmy]) to -indicate change in hours, 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.: +Furthermore you can specify a @emph{relative} date: put a plus/minus sign, +followed by a number and a letter [hdwmy] (hour, day, week, month, year). 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.: @example +0 @result{} today @@ -6033,17 +6032,16 @@ case, e.g.: @cindex calendar, for selecting date @vindex org-popup-calendar-for-date-prompt -Parallel to the minibuffer prompt, a calendar is popped up@footnote{If -you don't need/want the calendar, configure the variable -@code{org-popup-calendar-for-date-prompt}.}. When you exit the date -prompt, either by clicking on a date in the calendar, or by pressing -@key{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: +Parallel to the minibuffer prompt, a calendar is popped up@footnote{If you +don't need/want the calendar, configure the variable +@code{org-popup-calendar-for-date-prompt}.}. Calendar-based visual input is +possible, too, and it will be combined with the information entered at the +prompt. You can control the calendar fully from the minibuffer: @kindex < @kindex > @kindex M-v +@kindex C-. @kindex C-v @kindex mouse-1 @kindex S-@key{right} @@ -6054,22 +6052,23 @@ from the minibuffer: @kindex M-S-@key{left} @kindex @key{RET} @example -@key{RET} @r{Choose date at cursor in calendar.} +@key{RET} @r{Choose date at cursor in calendar.} mouse-1 @r{Select date by clicking on it.} S-@key{right}/@key{left} @r{One day forward/backward.} -S-@key{down}/@key{up} @r{One week forward/backward.} +S-@key{down}/@key{up} @r{One week forward/backward.} M-S-@key{right}/@key{left} @r{One month forward/backward.} > / < @r{Scroll calendar forward/backward by one month.} M-v / C-v @r{Scroll calendar forward/backward by 3 months.} +C-. @r{Go to today.} +! @r{Show diary entries. @ref{Displaying the Diary, , Displaying the Diary, emacs, The Emacs Editor}} @end example +@vindex org-read-date-minibuffer-local-map +S- keys conflict with other modes. For the details see @xref{Conflicts}. You can fully customize the key binding with the variable @code{org-read-date-minibuffer-local-map}. + @vindex org-read-date-display-live -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@footnote{If you find this distracting, turn the display off with -@code{org-read-date-display-live}.}. +The interpretation of your input will be shown on-the-fly in the +minibuffer. You can turn it off with the variable @code{org-read-date-display-live}. @node Custom time format @subsection Custom time format @@ -8557,7 +8556,7 @@ be accumulated. You can add a filter preset through the option @orgcmd{_,org-agenda-filter-by-effort} @vindex org-agenda-effort-filter-preset @vindex org-sort-agenda-noeffort-is-high -Filter the agenda view with respect to effort estimates. +Filter the agenda view with respect to effort estimates. You first need to set up allowed efforts globally, for example @lisp (setq org-global-properties @@ -13282,7 +13281,7 @@ equivalent Texinfo code. #+TEXINFO_PRINTED_TITLE: GNU Sample #+SUBTITLE: for version 2.0, last updated 4 March 2014 -* Copying +* Copying :PROPERTIES: :COPYING: t :END: @@ -13938,7 +13937,7 @@ however, override everything. @subsubheading @LaTeX{} specific properties -@multitable {@code{:latex-link-with-unknown-path-format}} {@code{org-latex-link-with-unknown-path-format}} +@multitable {@code{:latex-link-with-unknown-path-format}} {@code{org-latex-link-with-unknown-path-format}} @item @code{:latex-active-timestamp-format} @tab @code{org-latex-active-timestamp-format} @item @code{:latex-caption-above} @tab @code{org-latex-caption-above} @item @code{:latex-classes} @tab @code{org-latex-classes} -- 2.0.4