[elpa] externals/isearch-mb ce41e00 12/20: Add a Readme

[Stefan Monnier]

branch: externals/isearch-mb
commit ce41e0073f1388e72a39b457c1cb134f6de9cdca
Author: Augusto Stoffel <arstoffel@gmail.com>
Commit: Augusto Stoffel <arstoffel@gmail.com>

    Add a Readme
---
 README.md     | 107 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 isearch-mb.el |  14 ++++++--
 2 files changed, 119 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d682160
--- /dev/null
+++ b/README.md
@@ -0,0 +1,107 @@
+Isearch-Mb
+==========
+
+This Emacs package provides an alternative Isearch UI based on the
+minibuffer.  This allows editing the search string in arbitrary ways
+without any special maneuver; unlike standard Isearch, cursor motion
+commands do not end the search.  Moreover, in comparison with standard
+Isearch, this package provides simplified visual feedback in the echo
+area.
+
+To use the package, just add the following to your init file:
+``` elisp
+(isearch-mb-mode)
+```
+
+Keybindings
+-----------
+
+During a search, `isearch-mb-minibuffer-map` is active.  By default,
+it includes the following commands:
+
+- <kbd>C-s</kbd>: `isearch-repeat-forward`
+- <kbd>C-r</kbd>: `isearch-repeat-backward`
+- <kbd>M-<</kbd>: `isearch-beginning-of-buffer`
+- <kbd>M-></kbd>: `isearch-end-of-buffer`
+- <kbd>M-%</kbd>: `isearch-query-replace`
+- <kbd>C-M-%</kbd>: `isearch-query-replace-regexp`
+- <kbd>M-s</kbd> prefix: similar to standard Isearch
+
+Everything else works as in a plain minibuffer, e.g. <kbd>RET</kbd>
+ends the search normally and <kbd>C-g</kbd> cancels it.
+
+Some customization ideas
+------------------------
+
+Isearch provides a myriad of customization options, and most of them
+make just as much sense in Isearch-Mb mode.  The following are some
+uncontroversial settings that would make sense for most people:
+
+``` elisp
+(setq-default
+ ;; Match count next to minibuffer prompt
+ isearch-lazy-count t
+ ;; Don't be stingy with history; default is to keep just 16 entries
+ search-ring-max 200
+ regexp-search-ring-max 200)
+```
+
+Note that since Isearch-Mb relies on a regular minibuffer, you can use
+you favorite tool to browse the history of previous search strings
+(say, the `consult-history` command from the excellent [Consult]
+package).
+
+Using regexp search by default is a popular option as well:
+
+```elisp
+(global-set-key (kbd "C-s") 'isearch-forward-regexp)
+(global-set-key (kbd "C-r") 'isearch-backward-regexp)
+```
+
+For a Swiper-style fuzzy search, where spaces match any sequence of
+characters in a line, use the settings below.  You can still toggle
+strict whitespace matching with <kbd>M-s SPC</kbd> during a search.
+
+``` elisp
+(setq-default
+ isearch-regexp-lax-whitespace t
+ search-whitespace-regexp ".*?")
+```
+
+Interaction with other Isearch extensions
+-----------------------------------------
+
+Some third-party Isearch extensions need to be patched to work with
+Isearch-Mb.  There are three cases to consider:
+
+- **Commands that start a search** shouldn't require extra
+  configuration.
+  
+- **Commands that operate during a search session** require the
+  `isearch-mb--with-buffer` advice.  Examples of this case are
+  [`loccur-isearch`][loccur] and [`consult-isearch`][consult]:
+  
+  ``` elisp
+  (advice-add 'loccur-isearch :around 'isearch-mb--with-buffer)
+  (define-key isearch-mb-minibuffer-map (kbd "C-o") 'loccur-isearch)
+  
+  (advice-add 'consult-isearch :around 'isearch-mb--with-buffer)
+  (define-key isearch-mb-minibuffer-map (kbd "M-r") 'consult-isearch)
+  ```
+  
+- **Commands that end the Isearch session** require the
+  `isearch-mb--after-exit` advice.  Examples of this case are
+  [`anzu-isearch-query-replace`][anzu] and
+  [`consult-line`][consult]:
+
+  ``` elisp
+  (advice-add 'anzu-isearch-query-replace :around 'isearch-mb--after-exit)
+  (define-key isearch-mb-minibuffer-map (kbd "M-%") 
'anzu-isearch-query-replace)
+
+  (advice-add 'consult-line :around 'isearch-mb--after-exit)
+  (define-key isearch-mb-minibuffer-map (kbd "M-s l") 'consult-line)
+  ```
+
+[consult]: https://github.com/minad/consult
+[loccur]: https://github.com/fourier/loccur#isearch-integration
+[anzu]: https://github.com/emacsorphanage/anzu
diff --git a/isearch-mb.el b/isearch-mb.el
index 73d74d9..4bdc905 100644
--- a/isearch-mb.el
+++ b/isearch-mb.el
@@ -1,9 +1,10 @@
-;;; isearch-mb.el --- Alternative Isearch UI based on the minibuffer -*- 
lexical-binding: t; -*-
+;;; isearch-mb.el --- Control Isearch from the minibuffer -*- lexical-binding: 
t; -*-
 
 ;; Copyright (C) 2021 Augusto Stoffel
 
 ;; Author: Augusto Stoffel <arstoffel@gmail.com>
-;; Keywords: search
+;; URL: https://github.com/astoff/isearch-mb
+;; Keywords: matching
 ;; Package-Requires: ((emacs "27.1"))
 ;; Version: 0.1
 
@@ -22,6 +23,15 @@
 
 ;;; Commentary:
 
+;; This package provides an alternative Isearch UI based on the
+;; minibuffer.  This allows editing the search string in arbitrary
+;; ways without any special maneuver; unlike standard Isearch, cursor
+;; motion commands do not end the search.  Moreover, in comparison
+;; with standard Isearch, this package provides simplified visual
+;; feedback in the echo area.
+
+;; To use the package, simply activate `isearch-mb-mode'.
+
 ;;; Code:
 
 (eval-when-compile (require 'subr-x))