From mboxrd@z Thu Jan 1 00:00:00 1970 From: B Goodr Subject: =?UTF-8?B?UmU6IEJ1ZzogT3JnIG1hbnVhbDogU3RydWN0dXJlIEVkaXRpbmc6?= =?UTF-8?B?IENsYXJpZnkgY29tbWFuZHMgd2hpY2ggdXNlIHRoZSBUcmFuc2llbnQgTWFy?= =?UTF-8?B?ayByZWdpb24gWzkuMy42ICg5LjMuNi0yMy1nMDFlZTI1LWVscGFwbHVzIEAg?= =?UTF-8?B?L3RtcC8uZW1hY3MuZC50bXAuOTk3MTJhZDQtNjFmNC00NDY0LWIwMDMtZDZk?= =?UTF-8?B?NGVlYTliOThmL29yZy1wbHVzLWNvbnRyaWItMjAyMDAzMDkvKV0=?= Date: Sun, 15 Mar 2020 16:50:03 -0700 Message-ID: References: <87v9n58grm.fsf@kyleam.com> Mime-Version: 1.0 Content-Type: multipart/alternative; boundary="00000000000028ef9c05a0ed5dbc" Return-path: Received: from eggs.gnu.org ([2001:470:142:3::10]:33969) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jDd1O-0001Te-2W for emacs-orgmode@gnu.org; Sun, 15 Mar 2020 19:50:20 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1jDd1M-0003i2-5P for emacs-orgmode@gnu.org; Sun, 15 Mar 2020 19:50:17 -0400 Received: from mail-lf1-x132.google.com ([2a00:1450:4864:20::132]:37077) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1jDd1L-0003XH-RA for emacs-orgmode@gnu.org; Sun, 15 Mar 2020 19:50:16 -0400 Received: by mail-lf1-x132.google.com with SMTP id j11so12461396lfg.4 for ; Sun, 15 Mar 2020 16:50:15 -0700 (PDT) In-Reply-To: <87v9n58grm.fsf@kyleam.com> List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane-mx.org@gnu.org Sender: "Emacs-orgmode" To: Kyle Meyer Cc: emacs-orgmode@gnu.org --00000000000028ef9c05a0ed5dbc Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable 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 som= e > 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: > > =E2=80=98M-=E2=80=99 (=E2=80=98org-do-promote=E2=80=99), =E2=80= =98M-=E2=80=99 (=E2=80=98org-do-demote=E2=80=99) > Promote or demote current heading by one level. > > When there is an active region=E2=80=94i.e., when Transient Mark m= ode is > active=E2=80=94promotion and demotion work on all headlines in the= region. > To select a region of headlines, it is best to place both point an= d > mark at the beginning of a line, mark at the beginning of the firs= t > 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-Curso= r > +keys have different functionality. > > ** Sparse Trees > :PROPERTIES: > -- > 2.25.1 > --00000000000028ef9c05a0ed5dbc Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
That sounds great. Thanks!!

On Sun, Mar 15, 2020 at 2:1= 2 PM Kyle Meyer <kyle@kyleam.com&= gt; wrote:
B Goo= dr <bgoodr@gmail.c= om> 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 so= me 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.=C2=A0 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:

=C2=A0 =E2=80=98M-<LEFT>=E2=80=99 (=E2=80=98org-do-promote=E2=80=99),= =E2=80=98M-<RIGHT>=E2=80=99 (=E2=80=98org-do-demote=E2=80=99)
=C2=A0 =C2=A0 =C2=A0 =C2=A0Promote or demote current heading by one level.<= br>
=C2=A0 =C2=A0 =C2=A0 =C2=A0When there is an active region=E2=80=94i.e., whe= n Transient Mark mode is
=C2=A0 =C2=A0 =C2=A0 =C2=A0active=E2=80=94promotion and demotion work on al= l headlines in the region.
=C2=A0 =C2=A0 =C2=A0 =C2=A0To select a region of headlines, it is best to p= lace both point and
=C2=A0 =C2=A0 =C2=A0 =C2=A0mark at the beginning of a line, mark at the beg= inning of the first
=C2=A0 =C2=A0 =C2=A0 =C2=A0headline, and point at the line just after the l= ast headline to
=C2=A0 =C2=A0 =C2=A0 =C2=A0change.

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 =C2=A0region

* 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.=C2=A0 Reposition this comment to avoid any confusion.

Suggested-by: B Goodr <bgoodr@gmail.com>
---
=C2=A0doc/org-manual.org | 31 +++++++++++++++----------------
=C2=A01 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
=C2=A0#+cindex: sorting, of subtrees
=C2=A0#+cindex: subtrees, cut and paste

+#+attr_texinfo: :sep ,
=C2=A0- {{{kbd(M-RET)}}} (~org-meta-return~) ::

=C2=A0 =C2=A0#+kindex: M-RET
@@ -743,17 +744,23 @@ ** Structure Editing
=C2=A0 =C2=A0level.=C2=A0 Yet another {{{kbd(TAB)}}}, and you are back to t= he initial
=C2=A0 =C2=A0level.

-- {{{kbd(M-LEFT)}}} (~org-do-promote~) ::
+- {{{kbd(M-LEFT)}}} (~org-do-promote~), {{{kbd(M-RIGHT)}}} (~org-do-demote= ~) ::

=C2=A0 =C2=A0#+kindex: M-LEFT
=C2=A0 =C2=A0#+findex: org-do-promote
-=C2=A0 Promote current heading by one level.
-
-- {{{kbd(M-RIGHT)}}} (~org-do-demote~) ::
-
=C2=A0 =C2=A0#+kindex: M-RIGHT
=C2=A0 =C2=A0#+findex: org-do-demote
-=C2=A0 Demote current heading by one level.
+=C2=A0 Promote or demote current heading by one level.
+
+=C2=A0 #+cindex: region, active
+=C2=A0 #+cindex: active region
+=C2=A0 #+cindex: transient mark mode
+=C2=A0 When there is an active region---i.e., when Transient Mark mode is<= br> +=C2=A0 active---promotion and demotion work on all headlines in the region= .
+=C2=A0 To select a region of headlines, it is best to place both point and=
+=C2=A0 mark at the beginning of a line, mark at the beginning of the first=
+=C2=A0 headline, and point at the line just after the last headline to
+=C2=A0 change.

=C2=A0- {{{kbd(M-S-LEFT)}}} (~org-promote-subtree~) ::

@@ -889,16 +896,8 @@ ** Structure Editing
=C2=A0 =C2=A0Finally, if the first line is a headline, remove the stars fro= m all
=C2=A0 =C2=A0headlines 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.=C2=A0 Note that when point is inside a table (see [[*Tables]]), th= e
-Meta-Cursor keys have different functionality.
+Note that when point is inside a table (see [[*Tables]]), the Meta-Cursor<= br> +keys have different functionality.

=C2=A0** Sparse Trees
=C2=A0:PROPERTIES:
--
2.25.1
--00000000000028ef9c05a0ed5dbc--