diff options
author | Nicolas Goaziou <mail@nicolasgoaziou.fr> | 2016-09-29 22:22:56 +0200 |
---|---|---|
committer | Nicolas Goaziou <mail@nicolasgoaziou.fr> | 2016-09-29 22:22:56 +0200 |
commit | 12196b84726f88d16f273752966a8efbca144188 (patch) | |
tree | 20b5fc2252e74fda3170cedd9e89260b29387c28 | |
parent | 2b22d503e1ee83f3a2681964f9de8405438a6385 (diff) | |
download | org-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.texi | 121 | ||||
-rw-r--r-- | lisp/org-agenda.el | 27 | ||||
-rw-r--r-- | lisp/org-id.el | 5 | ||||
-rw-r--r-- | lisp/org.el | 76 |
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 |