From dc79db872ac0a90b759f7999afadc75a60b2ade2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miha=20Rihtar=C5=A1i=C4=8D?= Date: Sat, 10 Sep 2022 17:47:12 +0200 Subject: [PATCH] Improve doc strings of comint input fontification mechanism --- lisp/comint.el | 14 +++++++++----- lisp/ielm.el | 13 ++++++++++--- lisp/shell.el | 27 +++++++++++++++++++-------- 3 files changed, 38 insertions(+), 16 deletions(-) diff --git a/lisp/comint.el b/lisp/comint.el index 751e561d3e..696dac3d12 100644 --- a/lisp/comint.el +++ b/lisp/comint.el @@ -4030,9 +4030,13 @@ comint-indirect-setup-function `after-change-major-mode-hook' are bound to nil.") (defcustom comint-indirect-setup-hook nil - "Hook run after setting up an indirect comint fontification buffer. -It is run after the indirect buffer is set up for fontification -of input regions." + "Hook run in an indirect buffer for input fontification. +Input fontification and indentation, if enabled, is performed in +an indirect buffer, whose major mode and syntax highlighting are +set up according to `comint-indirect-setup-function'. After this +setup is done, run this hook with the indirect buffer as the +current buffer. This can be used to further customize +fontification and other behaviour of the indirect buffer." :group 'comint :type 'hook :version "29.1") @@ -4117,8 +4121,8 @@ comint--fl-ppss-flush-indirect (defun comint--fl-fontify-region (fun beg end verbose) "Fontify process output and user input in the current comint buffer. -First, highlight the region between BEG and END using FUN. Then -highlight only the input text in the region with the help of an +First, fontify the region between BEG and END using FUN. Then +fontify only the input text in the region with the help of an indirect buffer. VERBOSE is passed to the fontify-region functions. Skip fontification of input regions with non-nil `comint--fl-inhibit-fontification' text property." diff --git a/lisp/ielm.el b/lisp/ielm.el index 211804210c..4a10c00297 100644 --- a/lisp/ielm.el +++ b/lisp/ielm.el @@ -475,16 +475,23 @@ ielm-set-pm ;;; Input fontification (defcustom ielm-comint-fl-enable t - "Enable highlighting of input in ielm buffers. + "Enable fontification of input in ielm buffers. This variable only has effect when creating an ielm buffer. Use -the command `comint-fl-mode' to toggle highlighting of input in +the command `comint-fl-mode' to toggle fontification of input in an already existing ielm buffer." :type 'boolean :safe 'booleanp :version "29.1") (defcustom ielm-indirect-setup-hook nil - "Hook run after setting up an indirect ielm fontification buffer." + "Hook run in an indirect buffer for input fontification. +Input fontification and indentation of an IELM buffer, if +enabled, is performed in an indirect buffer, whose indentation +and syntax highlighting are set up with `emacs-lisp-mode'. In +addition to `comint-indirect-setup-hook', run this hook with the +indirect buffer as the current buffer after its setup is done. +This can be used to further customize fontification and other +behaviour of the indirect buffer." :type 'boolean :safe 'booleanp :version "29.1") diff --git a/lisp/shell.el b/lisp/shell.el index eccac66376..834ca6b627 100644 --- a/lisp/shell.el +++ b/lisp/shell.el @@ -309,16 +309,23 @@ shell-input-autoexpand :group 'shell) (defcustom shell-comint-fl-enable t - "Enable highlighting of input in shell buffers. + "Enable fontification of input in shell buffers. This variable only has effect when the shell is started. Use the -command `comint-fl-mode' to toggle highlighting of input." +command `comint-fl-mode' to toggle fontification of input." :type 'boolean :group 'shell :safe 'booleanp :version "29.1") (defcustom shell-indirect-setup-hook nil - "Hook run after setting up an indirect shell fontification buffer." + "Hook run in an indirect buffer for input fontification. +Input fontification and indentation of a `shell-mode' buffer, if +enabled, is performed in an indirect buffer, whose indentation +and syntax highlighting is set up with `sh-mode'. In addition to +`comint-indirect-setup-hook', run this hook with the indirect +buffer as the current buffer after its setup is done. This can +be used to further customize fontification and other behaviour of +the indirect buffer." :type 'boolean :group 'shell :safe 'booleanp @@ -1680,7 +1687,7 @@ shell-highlight-undef-matcher t)) (defvar-local shell--highlight-undef-indirect nil - "t if shell commands are fontified in `comint-indirect-buffer'.") + "Non-nil if shell commands are fontified in `comint-indirect-buffer'.") (declare-function sh-feature "sh-script" (alist &optional function)) (defvar sh-leading-keywords) @@ -1700,7 +1707,7 @@ shell-highlight-undef-mode (font-lock-remove-keywords nil shell-highlight-undef-keywords)))) (font-lock-remove-keywords nil shell-highlight-undef-keywords)) (remove-hook 'comint-fl-mode-hook - #'shell-highlight-undef-reset-mode t) + #'shell-highlight-undef-mode-restart t) (when shell-highlight-undef-mode (when comint-use-prompt-regexp @@ -1742,12 +1749,16 @@ shell-highlight-undef-mode (t (funcall setup)))) (add-hook 'comint-fl-mode-hook - #'shell-highlight-undef-reset-mode nil t)) + #'shell-highlight-undef-mode-restart nil t)) (font-lock-flush)) -(defun shell-highlight-undef-reset-mode () - "If `shell-highlight-undef-mode' is on, turn it off and on." +(defun shell-highlight-undef-mode-restart () + "If `shell-highlight-undef-mode' is on, restart it. +`shell-highlight-undef-mode' performs its setup differently +depending on `comint-fl-mode'. It's useful to call this function +when switching `comint-fl-mode' in order to make +`shell-highlight-undef-mode' redo its setup." (when shell-highlight-undef-mode (shell-highlight-undef-mode 1))) -- 2.37.2