From: B Goodr <bgoodr@gmail.com>
To: Kyle Meyer <kyle@kyleam.com>
Cc: 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 16:50:03 -0700 [thread overview]
Message-ID: <CAJj=8EG+7i8_fnKEgu=dZ1hysZ8pDk3PiSTg_p8=3DRCFxzo1A@mail.gmail.com> (raw)
In-Reply-To: <87v9n58grm.fsf@kyleam.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 --]
next prev parent reply other threads:[~2020-03-15 23:50 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
2020-03-15 23:50 ` B Goodr [this message]
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='CAJj=8EG+7i8_fnKEgu=dZ1hysZ8pDk3PiSTg_p8=3DRCFxzo1A@mail.gmail.com' \
--to=bgoodr@gmail.com \
--cc=emacs-orgmode@gnu.org \
--cc=kyle@kyleam.com \
/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).