doomemacs/modules/ui/zen/README.org

#+title:    :ui zen
#+subtitle: Distraction-free mode for the eternally distracted
#+created:  December 20, 2019
#+since:    21.12.0

* Description :unfold:
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 [[doom-package:olivetti]], [[doom-package:sublimity]], and [[doom-package:tabula-rasa]] (Emacs
plugins) -- 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~).
     
** Maintainers
- [[doom-user:][@hlissner]]

[[doom-contrib-maintainer:][Become a maintainer?]]

** Module flags
/This module has no flags./

** Packages
- [[doom-package:mixed-pitch]]
- [[doom-package:writeroom-mode]]

** Hacks
+ 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).

** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./

* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]

/This module has no external requirements./

* Usage
This module provides two entry points:

- ~M-x +zen/toggle~ (on [[kbd:][<leader> t z]]): toggles ~writeroom-mode~ (restricted to
  the current buffer).
- ~M-x +zen/toggle-fullscreen~ (on [[kbd:][<leader> t Z]]): toggles zen mode in
  full-screen mode (deletes other windows and full screens the Emacs frame).

Invoke either command again to undo the change.

* TODO Configuration
#+begin_quote
 󱌣 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote

* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]

* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]

* TODO Appendix
#+begin_quote
 󱌣 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote