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.

2 files changed, 32 insertions, 31 deletions

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