That sounds great. Thanks!!
On Sun, Mar 15, 2020 at 2:12 PM Kyle Meyer <k...@kyleam.com> wrote:
> B Goodr <bgo...@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 <bgo...@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
>
