branch: externals/pulsar
commit c675985cb12fb89fd39ea0b844c2cc10d89680c4
Author: Protesilaos Stavrou <[email protected]>
Commit: Protesilaos Stavrou <[email protected]>
Rewrite the manual
This is a good time to review it as I went through the code and I
still remember everything. It needed to be reorganised, anyway, as
that massive "Overview" was not giving us the option to establish
links between different sections. Now it is easier to read.
---
README.org | 378 +++++++++++++++++++++++++++++++++----------------------------
1 file changed, 206 insertions(+), 172 deletions(-)
diff --git a/README.org b/README.org
index 27cfc58dda..5b5e40cd18 100644
--- a/README.org
+++ b/README.org
@@ -1,4 +1,4 @@
-#+title: pulsar.el: Pulse highlight line on demand or after running select
functions
+#+title: pulsar.el: Highlight line automatically after some change or on demand
#+author: Protesilaos Stavrou
#+email: [email protected]
#+language: en
@@ -11,7 +11,7 @@
#+texinfo_filename: pulsar.info
#+texinfo_dir_category: Emacs misc features
#+texinfo_dir_title: Pulsar: (pulsar)
-#+texinfo_dir_desc: Pulse highlight line on demand or after running select
functions
+#+texinfo_dir_desc: Highlight line automatically after some change or on demand
#+texinfo_header: @set MAINTAINERSITE @uref{https://protesilaos.com,maintainer
webpage}
#+texinfo_header: @set MAINTAINER Protesilaos Stavrou
#+texinfo_header: @set MAINTAINEREMAIL @email{[email protected]}
@@ -60,143 +60,6 @@ included in the section entitled “GNU Free Documentation
License.”
modify this GNU manual.”
#+end_quote
-* Overview
-:PROPERTIES:
-:CUSTOM_ID: h:62d716b4-44f7-4078-85d2-29a7da8ca253
-:END:
-
-#+vindex: pulse-pulse-functions
-#+findex: pulsar-mode
-#+findex: pulsar-global-mode
-This is a small package that temporarily highlights the current line
-after a given function is invoked. The affected functions are defined
-in the user option ~pulsar-pulse-functions~ and the effect takes place
-when either ~pulsar-mode~ (buffer-local) or ~pulsar-global-mode~ is
-enabled.
-
-#+vindex: pulsar-resolve-pulse-function-aliases
-By default, Pulsar does not try to behave the same way for a function's
-aliases. If those are not added explicitly to the ~pulsar-pulse-functions~,
-they will not have a pulse effect. However, the user option
-~pulsar-resolve-pulse-function-aliases~ can be set to a non-nil value
-to change this behaviour, meaning that Pulsar will cover a function's
-aliases even if those are not explicitly added to the ~pulsar-pulse-functions~.
-
-#+findex: pulsar-pulse-region-functions
-Pulsar can also produce an effect over a specific region. This is
-useful to, for example, highlight the area covered by text that is
-pasted in the buffer. The user option ~pulsar-pulse-region-functions~
-defines a list of functions that are region-aware in this regard. The
-default value covers copyring, pasting, and undoing/redoing.
-
-#+findex: pulsar-pulse-on-window-change
-The pulse effect also happens whenever there is a change to the window
-layout. This includes the selection, addition, deletion, resize of
-windows in a frame. Users who do not want this to happen can set the
-user option ~pulsar-pulse-on-window-change~ to a nil value.
-
-#+vindex: pulsar-delay
-#+vindex: pulsar-iterations
-#+vindex: pulsar-face
-The overall duration of the highlight is determined by a combination of
-~pulsar-delay~ and ~pulsar-iterations~. The latter determines the
-number of blinks in a pulse, while the former sets their delay in
-seconds before they fade out. The applicable face is specified in
-~pulsar-face~.
-
-#+vindex: pulsar-pulse
-To disable the pulse but keep the temporary highlight, set the user
-option ~pulsar-pulse~ to nil. The current line will remain highlighted
-until another command is invoked.
-
-#+vindex: pulsar-inhibit-hidden-buffers
-The user option ~pulsar-inhibit-hidden-buffers~ controls whether
-Pulsar is active in hidden buffers. These are buffers that users
-normally do not interact with and are not displayed in the interface
-of the various buffer-switching commands. When this user option is
-nil, ~pulsar-mode~ will work in those buffers as well.
-
-#+findex: pulsar-pulse-line
-#+findex: pulsar-highlight-line-temporarily
-To highlight the current line on demand, use the ~pulsar-pulse-line~
-command. When ~pulsar-pulse~ is non-nil (the default), its highlight
-will pulse before fading away. Whereas the ~pulsar-highlight-line-temporarily~
-command never pulses the line: the highlight stays in place and is static (as
if
-~pulsar-pulse~ is ~nil~) and is removed when the point moves.
-
-#+findex: pulsar-pulse-region
-The command ~pulsar-pulse-region~ pulses the active region. The effect
-of the pulse is controlled by the aforementioned user options, namely,
-~pulsar-delay~, ~pulsar-iterations~, ~pulsar-face~.
-
-#+findex: pulsar-highlight-temporarily-dwim
-For temporary static highlights, a do-what-I-mean command is also on
-offer: ~pulsar-highlight-temporarily-dwim~. It temporarily highlights
-the current line line like ~pulsar-highlight-line-temporarily~~. If
-the region is active, it applies its effect there. The region may also
-be a rectangle (internally they differ from ordinary regions).
-
-#+findex: pulsar-highlight-permanently
-The command ~pulsar-highlight-permanently~ adds a permanent static
-highlight to the current line. The effect stays in place even after
-the point moves. When the region is active, the highlight is applied
-from the beginning to the end of the region. Otherwise the highlight
-is applied to the current line. [ The command ~pulsar-highlight-permanently~
is part of {{{development-version}}}. ]
-
-#+findex: pulsar-highlight-permanently-remove
-The command ~pulsar-highlight-permanently-remove~ removes permanent
-static highlights from the active region or current line. This command
-operates on the entire buffer when it is called with a universal
-prefix argument (=C-u= by default). [ The command
~pulsar-highlight-permanently-remove~ is part of {{{development-version}}}. ]
-
-#+findex: pulsar-highlight-permanently-dwim
-The command ~pulsar-highlight-permanently-dwim~ adds a permanent
-static highlight if there is none or removes it if there is one. It
-operates on the currently active region or line at point. [ The command
~pulsar-highlight-permanently-dwim~ is part of {{{development-version}}}. ]
-
-#+vindex: pulsar-highlight-face
-The user option ~pulsar-highlight-face~ controls which face is used
-for static highlight (temporary or permanent). By default, it is the
-same as the ~pulsar-face~, which is for pulse effects, but can be
-assigned to a different face to help differentiate pulses from static
-highlights.
-
-Why the name "pulsar"? It sounds like "pulse" and is a recognisable
-word. Though if you need a backronym, consider "Pulsar Unquestionably
-Luminates, Strictly Absent the Radiation".
-
-** Convenience functions
-:PROPERTIES:
-:CUSTOM_ID: h:6ca69953-1a89-4968-a46c-2fa5e57aca9b
-:END:
-
-Depending on the user's workflow, there may be a need for differently
-colored pulses. These are meant to provide an ad-hoc deviation from the
-standard style of the command ~pulsar-pulse-line~ (which is governed by
-the user option ~pulsar-face~). Pulsar thus provides the following for
-the user's convenience:
-
-#+findex: pulsar-pulse-line-red
-- ~pulsar-pulse-line-red~
-
-#+findex: pulsar-pulse-line-green
-- ~pulsar-pulse-line-green~
-
-#+findex: pulsar-pulse-line-yellow
-- ~pulsar-pulse-line-yellow~
-
-#+findex: pulsar-pulse-line-blue
-- ~pulsar-pulse-line-blue~
-
-#+findex: pulsar-pulse-line-magenta
-- ~pulsar-pulse-line-magenta~
-
-#+findex: pulsar-pulse-line-cyan
-- ~pulsar-pulse-line-cyan~
-
-These can be called with =M-x=, assigned to a hook and/or key binding,
-or be incorporated in custom functions.
-
* Installation
:PROPERTIES:
:CUSTOM_ID: h:812f7616-7e0f-489f-a908-1cb759ca64ce
@@ -256,41 +119,23 @@ Everything is in place to set up the package.
:END:
#+cindex: Package configuration
-Remember to read the doc string of each of these variables.
+Remember to read the doc string of each of these variables or functions.
#+begin_src emacs-lisp
-(require 'pulsar)
-
-;; Check the default value of `pulsar-pulse-functions'. That is where
-;; you add more commands that should cause a pulse after they are
-;; invoked
-
-(setq pulsar-pulse t)
-(setq pulsar-delay 0.055)
-(setq pulsar-iterations 10)
-(setq pulsar-face 'pulsar-magenta)
-(setq pulsar-highlight-face 'pulsar-yellow)
-
-(pulsar-global-mode 1)
-
-;; OR use the local mode for select mode hooks
-
-(dolist (hook '(org-mode-hook emacs-lisp-mode-hook))
- (add-hook hook #'pulsar-mode))
-
-;; pulsar does not define any key bindings. This is just a sample that
-;; respects the key binding conventions. Evaluate:
-;;
-;; (info "(elisp) Key Binding Conventions")
-;;
-;; The author uses C-x l for `pulsar-pulse-line' and C-x L for
-;; `pulsar-highlight-line'.
-;;
-;; You can replace `pulsar-highlight-line' with the command
-;; `pulsar-highlight-dwim'.
-(let ((map global-map))
- (define-key map (kbd "C-c h p") #'pulsar-pulse-line)
- (define-key map (kbd "C-c h h") #'pulsar-highlight-line))
+(use-package pulsar
+ :ensure t
+ :bind
+ ( :map global-map
+ ("C-x l" . pulsar-pulse-line) ; overrides `count-lines-page'
+ ("C-x L" . pulsar-highlight-permanently-dwim)) ; or use
`pulsar-highlight-temporarily-dwim'
+ :init
+ (pulsar-global-mode 1)
+ :config
+ (setq pulsar-delay 0.055)
+ (setq pulsar-iterations 5)
+ (setq pulsar-face 'pulsar-green)
+ (setq pulsar-region-face 'pulsar-yellow)
+ (setq pulsar-highlight-face 'pulsar-magenta))
#+end_src
** Use pulsar with next-error
@@ -334,6 +179,195 @@ For example:
(add-hook 'minibuffer-setup-hook #'pulsar-pulse-line-blue)
#+end_src
+* Overview
+:PROPERTIES:
+:CUSTOM_ID: h:62d716b4-44f7-4078-85d2-29a7da8ca253
+:END:
+
+This is a small Emacs package that automatically highlights the
+current line after certain functions are invoked. It can also
+highlight a line or region on demand. The idea is to make it easier to
+find where the point is, what was affected, and also to bring
+attention to something in a buffer.
+
+#+findex: pulsar-mode
+#+findex: pulsar-global-mode
+#+vindex: pulsar-pulse-functions
+When ~pulsar-mode~ is enabled in the current buffer, a pulsing
+highlight effect will be produced after any command listed in the user
+option ~pulsar-pulse-functions~. The ~pulsar-global-mode~ has the
+same effect in all buffers ([[#h:87ba8ed7-251d-4e74-8eb9-964c51c26bfa][More
ways to create automatic pulse effects]]).
+
+* Style of a pulse effect
+:PROPERTIES:
+:CUSTOM_ID: h:90cc699b-7f4a-414d-ab4e-1ab553992a14
+:END:
+
+#+vindex: pulsar-delay
+#+vindex: pulsar-iterations
+The pulse's duration is influenced by the user option ~pulsar-delay~.
+The greater the value, the longer the highlight will stay on display.
+The user option ~pulsar-iterations~ controls through how many steps
+does the produced pulse colour go through before it fades away.
+
+#+vindex: pulsar-face
+#+vindex: pulsar-generic
+#+vindex: pulsar-red
+#+vindex: pulsar-green
+#+vindex: pulsar-yellow
+#+vindex: pulsar-blue
+#+vindex: pulsar-magenta
+#+vindex: pulsar-cyan
+All pulse effects are done with the user option ~pulsar-face~. Any
+face with a background attribute can be used for this purpose. Pulsar
+defines several such faces, namely, ~pulsar-generic~ (the default
+value), ~pulsar-red~, ~pulsar-green~, ~pulsar-yellow~, ~pulsar-blue~,
+~pulsar-magenta~, ~pulsar-cyan~.
+
+* Temporary static highlights
+:PROPERTIES:
+:CUSTOM_ID: h:ae9d40d5-5f32-4bfe-ad75-ac6311b5b11f
+:END:
+
+[ Revised as part of {{{development-version}}}. The
+ ~pulsar-highlight-temporarily~ supersedes ~pulsar-highlight-line~
+ and ~pulsar-highlight-dwim~. ]
+
+#+findex: pulsar-highlight-pulse
+The command ~pulsar-highlight-pulse~ will produce a pulse effect on
+demand. This is independent of ~pulsar-mode~ and all the conditions
+for automatically creating a pulse.
+
+#+findex: pulsar-highlight-temporarily
+Unlike pulses which disappear after some time, it is possible to
+create temporary static highlights that stay in place until another
+command is performed. The ~pulsar-highlight-temporarily~ will produce
+such a static highlight for the active region or current line.
+
+#+vindex: pulsar-highlight-face
+The user option ~pulsar-highlight-face~ controls which face is used
+for static highlight (temporary or permanent). By default, it is the
+same as the ~pulsar-face~, which is for pulse effects, but can be
+assigned to a different face to help differentiate pulses from static
+highlights ([[#h:90cc699b-7f4a-414d-ab4e-1ab553992a14][Style of a pulse
effect]]).
+
+* Permanent static highlights
+:PROPERTIES:
+:CUSTOM_ID: h:690dac43-338b-4320-a1fb-db6b919016be
+:END:
+
+[ All the permanent highlights are part of {{{development-version}}}. ]
+
+#+findex: pulsar-highlight-permanently
+The command ~pulsar-highlight-permanently~ adds a permanent static
+highlight to the current line. The effect stays in place even after
+the point moves. When the region is active, the highlight is applied
+from the beginning to the end of the region. Otherwise the highlight
+is applied to the current line.
+
+#+findex: pulsar-highlight-permanently-remove
+The command ~pulsar-highlight-permanently-remove~ removes permanent
+static highlights from the active region or current line. This command
+operates on the entire buffer when it is called with a universal
+prefix argument (=C-u= by default).
+
+#+findex: pulsar-highlight-permanently-dwim
+The command ~pulsar-highlight-permanently-dwim~ adds a permanent
+static highlight if there is none or removes it if there is one. It
+operates on the currently active region or line at point.
+
+Permanent static highlights are rendered with the face specified in
+the user option ~pulsar-highlight-face~. It is the same used for their
+temporary counterparts ([[#h:ae9d40d5-5f32-4bfe-ad75-ac6311b5b11f][Temporary
static highlights]]).
+
+* More ways to create automatic pulse effects
+:PROPERTIES:
+:CUSTOM_ID: h:87ba8ed7-251d-4e74-8eb9-964c51c26bfa
+:END:
+
+The ~pulsar-mode~ and ~pulsar-global-mode~ perform an automatic pulse
+after a function in the ~pulsar-pulse-functions~ is called
([[#h:62d716b4-44f7-4078-85d2-29a7da8ca253][Overview]]).
+They can do the same in more cases.
+
+#+vindex: pulsar-pulse-region-functions
+- Region-related changes :: Pulsar can also produce an effect over a
+ specific region. This is useful to, for example, highlight the area
+ covered by text that is pasted in the buffer. The user option
+ ~pulsar-pulse-region-functions~ defines a list of functions that are
+ region-aware in this regard. The default value covers copyring,
+ pasting, and undoing/redoing.
+#+vindex: pulsar-pulse-on-window-change
+- Window-related changes :: The pulse effect can be created whenever
+ there is a change to the window layout. This includes the selection,
+ addition, deletion, orr resize of windows in a frame. Users can opt
+ in to this feature by setting ~pulsar-pulse-on-window-change~ to a
+ non-~nil~ value.
+
+#+vindex: pulsar-region-face
+The user option ~pulsar-region-face~ sets the face that is used for
+region-related pulses. By default, it is the same as the ~pulsar-face~
+([[#h:90cc699b-7f4a-414d-ab4e-1ab553992a14][Style of a pulse effect]]).
+
+* Resolve function aliases
+:PROPERTIES:
+:CUSTOM_ID: h:48c96d7d-77f1-42ba-955c-11982747c7d4
+:END:
+
+By default, Pulsar does not try to resolve and act on a function's
+aliases ([[#h:62d716b4-44f7-4078-85d2-29a7da8ca253][Overview]]). It only works
with the exact symbols it is given.
+If those aliases are not added to the ~pulsar-pulse-functions~ and/or
+~pulsar-pulse-region-functions~, they will not produce a pulse effect
+([[#h:87ba8ed7-251d-4e74-8eb9-964c51c26bfa][More ways to create automatic
pulse effects]]).
+
+#+vindex: pulsar-resolve-pulse-function-aliases
+The user option ~pulsar-resolve-pulse-function-aliases~ can
+be set to a non-~nil~ value to make Pulsar check for the aliases of
+all the function symbols it is aware of and act on them accordingly.
+
+* Omit hidden buffers
+:PROPERTIES:
+:CUSTOM_ID: h:b67b2ede-bbfc-4318-b395-3ee276434aa4
+:END:
+
+#+vindex: pulsar-inhibit-hidden-buffers
+The user option ~pulsar-inhibit-hidden-buffers~ controls whether
+Pulsar is active in hidden buffers. These are buffers that users
+normally do not interact with and are not displayed in the interface
+of the various buffer-switching commands. When this user option is set
+to ~nil~, Pulsar will work in those buffers as well
([[#h:62d716b4-44f7-4078-85d2-29a7da8ca253][Overview]]).
+
+* Convenience functions
+:PROPERTIES:
+:CUSTOM_ID: h:6ca69953-1a89-4968-a46c-2fa5e57aca9b
+:END:
+
+Depending on the user's workflow, there may be a need for differently
+colored pulses. These are meant to provide an ad-hoc deviation from the
+standard style of the command ~pulsar-pulse-line~ (which is governed by
+the user option ~pulsar-face~). Pulsar thus provides the following for
+the user's convenience:
+
+#+findex: pulsar-pulse-line-red
+- ~pulsar-pulse-line-red~
+
+#+findex: pulsar-pulse-line-green
+- ~pulsar-pulse-line-green~
+
+#+findex: pulsar-pulse-line-yellow
+- ~pulsar-pulse-line-yellow~
+
+#+findex: pulsar-pulse-line-blue
+- ~pulsar-pulse-line-blue~
+
+#+findex: pulsar-pulse-line-magenta
+- ~pulsar-pulse-line-magenta~
+
+#+findex: pulsar-pulse-line-cyan
+- ~pulsar-pulse-line-cyan~
+
+These can be called with =M-x=, assigned to a hook and/or key binding,
+or be incorporated in custom functions.
+
* Integration with other packages
:PROPERTIES:
:CUSTOM_ID: h:b884f2ac-82f3-48c0-bee5-6709d6647b1d
