[nongnu] elpa/focus 5e483363ac 75/82: New README

[ELPA Syncer]

branch: elpa/focus
commit 5e483363ac9aab7033996e1206b0a93db9ce8dc8
Author: Lars Tveito <larstvei@ifi.uio.no>
Commit: Lars Tveito <larstvei@ifi.uio.no>

    New README
---
 README.md      |  43 ----------------------------
 README.org     |  87 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 demo-dark.gif  | Bin 361222 -> 0 bytes
 demo-light.gif | Bin 285306 -> 0 bytes
 focus-demo.gif | Bin 0 -> 1827667 bytes
 5 files changed, 87 insertions(+), 43 deletions(-)

diff --git a/README.md b/README.md
deleted file mode 100644
index 3cc53ad6ee..0000000000
--- a/README.md
+++ /dev/null
@@ -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">
diff --git a/README.org b/README.org
new file mode 100644
index 0000000000..5d39115d8f
--- /dev/null
+++ b/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~.
diff --git a/demo-dark.gif b/demo-dark.gif
deleted file mode 100644
index 94c1c2889f..0000000000
Binary files a/demo-dark.gif and /dev/null differ
diff --git a/demo-light.gif b/demo-light.gif
deleted file mode 100644
index 59a63ab06b..0000000000
Binary files a/demo-light.gif and /dev/null differ
diff --git a/focus-demo.gif b/focus-demo.gif
new file mode 100644
index 0000000000..4a10b928d1
Binary files /dev/null and b/focus-demo.gif differ