Update doc for PacmanUpdates

This is a minor follow up to https://codeberg.org/xmobar/xmobar/pulls/764, so see that one as well if you got here because the plugin told you it's deprecated.

This change consists of:

  - turning the deprecated constructor in a pattern synonym for the new
    ones (which are also pattern synonyms for calling convenience),
  - dropping the `PacmanUpdatesDeprecated` type entirely,
  - adding documentation with usage examples.

3 files changed, 75 insertions, 31 deletions

diff --git a/doc/plugins.org b/doc/plugins.org
index 8ff9d7d..2c426e8 100644
--- a/doc/plugins.org
+++ b/doc/plugins.org
@@ -1355,6 +1355,7 @@
 
 *** =PacmanUpdates (Zero, One, Many, Error) Rate=
 
+  - *This constructor is deprecated. Use =PacmanUpdatesK= or =PacmanUpdatesNoK= instead.*
   - Aliases to =pacman=
   - =Zero=: a =String= to use when the system is up to date.
   - =One=: a =String= to use when only one update is available.
@@ -1371,6 +1372,48 @@
                    600
     #+end_src
 
+*** =PacmanUpdatesK Rate KernName (Bool -> Either String (Int, Bool) -> String)=
+
+  - Aliases to =pacman=
+  - =KernName=: a =String= containing the name of the kernel package, e.g. `linux`, `linux-lts`, …
+  - =(Bool -> Either String (Int, Bool) -> String)=: a function producing the
+    string to be shown by the plugin; it is fed with a `Bool` telling whether
+    the running kernel is older than the installed kernel, and an `Int` and
+    `Bool` telling the number of available updates and whether one of them is a
+    kernel update (or an error message if `checkupdates` fails).
+  - Example:
+    #+begin_src haskell
+      PacmanUpdatesK
+          600
+          "linux"
+          $ \oldKern mayb -> (if oldKern then "Running old kernel!" else "") ++
+                case mayb of
+                    Left _ -> "Some error occurred!"
+                    Right (0, False) -> "Up to date"
+                    Right (n, pendingK) | n >= 1 -> show n ++ " updates available"
+                                                  ++ if pendingK then " including a kernel update" else ""
+                    _ -> error "This is impossible"
+    #+end_src
+
+*** =PacmanUpdatesNoK Rate (Bool -> Either String Int -> String)=
+
+  - Aliases to =pacman=
+  - =(Bool -> Either String Int -> String)=: a function producing the
+    string to be shown by the plugin; it is fed with a `Bool` telling whether
+    the running kernel is older than the installed kernel, and an `Int` telling
+    the number of available updates (or an error message if `checkupdates` fails).
+  - Example:
+    #+begin_src haskell
+      PacmanUpdatesNoK
+          600
+          $ \oldKern mayb -> (if oldKern then "Running old kernel!" else "") ++
+                case mayb of
+                    Left _ -> "Some error occurred!"
+                    Right 0 -> ""
+                    Right n | n >= 1 -> show n ++ " updates available"
+                    _ -> error "impossible"
+    #+end_src
+
 *** =makeAccordion Tuning [Runnable]=
 
   - Wraps other =Runnable= plugins and makes them all collapsible to a single string:
diff --git a/src/Xmobar/Plugins/PacmanUpdates.hs b/src/Xmobar/Plugins/PacmanUpdates.hs
index ad6d2c9..bb65977 100644
--- a/src/Xmobar/Plugins/PacmanUpdates.hs
+++ b/src/Xmobar/Plugins/PacmanUpdates.hs
@@ -4,6 +4,7 @@
 {-# LANGUAGE TypeApplications #-}
 {-# LANGUAGE TypeFamilyDependencies #-}
 {-# LANGUAGE PatternSynonyms #-}
+{-# LANGUAGE ViewPatterns #-}
 
 -----------------------------------------------------------------------------
 
@@ -13,19 +14,22 @@
 Module      :  Plugins.Monitors.PacmanUpdates
 Copyright   :  (c) 2024 Enrico Maria De Angelis
             ,  (c) 2025 Alexander Pankoff
+            ,  (c) 2026 Enrico Maria De Angelis
 License     :  BSD-style (see LICENSE)
 
 Maintainer  :  Enrico Maria De Angelis <enricomaria.dean6elis@gmail.com>
 Stability   :  unstable
 Portability :  unportable
 
-A Pacman updates availablility plugin for Xmobar.
+A Pacman updates availablility plugin for Xmobar. It also informs whether a kernel update is
+available (provided the name of the kernel package), and whether the running kernel is older
+than the installed one.
 -}
 module Xmobar.Plugins.PacmanUpdates (
-    {-# DEPRECATED "These type and constructor are DEPRECATED;\
+    {-# DEPRECATED "This ctor is DEPRECATED;\
  please use `PacmanUpdates` type and `PacmanUpdatesK`\
- and `PacmanUpdatesNoK` constructors" #-}
-    PacmanUpdatesDeprecated(PacmanUpdates)
+ and `PacmanUpdatesNoK` constructors instead." #-}
+    pattern PacmanUpdates
   , PacmanUpdates ()
   , pattern PacmanUpdatesK
   , pattern PacmanUpdatesNoK) where
@@ -41,37 +45,35 @@ import Data.Void (Void)
 import Control.Arrow ((&&&))
 import qualified Data.Vector as V
 
--- | Deprecated plugin type.
-data PacmanUpdatesDeprecated
-    = PacmanUpdates (String, String, String, String) -- ^ strings to be shown for 0, 1, ≥ 2  updates,
-                                                     -- and for error respectively (in the 3rd string, for
-                                                     -- ≥ 2 updates, any occurrence of the '?' character
-                                                     -- is a placeholder for the number of available updates).
-                    Rate -- ^ rate of update
-  deriving (Read, Show)
-
-instance Exec PacmanUpdatesDeprecated where
-  alias = const "pacman"
-  rate (PacmanUpdates _ r) = r
-  run (PacmanUpdates (z, o, m, e) r)
-    = Xmobar.Run.Exec.run (Make @False r undefined printer)
-    where printer = const
-                  $ (++ deprecationNote)
-                  . \case Left _ -> e
-                          Right 0 -> z
-                          Right 1 -> o
-                          Right n -> m >>= \c -> if c == '?'
-                                                      then show n
-                                                      else pure c
-          deprecationNote = " <fc=#ff0000>(<action=`xdg-open https://codeberg.org/xmobar/xmobar/pulls/723`>"
-                           ++ "deprecated plugin, click here</action>)</fc>"
+-- | Deprecated plugin ctor (will be deleted in 2027).
+-- Use `PacmanUpdatesK` or `PacmanUpdatesNoK` instead.
+pattern PacmanUpdates :: (String, String, String, String) -- ^ `String`s to be shown for 0, 1, ≥ 2  updates,
+                                                          -- and for error respectively (in the 3rd string, for
+                                                          -- ≥ 2 updates, any occurrence of the '?' character
+                                                          -- is a placeholder for the number of available updates).
+                      -> Rate -- ^ `Rate` of update (see [Xmobar doc](https://codeberg.org/xmobar/xmobar/src/commit/39fd70308c3aef5402abe7152ade76ff7bb331bb/src/Xmobar/Plugins/Command.hs#L34)).
+                      -> PacmanUpdates False
+pattern PacmanUpdates irrelevant <- (error "PacmanUpdates: PacmanUpdates is a build-only pattern synonym (a ctor synonym)." -> irrelevant)
+  where PacmanUpdates zome r
+          = let (z, o, m, e) = zome
+                printer = const
+                        $ (++ deprecationNote)
+                        . \case Left _ -> e
+                                Right 0 -> z
+                                Right 1 -> o
+                                Right n -> m >>= \c -> if c == '?'
+                                                            then show n
+                                                            else pure c
+                deprecationNote = " <fc=#ff0000>(<action=`xdg-open https://codeberg.org/xmobar/xmobar/pulls/765`>"
+                                 ++ "deprecated plugin, click here</action>)</fc>"
+            in PacmanUpdatesNoK r printer
 
 -- | PacmanUpdates plugin parametrized over `Bool` kind: if `True` the plugin
 -- will detect if there's pending update(s) for the kernel package; if `False`
 -- it wont.
 data PacmanUpdates (b :: Bool)
-  = Make -- ^ Constructor
-         Rate -- ^ Rate of update (see [Xmobar doc](https://codeberg.org/xmobar/xmobar/src/commit/39fd70308c3aef5402abe7152ade76ff7bb331bb/src/Xmobar/Plugins/Command.hs#L34)).
+  = Make -- ^ Constructor.
+         Rate -- ^ `Rate` of update (see [Xmobar doc](https://codeberg.org/xmobar/xmobar/src/commit/39fd70308c3aef5402abe7152ade76ff7bb331bb/src/Xmobar/Plugins/Command.hs#L34)).
          (Arg b) -- ^ Optional further argument. See instances of `Updates`.
          (Printer b) -- ^ Printer. See instances of `Updates` for its signature.
 
diff --git a/src/Xmobar/Run/Types.hs b/src/Xmobar/Run/Types.hs
index e5c2e76..59270f9 100644
--- a/src/Xmobar/Run/Types.hs
+++ b/src/Xmobar/Run/Types.hs
@@ -61,7 +61,6 @@ infixr :*:
 runnableTypes :: Command :*: Monitors :*: Date :*: PipeReader :*:
                  BufferedPipeReader :*: CommandReader :*: StdinReader :*:
                  XMonadLog :*: EWMH :*: Kbd :*: Locks :*: NotmuchMail :*:
-                 PacmanUpdatesDeprecated :*:
                  PacmanUpdates False :*:
                  PacmanUpdates True :*:
 #ifdef INOTIFY