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

[Karl Fogel <kfogel@red-bean.com>]

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,