docs: add

README.org

@@ -0,0 +1,41 @@
+#+TITLE: exwm-modeline
+
+A modeline segment to display exwm workspaces.
+
+Here's how it looks near the list of [[https://github.com/nex3/perspective-el][perspectives]] (the segment of the current package is to the left):
+[[./img/screenshot.png]]
+- workspaces 0 and 5 do not have any X windows
+- workspace 1 is the current workspace
+- workspace 2 has at least one X window.
+
+Features:
+- Supports =exwm-randr= to display only workspaces related to the current monitor.
+- Numbers are clickable.
+
+* Installation
+As the package isn't yet available anywhere but in this repository, you can clone the repository, add it to the =load-path=, and =require= the package:
+#+begin_src emacs-lisp
+(require 'exwm-modeline)
+#+end_src
+
+My preferred way is to use =use-package= with =straight=:
+#+begin_src emacs-lisp
+(use-package exwm-modeline
+  :straight (:host github :repo "SqrtMinusOne/exwm-modelline")
+  :after (exwm))
+#+end_src
+
+Then put a call to =exwm-modeline-mode= somewhere after the moment when EXWM has been initialized, for instance:
+#+begin_src emacs-lisp
+(add-hook 'exwm-init-hook #'exwm-modeline-mode)
+#+end_src
+
+* Customization
+Set =exwm-modeline-randr= to nil to turn off filtering of workspaces by monitor.
+
+Set =exwm-modeline-short= to display only the current workspace in the modeline.
+
+* Credits
+[[https://github.com/nex3/perspective-el][perspective.el]] by [[https://github.com/nex3][@nex3]] was extremely instructive on how to make a modeline segment individual to a particular frame and avoid recalculating it too often.
+
+[[https://github.com/elken/doom-modeline-exwm][doom-modeline-exwm]] by [[https://github.com/elken][@elken]] also was a source of inspiration.

exwm-modeline.el

@@ -27,14 +27,21 @@
 
 ;;; Commentary:
 
-;; TODO
+;; A modeline segment to display exwm workspaces.
+;;
+;; Features:
+;; - Supports `exwm-randr' to display only of workspaces related to
+;;   the the current monitor.
+;; - The segment is clickable.
+;;
+;; Take a look at `exwm-modeline-mode' for more info.
 
-;;; Code
+;;; Code:
 (require 'exwm-workspace)
 (require 'exwm-manage)
 
 (defgroup exwm-modeline nil
-  "A modeline segment to show EXWM workspaces"
+  "A modeline segment to show EXWM workspaces."
   :group 'mode-line)
 
 (defcustom exwm-modeline-dividers '("[" "]" "|")
@@ -108,7 +115,7 @@ workspaces."
 (defun exwm-modeline--format-list (workspace-list)
   "Format the modestring for the current frame.
 
-WORKSPACE-LIST is the list of frames to display. "
+WORKSPACE-LIST is the list of frames to display."
   (cl-loop for frame in workspace-list
            for i from 0 to (length workspace-list)
            for workspace-name = (funcall exwm-workspace-index-map
@@ -177,7 +184,7 @@ WORKSPACE-LIST is the list of frames to display. "
   (frame-parameter nil 'exwm-modeline--string))
 
 (defun exwm-modeline--unmanage-advice (&rest _)
-  "An advice that updates the modeline.
+  "An advice to update the modeline.
 
 This one is meant to be attached :after
 `exwm-manage--unmanage-window', because that's when a workspace
@@ -189,6 +196,9 @@ i.e. the face in the segment has to change."
 (define-minor-mode exwm-modeline-mode
   "A mode for displaying EXWM workspaces in the modeline.
 
+Make sure to call this after EXWM was initialized, for instance
+in `exwm-init-hook'.
+
 By default, the mode displays all the workspaces on the current
 monitor.  To display only the current workspace, enable
 `exwm-modeline-short', and to disable the filtering by the
@@ -208,6 +218,7 @@ cases when the workspace list changes."
   :global t
   (if exwm-modeline-mode
       (progn
+        (exwm-modeline-update)
         (add-to-list 'global-mode-string '(:eval (exwm-modeline-segment)))
         (add-hook 'exwm-workspace-list-change-hook #'exwm-modeline-update)
         (add-hook 'exwm-randr-refresh-hook #'exwm-modeline-update)