From: Kyle Meyer <kyle@kyleam.com>
To: B Goodr <bgoodr@gmail.com>, emacs-orgmode@gnu.org
Subject: Re: Bug: Org manual: Structure Editing: Clarify commands which use the Transient Mark region [9.3.6 (9.3.6-23-g01ee25-elpaplus @ /tmp/.emacs.d.tmp.99712ad4-61f4-4464-b003-d6d4eea9b98f/org-plus-contrib-20200309/)]
Date: Sun, 15 Mar 2020 21:11:57 +0000 [thread overview]
Message-ID: <87v9n58grm.fsf@kyleam.com> (raw)
In-Reply-To: <CAJj=8EEVXUG0V1Qfr03JtqZWf0+=gD7WPYO=GjoPA+NqyN_PfQ@mail.gmail.com>
B Goodr <bgoodr@gmail.com> writes:
> The essential issue is this: The paragraph at the very bottom of the
> Structure Editing page of the manual is misleading: It leads a user to
> believe that all of the commands use the Transient Mark region, but some of
> them do not or should not.
I agree with your assessment, in particular that this comment could
easily be interpreted as applying to org-promote-subtree and
org-demote-subtree.
> One possibility to fix this is to mention, inside each described
> command in that page, which ones respect the region, and which ones do
> not, possibly using footnotes for more details.
Sounds good to me. As far as I can tell, this comment applies only to
org-do-promote and org-do-demote, so I think moving the comment into a
shared entry for those commands would make things clearer:
‘M-<LEFT>’ (‘org-do-promote’), ‘M-<RIGHT>’ (‘org-do-demote’)
Promote or demote current heading by one level.
When there is an active region—i.e., when Transient Mark mode is
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.
I'll apply the patch to do so in a day or two if no one raises an
objection.
Thanks for reporting the issue!
-- >8 --
Subject: [PATCH] manual: Clarify which structure editing commands use the
region
* doc/org-manual.org (Structure Editing): Combine org-do-promote and
org-do-demote into a single entry that includes the remark about their
treatment of an active region.
At the end of the structure editing node, there is a note that
promotion and demotion works on the region, if active, but that
applies only to org-do-demote and org-do-promote, not
org-promote-subtree and org-demote-subtree. Reposition this comment
to avoid any confusion.
Suggested-by: B Goodr <bgoodr@gmail.com>
---
doc/org-manual.org | 31 +++++++++++++++----------------
1 file changed, 15 insertions(+), 16 deletions(-)
diff --git a/doc/org-manual.org b/doc/org-manual.org
index 4c8dff5ee..c62fd58b4 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -689,6 +689,7 @@ ** Structure Editing
#+cindex: sorting, of subtrees
#+cindex: subtrees, cut and paste
+#+attr_texinfo: :sep ,
- {{{kbd(M-RET)}}} (~org-meta-return~) ::
#+kindex: M-RET
@@ -743,17 +744,23 @@ ** Structure Editing
level. Yet another {{{kbd(TAB)}}}, and you are back to the initial
level.
-- {{{kbd(M-LEFT)}}} (~org-do-promote~) ::
+- {{{kbd(M-LEFT)}}} (~org-do-promote~), {{{kbd(M-RIGHT)}}} (~org-do-demote~) ::
#+kindex: M-LEFT
#+findex: org-do-promote
- Promote current heading by one level.
-
-- {{{kbd(M-RIGHT)}}} (~org-do-demote~) ::
-
#+kindex: M-RIGHT
#+findex: org-do-demote
- Demote current heading by one level.
+ Promote or demote current heading by one level.
+
+ #+cindex: region, active
+ #+cindex: active region
+ #+cindex: transient mark mode
+ When there is an active region---i.e., when Transient Mark mode is
+ 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.
- {{{kbd(M-S-LEFT)}}} (~org-promote-subtree~) ::
@@ -889,16 +896,8 @@ ** Structure Editing
Finally, if the first line is a headline, remove the stars from all
headlines in the region.
-#+cindex: region, active
-#+cindex: active region
-#+cindex: transient mark mode
-When there is an active region---i.e., when Transient Mark mode is
-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 point is inside a table (see [[*Tables]]), the
-Meta-Cursor keys have different functionality.
+Note that when point is inside a table (see [[*Tables]]), the Meta-Cursor
+keys have different functionality.
** Sparse Trees
:PROPERTIES:
--
2.25.1
next prev parent reply other threads:[~2020-03-15 21:12 UTC|newest]
Thread overview: 7+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-03-15 18:01 Bug: Org manual: Structure Editing: Clarify commands which use the Transient Mark region [9.3.6 (9.3.6-23-g01ee25-elpaplus @ /tmp/.emacs.d.tmp.99712ad4-61f4-4464-b003-d6d4eea9b98f/org-plus-contrib-20200309/)] B Goodr
2020-03-15 21:11 ` Kyle Meyer [this message]
2020-03-15 23:50 ` B Goodr
2020-03-18 3:43 ` Kyle Meyer
2020-03-25 15:54 ` B Goodr
2020-03-26 1:46 ` Kyle Meyer
2020-03-26 17:29 ` B Goodr
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87v9n58grm.fsf@kyleam.com \
--to=kyle@kyleam.com \
--cc=bgoodr@gmail.com \
--cc=emacs-orgmode@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).