[PROPOSAL] Use prefix arg to control scope of org-narrow-to-subtree.

[PROPOSAL] Use prefix arg to control scope of org-narrow-to-subtree.

[Karl Fogel]

Hi.  This is a feature proposal -- if the consensus is that it would be welcomed, I'm happy to code it.  I just didn't want to take the time to write it if there's no chance for it to be accepted upstream (since I don't want to be maintaining my own personal branch of Org Mode).

It would be useful if `org-narrow-to-subtree' could optionally narrow to the next subtree(s) up, rather than only to the subtree point is currently in.  For example, assume this text:

   * This is the first level
   Some text here.
   ** This is the second level
   Some other text here.
   *** This is the third level
   By now we all know this song.
   It is such a pretty song.
   **** This is the fourth level
   But do we have to sing it all day long?
   This car trip is getting incong
   ***** This is the fifth level
   ruously unrhymed.

Further assume that point is on the "c" of "car trip".  

In the current Org Mode, if you type `C-x n s', it will narrow to the fourth-level subtree (with the fifth level included in the narrowed buffer, of course).

Since `org-narrow-to-subtree' takes no arguments at all right now, it's conveniently ripe for improvement :-).

My proposal is for each raw prefix arg (each `C-u' prefix) to expand the narrowing level outward/upward by one.  So in the above situation:

  - `C-u C-x n s' would narrow to the third-level subtree

  - `C-u C-u C-x n s' would narrow to the second-level subtree

And so on.

If you offer too many `C-u's, such that the narrowing would be wider than the current surrounding first-level subtree, then there are two possible ways we could handle it:

1) Extra `C-u's are ignored -- just narrow to surrounding 1st-level subtree.

2) Throw an error.

I prefer (1), because it would be the more useful behavior, even though (2) would be easier to implement (since `org-back-to-heading' already throws the error).  However, I'd welcome others' feedback on that question, or on any other aspect of this proposal.

Best regards,
-Karl

Re: [PROPOSAL] Use prefix arg to control scope of org-narrow-to-subtree.

[Alan L Tyree]

On 25/4/19 5:05 am, Karl Fogel wrote:
> Hi.  This is a feature proposal -- if the consensus is that it would be welcomed, I'm happy to code it.  I just didn't want to take the time to write it if there's no chance for it to be accepted upstream (since I don't want to be maintaining my own personal branch of Org Mode).
>
> It would be useful if `org-narrow-to-subtree' could optionally narrow to the next subtree(s) up, rather than only to the subtree point is currently in.  For example, assume this text:
>
>     * This is the first level
>     Some text here.
>     ** This is the second level
>     Some other text here.
>     *** This is the third level
>     By now we all know this song.
>     It is such a pretty song.
>     **** This is the fourth level
>     But do we have to sing it all day long?
>     This car trip is getting incong
>     ***** This is the fifth level
>     ruously unrhymed.
>
> Further assume that point is on the "c" of "car trip".
>
> In the current Org Mode, if you type `C-x n s', it will narrow to the fourth-level subtree (with the fifth level included in the narrowed buffer, of course).
>
> Since `org-narrow-to-subtree' takes no arguments at all right now, it's conveniently ripe for improvement :-).
>
> My proposal is for each raw prefix arg (each `C-u' prefix) to expand the narrowing level outward/upward by one.  So in the above situation:
>
>    - `C-u C-x n s' would narrow to the third-level subtree
>
>    - `C-u C-u C-x n s' would narrow to the second-level subtree
>
> And so on.
>
> If you offer too many `C-u's, such that the narrowing would be wider than the current surrounding first-level subtree, then there are two possible ways we could handle it:
>
> 1) Extra `C-u's are ignored -- just narrow to surrounding 1st-level subtree.
>
> 2) Throw an error.
>
> I prefer (1), because it would be the more useful behavior, even though (2) would be easier to implement (since `org-back-to-heading' already throws the error).  However, I'd welcome others' feedback on that question, or on any other aspect of this proposal.
>
> Best regards,
> -Karl
>
Hi Karl,

I would definitely use this feature. I'm not in a position to help with 
coding, but would be happy to help test. I presume that it would also 
apply to C-c C-x b: org-tree-to-indirect-buffer.

Regards,

Alan


-- 
Alan L Tyree                    http://www2.austlii.edu.au/~alan

Re: [PROPOSAL] Use prefix arg to control scope of org-narrow-to-subtree.

[Alan L Tyree]

On 25/4/19 5:05 am, Karl Fogel wrote:
> Hi.  This is a feature proposal -- if the consensus is that it would be welcomed, I'm happy to code it.  I just didn't want to take the time to write it if there's no chance for it to be accepted upstream (since I don't want to be maintaining my own personal branch of Org Mode).
>
> It would be useful if `org-narrow-to-subtree' could optionally narrow to the next subtree(s) up, rather than only to the subtree point is currently in.  For example, assume this text:
>
>     * This is the first level
>     Some text here.
>     ** This is the second level
>     Some other text here.
>     *** This is the third level
>     By now we all know this song.
>     It is such a pretty song.
>     **** This is the fourth level
>     But do we have to sing it all day long?
>     This car trip is getting incong
>     ***** This is the fifth level
>     ruously unrhymed.
>
> Further assume that point is on the "c" of "car trip".
>
> In the current Org Mode, if you type `C-x n s', it will narrow to the fourth-level subtree (with the fifth level included in the narrowed buffer, of course).
>
> Since `org-narrow-to-subtree' takes no arguments at all right now, it's conveniently ripe for improvement :-).
>
> My proposal is for each raw prefix arg (each `C-u' prefix) to expand the narrowing level outward/upward by one.  So in the above situation:
>
>    - `C-u C-x n s' would narrow to the third-level subtree
>
>    - `C-u C-u C-x n s' would narrow to the second-level subtree
>
> And so on.
>
> If you offer too many `C-u's, such that the narrowing would be wider than the current surrounding first-level subtree, then there are two possible ways we could handle it:
>
> 1) Extra `C-u's are ignored -- just narrow to surrounding 1st-level subtree.
>
> 2) Throw an error.
>
> I prefer (1), because it would be the more useful behavior, even though (2) would be easier to implement (since `org-back-to-heading' already throws the error).  However, I'd welcome others' feedback on that question, or on any other aspect of this proposal.
>
> Best regards,
> -Karl
>
Further to my previous message: there is already provision for a 
numerical prefix in org-tree-to-indirect-buffer.  I suppose that it and 
org-narrow-to-subtree should behave the same.

org-narrow-to-subtree is what the old pc outliners called "hoisting". I 
first saw it in Thinktank and it was a blessing when writing book length 
documents.


Cheers,

Alan


-- 
Alan L Tyree                    http://www2.austlii.edu.au/~alan

Re: [PROPOSAL] Use prefix arg to control scope of org-narrow-to-subtree.

[Nicolas Goaziou]

Hello,

Karl Fogel <kfogel@red-bean.com> writes:

> My proposal is for each raw prefix arg (each `C-u' prefix) to expand
> the narrowing level outward/upward by one.  So in the above situation:

I suggest to use a numeric argument for that. M-1 for one level, M-2 for
two levels, maybe M-0 equivalent to current behaviour. C-u can be
a shortcut for M-1.

> If you offer too many `C-u's, such that the narrowing would be wider than the current surrounding first-level subtree, then there are two possible ways we could handle it:
>
> 1) Extra `C-u's are ignored -- just narrow to surrounding 1st-level subtree.
>
> 2) Throw an error.
>
> I prefer (1), because it would be the more useful behavior, even
> though (2) would be easier to implement (since `org-back-to-heading'
> already throws the error).  However, I'd welcome others' feedback on
> that question, or on any other aspect of this proposal.

1 sounds good.

I think it is a good idea.

Thank you.

Regards,

-- 
Nicolas Goaziou

Re: [PROPOSAL] Use prefix arg to control scope of org-narrow-to-subtree.

[Karl Fogel]

On 25 Apr 2019, Nicolas Goaziou wrote:
>Hello,
>
>Karl Fogel <kfogel@red-bean.com> writes:
>
>> My proposal is for each raw prefix arg (each `C-u' prefix) to expand
>> the narrowing level outward/upward by one.  So in the above situation:
>
>I suggest to use a numeric argument for that. M-1 for one level, M-2 for
>two levels, maybe M-0 equivalent to current behaviour. C-u can be
>a shortcut for M-1.

Thanks to you and Alan Tyree for your encouraging replies.

In a followup message, you added:

> Further to my previous message: there is already provision for a
> numerical prefix in org-tree-to-indirect-buffer.  I suppose that it
> and org-narrow-to-subtree should behave the same.

Ahhh, okay, hmmm -- I didn't know about `org-tree-to-indirect-buffer'.  This makes the situation somewhat more complex.  Let me explain:

First, I agree it should be a numeric argument, and we can treat "C-u" specially, making each C-u be equivalent to one increment.  E.g., "C-u" is "M-1", as you said, and "C-u C-u" is "M-2", etc.  This may be a slightly unusual behavior in Emacs, but given the low numbers we're talking about here, and the high convenience of just being able to repeat C-u a certain number of times to indicate that number of levels, I think it's well worth it.

However, my orginal thought was that the number would be relative *from* the level point is currently at.  In other words, if you're in the 5th nested subtree down ("***** " is the most recent heading prefix), then `M-1 org-narrow-to-subtree' would narrow to the next level up -- the 4th-level nesting.

Unfortunately, this is the opposite of how `org-tree-to-indirect-buffer' interprets prefixes:

  "With a numerical prefix ARG, go up to this level and then take that tree.
   If ARG is negative, go up that many levels."

In other words, in `org-tree-to-indirect-buffer', the number is counted down from the absolute reference point of the top level (although you can use a negative number to get the behavior I was proposing for `org-narrow-to-subtree').

I'd like to be consistent with existing commands.  But still, most of the time a user would (I conjecture) want to choose their narrowing level *relative* to the level of where point currently is.  That's certainly what I always want: I'm at a certain nesting level, and either I want to narrow to that level, or to the one right above it, or to the one above that, etc.  I'm always thinking in terms relative to where I am now, not relative to the far-away top level.  In fact, I'm not necessarily even aware of the absolute nesting count of where I am now -- and I don't need to know either, for the purposes of narrowing.

So here's my updated proposal:

Purely numeric prefix arguments behave as in `org-tree-to-indirect-buffer', but each C-u behaves as an increment in the other direction (i.e., the way negative numbers behave for `org-tree-to-indirect-buffer').  Numeric arguments would thus be consistent with `org-tree-to-indirect-buffer', but there would still be a way, using repeated "C-u"s, to quickly and conveniently indicate a nesting level relative to where one currently is.

Thoughts?

Best regards,
-Karl

>> If you offer too many `C-u's, such that the narrowing would be wider
>> than the current surrounding first-level subtree, then there are two
>> possible ways we could handle it:
>>
>> 1) Extra `C-u's are ignored -- just narrow to surrounding 1st-level subtree.
>>
>> 2) Throw an error.
>>
>> I prefer (1), because it would be the more useful behavior, even
>> though (2) would be easier to implement (since `org-back-to-heading'
>> already throws the error).  However, I'd welcome others' feedback on
>> that question, or on any other aspect of this proposal.
>
>1 sounds good.
>
>I think it is a good idea.
>
>Thank you.
>
>Regards,

[PATCH] Use prefix arg to control scope of org-narrow-to-subtree.

[Karl Fogel]

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

This is the enhancement to `org-narrow-to-subtree' that I suggested back in May [1].

It allows you to choose what level subtree to narrow to.  There are two ways to specify the subtree: use repeated C-u's to select "upward" from the current subtree, or use a direct numeric prefix arg to specify the subtree "downward" from level 1.  (This is a somewhat unusual prefix argument usage, but it's useful to be able to choose from either direction, and the convenience of using C-u to select upward is quite enormous -- I expect it to be the common case, and it's pretty much the only way I use the feature.)

The prefix arg is optional, of course: if you don't pass it, then `org-narrow-to-subtree' behaves the same way it has always behaved.

Best regards,
-Karl

[1] https://lists.gnu.org/archive/html/emacs-orgmode/2019-05/msg00225.html


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Use-prefix-arg-to-narrow-to-a-specific-subtree.patch --]
[-- Type: text/x-diff, Size: 2894 bytes --]

From bbeca3c5444646685085c134b10f4883812068a0 Mon Sep 17 00:00:00 2001
From: Karl Fogel <kfogel@red-bean.com>
Date: Sat, 30 Nov 2019 01:33:15 -0600
Subject: [PATCH] Use prefix arg to narrow to a specific subtree

* lisp/org.el (org-narrow-to-subtree): Take a prefix arg and use
  it to choose which subtree to narrow to.  See thread for context:

  https://lists.gnu.org/archive/html/emacs-orgmode/2019-05/msg00225.html
  From: Karl Fogel
  To: Org Mode
  Subject: Re: [PROPOSAL] Use prefix arg to control scope \
           of org-narrow-to-subtree.
  Date: Fri, 31 May 2019 02:33:03 -0500
  Message-ID: <87y32ncc40.fsf@red-bean.com>
---
 lisp/org.el | 41 ++++++++++++++++++++++++++++++++++++++---
 1 file changed, 38 insertions(+), 3 deletions(-)

diff --git a/lisp/org.el b/lisp/org.el
index 90f222c8b..9b16c59e6 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -7743,11 +7743,46 @@ If yes, remember the marker and the distance to BEG."
     (move-marker (car x) (+ beg (cdr x))))
   (setq org-markers-to-move nil))
 
-(defun org-narrow-to-subtree ()
-  "Narrow buffer to the current subtree."
-  (interactive)
+(defun org-narrow-to-subtree (&optional steps)
+  "Narrow buffer to current subtree or to one specified by prefix arg STEPS.
+
+Interactively, use the prefix argument in one of two ways to
+narrow to a specific subtree: either give one or more C-u's to
+specify a subtree that many levels upward from the current
+subtree (that is, go up as many levels as the number of C-u's
+given -- each C-u counts for one level), or give a strictly
+numeric argument to narrow to the subtree that is that many
+levels downward from the current top level (level 1) subtree.
+
+From Lisp, if you want the C-u (upward) behavior, pass STEPS as a
+list with the desired number as its sole element.  Otherwise,
+pass STEPS as a number to get the other (downward) behavior.
+
+If STEPS would specify a subtree higher than the current level 1
+subtree, then just narrow to that level 1 subtree (in other
+words, you can use \"a lot of\" C-u's to narrow quickly to the
+current top subtree).  If STEPS would specify a subtree deeper
+than the current subtree, just narrow to the current subtree."
+  (interactive "P")
   (save-excursion
     (save-match-data
+      (widen)
+      (if steps
+	  (if (listp steps)
+	      (progn
+		(setq steps (car steps))
+		(when (< steps 0)
+		  (error "Argument cannot be negative"))
+		(setq steps (round (log steps 4))))
+	    (when (< steps 0) ; awkward duplication, but hard to avoid
+	      (error "Argument cannot be negative"))
+	    (let ((cur-level (org-outline-level)))
+	      (setq steps (max (- cur-level steps) 0))))
+	(setq steps 0))
+      (while (> steps 0)
+	(if (org-up-heading-safe)
+	    (setq steps (1- steps))
+	  (setq steps 0)))
       (org-with-limited-levels
        (narrow-to-region
 	(progn (org-back-to-heading t) (point))
-- 
2.24.0

Re: [PATCH] Use prefix arg to control scope of org-narrow-to-subtree.

[Marco Wahl]

Karl Fogel <kfogel@red-bean.com> writes:

> This is the enhancement to `org-narrow-to-subtree' that I suggested back in May [1].
>
> It allows you to choose what level subtree to narrow to.  There are
> two ways to specify the subtree: use repeated C-u's to select "upward"
> from the current subtree, or use a direct numeric prefix arg to
> specify the subtree "downward" from level 1.  (This is a somewhat
> unusual prefix argument usage, but it's useful to be able to choose
> from either direction, and the convenience of using C-u to select
> upward is quite enormous -- I expect it to be the common case, and
> it's pretty much the only way I use the feature.)
>
> The prefix arg is optional, of course: if you don't pass it, then
> `org-narrow-to-subtree' behaves the same way it has always behaved.

+1

I think your enhancement is great and worth a news entry.  What about
pushing your code if nobody objects within one week?


Ciao,  Marco

Re: [PATCH] Use prefix arg to control scope of org-narrow-to-subtree.

[Karl Fogel]

On 01 Dec 2019, Marco Wahl wrote:
>+1
>
>I think your enhancement is great and worth a news entry.  What about
>pushing your code if nobody objects within one week?

Thanks, Marco; I'm glad you like it.  I'll wait a week and then push (unless there's discussion, in which case we'll see what the outcome of the discussion is first, of course).

I just created a "kfogel" account at https://code.orgmode.org/ and uploaded my SSH key.  Should I mail Bastien about push access, or is posting here enough?

Regarding a news entry: that means the 9.3 section of etc/ORG-NEWS, right?  I will add a news entry to the commit at push time.

Best regards,
-Karl

Re: [PATCH] Use prefix arg to control scope of org-narrow-to-subtree.

[Marco Wahl]

Hi Karl,

>>I think your enhancement is great and worth a news entry.  What about
>>pushing your code if nobody objects within one week?
>
> Thanks, Marco; I'm glad you like it.  I'll wait a week and then push
> (unless there's discussion, in which case we'll see what the outcome
> of the discussion is first, of course).

This sounds right to me.

> I just created a "kfogel" account at https://code.orgmode.org/ and
> uploaded my SSH key.  Should I mail Bastien about push access, or is
> posting here enough?

I guess it's a good idea to write to Bastien explicitly.

> Regarding a news entry: that means the 9.3 section of etc/ORG-NEWS,
> right?  I will add a news entry to the commit at push time.

Great!

Thanks for asking about the version.  AFAICT there is a feature freeze
right now for version 9.3.  This means you would commit to the 'next'
branch which shall be the next master branch after the release.  And
also you would add the news entry in section [Version Next] in
etc/ORG-NEWS.


Ciao,  Marco

Re: [PATCH] Use prefix arg to control scope of org-narrow-to-subtree.

[Karl Fogel]

On 01 Dec 2019, Marco Wahl wrote:
>I guess it's a good idea to write to Bastien explicitly.

I will do so.

>Thanks for asking about the version.  AFAICT there is a feature freeze
>right now for version 9.3.  This means you would commit to the 'next'
>branch which shall be the next master branch after the release.  And
>also you would add the news entry in section [Version Next] in
>etc/ORG-NEWS.

Ah, okay.  Thanks for letting me know; I'll do all that.

Best regards,
-Karl

Re: [PATCH] Use prefix arg to control scope of org-narrow-to-subtree.

[Eric Abrahamsen]

Karl Fogel <kfogel@red-bean.com> writes:

> This is the enhancement to `org-narrow-to-subtree' that I suggested back in May [1].
>
> It allows you to choose what level subtree to narrow to. There are two
> ways to specify the subtree: use repeated C-u's to select "upward"
> from the current subtree, or use a direct numeric prefix arg to
> specify the subtree "downward" from level 1. (This is a somewhat
> unusual prefix argument usage, but it's useful to be able to choose
> from either direction, and the convenience of using C-u to select
> upward is quite enormous -- I expect it to be the common case, and
> it's pretty much the only way I use the feature.)

Just 2c: you're right that's a slightly odd use of the prefix argument.
I think a slightly more conventional approach might be to use positive
and negative numerical arguments, positive going one direction, negative
the other. Just a suggestion, though -- I like this addition a lot.

Re: [PATCH] Use prefix arg to control scope of org-narrow-to-subtree.

[Marco Wahl]

Karl Fogel <kfogel@red-bean.com> writes:

> It allows you to choose what level subtree to narrow to.  There are
> two ways to specify the subtree: use repeated C-u's to select "upward"
> from the current subtree, or use a direct numeric prefix arg to
> specify the subtree "downward" from level 1.  (This is a somewhat
> unusual prefix argument usage, but it's useful to be able to choose
> from either direction, and the convenience of using C-u to select
> upward is quite enormous -- I expect it to be the common case, and
> it's pretty much the only way I use the feature.)
>
> The prefix arg is optional, of course: if you don't pass it, then
> `org-narrow-to-subtree' behaves the same way it has always behaved.

What about numeric prefix arg 0 to reveal the whole buffer (aka
'widen')?  I think this would be a logical completion to the feature.

Re: [PATCH] Use prefix arg to control scope of org-narrow-to-subtree.

[Karl Fogel]

On 02 Dec 2019, Marco Wahl wrote:
>What about numeric prefix arg 0 to reveal the whole buffer (aka
>'widen')?  I think this would be a logical completion to the feature.

Since `widen' itself is already available via C-x n w, it might be better to save a special flag value like that for some special behavior that we (or someone else) might think of in the future.  I'm pretty sure that anyone using `org-narrow-to-subtree' must also know about the `widen' command, too.

Thoughts?

Best regards,
-Karl

Re: [PATCH] Use prefix arg to control scope of org-narrow-to-subtree.

[Marco Wahl]

Karl Fogel <kfogel@red-bean.com> writes:

> On 02 Dec 2019, Marco Wahl wrote:
>>What about numeric prefix arg 0 to reveal the whole buffer (aka
>>'widen')?  I think this would be a logical completion to the feature.
>
> Since `widen' itself is already available via C-x n w, it might be
> better to save a special flag value like that for some special
> behavior that we (or someone else) might think of in the future.  I'm
> pretty sure that anyone using `org-narrow-to-subtree' must also know
> about the `widen' command, too.

Okay, this sounds sound.

Let me be a bit more explicit about my wish: I vote for the prefix arg 0
to widen because this fits to the logic to view the whole file as level
0 subtree.  With this perspective on the feature the effect of a numeric
prefix argument is clear as day:

...
C-u 2 M-x org-narrow... => Narrow to the level-2 subtree containing point.
C-u 1 M-x org-narrow... => Narrow to the level-1 subtree containing point.
C-u 0 M-x org-narrow... => Narrow to the level-0 subtree containing point.

The last line stands in opposition to the current behavior.

C-u 0 M-x org-narrow... => Narrow to the level-1 subtree containing point.
    ^                                          ^

Re: [PATCH] Use prefix arg to control scope of org-narrow-to-subtree.

[Karl Fogel]

On 02 Dec 2019, Marco Wahl wrote:
>Karl Fogel <kfogel@red-bean.com> writes:
>> Since `widen' itself is already available via C-x n w, it might be
>> better to save a special flag value like that for some special
>> behavior that we (or someone else) might think of in the future.  I'm
>> pretty sure that anyone using `org-narrow-to-subtree' must also know
>> about the `widen' command, too.
>
>Okay, this sounds sound.
>
>Let me be a bit more explicit about my wish: I vote for the prefix arg 0
>to widen because this fits to the logic to view the whole file as level
>0 subtree.  With this perspective on the feature the effect of a numeric
>prefix argument is clear as day:
>
>...
>C-u 2 M-x org-narrow... => Narrow to the level-2 subtree containing point.
>C-u 1 M-x org-narrow... => Narrow to the level-1 subtree containing point.
>C-u 0 M-x org-narrow... => Narrow to the level-0 subtree containing point.
>
>The last line stands in opposition to the current behavior.
>
>C-u 0 M-x org-narrow... => Narrow to the level-1 subtree containing point.
>    ^                                          ^

Oh, yes, I get the logic, from a consistency standpoint.

My only concern is that a) it's unnecessary, because `widen' is available, and b) some day we might think of a better special meaning for C-u 0 (and in the meantime it could error instead of narrowing to the current level-1 subtree).

But I don't feel strongly about it either way.  Perhaps consistency is desirable here, although I tend to think that consistency is overrated in UI/UX in general -- the famous example of "`transpose-chars' at the end of a line" comes to mind.

Hmm, but on the other hand, your proposed consistency *would* be good if anyone's ever calling `org-narrow-to-subtree' from Lisp with an algorithmically calculated STEPS argument.  I can't imagine what kind of circumstance that would be, but if it's a general principle of Org Mode to consider "level 0" to be the entire buffer, then we should probably go with your proposed behavior.  So I guess I'm tentatively +1...

Does anyone else have any thoughts on this?

Best regards,
-Karl