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.

1 files changed, 43 insertions, 0 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: