From f81fc116136d28b87e8ea5edb2092b89a238104c Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Mon, 17 Nov 2025 17:54:48 +0200 Subject: [PATCH] ; Improve wording of documentation of 'hs-cycle-filter' * doc/emacs/programs.texi (Hideshow): * etc/NEWS: * lisp/progmodes/hideshow.el (hs-cycle-filter): Improve wording. --- doc/emacs/programs.texi | 10 ++++++---- etc/NEWS | 4 ++-- lisp/progmodes/hideshow.el | 20 +++++++++++--------- 3 files changed, 19 insertions(+), 15 deletions(-) diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi index 385bfafb1d1..0adb90b36cb 100644 --- a/doc/emacs/programs.texi +++ b/doc/emacs/programs.texi @@ -1774,10 +1774,12 @@ disabled; the value of @code{nil} will activate the indicators regardless of the buffer size. @item hs-cycle-filter -This variable controls where on the line with hideable blocks the -@kbd{@key{TAB}} key cycles their visibility. Depending on its non-nil -values, @kbd{@key{TAB}} can be active on different parts of such lines. -Anywhere else on the line this key has its default keybinding. +This variable controls where on the line with hideable blocks typing the +@kbd{@key{TAB}} key will cycle the visibility of the blocks. Depending +on its non-@code{nil} value, @key{TAB} can be active on different parts +of such lines. Anywhere else on the line @key{TAB} has its default key +binding. The value @code{nil} means @key{TAB} cannot cycle the +visibility of the blocks anywhere on the heading line. @item hs-isearch-open This variable specifies the conditions under which incremental search diff --git a/etc/NEWS b/etc/NEWS index 0c9c4962310..0d3c8938139 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -1114,8 +1114,8 @@ after cursor position. By default this is set to 'after-bol'. +++ *** New user option 'hs-cycle-filter' for visibility-cycling with 'TAB'. -This user option controls where on the line with hideable blocks -the 'TAB' key cycles their visibility. +This user option controls the positions on the headline of hideable blocks +where the 'TAB' key cycles the blocks' visibility. +++ *** The variable 'hs-special-modes-alist' is now obsolete. diff --git a/lisp/progmodes/hideshow.el b/lisp/progmodes/hideshow.el index 87c98b5b2a1..62bbbe40164 100644 --- a/lisp/progmodes/hideshow.el +++ b/lisp/progmodes/hideshow.el @@ -469,15 +469,17 @@ info node `(elisp)Overlays'." :version "28.1") (defcustom hs-cycle-filter nil - "Control where \\`TAB' cycles the visibility. -This option controls where on a line where a block begins, typing -the key sequences bound to the visibility-cycling commands like -`hs-toggle-hiding' will invoke those commands. When t, you can invoke -these commands by typing \\`TAB' anywhere on a headline. Customizing -this option to other values can make those bindings be in effect only at -specific positions on the headline, like only at the line's beginning or -line's end. This allows these keys to be bound to their usual commands, -as determined by the major mode, elsewhere on the headlines." + "Control where typing a \\`TAB' cycles the visibility. +This option determines on which parts of a line where a block +begins \\`TAB' will be bound to visibility-cycling commands such +as `hs-toggle-hiding'. The value t means you can type \\`TAB' +anywhere on a headline. The value nil means \\`TAB' always has its +usual binding. The value can also be a function of no arguments, +then \\`TAB' will invoke the visibility-cycling commands where that +function returns non-nil. For example, if the value is `bolp', +those commands will be invoked at the headline's beginning. +This allows to preserve the usual bindings, as determined by the +major mode, elsewhere on the headlines." :type `(choice (const :tag "Nowhere" nil) (const :tag "Everywhere on the headline" t) (const :tag "At block beginning"