Fix documentation

* doc/org.texi (Conventions): Remove unhelpful and wrong footnote.
(Initial visibility): Remove spurious paragraph.
(Global and local cycling):
(Motion): Fix function name.
(Plain lists): Reverse prefix argument action.
(Column width and alignment):
(Column groups):
(Tag inheritance):
(Tag hierarchy):
(The date/time prompt): Fix typo
(Link abbreviations):
(Tag searches):
(Timers): Fix wording.
(Checkboxes): Improve accuracy of footnote.  Correctly describe the
behaviour of `org-toggle-checkbox' on a headline.
(Filtering/limiting agenda items): More accurate description for `+' and
`-'.  Also remove unused `\' key.
(Agenda commands): Fix behaviour description.

* lisp/org-agenda.el (org-agenda-filter-by-tag): Fix docstring
  appearance.
(org-agenda-show-and-scroll-up): Fix wording.

* lisp/org-id.el (org-id-link-to-org-use-id): Fix function name.
(org-id-update-id-locations): Remove reference to unused argument.

* lisp/org.el (org-insert-heading): Improve docstring.
(org-insert-todo-heading): Describe behavior on a plain list item.
(org-update-statistics-cookies): Describe behavior when called with
a prefix argument.
(org-metaright): Fix typo.
(org-kill-note-or-show-branches): Fix function name.
(org-yank): Fix wording.

Reported-by: Jorge <jorge13515@gmail.com>
<http://permalink.gmane.org/gmane.emacs.orgmode/109428>

doc/org.texi

@@ -1118,9 +1118,7 @@ special meaning are written with all capitals.
 Moreover, Org uses @i{option keywords} (like @code{#+TITLE} to set the title)
 and @i{environment keywords} (like @code{#+BEGIN_EXPORT html} to start
 a @code{HTML} environment).  They are written in uppercase in the manual to
-enhance its readability, but you can use lowercase in your Org
-files@footnote{Easy templates insert lowercase keywords and Babel dynamically
-inserts @code{#+results}.}.
+enhance its readability, but you can use lowercase in your Org file.
 
 @subsubheading Key bindings and commands
 @kindex C-c a
@@ -1289,7 +1287,7 @@ tables, @kbd{S-@key{TAB}} jumps to the previous field.
 @orgcmd{C-u C-u @key{TAB},org-set-startup-visibility}
 Switch back to the startup visibility of the buffer (@pxref{Initial visibility}).
 @cindex show all, command
-@orgcmd{C-u C-u C-u @key{TAB},show-all}
+@orgcmd{C-u C-u C-u @key{TAB},outline-show-all}
 Show all, including drawers.
 @cindex revealing context
 @orgcmd{C-c C-r,org-reveal}
@@ -1300,10 +1298,10 @@ exposed by a sparse tree command (@pxref{Sparse trees}) or an agenda command
 level, all sibling headings.  With a double prefix argument, also show the
 entire subtree of the parent.
 @cindex show branches, command
-@orgcmd{C-c C-k,show-branches}
+@orgcmd{C-c C-k,outline-show-branches}
 Expose all the headings of the subtree, CONTENT view for just one subtree.
 @cindex show children, command
-@orgcmd{C-c @key{TAB},show-children}
+@orgcmd{C-c @key{TAB},outline-show-children}
 Expose all direct children of the subtree.  With a numeric prefix argument N,
 expose all children down to level N@.
 @orgcmd{C-c C-x b,org-tree-to-indirect-buffer}
@@ -1344,10 +1342,6 @@ following lines anywhere in the buffer:
 #+STARTUP: showeverything
 @end example
 
-The startup visibility options are ignored when the file is open for the
-first time during the agenda generation: if you want the agenda to honor
-the startup visibility, set @code{org-agenda-inhibit-startup} to @code{nil}.
-
 @cindex property, VISIBILITY
 @noindent
 Furthermore, any entries with a @samp{VISIBILITY} property (@pxref{Properties
@@ -1381,9 +1375,9 @@ them.
 The following commands jump to other headlines in the buffer.
 
 @table @asis
-@orgcmd{C-c C-n,outline-next-visible-heading}
+@orgcmd{C-c C-n,org-next-visible-heading}
 Next heading.
-@orgcmd{C-c C-p,outline-previous-visible-heading}
+@orgcmd{C-c C-p,org-previous-visible-heading}
 Previous heading.
 @orgcmd{C-c C-f,org-forward-same-level}
 Next heading same level.
@@ -1798,10 +1792,10 @@ Cycle the entire list level through the different itemize/enumerate bullets
 (@samp{-}, @samp{+}, @samp{*}, @samp{1.}, @samp{1)}) or a subset of them,
 depending on @code{org-plain-list-ordered-item-terminator}, the type of list,
 and its indentation.  With a numeric prefix argument N, select the Nth bullet
-from this list.  If there is an active region when calling this, selected
-text will be changed into an item.  With a prefix argument, all lines will be
-converted to list items.  If the first line already was a list item, any item
-marker will be removed from the list.  Finally, even without an active
+from this list.  If there is an active region when calling this, all selected
+lines are converted to list items.  With a prefix argument, selected text is
+changed into a single item.  If the first line already was a list item, any
+item marker will be removed from the list.  Finally, even without an active
 region, a normal line will be converted into a list item.
 @kindex C-c *
 @item C-c *
@@ -2355,7 +2349,7 @@ on a per-file basis with:
 @end example
 
 If you would like to overrule the automatic alignment of number-rich columns
-to the right and of string-rich column to the left, you can use @samp{<r>},
+to the right and of string-rich columns to the left, you can use @samp{<r>},
 @samp{<c>}@footnote{Centering does not work inside Emacs, but it does have an
 effect when exporting to HTML.} or @samp{<l>} in a similar fashion.  You may
 also combine alignment and field width like this: @samp{<r10>}.
@@ -2367,17 +2361,16 @@ automatically when exporting the document.
 @section Column groups
 @cindex grouping columns in tables
 
-When Org exports tables, it does so by default without vertical
-lines because that is visually more satisfying in general.  Occasionally
-however, vertical lines can be useful to structure a table into groups
-of columns, much like horizontal lines can do for groups of rows.  In
-order to specify column groups, you can use a special row where the
-first field contains only @samp{/}.  The further fields can either
-contain @samp{<} to indicate that this column should start a group,
-@samp{>} to indicate the end of a column, or @samp{<>} (no space between @samp{<}
-and @samp{>}) to make a column
-a group of its own.  Boundaries between column groups will upon export be
-marked with vertical lines.  Here is an example:
+When Org exports tables, it does so by default without vertical lines because
+that is visually more satisfying in general.  Occasionally however, vertical
+lines can be useful to structure a table into groups of columns, much like
+horizontal lines can do for groups of rows.  In order to specify column
+groups, you can use a special row where the first field contains only
+@samp{/}.  The further fields can either contain @samp{<} to indicate that
+this column should start a group, @samp{>} to indicate the end of a group, or
+@samp{<>} (no space between @samp{<} and @samp{>}) to make a column a group
+of its own.  Boundaries between column groups will upon export be marked with
+vertical lines.  Here is an example:
 
 @example
 | N | N^2 | N^3 | N^4 | ~sqrt(n)~ | ~sqrt[4](N)~ |
@@ -3875,8 +3868,8 @@ url-encode the tag (see the example above, where we need to encode
 the URL parameter.)  Using @samp{%(my-function)} will pass the tag
 to a custom function, and replace it by the resulting string.
 
-If the replacement text doesn't contain any specifier, it will simply
-be appended to the string in order to create the link.
+If the replacement text doesn't contain any specifier, the tag will simply be
+appended in order to create the link.
 
 Instead of a string, you may also specify a function that will be
 called with the tag as the only argument to create the link.
@@ -4815,11 +4808,12 @@ off a box while there are unchecked boxes above it.
 
 @table @kbd
 @orgcmd{C-c C-c,org-toggle-checkbox}
-Toggle checkbox status or (with prefix arg) checkbox presence at point.
-With a single prefix argument, add an empty checkbox or remove the current
-one@footnote{@kbd{C-u C-c C-c} on the @emph{first} item of a list with no checkbox
-will add checkboxes to the rest of the list.}.  With a double prefix argument, set it to @samp{[-]}, which is
-considered to be an intermediate state.
+Toggle checkbox status or (with prefix arg) checkbox presence at point.  With
+a single prefix argument, add an empty checkbox or remove the current
+one@footnote{@kbd{C-u C-c C-c} before the @emph{first} bullet in a list with
+no checkbox will add checkboxes to the rest of the list.}.  With a double
+prefix argument, set it to @samp{[-]}, which is considered to be an
+intermediate state.
 @orgcmd{C-c C-x C-b,org-toggle-checkbox}
 Toggle checkbox status or (with prefix arg) checkbox presence at point.  With
 double prefix argument, set it to @samp{[-]}, which is considered to be an
@@ -4830,8 +4824,10 @@ If there is an active region, toggle the first checkbox in the region
 and set all remaining boxes to the same status as the first.  With a prefix
 arg, add or remove the checkbox for all items in the region.
 @item
-If the cursor is in a headline, toggle checkboxes in the region between
-this headline and the next (so @emph{not} the entire subtree).
+If the cursor is in a headline, toggle the state of the first checkbox in the
+region between this headline and the next---so @emph{not} the entire
+subtree---and propagate this new state to all other checkboxes in the same
+area.
 @item
 If there is no active region, just toggle the checkbox at point.
 @end itemize
@@ -4902,11 +4898,11 @@ well.  For example, in the list
 @noindent
 the final heading will have the tags @samp{:work:}, @samp{:boss:},
 @samp{:notes:}, and @samp{:action:} even though the final heading is not
-explicitly marked with those tags.  You can also set tags that all entries in
-a file should inherit just as if these tags were defined in a hypothetical
-level zero that surrounds the entire file.  Use a line like this@footnote{As
-with all these in-buffer settings, pressing @kbd{C-c C-c} activates any
-changes in the line.}:
+explicitly marked with all those tags.  You can also set tags that all
+entries in a file should inherit just as if these tags were defined in
+a hypothetical level zero that surrounds the entire file.  Use a line like
+this@footnote{As with all these in-buffer settings, pressing @kbd{C-c C-c}
+activates any changes in the line.}:
 
 @cindex #+FILETAGS
 @example
@@ -5133,8 +5129,8 @@ One use-case is to create a taxonomy of terms (tags) that can be used to
 classify nodes in a document or set of documents.
 
 When you search for a group tag, it will return matches for all members in
-the group and its subgroup.  In an agenda view, filtering by a group tag will
-display or hide headlines tagged with at least one of the members of the
+the group and its subgroups.  In an agenda view, filtering by a group tag
+will display or hide headlines tagged with at least one of the members of the
 group or any of its subgroups.  This makes tag searches and filters even more
 flexible.
 
@@ -5249,10 +5245,10 @@ only TODO items and force checking subitems (see the option
 These commands all prompt for a match string which allows basic Boolean logic
 like @samp{+boss+urgent-project1}, to find entries with tags @samp{boss} and
 @samp{urgent}, but not @samp{project1}, or @samp{Kathy|Sally} to find entries
-which are tagged, like @samp{Kathy} or @samp{Sally}.  The full syntax of the search
-string is rich and allows also matching against TODO keywords, entry levels
-and properties.  For a complete description with many examples, see
-@ref{Matching tags and properties}.
+tagged as @samp{Kathy} or @samp{Sally}.  The full syntax of the search string
+is rich and allows also matching against TODO keywords, entry levels and
+properties.  For a complete description with many examples, see @ref{Matching
+tags and properties}.
 
 
 @node Properties and columns
@@ -6080,7 +6076,7 @@ feb 15        @result{} @b{2007}-02-15
 sep 12 9      @result{} 2009-09-12
 12:45         @result{} @b{2006}-@b{06}-@b{13} 12:45
 22 sept 0:34  @result{} @b{2006}-09-22 00:34
-w4            @result{} ISO week for of the current year @b{2006}
+w4            @result{} ISO week four of the current year @b{2006}
 2012 w4 fri   @result{} Friday of ISO week 4 in 2012
 2012-w04-5    @result{} Same as above
 @end example
@@ -6911,8 +6907,8 @@ in the active region by a certain amount.  This can be used to fix timer
 strings if the timer was not started at exactly the right moment.
 @orgcmd{C-c C-x ;,org-timer-set-timer}
 Start a countdown timer.  The user is prompted for a duration.
-@code{org-timer-default-timer} sets the default countdown value.  Giving a
-prefix numeric argument overrides this default value.  This command is
+@code{org-timer-default-timer} sets the default countdown value.  Giving
+a numeric prefix argument overrides this default value.  This command is
 available as @kbd{;} in agenda buffers.
 @end table
 
@@ -8590,16 +8586,14 @@ refreshes and more secondary filtering.  The filter is a global property of
 the entire agenda view---in a block agenda, you should only set this in the
 global options section, not in the section of an individual block.}
 
-You will be prompted for a tag selection letter; @key{SPC} will mean any tag at
-all.  Pressing @key{TAB} at that prompt will offer use completion to select a
-tag (including any tags that do not have a selection character).  The command
-then hides all entries that do not contain or inherit this tag.  When called
-with prefix arg, remove the entries that @emph{do} have the tag.  A second
-@kbd{/} at the prompt will turn off the filter and unhide any hidden entries.
-If the first key you press is either @kbd{+} or @kbd{-}, the previous filter
-will be narrowed by requiring or forbidding the selected additional tag.
-Instead of pressing @kbd{+} or @kbd{-} after @kbd{/}, you can also
-immediately use the @kbd{\} command.
+You will be prompted for a tag selection letter; @key{SPC} will mean any tag
+at all.  Pressing @key{TAB} at that prompt will offer use completion to
+select a tag (including any tags that do not have a selection character).
+The command then hides all entries that do not contain or inherit this tag.
+When called with prefix arg, remove the entries that @emph{do} have the tag.
+A second @kbd{/} at the prompt will turn off the filter and unhide any hidden
+entries.  Pressing @kbd{+} or @kbd{-} switches between filtering and
+excluding the next tag.
 
 Org also supports automatic, context-aware tag filtering.  If the variable
 @code{org-agenda-auto-exclude-function} is set to a user-defined function,
@@ -8763,9 +8757,8 @@ Next item: same as next line, but only consider items.
 Previous item: same as previous line, but only consider items.
 @tsubheading{View/Go to Org file}
 @orgcmdkkc{@key{SPC},mouse-3,org-agenda-show-and-scroll-up}
-Display the original location of the item in another window.
-With prefix arg, make sure that the entire entry is made visible in the
-outline, not only the heading.
+Display the original location of the item in another window.  With prefix
+arg, make sure that drawers stay folded.
 @c
 @orgcmd{L,org-agenda-recenter}
 Display original location and recenter that window.

lisp/org-agenda.el

@@ -7468,15 +7468,18 @@ With two prefix arguments, remove the effort filters."
 
 (defun org-agenda-filter-by-tag (arg &optional char exclude)
   "Keep only those lines in the agenda buffer that have a specific tag.
-The tag is selected with its fast selection letter, as
-configured.  With a single \\[universal-argument] prefix ARG,
-exclude the agenda search.  With a double \\[universal-argument]
-prefix ARG, filter the literal tag.  I.e. don't filter on all its
-group members.
-
-A lisp caller can specify CHAR.  EXCLUDE means that the new tag should be
-used to exclude the search - the interactive user can also press `-' or `+'
-to switch between filtering and excluding."
+
+The tag is selected with its fast selection letter, as configured.
+
+With a single \\[universal-argument] prefix ARG, exclude the agenda search.
+
+With a double \\[universal-argument] prefix ARG, filter the literal tag, \
+i.e. don't
+filter on all its group members.
+
+A lisp caller can specify CHAR.  EXCLUDE means that the new tag
+should be used to exclude the search - the interactive user can
+also press `-' or `+' to switch between filtering and excluding."
   (interactive "P")
   (let* ((alist org-tag-alist-for-agenda)
 	 (tag-chars (mapconcat
@@ -8622,9 +8625,9 @@ if it was hidden in the outline."
 (defun org-agenda-show-and-scroll-up (&optional arg)
   "Display the Org file which contains the item at point.
 When called repeatedly, scroll the window that is displaying the buffer.
-With a \\[universal-argument] prefix, use `org-show-entry' instead of
-`show-subtree' to display the item, so that drawers and logbooks stay
-folded."
+With a \\[universal-argument] prefix, use `org-show-entry' instead of \
+`outline-show-subtree'
+to display the item, so that drawers and logbooks stay folded."
   (interactive "P")
   (let ((win (selected-window)))
     (if (and (window-live-p org-agenda-show-window)

lisp/org-id.el

@@ -98,7 +98,7 @@ create-if-interactive
       call `org-capture' that automatically and preemptively creates a
       link.  If you do want to get an ID link in a capture template to
       an entry not having an ID, create it first by explicitly creating
-      a link to it, using `\\[org-insert-link]' first.
+      a link to it, using `\\[org-store-link]' first.
 
 create-if-interactive-and-no-custom-id
       Like create-if-interactive, but do not create an ID if there is
@@ -444,8 +444,7 @@ and time is the usual three-integer representation of time."
 Store the relation between files and corresponding IDs.
 This will scan all agenda files, all associated archives, and all
 files currently mentioned in `org-id-locations'.
-When FILES is given, scan these files instead.
-When CHECK is given, prepare detailed information about duplicate IDs."
+When FILES is given, scan these files instead."
   (interactive)
   (if (not org-id-track-globally)
       (error "Please turn on `org-id-track-globally' if you want to track IDs")

lisp/org.el

@@ -7868,31 +7868,25 @@ If point is at the beginning of a heading or a list item, insert
 a new heading or a new item above the current one.  If point is
 at the beginning of a normal line, turn the line into a heading.
 
-If point is in the middle of a headline or a list item, split the
-headline or the item and create a new headline/item with the text
-in the current line after point \(see `org-M-RET-may-split-line'
-on how to modify this behavior).
+If point is in the middle of a line, split it and create a new
+headline/item with the text in the current line after point (see
+`org-M-RET-may-split-line' on how to modify this behavior).
+
+If point is at the beginning of the headline, insert a sibling
+before it.  If it is at the beginning of a regular line of text,
+turn it into a heading.
 
 With one universal prefix argument, set the user option
-`org-insert-heading-respect-content' to t for the duration of
-the command.  This modifies the behavior described above in this
-ways: on list items and at the beginning of normal lines, force
-the insertion of a heading after the current subtree.
+`org-insert-heading-respect-content' to t for the duration of the
+command.  This modifies the behavior described above in this
+ways: on list items and at regular lines, force the insertion of
+a heading after the current subtree.
 
 With two universal prefix arguments, insert the heading at the
 end of the grandparent subtree.  For example, if point is within
 a 2nd-level heading, then it will insert a 2nd-level heading at
 the end of the 1st-level parent heading.
 
-If point is at the beginning of a headline, insert a sibling
-before the current headline.  If point is not at the beginning,
-split the line and create a new headline with the text in the
-current line after point \(see `org-M-RET-may-split-line' on how
-to modify this behavior).
-
-If point is at the beginning of a normal line, turn this line
-into a heading.
-
 When INVISIBLE-OK is set, stop at invisible headlines when going
 back.  This is important for non-interactive uses of the
 command.
@@ -8156,9 +8150,14 @@ Set it to HEADING when provided."
 
 (defun org-insert-todo-heading (arg &optional force-heading)
   "Insert a new heading with the same level and TODO state as current heading.
-If the heading has no TODO state, or if the state is DONE, use the first
-state (TODO by default).  Also with one prefix arg, force first state.  With
-two prefix args, force inserting at the end of the parent subtree."
+
+If the heading has no TODO state, or if the state is DONE, use
+the first state (TODO by default).  Also with one prefix arg,
+force first state.  With two prefix args, force inserting at the
+end of the parent subtree.
+
+When called at a plain list item, insert a new item with an
+unchecked check box."
   (interactive "P")
   (when (or force-heading (not (org-insert-item 'checkbox)))
     (org-insert-heading (or (and (equal arg '(16)) '(16))
@@ -8167,18 +8166,17 @@ two prefix args, force inserting at the end of the parent subtree."
       (org-back-to-heading)
       (outline-previous-heading)
       (looking-at org-todo-line-regexp))
-    (let*
-        ((new-mark-x
-	  (if (or (equal arg '(4))
-		  (not (match-beginning 2))
-		  (member (match-string 2) org-done-keywords))
- 	      (car org-todo-keywords-1)
-	    (match-string 2)))
-	 (new-mark
-	  (or
-	   (run-hook-with-args-until-success
-	    'org-todo-get-default-hook new-mark-x nil)
-	   new-mark-x)))
+    (let* ((new-mark-x
+	    (if (or (equal arg '(4))
+		    (not (match-beginning 2))
+		    (member (match-string 2) org-done-keywords))
+		(car org-todo-keywords-1)
+	      (match-string 2)))
+	   (new-mark
+	    (or
+	     (run-hook-with-args-until-success
+	      'org-todo-get-default-hook new-mark-x nil)
+	     new-mark-x)))
       (beginning-of-line 1)
       (and (looking-at org-outline-regexp) (goto-char (match-end 0))
 	   (if org-treat-insert-todo-heading-as-state-change
@@ -12903,7 +12901,9 @@ changes because there are unchecked boxes in this entry."
 
 (defun org-update-statistics-cookies (all)
   "Update the statistics cookie, either from TODO or from checkboxes.
-This should be called with the cursor in a line with a statistics cookie."
+This should be called with the cursor in a line with a statistics
+cookie.  When called with a \\[universal-argument] prefix, update
+all statistics cookies in the buffer."
   (interactive "P")
   (if all
       (progn
@@ -20609,7 +20609,7 @@ and returns at first non-nil value."
 In front of a drawer or a block keyword, indent it correctly.
 
 Calls `org-do-demote', `org-indent-item', `org-table-move-column',
-`org-indnet-drawer' or `org-indent-block' depending on context.
+`org-indent-drawer' or `org-indent-block' depending on context.
 With no specific context, calls the Emacs default `forward-word'.
 See the individual commands for more information.
 
@@ -21240,7 +21240,7 @@ Use \\[org-edit-special] to edit table.el tables"))
   (message "%s restarted" major-mode))
 
 (defun org-kill-note-or-show-branches ()
-  "If this is a Note buffer, abort storing the note.  Else call `show-branches'."
+  "Abort storing current note, or call `outline-show-branches'."
   (interactive)
   (if (not org-finish-function)
       (progn
@@ -23883,9 +23883,9 @@ empty headline, then the yank is handled specially.  How exactly depends
 on the value of the following variables.
 
 `org-yank-folded-subtrees'
-    By default, this variable is non-nil, which results in subtree(s)
-    being folded after insertion, but only if doing so would now
-    swallow text after the yanked text.
+    By default, this variable is non-nil, which results in
+    subtree(s) being folded after insertion, except if doing so
+    would swallow text after the yanked text.
 
 `org-yank-adjusted-subtrees'
     When non-nil (the default value is nil), the subtree will be