Merge branch 'maint'

doc/org.texi

@@ -891,7 +891,7 @@ been visited, i.e., where no Org built-in function have been loaded.
 Otherwise autoload Org functions will mess up the installation.
 
 Then, to make sure your Org configuration is taken into account, initialize
-the package system with @code{(package-initialize)} in your @file{.emacs}
+the package system with @code{(package-initialize)} in your Emacs init file
 before setting any Org option.  If you want to use Org's package repository,
 check out the @uref{http://orgmode.org/elpa.html, Org ELPA page}.
 
@@ -899,7 +899,7 @@ check out the @uref{http://orgmode.org/elpa.html, Org ELPA page}.
 
 You can download Org latest release from @uref{http://orgmode.org/, Org's
 website}.  In this case, make sure you set the load-path correctly in your
-@file{.emacs}:
+Emacs init file:
 
 @lisp
 (add-to-list 'load-path "~/path/to/orgdir/lisp")
@@ -1013,8 +1013,8 @@ version of Org available---if you are running an outdated version, it is
 quite possible that the bug has been fixed already.  If the bug persists,
 prepare a report and provide as much information as possible, including the
 version information of Emacs (@kbd{M-x emacs-version @key{RET}}) and Org
-(@kbd{M-x org-version RET}), as well as the Org related setup in
-@file{.emacs}.  The easiest way to do this is to use the command
+(@kbd{M-x org-version RET}), as well as the Org related setup in the Emacs
+init file.  The easiest way to do this is to use the command
 @example
 @kbd{M-x org-submit-bug-report RET}
 @end example
@@ -3645,9 +3645,9 @@ will be stored.  In addition or alternatively (depending on the value of
 be created and/or used to construct a link@footnote{The library
 @file{org-id.el} must first be loaded, either through @code{org-customize} by
 enabling @code{org-id} in @code{org-modules}, or by adding @code{(require
-'org-id)} in your @file{.emacs}.}. So using this command in Org buffers will
-potentially create two links: a human-readable from the custom ID, and one
-that is globally unique and works even if the entry is moved from file to
+'org-id)} in your Emacs init file.}.  So using this command in Org buffers
+will potentially create two links: a human-readable from the custom ID, and
+one that is globally unique and works even if the entry is moved from file to
 file.  Later, when inserting the link, you need to decide which one to use.
 
 @b{Email/News clients: VM, Rmail, Wanderlust, MH-E, Gnus}@*
@@ -4990,10 +4990,10 @@ By default Org mode uses the standard minibuffer completion facilities for
 entering tags.  However, it also implements another, quicker, tag selection
 method called @emph{fast tag selection}.  This allows you to select and
 deselect tags with just a single key press.  For this to work well you should
-assign unique letters to most of your commonly used tags.  You can do this
-globally by configuring the variable @code{org-tag-alist} in your
-@file{.emacs} file.  For example, you may find the need to tag many items in
-different files with @samp{:@@home:}.  In this case you can set something
+assign unique, case-sensitive, letters to most of your commonly used tags.
+You can do this globally by configuring the variable @code{org-tag-alist} in
+your Emacs init file.  For example, you may find the need to tag many items
+in different files with @samp{:@@home:}.  In this case you can set something
 like:
 
 @lisp
@@ -5059,7 +5059,7 @@ have no configured keys.}.  In this interface, you can use the following
 keys:
 
 @table @kbd
-@item a-z...
+@item a-zA-Z...
 Pressing keys assigned to tags will add or remove them from the list of
 tags in the current line.  Selecting a tag in a group of mutually
 exclusive tags will turn off any other tags from that group.
@@ -8231,12 +8231,12 @@ example, the ``property'' @code{TODO} represents the TODO keyword of the
 entry and the ``property'' @code{PRIORITY} represents the PRIORITY keyword of
 the entry.
 
-In addition to the @ref{Special properties}, one other ``property'' can also
-be used. @code{LEVEL} represents the level of an entry.  So a search
-@samp{+LEVEL=3+boss-TODO="DONE"} lists all level three headlines that have
-the tag @samp{boss} and are @emph{not} marked with the TODO keyword DONE@.
-In buffers with @code{org-odd-levels-only} set, @samp{LEVEL} does not count
-the number of stars, but @samp{LEVEL=2} will correspond to 3 stars etc.
+In addition to the properties mentioned above, @code{LEVEL} represents the
+level of an entry.  So a search @samp{+LEVEL=3+boss-TODO="DONE"} lists all
+level three headlines that have the tag @samp{boss} and are @emph{not} marked
+with the TODO keyword DONE@.  In buffers with @code{org-odd-levels-only} set,
+@samp{LEVEL} does not count the number of stars, but @samp{LEVEL=2} will
+correspond to 3 stars etc.
 
 Here are more examples:
 
@@ -9292,7 +9292,7 @@ buffer).
 Custom commands are configured in the variable
 @code{org-agenda-custom-commands}.  You can customize this variable, for
 example by pressing @kbd{C-c a C}.  You can also directly set it with Emacs
-Lisp in @file{.emacs}.  The following example contains all valid agenda
+Lisp in the Emacs init file.  The following example contains all valid agenda
 views:
 
 @lisp
@@ -17355,9 +17355,8 @@ works even if the automatic table editor has been turned off.
 If the cursor is on a @code{#+TBLFM} line, re-apply the formulas to
 the entire table.
 @item
-If the current buffer is a capture buffer, close the note and file it.
-With a prefix argument, file it, without further interaction, to the
-default location.
+If the current buffer is a capture buffer, close the note and file it.  With
+a prefix argument, jump to the target location, without capturing anything.
 @item
 If the cursor is on a @code{<<<target>>>}, update radio targets and
 corresponding links in this buffer.
@@ -17772,8 +17771,8 @@ Any text below a headline that has a @samp{:crypt:} tag will be automatically
 be encrypted when the file is saved.  If you want to use a different tag just
 customize the @code{org-crypt-tag-matcher} setting.
 
-To use org-crypt it is suggested that you have the following in your
-@file{.emacs}:
+To use org-crypt it is suggested that you have the following in your Emacs
+init file:
 
 @lisp
 (require 'org-crypt)
@@ -17896,7 +17895,7 @@ PATH should be a topic that can be thrown at the man command."
 @end lisp
 
 @noindent
-You would activate this new link type in @file{.emacs} with
+You would activate this new link type in Emacs init file with
 
 @lisp
 (require 'org-man)

lisp/org-agenda.el

@@ -769,10 +769,12 @@ to make his option also apply to the tags-todo list."
 
 (defcustom org-agenda-todo-ignore-deadlines nil
   "Non-nil means ignore some deadline TODO items when making TODO list.
+
 There are different motivations for using different values, please think
 carefully when configuring this variable.
 
-This applies when creating the global todo list.
+This applies when creating the global TODO list.
+
 Valid values are:
 
 near    Don't show near deadline entries.  A deadline is near when it is
@@ -780,8 +782,8 @@ near    Don't show near deadline entries.  A deadline is near when it is
         is that such items will appear in the agenda anyway.
 
 far     Don't show TODO entries where a deadline has been defined, but
-        the deadline is not near.  This is useful if you don't want to
-        use the todo list to figure out what to do now.
+        is not going to happen anytime soon.  This is useful if you want to use
+        the TODO list to figure out what to do now.
 
 past    Don't show entries with a deadline timestamp for today or in the past.
 
@@ -1789,7 +1791,8 @@ in every agenda.
 
 When this option is set to t (the default), inherited tags are
 shown when they are available, i.e. when the value of
-`org-agenda-use-tag-inheritance' has been taken into account.
+`org-agenda-use-tag-inheritance' enables tag inheritance for the
+given agenda type.
 
 This can be set to a list of agenda types in which the agenda
 must display the inherited tags.  Available types are `todo',
@@ -7980,41 +7983,48 @@ With prefix ARG, go backward that many times the current span."
   "Switch to default view for agenda."
   (interactive)
   (org-agenda-change-time-span org-agenda-span))
+
 (defun org-agenda-day-view (&optional day-of-month)
   "Switch to daily view for agenda.
 With argument DAY-OF-MONTH, switch to that day of the month."
   (interactive "P")
   (org-agenda-change-time-span 'day day-of-month))
+
 (defun org-agenda-week-view (&optional iso-week)
-  "Switch to daily view for agenda.
+  "Switch to weekly view for agenda.
 With argument ISO-WEEK, switch to the corresponding ISO week.
-If ISO-WEEK has more then 2 digits, only the last two encode the
-week.  Any digits before this encode a year.  So 200712 means
-week 12 of year 2007.  Years in the range 1938-2037 can also be
-written as 2-digit years."
+If ISO-WEEK has more then 2 digits, only the last two encode
+the week.  Any digits before this encode a year.  So 200712
+means week 12 of year 2007.  Years ranging from 70 years ago
+to 30 years in the future can also be written as 2-digit years."
   (interactive "P")
   (org-agenda-change-time-span 'week iso-week))
+
 (defun org-agenda-fortnight-view (&optional iso-week)
-  "Switch to daily view for agenda.
+  "Switch to fortnightly view for agenda.
 With argument ISO-WEEK, switch to the corresponding ISO week.
-If ISO-WEEK has more then 2 digits, only the last two encode the
-week.  Any digits before this encode a year.  So 200712 means
-week 12 of year 2007.  Years in the range 1938-2037 can also be
-written as 2-digit years."
+If ISO-WEEK has more then 2 digits, only the last two encode
+the week.  Any digits before this encode a year.  So 200712
+means week 12 of year 2007.  Years ranging from 70 years ago
+to 30 years in the future can also be written as 2-digit years."
   (interactive "P")
   (org-agenda-change-time-span 'fortnight iso-week))
+
 (defun org-agenda-month-view (&optional month)
   "Switch to monthly view for agenda.
-With argument MONTH, switch to that month."
+With argument MONTH, switch to that month.  If MONTH has more
+then 2 digits, only the last two encode the month.  Any digits
+before this encode a year.  So 200712 means December year 2007.
+Years ranging from 70 years ago to 30 years in the future can
+also be written as 2-digit years."
   (interactive "P")
   (org-agenda-change-time-span 'month month))
+
 (defun org-agenda-year-view (&optional year)
   "Switch to yearly view for agenda.
-With argument YEAR, switch to that year.
-If MONTH has more then 2 digits, only the last two encode the
-month.  Any digits before this encode a year.  So 200712 means
-December year 2007.  Years in the range 1938-2037 can also be
-written as 2-digit years."
+With argument YEAR, switch to that year.  Years ranging from 70
+years ago to 30 years in the future can also be written as
+2-digit years."
   (interactive "P")
   (when year
     (setq year (org-small-year-to-year year)))

lisp/org-archive.el

@@ -395,9 +395,12 @@ this heading."
 ;;;###autoload
 (defun org-archive-to-archive-sibling ()
   "Archive the current heading by moving it under the archive sibling.
+
 The archive sibling is a sibling of the heading with the heading name
 `org-archive-sibling-heading' and an `org-archive-tag' tag.  If this
-sibling does not exist, it will be created at the end of the subtree."
+sibling does not exist, it will be created at the end of the subtree.
+
+Archiving time is retained in the ARCHIVE_TIME node property."
   (interactive)
   (if (and (org-region-active-p) org-loop-over-headlines-in-active-region)
       (let ((cl (when (eq org-loop-over-headlines-in-active-region 'start-level)

lisp/org-capture.el

@@ -133,7 +133,7 @@ target       Specification of where the captured item should be placed.
              (file \"path/to/file\")
                  Text will be placed at the beginning or end of that file
 
-             (id \"id of existing org entry\")
+             (id \"id of existing Org entry\")
                  File as child of this entry, or in the body of the entry
 
              (file+headline \"path/to/file\" \"node headline\")

lisp/org-table.el

@@ -563,6 +563,7 @@ SIZE is a string Columns x Rows like for example \"3x2\"."
 ;;;###autoload
 (defun org-table-convert-region (beg0 end0 &optional separator)
   "Convert region to a table.
+
 The region goes from BEG0 to END0, but these borders will be moved
 slightly, to make sure a beginning of line in the first line is included.
 
@@ -572,7 +573,7 @@ following values:
 (4)     Use the comma as a field separator
 (16)    Use a TAB as field separator
 (64)    Prompt for a regular expression as field separator
-integer  When a number, use that many spaces as field separator
+integer  When a number, use that many spaces, or a TAB, as field separator
 regexp   When a regular expression, use it to match the separator
 nil      When nil, the command tries to be smart and figure out the
          separator in the following way:

lisp/org.el

@@ -923,6 +923,7 @@ already archived entries."
 
 (defcustom org-startup-folded t
   "Non-nil means entering Org mode will switch to OVERVIEW.
+
 This can also be configured on a per-file basis by adding one of
 the following lines anywhere in the buffer:
 
@@ -931,9 +932,8 @@ the following lines anywhere in the buffer:
    #+STARTUP: content
    #+STARTUP: showeverything
 
-By default, this option is ignored when Org opens agenda files
-for the first time.  If you want the agenda to honor the startup
-option, set `org-agenda-inhibit-startup' to nil."
+Set `org-agenda-inhibit-startup' to a non-nil value so as to
+ignore this option when Org opens agenda files for the first time."
   :group 'org-startup
   :type '(choice
 	  (const :tag "nofold: show all" nil)
@@ -3546,12 +3546,12 @@ The value of this variable is an alist.  Associations either:
   (TAG . SELECT)
   (SPECIAL)
 
-where TAG is a tag as a string, SELECT is a character, used to
-select that tag through the fast tag selection interface, and
-SPECIAL is one of the following keywords: `:startgroup',
-`:startgrouptag', `:grouptags', `:engroup', `:endgrouptag' or
-`:newline'.  These keywords are used to define a hierarchy of
-tags.  See manual for details.
+where TAG is a tag as a string, SELECT is a case-sensitive
+letter, used to select that tag through the fast tag selection
+interface, and SPECIAL is one of the following keywords:
+`:startgroup', `:startgrouptag', `:grouptags', `:engroup',
+`:endgrouptag' or `:newline'.  These keywords are used to define
+a hierarchy of tags.  See manual for details.
 
 When this variable is nil, Org mode bases tag input on what is
 already in the buffer.  The value can be overridden locally by
@@ -14505,10 +14505,14 @@ headlines matching this string."
 
 (defun org-match-sparse-tree (&optional todo-only match)
   "Create a sparse tree according to tags string MATCH.
-MATCH can contain positive and negative selection of tags, like
-\"+WORK+URGENT-WITHBOSS\".
-If optional argument TODO-ONLY is non-nil, only select lines that are
-also TODO lines."
+
+MATCH is a string with match syntax.  It can contain a selection
+of tags (\"+work+urgent-boss\"), properties (\"LEVEL>3\"), and
+TODO keywords (\"TODO=\\\"WAITING\\\"\") or a combination of
+those.  See the manual for details.
+
+If optional argument TODO-ONLY is non-nil, only select lines that
+are also TODO tasks."
   (interactive "P")
   (org-agenda-prepare-buffers (list (current-buffer)))
   (let ((org--matcher-tags-todo-only todo-only))