That sounds great. Thanks!! On Sun, Mar 15, 2020 at 2:12 PM Kyle Meyer wrote: > B Goodr 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-’ (‘org-do-promote’), ‘M-’ (‘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 > --- > 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 >