[nongnu] elpa/iedit 5e7253c36e 274/301: Update documents and comments

[ELPA Syncer]

branch: elpa/iedit
commit 5e7253c36ee4ca2cdb6dfce50a98e0aa04fb67b7
Author: Victor Ren <victorhge@gmail.com>
Commit: Victor <victorhge@gmail.com>

    Update documents and comments
---
 README.org   | 25 +++++++++++++++----------
 iedit-lib.el | 34 +++++++++++++++++++++-------------
 iedit.el     | 19 ++++++++++++-------
 3 files changed, 48 insertions(+), 30 deletions(-)

diff --git a/README.org b/README.org
index 93b824be20..5a54abca9a 100644
--- a/README.org
+++ b/README.org
@@ -4,18 +4,23 @@
 
 [[./iedit-demo.gif]]
 ** Introduction
-This package includes Emacs minor modes (iedit-mode and
-iedit-rectangle-mode) based on a API library (iedit-lib) and allows you to edit
-one occurrence of some text in a buffer (possibly narrowed) or region, and
-simultaneously have other occurrences edited in the same way, with visual
-feedback as you type.
+This package includes Emacs minor modes (iedit-mode and iedit-rectangle-mode)
+based on a API library (iedit-lib) and allows you to alter one occurrence of
+some text in a buffer (possibly narrowed) or region, and simultaneously have
+other occurrences changed in the same way, with visual feedback as you type.
+
+`iedit-mode' is a great alternative of build-in replace commands:
+
+ - A more intuitive way to alter all the occurrences at once
+ - Visual feedback
+ - Less keystrokes in most cases
 
 Normal work flow of Iedit mode is like:
 
- - Move to certain point and press C-; (The default key binding).  All
-   occurrences of a symbol, string or a region in the buffer are highlighted
-   corresponding to the thing under the point, current mark and prefix 
argument.
-   Refer to the document of `iedit-mode' for details.
+ - Move to certain point and press C-; (The default key binding) to enable
+   `iedit-mode'.  All occurrences of a symbol, string or a region in the buffer
+   are highlighted corresponding to the thing under the point, current mark and
+   prefix argument.  Refer to the document of `iedit-mode' for details.
 
  - Edit one of the occurrences
    The change is applied to other occurrences simultaneously.
@@ -30,7 +35,7 @@ buffer lines that match the current text being edited.  This 
gives you the
 effect of a temporary `keep-lines' or `occur'.  To get this effect, hit C-'
 when in Iedit mode - it toggles hiding non-matching lines.
 
-Renaming refactoring is convenient in Iedit mode
+`iedit-mode' is optimized for renaming refactoring in many ways:
 
  - The symbol under point is selected as occurrence by default and only 
complete
    symbols are matched
diff --git a/iedit-lib.el b/iedit-lib.el
index 1186e30958..77846b02df 100755
--- a/iedit-lib.el
+++ b/iedit-lib.el
@@ -3,7 +3,7 @@
 
 ;; Copyright (C) 2010 - 2019, 2020 Victor Ren
 
-;; Time-stamp: <2020-11-21 21:16:05 Victor Ren>
+;; Time-stamp: <2020-11-23 15:50:37 Victor Ren>
 ;; Author: Victor Ren <victorhge@gmail.com>
 ;; Keywords: occurrence region simultaneous rectangle refactoring
 ;; Version: 0.9.9.9
@@ -124,7 +124,9 @@ configurable via `iedit-ready-only-occurrence'.")
 
 (defvar iedit-case-sensitive iedit-case-sensitive-default
   "This is buffer local variable.
-If no-nil, matching is case sensitive.")
+If no-nil, matching is case sensitive.  If nil and `case-replace'
+is no-nil, iedit try to preserve the case pattern of each
+occurrence.")
 
 (defvar iedit-hiding nil
   "This is buffer local variable which indicates whether buffer lines are 
hided. ")
@@ -431,8 +433,9 @@ occurrences if the user starts typing."
     (overlay-put occurrence 'insert-behind-hooks '(iedit-update-occurrences))
     (overlay-put occurrence 'modification-hooks '(iedit-update-occurrences))
     (overlay-put occurrence 'priority iedit-overlay-priority)
+       ;; Identify case pattern of the occurrence.
     (overlay-put occurrence 'category (if (and (not iedit-case-sensitive) 
case-replace)
-                                                                               
  (iedit-case-action begin end)
+                                                                               
  (iedit-case-pattern begin end)
                                                                                
'no-change))
     occurrence))
 
@@ -561,10 +564,11 @@ Apply the change to all the other occurrences. "
     (save-excursion
          (iedit-move-conjoined-overlays occurrence)
          (when (/= beg end)
+               ;; apply the case pattern on the current occurrence
                (case (overlay-get occurrence 'category)
                  ('all-caps
                   (upcase-region beg end))
-                 ('cap-initial 
+                 ('cap-initial
                   (when (= 0 offset) (capitalize-region beg end )))))
       (dolist (another-occurrence iedit-occurrences-overlays)
         (when (not (eq another-occurrence occurrence))
@@ -574,6 +578,7 @@ Apply the change to all the other occurrences. "
                        (when (/= beg end) ;; insert
                          (goto-char beginning)
                          (insert-and-inherit
+                          ;; preserve the case pattern of each occurrence
                           (case (overlay-get another-occurrence 'category)
                                 ('no-change value)
                                 ('all-caps
@@ -907,23 +912,26 @@ be applied to other occurrences when buffering is off."
   (buffer-disable-undo)
   (message "Start buffering editing..."))
 
-(defun iedit-case-action (beg end)
-  "Decide how to casify by examining the text between `beg' and `end'.
+(defun iedit-case-pattern (beg end)
+  "Distinguish the case pattern of the text between `beg' and `end'.
+
+These case ptterns are the same as the ones Emacs replace
+commands can recognized - three alternatives - all caps,
+captilized, the others.
 
-Maybe capitalize the whole text, or maybe just word initials,
-based on the text between `beg' and `end'.  If the text has only
-capital letters and has at least one multiletter word, convert
-`new-text' to all caps.  Otherwise if all words are capitalized
-in the replaced text, capitalize each word in `new-text'"
+If the text has only capital letters and has at least one
+multiletter word, it is 'all caps'. If all words are capitalized,
+it is captilized.'"
   (let ((some-word nil)
                (some-lowercase nil)
                (some-uppercase nil)
                (some-non-uppercase-init nil)
                (previous-char ?\n)
                (char nil)
-               (index 0))
+               (index 0)
+               (text (buffer-substring beg end)))
        (while (< index (- end beg))
-         (setq char (elt (buffer-substring beg end) index))
+         (setq char (elt text index))
          (if (and (= char (downcase char))
                           (/= char (upcase char)))
                  (progn
diff --git a/iedit.el b/iedit.el
index 80625d267f..e5efccc2d7 100644
--- a/iedit.el
+++ b/iedit.el
@@ -2,7 +2,7 @@
 
 ;; Copyright (C) 2010 - 2019, 2020 Victor Ren
 
-;; Time-stamp: <2020-11-21 21:08:37 Victor Ren>
+;; Time-stamp: <2020-11-23 15:18:05 Victor Ren>
 ;; Author: Victor Ren <victorhge@gmail.com>
 ;; Keywords: occurrence region simultaneous refactoring
 ;; Version: 0.9.9.9
@@ -28,11 +28,16 @@
 
 ;;; Commentary:
 
-;; This package includes Emacs minor modes (iedit-mode and
-;; iedit-rectangle-mode) based on a API library (iedit-lib) and allows you to 
edit
-;; one occurrence of some text in a buffer (possibly narrowed) or region, and
-;; simultaneously have other occurrences edited in the same way, with visual
-;; feedback as you type.
+;; This package includes Emacs minor modes (iedit-mode and 
iedit-rectangle-mode)
+;; based on a API library (iedit-lib) and allows you to alter one occurrence of
+;; some text in a buffer (possibly narrowed) or region, and simultaneously have
+;; other occurrences changed in the same way, with visual feedback as you type.
+
+;; `iedit-mode' is a great alternative of build-in replace commands:
+
+;;  - A more intuitive way to alter all the occurrences at once
+;;  - Visual feedback
+;;  - Less keystrokes in most cases
 
 ;; Normal work flow of Iedit mode is like:
 
@@ -54,7 +59,7 @@
 ;; effect of a temporary `keep-lines' or `occur'.  To get this effect, hit C-'
 ;; when in Iedit mode - it toggles hiding non-matching lines.
 
-;; Renaming refactoring is convenient in Iedit mode
+;; `iedit-mode' is optimized for renaming refactoring in many ways:
 
 ;;  - The symbol under point is selected as occurrence by default and only 
complete
 ;;    symbols are matched