PROPOSAL: Bind `org-fold-hide-subtree' by default in Org Mode.

PROPOSAL: Bind `org-fold-hide-subtree' by default in Org Mode.

[Karl Fogel]

Hey everyone, is there a reason we don't bind 
`org-fold-hide-subtree' by default in Org Mode?

I bind it to C-<tab> and now find this to be one of the most 
useful keybindings in Org Mode.  I suspect my workflow is pretty 
typical.

The use case is simple:

When reading material within a certain heading level, one often 
decides that one is done with that section (and therefore done 
with everything inside it -- including anything at deeper levels 
of nesting).  So one just folds the entire subtree around point 
and moves on, without changing the visibility of any of the 
sibling-or-higher subtrees around it (because often the next place 
one is going is one of them).

This is one of my most frequent actions in Org Mode.  In fact, I 
think it might be the most common Org Mode command I run.

It seems like an obvious thing have bound to a key, and yet Org 
Mode doesn't bind it by default.  Should we?

(I put it on "C-<tab>" because that's normally unbound in Org 
Mode, and because so many of the Org Mode cycling commands involve 
modified tab already.  But I don't feel strongly about the 
particular key, as long as it's fast to type; maybe there's a 
better key available.)

I looked for prior discussion about this in the archives and 
didn't find anything: 
https://list.orgmode.org/?q=org-fold-hide-subtree

Best regards,
-Karl

Re: PROPOSAL: Bind `org-fold-hide-subtree' by default in Org Mode.

[Max Nikulin]

On 22/02/2023 14:29, Karl Fogel wrote:
> I put it on "C-<tab>" because that's normally unbound in Org Mode, and 
> because so many of the Org Mode cycling commands involve modified tab 
> already.

Perhaps C-<tab> is not the best choice:

9092c289b6bea38bb519e6c59a60237ae5af8f08
author Bastien Mon Jun 1 14:39:28 2020 +0200

Bind `org-force-cycle-archived' to C-c C-TAB

* lisp/org-keys.el (org-mode-map): Bind `org-force-cycle-archived'
to C-c C-TAB instead of C-TAB to avoid conflict with native Emacs
keybinding.

...

-(org-defkey org-mode-map (kbd "C-<tab>") #'org-force-cycle-archived)
+(org-defkey org-mode-map (kbd "C-c C-<tab>") #'org-force-cycle-archived)

Re: PROPOSAL: Bind `org-fold-hide-subtree' by default in Org Mode.

[Karl Fogel]

On 22 Feb 2023, Max Nikulin wrote:
>On 22/02/2023 14:29, Karl Fogel wrote:
>> I put it on "C-<tab>" because that's normally unbound in Org 
>> Mode,
>> and because so many of the Org Mode cycling commands involve
>> modified tab already.
>
>Perhaps C-<tab> is not the best choice:
>
>9092c289b6bea38bb519e6c59a60237ae5af8f08
>author Bastien Mon Jun 1 14:39:28 2020 +0200
>
>Bind `org-force-cycle-archived' to C-c C-TAB
>
>* lisp/org-keys.el (org-mode-map): Bind 
>`org-force-cycle-archived'
>to C-c C-TAB instead of C-TAB to avoid conflict with native Emacs
>keybinding.

Ah, clearly it is not a good choice -- thank you for noticing 
that.

I think there are two separate questions here:

1) Would it be useful to bind `org-fold-hide-subtree' by default?

2) If yes to (1), then is there a good key to bind it to?  (C-c 
C-something, I guess.)

If we agree on (1), then let's figure out the answer to (2).  I 
don't know if anyone else agrees about (1) yet, though.

By the way, the binding in my Org Mode hook looks like this:

  (when (not (keymap-lookup nil "C-<tab>"))
    (keymap-local-set "C-<tab>" 'org-fold-hide-subtree))

So FWIW C-<tab> is not bound in Org Mode buffers for me, in Emacs 
30.x (i.e., recent development builds).  However, I agree with 
Bastien's logic: C-<tab> is not in the reserved keymap space, so 
Emacs might bind it (and perhaps does bind it in other modes).

I don't know how widely-used `org-cycle-force-archived' is (that's 
the new name of that function).  I don't use it, personally, so if 
we decide against (1)+(2) above, then perhaps I'll just override 
that binding for myself instead.

Best regards,
-Karl

Re: PROPOSAL: Bind `org-fold-hide-subtree' by default in Org Mode.

[Max Nikulin]

On 23/02/2023 00:01, Karl Fogel wrote:
> 
>   (when (not (keymap-lookup nil "C-<tab>"))
>     (keymap-local-set "C-<tab>" 'org-fold-hide-subtree))
> 
> So FWIW C-<tab> is not bound in Org Mode buffers for me, in Emacs 30.x 
> (i.e., recent development builds).

lisp/tab-bar.el:130:  (unless (global-key-binding [(control tab)])
lisp/tab-bar.el:131:    (global-set-key [(control tab)] #'tab-next))

Minibuffer file cache completion should not be relevant to Org buffers.

Re: PROPOSAL: Bind `org-fold-hide-subtree' by default in Org Mode.

[Samuel Wales]

huh i had put org-next-link there.  i wish define-key could have a
button in a help page like functions and vars do so you could go to
where you define it.  [there are probably 300 competing packages that
do exactly that.]

On 2/22/23, Max Nikulin <manikulin@gmail.com> wrote:
> On 23/02/2023 00:01, Karl Fogel wrote:
>>
>>   (when (not (keymap-lookup nil "C-<tab>"))
>>     (keymap-local-set "C-<tab>" 'org-fold-hide-subtree))
>>
>> So FWIW C-<tab> is not bound in Org Mode buffers for me, in Emacs 30.x
>> (i.e., recent development builds).
>
> lisp/tab-bar.el:130:  (unless (global-key-binding [(control tab)])
> lisp/tab-bar.el:131:    (global-set-key [(control tab)] #'tab-next))
>
> Minibuffer file cache completion should not be relevant to Org buffers.
>
>
>


-- 
The Kafka Pandemic

A blog about science, health, human rights, and misopathy:
https://thekafkapandemic.blogspot.com

Key binding in help (was: Re: PROPOSAL: Bind `org-fold-hide-subtree' by default in Org Mode.)

[Max Nikulin]

On 23/02/2023 11:48, Samuel Wales wrote:
> huh i had put org-next-link there.  i wish define-key could have a
> button in a help page like functions and vars do so you could go to
> where you define it.  [there are probably 300 competing packages that
> do exactly that.]

C-h f org-next-link

displays at the top:

It is bound to C-c C-x C-n, <menu-bar> <Org> <Hyperlinks> <Next link>.

Is it the feature you are asking for? This one is available out of the box.

Unfortunately it is not trivial to discover binding from a file that is 
not loaded. Actually I found `tab-next' in the manual at first. Earlier 
attempts with "C-<tab>" and "C-TAB" failed due to "[(control tab)]" is 
used in tab-bar.el.

Re: Key binding in help (was: Re: PROPOSAL: Bind `org-fold-hide-subtree' by default in Org Mode.)

[Samuel Wales]

what i meant was that i have a binding, org-next-link, bound to c-tab.

i acccomplished this with (define-key org-mode-map (quote [C-tab])
(quote org-next-link)) [kbd would be better].

i did similar with org-link-minor-mode.  i was just offtopicing that
it would be useful to jump to those definitions.

i.e. like m-. on a function name, if that is set up to work, or c-h f
command tab ret to go to the fuction definition, but for keys.

On 2/25/23, Max Nikulin <manikulin@gmail.com> wrote:
> On 23/02/2023 11:48, Samuel Wales wrote:
>> huh i had put org-next-link there.  i wish define-key could have a
>> button in a help page like functions and vars do so you could go to
>> where you define it.  [there are probably 300 competing packages that
>> do exactly that.]
>
> C-h f org-next-link
>
> displays at the top:
>
> It is bound to C-c C-x C-n, <menu-bar> <Org> <Hyperlinks> <Next link>.
>
> Is it the feature you are asking for? This one is available out of the box.
>
> Unfortunately it is not trivial to discover binding from a file that is
> not loaded. Actually I found `tab-next' in the manual at first. Earlier
> attempts with "C-<tab>" and "C-TAB" failed due to "[(control tab)]" is
> used in tab-bar.el.
>
>
>


-- 
The Kafka Pandemic

A blog about science, health, human rights, and misopathy:
https://thekafkapandemic.blogspot.com

Re: Key binding in help (was: Re: PROPOSAL: Bind `org-fold-hide-subtree' by default in Org Mode.)

[Max Nikulin]

On 26/02/2023 06:32, Samuel Wales wrote:
> i acccomplished this with (define-key org-mode-map (quote [C-tab])
> (quote org-next-link)) [kbd would be better].
...
> i.e. like m-. on a function name, if that is set up to work, or c-h f
> command tab ret to go to the fuction definition, but for keys.

I do not mind to have such feature as well. If you really want to get 
it, you should send a feature request to bug-gnu-emacs.

>> On 23/02/2023 11:48, Samuel Wales wrote:
>>> [there are probably 300 competing packages that
>>> do exactly that.]

I expect that it should be implemented in Emacs core since updated 
`define-key' should be available rather early during initialization. 
Looking into
https://www.gnu.org/software/emacs/manual/html_node/elisp/Format-of-Keymaps.html
https://www.gnu.org/software/emacs/manual/html_node/elisp/Key-Lookup.html
I do not see a ready to use slot for location of key definition. Another 
point is that keymap extension should not noticeably affect performance.

Re: PROPOSAL: Bind `org-fold-hide-subtree' by default in Org Mode.

[Karl Fogel]

On 23 Feb 2023, Max Nikulin wrote:
>On 23/02/2023 00:01, Karl Fogel wrote:
>>   (when (not (keymap-lookup nil "C-<tab>"))
>>     (keymap-local-set "C-<tab>" 'org-fold-hide-subtree))
>> So FWIW C-<tab> is not bound in Org Mode buffers for me, in 
>> Emacs
>> 30.x (i.e., recent development builds).
>
>lisp/tab-bar.el:130:  (unless (global-key-binding [(control 
>tab)])
>lisp/tab-bar.el:131:    (global-set-key [(control tab)] 
>#'tab-next))
>
>Minibuffer file cache completion should not be relevant to Org 
>buffers.

Ah, I don't use tab-bar at all (at least not as far as I know), so 
I'm not 100% sure what the above is saying.

Are you saying that the only current default binding for C-<tab> 
in Emacs is that one in tab-bar.el, and therefore we should feel 
free to rebind it in Org Mode?  If so, we should still be 
cautious, since Emacs has policies for maintaining the keybinding 
space.  Generally, the space "C-c C-<LETTER>" is reserved for 
major modes, so ideally we should find something in there if we 
can -- although Org Mode has used up a lot of that space already 
:-), so I'm not sure what's left, unless we decide to swap out 
some existing binding in favor of this one.

(I realize this contradicts what I said in my inital post.  I had 
forgotten that C-<tab> was not part of the mode-reserved space.)

Best regards,
-Karl

Re: PROPOSAL: Bind `org-fold-hide-subtree' by default in Org Mode.

[Karl Fogel]

Okay, today I did some research and found that every "C-c 
C-<letter>" binding is used in Org Mode except for "C-c C-g". 
While that one is technically reserved for the mode's use, I 
suspect the reason it's unbound is that people are accustomed to 
using C-g as a quit command (and they get that effect if they 
accidentally type C-c, because then they type C-g and it's just an 
undefined key -- i.e., it quits, which is what the user wanted).

Note that while "C-c C-h" does not appear to be bound, it actually 
is: it gets you a help buffer about the Org Mode keybindings 
(which then, ironically, does not list "C-c C-h" as one of the 
bindings).

(It's not clear to me whether Emacs's conventions consider "C-c 
C-i" to be a letter or whether they treat "C-i" as "TAB" and 
consider it special; based on the previous evidence in this 
thread, maybe the latter, so we shouldn't consider "C-c C-i" to be 
available.)

I think what this is telling me is that Org Mode keybinding real 
estate is quite valuable :-), and that unless there are other 
people who feel as strongly as I do that `org-fold-hide-subtree' 
is amazingly useful, we probably won't decide to bind it by 
default in Org Mode.  So I should just continue to bind it to a 
custom key myself and continue to live a glorious life all alone 
in my private keymap splendour.

Best regards,
-Karl

I wrote:
>On 23 Feb 2023, Max Nikulin wrote:
>>On 23/02/2023 00:01, Karl Fogel wrote:
>>>  =C2=A0(when (not (keymap-lookup nil "C-<tab>"))
>>>  =C2=A0=C2=A0 (keymap-local-set "C-<tab>" 
>>>  'org-fold-hide-subtree))
>>> So FWIW C-<tab> is not bound in Org Mode buffers for me, in=20
>>> Emacs
>>> 30.x (i.e., recent development builds).
>>
>>lisp/tab-bar.el:130:  (unless (global-key-binding [(control=20
>>tab)])
>>lisp/tab-bar.el:131:    (global-set-key [(control tab)]=20
>>#'tab-next))
>>
>>Minibuffer file cache completion should not be relevant to 
>>Org=20
>>buffers.
>
>Ah, I don't use tab-bar at all (at least not as far as I know), 
>so=20
>I'm not 100% sure what the above is saying.
>
>Are you saying that the only current default binding for 
>C-<tab>=20
>in Emacs is that one in tab-bar.el, and therefore we should 
>feel=20
>free to rebind it in Org Mode?  If so, we should still be=20
>cautious, since Emacs has policies for maintaining the 
>keybinding=20
>space.  Generally, the space "C-c C-<LETTER>" is reserved for=20
>major modes, so ideally we should find something in there if 
>we=20
>can -- although Org Mode has used up a lot of that space 
>already=20
>:-), so I'm not sure what's left, unless we decide to swap out=20
>some existing binding in favor of this one.
>
>(I realize this contradicts what I said in my inital post.  I 
>had=20
>forgotten that C-<tab> was not part of the mode-reserved space.)

Re: PROPOSAL: Bind `org-fold-hide-subtree' by default in Org Mode.

[Max Nikulin]

On 25/02/2023 07:13, Karl Fogel wrote:
> Okay, today I did some research and found that every "C-c C-<letter>" 
> binding is used in Org Mode except for "C-c C-g". While that one is 
> technically reserved for the mode's use

No, there is an explicit exception for C-g, see (info "(elisp) Key 
Binding Conventions") in "Tips and Conventions" appendix.
https://www.gnu.org/software/emacs/manual/html_node/elisp/Key-Binding-Conventions.html

> (It's not clear to me whether Emacs's conventions consider "C-c C-i" to 
> be a letter or whether they treat "C-i" as "TAB" and consider it 
> special; based on the previous evidence in this thread, maybe the 
> latter, so we shouldn't consider "C-c C-i" to be available.)

It might be a problem to distinguish C-i and <tab> in text terminal. 
Issues with "C-c C-," raised on this list
- (info "(emacs) Named ASCII Chars")
 
https://www.gnu.org/software/emacs/manual/html_node/emacs/Named-ASCII-Chars.html
- (info "(elisp) Function Keys")
 
https://www.gnu.org/software/emacs/manual/html_node/elisp/Function-Keys.html
A similar issue exists with C-S-letter
- (info "(emacs) Modifier Keys")
 
https://www.gnu.org/software/emacs/manual/html_node/emacs/Modifier-Keys.html
- (info "(elisp) Other Char Bits")
 
https://www.gnu.org/software/emacs/manual/html_node/elisp/Other-Char-Bits.html

> I think what this is telling me is that Org Mode keybinding real estate 
> is quite valuable :-),

Even C-c C-x prefix is quite busy. Other modifiers might be a rescue: 
C-c M-something.

However perhaps M-x with fuzzy completion allowing typos (and ideally 
synonyms) might be a better solution.

>> Are you saying that the only current default binding for C-<tab>=20
>> in Emacs is that one in tab-bar.el, and therefore we should feel=20
>> free to rebind it in Org Mode?

No, [Ctrl+Tab] and [Ctrl+Shift+Tab] is widely used in other applications 
to switch to next/previous tabs. I would strongly prefer to keep it 
consistent across as much applications as possible. (There are corner 
cases like e.g. vim with multiple tabs running in a terminal application 
having several tabs as well. E.g. gnome terminal is able to pass 
[Ctrl+PgDn], a [Ctrl+Tab] alternative, while it has single tab, but 
intercepts the same shortcut when more terminal tabs are opened, so vim 
keys have to be used.)

Re: PROPOSAL: Bind `org-fold-hide-subtree' by default in Org Mode.

[Karl Fogel]

On 25 Feb 2023, Max Nikulin wrote:
>On 25/02/2023 07:13, Karl Fogel wrote:
>> Okay, today I did some research and found that every "C-c
>> C-<letter>" binding is used in Org Mode except for "C-c 
>> C-g". While
>> that one is technically reserved for the mode's use
>
>No, there is an explicit exception for C-g, see (info "(elisp) 
>Key
>Binding Conventions") in "Tips and Conventions" appendix.
>https://www.gnu.org/software/emacs/manual/html_node/elisp/Key-Binding-Conventions.html

Ah, thanks for pointing that out.

>Even C-c C-x prefix is quite busy. Other modifiers might be a 
>rescue:
>C-c M-something.
>
>However perhaps M-x with fuzzy completion allowing typos (and 
>ideally
>synonyms) might be a better solution.

Well, sure -- we get that for free.

I think we can consider this proposal over.  While I find 
`org-fold-hide-subtree' very useful, the Org Mode default keyspace 
is very busy already, and we don't hear anyone proposing to drop 
something else in favor of `org-fold-hide-subtree'.  Anyone can 
custom-bind it themselves, of course (which is what I'll continue 
doing).

>No, [Ctrl+Tab] and [Ctrl+Shift+Tab] is widely used in other
>applications to switch to next/previous tabs. I would strongly 
>prefer
>to keep it consistent across as much applications as 
>possible. (There
>are corner cases like e.g. vim with multiple tabs running in a
>terminal application having several tabs as well. E.g. gnome 
>terminal
>is able to pass [Ctrl+PgDn], a [Ctrl+Tab] alternative, while it 
>has
>single tab, but intercepts the same shortcut when more terminal 
>tabs
>are opened, so vim keys have to be used.)

Agreed.

Best regards,
-Karl