summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorNicolas Goaziou <mail@nicolasgoaziou.fr>2016-09-29 22:22:56 +0200
committerNicolas Goaziou <mail@nicolasgoaziou.fr>2016-09-29 22:22:56 +0200
commit12196b84726f88d16f273752966a8efbca144188 (patch)
tree20b5fc2252e74fda3170cedd9e89260b29387c28
parent2b22d503e1ee83f3a2681964f9de8405438a6385 (diff)
downloadorg-mode-12196b84726f88d16f273752966a8efbca144188.tar.gz
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>
-rw-r--r--doc/org.texi121
-rw-r--r--lisp/org-agenda.el27
-rw-r--r--lisp/org-id.el5
-rw-r--r--lisp/org.el76
4 files changed, 112 insertions, 117 deletions
diff --git a/doc/org.texi b/doc/org.texi
index a32d15e..2b2c561 100644
--- a/doc/org.texi
+++ b/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.
diff --git a/lisp/org-agenda.el b/lisp/org-agenda.el
index 82d62f6..b7bc08f 100644
--- a/lisp/org-agenda.el
+++ b/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)
diff --git a/lisp/org-id.el b/lisp/org-id.el
index 1abbe01..dfb7912 100644
--- a/lisp/org-id.el
+++ b/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")
diff --git a/lisp/org.el b/lisp/org.el
index 8d6f901..2c100c8 100644
--- a/lisp/org.el
+++ b/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