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/)]

[B Goodr <bgoodr@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 4795 bytes --]

That sounds great. Thanks!!

On Sun, Mar 15, 2020 at 2:12 PM Kyle Meyer <kyle@kyleam.com> wrote:

> 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
>

[-- Attachment #2: Type: text/html, Size: 5961 bytes --]