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