New README

README.md

@@ -1,43 +0,0 @@
-[![MELPA](http://melpa.org/packages/focus-badge.svg)](http://melpa.org/#/focus)
-# Focus
-
-Focus provides `focus-mode` that dims the text of surrounding sections, similar to [iA Writer's](https://ia.net/writer) Focus Mode.
-
-## Installation
-
-You can install Focus using elpa. It's available on [melpa](http://melpa.milkbox.net/):
-
-<kbd> M-x package-install focus </kbd>
-
-The package has only been tried on Emacs 24.4 and 24.5, but should work on Emacs 24 or higher.
-
-## Usage
-
-Enable the `focus-mode` with <kbd> M-x focus-mode </kbd>.
-
-Also, `focus-read-only-mode` is provided, which is a mode optimized for continuous reading. It inhibits change in the buffer, hides the cursor and provides bindings for moving between *things* (defined in [Thing At Point](http://emacswiki.org/emacs/ThingAtPoint)). One can toggle `focus-read-only-mode` with <kbd> M-x focus-read-only-mode </kbd> or <kbd> C-c C-q </kbd> if `focus-mode` is enabled.
-
-Some bindings for simple navigation and exiting `focus-read-only-mode` are provided.
-
-Keybinding         | Description
--------------------|----------------------------
-<kbd> n </kbd>     | Jump to next *thing*
-<kbd> SPC </kbd>   | Jump to next *thing*
-<kbd> p </kbd>     | Jump to previous *thing*
-<kbd> S-SPC </kbd> | Jump to previous *thing*
-<kbd> i </kbd>     | Exit `focus-read-only-mode`
-<kbd> q </kbd>     | Exit `focus-read-only-mode`
-
-## Configuring
-
-The amount of dimness can be customized by setting the `focus-dimness` variable, where a positive integer indicates a more dim color (i.e. more blended with the background color of your theme), and a negative integer indicates a less dim color.
-
-Focus uses the [Thing At Point](http://emacswiki.org/emacs/ThingAtPoint) library to choose what section should be in focus. By default, modes derived from `prog-mode` uses `defun`, and modes derived from `text-mode` uses `sentence`. This a customizable by setting the `focus-mode-to-thing` variable, which is a list containing pairs on the form `(mode . thing)`.
-
-### Example
-
-This is what it looks like:
-
-Light Theme (leuven)                     |  Dark Theme (monokai)
-:---------------------------------------:|:---------------------------------------:
-<img src="./demo-light.gif" width="333"> | <img src="./demo-dark.gif" width="333">

README.org

@@ -0,0 +1,87 @@
+[[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~, which is
+   optimized for continuous reading. 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~.