Focus/README.org

[[https://melpa.org/#/focus][file:https://melpa.org/packages/focus-badge.svg]]
[[https://stable.melpa.org/#/focus][file:https://stable.melpa.org/packages/focus-badge.svg]]

* Focus

  [[./focus-demo.gif]]

  This is Focus, a package that dims surrounding text. It works with any theme
  and can be configured to focus in on different regions like sentences,
  paragraphs or code-blocks.

* Installation

  It's available on [[https://melpa.org/#/focus][MELPA]] and [[https://stable.melpa.org/#/focus][MELPA Stable]]:

  #+BEGIN_EXAMPLE
  M-x package-install focus
  #+END_EXAMPLE

* Usage

  Enable ~focus-mode~ with ~M-x focus-mode~.

  A few interactive functions are provided:

  | Function             | Description                                                              |
  |----------------------+--------------------------------------------------------------------------|
  | ~focus-change-thing~ | Adjust the narrowness of the focused section for the current buffer      |
  | ~focus-pin~          | Pin the focused section to its current location or the region, if active |
  | ~focus-unpin~        | Unpin the focused section                                                |
  | ~focus-next-thing~   | Move the point to the middle of the Nth next thing                       |
  | ~focus-prev-thing~   | Move the point to the middle of the Nth previous thing                   |

  Focus relies on [[https://www.emacswiki.org/emacs/ThingAtPoint][Thing At Point]], which can retrieve a /thing/ surrounding the
  point. These /things/ may be a symbol, list, S-expression (sexp), function
  definition (defun), sentence, line, page and others. Calling ~M-x
  focus-change-thing~ allows you to interactively change the kind of region
  which should be in focus.

** Focus read-only mode

   Enable ~focus-read-only-mode~ with ~M-x focus-read-only-mode~. It inhibits
   changes in a buffer, hides the cursor and provides bindings for moving
   between /things/.

   Some bindings for simple navigation and exiting `focus-read-only-mode` are
   provided.

   | Keybinding | Description                 |
   |------------+-----------------------------|
   | ~n~        | Jump to next /thing/        |
   | ~SPC~      | Jump to next /thing/        |
   | ~p~        | Jump to previous /thing/    |
   | ~S-SPC~    | Jump to previous /thing/    |
   | ~i~        | Exit ~focus-read-only-mode~ |
   | ~q~        | Exit ~focus-read-only-mode~ |

* Customization

   The choice of what /thing/ is suitable for a mode may be configured by
   setting the variable ~focus-mode-to-thing~. The default is

   #+BEGIN_EXAMPLE
   '((prog-mode . defun) (text-mode . sentence))
   #+END_EXAMPLE

   For modes inheriting ~prog-mode~ (which are most programming modes), the
   default is the function-body, and for modes inheriting ~text-mode~, the
   default is a sentence.

   For instance, adding the following to your ~.emacs~-file:

   #+BEGIN_SRC emacs-lisp
   (add-to-list 'focus-mode-to-thing '(python-mode . paragraph))
   #+END_SRC

   changes ~python-mode~ to focus in on code-blocks with no blank lines rather
   than the entire function.

   According to [[https://www.reddit.com/r/emacs/comments/b1vrar/lsp_support_for_focusel_using_lspmode/][this reddit post]], Focus plays nice with ~lsp-mode~.

** Faces

   Focus offers two faces, one for the focused- and unfocused area. By default,
   the ~focus-focused~ is the empty face, meaning there is no change, and
 ~focus-unfocused~ inherits the comment face (which is usually subtle). The
   faces can easily be customized via ~M-x list-faces-display~.