* Org Mode Documentation Patch
@ 2018-06-22 16:08 Ben Phipathananunth
2018-06-22 18:14 ` Eli Zaretskii
0 siblings, 1 reply; 9+ messages in thread
From: Ben Phipathananunth @ 2018-06-22 16:08 UTC (permalink / raw)
To: emacs-devel
[-- Attachment #1: Type: text/plain, Size: 1440 bytes --]
I've begun reading the Org Mode manual, and noticed that the wording
in some places could be improved (so far I've read up to Section 4.8).
I've attached my patch. Some of the more drastic changes:
- Changed all occurrences of "the cursor" to "point", I thought the
inconsistency was confusing, especially since the Emacs manual
maintains usage of "point" throughout, so too should the Org Mode
manual.
I have a couple of questions regarding the Org Mode manual and
submitting patches:
Section 4.6 "Link abbreviations" in the Org Mode manual link to
websites that have and/or promote non-free software. The URLs are
used to illustrate link abbreviations in Org Mode, but I suppose this
was purely coincidental because long URLs to websites such as
gnu.org/some/long/path could be used instead. Would it be appropriate
to change the examples in a later patch?
When the PDF version of the Org Mode manual is generated with "make
docs", the footnotes (3 and 4) around Section 4.3 are incorrectly
indented, can anyone reproduce this? What is causing it?
Should I submit my patches as smaller ones as I read sections of the
manual or bulk them together into a larger patch, or is it just a
matter of preference?
Please let me know if you have any comments about the patch. It's my
first one, I hope I have followed the CONTRIBUTING guide properly.
Thanks!
--
Siraphob (Ben) Phipathananunth
[-- Attachment #2: 0001-Fix-various-grammatical-errors-and-terminology.patch --]
[-- Type: application/octet-stream, Size: 53012 bytes --]
From d3145b9e4f0bc18a638d0fb436ceb68ab694e53c Mon Sep 17 00:00:00 2001
From: Ben Phipathananunth <bensiraphob@hotmail.co.uk>
Date: Fri, 22 Jun 2018 22:58:27 +0700
Subject: [PATCH] Fix various grammatical errors and terminology.
---
doc/misc/org.texi | 372 +++++++++++++++++++++++-----------------------
1 file changed, 187 insertions(+), 185 deletions(-)
diff --git a/doc/misc/org.texi b/doc/misc/org.texi
index 3bce0dd736..328db319a3 100644
--- a/doc/misc/org.texi
+++ b/doc/misc/org.texi
@@ -990,7 +990,7 @@ Activation
use of this, you need to have @code{transient-mark-mode} turned on, which is
the default. If you do not like @code{transient-mark-mode}, you can create
an active region by using the mouse to select a region, or pressing
-@kbd{C-@key{SPC}} twice before moving the cursor.
+@kbd{C-@key{SPC}} twice before moving point.
@node Feedback
@section Feedback
@@ -1257,7 +1257,7 @@ Global and local cycling
@end example
@vindex org-cycle-emulate-tab
-The cursor must be on a headline for this to work@footnote{see, however,
+Point must be on a headline for this to work@footnote{see, however,
the option @code{org-cycle-emulate-tab}.}.
@cindex global visibility states
@@ -1538,9 +1538,8 @@ Structure editing
demotion work on all headlines in the region. To select a region of
headlines, it is best to place both point and mark at the beginning of a
line, mark at the beginning of the first headline, and point at the line
-just after the last headline to change. Note that when the cursor is
-inside a table (@pxref{Tables}), the Meta-Cursor keys have different
-functionality.
+just after the last headline to change. Note that when point is inside a
+table (@pxref{Tables}), the Meta-Cursor keys have different functionality.
@node Sparse trees
@@ -1697,24 +1696,24 @@ Plain lists
@code{org-list-indent-offset}.
@vindex org-list-automatic-rules
-The following commands act on items when the cursor is in the first line of
-an item (the line with the bullet or number). Some of them imply the
+The following commands act on items when point is in the first line of an
+item (the line with the bullet or number). Some of them imply the
application of automatic rules to keep list structure intact. If some of
-these actions get in your way, configure @code{org-list-automatic-rules}
-to disable them individually.
+these actions get in your way, configure @code{org-list-automatic-rules} to
+disable them individually.
@table @asis
@orgcmd{@key{TAB},org-cycle}
@cindex cycling, in plain lists
@vindex org-cycle-include-plain-lists
Items can be folded just like headline levels. Normally this works only if
-the cursor is on a plain list item. For more details, see the variable
+point is on a plain list item. For more details, see the variable
@code{org-cycle-include-plain-lists}. If this variable is set to
@code{integrate}, plain list items will be treated like low-level
headlines. The level of an item is then given by the indentation of the
-bullet/number. Items are always subordinate to real headlines, however; the
-hierarchies remain completely separated. In a new item with no text yet, the
-first @key{TAB} demotes the item to become a child of the previous
+bullet/number. Items are always subordinate to real headlines, however;
+the hierarchies remain completely separated. In a new item with no text
+yet, the first @key{TAB} demotes the item to become a child of the previous
one. Subsequent @key{TAB}s move the item to meaningful levels in the list
and eventually get it back to its initial position.
@orgcmd{M-@key{RET},org-insert-heading}
@@ -1803,7 +1802,7 @@ Plain lists
@kindex S-RIGHT
@item S-@key{LEFT}/@key{RIGHT}
@vindex org-support-shift-select
-This command also cycles bullet styles when the cursor in on the bullet or
+This command also cycles bullet styles when point is on the bullet or
anywhere in an item line, details depending on
@code{org-support-shift-select}.
@kindex C-c ^
@@ -1844,15 +1843,15 @@ Drawers
intercept @kbd{M-@key{TAB}} to switch windows. Use @kbd{C-M-i} or
@kbd{@key{ESC} @key{TAB}} instead for completion (@pxref{Completion}).}.
-Visibility cycling (@pxref{Visibility cycling}) on the headline will hide and
-show the entry, but keep the drawer collapsed to a single line. In order to
-look inside the drawer, you need to move the cursor to the drawer line and
-press @key{TAB} there. Org mode uses the @code{PROPERTIES} drawer for
-storing properties (@pxref{Properties and columns}), and you can also arrange
-for state change notes (@pxref{Tracking TODO state changes}) and clock times
-(@pxref{Clocking work time}) to be stored in a drawer @code{LOGBOOK}. If you
-want to store a quick note in the LOGBOOK drawer, in a similar way to state
-changes, use
+Visibility cycling (@pxref{Visibility cycling}) on the headline will hide
+and show the entry, but keep the drawer collapsed to a single line. In
+order to look inside the drawer, you need to move point to the drawer line
+and press @key{TAB} there. Org mode uses the @code{PROPERTIES} drawer for
+storing properties (@pxref{Properties and columns}), and you can also
+arrange for state change notes (@pxref{Tracking TODO state changes}) and
+clock times (@pxref{Clocking work time}) to be stored in a drawer
+@code{LOGBOOK}. If you want to store a quick note in the LOGBOOK drawer,
+in a similar way to state changes, use
@table @kbd
@kindex C-c C-z
@@ -1933,7 +1932,7 @@ Footnotes
@item C-c C-x f
The footnote action command.
-When the cursor is on a footnote reference, jump to the definition. When it
+When point is on a footnote reference, jump to the definition. When it
is at a definition, jump to the (first) reference.
@vindex org-footnote-define-inline
@@ -1972,7 +1971,7 @@ Footnotes
@kindex C-c C-c
@item C-c C-c
-If the cursor is on a footnote reference, jump to the definition. If it is a
+If point is on a footnote reference, jump to the definition. If it is a
the definition, jump back to the reference. When called at a footnote
location with a prefix argument, offer the same menu as @kbd{C-c C-x f}.
@kindex C-c C-o
@@ -2007,10 +2006,10 @@ Orgstruct mode
(add-hook 'message-mode-hook 'turn-on-orgstruct++)
@end lisp
-When this mode is active and the cursor is on a line that looks to Org like a
+When this mode is active and point is on a line that looks to Org like a
headline or the first line of a list item, most structure editing commands
-will work, even if the same keys normally have different functionality in the
-major mode you are using. If the cursor is not in one of those special
+will work, even if the same keys normally have different functionality in
+the major mode you are using. If point is not in one of those special
lines, Orgstruct mode lurks silently in the shadows.
When you use @code{orgstruct++-mode}, Org will also export indentation and
@@ -2106,12 +2105,12 @@ Built-in table editor
@kbd{C-c @key{RET}}.
@vindex org-table-auto-blank-field
-When typing text into a field, Org treats @key{DEL}, @key{Backspace}, and all
-character keys in a special way, so that inserting and deleting avoids
-shifting other fields. Also, when typing @emph{immediately after the cursor
-was moved into a new field with @kbd{@key{TAB}}, @kbd{S-@key{TAB}} or
-@kbd{@key{RET}}}, the field is automatically made blank. If this behavior is
-too unpredictable for you, configure the option
+When typing text into a field, Org treats @key{DEL}, @key{Backspace}, and
+all character keys in a special way, so that inserting and deleting avoids
+shifting other fields. Also, when typing @emph{immediately after point was
+moved into a new field with @kbd{@key{TAB}}, @kbd{S-@key{TAB}} or
+@kbd{@key{RET}}}, the field is automatically made blank. If this behavior
+is too unpredictable for you, configure the option
@code{org-table-auto-blank-field}.
@table @kbd
@@ -2162,7 +2161,7 @@ Built-in table editor
Kill the current column.
@c
@orgcmd{M-S-@key{RIGHT},org-table-insert-column}
-Insert a new column to the left of the cursor position.
+Insert a new column to the left of point.
@c
@orgcmdkkcc{M-@key{UP},M-@key{DOWN},org-table-move-row-up,org-table-move-row-down}
Move the current row up/down.
@@ -2179,7 +2178,7 @@ Built-in table editor
is created above the current line.
@c
@orgcmd{C-c @key{RET},org-table-hline-and-move}
-Insert a horizontal line below current row, and move the cursor into the row
+Insert a horizontal line below current row, and move point into the row
below that line.
@c
@orgcmd{C-c ^,org-table-sort-lines}
@@ -2213,11 +2212,11 @@ Built-in table editor
lines.
@c
@orgcmd{M-@key{RET},org-table-wrap-region}
-Split the current field at the cursor position and move the rest to the line
-below. If there is an active region, and both point and mark are in the same
-column, the text in the column is wrapped to minimum width for the given
-number of lines. A numeric prefix argument may be used to change the number
-of desired lines. If there is no region, but you specify a prefix argument,
+Split the current field at point and move the rest to the line below. If
+there is an active region, and both point and mark are in the same column,
+the text in the column is wrapped to minimum width for the given number of
+lines. A numeric prefix argument may be used to change the number of
+desired lines. If there is no region, but you specify a prefix argument,
the current field is made blank, and the content is appended to the field
above.
@@ -2244,13 +2243,13 @@ Built-in table editor
@tsubheading{Miscellaneous}
@orgcmd{C-c `,org-table-edit-field}
-Edit the current field in a separate window. This is useful for fields that
-are not fully visible (@pxref{Column width and alignment}). When called with
-a @kbd{C-u} prefix, just make the full field visible, so that it can be
-edited in place. When called with two @kbd{C-u} prefixes, make the editor
-window follow the cursor through the table and always show the current
-field. The follow mode exits automatically when the cursor leaves the table,
-or when you repeat this command with @kbd{C-u C-u C-c `}.
+Edit the current field in a separate window. This is useful for fields
+that are not fully visible (@pxref{Column width and alignment}). When
+called with a @kbd{C-u} prefix, just make the full field visible, so that
+it can be edited in place. When called with two @kbd{C-u} prefixes, make
+the editor window follow point through the table and always show the
+current field. The follow mode exits automatically when point leaves the
+table, or when you repeat this command with @kbd{C-u C-u C-c `}.
@c
@item M-x org-table-import @key{RET}
Import a file as a table. The table should be TAB or whitespace
@@ -2750,7 +2749,7 @@ Formula syntax for Lisp
you provide the @samp{N} mode switch, all referenced elements will be numbers
(non-number fields will be zero) and interpolated as Lisp numbers, without
quotes. If you provide the @samp{L} flag, all fields will be interpolated
-literally, without quotes. I.e., if you want a reference to be interpreted
+literally, without quotes. For example, if you want a reference to be interpreted
as a string by the Lisp form, enclose the reference operator itself in
double-quotes, like @code{"$3"}. Ranges are inserted as space-separated
fields, so you can embed them in list or vector syntax.
@@ -2811,7 +2810,7 @@ Field and range formulas
To assign a formula to a particular field, type it directly into the field,
preceded by @samp{:=}, for example @samp{:=vsum(@@II..III)}. When you press
-@key{TAB} or @key{RET} or @kbd{C-c C-c} with the cursor still in the field,
+@key{TAB} or @key{RET} or @kbd{C-c C-c} with point still in the field,
the formula will be stored as the formula for this field, evaluated, and the
current field will be replaced with the result.
@@ -2824,9 +2823,9 @@ Field and range formulas
modified in order to still reference the same field. To avoid this, in
particular in range references, anchor ranges at the table borders (using
@code{@@<}, @code{@@>}, @code{$<}, @code{$>}), or at hlines using the
-@code{@@I} notation. Automatic adaptation of field references does of course
+@code{@@I} notation. Automatic adaptation of field references does
not happen if you edit the table structure with normal editing
-commands---then you must fix the equations yourself.
+commands---you must fix the formulas yourself.
Instead of typing an equation into the field, you may also use the following
command
@@ -2876,9 +2875,9 @@ Column formulas
To assign a formula to a column, type it directly into any field in the
column, preceded by an equal sign, like @samp{=$1+$2}. When you press
-@key{TAB} or @key{RET} or @kbd{C-c C-c} with the cursor still in the field,
-the formula will be stored as the formula for the current column, evaluated
-and the current field replaced with the result. If the field contains only
+@key{TAB} or @key{RET} or @kbd{C-c C-c} with point still in the field, the
+formula will be stored as the formula for the current column, evaluated and
+the current field replaced with the result. If the field contains only
@samp{=}, the previously stored formula for this column is used. For each
column, Org will only remember the most recently used formula. In the
@code{#+TBLFM:} line, column formulas will look like @samp{$4=$1+$2}. The
@@ -2965,7 +2964,7 @@ Editing and debugging formulas
minibuffer is that you can use the command @kbd{C-c ?}.
@orgcmd{C-c ?,org-table-field-info}
While editing a formula in a table field, highlight the field(s)
-referenced by the reference at the cursor position in the formula.
+referenced by the reference at point in the formula.
@kindex C-c @}
@findex org-table-toggle-coordinate-overlays
@item C-c @}
@@ -2980,9 +2979,9 @@ Editing and debugging formulas
@orgcmd{C-c ',org-table-edit-formulas}
Edit all formulas for the current table in a special buffer, where the
formulas will be displayed one per line. If the current field has an
-active formula, the cursor in the formula editor will mark it.
+active formula, point in the formula editor will mark it.
While inside the special buffer, Org will automatically highlight
-any field or range reference at the cursor position. You may edit,
+any field or range reference at point. You may edit,
remove and add formulas, and use the following commands:
@table @kbd
@@ -3045,7 +3044,7 @@ Editing and debugging formulas
@cindex @code{#+TBLFM}, switching
@kindex C-c C-c
-You may apply the formula temporarily. This is useful when you
+You may apply the formula temporarily. This is useful when you want to
switch the formula. Place multiple @code{#+TBLFM} lines right
after the table, and then press @kbd{C-c C-c} on the formula to
apply. Here is an example:
@@ -3073,7 +3072,7 @@ Editing and debugging formulas
@noindent
Note: If you recalculate this table (with @kbd{C-u C-c *}, for example), you
-will get the following result of applying only the first @code{#+TBLFM} line.
+will get the following result from applying only the first @code{#+TBLFM} line.
@example
| x | y |
@@ -3135,10 +3134,10 @@ Advanced features
@subsection Advanced features
If you want the recalculation of fields to happen automatically, or if you
-want to be able to assign @i{names}@footnote{Such names must start by an
-alphabetic character and use only alphanumeric/underscore characters.} to
-fields and columns, you need to reserve the first column of the table for
-special marking characters.
+want to be able to assign @i{names}@footnote{Such names must start with an
+alphabetic character and consist solely of alphanumeric or underscore
+characters.} to fields and columns, you need to reserve the first column of
+the table for special marking characters.
@table @kbd
@orgcmd{C-#,org-table-rotate-recalc-marks}
@@ -3329,7 +3328,7 @@ Org-Plot
@subheading ASCII bar plots
-While the cursor is on a column, typing @kbd{C-c " a} or
+While point is on a column, typing @kbd{C-c " a} or
@kbd{M-x orgtbl-ascii-plot @key{RET}} create a new column containing an
ASCII-art bars plot. The plot is implemented through a regular column
formula. When the source column changes, the bar plot may be updated by
@@ -3372,7 +3371,7 @@ Hyperlinks
@chapter Hyperlinks
@cindex hyperlinks
-Like HTML, Org provides links inside a file, external links to
+Like HTML, Org provides support for links inside a file, external links to
other files, Usenet articles, emails, and much more.
@menu
@@ -3409,7 +3408,7 @@ Link format
edit also the invisible @samp{link} part, use @kbd{C-c C-l} with the
cursor on the link.
-If you place the cursor at the beginning or just behind the end of the
+If you place point at the beginning or just behind the end of the
displayed text and press @key{BACKSPACE}, you will remove the
(invisible) bracket at that location. This makes the link incomplete
and the internals are again displayed as plain text. Inserting the
@@ -3424,16 +3423,16 @@ Internal links
@cindex targets, for links
@cindex property, @code{CUSTOM_ID}
-If the link does not look like a URL, it is considered to be internal in the
-current file. The most important case is a link like
+If the link does not look like a URL, it is considered to be internal to
+the current file. The most important case is a link like
@samp{[[#my-custom-id]]} which will link to the entry with the
-@code{CUSTOM_ID} property @samp{my-custom-id}. You are responsible yourself
-to make sure these custom IDs are unique in a file.
+@code{CUSTOM_ID} property @samp{my-custom-id}. It is up to you to make
+sure these custom IDs are unique in a file.
Links such as @samp{[[My Target]]} or @samp{[[My Target][Find my target]]}
lead to a text search in the current file.
-The link can be followed with @kbd{C-c C-o} when the cursor is on the link,
+The link can be followed with @kbd{C-c C-o} when point is on the link,
or with a mouse click (@pxref{Handling links}). Links to custom IDs will
point to the corresponding headline. The preferred match for a text link is
a @i{dedicated target}: the same string in double angular brackets, like
@@ -3462,7 +3461,7 @@ Internal links
During export, internal links will be used to mark objects and assign them
a number. Marked objects will then be referenced by links pointing to them.
In particular, links without a description will appear as the number assigned
-to the marked object@footnote{When targeting a @code{#+NAME} keyword,
+to the marked object@footnote{When targeting a @code{#+NAME} keyword, the
@code{#+CAPTION} keyword is mandatory in order to get proper numbering
(@pxref{Images and tables}).}. In the following excerpt from an Org buffer
@@ -3569,7 +3568,7 @@ External links
@cindex VM links
@cindex WANDERLUST links
-On top of these built-in link types, some are available through the
+On top of these built-in link types, additional ones are available through the
@code{contrib/} directory (@pxref{Installation}). For example, these links
to VM or Wanderlust messages are available when you load the corresponding
libraries from the @code{contrib/} directory:
@@ -3584,7 +3583,7 @@ External links
wl:folder#id @r{WANDERLUST message link}
@end example
-For customizing Org to add new link types @ref{Adding hyperlink types}.
+For more on customizing Org to add new link types see @ref{Adding hyperlink types}.
A link should be enclosed in double brackets and may contain a descriptive
text to be displayed instead of the URL (@pxref{Link format}), for example:
@@ -3596,7 +3595,7 @@ External links
@noindent
If the description is a file name or URL that points to an image, HTML
export (@pxref{HTML export}) will inline the image as a clickable
-button. If there is no description at all and the link points to an
+button. If there is no description and the link points to an
image,
that image will be inlined into the exported HTML file.
@@ -3605,7 +3604,7 @@ External links
Org also finds external links in the normal text and activates them
as links. If spaces must be part of the link (for example in
@samp{bbdb:Richard Stallman}), or if you need to remove ambiguities
-about the end of the link, enclose them in square brackets.
+about the end of the link, enclose the link in square brackets.
@node Handling links
@section Handling links
@@ -3620,11 +3619,11 @@ Handling links
Store a link to the current location. This is a @emph{global} command (you
must create the key binding yourself) which can be used in any buffer to
create a link. The link will be stored for later insertion into an Org
-buffer (see below). What kind of link will be created depends on the current
-buffer:
+buffer (see below). The kind of link that will be created depends on the
+current buffer:
@b{Org mode buffers}@*
-For Org files, if there is a @samp{<<target>>} at the cursor, the link points
+For Org files, if there is a @samp{<<target>>} at point, the link points
to the target. Otherwise it points to the current headline, which will also
be the description@footnote{If the headline contains a timestamp, it will be
removed from the link and result in a wrong link---you should avoid putting
@@ -3634,23 +3633,24 @@ Handling links
@cindex property, @code{CUSTOM_ID}
@cindex property, @code{ID}
If the headline has a @code{CUSTOM_ID} property, a link to this custom ID
-will be stored. In addition or alternatively (depending on the value of
-@code{org-id-link-to-org-use-id}), a globally unique @code{ID} property will
-be created and/or used to construct a link@footnote{The library
-@file{org-id.el} must first be loaded, either through @code{org-customize} by
-enabling @code{org-id} in @code{org-modules}, or by adding @code{(require
-'org-id)} in your Emacs init file.}. So using this command in Org buffers
-will potentially create two links: a human-readable from the custom ID, and
-one that is globally unique and works even if the entry is moved from file to
-file. Later, when inserting the link, you need to decide which one to use.
+will be stored. Depending on the value of
+@code{org-id-link-to-org-use-id}), a globally unique @code{ID} property
+will be created and/or used to construct a link@footnote{The library
+@file{org-id.el} must first be loaded, either through @code{org-customize}
+by enabling @code{org-id} in @code{org-modules}, or by adding
+@code{(require 'org-id)} in your Emacs init file.}. So using this command
+in Org buffers will potentially create two links: a human-readable from the
+custom ID, and one that is globally unique and works even if the entry is
+moved from file to file. Later, when inserting the link, you need to
+decide which one to use.
@b{Email/News clients: VM, Rmail, Wanderlust, MH-E, Gnus}@*
Pretty much all Emacs mail clients are supported. The link will point to the
current article, or, in some GNUS buffers, to the group. The description is
constructed from the author and the subject.
-@b{Web browsers: Eww, W3 and W3M}@*
-Here the link will be the current URL, with the page title as description.
+@b{Web browsers: EWW, W3 and W3M}@*
+Here the link will be the current URL, with the page title as the description.
@b{Contacts: BBDB}@*
Links created in a BBDB buffer will point to the current entry.
@@ -3666,13 +3666,12 @@ Handling links
For any other files, the link will point to the file, with a search string
(@pxref{Search options}) pointing to the contents of the current line. If
there is an active region, the selected words will form the basis of the
-search string. If the automatically created link is not working correctly or
-accurately enough, you can write custom functions to select the search string
+search string. You can write custom Lisp functions to select the search string
and to do the search for particular file types---see @ref{Custom searches}.
The key binding @kbd{C-c l} is only a suggestion---see @ref{Installation}.
@b{Agenda view}@*
-When the cursor is in an agenda view, the created link points to the
+When point is in an agenda view, the created link points to the
entry referenced by the current line.
@c
@@ -3684,17 +3683,18 @@ Handling links
@vindex org-link-parameters
Insert a link@footnote{Note that you don't have to use this command to
insert a link. Links in Org are plain text, and you can type or paste them
-straight into the buffer. By using this command, the links are automatically
-enclosed in double brackets, and you will be asked for the optional
-descriptive text.}. This prompts for a link to be inserted into the buffer.
-You can just type a link, using text for an internal link, or one of the link
-type prefixes mentioned in the examples above. The link will be inserted
-into the buffer@footnote{After insertion of a stored link, the link will be
-removed from the list of stored links. To keep it in the list later use, use
-a triple @kbd{C-u} prefix argument to @kbd{C-c C-l}, or configure the option
-@code{org-keep-stored-link-after-insertion}.}, along with a descriptive text.
-If some text was selected when this command is called, the selected text
-becomes the default description.
+straight into the buffer. By using this command, the links are
+automatically enclosed in double brackets, and you will be asked for the
+optional descriptive text.}. This prompts for a link to be inserted into
+the buffer. You can just type a link, using text for an internal link, or
+one of the link type prefixes mentioned in the examples above. The link
+will be inserted into the buffer@footnote{After insertion of a stored link,
+the link will be removed from the list of stored links. To keep it in the
+list for later use, use a triple @kbd{C-u} prefix argument to @kbd{C-c
+C-l}, or configure the option
+@code{org-keep-stored-link-after-insertion}.}, along with a descriptive
+text. If some text was selected when this command is called, the selected
+text becomes the default description.
@b{Inserting stored links}@*
All links stored during the
@@ -3724,7 +3724,7 @@ Handling links
force an absolute path with two @kbd{C-u} prefixes.
@c
@item C-c C-l @ @r{(with cursor on existing link)}
-When the cursor is on an existing link, @kbd{C-c C-l} allows you to edit the
+When point is on an existing link, @kbd{C-c C-l} allows you to edit the
link and description parts of the link.
@c
@cindex following links
@@ -3735,15 +3735,15 @@ Handling links
@command{browse-url-at-point}), run VM/MH-E/Wanderlust/Rmail/Gnus/BBDB for
the corresponding links, and execute the command in a shell link. When the
cursor is on an internal link, this command runs the corresponding search.
-When the cursor is on a TAG list in a headline, it creates the corresponding
-TAGS view. If the cursor is on a timestamp, it compiles the agenda for that
+When point is on a TAG list in a headline, it creates the corresponding
+TAGS view. If point is on a timestamp, it compiles the agenda for that
date. Furthermore, it will visit text and remote files in @samp{file:} links
with Emacs and select a suitable application for local non-text files.
Classification of files is based on file extension only. See option
@code{org-file-apps}. If you want to override the default application and
visit the file with Emacs, use a @kbd{C-u} prefix. If you want to avoid
opening in Emacs, use a @kbd{C-u C-u} prefix.@*
-If the cursor is on a headline, but not on a link, offer all links in the
+If point is on a headline, but not on a link, offer all links in the
headline and entry text. If you want to setup the frame configuration for
following links, customize @code{org-link-frame-setup}.
@@ -3781,7 +3781,7 @@ Handling links
@code{#+STARTUP} keywords @code{inlineimages} and @code{noinlineimages}}.
@orgcmd{C-c %,org-mark-ring-push}
@cindex mark ring
-Push the current position onto the mark ring, to be able to return
+Push the current position onto Org's mark ring, to be able to return
easily. Commands following an internal link do this automatically.
@c
@orgcmd{C-c &,org-mark-ring-goto}
@@ -3793,7 +3793,7 @@ Handling links
@c
@orgcmdkkcc{C-c C-x C-n,C-c C-x C-p,org-next-link,org-previous-link}
@cindex links, finding next/previous
-Move forward/backward to the next link in the buffer. At the limit of
+Move forward/backward to the next link in the buffer. At the end of
the buffer, the search fails once, and then wraps around. The key
bindings for this are really too long; you might want to bind this also
to @kbd{C-n} and @kbd{C-p}
@@ -3808,16 +3808,17 @@ Handling links
@node Using links outside Org
@section Using links outside Org
-You can insert and follow links that have Org syntax not only in
-Org, but in any Emacs buffer. For this, you should create two
-global commands, like this (please select suitable global keys
-yourself):
+You can insert and follow links that have Org syntax not only in Org, but
+in any Emacs buffer. To achieve this, you can create two global key
+bindings, using Lisp code like this (alternative keys may be chosen):
@lisp
(global-set-key "\C-c L" 'org-insert-link-global)
(global-set-key "\C-c o" 'org-open-at-point-global)
@end lisp
+This can be placed in your Init file, for instance.
+
@node Link abbreviations
@section Link abbreviations
@cindex link abbreviations
@@ -3855,12 +3856,12 @@ Link abbreviations
replaced with the tag. Using @samp{%h} instead of @samp{%s} will
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.
+to a custom Lisp function, and replace it by the resulting string.
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
+Instead of a string, you may also specify a Lisp function that will be
called with the tag as the only argument to create the link.
With the above setting, you could link to a specific bug with
@@ -3882,10 +3883,11 @@ Link abbreviations
@noindent
In-buffer completion (@pxref{Completion}) can be used after @samp{[} to
-complete link abbreviations. You may also define a function that implements
-special (e.g., completion) support for inserting such a link with @kbd{C-c
-C-l}. Such a function should not accept any arguments, and return the full
-link with prefix. You can add a completion function to a link like this:
+complete link abbreviations. You may also define a Lisp function that
+implements special (e.g. completion) support for inserting such a link with
+@kbd{C-c C-l}. Such a function should not accept any arguments, and should
+return the full link with a prefix. You can add a completion function to a
+link like this:
@lisp
(org-link-set-parameters ``type'' :complete #'some-function)
@@ -3907,7 +3909,7 @@ Search options
link with @kbd{C-c C-o}.
Here is the syntax of the different ways to attach a search to a file
-link, together with an explanation:
+link, together with explanations for each:
@example
[[file:~/code/main.c::255]]
@@ -3958,15 +3960,15 @@ Custom searches
@vindex org-create-file-search-functions
@vindex org-execute-file-search-functions
-If you come across such a problem, you can write custom functions to set
-the right search string for a particular file type, and to do the search
-for the string in the file. Using @code{add-hook}, these functions need
-to be added to the hook variables
+If you come across such a problem, you can write custom Lisp functions to
+set the right search string for a particular file type, and to do the
+search for the string in the file. Using @code{add-hook}, these functions
+need to be added to the hook variables
@code{org-create-file-search-functions} and
@code{org-execute-file-search-functions}. See the docstring for these
-variables for more information. Org actually uses this mechanism
-for Bib@TeX{} database files, and you can use the corresponding code as
-an implementation example. See the file @file{org-bibtex.el}.
+variables for more information. Org actually uses this mechanism for
+Bib@TeX{} database files, and you can use the corresponding code as an
+implementation example. See the file @file{org-bibtex.el}.
@node TODO items
@chapter TODO items
@@ -4268,7 +4270,7 @@ Per-file keywords
Remember that the keywords after the vertical bar (or the last keyword
if no bar is there) must always mean that the item is DONE (although you
may use a different word). After changing one of these lines, use
-@kbd{C-c C-c} with the cursor still in the line to make the changes
+@kbd{C-c C-c} with point still in the line to make the changes
known to Org mode@footnote{Org mode parses these lines only when
Org mode is activated after visiting a file. @kbd{C-c C-c} with the
cursor in a line starting with @samp{#+} is simply restarting Org mode
@@ -4808,7 +4810,7 @@ Checkboxes
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 the state of the first checkbox in the
+If point 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.
@@ -4816,7 +4818,7 @@ Checkboxes
If there is no active region, just toggle the checkbox at point.
@end itemize
@orgcmd{M-S-@key{RET},org-insert-todo-heading}
-Insert a new item with a checkbox. This works only if the cursor is already
+Insert a new item with a checkbox. This works only if point is already
in a plain list item (@pxref{Plain lists}).
@orgcmd{C-c C-x o,org-toggle-ordered-property}
@vindex org-track-ordered-property-with-tag
@@ -4940,7 +4942,7 @@ Setting tags
demotion, and TODO state changes (@pxref{TODO basics}).
@orgcmd{C-c C-c,org-set-tags-command}
-When the cursor is in a headline, this does the same as @kbd{C-c C-q}.
+When point is in a headline, this does the same as @kbd{C-c C-q}.
@end table
@vindex org-tag-alist
@@ -5022,7 +5024,7 @@ Setting tags
@noindent you indicate that at most one of @samp{@@work}, @samp{@@home},
and @samp{@@tennisclub} should be selected. Multiple such groups are allowed.
-@noindent Don't forget to press @kbd{C-c C-c} with the cursor in one of
+@noindent Don't forget to press @kbd{C-c C-c} with point in one of
these lines to activate any changes.
@noindent
@@ -5380,7 +5382,7 @@ Property syntax
inserted early in the entry, but after the lines with planning
information like deadlines.
@orgcmd{C-c C-c,org-property-action}
-With the cursor in a property drawer, this executes property commands.
+With point in a property drawer, this executes property commands.
@orgcmd{C-c C-c s,org-set-property}
Set a property in the current entry. Both the property and the value
can be inserted using completion.
@@ -5697,7 +5699,7 @@ Using column view
@tsubheading{Turning column view on and off}
@orgcmd{C-c C-x C-c,org-columns}
@vindex org-columns-default-format
-Turn on column view. If the cursor is before the first headline in the file,
+Turn on column view. If point is before the first headline in the file,
or the function called with the universal prefix argument, column view is
turned on for the entire file, using the @code{#+COLUMNS} definition. If the
cursor is somewhere inside the outline, this command searches the hierarchy,
@@ -5966,7 +5968,7 @@ Creating timestamps
@table @kbd
@orgcmd{C-c .,org-time-stamp}
-Prompt for a date and insert a corresponding timestamp. When the cursor is
+Prompt for a date and insert a corresponding timestamp. When point is
at an existing timestamp in the buffer, the command is used to modify this
timestamp instead of inserting a new one. When this command is used twice in
succession, a time range is inserted.
@@ -5988,7 +5990,7 @@ Creating timestamps
Normalize timestamp, insert/fix day name if missing or wrong.
@c
@orgcmd{C-c <,org-date-from-calendar}
-Insert a timestamp corresponding to the cursor date in the Calendar.
+Insert a timestamp corresponding to point date in the Calendar.
@c
@orgcmd{C-c >,org-goto-calendar}
Access the Emacs calendar for the current date. If there is a
@@ -6004,11 +6006,11 @@ Creating timestamps
shift-selection and related modes (@pxref{Conflicts}).
@c
@orgcmdkkcc{S-@key{UP},S-@key{DOWN},org-timestamp-up,org-timestamp-down-down}
-Change the item under the cursor in a timestamp. The cursor can be on a
+Change the item under point in a timestamp. point can be on a
year, month, day, hour or minute. When the timestamp contains a time range
like @samp{15:30-16:30}, modifying the first time will also shift the second,
shifting the time block with constant length. To change the length, modify
-the second time. Note that if the cursor is in a headline and not at a
+the second time. Note that if point is in a headline and not at a
timestamp, these same keys modify the priority of an item.
(@pxref{Priorities}). The key bindings also conflict with shift-selection and
related modes (@pxref{Conflicts}).
@@ -6182,11 +6184,11 @@ Custom time format
following consequences:
@itemize @bullet
@item
-You cannot place the cursor onto a timestamp anymore, only before or
+You cannot place point onto a timestamp anymore, only before or
after.
@item
The @kbd{S-@key{UP}/@key{DOWN}} keys can no longer be used to adjust
-each component of a timestamp. If the cursor is at the beginning of
+each component of a timestamp. If point is at the beginning of
the stamp, @kbd{S-@key{UP}/@key{DOWN}} will change the stamp by one day,
just like @kbd{S-@key{LEFT}/@key{RIGHT}}. At the end of the stamp, the
time will be changed by one minute.
@@ -6585,7 +6587,7 @@ The clock table
@table @kbd
@orgcmd{C-c C-x C-r,org-clock-report}
Insert a dynamic block (@pxref{Dynamic blocks}) containing a clock
-report as an Org mode table into the current file. When the cursor is
+report as an Org mode table into the current file. When point is
at an existing clock table, just update it. When called with a prefix
argument, jump to the first clock report in the current document and
update it. The clock table always includes also trees with
@@ -6596,7 +6598,7 @@ The clock table
Update all dynamic blocks (@pxref{Dynamic blocks}). This is useful if
you have several clock table blocks in a buffer.
@orgcmdkxkc{S-@key{LEFT},S-@key{RIGHT},org-clocktable-try-shift}
-Shift the current @code{:block} interval and update the table. The cursor
+Shift the current @code{:block} interval and update the table. point
needs to be in the @code{#+BEGIN: clocktable} line for this command. If
@code{:block} is @code{today}, it will be shifted to @code{today-1} etc.
@end table
@@ -7005,9 +7007,9 @@ Using capture
@orgcmd{C-c C-w,org-capture-refile}
Finalize the capture process by refiling (@pxref{Refile and copy}) the note to
a different place. Please realize that this is a normal refiling command
-that will be executed---so the cursor position at the moment you run this
+that will be executed---so point position at the moment you run this
command is important. If you have inserted a tree with a parent and
-children, first move the cursor back to the parent. Any prefix argument
+children, first move point back to the parent. Any prefix argument
given to this command will be passed on to the @code{org-refile} command.
@orgcmd{C-c C-k,org-capture-kill}
@@ -7017,7 +7019,7 @@ Using capture
You can also call @code{org-capture} in a special way from the agenda, using
the @kbd{k c} key combination. With this access, any timestamps inserted by
-the selected capture template will default to the cursor date in the agenda,
+the selected capture template will default to point date in the agenda,
rather than to the current date.
To find the locations of the last stored capture, use @code{org-capture} with
@@ -7172,7 +7174,7 @@ Template elements
For non-unique headings, the full path is safer.
@item (file+regexp "path/to/file" "regexp to find location")
-Use a regular expression to position the cursor.
+Use a regular expression to position point.
@item (file+olp+datetree "path/to/file" [ "Level 1 heading" ....])
This target@footnote{Org used to offer four different targets for date/week
@@ -7344,7 +7346,7 @@ Template expansion
@end smallexample
@noindent
-To place the cursor after template expansion use:
+To place point after template expansion use:
@smallexample
%? @r{After completing the template, position cursor here.}
@@ -7804,13 +7806,13 @@ Moving subtrees
@table @kbd
@orgcmdkskc{C-c C-x C-s,C-c $,org-archive-subtree}
@vindex org-archive-location
-Archive the subtree starting at the cursor position to the location
+Archive the subtree starting at point position to the location
given by @code{org-archive-location}.
@orgkey{C-u C-c C-x C-s}
Check if any direct children of the current headline could be moved to
the archive. To do this, each subtree is checked for open TODO entries.
If none are found, the command offers to move it to the archive
-location. If the cursor is @emph{not} on a headline when this command
+location. If point is @emph{not} on a headline when this command
is invoked, the level 1 trees will be checked.
@orgkey{C-u C-u C-c C-x C-s}
As above, but check subtree for timestamps instead of TODO entries. The
@@ -8032,7 +8034,7 @@ Agenda files
@table @kbd
@orgcmd{C-c C-x <,org-agenda-set-restriction-lock}
Permanently restrict the agenda to the current subtree. When with a
-prefix argument, or with the cursor before the first headline in a file,
+prefix argument, or with point before the first headline in a file,
the agenda scope is set to the entire file. This restriction remains in
effect until removed with @kbd{C-c C-x >}, or by typing either @kbd{<}
or @kbd{>} in the agenda dispatcher. If there is a window displaying an
@@ -8048,7 +8050,7 @@ Agenda files
@table @kbd
@orgcmdtkc{< @r{in the speedbar frame},<,org-speedbar-set-agenda-restriction}
Permanently restrict the agenda to the item---either an Org file or a subtree
-in such a file---at the cursor in the Speedbar frame.
+in such a file---at point in the Speedbar frame.
If there is a window displaying an agenda view, the new restriction takes
effect immediately.
@orgcmdtkc{> @r{in the speedbar frame},>,org-agenda-remove-restriction-lock}
@@ -8242,7 +8244,7 @@ Weekly/daily agenda
@end example
You can then go ahead and define anniversaries for a BBDB record. Basically,
-you need to press @kbd{C-o anniversary @key{RET}} with the cursor in a BBDB
+you need to press @kbd{C-o anniversary @key{RET}} with point in a BBDB
record and then add the date in the format @code{YYYY-MM-DD} or @code{MM-DD},
followed by a space and the class of the anniversary (@samp{birthday} or
@samp{wedding}, or a format string). If you omit the class, it will default to
@@ -8935,7 +8937,7 @@ Agenda commands
removing the risk that your agenda and note files may diverge.
Some commands can be executed with mouse clicks on agenda lines. For
-the other commands, the cursor needs to be in the desired line.
+the other commands, point needs to be in the desired line.
@table @kbd
@tsubheading{Motion}
@@ -8964,7 +8966,7 @@ Agenda commands
@c
@orgcmd{F,org-agenda-follow-mode}
@vindex org-agenda-start-with-follow-mode
-Toggle Follow mode. In Follow mode, as you move the cursor through
+Toggle Follow mode. In Follow mode, as you move point through
the agenda buffer, the other window always shows the corresponding
location in the Org file. The initial setting for this mode in new
agenda buffers can be set with the variable
@@ -9378,12 +9380,12 @@ Agenda commands
@c
@orgcmd{c,org-calendar-goto-agenda}
When in the calendar, compute and show the Org mode agenda for the
-date at the cursor.
+date at point.
@c
@cindex diary entries, creating from agenda
@orgcmd{i,org-agenda-diary-entry}
@vindex org-agenda-diary-file
-Insert a new entry into the diary, using the date at the cursor and (for
+Insert a new entry into the diary, using the date at point and (for
block entries) the date at the mark. This will add to the Emacs diary
file@footnote{This file is parsed for the agenda when
@code{org-agenda-include-diary} is set.}, in a way similar to the @kbd{i}
@@ -9413,7 +9415,7 @@ Agenda commands
calendars.
@c
@orgcmd{H,org-agenda-holidays}
-Show holidays for three months around the cursor date.
+Show holidays for three months around the date at point.
@item M-x org-icalendar-combine-agenda-files @key{RET}
Export a single iCalendar file containing entries from all agenda files.
@@ -10373,7 +10375,7 @@ Previewing @LaTeX{} fragments
over the source code. If there is no fragment at point, process all
fragments in the current entry (between two headlines). When called
with a prefix argument, process the entire subtree. When called with
-two prefix arguments, or when the cursor is before the first headline,
+two prefix arguments, or when point is before the first headline,
process the entire buffer.
@kindex C-c C-c
@item C-c C-c
@@ -10420,11 +10422,11 @@ CDLaTeX mode
Environment templates can be inserted with @kbd{C-c @{}.
@item
@kindex TAB
-The @key{TAB} key will do template expansion if the cursor is inside a
-@LaTeX{} fragment@footnote{Org mode has a method to test if the cursor is
+The @key{TAB} key will do template expansion if point is inside a
+@LaTeX{} fragment@footnote{Org mode has a method to test if point is
inside such a fragment, see the documentation of the function
@code{org-inside-LaTeX-fragment-p}.}. For example, @key{TAB} will
-expand @code{fr} to @code{\frac@{@}@{@}} and position the cursor
+expand @code{fr} to @code{\frac@{@}@{@}} and position point
correctly inside the first brace. Another @key{TAB} will get you into
the second brace. Even outside fragments, @key{TAB} will expand
environment abbreviations at the beginning of a line. For example, if
@@ -10576,9 +10578,9 @@ The export dispatcher
@item C-s
@vindex org-export-initial-scope
Toggle sub-tree export. When turned on, Org exports only the sub-tree starting
-from the cursor position at the time the export dispatcher was invoked. Org
-uses the top heading of this sub-tree as the document's title. If the cursor
-is not on a heading, Org uses the nearest enclosing header. If the cursor is
+from point position at the time the export dispatcher was invoked. Org
+uses the top heading of this sub-tree as the document's title. If point
+is not on a heading, Org uses the nearest enclosing header. If point is
in the document preamble, Org signals an error and aborts export.
To make the sub-tree export the default, customize the variable,
@@ -17360,7 +17362,7 @@ Speed keys
@section Speed keys
@cindex speed keys
-Single keystrokes can execute custom commands in an Org file when the cursor
+Single keystrokes can execute custom commands in an Org file when point
is on a headline. Without the extra burden of a meta or modifier key, Speed
Keys can speed navigation or execute custom commands. Besides faster
navigation, Speed Keys may come in handy on small mobile devices that do not
@@ -17370,7 +17372,7 @@ Speed keys
@vindex org-use-speed-commands
By default, Org has Speed Keys disabled. To activate Speed Keys, set the
variable @code{org-use-speed-commands} to a non-@code{nil} value. To trigger
-a Speed Key, the cursor must be at the beginning of an Org headline, before
+a Speed Key, point must be at the beginning of an Org headline, before
any of the stars.
@vindex org-speed-commands-user
@@ -17513,7 +17515,7 @@ In-buffer settings
also parses and loads the document during normal exporting process. Org
parses the contents of this document as if it was included in the buffer. It
can be another Org file. To visit the file (not a URL), @kbd{C-c '} while
-the cursor is on the line with the file name.
+point is on the line with the file name.
@item #+STARTUP:
@cindex @code{#+STARTUP}
Startup options Org uses when first visiting a file.
@@ -17753,41 +17755,41 @@ The very busy C-c C-c key
If any highlights shown in the buffer from the creation of a sparse tree, or
from clock display, remove such highlights.
@item
-If the cursor is in one of the special @code{#+KEYWORD} lines, scan the
+If point is in one of the special @code{#+KEYWORD} lines, scan the
buffer for these lines and update the information. Also reset the Org file
cache used to temporary store the contents of URLs used as values for
keywords like @code{#+SETUPFILE}.
@item
-If the cursor is inside a table, realign the table. The table realigns even
+If point is inside a table, realign the table. The table realigns even
if automatic table editor is turned off.
@item
-If the cursor is on a @code{#+TBLFM} line, re-apply the formulas to
+If point is on a @code{#+TBLFM} line, re-apply the formulas to
the entire table.
@item
If the current buffer is a capture buffer, close the note and file it. With
a prefix argument, also jump to the target location after saving the note.
@item
-If the cursor is on a @code{<<<target>>>}, update radio targets and
+If point is on a @code{<<<target>>>}, update radio targets and
corresponding links in this buffer.
@item
-If the cursor is on a property line or at the start or end of a property
+If point is on a property line or at the start or end of a property
drawer, offer property commands.
@item
-If the cursor is at a footnote reference, go to the corresponding
+If point is at a footnote reference, go to the corresponding
definition, and @emph{vice versa}.
@item
-If the cursor is on a statistics cookie, update it.
+If point is on a statistics cookie, update it.
@item
-If the cursor is in a plain list item with a checkbox, toggle the status
+If point is in a plain list item with a checkbox, toggle the status
of the checkbox.
@item
-If the cursor is on a numbered item in a plain list, renumber the
+If point is on a numbered item in a plain list, renumber the
ordered list.
@item
-If the cursor is on the @code{#+BEGIN} line of a dynamic block, the
+If point is on the @code{#+BEGIN} line of a dynamic block, the
block is updated.
@item
-If the cursor is at a timestamp, fix the day name in the timestamp.
+If point is at a timestamp, fix the day name in the timestamp.
@end itemize
@node Clean view
@@ -18014,7 +18016,7 @@ Cooperation
Ota tables cannot be edited directly in the Org buffer.
@table @kbd
@orgcmd{C-c ',org-edit-special}
-Edit a @file{table.el} table. Works when the cursor is in a table.el table.
+Edit a @file{table.el} table. Works when point is in a table.el table.
@c
@orgcmd{C-c ~,org-table-create-with-table.el}
Insert a @file{table.el} table. If there is already a table at point, this
@@ -18039,7 +18041,7 @@ Conflicts
variable @code{org-support-shift-select} for customization. Org mode
accommodates shift selection by (i) making it available outside of the
special contexts where special commands apply, and (ii) extending an
-existing active region even if the cursor moves across a special context.
+existing active region even if point moves across a special context.
@item @file{CUA.el} by Kim. F. Storm
@cindex @file{CUA.el}
@@ -19056,12 +19058,12 @@ Using the mapping API
@defun org-map-entries func &optional match scope &rest skip
Call @samp{FUNC} at each headline selected by @code{MATCH} in @code{SCOPE}.
-@samp{FUNC} is a function or a Lisp form. With the cursor positioned at the
+@samp{FUNC} is a function or a Lisp form. With point positioned at the
beginning of the headline, call the function without arguments. Org returns
an alist of return values of calls to the function.
To avoid preserving point, Org wraps the call to @code{FUNC} in
-save-excursion form. After evaluation, Org moves the cursor to the end of
+save-excursion form. After evaluation, Org moves point to the end of
the line that was just processed. Search continues from that point forward.
This may not always work as expected under some conditions, such as if the
current sub-tree was removed by a previous archiving operation. In such rare
@@ -19263,7 +19265,7 @@ Pulling from MobileOrg
@item
Org generates an agenda view for flagged entries for user intervention to
clean up. For notes stored in flagged entries, MobileOrg displays them in
-the echo area when the cursor is on the corresponding agenda item.
+the echo area when point is on the corresponding agenda item.
@table @kbd
@kindex ?
--
2.17.1
^ permalink raw reply related [flat|nested] 9+ messages in thread
* Re: Org Mode Documentation Patch
2018-06-22 16:08 Org Mode Documentation Patch Ben Phipathananunth
@ 2018-06-22 18:14 ` Eli Zaretskii
0 siblings, 0 replies; 9+ messages in thread
From: Eli Zaretskii @ 2018-06-22 18:14 UTC (permalink / raw)
To: Ben Phipathananunth; +Cc: emacs-devel
> Date: Fri, 22 Jun 2018 16:08:35 +0000
> From: "Ben Phipathananunth" <siraben@disroot.org>
>
> I've begun reading the Org Mode manual, and noticed that the wording
> in some places could be improved (so far I've read up to Section 4.8).
> I've attached my patch. Some of the more drastic changes:
>
> - Changed all occurrences of "the cursor" to "point", I thought the
> inconsistency was confusing, especially since the Emacs manual
> maintains usage of "point" throughout, so too should the Org Mode
> manual.
>
> I have a couple of questions regarding the Org Mode manual and
> submitting patches:
>
> Section 4.6 "Link abbreviations" in the Org Mode manual link to
> websites that have and/or promote non-free software. The URLs are
> used to illustrate link abbreviations in Org Mode, but I suppose this
> was purely coincidental because long URLs to websites such as
> gnu.org/some/long/path could be used instead. Would it be appropriate
> to change the examples in a later patch?
>
> When the PDF version of the Org Mode manual is generated with "make
> docs", the footnotes (3 and 4) around Section 4.3 are incorrectly
> indented, can anyone reproduce this? What is causing it?
>
> Should I submit my patches as smaller ones as I read sections of the
> manual or bulk them together into a larger patch, or is it just a
> matter of preference?
Please submit this to Org developers first, as the manual's master
copy is maintained there. (I think they are moving towards using Org
format for the manual source anyway, so submitting patches in Texinfo
will not be useful.)
Thanks.
^ permalink raw reply [flat|nested] 9+ messages in thread
* Org Mode Documentation Patch
@ 2018-06-23 2:23 Siraphob (Ben) Phipathananunth
2018-06-23 7:36 ` Nicolas Goaziou
0 siblings, 1 reply; 9+ messages in thread
From: Siraphob (Ben) Phipathananunth @ 2018-06-23 2:23 UTC (permalink / raw)
To: emacs-orgmode
[-- Attachment #1: Type: text/plain, Size: 1534 bytes --]
This patch was originally submitted to Emacs devel, but Eli Zaretskii
redirected me here.
I've begun reading the Org Mode manual, and noticed that the wording
in some places could be improved (so far I've read up to Section 4.8).
I've attached my patch. Some of the more drastic changes:
- Changed all occurrences of "the cursor" to "point", I thought the
inconsistency was confusing, especially since the Emacs manual
maintains usage of "point" throughout, so too should the Org Mode
manual.
I have a couple of questions regarding the Org Mode manual and
submitting patches:
Section 4.6 "Link abbreviations" in the Org Mode manual link to
websites that have and/or promote non-free software. The URLs are
used to illustrate link abbreviations in Org Mode, but I suppose this
was purely coincidental because long URLs to websites such as
gnu.org/some/long/path could be used instead. Would it be appropriate
to change the examples in a later patch?
When the PDF version of the Org Mode manual is generated with "make
docs", the footnotes (3 and 4) around Section 4.3 are incorrectly
indented, can anyone reproduce this? What is causing it?
Should I submit my patches as smaller ones as I read sections of the
manual or bulk them together into a larger patch, or is it just a
matter of preference?
Please let me know if you have any comments about the patch. It's my
first one, I hope I have followed the CONTRIBUTING guide properly.
Thanks!
--
Siraphob (Ben) Phipathananunth
[-- Attachment #2: 0001-Fix-various-grammatical-errors-and-fix-terminology.patch --]
[-- Type: application/octet-stream, Size: 42991 bytes --]
From dd4c2da7644c5449186166da43603155f4b56311 Mon Sep 17 00:00:00 2001
From: Ben Phipathananunth <bensiraphob@hotmail.co.uk>
Date: Sat, 23 Jun 2018 09:14:04 +0700
Subject: [PATCH] Fix various grammatical errors and fix terminology
* All occurrences of "the cursor" are replaced with "point"
* Begin changing "function" to "Lisp function" as used in the Emacs
manual
---
doc/org-manual.org | 258 ++++++++++++++++++++++-----------------------
1 file changed, 128 insertions(+), 130 deletions(-)
diff --git a/doc/org-manual.org b/doc/org-manual.org
index c7598573a..534703519 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -204,7 +204,7 @@ Many commands in Org work on the region if the region is /active/. To
make use of this, you need to have ~transient-mark-mode~ turned on,
which is the default. If you do not like ~transient-mark-mode~, you
can create an active region by using the mouse to select a region, or
-pressing {{{kbd(C-SPC)}}} twice before moving the cursor.
+pressing {{{kbd(C-SPC)}}} twice before moving point.
** Feedback
:PROPERTIES:
@@ -468,7 +468,7 @@ Org uses just two commands, bound to {{{kbd(TAB)}}} and
#+end_example
#+vindex: org-cycle-emulate-tab
- The cursor must be on a headline for this to work[fn:4].
+ point must be on a headline for this to work[fn:4].
- {{{kbd(S-TAB)}}} (~org-global-cycle~), {{{kbd(C-u TAB)}}} ::
@@ -901,7 +901,7 @@ active---promotion and demotion work on all headlines in the region.
To select a region of headlines, it is best to place both point and
mark at the beginning of a line, mark at the beginning of the first
headline, and point at the line just after the last headline to
-change. Note that when the cursor is inside a table (see [[*Tables]]),
+change. Note that when point is inside a table (see [[*Tables]]),
the Meta-Cursor keys have different functionality.
** Sparse Trees
@@ -1066,7 +1066,7 @@ of indentation between items and theirs sub-items, customize
~org-list-indent-offset~.
#+vindex: org-list-automatic-rules
-The following commands act on items when the cursor is in the first
+The following commands act on items when point is in the first
line of an item---the line with the bullet or number. Some of them
imply the application of automatic rules to keep list structure
intact. If some of these actions get in your way, configure
@@ -1080,7 +1080,7 @@ intact. If some of these actions get in your way, configure
#+findex: org-cycle
#+vindex: org-cycle-include-plain-lists
Items can be folded just like headline levels. Normally this
- works only if the cursor is on a plain list item. For more
+ works only if point is on a plain list item. For more
details, see the variable ~org-cycle-include-plain-lists~. If
this variable is set to ~integrate~, plain list items are treated
like low-level headlines. The level of an item is then given by
@@ -1194,7 +1194,7 @@ intact. If some of these actions get in your way, configure
#+vindex: org-support-shift-select
#+kindex: S-LEFT
#+kindex: S-RIGHT
- This command also cycles bullet styles when the cursor in on the
+ This command also cycles bullet styles when point in on the
bullet or anywhere in an item line, details depending on
~org-support-shift-select~.
@@ -1241,7 +1241,7 @@ Completion over drawer keywords is also possible using
Visibility cycling (see [[*Visibility Cycling]]) on the headline hides and
shows the entry, but keep the drawer collapsed to a single line. In
-order to look inside the drawer, you need to move the cursor to the
+order to look inside the drawer, you need to move point to the
drawer line and press {{{kbd(TAB)}}} there.
You can also arrange for state change notes (see [[Tracking TODO state
@@ -1328,7 +1328,7 @@ The following command handles footnotes:
The footnote action command.
#+kindex: C-c C-x f
- When the cursor is on a footnote reference, jump to the
+ When point is on a footnote reference, jump to the
definition. When it is at a definition, jump to
the---first---reference.
@@ -1357,7 +1357,7 @@ The following command handles footnotes:
- {{{kbd(C-c C-c)}}} ::
#+kindex: C-c C-c
- If the cursor is on a footnote reference, jump to the definition.
+ If point is on a footnote reference, jump to the definition.
If it is at the definition, jump back to the reference. When
called at a footnote location with a prefix argument, offer the
same menu as {{{kbd(C-c C-x f)}}}.
@@ -1450,7 +1450,7 @@ fields. Even faster would be to type =|Name|Phone|Age= followed by
When typing text into a field, Org treats {{{kbd(DEL)}}},
{{{kbd(Backspace)}}}, and all character keys in a special way, so that
inserting and deleting avoids shifting other fields. Also, when
-typing /immediately/ after the cursor was moved into a new field with
+typing /immediately/ after point was moved into a new field with
{{{kbd(TAB)}}}, {{{kbd(S-TAB)}}} or {{{kbd(RET)}}}, the field is
automatically made blank. If this behavior is too unpredictable for
you, configure the option ~org-table-auto-blank-field~.
@@ -1488,7 +1488,7 @@ you, configure the option ~org-table-auto-blank-field~.
#+kindex: C-c C-c
#+findex: org-table-align
- Re-align the table without moving the cursor.
+ Re-align the table without moving point.
- {{{kbd(TAB)}}} (~org-table-next-field~) ::
@@ -1557,7 +1557,7 @@ you, configure the option ~org-table-auto-blank-field~.
#+kindex: M-S-RIGHT
#+findex: org-table-insert-column
- Insert a new column to the left of the cursor position.
+ Insert a new column to the left of point position.
- {{{kbd(M-UP)}}} (~org-table-move-row-up~) ::
@@ -1595,7 +1595,7 @@ you, configure the option ~org-table-auto-blank-field~.
#+kindex: C-c RET
#+findex: org-table-hline-and-move
- Insert a horizontal line below current row, and move the cursor
+ Insert a horizontal line below current row, and move point
into the row below that line.
- {{{kbd(C-c ^)}}} (~org-table-sort-lines~) ::
@@ -1651,7 +1651,7 @@ you, configure the option ~org-table-auto-blank-field~.
#+kindex: M-RET
#+findex: org-table-wrap-region
- Split the current field at the cursor position and move the rest
+ Split the current field at point position and move the rest
to the line below. If there is an active region, and both point
and mark are in the same column, the text in the column is
wrapped to minimum width for the given number of lines.
@@ -1704,8 +1704,8 @@ you, configure the option ~org-table-auto-blank-field~.
Alignment]]). When called with a {{{kbd(C-u)}}} prefix, just make
the full field visible, so that it can be edited in place. When
called with two {{{kbd(C-u)}}} prefixes, make the editor window
- follow the cursor through the table and always show the current
- field. The follow mode exits automatically when the cursor
+ follow point through the table and always show the current
+ field. The follow mode exits automatically when point
leaves the table, or when you repeat this command with {{{kbd(C-u
C-u C-c `)}}}.
@@ -2279,11 +2279,11 @@ interpolated as a Lisp string (in double-quotes) containing the field.
If you provide the =N= mode switch, all referenced elements are
numbers---non-number fields will be zero---and interpolated as Lisp
numbers, without quotes. If you provide the =L= flag, all fields are
-interpolated literally, without quotes. I.e., if you want a reference
-to be interpreted as a string by the Lisp form, enclose the reference
-operator itself in double-quotes, like ="$3"=. Ranges are inserted as
-space-separated fields, so you can embed them in list or vector
-syntax.
+interpolated literally, without quotes. For example, if you want a
+reference to be interpreted as a string by the Lisp form, enclose the
+reference operator itself in double-quotes, like ="$3"=. Ranges are
+inserted as space-separated fields, so you can embed them in list or
+vector syntax.
Here are a few examples---note how the =N= mode is used when we do
computations in Lisp:
@@ -2346,7 +2346,7 @@ considered as seconds in addition and subtraction.
To assign a formula to a particular field, type it directly into the
field, preceded by =:==, for example =vsum(@II..III)=. When you press
-{{{kbd(TAB)}}} or {{{kbd(RET)}}} or {{{kbd(C-c C-c)}}} with the cursor
+{{{kbd(TAB)}}} or {{{kbd(RET)}}} or {{{kbd(C-c C-c)}}} with point
still in the field, the formula is stored as the formula for this
field, evaluated, and the current field is replaced with the result.
@@ -2360,9 +2360,8 @@ formulas are modified in order to still reference the same field. To
avoid this from happening, in particular in range references, anchor
ranges at the table borders (using =@<=, =@>=, =$<=, =$>=), or at
hlines using the =@I= notation. Automatic adaptation of field
-references does of course not happen if you edit the table structure
-with normal editing commands---then you must fix the equations
-yourself.
+references does not happen if you edit the table structure with normal
+editing commands---you must fix the formulas yourself.
Instead of typing an equation into the field, you may also use the
following command
@@ -2423,7 +2422,7 @@ column formulas very easy to use.
To assign a formula to a column, type it directly into any field in
the column, preceded by an equal sign, like ==$1+$2=. When you press
-{{{kbd(TAB)}}} or {{{kbd(RET)}}} or {{{kbd(C-c C-c)}}} with the cursor
+{{{kbd(TAB)}}} or {{{kbd(RET)}}} or {{{kbd(C-c C-c)}}} with point
still in the field, the formula is stored as the formula for the
current column, evaluated and the current field replaced with the
result. If the field contains only ===, the previously stored formula
@@ -2536,7 +2535,7 @@ you prefer to only work with the internal format (like =@3$2= or
#+kindex: C-c ?
#+findex: org-table-field-info
While editing a formula in a table field, highlight the field(s)
- referenced by the reference at the cursor position in the
+ referenced by the reference at point position in the
formula.
- {{{kbd(C-c })}}} (~org-table-toggle-coordinate-overlays~) ::
@@ -2559,9 +2558,9 @@ you prefer to only work with the internal format (like =@3$2= or
#+findex: org-table-edit-formulas
Edit all formulas for the current table in a special buffer,
where the formulas are displayed one per line. If the current
- field has an active formula, the cursor in the formula editor
+ field has an active formula, point in the formula editor
marks it. While inside the special buffer, Org automatically
- highlights any field or range reference at the cursor position.
+ highlights any field or range reference at point position.
You may edit, remove and add formulas, and use the following
commands:
@@ -2668,10 +2667,10 @@ recalculation commands in the table.
#+cindex: @samp{TBLFM}, switching
#+kindex: C-c C-c
-You may apply the formula temporarily. This is useful when you switch
-the formula. Place multiple =TBLFM= keywords right after the table,
-and then press {{{kbd(C-c C-c)}}} on the formula to apply. Here is an
-example:
+You may apply the formula temporarily. This is useful when you want
+to switch the formula applied to the table. Place multiple =TBLFM=
+keywords right after the table, and then press {{{kbd(C-c C-c)}}} on
+the formula to apply. Here is an example:
#+begin_example
| x | y |
@@ -2696,7 +2695,7 @@ Pressing {{{kbd(C-c C-c)}}} in the line of =#+TBLFM: $2=$1*2= yields:
#+texinfo: @noindent
Note: If you recalculate this table, with {{{kbd(C-u C-c *)}}}, for
-example, you get the following result of applying only the first
+example, you get the following result from applying only the first
=TBLFM= keyword.
#+begin_example
@@ -2995,7 +2994,7 @@ For more information and examples see the [[https://orgmode.org/worg/org-tutoria
:UNNUMBERED: notoc
:END:
-While the cursor is on a column, typing {{{kbd(C-c " a)}}} or
+While point is on a column, typing {{{kbd(C-c " a)}}} or
{{{kbd(M-x orgtbl-ascii-plot)}}} create a new column containing an
ASCII-art bars plot. The plot is implemented through a regular column
formula. When the source column changes, the bar plot may be updated
@@ -3035,8 +3034,8 @@ defaults to =12=.
:END:
#+cindex: hyperlinks
-Like HTML, Org provides links inside a file, external links to
-other files, Usenet articles, emails, and much more.
+Like HTML, Org provides support for links inside a file, external
+links to other files, Usenet articles, emails, and much more.
** Link Format
:PROPERTIES:
@@ -3063,10 +3062,10 @@ highlighted in the face ~org-link~, which by default is an underlined
face. You can directly edit the visible part of a link. Note that
this can be either the LINK part, if there is no description, or the
{{{var(DESCRIPTION)}}} part. To edit also the invisible
-{{{var(LINK)}}} part, use {{{kbd(C-c C-l)}}} with the cursor on the
+{{{var(LINK)}}} part, use {{{kbd(C-c C-l)}}} with point on the
link.
-If you place the cursor at the beginning or just behind the end of the
+If you place point at the beginning or just behind the end of the
displayed text and press {{{kbd(BS)}}}, you remove
the---invisible---bracket at that location. This makes the link
incomplete and the internals are again displayed as plain text.
@@ -3092,7 +3091,7 @@ custom IDs are unique in a file.
Links such as =[[My Target]]= or =[[My Target][Find my target]]= lead to a text search in
the current file.
-The link can be followed with {{{kbd(C-c C-o)}}} when the cursor is on
+The link can be followed with {{{kbd(C-c C-o)}}} when point is on
the link, or with a mouse click (see [[*Handling Links]]). Links to
custom IDs point to the corresponding headline. The preferred match
for a text link is a /dedicated target/: the same string in double
@@ -3155,7 +3154,7 @@ Target>>>= causes each occurrence of =my target= in normal text to
become activated as a link. The Org file is scanned automatically for
radio targets only when the file is first loaded into Emacs. To
update the target list during editing, press {{{kbd(C-c C-c)}}} with
-the cursor on or at a target.
+point on or at a target.
** External Links
:PROPERTIES:
@@ -3214,10 +3213,10 @@ the colon. The following list shows examples for each link type.
#+cindex: VM links
#+cindex: Wanderlust links
-On top of these built-in link types, some are available through the
-=contrib/= directory (see [[*Installation]]). For example, these links to
-VM or Wanderlust messages are available when you load the
-corresponding libraries from the =contrib/= directory:
+On top of these built-in link types, additional ones are available
+through the =contrib/= directory (see [[*Installation]]). For example,
+these links to VM or Wanderlust messages are available when you load
+the corresponding libraries from the =contrib/= directory:
| =vm:folder= | VM folder link |
| =vm:folder#id= | VM message link |
@@ -3227,11 +3226,11 @@ corresponding libraries from the =contrib/= directory:
| =wl:folder= | Wanderlust folder link |
| =wl:folder#id= | Wanderlust message link |
-For customizing Org to add new link types, see [[*Adding Hyperlink
-Types]].
+For information on customizing Org to add new link types, see [[*Adding
+Hyperlink Types]].
A link should be enclosed in double brackets and may contain
-a descriptive text to be displayed instead of the URL (see [[*Link
+descriptive text to be displayed instead of the URL (see [[*Link
Format]]), for example:
: [[http://www.gnu.org/software/emacs/][GNU Emacs]]
@@ -3248,7 +3247,7 @@ image is inlined into the exported HTML file.
Org also finds external links in the normal text and activates them as
links. If spaces must be part of the link (for example in
=bbdb:Richard Stallman=), or if you need to remove ambiguities about
-the end of the link, enclose them in square or angular brackets.
+the end of the link, enclose the link in square or angular brackets.
** Handling Links
:PROPERTIES:
@@ -3265,12 +3264,12 @@ The main function is ~org-store-link~, called with {{{kbd(M-x
org-store-link)}}}. Because of its importance, we suggest to bind it
to a widely available key (see [[*Activation]]). It stores a link to the
current location. The link is stored for later insertion into an Org
-buffer---see below. What kind of link is created depends on the
+buffer---see below. The kind of link that is created depends on the
current buffer:
- /Org mode buffers/ ::
- For Org files, if there is a =<<target>>= at the cursor, the link
+ For Org files, if there is a =<<target>>= at point, the link
points to the target. Otherwise it points to the current
headline, which is also the description[fn:28].
@@ -3295,7 +3294,7 @@ current buffer:
- /Web browsers: W3, W3M and EWW/ ::
- Here the link is the current URL, with the page title as
+ Here the link is the current URL, with the page title as the
description.
- /Contacts: BBDB/ ::
@@ -3315,18 +3314,16 @@ current buffer:
For any other file, the link points to the file, with a search
string (see [[*Search Options in File Links]]) pointing to the
contents of the current line. If there is an active region, the
- selected words form the basis of the search string. If the
- automatically created link is not working correctly or accurately
- enough, you can write custom functions to select the search
- string and to do the search for particular file types (see
- [[*Custom Searches]]).
+ selected words form the basis of the search string. You can write
+ custom Lisp functions to select the search string and perform the
+ search for particular file types (see [[*Custom Searches]]).
You can also define dedicated links to other files. See [[*Adding
Hyperlink Types]].
- /Agenda view/ ::
- When the cursor is in an agenda view, the created link points to
+ When point is in an agenda view, the created link points to
the entry referenced by the current line.
From an Org buffer, the following commands create, navigate or, more
@@ -3385,7 +3382,7 @@ generally, act on links.
- {{{kbd(C-c C-l)}}} (with cursor on existing link) ::
#+cindex: following links
- When the cursor is on an existing link, {{{kbd(C-c C-l)}}} allows
+ When point is on an existing link, {{{kbd(C-c C-l)}}} allows
you to edit the link and description parts of the link.
- {{{kbd(C-c C-o)}}} (~org-open-at-point~) ::
@@ -3396,8 +3393,8 @@ generally, act on links.
Open link at point. This launches a web browser for URL (using
~browse-url-at-point~), run VM/MH-E/Wanderlust/Rmail/Gnus/BBDB
for the corresponding links, and execute the command in a shell
- link. When the cursor is on an internal link, this command runs
- the corresponding search. When the cursor is on a TAG list in
+ link. When point is on an internal link, this command runs
+ the corresponding search. When point is on a TAG list in
a headline, it creates the corresponding TAGS view. If the
cursor is on a timestamp, it compiles the agenda for that date.
Furthermore, it visits text and remote files in =file= links with
@@ -3409,7 +3406,7 @@ generally, act on links.
C-u)}}} prefix.
#+vindex: org-link-frame-setup
- If the cursor is on a headline, but not on a link, offer all
+ If point is on a headline, but not on a link, offer all
links in the headline and entry text. If you want to setup the
frame configuration for following links, customize
~org-link-frame-setup~.
@@ -3455,7 +3452,7 @@ generally, act on links.
#+kindex: C-c %
#+findex: org-mark-ring-push
#+cindex: mark ring
- Push the current position onto the mark ring, to be able to
+ Push the current position onto the Org mark ring, to be able to
return easily. Commands following an internal link do this
automatically.
@@ -3536,14 +3533,15 @@ replacement text. Here is an example:
If the replacement text contains the string =%s=, it is replaced with
the tag. Using =%h= instead of =%s= percent-encodes the tag (see the
example above, where we need to encode the URL parameter). Using
-=%(my-function)= passes the tag to a custom function, and replace it
-by the resulting string.
+=%(my-function)= passes the tag to a custom Lisp function, and replace
+it by the resulting string.
If the replacement text do not contain any specifier, it is simply
appended to the string 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.
+Instead of a string, you may also specify a Lisp function to create
+the link. Such a function will be called with the tag as the only
+argument.
With the above setting, you could link to a specific bug with
=[[bugzilla:129]]=, search the web for =OrgMode= with =[[google:OrgMode]]=,
@@ -3563,11 +3561,11 @@ can define them in the file with
#+texinfo: @noindent
In-buffer completion (see [[*Completion]]) can be used after =[= to
-complete link abbreviations. You may also define a function that
-implements special (e.g., completion) support for inserting such
-a link with {{{kbd(C-c C-l)}}}. Such a function should not accept any
-arguments, and return the full link with prefix. You can set the link
-completion function like this:
+complete link abbreviations. You may also define a Lisp function that
+implements special (e.g., completion) support for inserting such a
+link with {{{kbd(C-c C-l)}}}. Such a function should not accept any
+arguments, and should return the full link with a prefix. You can set
+the link completion function like this:
#+begin_src emacs-lisp
(org-link-set-parameter "type" :complete #'some-completion-function)
@@ -3590,7 +3588,7 @@ as a search string that can be used to find this line back later when
following the link with {{{kbd(C-c C-o)}}}.
Here is the syntax of the different ways to attach a search to a file
-link, together with an explanation:
+link, together with explanations for each:
#+begin_example
[[file:~/code/main.c::255]]
@@ -3971,7 +3969,7 @@ buffer and then use {{{kbd(M-TAB)}}} completion.
Remember that the keywords after the vertical bar---or the last
keyword if no bar is there---must always mean that the item is DONE,
although you may use a different word. After changing one of these
-lines, use {{{kbd(C-c C-c)}}} with the cursor still in the line to
+lines, use {{{kbd(C-c C-c)}}} with point still in the line to
make the changes known to Org mode[fn:41].
*** Faces for TODO keywords
@@ -4525,7 +4523,7 @@ The following commands work with checkboxes:
first. With a prefix argument, add or remove the checkbox for
all items in the region.
- - If the cursor is in a headline, toggle checkboxes in the region
+ - If point is in a headline, toggle checkboxes in the region
between this headline and the next---so /not/ the entire
subtree.
@@ -4536,7 +4534,7 @@ The following commands work with checkboxes:
#+kindex: M-S-RET
#+findex: org-insert-todo-heading
- Insert a new item with a checkbox. This works only if the cursor
+ Insert a new item with a checkbox. This works only if point
is already in a plain list item (see [[*Plain Lists]]).
- {{{kbd(C-c C-x o)}}} (~org-toggle-ordered-property~) ::
@@ -4669,7 +4667,7 @@ also a special command for inserting tags:
- {{{kbd(C-c C-c)}}} (~org-set-tags-command~) ::
#+kindex: C-c C-c
- When the cursor is in a headline, this does the same as
+ When point is in a headline, this does the same as
{{{kbd(C-c C-q)}}}.
#+vindex: org-complete-tags-always-offer-all-agenda-tags
@@ -4747,7 +4745,7 @@ you indicate that at most one of =@work=, =@home=, and =@tennisclub=
should be selected. Multiple such groups are allowed.
#+texinfo: @noindent
-Do not forget to press {{{kbd(C-c C-c)}}} with the cursor in one of
+Do not forget to press {{{kbd(C-c C-c)}}} with point in one of
these lines to activate any changes.
#+texinfo: @noindent
@@ -5130,7 +5128,7 @@ The following commands help to work with properties:
#+kindex: C-c C-c
#+findex: org-property-action
- With the cursor in a property drawer, this executes property
+ With point in a property drawer, this executes property
commands.
- {{{kbd(C-c C-c s)}}} (~org-set-property~) ::
@@ -5491,9 +5489,9 @@ either for all clocks or just for today.
#+kindex: C-c C-x C-c
#+vindex: org-columns
#+vindex: org-columns-default-format
- Turn on column view. If the cursor is before the first headline
+ Turn on column view. If point is before the first headline
in the file, column view is turned on for the entire file, using
- the =#+COLUMNS= definition. If the cursor is somewhere inside
+ the =#+COLUMNS= definition. If point is somewhere inside
the outline, this command searches the hierarchy, up from point,
for a =COLUMNS= property that defines a format. When one is
found, the column view table is established for the tree starting
@@ -5685,7 +5683,7 @@ The following commands insert or update the dynamic block:
#+kindex: C-c C-c
#+kindex: C-c C-x C-u
#+findex: org-dblock-update
- Update dynamic block at point. The cursor needs to be in the
+ Update dynamic block at point. point needs to be in the
=#+BEGIN= line of the dynamic block.
- {{{kbd(C-u C-c C-x C-u)}}} (~org-update-all-dblocks~) ::
@@ -5858,7 +5856,7 @@ format.
#+kindex: C-c <
#+findex: org-date-from-calendar
- Insert a timestamp corresponding to the cursor date in the
+ Insert a timestamp corresponding to point date in the
calendar.
- {{{kbd(C-c >)}}} (~org-goto-calendar~) ::
@@ -5891,12 +5889,12 @@ format.
#+kindex: S-UP
#+kindex: S-DOWN
On the beginning or enclosing bracket of a timestamp, change its
- type. Within a timestamp, change the item under the cursor. The
+ type. Within a timestamp, change the item under point. The
cursor can be on a year, month, day, hour or minute. When the
timestamp contains a time range like =15:30-16:30=, modifying the
first time also shifts the second, shifting the time block with
constant length. To change the length, modify the second time.
- Note that if the cursor is in a headline and not at a timestamp,
+ Note that if point is in a headline and not at a timestamp,
these same keys modify the priority of an item (see [[*Priorities]]).
The key bindings also conflict with shift-selection and related
modes (see [[*Packages that conflict with Org mode]]).
@@ -6059,11 +6057,11 @@ date/time format does not /replace/ the default format. Instead, it
is put /over/ the default format using text properties. This has the
following consequences:
-- You cannot place the cursor onto a timestamp anymore, only before or
+- You cannot place point onto a timestamp anymore, only before or
after.
- The {{{kbd(S-UP)}}} and {{{kbd(S-DOWN)}}} keys can no longer be used
- to adjust each component of a timestamp. If the cursor is at the
+ to adjust each component of a timestamp. If point is at the
beginning of the stamp, {{{kbd(S-UP)}}} and {{{kbd(S-DOWN)}}} change
the stamp by one day, just like {{{kbd(S-LEFT)}}}
{{{kbd(S-RIGHT)}}}. At the end of the stamp, change the time by one
@@ -6208,7 +6206,7 @@ schedule an item:[fn:66]
#+findex: org-mark-entry-for-agenda-action
Mark the current entry for agenda action. After you have marked
the entry like this, you can open the agenda or the calendar to
- find an appropriate date. With the cursor on the selected date,
+ find an appropriate date. With point on the selected date,
press {{{kbd(k s)}}} or {{{kbd(k d)}}} to schedule the marked
item.
@@ -6550,7 +6548,7 @@ formatted as one or several Org tables.
#+kindex: C-c C-c
#+kindex: C-c C-x C-u
#+findex: org-dblock-update
- Update dynamic block at point. The cursor needs to be in the
+ Update dynamic block at point. point needs to be in the
=BEGIN= line of the dynamic block.
- {{{kbd(C-u C-c C-x C-u)}}} ::
@@ -7118,7 +7116,7 @@ You may also define a global key for capturing new material (see
#+findex: org-capture-refile
Finalize the capture process by refiling the note to a different
place (see [[*Refile and Copy]]). Please realize that this is
- a normal refiling command that will be executed---so the cursor
+ a normal refiling command that will be executed---so point
position at the moment you run this command is important. If you
have inserted a tree with a parent and children, first move the
cursor back to the parent. Any prefix argument given to this
@@ -7306,7 +7304,7 @@ Now lets look at the elements of a template definition. Each entry in
- =(file+regexp "filename" "regexp to find location")= ::
- Use a regular expression to position the cursor.
+ Use a regular expression to position point.
- =(file+olp+datetree "filename" [ "Level 1 heading" ...])= ::
@@ -8093,7 +8091,7 @@ file, the archive file.
#+kindex: C-c $
#+findex: org-archive-subtree
#+vindex: org-archive-location
- Archive the subtree starting at the cursor position to the
+ Archive the subtree starting at point position to the
location given by ~org-archive-location~.
- {{{kbd(C-u C-c C-x C-s)}}} ::
@@ -8102,7 +8100,7 @@ file, the archive file.
Check if any direct children of the current headline could be
moved to the archive. To do this, check each subtree for open
TODO entries. If none is found, the command offers to move it to
- the archive location. If the cursor is /not/ on a headline when
+ the archive location. If point is /not/ on a headline when
this command is invoked, check level 1 trees.
- {{{kbd(C-u C-u C-c C-x C-s)}}} ::
@@ -8202,7 +8200,7 @@ The following commands help manage the =ARCHIVE= tag:
Check if any direct children of the current headline should be
archived. To do this, check each subtree for open TODO entries.
If none is found, the command offers to set the =ARCHIVE= tag for
- the child. If the cursor is /not/ on a headline when this
+ the child. If point is /not/ on a headline when this
command is invoked, check the level 1 trees.
- {{{kbd(C-TAB)}}} (~org-force-cycle-archived~) ::
@@ -8341,7 +8339,7 @@ scope for an extended period, use the following commands:
#+findex: org-agenda-set-restriction-lock
Restrict the agenda to the current subtree. If there already is
a restriction at point, remove it. When called with a universal
- prefix argument or with the cursor before the first headline in a
+ prefix argument or with point before the first headline in a
file, set the agenda scope to the entire file. This restriction
remains in effect until removed with {{{kbd(C-c C-x >)}}}, or by typing
either {{{kbd(<)}}} or {{{kbd(>)}}} in the agenda dispatcher. If there is a
@@ -8362,7 +8360,7 @@ the Speedbar frame:
#+findex: org-speedbar-set-agenda-restriction
Restrict the agenda to the item---either an Org file or a subtree
- in such a file---at the cursor in the Speedbar frame. If agenda
+ in such a file---at point in the Speedbar frame. If agenda
is already restricted there, remove the restriction. If there is
a window displaying an agenda view, the new restriction takes
effect immediately.
@@ -9337,7 +9335,7 @@ agenda buffer. In this way, all information is stored only once,
removing the risk that your agenda and note files may diverge.
Some commands can be executed with mouse clicks on agenda lines. For
-the other commands, the cursor needs to be in the desired line.
+the other commands, point needs to be in the desired line.
*** Motion
:PROPERTIES:
@@ -9394,7 +9392,7 @@ the other commands, the cursor needs to be in the desired line.
#+kindex: F
#+findex: org-agenda-follow-mode
#+vindex: org-agenda-start-with-follow-mode
- Toggle Follow mode. In Follow mode, as you move the cursor
+ Toggle Follow mode. In Follow mode, as you move point
through the agenda buffer, the other window always shows the
corresponding location in the Org file. The initial setting for
this mode in new agenda buffers can be set with the variable
@@ -10058,14 +10056,14 @@ the other commands, the cursor needs to be in the desired line.
#+kindex: c
#+findex: org-calendar-goto-agenda
When in the calendar, compute and show the Org agenda for the
- date at the cursor.
+ date at point.
- {{{kbd(i)}}} (~org-agenda-diary-entry~) ::
#+kindex: i
#+findex: org-agenda-diary-entry
#+cindex: diary entries, creating from agenda
- Insert a new entry into the diary, using the date at the cursor
+ Insert a new entry into the diary, using the date at point
and (for block entries) the date at the mark. This adds to the
Emacs diary file[fn:98], in a way similar to the {{{kbd(i)}}}
command in the calendar. The diary file pops up in another
@@ -10110,7 +10108,7 @@ the other commands, the cursor needs to be in the desired line.
#+kindex: H
#+findex: org-agenda-holidays
- Show holidays for three months around the cursor date.
+ Show holidays for three months around point date.
*** Quit and exit
:PROPERTIES:
@@ -11037,7 +11035,7 @@ images.
point, process all fragments in the current entry (between two
headlines). When called with a prefix argument, process the
entire subtree. When called with two prefix arguments, or when
- the cursor is before the first headline, process the entire
+ point is before the first headline, process the entire
buffer.
#+vindex: org-startup-with-latex-preview
@@ -11083,9 +11081,9 @@ more details see the documentation of CDLaTeX mode):
- {{{kbd(TAB)}}} ::
#+kindex: TAB
- The {{{kbd(TAB)}}} key expands the template if the cursor is
+ The {{{kbd(TAB)}}} key expands the template if point is
inside a LaTeX fragment[fn:115]. For example, {{{kbd(TAB)}}}
- expands =fr= to =\frac{}{}= and position the cursor correctly
+ expands =fr= to =\frac{}{}= and position point correctly
inside the first brace. Another {{{kbd(TAB)}}} gets you into the
second brace.
@@ -11236,10 +11234,10 @@ further alter what is exported, and how.
#+kindex: C-c C-e C-s
Toggle sub-tree export. When turned on, Org exports only the
- sub-tree starting from the cursor position at the time the export
+ sub-tree starting from point position at the time the export
dispatcher was invoked. Org uses the top heading of this
- sub-tree as the document's title. If the cursor is not on
- a heading, Org uses the nearest enclosing header. If the cursor
+ sub-tree as the document's title. If point is not on
+ a heading, Org uses the nearest enclosing header. If point
is in the document preamble, Org signals an error and aborts
export.
@@ -18288,7 +18286,7 @@ key chords.
#+vindex: org-use-speed-commands
By default, Org has Speed Keys disabled. To activate Speed Keys, set
the variable ~org-use-speed-commands~ to a non-~nil~ value. To
-trigger a Speed Key, the cursor must be at the beginning of an Org
+trigger a Speed Key, point must be at the beginning of an Org
headline, before any of the stars.
#+vindex: org-speed-commands-user
@@ -18480,7 +18478,7 @@ changes.
also parses and loads the document during normal exporting
process. Org parses the contents of this document as if it was
included in the buffer. It can be another Org file. To visit
- the file---not a URL---use {{{kbd(C-c ')}}} while the cursor is
+ the file---not a URL---use {{{kbd(C-c ')}}} while point is
on the line with the file name.
- =#+STARTUP:= ::
@@ -18776,42 +18774,42 @@ manual, but here is a consolidated list for easy reference.
- If any highlights shown in the buffer from the creation of a sparse
tree, or from clock display, remove such highlights.
-- If the cursor is in one of the special =KEYWORD= lines, scan the
+- If point is in one of the special =KEYWORD= lines, scan the
buffer for these lines and update the information. Also reset the
Org file cache used to temporary store the contents of URLs used as
values for keywords like =SETUPFILE=.
-- If the cursor is inside a table, realign the table. The table
+- If point is inside a table, realign the table. The table
realigns even if automatic table editor is turned off.
-- If the cursor is on a =TBLFM= keyword, re-apply the formulas to the
+- If point is on a =TBLFM= keyword, re-apply the formulas to the
entire table.
- If the current buffer is a capture buffer, close the note and file
it. With a prefix argument, also jump to the target location after
saving the note.
-- If the cursor is on a =<<<target>>>=, update radio targets and
+- If point is on a =<<<target>>>=, update radio targets and
corresponding links in this buffer.
-- If the cursor is on a property line or at the start or end of
+- If point is on a property line or at the start or end of
a property drawer, offer property commands.
-- If the cursor is at a footnote reference, go to the corresponding
+- If point is at a footnote reference, go to the corresponding
definition, and /vice versa/.
-- If the cursor is on a statistics cookie, update it.
+- If point is on a statistics cookie, update it.
-- If the cursor is in a plain list item with a checkbox, toggle the
+- If point is in a plain list item with a checkbox, toggle the
status of the checkbox.
-- If the cursor is on a numbered item in a plain list, renumber the
+- If point is on a numbered item in a plain list, renumber the
ordered list.
-- If the cursor is on the =#+BEGIN= line of a dynamic block, the block
+- If point is on the =#+BEGIN= line of a dynamic block, the block
is updated.
-- If the cursor is at a timestamp, fix the day name in the timestamp.
+- If point is at a timestamp, fix the day name in the timestamp.
** A Cleaner Outline View
:PROPERTIES:
@@ -19046,7 +19044,7 @@ packages are documented here.
#+kindex: C-c '
#+findex: org-edit-special
- Edit a =table.el= table. Works when the cursor is in
+ Edit a =table.el= table. Works when point is in
a =table.el= table.
- {{{kbd(C-c ~)}}} (~org-table-create-with-table.el~) ::
@@ -19076,7 +19074,7 @@ not do anything, Org offers the variable ~org-support-shift-select~
for customization. Org mode accommodates shift selection by (i)
making it available outside of the special contexts where special
commands apply, and (ii) extending an existing active region even if
-the cursor moves across a special context.
+point moves across a special context.
- =cua.el= by Kim\nbsp{}F.\nbsp{}Storm ::
@@ -20098,13 +20096,13 @@ entry point for this API is:
Call {{{(var(FUNC))}}} at each headline selected by {{{var(MATCH)}}}
in {{{var(SCOPE)}}}.
-{{{var(FUNC)}}} is a function or a Lisp form. With the cursor
+{{{var(FUNC)}}} is a function or a Lisp form. With point
positioned at the beginning of the headline, call the function without
arguments. Org returns an alist of return values of calls to the
function.
To avoid preserving point, Org wraps the call to {{{var(FUNC)}}} in
-save-excursion form. After evaluation, Org moves the cursor to the
+save-excursion form. After evaluation, Org moves point to the
end of the line that was just processed. Search continues from that
point forward. This may not always work as expected under some
conditions, such as if the current sub-tree was removed by a previous
@@ -20329,7 +20327,7 @@ Org integrates its data in an inbox file format.
3. Org generates an agenda view for flagged entries for user
intervention to clean up. For notes stored in flagged entries,
- MobileOrg displays them in the echo area when the cursor is on the
+ MobileOrg displays them in the echo area when point is on the
corresponding agenda item.
- {{{kbd(?)}}} ::
@@ -20916,7 +20914,7 @@ can be used. Just type a star followed by a few optional letters into
the buffer and press {{{kbd(M-TAB)}}}. All headlines in the current
buffer are offered as completions.
-[fn:26] When targeting a =NAME= keyword, =CAPTION= keyword is
+[fn:26] When targeting a =NAME= keyword, the =CAPTION= keyword is
mandatory in order to get proper numbering (see [[*Images and Tables]]).
[fn:27] The actual behavior of the search depends on the value of the
@@ -20941,8 +20939,8 @@ automatically enclosed in double brackets, and you will be asked for
the optional descriptive text.
[fn:31] After insertion of a stored link, the link will be removed
-from the list of stored links. To keep it in the list later use, use
-a triple {{{kbd(C-u)}}} prefix argument to {{{kbd(C-c C-l)}}}, or
+from the list of stored links. To keep it in the list for later use,
+use a triple {{{kbd(C-u)}}} prefix argument to {{{kbd(C-c C-l)}}}, or
configure the option ~org-keep-stored-link-after-insertion~.
[fn:32] This works if a function has been defined in the ~:complete~
@@ -20976,7 +20974,7 @@ that this means you need to come up with unique keys across both sets
of keywords.
[fn:41] Org mode parses these lines only when Org mode is activated
-after visiting a file. {{{kbd(C-c C-c)}}} with the cursor in a line
+after visiting a file. {{{kbd(C-c C-c)}}} with point in a line
starting with =#+= is simply restarting Org mode for the current
buffer.
@@ -21258,7 +21256,7 @@ used to create images, any LaTeX environment is handled.
and from the ImageMagick suite. Choose the converter by setting the
variable ~org-preview-latex-default-process~ accordingly.
-[fn:115] Org mode has a method to test if the cursor is inside such
+[fn:115] Org mode has a method to test if point is inside such
a fragment, see the documentation of the function
~org-inside-LaTeX-fragment-p~.
--
2.17.1
^ permalink raw reply related [flat|nested] 9+ messages in thread
* Re: Org Mode Documentation Patch
2018-06-23 2:23 Siraphob (Ben) Phipathananunth
@ 2018-06-23 7:36 ` Nicolas Goaziou
2018-06-23 13:28 ` Siraphob (Ben) Phipathananunth
0 siblings, 1 reply; 9+ messages in thread
From: Nicolas Goaziou @ 2018-06-23 7:36 UTC (permalink / raw)
To: Siraphob (Ben) Phipathananunth; +Cc: emacs-orgmode
Hello,
"Siraphob (Ben) Phipathananunth" <siraben@disroot.org> writes:
> I've begun reading the Org Mode manual, and noticed that the wording
> in some places could be improved (so far I've read up to Section 4.8).
> I've attached my patch. Some of the more drastic changes:
>
> - Changed all occurrences of "the cursor" to "point", I thought the
> inconsistency was confusing, especially since the Emacs manual
> maintains usage of "point" throughout, so too should the Org Mode
> manual.
Thank you. I applied your patch.
I'm not totally convinced by the change from "function" to "Lisp
function", since, in the context of Org, an Elisp library, there is no
ambiguity. But I have no strong opinion, so I didn't remove the
occurrences in your patch.
BTW, what is your status wrt FSF papers?
> Section 4.6 "Link abbreviations" in the Org Mode manual link to
> websites that have and/or promote non-free software. The URLs are
> used to illustrate link abbreviations in Org Mode, but I suppose this
> was purely coincidental because long URLs to websites such as
> gnu.org/some/long/path could be used instead. Would it be appropriate
> to change the examples in a later patch?
Sure. However, for the sake of clarity, it would be better if not all
examples are similar, i.e., no "gnu.org/some/long/path" everywhere.
> When the PDF version of the Org Mode manual is generated with "make
> docs", the footnotes (3 and 4) around Section 4.3 are incorrectly
> indented, can anyone reproduce this?
I don't see anything like that in the PDF. You may want to try deleting
it and re-generate it.
> Should I submit my patches as smaller ones as I read sections of the
> manual or bulk them together into a larger patch, or is it just a
> matter of preference?
As you wish.
> Please let me know if you have any comments about the patch. It's my
> first one, I hope I have followed the CONTRIBUTING guide properly.
I fixed a couple of missing capitalization (point at the beginning of
a sentence) and filled modified paragraphs. I also slightly modified
your commit message.
Regards,
--
Nicolas Goaziou
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: Org Mode Documentation Patch
2018-06-23 7:36 ` Nicolas Goaziou
@ 2018-06-23 13:28 ` Siraphob (Ben) Phipathananunth
2018-06-23 13:47 ` Nicolas Goaziou
0 siblings, 1 reply; 9+ messages in thread
From: Siraphob (Ben) Phipathananunth @ 2018-06-23 13:28 UTC (permalink / raw)
To: Nicolas Goaziou; +Cc: emacs-orgmode
Thank you very much for accepting the patch.
Nicolas Goaziou wrote:
> BTW, what is your status wrt FSF papers?
I just sent an email to assign@gnu.org with my information, how will I know when copyright assign is completed?
Thank you again,
--
Siraphob (Ben) Phipathananunth
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: Org Mode Documentation Patch
2018-06-23 13:28 ` Siraphob (Ben) Phipathananunth
@ 2018-06-23 13:47 ` Nicolas Goaziou
2018-06-25 14:35 ` Siraphob (Ben) Phipathananunth
0 siblings, 1 reply; 9+ messages in thread
From: Nicolas Goaziou @ 2018-06-23 13:47 UTC (permalink / raw)
To: Siraphob (Ben) Phipathananunth; +Cc: emacs-orgmode
"Siraphob (Ben) Phipathananunth" <siraben@disroot.org> writes:
> I just sent an email to assign@gnu.org with my information,
Great!
> how will I know when copyright assign is completed?
They will let you know. Then, you may let me know. :)
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: Org Mode Documentation Patch
2018-06-23 13:47 ` Nicolas Goaziou
@ 2018-06-25 14:35 ` Siraphob (Ben) Phipathananunth
2018-06-25 14:54 ` Nicolas Goaziou
0 siblings, 1 reply; 9+ messages in thread
From: Siraphob (Ben) Phipathananunth @ 2018-06-25 14:35 UTC (permalink / raw)
To: Nicolas Goaziou; +Cc: emacs-orgmode
[-- Attachment #1: Type: text/plain, Size: 363 bytes --]
I've printed, signed, scanned and sent the assignment to assign@gnu.org
, waiting for their response.
In the meantime, please install another patch I wrote, attached.
You may notice that the email and name of the patch author is different,
this is to correspond with my email and legal name. ("Ben" is my nickname)
Thanks,
--
Siraphob (Ben) Phipathananunth
[-- Attachment #2: 0001-Fix-cursor-to-point-fix-grammar-and-add-cross-refere.patch --]
[-- Type: text/plain, Size: 34644 bytes --]
From 677ac08a5b11157f59dd5acc73a2bc7103344f22 Mon Sep 17 00:00:00 2001
From: Siraphob Phipathananunth <siraben@disroot.org>
Date: Mon, 25 Jun 2018 21:27:05 +0700
Subject: [PATCH] Fix "cursor" to "point", fix grammar and add cross-references
* doc/org-manual : More wording and grammar is fixed, cross-references
to other sections are added when key terms appear (e.g. agenda,
property, completion).
---
doc/org-manual.org | 323 ++++++++++++++++++++++-----------------------
1 file changed, 161 insertions(+), 162 deletions(-)
diff --git a/doc/org-manual.org b/doc/org-manual.org
index f1180458a..caa23be83 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -1145,8 +1145,7 @@ to disable them individually.
indentation. When these commands are executed several times in
direct succession, the initially selected region is used, even if
the new indentation would imply a different hierarchy. To use
- the new hierarchy, break the command chain with a cursor motion
- or so.
+ the new hierarchy, break the command chain by moving point.
As a special case, using this command on the very first item of
a list moves the whole list. This behavior can be disabled by
@@ -1194,7 +1193,7 @@ to disable them individually.
#+vindex: org-support-shift-select
#+kindex: S-LEFT
#+kindex: S-RIGHT
- This command also cycles bullet styles when point in on the
+ This command also cycles bullet styles when point is in on the
bullet or anywhere in an item line, details depending on
~org-support-shift-select~.
@@ -1683,7 +1682,7 @@ you, configure the option ~org-table-auto-blank-field~.
#+vindex: org-table-copy-increment
When current field is empty, copy from first non-empty field
above. When not empty, copy current field down to next row and
- move cursor along with it. Depending on the variable
+ move point along with it. Depending on the variable
~org-table-copy-increment~, integer field values can be
incremented during copy. Integers that are too large are not
incremented, however. Also, a ~0~ prefix argument temporarily
@@ -1919,10 +1918,10 @@ to derive fields from other fields. While fully featured, Org's
implementation is not identical to other spreadsheets. For example,
Org knows the concept of a /column formula/ that will be applied to
all non-header fields in a column without having to copy the formula
-to each relevant field. There is also a formula debugger, and
-a formula editor with features for highlighting fields in the table
-corresponding to the references at the point in the formula, moving
-these references by arrow keys.
+to each relevant field. There is also a formula debugger, and a
+formula editor with features for highlighting fields in the table
+corresponding to the references at point in the formula, moving these
+references by arrow keys.
*** References
:PROPERTIES:
@@ -3376,7 +3375,7 @@ generally, act on links.
possible with =~/= for your home directory. You can force an
absolute path with two {{{kbd(C-u)}}} prefixes.
-- {{{kbd(C-c C-l)}}} (with cursor on existing link) ::
+- {{{kbd(C-c C-l)}}} (with point on existing link) ::
#+cindex: following links
When point is on an existing link, {{{kbd(C-c C-l)}}} allows
@@ -3391,11 +3390,11 @@ generally, act on links.
~browse-url-at-point~), run VM/MH-E/Wanderlust/Rmail/Gnus/BBDB
for the corresponding links, and execute the command in a shell
link. When point is on an internal link, this command runs the
- corresponding search. When point is on the tags part of
- a headline, it creates the corresponding tags view (see [[*Matching
- tags and properties]]). If the cursor is on a timestamp, it
- compiles the agenda for that date. Furthermore, it visits text
- and remote files in =file= links with Emacs and select a suitable
+ corresponding search. When point is on the tags part of a
+ headline, it creates the corresponding tags view (see [[*Matching
+ tags and properties]]). If point is on a timestamp, it compiles
+ the agenda for that date. Furthermore, it visits text and remote
+ files in =file= links with Emacs and select a suitable
application for local non-text files. Classification of files is
based on file extension only. See option ~org-file-apps~. If
you want to override the default application and visit the file
@@ -3867,14 +3866,13 @@ require action. Your setup would then look like this:
(sequence "|" "CANCELED")))
#+end_src
-The keywords should all be different, this helps Org mode to keep
-track of which subsequence should be used for a given entry. In this
-setup, {{{kbd(C-c C-t)}}} only operates within a subsequence, so it
-switches from =DONE= to (nothing) to =TODO=, and from =FIXED= to
-(nothing) to =REPORT=. Therefore you need a mechanism to initially
-select the correct sequence. Besides the obvious ways like typing
-a keyword or using completion, you may also apply the following
-commands:
+The keywords should all be different, this helps Org mode keep track
+of which subsequence should be used for a given entry. In this setup,
+{{{kbd(C-c C-t)}}} only operates within a sub-sequence, so it switches
+from =DONE= to (nothing) to =TODO=, and from =FIXED= to (nothing) to
+=REPORT=. Therefore you need a mechanism to initially select the
+correct sequence. In addition to typing a keyword or using completion
+(see [[*Completion]]), you may also apply the following commands:
#+attr_texinfo: :sep ,
- {{{kbd(C-u C-u C-c C-t)}}}, {{{kbd(C-S-RIGHT)}}}, {{{kbd(C-S-LEFT)}}} ::
@@ -3882,22 +3880,22 @@ commands:
#+kindex: C-S-RIGHT
#+kindex: C-S-LEFT
#+kindex: C-u C-u C-c C-t
- These keys jump from one TODO subset to the next. In the above
- example, {{{kbd(C-u C-u C-c C-t)}}} or {{{kbd(C-S-RIGHT)}}} would
- jump from =TODO= or =DONE= to =REPORT=, and any of the words in
- the second row to =CANCELED=. Note that the {{{kbd(C-S-)}}} key
- binding conflict with ~shift-selection-mode~ (see [[*Packages
- that conflict with Org mode]]).
+ These keys jump from one TODO sub-sequence to the next. In the
+ above example, {{{kbd(C-u C-u C-c C-t)}}} or {{{kbd(C-S-RIGHT)}}}
+ would jump from =TODO= or =DONE= to =REPORT=, and any of the
+ words in the second row to =CANCELED=. Note that the
+ {{{kbd(C-S-)}}} key binding conflict with ~shift-selection-mode~
+ (see [[*Packages that conflict with Org mode]]).
- {{{kbd(S-RIGHT)}}}, {{{kbd(S-LEFT)}}} ::
#+kindex: S-RIGHT
#+kindex: S-LEFT
{{{kbd(S-LEFT)}}} and {{{kbd(S-RIGHT)}}} walk through /all/
- keywords from all sets, so for example {{{kbd(S-RIGHT)}}} would
- switch from =DONE= to =REPORT= in the example above. For
- a discussion of the interaction with ~shift-selection-mode~, see
- [[*Packages that conflict with Org mode]].
+ keywords from all sub-sequences, so for example
+ {{{kbd(S-RIGHT)}}} would switch from =DONE= to =REPORT= in the
+ example above. For a discussion of the interaction with
+ ~shift-selection-mode~, see [[*Packages that conflict with Org mode]].
*** Fast access to TODO states
:PROPERTIES:
@@ -3943,7 +3941,7 @@ anywhere in the file:
: #+TODO: TODO FEEDBACK VERIFY | DONE CANCELED
#+texinfo: @noindent
-you may also write =#+SEQ_TODO= to be explicit about the
+You may also write =#+SEQ_TODO= to be explicit about the
interpretation, but it means the same as =#+TODO=, or
: #+TYP_TODO: Fred Sara Lucy Mike | DONE
@@ -3960,7 +3958,7 @@ A setup for using several sets in parallel would be:
#+kindex: M-TAB
#+texinfo: @noindent
To make sure you are using the correct keyword, type =#+= into the
-buffer and then use {{{kbd(M-TAB)}}} completion.
+buffer and then use {{{kbd(M-TAB)}}} to complete it (see [[*Completion]]).
#+cindex: DONE, final TODO keyword
Remember that the keywords after the vertical bar---or the last
@@ -4010,15 +4008,15 @@ a background color.
#+cindex: @samp{ORDERED}, property
The structure of Org files---hierarchy and lists---makes it easy to
define TODO dependencies. Usually, a parent TODO task should not be
-marked DONE until all TODO subtasks, defined as children tasks, are
-marked as DONE. And sometimes there is a logical sequence to a number
-of TODO (sub)tasks, so that one task cannot be acted upon before all
-siblings above it are done. If you customize the variable
-~org-enforce-todo-dependencies~, Org blocks entries from changing state
-to DONE while they have TODO children that are not DONE. Furthermore,
-if an entry has a property =ORDERED=, each of its TODO children is
-blocked until all earlier siblings are marked DONE. Here is an
-example:
+marked DONE until all TODO subtasks, or children tasks, are marked as
+DONE. Sometimes there is a logical sequence to (sub)tasks, so that one
+subtask cannot be acted upon before all siblings above it have been
+marked DONE. If you customize the variable
+~org-enforce-todo-dependencies~, Org blocks entries from changing
+state to DONE while they have TODO children that are not DONE.
+Furthermore, if an entry has a property =ORDERED=, each of its TODO
+children is blocked until all earlier siblings are marked DONE. Here
+is an example:
#+begin_example
,* TODO Blocked until (two) is done
@@ -4037,7 +4035,7 @@ example:
#+cindex: TODO dependencies, @samp{NOBLOCKING}
#+cindex: @samp{NOBLOCKING}, property
You can ensure an entry is never blocked by using the =NOBLOCKING=
-property:
+property (see [[* Properties and Columns]]):
#+begin_example
,* This entry is never blocked
@@ -4053,7 +4051,8 @@ property:
#+vindex: org-track-ordered-property-with-tag
Toggle the =ORDERED= property of the current entry. A property is
used for this behavior because this should be local to the
- current entry, not inherited from entries above like a tag.
+ current entry, not inherited from entries above like a tag (see
+ [[* Tags]]).
However, if you would like to /track/ the value of this property
with a tag for better visibility, customize the variable
~org-track-ordered-property-with-tag~.
@@ -4061,18 +4060,18 @@ property:
- {{{kbd(C-u C-u C-u C-c C-t)}}} ::
#+kindex: C-u C-u C-u C-c C-t
- Change TODO state, circumventing any state blocking.
+ Change TODO state, regardless of any state blocking.
#+vindex: org-agenda-dim-blocked-tasks
If you set the variable ~org-agenda-dim-blocked-tasks~, TODO entries
-that cannot be closed because of such dependencies are shown in
-a dimmed font or even made invisible in agenda views (see [[*Agenda
+that cannot be marked DONE because of unmarked children are shown in a
+dimmed font or even made invisible in agenda views (see [[*Agenda
Views]]).
#+cindex: checkboxes and TODO dependencies
#+vindex: org-enforce-todo-dependencies
-You can also block changes of TODO states by looking at checkboxes
-(see [[*Checkboxes]]). If you set the variable
+You can also block changes of TODO states by using checkboxes (see
+[[*Checkboxes]]). If you set the variable
~org-enforce-todo-checkbox-dependencies~, an entry that has unchecked
checkboxes is blocked from switching to DONE.
@@ -4087,12 +4086,12 @@ the contributed module =org-depend.el=.
#+cindex: progress logging
#+cindex: logging, of progress
-Org mode can automatically record a timestamp and possibly a note when
-you mark a TODO item as DONE, or even each time you change the state
-of a TODO item. This system is highly configurable, settings can be
-on a per-keyword basis and can be localized to a file or even
-a subtree. For information on how to clock working time for a task,
-see [[*Clocking Work Time]].
+Org mode can automatically record a timestamp and optionally a note
+when you mark a TODO item as DONE, or even each time you change the
+state of a TODO item. This system is highly configurable, settings
+can be on a per-keyword basis and can be localized to a file or even a
+subtree. For information on how to clock working time for a task, see
+[[*Clocking Work Time]].
*** Closing items
:PROPERTIES:
@@ -4100,7 +4099,7 @@ see [[*Clocking Work Time]].
:END:
The most basic logging is to keep track of /when/ a certain TODO item
-was finished. This is achieved with[fn:42]
+was marked DONE. This can be achieved with[fn:42]
#+begin_src emacs-lisp
(setq org-log-done 'time)
@@ -4136,15 +4135,14 @@ entry with a =Closing Note= heading.
#+cindex: @samp{LOG_INTO_DRAWER}, property
When TODO keywords are used as workflow states (see [[*TODO keywords as workflow states][*Workflow states]]),
you might want to keep track of when a state change occurred and maybe
-take a note about this change. You can either record just
-a timestamp, or a time-stamped note for a change. These records are
-inserted after the headline as an itemized list, newest first[fn:44].
-When taking a lot of notes, you might want to get the notes out of the
-way into a drawer (see [[*Drawers]]). Customize the variable
-~org-log-into-drawer~ to get this behavior---the recommended drawer
-for this is called =LOGBOOK=[fn:45]. You can also overrule the
-setting of this variable for a subtree by setting a =LOG_INTO_DRAWER=
-property.
+take a note about this change. You can either record just a
+timestamp, or a time-stamped note. These records are inserted after
+the headline as an itemized list, newest first[fn:44]. When taking a
+lot of notes, you might want to get the notes out of the way into a
+drawer (see [[*Drawers]]). Customize the variable ~org-log-into-drawer~
+to get this behavior---the recommended drawer for this is called
+=LOGBOOK=[fn:45]. You can also overrule the setting of this variable
+for a subtree by setting a =LOG_INTO_DRAWER= property.
Since it is normally too much to record a note for every state, Org
mode expects configuration on a per-keyword basis for this. This is
@@ -4212,29 +4210,29 @@ specific settings like =TODO(!)=. For example:
#+cindex: @samp{STYLE}, property
Org has the ability to track the consistency of a special category of
-TODO, called "habits." A habit has the following properties:
+TODO, called "habits." To use habits, you have to enable the ~habits~
+module by customizing the variable ~org-modules~.
-1. You have enabled the ~habits~ module by customizing the variable
- ~org-modules~.
+A habit has the following properties:
-2. The habit is a TODO item, with a TODO keyword representing an open
+1. The habit is a TODO item, with a TODO keyword representing an open
state.
-3. The property =STYLE= is set to the value =habit=.
+2. The property =STYLE= is set to the value =habit= (see [[*Properties and Columns]]).
-4. The TODO has a scheduled date, usually with a =.+= style repeat
+3. The TODO has a scheduled date, usually with a =.+= style repeat
interval. A =++= style may be appropriate for habits with time
constraints, e.g., must be done on weekends, or a =+= style for an
unusual habit that can have a backlog, e.g., weekly reports.
-5. The TODO may also have minimum and maximum ranges specified by
+4. The TODO may also have minimum and maximum ranges specified by
using the syntax =.+2d/3d=, which says that you want to do the task
at least every three days, but at most every two days.
-6. You must also have state logging for the DONE state enabled (see
- [[*Tracking TODO state changes]]), in order for historical data to be
- represented in the consistency graph. If it is not enabled it is
- not an error, but the consistency graphs are largely meaningless.
+5. State logging for the DONE state is enabled (see [[*Tracking TODO state changes]]),
+ in order for historical data to be represented in the consistency
+ graph. If it is not enabled it is not an error, but the
+ consistency graphs are largely meaningless.
To give you an idea of what the above rules look like in action, here's an
actual habit with some history:
@@ -4259,10 +4257,11 @@ actual habit with some history:
#+end_example
What this habit says is: I want to shave at most every 2 days---given
-by the =SCHEDULED= date and repeat interval---and at least every
-4 days. If today is the 15th, then the habit first appears in the
-agenda on Oct 17, after the minimum of 2 days has elapsed, and will
-appear overdue on Oct 19, after four days have elapsed.
+by the =SCHEDULED= date and repeat interval---and at least every 4
+days. If today is the 15th, then the habit first appears in the
+agenda (see [[* Agenda Views]]) on Oct 17, after the minimum of 2 days has
+elapsed, and will appear overdue on Oct 19, after four days have
+elapsed.
What's really useful about habits is that they are displayed along
with a consistency graph, to show how consistent you've been at
@@ -4303,8 +4302,8 @@ the way habits are displayed in the agenda.
- ~org-habit-show-habits-only-for-today~ ::
#+vindex: org-habit-show-habits-only-for-today
- If non-~nil~, only show habits in today's agenda view. This is
- set to true by default.
+ If non-~nil~, only show habits in today's agenda view. The
+ default value is ~t~.
Lastly, pressing {{{kbd(K)}}} in the agenda buffer causes habits to
temporarily be disabled and do not appear at all. Press {{{kbd(K)}}}
@@ -4329,11 +4328,12 @@ like this
#+vindex: org-priority-faces
#+texinfo: @noindent
By default, Org mode supports three priorities: =A=, =B=, and =C=.
-=A= is the highest priority. An entry without a cookie is treated
-just like priority =B=. Priorities make a difference only for sorting
-in the agenda (see [[*Weekly/daily agenda]]); outside the agenda, they
-have no inherent meaning to Org mode. The cookies can be highlighted
-with special faces by customizing the variable ~org-priority-faces~.
+=A= is the highest priority. An entry without a cookie is treated as
+equivalent if it had priority =B=. Priorities make a difference only
+for sorting in the agenda (see [[*Weekly/daily agenda]]); outside the
+agenda, they have no inherent meaning to Org mode. The cookies are
+displayed with the face defined by the variable ~org-priority-faces~,
+which can be customized.
Priorities can be attached to any outline node; they do not need to be
TODO items.
@@ -4345,10 +4345,10 @@ TODO items.
#+findex: org-priority
Set the priority of the current headline. The command prompts
for a priority character =A=, =B= or =C=. When you press
- {{{kbd(SPC)}}} instead, the priority cookie is removed from the
- headline. The priorities can also be changed "remotely" from the
- agenda buffer with the {{{kbd(\,)}}} command (see [[*Commands in
- the Agenda Buffer]]).
+ {{{kbd(SPC)}}} instead, the priority cookie, if one is set, is
+ removed from the headline. The priorities can also be changed
+ "remotely" from the agenda buffer with the {{{kbd(\,)}}} command
+ (see [[*Commands in the Agenda Buffer]]).
- {{{kbd(S-UP)}}} (~org-priority-up~); {{{kbd(S-DOWN)}}} (~org-priority-down~) ::
@@ -4357,10 +4357,11 @@ TODO items.
#+findex: org-priority-up
#+findex: org-priority-down
#+vindex: org-priority-start-cycle-with-default
- Increase/decrease priority of current headline[fn:47]. Note that
- these keys are also used to modify timestamps (see [[*Creating
- Timestamps]]). See also [[*Packages that conflict with Org mode]], for
- a discussion of the interaction with ~shift-selection-mode~.
+ Increase/decrease the priority of the current headline[fn:47].
+ Note that these keys are also used to modify timestamps (see
+ [[*Creating Timestamps]]). See also [[*Packages that conflict with Org
+ mode]], for a discussion of the interaction with
+ ~shift-selection-mode~.
#+vindex: org-highest-priority
#+vindex: org-lowest-priority
@@ -4386,10 +4387,10 @@ highest priority is earlier in the alphabet than the lowest priority):
It is often advisable to break down large tasks into smaller,
manageable subtasks. You can do this by creating an outline tree
below a TODO item, with detailed subtasks on the tree[fn:48]. To keep
-the overview over the fraction of subtasks that are already completed,
-insert either =[/]= or =[%]= anywhere in the headline. These cookies
-are updated each time the TODO status of a child changes, or when
-pressing {{{kbd(C-c C-c)}}} on the cookie. For example:
+an overview of the fraction of subtasks that have already been marked
+DONE, insert either =[/]= or =[%]= anywhere in the headline. These
+cookies are updated each time the TODO status of a child changes, or
+when pressing {{{kbd(C-c C-c)}}} on the cookie. For example:
#+begin_example
,* Organize Party [33%]
@@ -5435,7 +5436,7 @@ a more predictable delivery.
When combining a set of such estimates, simply adding the lows and
highs produces an unrealistically wide result. Instead, =est+= adds
-the statistical mean and variance of the sub-tasks, generating a final
+the statistical mean and variance of the subtasks, generating a final
estimate from the sum. For example, suppose you had ten tasks, each
of which was estimated at 0.5 to 2 days of work. Straight addition
produces an estimate of 5 to 20 days, representing what to expect if
@@ -5817,8 +5818,8 @@ format.
#+kindex: C-c .
#+findex: org-time-stamp
- Prompt for a date and insert a corresponding timestamp. When the
- cursor is at an existing timestamp in the buffer, the command is
+ Prompt for a date and insert a corresponding timestamp. When
+ point is at an existing timestamp in the buffer, the command is
used to modify this timestamp instead of inserting a new one.
When this command is used twice in succession, a time range is
inserted.
@@ -5875,19 +5876,18 @@ format.
#+kindex: S-RIGHT
#+findex: org-timestamp-down-day
#+findex: org-timestamp-up-day
- Change date at cursor by one day. These key bindings conflict
- with shift-selection and related modes (see [[*Packages that
- conflict with Org mode]]).
+ Change date at point by one day. These key bindings conflict
+ with shift-selection and related modes (see [[*Packages that conflict with Org mode]]).
- {{{kbd(S-UP)}}} (~org-timestamp-up~), {{{kbd(S-DOWN)}}} (~org-timestamp-down~) ::
#+kindex: S-UP
#+kindex: S-DOWN
On the beginning or enclosing bracket of a timestamp, change its
- type. Within a timestamp, change the item under point. The
- cursor can be on a year, month, day, hour or minute. When the
- timestamp contains a time range like =15:30-16:30=, modifying the
- first time also shifts the second, shifting the time block with
+ type. Within a timestamp, change the item under point. Point
+ can be on a year, month, day, hour or minute. When the timestamp
+ contains a time range like =15:30-16:30=, modifying the first
+ time also shifts the second, shifting the time block with
constant length. To change the length, modify the second time.
Note that if point is in a headline and not at a timestamp, these
same keys modify the priority of an item (see [[*Priorities]]). The
@@ -6004,18 +6004,18 @@ can control the calendar fully from the minibuffer:
#+kindex: M-S-LEFT
#+kindex: RET
#+attr_texinfo: :columns 0.25 0.55
-| {{{kbd(RET)}}} | Choose date at cursor in calendar. |
-| {{{kbd(mouse-1)}}} | Select date by clicking on it. |
-| {{{kbd(S-RIGHT)}}} | One day forward. |
-| {{{kbd(S-LEFT)}}} | One day backward. |
-| {{{kbd(S-DOWN)}}} | One week forward. |
-| {{{kbd(S-UP)}}} | One week backward. |
-| {{{kbd(M-S-RIGHT)}}} | One month forward. |
-| {{{kbd(M-S-LEFT)}}} | One month backward. |
-| {{{kbd(>)}}} | Scroll calendar forward by one month. |
-| {{{kbd(<)}}} | Scroll calendar backward by one month. |
-| {{{kbd(M-v)}}} | Scroll calendar forward by 3 months. |
-| {{{kbd(C-v)}}} | Scroll calendar backward by 3 months. |
+| {{{kbd(RET)}}} | Choose date at point in calendar. |
+| {{{kbd(mouse-1)}}} | Select date by clicking on it. |
+| {{{kbd(S-RIGHT)}}} | One day forward. |
+| {{{kbd(S-LEFT)}}} | One day backward. |
+| {{{kbd(S-DOWN)}}} | One week forward. |
+| {{{kbd(S-UP)}}} | One week backward. |
+| {{{kbd(M-S-RIGHT)}}} | One month forward. |
+| {{{kbd(M-S-LEFT)}}} | One month backward. |
+| {{{kbd(>)}}} | Scroll calendar forward by one month. |
+| {{{kbd(<)}}} | Scroll calendar backward by one month. |
+| {{{kbd(M-v)}}} | Scroll calendar forward by 3 months. |
+| {{{kbd(C-v)}}} | Scroll calendar backward by 3 months. |
#+vindex: org-read-date-display-live
The actions of the date/time prompt may seem complex, but I assure you
@@ -6117,8 +6117,8 @@ immediately after the task they refer to.
#+vindex: org-agenda-skip-scheduled-if-done
The headline is listed under the given date[fn:65]. In addition,
a reminder that the scheduled date has passed is present in the
- compilation for /today/, until the entry is marked DONE, i.e.,
- the task is automatically forwarded until completed.
+ compilation for /today/, until the entry is marked DONE, (i.e.
+ the task is automatically forwarded until completed).
#+begin_example
,*** TODO Call Trillian for a date on New Years Eve.
@@ -6262,8 +6262,8 @@ the repeater should come first and the warning period last: =DEADLINE:
#+vindex: org-todo-repeat-to-state
Deadlines and scheduled items produce entries in the agenda when they
are over-due, so it is important to be able to mark such an entry as
-completed once you have done so. When you mark a =DEADLINE= or
-a =SCHEDULED= with the TODO keyword =DONE=, it no longer produces
+DONE once you have done so. When you mark a =DEADLINE= or a
+=SCHEDULED= with the TODO keyword =DONE=, it no longer produces
entries in the agenda. The problem with this is, however, is that
then also the /next/ instance of the repeated entry will not be
active. Org mode deals with this in the following way: when you try
@@ -6531,11 +6531,10 @@ formatted as one or several Org tables.
#+kindex: C-c C-x C-r
#+findex: org-clock-report
Insert a dynamic block (see [[*Dynamic Blocks]]) containing a clock
- report as an Org mode table into the current file. When the
- cursor is at an existing clock table, just update it. When
- called with a prefix argument, jump to the first clock report in
- the current document and update it. The clock table includes
- archived trees.
+ report as an Org mode table into the current file. When point is
+ at an existing clock table, just update it. When called with a
+ prefix argument, jump to the first clock report in the current
+ document and update it. The clock table includes archived trees.
- {{{kbd(C-c C-c)}}} or {{{kbd(C-c C-x C-u)}}} (~org-dblock-update~) ::
@@ -6556,10 +6555,9 @@ formatted as one or several Org tables.
#+kindex: S-LEFT
#+kindex: S-RIGHT
#+findex: org-clocktable-try-shift
- Shift the current =:block= interval and update the table. The
- cursor needs to be in the =#+BEGIN: clocktable= line for this
- command. If =:block= is =today=, it is shifted to =today-1=,
- etc.
+ Shift the current =:block= interval and update the table. Point
+ needs to be in the =#+BEGIN: clocktable= line for this command.
+ If =:block= is =today=, it is shifted to =today-1=, etc.
Here is an example of the frame for a clock table as it is inserted
into the buffer with the {{{kbd(C-c C-x C-r)}}} command:
@@ -7112,12 +7110,12 @@ You may also define a global key for capturing new material (see
#+kindex: C-c C-w @r{(Capture buffer)}
#+findex: org-capture-refile
Finalize the capture process by refiling the note to a different
- place (see [[*Refile and Copy]]). Please realize that this is
- a normal refiling command that will be executed---so point
- position at the moment you run this command is important. If you
- have inserted a tree with a parent and children, first move the
- cursor back to the parent. Any prefix argument given to this
- command is passed on to the ~org-refile~ command.
+ place (see [[*Refile and Copy]]). Please realize that this is a
+ normal refiling command that will be executed---so point position
+ at the moment you run this command is important. If you have
+ inserted a tree with a parent and children, first move point back
+ to the parent. Any prefix argument given to this command is
+ passed on to the ~org-refile~ command.
- {{{kbd(C-c C-k)}}} (~org-capture-kill~) ::
@@ -7129,7 +7127,7 @@ You may also define a global key for capturing new material (see
You can also call ~org-capture~ in a special way from the agenda,
using the {{{kbd(k c)}}} key combination. With this access, any
timestamps inserted by the selected capture template defaults to the
-cursor date in the agenda, rather than to the current date.
+date at point in the agenda, rather than to the current date.
To find the locations of the last stored capture, use ~org-capture~
with prefix commands:
@@ -7527,7 +7525,7 @@ here:
- ~%?~ ::
- After completing the template, position cursor here.
+ After completing the template, position point here.
#+texinfo: @noindent
#+vindex: org-store-link-props
@@ -8575,12 +8573,12 @@ add the following to one of your agenda files:
#+end_example
You can then go ahead and define anniversaries for a BBDB record.
-Basically, you need to press {{{kbd(C-o anniversary RET)}}} with the
-cursor in a BBDB record and then add the date in the format
-=YYYY-MM-DD= or =MM-DD=, followed by a space and the class of the
-anniversary (=birthday=, =wedding=, or a format string). If you omit
-the class, it defaults to =birthday=. Here are a few examples, the
-header for the file =org-bbdb.el= contains more detailed information.
+Basically, you need to press {{{kbd(C-o anniversary RET)}}} with point
+in a BBDB record and then add the date in the format =YYYY-MM-DD= or
+=MM-DD=, followed by a space and the class of the anniversary
+(=birthday=, =wedding=, or a format string). If you omit the class,
+it defaults to =birthday=. Here are a few examples, the header for
+the file =org-bbdb.el= contains more detailed information.
#+begin_example
1973-06-22
@@ -10042,8 +10040,8 @@ the other commands, point needs to be in the desired line.
#+kindex: c
#+findex: org-agenda-goto-calendar
- Open the Emacs calendar and move to the date at the agenda
- cursor.
+ Open the Emacs calendar and go to the date at point in the
+ agenda.
- {{{kbd(c)}}} (~org-calendar-goto-agenda~) ::
@@ -10095,7 +10093,7 @@ the other commands, point needs to be in the desired line.
#+kindex: C
#+findex: org-agenda-convert-date
- Convert the date at cursor into many other cultural and historic
+ Convert the date at point into many other cultural and historic
calendars.
- {{{kbd(H)}}} (~org-agenda-holidays~) ::
@@ -18266,8 +18264,8 @@ init file[fn:138].
:END:
#+cindex: speed keys
-Single keystrokes can execute custom commands in an Org file when the
-cursor is on a headline. Without the extra burden of a meta or
+Single keystrokes can execute custom commands in an Org file when
+point is on a headline. Without the extra burden of a meta or
modifier key, Speed Keys can speed navigation or execute custom
commands. Besides faster navigation, Speed Keys may come in handy on
small mobile devices that do not have full keyboards. Speed Keys may
@@ -18286,7 +18284,7 @@ Org comes with a pre-defined list of Speed Keys. To add or modify
Speed Keys, customize the variable, ~org-speed-commands-user~. For
more details, see the variable's docstring. With Speed Keys
activated, {{{kbd(M-x org-speed-command-help)}}}, or {{{kbd(?)}}} when
-cursor is at the beginning of an Org headline, shows currently active
+point is at the beginning of an Org headline, shows currently active
Speed Keys, including the user-defined ones.
** Code Evaluation and Security Issues
@@ -18924,11 +18922,12 @@ headings as shown in examples below.
#+cindex: tty key bindings
Org provides alternative key bindings for TTY and modern mobile
-devices that cannot handle cursor keys and complex modifier key
-chords. Some of these workarounds may be more cumbersome than
-necessary. Users should look into customizing these further based on
-their usage needs. For example, the normal {{{kbd(S-<cursor>)}}} for
-editing timestamp might be better with {{{kbd(C-c .)}}} chord.
+devices that cannot perform movement commands on point and key
+bindings with modifier keys. Some of these workarounds may be more
+cumbersome than necessary. Users should look into customizing these
+further based on their usage needs. For example, the normal
+{{{kbd(S-<cursor>)}}} for editing timestamp might be better with
+{{{kbd(C-c .)}}} chord.
#+attr_texinfo: :columns 0.2 0.28 0.15 0.21
| Default | Alternative 1 | Speed key | Alternative 2 |
@@ -19056,7 +19055,7 @@ packages are documented here.
#+cindex: shift-selection-mode
#+vindex: org-support-shift-select
-In Emacs, ~shift-selection-mode~ combines cursor motions with shift
+In Emacs, ~shift-selection-mode~ combines motions of point with shift
key to enlarge regions. Emacs sets this mode by default. This
conflicts with Org's use of {{{kbd(S-<cursor>)}}} commands to change
timestamps, TODO keywords, priorities, and item bullet types, etc.
@@ -20986,7 +20985,7 @@ change recording note takes precedence and cancel the closing note.
[fn:47] See also the option ~org-priority-start-cycle-with-default~.
-[fn:48] To keep subtasks out of the global TODO list, see the
+[fn:48] To keep subtasks out of the global TODO list, see the option
~org-agenda-todo-list-sublevels~.
[fn:49] With the exception of description lists. But you can allow it
--
2.18.0
^ permalink raw reply related [flat|nested] 9+ messages in thread
* Re: Org Mode Documentation Patch
2018-06-25 14:35 ` Siraphob (Ben) Phipathananunth
@ 2018-06-25 14:54 ` Nicolas Goaziou
2018-06-25 16:01 ` Van L
0 siblings, 1 reply; 9+ messages in thread
From: Nicolas Goaziou @ 2018-06-25 14:54 UTC (permalink / raw)
To: Siraphob (Ben) Phipathananunth; +Cc: emacs-orgmode
Hello,
"Siraphob (Ben) Phipathananunth" <siraben@disroot.org> writes:
> I've printed, signed, scanned and sent the assignment to
> assign@gnu.org , waiting for their response.
Nice.
> In the meantime, please install another patch I wrote, attached.
Done, barring one hunk specified below.
> You may notice that the email and name of the patch author is
> different, this is to correspond with my email and legal name. ("Ben"
> is my nickname)
OK.
> - compilation for /today/, until the entry is marked DONE, i.e.,
> - the task is automatically forwarded until completed.
> + compilation for /today/, until the entry is marked DONE, (i.e.
> + the task is automatically forwarded until completed).
I wasn't convinced by this change so I didn't apply it. The former form
looks correct.
Thank you.
Regards,
--
Nicolas Goaziou
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: Org Mode Documentation Patch
2018-06-25 14:54 ` Nicolas Goaziou
@ 2018-06-25 16:01 ` Van L
0 siblings, 0 replies; 9+ messages in thread
From: Van L @ 2018-06-25 16:01 UTC (permalink / raw)
To: Nicolas Goaziou; +Cc: Org-mode
>> I've printed, signed, scanned and sent the assignment to
>> assign@gnu.org , waiting for their response.
>
> Nice.
It should be possible to do without printing and
scanning, do all of the assignment electronically.
^ permalink raw reply [flat|nested] 9+ messages in thread
end of thread, other threads:[~2018-06-25 16:02 UTC | newest]
Thread overview: 9+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2018-06-22 16:08 Org Mode Documentation Patch Ben Phipathananunth
2018-06-22 18:14 ` Eli Zaretskii
-- strict thread matches above, loose matches on Subject: below --
2018-06-23 2:23 Siraphob (Ben) Phipathananunth
2018-06-23 7:36 ` Nicolas Goaziou
2018-06-23 13:28 ` Siraphob (Ben) Phipathananunth
2018-06-23 13:47 ` Nicolas Goaziou
2018-06-25 14:35 ` Siraphob (Ben) Phipathananunth
2018-06-25 14:54 ` Nicolas Goaziou
2018-06-25 16:01 ` Van L
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.