ui/zen: proofread & expand readme

modules/ui/zen/README.org

@@ -5,6 +5,7 @@
 
 * Table of Contents :TOC_3:noexport:
 - [[#description][Description]]
+  - [[#usage][Usage]]
   - [[#module-flags][Module Flags]]
   - [[#plugins][Plugins]]
   - [[#hacks][Hacks]]
@@ -15,12 +16,34 @@
   - [[#enable-fullscreen-on-activation][Enable fullscreen on activation]]
 
 * Description
-This module provides ~writeroom-mode~, which transforms Emacs into a
-comfortable writing or coding space by centering the buffer, removing
-superfluous UI elements, and turning on variable-pitch fonts (but keeps certain
-elements fixed-pitch, where it makes sense to).
+This module provides two minor modes that make Emacs into a more comfortable
+writing or coding environment. Folks familiar with "distraction-free" or "zen"
+modes from other editors -- or [[https://github.com/rnkn/olivetti][olivetti]], [[https://github.com/zk-phi/sublimity][sublimity]], and [[https://github.com/IdoMagal/Tabula-Rasa][tabula-rasa]] (Emacs
+plugins) -- will feel right at home.
 
-If you've used olivetti, sublimity, or tabula-rasa, you will feel right at home.
+These modes are:
+
++ ~mixed-pitch-mode~ :: Which renders (most) text in a variable pitch font (see
+  ~doom-variable-pitch-font~). Unlike ~variable-pitch-mode~, this will not
+  affect segments of text that are intended to remain in a fixed pitch font,
+  such as code blocks or ASCII tables.
++ ~writeroom-mode~ :: Our all-in-one "zen" mode that will:
+  1. Center the current buffer.
+  2. Remove superfluous UI elements (like the modeline).
+  3. Activate ~mixed-pitch-mode~.
+  4. Scale up the buffer's text slightly (see ~+zen-text-scale~).
+  5. And make the window's borders slightly thicker (see
+     ~+zen-window-divider-size~).
+     
+** Usage
+This module provides two entry points:
+
++ ~M-x +zen/toggle~ :: toggles ~writeroom-mode~ (restricted to the current
+  buffer).
++ ~M-x +zen/toggle-fullscreen~ :: toggles zen mode in full-screen mode (deletes
+  other windows and full screens the Emacs frame).
+
+Invoke either command again to undo the change.
 
 ** Module Flags
 This module provides no flags.
@@ -30,9 +53,13 @@ This module provides no flags.
 + [[https://gitlab.com/jabranham/mixed-pitch][mixed-pitch]]
 
 ** Hacks
-+ =mixed-pitch= has been modified not to override ~:height~ properties on the
-  faces it remaps. This means text-scale can affect the ~fixed-pitch~ faces as
-  well; See https://gitlab.com/jabranham/mixed-pitch/issues/6#note_79691741.
++ Doom has disabled all of writeroom-mode's "global" effects
+  (~writeroom-global-effects~ and ~writeroom-maximize-window~ are set to ~nil~),
+  and encapsulated them into the ~+zen/toggle-fullscreen~ command, whereas
+  ~+zen/toggle~ will only operate on the current buffer. This way, the user may
+  choose how far-reaching they want its effect to be.
++ ~text-scale~ has been advised to adjust ~visual-fill-column~'s margins, so its
+  text won't "squeeze" as you scale it up (or "spill" when scaled down).
 
 * Prerequisites
 This module has no prerequisites.