mirror/org-mode
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/emacs/org-mode.git synced 2025-01-23 19:49:32 +00:00
Code

Fix documentation

Browse Source 
* 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>
This commit is contained in:
Nicolas Goaziou 2016-09-29 22:22:56 +02:00
parent 2b22d503e1
commit 12196b8472
4 changed files with 111 additions and 116 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

121
doc/org.texi
View File

@ -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.

25
lisp/org-agenda.el
View File

@ -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)

5
lisp/org-id.el
View File

@ -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")

76
lisp/org.el
View File

@ -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