ui/popup: update README

modules/ui/popup/README.org

@@ -1,50 +1,59 @@
-#+TITLE: :feature popup
+#+TITLE: :ui popup
 
-This module provides a highly customizable popup window management system.
+* Table of Contents :TOC:
+- [[#description][Description]]
+  - [[#module-flags][Module Flags]]
+- [[#prerequisites][Prerequisites]]
+- [[#configuration][Configuration]]
+  - [[#set-popup-rule-and-set-popup-rules][~set-popup-rule!~ and ~set-popup-rules!~]]
+  - [[#disabling-aggressive-mode-line-hiding-in-popups][Disabling aggressive mode-line hiding in popups]]
+- [[#appendix][Appendix]]
+  - [[#commands][Commands]]
+  - [[#library][Library]]
+  - [[#hacks][Hacks]]
+
+* Description
+This module provides a customizable popup window management system.
 
-#+begin_quote
 Not all windows are created equally. Some are less important. Some I want gone
 once they have served their purpose, like code output or a help buffer. Others I
 want to stick around, like a scratch buffer or org-capture popup.
 
 More than that, popups ought to be be the second class citizens of my editor;
-spawned off to the side, discarded with the simple push of a button
+spawned off to the side, discarded with the push of a button (e.g. =ESC= or
-(Escape/C-g), and easily restored if I want to see them again. Of course, this
+=C-g=), and easily restored if I want to see them again. Of course, this system
-system should clean up after itself and kill off buffers I mark as transient.
+should clean up after itself and kill off buffers I mark as transient.
-#+end_quote
 
-* Table of Contents :TOC:
+** Module Flags
-- [[Configuration][Configuration]]
++ =+all= Enables fallback rules to ensure all temporary/special buffers (whose
-  - [[~set-popup-rules!~][~set-popup-rules!~]]
+  name begins with a space or asterix) are treated as popups.
-  - [[Disabling aggressive mode-line hiding in popups][Disabling aggressive mode-line hiding in popups]]
++ =+defaults= Enables reasonable default popup rules for a variety of buffers.
-- [[Appendix][Appendix]]
+
-  - [[Commands][Commands]]
+* Prerequisites
-  - [[Library][Library]]
+This module has no external prerequisites.
-  - [[Hacks][Hacks]]
 
 * Configuration
-** ~set-popup-rules!~
+** ~set-popup-rule!~ and ~set-popup-rules!~
-This module has one setting for defining your own rules for popups:
+This module has two functions for defining your own rules for popups:
 
 #+BEGIN_SRC emacs-lisp
+(set-popup-rule! PREDICATE &key IGNORE ACTIONS SIDE SIZE WIDTH HEIGHT SLOT VSLOT TTL QUIT SELECT MODELINE AUTOSAVE PARAMETERS)
 (set-popup-rules! &rest RULESETS)
 #+END_SRC
 
-+ ~RULESETS~ consist of a function or regexp string that matches the buffer's
+~PREDICATE~ is a predicate function or regexp string to match against the
-  name, and a list of settings. See ~display-buffer~'s, 
+buffer's name. To see what the other keywords do, check out the documentation
-  ~display-window-parameters~'s, and ~+popup-window-parameters~'s documentation
+for ~set-popup-rule!~ (=SPC h f set-popup-rule!=).
-  for what parameters are supported.
 
+#+begin_quote
 Rules are added to ~display-buffer-alist~, which instructs ~display-buffer~
 calls on how to set up windows for buffers that meet certain conditions.
 
-#+begin_quote
 The ~switch-to-buffer~ command (and its ~switch-to-buffer-*~ variants) are not
 affected by ~display-buffer-alist~.
 #+end_quote
 
-Here are a couple example rules:
+e.g.
-
 #+BEGIN_SRC emacs-lisp
 (set-popup-rules!
  '(("^ \\*" :slot -1) ; fallback rule for special buffers
@@ -57,25 +66,27 @@ Here are a couple example rules:
 #+END_SRC
 
 Omitted parameters in a ~set-popup-rules!~ will use the defaults set in
-~+popup-default-alist~ and ~+popup-default-parameters~.
+~+popup-defaults~.
 
 ** Disabling aggressive mode-line hiding in popups
-There are two ways to go about this. You can turn on modelines by changing the
+There are two ways to go about this.
-default ~'modeline~ window parameter in ~+popup-default-parameters~:
 
-#+BEGIN_SRC emacs-lisp
+1. Turn on modelines by changing the ~:modeline~ property in ~+popup-defaults~:
-;; put in private/$USER/config.el
-(map-put +popup-default-parameters 'modeline t)
-#+END_SRC
 
-This will ensure all popups have a modeline /by default/, but allows you to override this on a per-popup basis.
+   #+BEGIN_SRC emacs-lisp
+   ;; put in private/$USER/config.el
+   (map-put +popup-defaults :modeline t)
+   #+END_SRC
 
-*Alternatively*, you can disable modeline-hiding entirely:
+   This will ensure all popups have a modeline /by default/, but allows you to
+   override this on a per-popup basis.
 
-#+BEGIN_SRC emacs-lisp
+2. Disable modeline-hiding entirely:
-;; put in private/$USER/config.el
+
-(remove-hook '+popup-buffer-mode-hook '+popup|set-modeline)
+   #+BEGIN_SRC emacs-lisp
-#+END_SRC
+   ;; in ~/.doom.d/config.el
+   (remove-hook '+popup-buffer-mode-hook #'+popup|set-modeline-on-enable)
+   #+END_SRC
 
 * Appendix
 ** Commands