[elpa] externals/el-search 2c2930b 256/332: * el-search/el-search.el: Again tweak commentary in header

[Stefan Monnier]

branch: externals/el-search
commit 2c2930b7e9b4b1b206792e624b38cb8c0932f115
Author: Michael Heerdegen <michael_heerdegen@web.de>
Commit: Michael Heerdegen <michael_heerdegen@web.de>

    * el-search/el-search.el: Again tweak commentary in header
---
 el-search.el | 148 +++++++++++++++++++++++++++++------------------------------
 1 file changed, 74 insertions(+), 74 deletions(-)

diff --git a/el-search.el b/el-search.el
index 1a47072..731b98b 100644
--- a/el-search.el
+++ b/el-search.el
@@ -7,7 +7,7 @@
 ;; Created: 29 Jul 2015
 ;; Keywords: lisp
 ;; Compatibility: GNU Emacs 25
-;; Version: 1.7.3
+;; Version: 1.7.4
 ;; Package-Requires: ((emacs "25") (stream "2.2.4") (cl-print "1.0"))
 
 
@@ -48,19 +48,19 @@
 ;; ============
 ;;
 ;; Loading this file doesn't install any key bindings - but you
-;; probably want some.  There are two predefined sets of key bindings.
-;; The first set installs bindings mostly of the form
-;; "Control-Shift-Letter", e.g. C-S, C-R, C-% etc.  These can be
+;; probably want some.  There are two predefined installable schemes
+;; of key bindings.  The first scheme defines bindings mostly of the
+;; form "Control-Shift-Letter", e.g. C-S, C-R, C-% etc.  These can be
 ;; installed by calling (el-search-install-shift-bindings) - typically
-;; in your init file.  For console users (and others), the function
+;; from your init file.  For console users (and others), the function
 ;; `el-search-install-bindings-under-prefix' installs bindings of the
-;; form PREFIX LETTER.  If you e.g. call
+;; form PREFIX LETTER.  If you call
 ;;
 ;;   (el-search-install-bindings-under-prefix [(meta ?s) ?e])
 ;;
 ;; you install bindings M-s e s, M-s e r, M-s e % etc.  When using
-;; this function to install key bindings, the bindings are
-;; "repeatable" where it makes sense, so that you can for example hit
+;; this function to install key bindings, installed bindings are
+;; "repeatable" where it makes sense so that you can for example hit
 ;; M-s e j s s s a % to reactive the last search, go to the next match
 ;; three times, then go back to the first match in the current buffer,
 ;; and finally invoke query-replace.
@@ -83,7 +83,7 @@
 ;;     Do a query-replace.
 ;;
 ;;   M-x el-search-directory
-;;     Prompt for a directory name and start a multi search for all
+;;     Prompt for a directory name and start a multi el-search for all
 ;;     Emacs-Lisp files in that directory.  With prefix arg,
 ;;     recursively search files in subdirectories.
 ;;
@@ -128,30 +128,27 @@
 ;;     the latest position.
 ;;
 ;;
-;; The setup you'll need for your init file is trivial: just define
-;; the key bindings you want to use (all important commands are
-;; autoloaded) and you are done.
+;; The setup you need for your init file is trivial: you only need to
+;; install the key bindings you want to use.  All important commands
+;; are autoloaded.
 ;;
 ;;
 ;; Usage
 ;; =====
 ;;
-;; The main user entry point `el-search-pattern' (C-S) is analogue to
-;; `isearch-forward'.  You are prompted for a `pcase'-style search
-;; pattern using an `emacs-lisp-mode' minibuffer.  After hitting RET
-;; it searches the current buffer from point for matching expressions.
-;; For any match, point is put at the beginning of the expression
-;; found (unlike isearch which puts point at the end of matches).  Hit
-;; C-S again to go to the next match etc.
+;; The main user entry point `el-search-pattern' (C-S or M-s e s) is
+;; analogue to `isearch-forward'.  You are prompted for a
+;; `pcase'-style search pattern using an `emacs-lisp-mode' minibuffer.
+;; After hitting RET it searches the current buffer from point for
+;; matching expressions.  For any match, point is put at the beginning
+;; of the expression found (unlike isearch which puts point at the end
+;; of matches).  Hit C-S or s again to go to the next match etc.
 ;;
 ;; Syntax and semantics of search patterns are identical to that of
 ;; `pcase' patterns, plus additionally defined pattern types
-;; especially useful for matching parts of programs.  The (only)
-;; difference to the `pcase' macro is that the expressions found in
-;; buffers and files are tried to be matched instead of a given
-;; expression.
+;; especially useful for matching parts of programs.
 ;;
-;; It doesn't matter how code is actually formatted.  Comments are
+;; It doesn't matter how code is formatted.  Comments are
 ;; ignored, and strings are treated as atomic objects (their contents
 ;; are not being searched).
 ;;
@@ -180,23 +177,24 @@
 ;;            s
 ;;            (guard (< 70 (length (car (split-string s "\n")))))))
 ;;
-;; Put simply, el-search is a tool to match representations of
+;; Put simply, el-search is a tool for matching representations of
 ;; symbolic expressions written in a buffer or file.  Most of the
 ;; time, but not necessarily, this is Elisp code.  El-search has no
-;; semantic understanding of the meaning of these s-exps as a program.
-;; For example, if you define a macro `my-defvar' that expands to
-;; `defvar' forms, the pattern `(defvar ,_) will not match any
-;; equivalent `my-defvar' form, it just matches any lists of two
-;; elements with the first element being the symbol `defvar'.
-;;
-;; You can define your own pattern types with `el-search-defpattern'
-;; which is analogue to `defmacro'.  See C-h f `el-search-pattern' for
-;; a list of predefined additional pattern types, and C-h f pcase for
+;; semantic understanding of the meaning of these s-exps as a program
+;; per se.  If you define a macro `my-defvar' that expands to `defvar'
+;; forms, the pattern `(defvar ,_) will not match any equivalent
+;; `my-defvar' form, it just matches any lists of two elements with
+;; the first element being the symbol `defvar'.
+;;
+;; You can define your own pattern types with macro
+;; `el-search-defpattern' which is analogue to `defmacro' (and
+;; `pcase-defmacro').  See C-h f `el-search-defined-patterns' for a
+;; list of predefined additional pattern types, and C-h f pcase for
 ;; the basic pcase patterns.
 ;;
-;; Some more pattern definitions can be found in the file
-;; "el-search-x" which is part of this package but not automatically
-;; loaded.
+;; Some additional pattern definitions can be found in the file
+;; "el-search-x.el" which is part of this package but not
+;; automatically loaded.
 ;;
 ;;
 ;; Multi Searching
@@ -205,34 +203,34 @@
 ;; "el-search" is capable of performing "multi searches" - searches
 ;; spanning multiple files or buffers.  When no more matches can be
 ;; found in the current file or buffer, the search automatically
-;; switches to the next.  Examples for search commands starting a
-;; multi search are `el-search-buffers' (search all living elisp mode
+;; switches to the next one.  Examples for search commands that start
+;; a multi search are `el-search-buffers' (search all live elisp mode
 ;; buffers), `el-search-directory' (search all elisp files in a
-;; specified directory), `el-search-emacs-elisp-sources' (search all
-;; Emacs elisp sources) and `el-search-dired-marked-files'.  Actually,
-;; every search is internally a multi search.
+;; specified directory), `el-search-emacs-elisp-sources' and
+;; `el-search-dired-marked-files'.  Actually, every search is
+;; internally a multi search.
 ;;
-;; You can pause any (multi) search by just doing something different
-;; (no quitting is needed), the state of the search is automatically
+;; You can pause any search by just doing something different (no
+;; explicit quitting needed); the state of the search is automatically
 ;; saved.  You can later continue searching by calling
-;; `el-search-jump-to-search-head' (C-J): this command jumps to the
-;; last match and re-activates the search.
-
-;; `el-search-continue-in-next-buffer' (C-N) skips all remaining
+;; `el-search-jump-to-search-head' (C-J; M-s e j): this command jumps
+;; to the last match and re-activates the search.
+;;
+;; `el-search-continue-in-next-buffer' (C-N; n) skips all remaining
 ;; matches in the current buffer and continues searching in the next
-;; buffer.  `el-search-skip-directory' even skips all subsequent files
-;; under a specified directory.
+;; buffer.  `el-search-skip-directory' (C-D; d) even skips all
+;; subsequent files under a specified directory.
 ;;
 ;;
 ;; El-Occur
 ;; ========
 ;;
-;; To get an occur-like overview buffer, you can use the usual
-;; commands to initiate a search.  You can either hit C-O from a
-;; pattern prompt instead of RET to confirm your input and start the
-;; search as noninteractive occur search.  Alternatively, you can
-;; always call `el-search-occur' (C-O) to start an occur for the
-;; latest started search.
+;; To get an occur-like overview you can use the usual commands.  You
+;; can either hit C-O or M-RET from the pattern prompt instead of RET
+;; to confirm your input and start the search as noninteractive occur
+;; search in the first place.  Alternatively, you can always call
+;; `el-search-occur' (C-O or o) to start an occur for the latest
+;; started search.
 ;;
 ;; The *El Occur* buffer uses an adjusted emacs-lisp-mode.  RET on a
 ;; match gives you a pop-up window displaying the position of the
@@ -240,7 +238,8 @@
 ;; file sections like in `org-mode' to see only file names and the
 ;; number of matches, or everything.  Tab folds and unfolds
 ;; expressions (this uses hideshow; initially, all expressions are
-;; folded to one line) and sections at the beginning of headlines.
+;; folded to one line) and also sections at the beginning of
+;; headlines.
 ;;
 ;;
 ;; Multiple multi searches
@@ -248,9 +247,11 @@
 ;;
 ;; Every search is collected in a history.  You can resume older
 ;; searches from the position of the last match by calling
-;; `el-search-jump-to-search-head' (C-J) with a prefix argument.  That
-;; let's you select an older search to resume and switches to the
-;; buffer and position where this search had been suspended.
+;; `el-search-jump-to-search-head' (C-J; M-s e j) with a prefix
+;; argument.  That let's you select an older search to resume and
+;; switches to the buffer and position where this search had been
+;; suspended.  Like any search you can restart the search driving an
+;; `el-search-query-replace' with C-u C-A or C-u M-s e a respectively.
 ;;
 ;;
 ;; Query-replace
@@ -259,8 +260,8 @@
 ;; You can replace expressions with command `el-search-query-replace'.
 ;; You are queried for a pattern and a replacement expression.  For
 ;; each match of the pattern, the replacement expression is evaluated
-;; with the bindings created by pattern matching in effect, and
-;; printed to a string to produce the replacement.
+;; with the bindings created by pattern matching in effect and printed
+;; to a string to produce the replacement.
 ;;
 ;; Example: In some buffer you want to swap the two expressions at the
 ;; places of the first two arguments in all calls of function `foo',
@@ -274,7 +275,7 @@
 ;;
 ;; This will do it:
 ;;
-;;    M-x el-search-query-replace RET
+;;    C-%  (or M-s e %)
 ;;    `(foo ,a ,b . ,rest) RET
 ;;    `(foo ,b ,a . ,rest) RET
 ;;
@@ -283,11 +284,11 @@
 ;; all remaining matches automatically.  q quits.  And ? shows a quick
 ;; help summarizing all of these keys.
 ;;
-;; It is possible to replace a match with more than one expression
-;; using "splicing mode".  When it is active, the replacement
-;; expression must evaluate to a list, and is spliced into the buffer
-;; for any match.  Use s from the prompt to toggle splicing mode in an
-;; `el-search-query-replace' session.
+;; It is possible to replace a match with an arbitrary number of
+;; expressions using "splicing mode".  When it is active, the
+;; replacement expression must evaluate to a list, and is spliced into
+;; the buffer for any match.  Hit s from the prompt to toggle splicing
+;; mode in an `el-search-query-replace' session.
 ;;
 ;;
 ;; Multi query-replace
@@ -297,17 +298,16 @@
 ;; `el-search-query-replace' directly after starting a search whose
 ;; search domain is the set of files and buffers you want to treat.
 ;; Answer "yes" to the prompt asking whether you want the started
-;; search drive the query-replace.  The user interface is
+;; search to drive the query-replace.  The user interface is
 ;; self-explanatory.
 ;;
 ;; It is always possible to resume an aborted query-replace session
 ;; even if you did other stuff in the meantime (including other
 ;; `el-search-query-replace' invocations).  Since internally every
 ;; query-replace is driven by a search, call
-;; `el-search-jump-to-search-head' (maybe with a prefix arg) to make
-;; that search current, and invoke `el-search-query-replace' (with the
-;; default bindings, this would be C-J C-% or C-x o j %).  This will
-;; continue the query-replace session from where you left.
+;; `el-search-jump-to-search-head' to make that search current, and
+;; invoke `el-search-query-replace'.  This will continue the
+;; query-replace session from where you left.
 ;;
 ;;
 ;; Advanced usage: Replacement rules for semi-automatic code rewriting
@@ -407,7 +407,7 @@
 ;;   docstrings?
 ;;
 ;; - Port this package to non Emacs Lisp modes?  How?  Would it
-;;   already work using only syntax tables, sexp scanning and
+;;   already suffice using only syntax tables, sexp scanning and
 ;;   font-lock?
 ;;
 ;; - Replace: pause and warn when replacement might be wrong